diff --git a/README.md b/README.md
index 83fb48e..b4a5821 100644
--- a/README.md
+++ b/README.md
@@ -53,6 +53,18 @@ result, err := matcher.Find(ctx, "log in button", elements, semantic.FindOptions
 // result.BestScore = 0.82
 ```
 
+Structured locators are also supported when descriptors include the corresponding fields:
+
+```go
+result, err := matcher.Find(ctx, "role:button Sign In", elements, semantic.FindOptions{})
+result, err = matcher.Find(ctx, "placeholder:Search", elements, semantic.FindOptions{})
+result, err = matcher.Find(ctx, "nth:1:role:button", elements, semantic.FindOptions{})
+```
+
+`nth:<n>` is 1-based: `nth:1` selects the first ordered candidate, `nth:2` selects the second, and `nth:0` is not the first match.
+
+Use `find:<query>` or `semantic:<query>` to force natural-language matching for locator-like text.
+
 ## Package Layout
 
 ```
diff --git a/cmd/semantic/main.go b/cmd/semantic/main.go
index b99815c..d7ac931 100644
--- a/cmd/semantic/main.go
+++ b/cmd/semantic/main.go
@@ -81,9 +81,18 @@ type snapshotElement struct {
 	Role        string              `json:"role"`
 	Name        string              `json:"name"`
 	Value       string              `json:"value"`
+	Label       string              `json:"label"`
+	Placeholder string              `json:"placeholder"`
+	Alt         string              `json:"alt"`
+	Title       string              `json:"title"`
+	TestID      string              `json:"testid"`
+	TestIDAlt   string              `json:"test_id"`
+	Text        string              `json:"text"`
+	Tag         string              `json:"tag"`
 	Interactive bool                `json:"interactive"`
 	Parent      string              `json:"parent"`
 	Section     string              `json:"section"`
+	DocumentIdx int                 `json:"document_idx"`
 	Depth       int                 `json:"depth"`
 	SiblingIdx  int                 `json:"sibling_index"`
 	SiblingCnt  int                 `json:"sibling_count"`
@@ -122,6 +131,11 @@ func loadSnapshot(path string) ([]semantic.ElementDescriptor, error) {
 
 	descs := make([]semantic.ElementDescriptor, len(elements))
 	for i, e := range elements {
+		testID := e.TestID
+		if testID == "" {
+			testID = e.TestIDAlt
+		}
+
 		labelledBy := e.LabelledBy
 		depth := e.Depth
 		siblingIdx := e.SiblingIdx
@@ -173,9 +187,17 @@ func loadSnapshot(path string) ([]semantic.ElementDescriptor, error) {
 			Role:        e.Role,
 			Name:        e.Name,
 			Value:       e.Value,
+			Label:       e.Label,
+			Placeholder: e.Placeholder,
+			Alt:         e.Alt,
+			Title:       e.Title,
+			TestID:      testID,
+			Text:        e.Text,
+			Tag:         e.Tag,
 			Interactive: e.Interactive,
 			Parent:      e.Parent,
 			Section:     e.Section,
+			DocumentIdx: e.DocumentIdx,
 			Positional: semantic.PositionalHints{
 				Depth:        depth,
 				SiblingIndex: siblingIdx,
diff --git a/cmd/semantic/main_test.go b/cmd/semantic/main_test.go
index 0a7d117..4e52474 100644
--- a/cmd/semantic/main_test.go
+++ b/cmd/semantic/main_test.go
@@ -12,8 +12,8 @@ func TestLoadSnapshot_PropagatesInteractiveFlag(t *testing.T) {
 	}
 
 	json := `[
-		{"ref":"e1","role":"button","name":"Submit","interactive":true,"parent":"Login form","section":"Authentication","depth":3,"sibling_index":1,"sibling_count":2,"labelled_by":"Primary Action","x":20,"y":40,"width":120,"height":30},
-		{"ref":"e2","role":"text","name":"Submit","interactive":false,"parent":"Payment form","section":"Checkout","positional":{"depth":2,"sibling_index":0,"sibling_count":1,"labelled_by":"Secondary Action","left":300,"top":640,"width":200,"height":44}}
+		{"ref":"e1","role":"button","name":"Submit","label":"Primary Action","placeholder":"Search","alt":"Submit icon","title":"Submit form","testid":"submit-button","text":"Submit","tag":"button","document_idx":7,"interactive":true,"parent":"Login form","section":"Authentication","depth":3,"sibling_index":1,"sibling_count":2,"labelled_by":"Primary Action","x":20,"y":40,"width":120,"height":30},
+		{"ref":"e2","role":"text","name":"Submit","test_id":"legacy-submit","interactive":false,"parent":"Payment form","section":"Checkout","positional":{"depth":2,"sibling_index":0,"sibling_count":1,"labelled_by":"Secondary Action","left":300,"top":640,"width":200,"height":44}}
 	]`
 	if _, err := f.WriteString(json); err != nil {
 		t.Fatalf("WriteString failed: %v", err)
@@ -38,6 +38,30 @@ func TestLoadSnapshot_PropagatesInteractiveFlag(t *testing.T) {
 	if descs[0].Section != "Authentication" {
 		t.Fatalf("expected first descriptor section=Authentication, got %q", descs[0].Section)
 	}
+	if descs[0].Label != "Primary Action" {
+		t.Fatalf("expected first descriptor label=Primary Action, got %q", descs[0].Label)
+	}
+	if descs[0].Placeholder != "Search" {
+		t.Fatalf("expected first descriptor placeholder=Search, got %q", descs[0].Placeholder)
+	}
+	if descs[0].Alt != "Submit icon" {
+		t.Fatalf("expected first descriptor alt=Submit icon, got %q", descs[0].Alt)
+	}
+	if descs[0].Title != "Submit form" {
+		t.Fatalf("expected first descriptor title=Submit form, got %q", descs[0].Title)
+	}
+	if descs[0].TestID != "submit-button" {
+		t.Fatalf("expected first descriptor testid=submit-button, got %q", descs[0].TestID)
+	}
+	if descs[0].Text != "Submit" {
+		t.Fatalf("expected first descriptor text=Submit, got %q", descs[0].Text)
+	}
+	if descs[0].Tag != "button" {
+		t.Fatalf("expected first descriptor tag=button, got %q", descs[0].Tag)
+	}
+	if descs[0].DocumentIdx != 7 {
+		t.Fatalf("expected first descriptor document_idx=7, got %d", descs[0].DocumentIdx)
+	}
 	if descs[0].Positional.Depth != 3 {
 		t.Fatalf("expected first descriptor depth=3, got %d", descs[0].Positional.Depth)
 	}
@@ -65,6 +89,9 @@ func TestLoadSnapshot_PropagatesInteractiveFlag(t *testing.T) {
 	if descs[1].Section != "Checkout" {
 		t.Fatalf("expected second descriptor section=Checkout, got %q", descs[1].Section)
 	}
+	if descs[1].TestID != "legacy-submit" {
+		t.Fatalf("expected second descriptor test_id fallback=legacy-submit, got %q", descs[1].TestID)
+	}
 	if descs[1].Positional.Depth != 2 {
 		t.Fatalf("expected second descriptor depth=2, got %d", descs[1].Positional.Depth)
 	}
diff --git a/docs/architecture/implementation.md b/docs/architecture/implementation.md
index 9eb0518..6dbdb1e 100644
--- a/docs/architecture/implementation.md
+++ b/docs/architecture/implementation.md
@@ -8,14 +8,36 @@ The input unit. Each element from the accessibility tree becomes a descriptor:
 
 ```go
 type ElementDescriptor struct {
-    Ref   string  // "e4" — the element reference
-    Role  string  // "button" — ARIA role
-    Name  string  // "Sign In" — accessible name
-    Value string  // "" — current value (for inputs)
+    Ref         string
+    Role        string
+    Name        string
+    Value       string
+    Label       string
+    Placeholder string
+    Alt         string
+    Title       string
+    TestID      string
+    Text        string
+    Tag         string
 }
 ```
 
-The `Composite()` method produces a single searchable string: `"button: Sign In"`. This is what matchers score against.
+The `Composite()` method produces a single searchable string such as `"button: Sign In"`. Natural-language matchers score against this composite; structured locators score explicit fields directly.
+
+Structured locator queries are parsed before generic semantic matching:
+
+- `role:<role> [name]`
+- `text:<text>`
+- `label:<label>`
+- `placeholder:<text>`
+- `alt:<text>`
+- `title:<text>`
+- `testid:<id>`
+- `first:<selector>`, `last:<selector>`, `nth:<n>:<selector>`
+
+`nth:<n>` is 1-based: `nth:1` selects the first ordered candidate, `nth:2` selects the second, and `nth:0` is not the first match.
+
+Exact normalized field matches outrank substring matches. Role locators prefer `Role` and fall back to the implicit role inferred from `Tag` when the explicit role is empty or generic. `find:<query>` and `semantic:<query>` force natural-language matching.
 
 ## Lexical Matcher
 
diff --git a/docs/core-concepts.md b/docs/core-concepts.md
index d74ff43..df18a59 100644
--- a/docs/core-concepts.md
+++ b/docs/core-concepts.md
@@ -6,15 +6,37 @@ The input unit. Each element from the accessibility tree becomes a descriptor:
 
 ```go
 semantic.ElementDescriptor{
-    Ref:   "e4",      // element reference
-    Role:  "button",  // ARIA role
-    Name:  "Sign In", // accessible name
-    Value: "",        // current value (for inputs)
+    Ref:         "e4",      // element reference
+    Role:        "button",  // explicit/accessibility role
+    Name:        "Sign In", // accessible name
+    Value:       "",        // current value (for inputs)
+    Label:       "Email",   // associated label text
+    Placeholder: "Search",  // placeholder text
+    Alt:         "Logo",    // image alt text
+    Title:       "Help",    // title attribute text
+    TestID:      "submit",  // test id attribute
+    Text:        "Sign In", // visible text
+    Tag:         "button",  // HTML tag for implicit role fallback
 }
 ```
 
 `Composite()` produces a single searchable string: `"button: Sign In"`.
 
+Structured locators are parsed before natural-language matching:
+
+| Query | Meaning |
+|-------|---------|
+| `role:button Sign In` | Role plus optional accessible name |
+| `text:Sign In` | Visible text |
+| `label:Email` | Associated label text |
+| `placeholder:Search` | Placeholder text |
+| `alt:Logo` | Image alt text |
+| `title:Help` | Title text |
+| `testid:submit` | Test id |
+| `first:role:button`, `last:role:button`, `nth:1:role:button` | Ordered candidate selection; `nth` is 1-based |
+
+`nth:<n>` is 1-based: `nth:1` selects the first ordered candidate, `nth:2` selects the second, and `nth:0` is not the first match. Use `find:<query>` or `semantic:<query>` to force natural-language matching when a query starts with a locator-like prefix.
+
 ## Matchers
 
 All matchers implement the `ElementMatcher` interface:
diff --git a/docs/reference/api.md b/docs/reference/api.md
index c605e28..ffd91d6 100644
--- a/docs/reference/api.md
+++ b/docs/reference/api.md
@@ -50,6 +50,31 @@ func CosineSimilarity(a, b []float32) float64
 | `EmbeddingWeight` | `float64` | 0 | Per-request weight override |
 | `Explain` | `bool` | false | Include per-strategy breakdown |
 
+### ElementDescriptor Fields
+
+| Field | Description |
+|-------|-------------|
+| `Ref` | Snapshot element reference |
+| `Role` | Explicit/accessibility role |
+| `Name` | Accessible name |
+| `Value` | Current value |
+| `Label` | Associated label text |
+| `Placeholder` | Placeholder text |
+| `Alt` | Image alt text |
+| `Title` | Title text |
+| `TestID` | Test id attribute |
+| `Text` | Visible text |
+| `Tag` | HTML tag used for implicit role fallback |
+| `Interactive` | Whether the element is interactive |
+| `Parent` | Parent context |
+| `Section` | Section context |
+| `DocumentIdx` | Document order hint |
+| `Positional` | AX-tree and visual position hints |
+
+### Structured Locator Queries
+
+`Find` parses these locator forms before natural-language scoring: `role:<role> [name]`, `text:<text>`, `label:<label>`, `placeholder:<text>`, `alt:<text>`, `title:<text>`, `testid:<id>`, `first:<selector>`, `last:<selector>`, and `nth:<n>:<selector>`. `nth:<n>` is 1-based: `nth:1` selects the first ordered candidate, `nth:2` selects the second, and `nth:0` is not the first match. `find:<query>` and `semantic:<query>` force natural-language matching.
+
 ---
 
 ## Recovery Package (`github.com/pinchtab/semantic/recovery`)
diff --git a/docs/semantic.md b/docs/semantic.md
index 731a0ea..484591a 100644
--- a/docs/semantic.md
+++ b/docs/semantic.md
@@ -5,6 +5,7 @@ Zero-dependency Go library for semantic matching of accessibility tree elements.
 ## What Semantic Does
 
 Matches natural language queries like "sign in button" against structured UI element descriptors using lexical similarity, synonym expansion, and embedding-based fuzzy matching.
+It also supports structured locator queries such as `role:button Sign In`, `text:Submit`, `label:Email`, and `testid:checkout-submit` when descriptors include those fields.
 
 Browser automation tools find UI elements via CSS selectors, XPath, or IDs — all brittle. When the DOM changes (SPA re-renders, layout shifts, framework updates), selectors break. AI agents make it worse: they describe elements in natural language but the accessibility tree has structured labels.
 
@@ -14,5 +15,6 @@ Semantic bridges that gap.
 
 - **Zero dependencies** — only Go standard library
 - **Stateless** — every `Find()` call is independent, thread-safe by default
+- **Structured locators** — exact field matching for role, text, label, placeholder, alt, title, and test id
 - **Sub-millisecond** — < 1ms for 100 elements with combined matcher
 - **Self-healing** — recovery engine re-locates stale elements after DOM changes
diff --git a/internal/engine/benchmark_test.go b/internal/engine/benchmark_test.go
index 0ebc2c6..cca9b24 100644
--- a/internal/engine/benchmark_test.go
+++ b/internal/engine/benchmark_test.go
@@ -361,3 +361,56 @@ func BenchmarkCombinedFind_WeightVariants(b *testing.B) {
 		})
 	}
 }
+
+func BenchmarkStructuredLocatorFind(b *testing.B) {
+	m := NewCombinedMatcher(NewHashingEmbedder(128))
+	elements := []types.ElementDescriptor{
+		{Ref: "e0", Role: "heading", Name: "Welcome Back", Text: "Welcome Back", DocumentIdx: 0},
+		{Ref: "e1", Role: "textbox", Name: "Email address", Label: "Email address", Placeholder: "name@example.com", Tag: "input", Interactive: true, DocumentIdx: 1},
+		{Ref: "e2", Role: "textbox", Name: "Password", Label: "Password", Placeholder: "Password", Tag: "input", Interactive: true, DocumentIdx: 2},
+		{Ref: "e3", Role: "checkbox", Name: "Remember me", Label: "Remember me", Tag: "input", Interactive: true, DocumentIdx: 3},
+		{Ref: "e4", Role: "button", Name: "Sign In", Text: "Sign In", TestID: "submit-login", Tag: "button", Interactive: true, DocumentIdx: 4},
+		{Ref: "e5", Role: "link", Name: "Forgot password?", Text: "Forgot password?", Tag: "a", Interactive: true, DocumentIdx: 5},
+		{Ref: "e6", Role: "img", Name: "Company Logo", Alt: "Company Logo", Tag: "img", DocumentIdx: 6},
+	}
+	ctx := context.Background()
+	opts := types.FindOptions{Threshold: 0, TopK: 3}
+	queries := []string{
+		"role:button Sign In",
+		"text:Forgot password?",
+		"label:Email address",
+		"placeholder:Password",
+		"alt:Company Logo",
+		"testid:submit-login",
+		"nth:1:role:textbox",
+	}
+
+	for _, query := range queries {
+		b.Run(query, func(b *testing.B) {
+			b.ReportAllocs()
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				_, _ = m.Find(ctx, query, elements, opts)
+			}
+		})
+	}
+}
+
+func BenchmarkParseStructuredLocator(b *testing.B) {
+	queries := []string{
+		"role:button Sign In",
+		"text:Forgot password?",
+		"label:Email address",
+		"placeholder:Password",
+		"alt:Company Logo",
+		"testid:submit-login",
+		"nth:2:role:button Save",
+	}
+	b.ReportAllocs()
+
+	for b.Loop() {
+		for _, query := range queries {
+			parseStructuredLocator(query)
+		}
+	}
+}
diff --git a/internal/engine/combined.go b/internal/engine/combined.go
index c42597f..2757e4f 100644
--- a/internal/engine/combined.go
+++ b/internal/engine/combined.go
@@ -46,6 +46,13 @@ func (c *CombinedMatcher) Find(ctx context.Context, query string, elements []typ
 		ctx = context.Background()
 	}
 
+	query, forceNatural := normalizeSemanticQuery(query)
+	if !forceNatural {
+		if result, ok := findStructuredLocator(query, elements, opts, c.Strategy()); ok {
+			return result, nil
+		}
+	}
+
 	opts = sanitizeFindOptions(opts, len(elements), 3)
 
 	parsed := ParseQueryContext(query)
diff --git a/internal/engine/descriptor_test.go b/internal/engine/descriptor_test.go
index bf66942..e37eb70 100644
--- a/internal/engine/descriptor_test.go
+++ b/internal/engine/descriptor_test.go
@@ -23,6 +23,25 @@ func TestComposite(t *testing.T) {
 			desc: types.ElementDescriptor{Ref: "e1", Role: "textbox", Name: "Email", Value: "user@pinchtab.com"},
 			want: "textbox: Email [user@pinchtab.com]",
 		},
+		{
+			name: "locator identity fields",
+			desc: types.ElementDescriptor{
+				Ref:         "e4",
+				Role:        "textbox",
+				Name:        "Email",
+				Label:       "Work Email",
+				Placeholder: "name@example.com",
+				Title:       "Primary email address",
+				Text:        "Email",
+				TestID:      "email-input",
+			},
+			want: "textbox: Email label:Work Email placeholder:name@example.com title:Primary email address",
+		},
+		{
+			name: "tag when role missing",
+			desc: types.ElementDescriptor{Ref: "e5", Tag: "button", Text: "Save"},
+			want: "button: Save",
+		},
 		{
 			name: "name only",
 			desc: types.ElementDescriptor{Ref: "e2", Name: "Heading"},
diff --git a/internal/engine/embedding.go b/internal/engine/embedding.go
index 48922dc..b21617a 100644
--- a/internal/engine/embedding.go
+++ b/internal/engine/embedding.go
@@ -64,6 +64,13 @@ func (m *EmbeddingMatcher) Find(ctx context.Context, query string, elements []ty
 		return types.FindResult{}, err
 	}
 
+	query, forceNatural := normalizeSemanticQuery(query)
+	if !forceNatural {
+		if result, ok := findStructuredLocator(query, elements, opts, m.Strategy()); ok {
+			return result, nil
+		}
+	}
+
 	queryCtx := ParseQueryContext(query)
 	return m.findWithParsedContext(ctx, queryCtx, elements, opts)
 }
diff --git a/internal/engine/lexical.go b/internal/engine/lexical.go
index ffde616..57d7f63 100644
--- a/internal/engine/lexical.go
+++ b/internal/engine/lexical.go
@@ -55,6 +55,13 @@ func (m *LexicalMatcher) Find(ctx context.Context, query string, elements []type
 		return types.FindResult{}, err
 	}
 
+	query, forceNatural := normalizeSemanticQuery(query)
+	if !forceNatural {
+		if result, ok := findStructuredLocator(query, elements, opts, m.Strategy()); ok {
+			return result, nil
+		}
+	}
+
 	queryCtx := ParseQueryContext(query)
 	return m.findWithParsedContext(ctx, queryCtx, elements, opts), nil
 }
diff --git a/internal/engine/query_context.go b/internal/engine/query_context.go
index 6d0fc24..93e35dd 100644
--- a/internal/engine/query_context.go
+++ b/internal/engine/query_context.go
@@ -90,6 +90,12 @@ func matchesExcludedContext(el types.ElementDescriptor, excludeTokens []string)
 		el.Role,
 		el.Name,
 		el.Value,
+		el.Label,
+		el.Placeholder,
+		el.Alt,
+		el.Title,
+		el.Text,
+		el.Tag,
 	}, " "))
 	if len(ctxTokens) == 0 {
 		return false
diff --git a/internal/engine/structured_locator.go b/internal/engine/structured_locator.go
new file mode 100644
index 0000000..9d8b4f8
--- /dev/null
+++ b/internal/engine/structured_locator.go
@@ -0,0 +1,495 @@
+package engine
+
+import (
+	"sort"
+	"strconv"
+	"strings"
+	"unicode"
+
+	"github.com/pinchtab/semantic/internal/types"
+)
+
+type structuredLocatorKind int
+
+const (
+	locatorRole structuredLocatorKind = iota + 1
+	locatorText
+	locatorLabel
+	locatorPlaceholder
+	locatorAlt
+	locatorTitle
+	locatorTestID
+)
+
+type structuredLocatorWrapper int
+
+const (
+	locatorNoWrapper structuredLocatorWrapper = iota
+	locatorFirst
+	locatorLast
+	locatorNth
+)
+
+type structuredLocator struct {
+	kind    structuredLocatorKind
+	role    string
+	value   string
+	wrapper structuredLocatorWrapper
+	nth     int
+}
+
+type structuredLocatorCandidate struct {
+	desc  types.ElementDescriptor
+	score float64
+	order int
+}
+
+func normalizeSemanticQuery(raw string) (query string, forceNatural bool) {
+	query = strings.TrimSpace(raw)
+	if rest, ok := cutFoldedPrefix(query, "find:"); ok {
+		return strings.TrimSpace(rest), true
+	}
+	if rest, ok := cutFoldedPrefix(query, "semantic:"); ok {
+		return strings.TrimSpace(rest), true
+	}
+	return query, false
+}
+
+func findStructuredLocator(raw string, elements []types.ElementDescriptor, opts types.FindOptions, strategy string) (types.FindResult, bool) {
+	locator, ok := parseStructuredLocator(raw)
+	if !ok {
+		return types.FindResult{}, false
+	}
+	return matchStructuredLocator(locator, elements, opts, strategy), true
+}
+
+func parseStructuredLocator(raw string) (structuredLocator, bool) {
+	query := strings.TrimSpace(raw)
+	if query == "" {
+		return structuredLocator{}, false
+	}
+
+	if rest, ok := cutFoldedPrefix(query, "first:"); ok {
+		locator, ok := parseStructuredLocatorBase(rest)
+		if !ok {
+			return structuredLocator{}, false
+		}
+		locator.wrapper = locatorFirst
+		return locator, true
+	}
+
+	if rest, ok := cutFoldedPrefix(query, "last:"); ok {
+		locator, ok := parseStructuredLocatorBase(rest)
+		if !ok {
+			return structuredLocator{}, false
+		}
+		locator.wrapper = locatorLast
+		return locator, true
+	}
+
+	if rest, ok := cutFoldedPrefix(query, "nth:"); ok {
+		ordinal, baseRaw, ok := splitNthLocator(rest)
+		if !ok {
+			return structuredLocator{}, false
+		}
+		locator, ok := parseStructuredLocatorBase(baseRaw)
+		if !ok {
+			return structuredLocator{}, false
+		}
+		locator.wrapper = locatorNth
+		locator.nth = ordinal
+		return locator, true
+	}
+
+	return parseStructuredLocatorBase(query)
+}
+
+func parseStructuredLocatorBase(raw string) (structuredLocator, bool) {
+	query := strings.TrimSpace(raw)
+	if query == "" {
+		return structuredLocator{}, false
+	}
+
+	if rest, ok := cutFoldedPrefix(query, "role:"); ok {
+		role, name, ok := splitRoleLocator(rest)
+		if !ok {
+			return structuredLocator{}, false
+		}
+		return structuredLocator{kind: locatorRole, role: role, value: name}, true
+	}
+
+	fieldPrefixes := []struct {
+		prefix string
+		kind   structuredLocatorKind
+	}{
+		{"text:", locatorText},
+		{"label:", locatorLabel},
+		{"placeholder:", locatorPlaceholder},
+		{"alt:", locatorAlt},
+		{"title:", locatorTitle},
+		{"testid:", locatorTestID},
+	}
+
+	for _, prefix := range fieldPrefixes {
+		if rest, ok := cutFoldedPrefix(query, prefix.prefix); ok {
+			value := cleanLocatorValue(rest)
+			if value == "" {
+				return structuredLocator{}, false
+			}
+			return structuredLocator{kind: prefix.kind, value: value}, true
+		}
+	}
+
+	return structuredLocator{}, false
+}
+
+func splitNthLocator(raw string) (int, string, bool) {
+	rest := strings.TrimSpace(raw)
+	sep := strings.Index(rest, ":")
+	if sep <= 0 {
+		return 0, "", false
+	}
+	n, err := strconv.Atoi(strings.TrimSpace(rest[:sep]))
+	if err != nil || n < 0 {
+		return 0, "", false
+	}
+	base := strings.TrimSpace(rest[sep+1:])
+	if base == "" {
+		return 0, "", false
+	}
+	return n, base, true
+}
+
+func splitRoleLocator(raw string) (role string, name string, ok bool) {
+	rest := strings.TrimSpace(raw)
+	if rest == "" {
+		return "", "", false
+	}
+
+	fields := strings.Fields(rest)
+	if len(fields) == 0 {
+		return "", "", false
+	}
+
+	role = cleanRoleValue(fields[0])
+	if role == "" {
+		return "", "", false
+	}
+
+	nameStart := strings.Index(rest, fields[0]) + len(fields[0])
+	if nameStart < len(rest) {
+		name = cleanLocatorValue(rest[nameStart:])
+	}
+	return role, name, true
+}
+
+func cutFoldedPrefix(s, prefix string) (string, bool) {
+	if len(s) < len(prefix) {
+		return "", false
+	}
+	if !strings.EqualFold(s[:len(prefix)], prefix) {
+		return "", false
+	}
+	return s[len(prefix):], true
+}
+
+func cleanRoleValue(value string) string {
+	value = strings.TrimSpace(value)
+	value = strings.Trim(value, ",.;")
+	return strings.ToLower(value)
+}
+
+func cleanLocatorValue(value string) string {
+	value = strings.TrimSpace(value)
+	value = strings.Trim(value, ",.;")
+	value = strings.TrimSpace(value)
+	if len(value) >= 2 {
+		first := value[0]
+		last := value[len(value)-1]
+		if (first == '"' && last == '"') || (first == '\'' && last == '\'') || (first == '`' && last == '`') || (first == '[' && last == ']') {
+			value = strings.TrimSpace(value[1 : len(value)-1])
+		}
+	}
+	return value
+}
+
+func matchStructuredLocator(locator structuredLocator, elements []types.ElementDescriptor, opts types.FindOptions, strategy string) types.FindResult {
+	opts = sanitizeFindOptions(opts, len(elements), 3)
+
+	result := types.FindResult{
+		Strategy:     strategy + ":structured",
+		ElementCount: len(elements),
+	}
+
+	candidates := make([]structuredLocatorCandidate, 0, len(elements))
+	for i, el := range elements {
+		score, ok := scoreStructuredLocatorCandidate(locator, el)
+		if !ok || score < opts.Threshold {
+			continue
+		}
+		candidates = append(candidates, structuredLocatorCandidate{
+			desc:  el,
+			score: score,
+			order: structuredElementOrder(i, el),
+		})
+	}
+
+	if locator.wrapper != locatorNoWrapper {
+		sortStructuredLocatorCandidatesByDocumentOrder(candidates)
+		candidates = selectStructuredLocatorWrapper(candidates, locator)
+	} else {
+		sortStructuredLocatorCandidatesByRank(candidates)
+		if len(candidates) > opts.TopK {
+			candidates = candidates[:opts.TopK]
+		}
+	}
+
+	for _, candidate := range candidates {
+		result.Matches = append(result.Matches, types.ElementMatch{
+			Ref:   candidate.desc.Ref,
+			Score: candidate.score,
+			Role:  candidate.desc.Role,
+			Name:  candidate.desc.Name,
+		})
+	}
+	if len(result.Matches) > 0 {
+		result.BestRef = result.Matches[0].Ref
+		result.BestScore = result.Matches[0].Score
+	}
+	return result
+}
+
+func sortStructuredLocatorCandidatesByRank(candidates []structuredLocatorCandidate) {
+	sort.SliceStable(candidates, func(i, j int) bool {
+		return rankedMatchLess(
+			candidates[i].score, candidates[i].desc, candidates[i].order,
+			candidates[j].score, candidates[j].desc, candidates[j].order,
+		)
+	})
+}
+
+func sortStructuredLocatorCandidatesByDocumentOrder(candidates []structuredLocatorCandidate) {
+	sort.SliceStable(candidates, func(i, j int) bool {
+		if candidates[i].order != candidates[j].order {
+			return candidates[i].order < candidates[j].order
+		}
+		return candidates[i].desc.Ref < candidates[j].desc.Ref
+	})
+}
+
+func selectStructuredLocatorWrapper(candidates []structuredLocatorCandidate, locator structuredLocator) []structuredLocatorCandidate {
+	if len(candidates) == 0 {
+		return nil
+	}
+
+	idx := 0
+	switch locator.wrapper {
+	case locatorFirst:
+		idx = 0
+	case locatorLast:
+		idx = len(candidates) - 1
+	case locatorNth:
+		idx = locator.nth - 1
+	default:
+		return candidates
+	}
+
+	if idx < 0 || idx >= len(candidates) {
+		return nil
+	}
+	return []structuredLocatorCandidate{candidates[idx]}
+}
+
+func scoreStructuredLocatorCandidate(locator structuredLocator, el types.ElementDescriptor) (float64, bool) {
+	switch locator.kind {
+	case locatorRole:
+		roleScore, ok := scoreLocatorRole(locator.role, el)
+		if !ok {
+			return 0, false
+		}
+		if strings.TrimSpace(locator.value) == "" {
+			return roleScore, true
+		}
+		nameScore, ok := scoreLocatorValues(locator.value, roleNameLocatorValues(el))
+		if !ok {
+			return 0, false
+		}
+		return roleScore * nameScore, true
+	case locatorText, locatorLabel, locatorPlaceholder, locatorAlt, locatorTitle, locatorTestID:
+		return scoreLocatorValues(locator.value, locatorFieldValues(locator.kind, el))
+	default:
+		return 0, false
+	}
+}
+
+func roleNameLocatorValues(el types.ElementDescriptor) []string {
+	return []string{
+		el.Name,
+		el.Label,
+		el.Positional.LabelledBy,
+		el.Text,
+		el.Alt,
+		el.Title,
+		el.Placeholder,
+		el.Value,
+	}
+}
+
+func scoreLocatorRole(role string, el types.ElementDescriptor) (float64, bool) {
+	want := normalizeLocatorText(role)
+	if want == "" {
+		return 0, false
+	}
+
+	explicit := normalizeLocatorText(el.Role)
+	if explicit != "" && explicit == want {
+		return 1.0, true
+	}
+	if explicit != "" && !allowsImplicitRoleFallback(explicit) {
+		return 0, false
+	}
+
+	if implicitRoleForTag(el.Tag) == want {
+		return 0.92, true
+	}
+	return 0, false
+}
+
+func allowsImplicitRoleFallback(role string) bool {
+	switch role {
+	case "", "generic", "none", "presentation", "unknown":
+		return true
+	default:
+		return false
+	}
+}
+
+func implicitRoleForTag(tag string) string {
+	tag = strings.ToLower(strings.TrimSpace(tag))
+	if tag == "" {
+		return ""
+	}
+	if idx := strings.IndexFunc(tag, func(r rune) bool {
+		return !unicode.IsLetter(r) && !unicode.IsDigit(r)
+	}); idx >= 0 {
+		tag = tag[:idx]
+	}
+
+	switch tag {
+	case "a", "area":
+		return "link"
+	case "button", "summary":
+		return "button"
+	case "input", "textarea":
+		return "textbox"
+	case "select":
+		return "combobox"
+	case "option":
+		return "option"
+	case "img":
+		return "img"
+	case "form":
+		return "form"
+	case "nav":
+		return "navigation"
+	case "main":
+		return "main"
+	case "header":
+		return "banner"
+	case "footer":
+		return "contentinfo"
+	case "aside":
+		return "complementary"
+	case "article":
+		return "article"
+	case "section":
+		return "region"
+	case "h1", "h2", "h3", "h4", "h5", "h6":
+		return "heading"
+	case "ul", "ol":
+		return "list"
+	case "li":
+		return "listitem"
+	case "table":
+		return "table"
+	case "tr":
+		return "row"
+	case "th":
+		return "columnheader"
+	case "td":
+		return "cell"
+	default:
+		return ""
+	}
+}
+
+func locatorFieldValues(kind structuredLocatorKind, el types.ElementDescriptor) []string {
+	switch kind {
+	case locatorText:
+		if strings.TrimSpace(el.Text) != "" {
+			return []string{el.Text}
+		}
+		return []string{el.Name}
+	case locatorLabel:
+		return []string{el.Label, el.Positional.LabelledBy}
+	case locatorPlaceholder:
+		return []string{el.Placeholder}
+	case locatorAlt:
+		if strings.TrimSpace(el.Alt) != "" {
+			return []string{el.Alt}
+		}
+		if isImageRole(el.Role) {
+			return []string{el.Name}
+		}
+		return nil
+	case locatorTitle:
+		return []string{el.Title}
+	case locatorTestID:
+		return []string{el.TestID}
+	default:
+		return nil
+	}
+}
+
+func isImageRole(role string) bool {
+	role = normalizeLocatorText(role)
+	return role == "img" || role == "image"
+}
+
+func scoreLocatorValues(needle string, values []string) (float64, bool) {
+	want := normalizeLocatorText(needle)
+	if want == "" {
+		return 0, false
+	}
+
+	best := 0.0
+	for _, value := range values {
+		have := normalizeLocatorText(value)
+		if have == "" {
+			continue
+		}
+		switch {
+		case have == want:
+			return 1.0, true
+		case strings.Contains(have, want):
+			if best < 0.78 {
+				best = 0.78
+			}
+		}
+	}
+	if best == 0 {
+		return 0, false
+	}
+	return best, true
+}
+
+func normalizeLocatorText(value string) string {
+	return strings.ToLower(strings.Join(strings.Fields(strings.TrimSpace(value)), " "))
+}
+
+func structuredElementOrder(idx int, el types.ElementDescriptor) int {
+	if el.DocumentIdx > 0 {
+		return el.DocumentIdx
+	}
+	return idx
+}
diff --git a/internal/engine/structured_locator_test.go b/internal/engine/structured_locator_test.go
new file mode 100644
index 0000000..6f6c31b
--- /dev/null
+++ b/internal/engine/structured_locator_test.go
@@ -0,0 +1,376 @@
+package engine
+
+import (
+	"context"
+	"testing"
+
+	"github.com/pinchtab/semantic/internal/types"
+)
+
+func TestParseStructuredLocator_TableDriven(t *testing.T) {
+	tests := []struct {
+		name   string
+		raw    string
+		want   structuredLocator
+		wantOK bool
+	}{
+		{
+			name:   "role only",
+			raw:    "role:button",
+			want:   structuredLocator{kind: locatorRole, role: "button"},
+			wantOK: true,
+		},
+		{
+			name:   "role with name",
+			raw:    "role:button Sign In",
+			want:   structuredLocator{kind: locatorRole, role: "button", value: "Sign In"},
+			wantOK: true,
+		},
+		{
+			name:   "role with bracketed name",
+			raw:    "role:button [Sign In]",
+			want:   structuredLocator{kind: locatorRole, role: "button", value: "Sign In"},
+			wantOK: true,
+		},
+		{
+			name:   "text",
+			raw:    "text:Welcome back",
+			want:   structuredLocator{kind: locatorText, value: "Welcome back"},
+			wantOK: true,
+		},
+		{
+			name:   "quoted placeholder",
+			raw:    `placeholder:"Search products"`,
+			want:   structuredLocator{kind: locatorPlaceholder, value: "Search products"},
+			wantOK: true,
+		},
+		{
+			name:   "first wrapper",
+			raw:    "first:role:button",
+			want:   structuredLocator{kind: locatorRole, role: "button", wrapper: locatorFirst},
+			wantOK: true,
+		},
+		{
+			name:   "last wrapper",
+			raw:    "last:text:Submit",
+			want:   structuredLocator{kind: locatorText, value: "Submit", wrapper: locatorLast},
+			wantOK: true,
+		},
+		{
+			name:   "nth wrapper",
+			raw:    "nth:2:role:link Privacy",
+			want:   structuredLocator{kind: locatorRole, role: "link", value: "Privacy", wrapper: locatorNth, nth: 2},
+			wantOK: true,
+		},
+		{
+			name:   "nth zero parses as structured locator",
+			raw:    "nth:0:role:button",
+			want:   structuredLocator{kind: locatorRole, role: "button", wrapper: locatorNth, nth: 0},
+			wantOK: true,
+		},
+		{
+			name:   "invalid wrapper base",
+			raw:    "first:button",
+			wantOK: false,
+		},
+		{
+			name:   "natural language",
+			raw:    "first button",
+			wantOK: false,
+		},
+		{
+			name:   "empty field",
+			raw:    "testid:",
+			wantOK: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, ok := parseStructuredLocator(tt.raw)
+			if ok != tt.wantOK {
+				t.Fatalf("ok=%v, want %v", ok, tt.wantOK)
+			}
+			if !ok {
+				return
+			}
+			if got != tt.want {
+				t.Fatalf("locator=%+v, want %+v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestStructuredLocator_FieldSpecificMatches(t *testing.T) {
+	m := NewLexicalMatcher()
+	elements := []types.ElementDescriptor{
+		{Ref: "name", Role: "button", Name: "Search"},
+		{Ref: "placeholder", Role: "textbox", Name: "Query", Placeholder: "Search"},
+		{Ref: "label", Role: "textbox", Name: "Email", Label: "Work Email"},
+		{Ref: "alt", Role: "img", Name: "Decorative", Alt: "Company Logo"},
+		{Ref: "title", Role: "button", Name: "Help", Title: "Open Help Center"},
+		{Ref: "testid", Role: "button", Name: "Submit", TestID: "checkout-submit"},
+	}
+
+	tests := []struct {
+		query string
+		want  string
+	}{
+		{"placeholder:Search", "placeholder"},
+		{"label:Work Email", "label"},
+		{"alt:Company Logo", "alt"},
+		{"title:Help Center", "title"},
+		{"testid:checkout-submit", "testid"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.query, func(t *testing.T) {
+			res, err := m.Find(context.Background(), tt.query, elements, types.FindOptions{Threshold: 0, TopK: len(elements)})
+			if err != nil {
+				t.Fatalf("Find returned error: %v", err)
+			}
+			if res.BestRef != tt.want {
+				t.Fatalf("BestRef=%q, want %q; matches=%v", res.BestRef, tt.want, res.Matches)
+			}
+			if len(res.Matches) != 1 {
+				t.Fatalf("expected field-specific locator to match one element, got %d", len(res.Matches))
+			}
+		})
+	}
+}
+
+func TestStructuredLocator_ExactOutranksSubstring(t *testing.T) {
+	m := NewLexicalMatcher()
+	elements := []types.ElementDescriptor{
+		{Ref: "substring", Role: "button", Text: "Submit order", DocumentIdx: 0},
+		{Ref: "exact", Role: "button", Text: "Submit", DocumentIdx: 1},
+	}
+
+	res, err := m.Find(context.Background(), "text:Submit", elements, types.FindOptions{Threshold: 0, TopK: 2})
+	if err != nil {
+		t.Fatalf("Find returned error: %v", err)
+	}
+	if res.BestRef != "exact" {
+		t.Fatalf("BestRef=%q, want exact; matches=%v", res.BestRef, res.Matches)
+	}
+	if len(res.Matches) != 2 {
+		t.Fatalf("expected two matches, got %d", len(res.Matches))
+	}
+	if res.Matches[0].Score <= res.Matches[1].Score {
+		t.Fatalf("expected exact score above substring, got %.2f <= %.2f", res.Matches[0].Score, res.Matches[1].Score)
+	}
+}
+
+func TestStructuredLocator_RoleUsesExplicitBeforeImplicitTagRole(t *testing.T) {
+	m := NewLexicalMatcher()
+	elements := []types.ElementDescriptor{
+		{Ref: "implicit", Tag: "button", Name: "Save", DocumentIdx: 0},
+		{Ref: "explicit", Role: "button", Tag: "div", Name: "Save", DocumentIdx: 1},
+		{Ref: "overridden", Role: "link", Tag: "button", Name: "Save", DocumentIdx: 2},
+	}
+
+	res, err := m.Find(context.Background(), "role:button Save", elements, types.FindOptions{Threshold: 0, TopK: 3})
+	if err != nil {
+		t.Fatalf("Find returned error: %v", err)
+	}
+	if res.BestRef != "explicit" {
+		t.Fatalf("BestRef=%q, want explicit; matches=%v", res.BestRef, res.Matches)
+	}
+	if len(res.Matches) != 2 {
+		t.Fatalf("expected explicit and implicit matches only, got %d: %v", len(res.Matches), res.Matches)
+	}
+	if _, ok := findInternalScore(res.Matches, "overridden"); ok {
+		t.Fatalf("explicit role should override implicit tag role; matches=%v", res.Matches)
+	}
+}
+
+func TestStructuredLocator_WrappersSelectFromOrderedCandidates(t *testing.T) {
+	m := NewCombinedMatcher(NewHashingEmbedder(128))
+	elements := []types.ElementDescriptor{
+		{Ref: "first", Role: "button", Name: "Save", DocumentIdx: 0},
+		{Ref: "second", Role: "button", Name: "Save", DocumentIdx: 1},
+		{Ref: "third", Role: "button", Name: "Save", DocumentIdx: 2},
+	}
+
+	tests := []struct {
+		query string
+		want  string
+	}{
+		{"first:role:button Save", "first"},
+		{"last:role:button Save", "third"},
+		{"nth:2:role:button Save", "second"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.query, func(t *testing.T) {
+			res, err := m.Find(context.Background(), tt.query, elements, types.FindOptions{Threshold: 0, TopK: 1})
+			if err != nil {
+				t.Fatalf("Find returned error: %v", err)
+			}
+			if res.BestRef != tt.want {
+				t.Fatalf("BestRef=%q, want %q; matches=%v", res.BestRef, tt.want, res.Matches)
+			}
+			if len(res.Matches) != 1 {
+				t.Fatalf("expected wrapper to select one match, got %d", len(res.Matches))
+			}
+		})
+	}
+}
+
+func TestStructuredLocator_WrappersUseDocumentOrderNotScoreRank(t *testing.T) {
+	m := NewLexicalMatcher()
+	elements := []types.ElementDescriptor{
+		{Ref: "first-partial", Role: "button", Text: "Submit order", DocumentIdx: 0},
+		{Ref: "second-exact", Role: "button", Text: "Submit", DocumentIdx: 1},
+	}
+
+	tests := []struct {
+		query string
+		want  string
+	}{
+		{"first:text:Submit", "first-partial"},
+		{"last:text:Submit", "second-exact"},
+		{"nth:1:text:Submit", "first-partial"},
+		{"nth:2:text:Submit", "second-exact"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.query, func(t *testing.T) {
+			res, err := m.Find(context.Background(), tt.query, elements, types.FindOptions{Threshold: 0, TopK: 1})
+			if err != nil {
+				t.Fatalf("Find returned error: %v", err)
+			}
+			if res.BestRef != tt.want {
+				t.Fatalf("BestRef=%q, want %q; matches=%v", res.BestRef, tt.want, res.Matches)
+			}
+		})
+	}
+}
+
+func TestStructuredLocator_NthZeroReturnsNoMatch(t *testing.T) {
+	m := NewLexicalMatcher()
+	elements := []types.ElementDescriptor{
+		{Ref: "submit", Role: "button", Text: "Submit"},
+	}
+
+	res, err := m.Find(context.Background(), "nth:0:text:Submit", elements, types.FindOptions{Threshold: 0, TopK: 1})
+	if err != nil {
+		t.Fatalf("Find returned error: %v", err)
+	}
+	if len(res.Matches) != 0 {
+		t.Fatalf("expected nth:0 to return no structured matches, got %v", res.Matches)
+	}
+	if res.BestRef != "" {
+		t.Fatalf("expected empty BestRef, got %q", res.BestRef)
+	}
+}
+
+func TestStructuredLocator_RoleNameUsesAccessibleNameCandidates(t *testing.T) {
+	m := NewLexicalMatcher()
+	elements := []types.ElementDescriptor{
+		{Ref: "label", Role: "textbox", Name: "Input", Label: "Work Email"},
+		{Ref: "labelled-by", Role: "textbox", Name: "Input", Positional: types.PositionalHints{LabelledBy: "Billing ZIP"}},
+		{Ref: "text", Role: "button", Name: "Icon only", Text: "Save changes"},
+		{Ref: "alt", Role: "img", Name: "Graphic", Alt: "Company Logo"},
+		{Ref: "title", Role: "button", Name: "?", Title: "Open Help Center"},
+		{Ref: "placeholder", Role: "textbox", Name: "", Placeholder: "Search products"},
+		{Ref: "value", Role: "textbox", Name: "Promo", Value: "SUMMER25"},
+	}
+
+	tests := []struct {
+		query string
+		want  string
+	}{
+		{"role:textbox Work Email", "label"},
+		{"role:textbox Billing ZIP", "labelled-by"},
+		{"role:button Save changes", "text"},
+		{"role:img Company Logo", "alt"},
+		{"role:button Help Center", "title"},
+		{"role:textbox Search products", "placeholder"},
+		{"role:textbox SUMMER25", "value"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.query, func(t *testing.T) {
+			res, err := m.Find(context.Background(), tt.query, elements, types.FindOptions{Threshold: 0, TopK: len(elements)})
+			if err != nil {
+				t.Fatalf("Find returned error: %v", err)
+			}
+			if res.BestRef != tt.want {
+				t.Fatalf("BestRef=%q, want %q; matches=%v", res.BestRef, tt.want, res.Matches)
+			}
+		})
+	}
+}
+
+func TestStructuredLocator_FindAndSemanticPrefixesForceNaturalMatching(t *testing.T) {
+	m := NewLexicalMatcher()
+	elements := []types.ElementDescriptor{
+		{Ref: "button", Role: "button", Name: "Save"},
+		{Ref: "literal", Role: "heading", Name: "role button"},
+	}
+
+	tests := []string{
+		"find:role:button",
+		"semantic:role:button",
+	}
+
+	for _, query := range tests {
+		t.Run(query, func(t *testing.T) {
+			res, err := m.Find(context.Background(), query, elements, types.FindOptions{Threshold: 0, TopK: 2})
+			if err != nil {
+				t.Fatalf("Find returned error: %v", err)
+			}
+			if res.BestRef != "literal" {
+				t.Fatalf("BestRef=%q, want literal natural-language match; matches=%v", res.BestRef, res.Matches)
+			}
+		})
+	}
+}
+
+func TestStructuredLocator_TextFallsBackToNameForLegacyDescriptors(t *testing.T) {
+	m := NewLexicalMatcher()
+	elements := []types.ElementDescriptor{
+		{Ref: "button", Role: "button", Name: "Submit"},
+	}
+
+	res, err := m.Find(context.Background(), "text:Submit", elements, types.FindOptions{Threshold: 0, TopK: 1})
+	if err != nil {
+		t.Fatalf("Find returned error: %v", err)
+	}
+	if res.BestRef != "button" {
+		t.Fatalf("BestRef=%q, want button", res.BestRef)
+	}
+}
+
+func TestStructuredLocator_EmbeddingMatcherBypassesEmbedding(t *testing.T) {
+	m := NewEmbeddingMatcher(forbiddenEmbedder{})
+	elements := []types.ElementDescriptor{
+		{Ref: "button", Role: "button", Name: "Submit"},
+	}
+
+	res, err := m.Find(context.Background(), "role:button Submit", elements, types.FindOptions{Threshold: 0, TopK: 1})
+	if err != nil {
+		t.Fatalf("Find returned error: %v", err)
+	}
+	if res.BestRef != "button" {
+		t.Fatalf("BestRef=%q, want button", res.BestRef)
+	}
+}
+
+func findInternalScore(matches []types.ElementMatch, ref string) (float64, bool) {
+	for _, match := range matches {
+		if match.Ref == ref {
+			return match.Score, true
+		}
+	}
+	return 0, false
+}
+
+type forbiddenEmbedder struct{}
+
+func (forbiddenEmbedder) Strategy() string { return "forbidden" }
+
+func (forbiddenEmbedder) Embed([]string) ([][]float32, error) {
+	panic("structured locator should not call Embed")
+}
diff --git a/internal/types/types.go b/internal/types/types.go
index 192cce8..fb0678a 100644
--- a/internal/types/types.go
+++ b/internal/types/types.go
@@ -85,36 +85,45 @@ type MatchExplain struct {
 
 // PositionalHints captures optional AX-tree relationship and position metadata.
 type PositionalHints struct {
-	Depth        int
-	SiblingIndex int
-	SiblingCount int
-	LabelledBy   string
-	X            float64
-	Y            float64
-	Width        float64
-	Height       float64
+	Depth        int     `json:"depth,omitempty"`
+	SiblingIndex int     `json:"sibling_index,omitempty"`
+	SiblingCount int     `json:"sibling_count,omitempty"`
+	LabelledBy   string  `json:"labelled_by,omitempty"`
+	X            float64 `json:"x,omitempty"`
+	Y            float64 `json:"y,omitempty"`
+	Width        float64 `json:"width,omitempty"`
+	Height       float64 `json:"height,omitempty"`
 }
 
 // ElementDescriptor describes a single accessibility tree node.
 type ElementDescriptor struct {
-	Ref         string
-	Role        string
-	Name        string
-	Value       string
-	Interactive bool
-	Parent      string
-	Section     string
-	DocumentIdx int
-	Positional  PositionalHints
+	Ref         string          `json:"ref,omitempty"`
+	Role        string          `json:"role,omitempty"`
+	Name        string          `json:"name,omitempty"`
+	Value       string          `json:"value,omitempty"`
+	Label       string          `json:"label,omitempty"`
+	Placeholder string          `json:"placeholder,omitempty"`
+	Alt         string          `json:"alt,omitempty"`
+	Title       string          `json:"title,omitempty"`
+	TestID      string          `json:"testid,omitempty"`
+	Text        string          `json:"text,omitempty"`
+	Tag         string          `json:"tag,omitempty"`
+	Interactive bool            `json:"interactive,omitempty"`
+	Parent      string          `json:"parent,omitempty"`
+	Section     string          `json:"section,omitempty"`
+	DocumentIdx int             `json:"document_idx,omitempty"`
+	Positional  PositionalHints `json:"positional,omitempty"`
 }
 
-// Composite returns a single string combining role, name, and value
+// Composite returns a single string combining public element identity fields
 // for matching purposes: "role: name [value]".
 func (ed *ElementDescriptor) Composite() string {
 	var parts []string
 
 	if ed.Role != "" {
 		parts = append(parts, ed.Role+":")
+	} else if ed.Tag != "" {
+		parts = append(parts, ed.Tag+":")
 	}
 	if ed.Name != "" {
 		parts = append(parts, ed.Name)
@@ -122,6 +131,21 @@ func (ed *ElementDescriptor) Composite() string {
 	if ed.Value != "" && ed.Value != ed.Name {
 		parts = append(parts, "["+ed.Value+"]")
 	}
+	if shouldAddCompositeField(ed.Text, ed.Name, ed.Value) {
+		parts = append(parts, ed.Text)
+	}
+	if shouldAddCompositeField(ed.Label, ed.Name, ed.Text) {
+		parts = append(parts, "label:"+ed.Label)
+	}
+	if shouldAddCompositeField(ed.Placeholder, ed.Name, ed.Text) {
+		parts = append(parts, "placeholder:"+ed.Placeholder)
+	}
+	if shouldAddCompositeField(ed.Alt, ed.Name, ed.Text) {
+		parts = append(parts, "alt:"+ed.Alt)
+	}
+	if shouldAddCompositeField(ed.Title, ed.Name, ed.Text) {
+		parts = append(parts, "title:"+ed.Title)
+	}
 	if ed.Section != "" {
 		parts = append(parts, "{"+ed.Section+"}")
 	}
@@ -129,6 +153,24 @@ func (ed *ElementDescriptor) Composite() string {
 	return strings.Join(parts, " ")
 }
 
+func shouldAddCompositeField(value string, existing ...string) bool {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return false
+	}
+	normValue := normalizeCompositeValue(value)
+	for _, candidate := range existing {
+		if normValue == normalizeCompositeValue(candidate) {
+			return false
+		}
+	}
+	return true
+}
+
+func normalizeCompositeValue(value string) string {
+	return strings.ToLower(strings.Join(strings.Fields(strings.TrimSpace(value)), " "))
+}
+
 // CalibrateConfidence maps a score to a human-readable confidence level.
 func CalibrateConfidence(score float64) string {
 	switch {
diff --git a/semantic_test.go b/semantic_test.go
index e41120b..2376b24 100644
--- a/semantic_test.go
+++ b/semantic_test.go
@@ -309,6 +309,21 @@ func TestElementDescriptor_Composite_IncludesSection(t *testing.T) {
 	}
 }
 
+func TestElementDescriptor_Composite_IncludesLocatorFields(t *testing.T) {
+	d := semantic.ElementDescriptor{
+		Role:        "textbox",
+		Name:        "Email",
+		Label:       "Work Email",
+		Placeholder: "name@example.com",
+		Title:       "Primary email address",
+		TestID:      "email-input",
+	}
+	want := "textbox: Email label:Work Email placeholder:name@example.com title:Primary email address"
+	if d.Composite() != want {
+		t.Errorf("unexpected composite with locator fields: %q", d.Composite())
+	}
+}
+
 func TestElementDescriptor_PositionalHints(t *testing.T) {
 	d := semantic.ElementDescriptor{
 		Role: "textbox",