From 88b698982fba71964bb1b482dbf9778391666a15 Mon Sep 17 00:00:00 2001
From: Logan Stokols <LFStokols@gmail.com>
Date: Mon, 25 May 2026 21:56:42 -0400
Subject: [PATCH 1/3] feat(xfa): extract scripts from nodes not emitted as
 Questions/Sections
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Previously, script extraction was driven by walkSubformChildren via the
per-node attachFieldScripts helper, so any script whose owner node was
suppressed by emitField / emitDraw was silently dropped. The known cases:
event-bearing <draw> elements (status indicators), bind="none"
non-AddAttachment buttons (Help Text / Show Intro triggers), <pageArea>
events, and per-option scripts on <field>s flattened into an <exclGroup>'s
Options. The b44a6f9 FormScript comment acknowledged this gap and deferred
the fix.

Split script extraction from question emission:

- New extractAllScripts walks the entire xfaNode tree post-Section walk
  and emits a FormScript for every event-bearing node, regardless of
  whether the node was emitted as a Question or Section. OwnerPath is set
  to the SOM path of the owning node; OwnerID is left empty.

- New populateScriptBackRefs indexes the resulting scripts by OwnerPath,
  fills in OwnerID and Question.Scripts / FormSection.Scripts back-refs
  whenever the owner was also emitted as a Question/Section, and leaves
  orphans with empty OwnerID.

- exclGroup OptionEvents is a parallel slice to Options that preserves
  per-option events through the flatten so they reach extractAllScripts.

- pageArea and exclGroup are now valid event-stack targets in the
  parseXFATemplate state machine (previously only subform).

The attachFieldScripts / appendScripts helpers and xfaNode.QuestionID
field are removed — back-refs are now populated by path lookup in a single
post-pass rather than threaded through emission.

Tests cover all four orphan cases (pageArea, bind=none button, draw with
event, exclGroup per-option) and assert that the corresponding nodes are
still NOT emitted as Questions — only their scripts are surfaced.

FormScript doc comment rewritten: orphan scripts are now first-class
(OwnerPath set, OwnerID empty) rather than missing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 forms/xfa/xfa_form_translator.go        | 180 ++++++++++++++++-----
 forms/xfa/xfa_script_extraction_test.go | 207 ++++++++++++++++++++++++
 types/form_types.go                     |  11 +-
 3 files changed, 348 insertions(+), 50 deletions(-)

diff --git a/forms/xfa/xfa_form_translator.go b/forms/xfa/xfa_form_translator.go
index b6420e8..0a9b24d 100644
--- a/forms/xfa/xfa_form_translator.go
+++ b/forms/xfa/xfa_form_translator.go
@@ -420,6 +420,12 @@ type xfaNode struct {
 	Validation   *XFAValidation
 	Events       []XFAEvent
 
+	// OptionEvents is parallel to Options on exclGroup nodes: one []XFAEvent per
+	// flattened option <field>. Lets per-option event scripts (originally hung off
+	// the individual <field> inside an <exclGroup>) survive the flatten so they
+	// can still be surfaced as FormScripts.
+	OptionEvents [][]XFAEvent
+
 	// UI-element-specific constraints
 	AllowNeutral          bool   // checkButton allowNeutral="1" → tri-state checkbox
 	MaxChars              *int   // textEdit maxChars → ValidationRules.MaxLength
@@ -444,11 +450,6 @@ type xfaNode struct {
 	ExDataHTML       string // plain text extracted from text/html exData without xfa:embed markers
 
 	PageNumber int
-
-	// QuestionID is the ID assigned to this node's emitted Question.
-	// Set by emitField/emitExclGroup after the question is built; empty otherwise.
-	// Used by buildFormScripts to populate FormScript.OwnerID for field-attached scripts.
-	QuestionID string
 }
 
 // xfaTemplateResult bundles the parse tree with top-level metadata.
@@ -965,7 +966,7 @@ func parseXFATemplate(xfaXML string, verbose bool) (*xfaTemplateResult, error) {
 				}
 				if currentLeaf != nil {
 					currentLeaf.Events = append(currentLeaf.Events, ev)
-				} else if top := topOfStack(); top.Kind == xfaKindSubform {
+				} else if top := topOfStack(); top.Kind == xfaKindSubform || top.Kind == xfaKindPageArea || top.Kind == xfaKindExclGroup {
 					top.Events = append(top.Events, ev)
 				}
 
@@ -1002,7 +1003,7 @@ func parseXFATemplate(xfaXML string, verbose bool) (*xfaTemplateResult, error) {
 							putAttr(&last.Properties, attr.Name.Local, attr.Value)
 						}
 					}
-				} else if top := topOfStack(); top.Kind == xfaKindSubform && len(top.Events) > 0 {
+				} else if top := topOfStack(); (top.Kind == xfaKindSubform || top.Kind == xfaKindPageArea || top.Kind == xfaKindExclGroup) && len(top.Events) > 0 {
 					inScript = true
 					currentValue.Reset()
 					last := &top.Events[len(top.Events)-1]
@@ -1155,6 +1156,9 @@ func parseXFATemplate(xfaXML string, verbose bool) (*xfaTemplateResult, error) {
 							optValue = currentLeaf.Name
 						}
 						top.Options = append(top.Options, XFAOption{Label: optLabel, Value: optValue})
+						// Preserve per-option events (parallel slice) so they can still
+						// surface as FormScripts even though the option <field> is flattened.
+						top.OptionEvents = append(top.OptionEvents, currentLeaf.Events)
 						// draws inside exclGroup are decorative labels — fall through and discard
 					} else if top.Kind != xfaKindExclGroup {
 						top.Children = append(top.Children, currentLeaf)
@@ -1269,7 +1273,7 @@ func parseXFATemplate(xfaXML string, verbose bool) (*xfaTemplateResult, error) {
 				} else if currentLeaf != nil && len(currentLeaf.Events) > 0 {
 					last := &currentLeaf.Events[len(currentLeaf.Events)-1]
 					last.Body = currentValue.String()
-				} else if top := topOfStack(); top.Kind == xfaKindSubform && len(top.Events) > 0 {
+				} else if top := topOfStack(); (top.Kind == xfaKindSubform || top.Kind == xfaKindPageArea || top.Kind == xfaKindExclGroup) && len(top.Events) > 0 {
 					last := &top.Events[len(top.Events)-1]
 					last.Body = currentValue.String()
 				}
@@ -1402,6 +1406,15 @@ func buildFormSchema(result *xfaTemplateResult, verbose bool) *types.FormSchema
 	var qIdx int
 	schema.Sections = walkSubformChildren(result.Root, nil, schema, &qIdx, false, verbose)
 
+	// Extract every <script> body in the template — including those on nodes
+	// pdfer doesn't emit as a Question or FormSection (event-bearing <draw>s,
+	// bind="none" non-AddAttachment buttons, <pageArea>s, per-option events
+	// inside an <exclGroup>). OwnerID is filled in by the back-ref pass below
+	// when the owner happens to also be a Question/Section; orphan scripts keep
+	// OwnerID empty and rely on OwnerPath for correlation.
+	extractAllScripts(result.Root, schema)
+	populateScriptBackRefs(schema)
+
 	// Append <variables><script> blocks verbatim as FormScripts. These are
 	// template-wide helper definitions (functions invoked from field events) and
 	// are exposed as-is for callers to interpret.
@@ -1481,19 +1494,123 @@ func buildFormScripts(events []XFAEvent, ownerPath, ownerID string) []types.Form
 	return out
 }
 
-// appendScripts appends scripts to schema.Scripts and returns the appended IDs
-// in order. The IDs are suitable for storage in Question.Scripts /
-// FormSection.Scripts.
-func appendScripts(schema *types.FormSchema, scripts []types.FormScript) []string {
-	if len(scripts) == 0 {
-		return nil
+// extractAllScripts walks the entire xfaNode tree and emits a FormScript for
+// every event-bearing node — regardless of whether pdfer also surfaces that
+// node as a Question or FormSection. OwnerPath is the SOM path of the owning
+// node. OwnerID is left blank here and filled in by populateScriptBackRefs
+// when the owner also became a Question/Section; it stays empty for orphan
+// scripts (event-bearing <draw>s, bind="none" non-AddAttachment buttons,
+// <pageArea>s, and per-option events flattened out of an <exclGroup>).
+func extractAllScripts(root *xfaNode, schema *types.FormSchema) {
+	var walk func(*xfaNode, []string)
+	walk = func(node *xfaNode, parentPath []string) {
+		var nodePath []string
+		if node.Name != "" && node.Name != "_root" {
+			nodePath = make([]string, len(parentPath)+1)
+			copy(nodePath, parentPath)
+			nodePath[len(parentPath)] = node.Name
+		} else {
+			nodePath = parentPath
+		}
+		somPath := strings.Join(nodePath, ".")
+
+		if len(node.Events) > 0 {
+			schema.Scripts = append(schema.Scripts, buildFormScripts(node.Events, somPath, "")...)
+		}
+
+		// Per-option events on exclGroup — Options and OptionEvents are parallel
+		// slices populated when child <field>s are flattened into the group.
+		if node.Kind == xfaKindExclGroup {
+			for i, optEvents := range node.OptionEvents {
+				if i >= len(node.Options) || len(optEvents) == 0 {
+					continue
+				}
+				optPath := somPath
+				if v := node.Options[i].Value; v != "" {
+					if optPath == "" {
+						optPath = v
+					} else {
+						optPath = optPath + "." + v
+					}
+				}
+				schema.Scripts = append(schema.Scripts, buildFormScripts(optEvents, optPath, "")...)
+			}
+		}
+
+		for _, child := range node.Children {
+			walk(child, nodePath)
+		}
 	}
-	ids := make([]string, len(scripts))
-	for i, s := range scripts {
-		ids[i] = s.ID
+	walk(root, nil)
+}
+
+// populateScriptBackRefs indexes schema.Scripts by OwnerPath and fills in the
+// Question.Scripts / FormSection.Scripts back-references, plus the script's
+// OwnerID, whenever its owner happens to be an emitted Question or Section.
+// Orphan scripts keep an empty OwnerID and rely solely on OwnerPath.
+func populateScriptBackRefs(schema *types.FormSchema) {
+	if len(schema.Scripts) == 0 {
+		return
+	}
+	byPath := make(map[string][]int)
+	for i, s := range schema.Scripts {
+		if s.OwnerPath == "" {
+			continue
+		}
+		byPath[s.OwnerPath] = append(byPath[s.OwnerPath], i)
+	}
+	if len(byPath) == 0 {
+		return
+	}
+	qByID := make(map[string]*types.Question, len(schema.Questions))
+	for i := range schema.Questions {
+		qByID[schema.Questions[i].ID] = &schema.Questions[i]
+	}
+	covered := make(map[string]bool)
+
+	assign := func(ownerPath, ownerID string) []string {
+		idxs, ok := byPath[ownerPath]
+		if !ok {
+			return nil
+		}
+		ids := make([]string, len(idxs))
+		for i, idx := range idxs {
+			schema.Scripts[idx].OwnerID = ownerID
+			ids[i] = schema.Scripts[idx].ID
+		}
+		return ids
+	}
+
+	var walkSections func([]types.FormSection)
+	walkSections = func(secs []types.FormSection) {
+		for i := range secs {
+			sec := &secs[i]
+			sec.Scripts = assign(sec.Path, sec.Path)
+			for _, qID := range sec.Questions {
+				q := qByID[qID]
+				if q == nil {
+					continue
+				}
+				covered[qID] = true
+				somPath := q.Name
+				if sec.Path != "" {
+					somPath = sec.Path + "." + q.Name
+				}
+				q.Scripts = assign(somPath, q.ID)
+			}
+			walkSections(sec.Children)
+		}
+	}
+	walkSections(schema.Sections)
+
+	// Root-level questions (no enclosing section) — their SOM path is just Name.
+	for i := range schema.Questions {
+		q := &schema.Questions[i]
+		if covered[q.ID] {
+			continue
+		}
+		q.Scripts = assign(q.Name, q.ID)
 	}
-	schema.Scripts = append(schema.Scripts, scripts...)
-	return ids
 }
 
 // subformHasInteractive reports whether node contains at least one field or
@@ -1641,21 +1758,15 @@ func walkSubformChildren(node *xfaNode, path []string, schema *types.FormSchema,
 
 		case xfaKindExclGroup:
 			q := emitExclGroup(child, path, qIdx)
-			child.QuestionID = q.ID
-			attachFieldScripts(&q, child, path, schema)
 			schema.Questions = append(schema.Questions, q)
 
 		case xfaKindField:
 			if q, ok := emitField(child, path, qIdx, verbose); ok {
-				child.QuestionID = q.ID
-				attachFieldScripts(&q, child, path, schema)
 				schema.Questions = append(schema.Questions, q)
 			}
 
 		case xfaKindDraw:
 			if q, ok := emitDraw(child, path, node, qIdx, parentHidden); ok {
-				child.QuestionID = q.ID
-				attachFieldScripts(&q, child, path, schema)
 				schema.Questions = append(schema.Questions, q)
 			}
 		}
@@ -1663,23 +1774,6 @@ func walkSubformChildren(node *xfaNode, path []string, schema *types.FormSchema,
 	return sections
 }
 
-// attachFieldScripts builds FormScripts for any events on the node and records
-// their IDs on the Question. The SOM path of the owner is the parent subform
-// path joined with the node's own name.
-func attachFieldScripts(q *types.Question, node *xfaNode, parentPath []string, schema *types.FormSchema) {
-	if len(node.Events) == 0 {
-		return
-	}
-	owner := node.Name
-	if len(parentPath) > 0 {
-		owner = strings.Join(parentPath, ".") + "." + node.Name
-	}
-	ids := appendScripts(schema, buildFormScripts(node.Events, owner, q.ID))
-	if len(ids) > 0 {
-		q.Scripts = ids
-	}
-}
-
 // buildSection creates a FormSection for a subform node and recurses into its children.
 func buildSection(node *xfaNode, parentPath []string, schema *types.FormSchema, qIdx *int, parentHidden bool, verbose bool) types.FormSection {
 	path := make([]string, len(parentPath)+1)
@@ -1687,7 +1781,6 @@ func buildSection(node *xfaNode, parentPath []string, schema *types.FormSchema,
 	path[len(path)-1] = node.Name
 
 	sectionPath := strings.Join(path, ".")
-	sectionScriptIDs := appendScripts(schema, buildFormScripts(node.Events, sectionPath, sectionPath))
 
 	startLen := len(schema.Questions)
 	nodeHidden := parentHidden || node.Hidden
@@ -1709,7 +1802,6 @@ func buildSection(node *xfaNode, parentPath []string, schema *types.FormSchema,
 		Layout:      node.Layout,
 		Width:       node.W,
 		Height:      node.H,
-		Scripts:     sectionScriptIDs,
 	}
 	sec.Children = walkSubformChildren(node, path, schema, qIdx, nodeHidden, verbose)
 	// Record all question IDs added during this section's subtree walk.
diff --git a/forms/xfa/xfa_script_extraction_test.go b/forms/xfa/xfa_script_extraction_test.go
index 069668f..317a872 100644
--- a/forms/xfa/xfa_script_extraction_test.go
+++ b/forms/xfa/xfa_script_extraction_test.go
@@ -386,3 +386,210 @@ func TestVariablesScriptAttrsCaptured(t *testing.T) {
 		t.Errorf("Properties[\"binding\"] = %q, want this", vs.binding)
 	}
 }
+
+// findScript returns the first FormScript matching the given OwnerPath and
+// event activity, or nil if none is found.
+func findScript(scripts []types.FormScript, ownerPath, event string) *types.FormScript {
+	for i := range scripts {
+		if scripts[i].OwnerPath == ownerPath && scripts[i].Event == event {
+			return &scripts[i]
+		}
+	}
+	return nil
+}
+
+// TestPageAreaEventExtracted verifies that <pageArea> events are surfaced as
+// FormScripts with the pageArea's SOM path as OwnerPath. pageAreas are not
+// emitted as Sections, so OwnerID is empty (orphan).
+func TestPageAreaEventExtracted(t *testing.T) {
+	body := `xfa.host.messageBox("page rendered");`
+	xfaXML := `<template>
+  <subform name="form1">
+    <pageArea name="Master">
+      <event activity="ready">
+        <script contentType="application/x-javascript">` + body + `</script>
+      </event>
+    </pageArea>
+    <subform name="Page1">
+      <field name="anchor"><ui><textEdit/></ui></field>
+    </subform>
+  </subform>
+</template>`
+
+	form, err := ParseXFAForm(xfaXML, false)
+	if err != nil {
+		t.Fatalf("ParseXFAForm() error = %v", err)
+	}
+	s := findScript(form.Scripts, "form1.Master", "ready")
+	if s == nil {
+		t.Fatalf("no script with OwnerPath=form1.Master event=ready; got %+v", form.Scripts)
+	}
+	if s.Body != body {
+		t.Errorf("body = %q, want %q", s.Body, body)
+	}
+	if s.OwnerID != "" {
+		t.Errorf("OwnerID = %q, want empty (pageArea is not a Question/Section)", s.OwnerID)
+	}
+}
+
+// TestBindNoneButtonScriptExtracted verifies that a bind="none" button that is
+// not an AddAttachment (e.g. "Help Text" / "Show Intro" UI triggers) still
+// contributes its click-handler script to FormSchema.Scripts, even though the
+// button itself is not emitted as a Question.
+func TestBindNoneButtonScriptExtracted(t *testing.T) {
+	body := `xfa.host.messageBox("?-hint");`
+	xfaXML := `<template>
+  <subform name="Page1">
+    <field name="helpBtn">
+      <ui><button/></ui>
+      <caption><value><text>Help Text</text></value></caption>
+      <bind match="none"/>
+      <event activity="click">
+        <script contentType="application/x-javascript">` + body + `</script>
+      </event>
+    </field>
+  </subform>
+</template>`
+
+	form, err := ParseXFAForm(xfaXML, false)
+	if err != nil {
+		t.Fatalf("ParseXFAForm() error = %v", err)
+	}
+	for _, q := range form.Questions {
+		if q.Name == "helpBtn" {
+			t.Fatalf("bind=none non-AddAttachment button should not be emitted as Question; got %+v", q)
+		}
+	}
+	s := findScript(form.Scripts, "Page1.helpBtn", "click")
+	if s == nil {
+		t.Fatalf("no orphan script for Page1.helpBtn click; got %+v", form.Scripts)
+	}
+	if s.Body != body {
+		t.Errorf("body = %q, want %q", s.Body, body)
+	}
+	if s.OwnerID != "" {
+		t.Errorf("OwnerID = %q, want empty (button is not emitted as Question)", s.OwnerID)
+	}
+}
+
+// TestDrawEventScriptExtracted verifies that event-bearing <draw> elements
+// (status indicators with dynamic show/hide handlers) still surface their
+// scripts as orphan FormScripts even though the draw itself is suppressed.
+func TestDrawEventScriptExtracted(t *testing.T) {
+	body := `this.presence = "hidden";`
+	xfaXML := `<template>
+  <subform name="Page1">
+    <draw name="statusOk">
+      <value><text>Required Question Complete</text></value>
+      <event activity="initialize">
+        <script contentType="application/x-javascript">` + body + `</script>
+      </event>
+    </draw>
+  </subform>
+</template>`
+
+	form, err := ParseXFAForm(xfaXML, false)
+	if err != nil {
+		t.Fatalf("ParseXFAForm() error = %v", err)
+	}
+	for _, q := range form.Questions {
+		if q.Name == "statusOk" {
+			t.Fatalf("event-bearing draw should not be emitted as Question; got %+v", q)
+		}
+	}
+	s := findScript(form.Scripts, "Page1.statusOk", "initialize")
+	if s == nil {
+		t.Fatalf("no orphan script for Page1.statusOk initialize; got %+v", form.Scripts)
+	}
+	if s.Body != body {
+		t.Errorf("body = %q, want %q", s.Body, body)
+	}
+	if s.OwnerID != "" {
+		t.Errorf("OwnerID = %q, want empty (draw is not emitted as Question)", s.OwnerID)
+	}
+}
+
+// TestExclGroupOptionScriptsExtracted verifies that per-option <event>
+// blocks (defined on the individual radio-option <field>s inside an
+// <exclGroup>) are preserved as distinct FormScripts. Each option's script
+// must have its own OwnerPath (exclGroup SOM path + "." + option value) and
+// remain an orphan, while the exclGroup itself (which IS a Question) gets
+// its own script back-ref via the standard Question.Scripts mechanism.
+func TestExclGroupOptionScriptsExtracted(t *testing.T) {
+	bodyA := `xfa.host.messageBox("A selected");`
+	bodyB := `xfa.host.messageBox("B selected");`
+	groupBody := `xfa.host.messageBox("group changed");`
+	xfaXML := `<template>
+  <subform name="Page1">
+    <exclGroup name="choice">
+      <event activity="change">
+        <script contentType="application/x-javascript">` + groupBody + `</script>
+      </event>
+      <field name="optA">
+        <ui><radioButton/></ui>
+        <caption><value><text>A</text></value></caption>
+        <items><text>a</text></items>
+        <event activity="click">
+          <script contentType="application/x-javascript">` + bodyA + `</script>
+        </event>
+      </field>
+      <field name="optB">
+        <ui><radioButton/></ui>
+        <caption><value><text>B</text></value></caption>
+        <items><text>b</text></items>
+        <event activity="click">
+          <script contentType="application/x-javascript">` + bodyB + `</script>
+        </event>
+      </field>
+    </exclGroup>
+  </subform>
+</template>`
+
+	form, err := ParseXFAForm(xfaXML, false)
+	if err != nil {
+		t.Fatalf("ParseXFAForm() error = %v", err)
+	}
+
+	var choiceQ *types.Question
+	for i := range form.Questions {
+		if form.Questions[i].Name == "choice" {
+			choiceQ = &form.Questions[i]
+		}
+	}
+	if choiceQ == nil {
+		t.Fatalf("exclGroup 'choice' question missing")
+	}
+
+	groupScript := findScript(form.Scripts, "Page1.choice", "change")
+	if groupScript == nil {
+		t.Fatalf("no script with OwnerPath=Page1.choice event=change; got %+v", form.Scripts)
+	}
+	if groupScript.Body != groupBody {
+		t.Errorf("group body = %q, want %q", groupScript.Body, groupBody)
+	}
+	if groupScript.OwnerID != choiceQ.ID {
+		t.Errorf("group OwnerID = %q, want question ID %q", groupScript.OwnerID, choiceQ.ID)
+	}
+
+	scriptA := findScript(form.Scripts, "Page1.choice.a", "click")
+	if scriptA == nil {
+		t.Fatalf("no per-option script with OwnerPath=Page1.choice.a; got %+v", form.Scripts)
+	}
+	if scriptA.Body != bodyA {
+		t.Errorf("option A body = %q, want %q", scriptA.Body, bodyA)
+	}
+	if scriptA.OwnerID != "" {
+		t.Errorf("option A OwnerID = %q, want empty (orphan)", scriptA.OwnerID)
+	}
+
+	scriptB := findScript(form.Scripts, "Page1.choice.b", "click")
+	if scriptB == nil {
+		t.Fatalf("no per-option script with OwnerPath=Page1.choice.b; got %+v", form.Scripts)
+	}
+	if scriptB.Body != bodyB {
+		t.Errorf("option B body = %q, want %q", scriptB.Body, bodyB)
+	}
+	if scriptB.OwnerID != "" {
+		t.Errorf("option B OwnerID = %q, want empty (orphan)", scriptB.OwnerID)
+	}
+}
diff --git a/types/form_types.go b/types/form_types.go
index a021b04..5319ec9 100644
--- a/types/form_types.go
+++ b/types/form_types.go
@@ -100,12 +100,11 @@ type ValidationRules struct {
 // FormScript represents a raw script block extracted from an XFA form.
 // Bodies are exposed verbatim — pdfer does not interpret script semantics.
 //
-// Limitations: scripts attached to XFA nodes that pdfer does not surface in
-// the schema are not extracted. This includes decorative <draw> elements with
-// events (e.g. status indicators), <field> buttons with bind="none" other than
-// AddAttachment, <pageArea>-level events, and individual <field> radio options
-// that are collapsed into an <exclGroup>'s Options. Callers that need full
-// event fidelity should walk the raw XFA XML directly.
+// Scripts whose owner node is not emitted as a Question or FormSection (e.g.
+// event-bearing <draw> elements, bind="none" non-AddAttachment buttons,
+// <pageArea> events, individual radio options collapsed into an <exclGroup>)
+// appear here with OwnerPath set and OwnerID empty. Callers that need to
+// correlate orphan scripts must inspect OwnerPath directly.
 type FormScript struct {
 	ID         string                 `json:"id"`                   // stable: SOM owner path + "#" + event + "[" + index + "]"
 	OwnerPath  string                 `json:"owner_path,omitempty"` // SOM path of containing node (e.g. "form1.section.field"); empty for template-level

From 7594b78462ea5e38d0d6fe4625f1ccad7272be66 Mon Sep 17 00:00:00 2001
From: Logan Stokols <LFStokols@gmail.com>
Date: Mon, 25 May 2026 22:59:27 -0400
Subject: [PATCH 2/3] docs(xfa): add scope recommendation design doc
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Captures the high-level design plan for pdfer's XFA surface:

- The scope principle: extract structure and surface logic, don't
  execute logic. Schema is a projection of the template DOM, not a
  snapshot of a Form DOM. Runtime model (instance counts, presence
  toggles, calculation order) is the caller's responsibility.

- P1 roadmap: orphan-script extraction (done in 88b6989), a parallel
  Elements collection for non-question template nodes with visual
  presence or events, and <occur> / <bind> metadata on Sections and
  Questions for dynamic XFA.

- P2 drafts: SOM path parser and schema resolver, SOM-keyed data-DOM
  cursor API, and <validate><script> child-element capture.

- Explicit non-goals: script execution, merge algorithm, instance
  management, calculate dependency tracking, layout engine, and
  script-body parsing. These belong in the runtime layer.

Lives under docs/design/ — first design doc in this repo, introduces
the convention. Status header marks it as P1 committed, P2 draft, and
open for discussion.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/design/xfa-scope.md | 334 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 334 insertions(+)
 create mode 100644 docs/design/xfa-scope.md

diff --git a/docs/design/xfa-scope.md b/docs/design/xfa-scope.md
new file mode 100644
index 0000000..58ebc03
--- /dev/null
+++ b/docs/design/xfa-scope.md
@@ -0,0 +1,334 @@
+# pdfer XFA support: scope recommendations
+
+**Status:** Design plan for pdfer's XFA surface. P1 is the committed roadmap;
+P2 is a draft proposal still under consideration. Open for discussion — file
+an issue or open a PR to suggest changes.
+
+**Implementation status:** P1 #1 closed by commit `88b6989` (orphan-script
+extraction). P1 #2 and #3 remain open and tracked here.
+
+---
+
+A review of pdfer's XFA support from the perspective of a downstream consumer
+(`xfa-web`) building an interactive renderer on top of the library.
+
+The headline: **the overall design is coherent and defensible. The scope
+boundary is in the right place. Most of what follows is about finishing the
+contract that the current code is already 80% of the way to, not redrawing
+it.**
+
+---
+
+## TL;DR
+
+| Change | Priority | Status | Why |
+|---|---|---|---|
+| Export all scripts, regardless of whether their owner node is emitted as a Question | **P1** | **Done** (`88b6989`) | The current emission filter drops the script-bearing nodes (`bind="none"` buttons, event-bearing draws, `<pageArea>` events) that renderers most need. This is the single largest fidelity gap. |
+| Surface event-bearing and `bind="none"` nodes via a parallel `Elements` collection | **P1** | Planned | Renderers need these nodes addressable in the schema; keeping them out of `Questions` preserves the "Question = thing a user answers" invariant. |
+| Parse and expose `<occur>` and `<bind>` metadata on Questions and Sections | **P1** | Planned | Without this, renderers can't tell which subforms are repeatable or what they bind to — i.e. can't implement dynamic XFA at all. |
+| Ship a SOM path parser + schema resolver as `forms/xfa/som` | **P2** | Draft | Single correct implementation everyone needs; co-located with the schema it operates on. |
+| Add data-DOM cursor API (`GetDataValue` / `SetDataValue` / `ListDataChildren` by SOM path) | **P2** | Draft | Current `UpdateXFAValues` is name-keyed and regex-based; renderers doing real binding need path-keyed access. |
+| Capture `<validate><script>` child elements as regular FormScripts | **P2** | Draft | Currently only the `scriptTest` attribute form is captured; the child-element form is not. |
+
+---
+
+## The scope principle
+
+Stated as plainly as possible, here's where the line should sit:
+
+> pdfer's XFA support extracts structure and surfaces logic; it does not
+> execute logic. Every `<script>` in the template is exposed verbatim with
+> stable identifiers and owner pointers. Every `<occur>` and `<bind>`
+> declaration is exposed as data. Every node that an authoring tool produced
+> is reachable from the schema. The runtime model — instance counts, presence
+> toggles, calculation order, script-driven UI changes — is the caller's
+> responsibility.
+>
+> The schema is a **projection of the template DOM**, not a snapshot of a Form
+> DOM. Callers building a renderer must implement merge themselves; callers
+> only round-tripping data values can use the dataset APIs and never touch the
+> template projection.
+
+If you state it that way, "should pdfer drop bind=none help buttons?" answers
+itself: no, because the renderer needs them addressable. And "should pdfer
+execute click scripts?" also answers itself: no, because that's the runtime
+layer.
+
+The current code is about 80% of the way to that statement being true. The
+remaining 20% is mostly removing emission filters that are doing the
+renderer's job, plus the metadata additions below.
+
+---
+
+## What's working well
+
+These are load-bearing pieces of the current design and should be preserved as
+the contract evolves.
+
+**Two-layer split.** Stream plumbing (`xfa.go`, `stream.go`, the translators)
+is cleanly separated from schema translation (`xfa_form_translator.go`).
+Callers who only want to patch dataset values don't have to pay for the
+template walk. Keep this separation.
+
+**Verbatim script bodies with stable SOM-keyed IDs.** This is the foundation
+that makes a downstream runtime possible at all. As long as bodies stay
+byte-identical to source and IDs stay stable across regenerations, consumers
+can compile, cache, and attach behavior without pdfer caring. The existing
+`TestFieldEventBodyPreservedVerbatim` invariant must remain inviolable as new
+code lands.
+
+**Flat-with-pointers schema shape.** `FormSchema.Questions` (flat) +
+`FormSchema.Sections` (hierarchical tree referencing question IDs) +
+`FormSchema.Scripts` (flat with owner pointers) is the right shape for a JS
+frontend. It's much friendlier than a deep object graph and scales when scripts
+have multiple owners.
+
+**Dataset round-trip via incremental update.** `UpdateXFAValues` touches only
+`<data>…</data>` and splices into the original PDF. Exporters want exactly
+this — pdfer is not in the business of regenerating template packets and
+shouldn't be.
+
+---
+
+## P1 — Required for a credible renderer
+
+### 1. Export all scripts, decoupled from question emission
+
+**Status: Done (commit `88b6989`).** `extractAllScripts` does a pre-pass over
+the template tree; `populateScriptBackRefs` fills in `OwnerID` when the owner
+is also a Question/Section and leaves orphans with empty `OwnerID`. Tests
+assert pageArea, bind=none button, event-bearing draw, and per-option
+exclGroup scripts all survive.
+
+The original problem statement and rationale are preserved below for reference.
+
+**Problem.** `attachFieldScripts` only runs inside `walkSubformChildren` for
+nodes that survived `emitField` / `emitDraw`. Any script attached to a filtered
+node is silently lost. Common XFA patterns silently disappeared from the
+schema as a result:
+- Help-text popup buttons (`bind="none"` buttons with a `click` script that
+  calls `xfa.host.messageBox` or toggles `presence` on a sibling)
+- Dynamic show/hide draws (event-bearing draws controlled by scripts)
+- Per-option click handlers on radio buttons collapsed into an `<exclGroup>`
+- Document-lifecycle events on `<pageArea>`
+
+**Fix (shipped).** Script extraction was split from question emission: a
+separate pre-pass over the template visits every `<field>`, `<draw>`,
+`<subform>`, `<exclGroup>`, `<pageArea>`, and `<variables>` and pulls their
+events into `FormSchema.Scripts`. Question emission then attaches IDs to the
+questions that exist. Scripts on filtered nodes appear in the flat list with
+`OwnerPath` set; their `OwnerID` is empty until §2 lands.
+
+**Follow-on (§2).** Once `FormSchema.Elements` exists, `OwnerID` will be
+populated to point at Element IDs for the orphan cases listed above —
+giving every script a typed owner reference.
+
+### 2. Surface event-bearing and `bind="none"` nodes via a parallel `Elements` collection
+
+**Problem.** `emitField` currently drops `bind="none"` button nodes as "UI
+trigger (Help Text, Show Intro, etc.)", with a hardcoded exception for
+`AddAttachment`. `emitDraw` drops any draw with `len(node.Events) > 0` as
+"dynamic." Renderers need these nodes to exist so they can render the
+buttons and attach the click handlers — and so the orphan scripts produced
+by §1 have a typed owner to point at.
+
+The current pattern of carving out exceptions case-by-case is not
+generalizable. The general rule should be: *if it has visual presence or
+events, it's part of the template — surface it.*
+
+**Fix.** Add a parallel collection on `FormSchema` for non-question template
+nodes:
+
+```go
+type FormSchema struct {
+    // ... existing fields
+    Elements []FormElement `json:"elements,omitempty"`
+}
+
+// FormElement represents a non-question template node with visual presence
+// or events — e.g. a bind="none" button, an event-bearing <draw>, or a
+// <pageArea>. Renderers that want full template fidelity iterate both
+// Questions and Elements; renderers that only render input controls iterate
+// Questions and ignore Elements.
+type FormElement struct {
+    ID         string                 `json:"id"`
+    OwnerPath  string                 `json:"owner_path"`           // SOM path
+    Role       string                 `json:"role"`                 // "button" | "draw" | "pageArea" | ...
+    Label      string                 `json:"label,omitempty"`      // caption / text content
+    Properties map[string]interface{} `json:"properties,omitempty"` // position, size, xfa_role, etc.
+    Scripts    []string               `json:"scripts,omitempty"`    // FormScript IDs, parallel to Question.Scripts
+}
+```
+
+`Question` stays semantically "thing a user answers" — renderers that iterate
+questions to render input controls don't have to special-case button or draw
+entries.
+
+When this lands, `FormScript.OwnerID` will be populated for owners in either
+collection. The existing `AddAttachment` special case in `emitField` can be
+removed in favor of treating all `bind="none"` buttons uniformly via
+`Elements`.
+
+### 3. Parse and expose `<occur>` and `<bind>` metadata
+
+**Problem.** This is the missing piece for any renderer that wants to do
+dynamic XFA. Currently:
+
+- `<occur>` is not parsed at all. Every repeating subform appears in the
+  schema exactly once. A "list of dependents" template that can grow to N
+  rows looks identical to a one-row form.
+- `<bind>` is read only to detect `match="none"`. The `ref` attribute and
+  other `match` values (`once`, `global`, `dataRef`) are ignored.
+
+**Fix.** Parse both elements and surface the data, without acting on it:
+
+```go
+// Occur reflects the template's declared cardinality. The actual number of
+// instances in a filled form is determined by the data DOM and is the
+// runtime's responsibility to materialize — the schema lists each repeating
+// subform exactly once regardless of how many instances the dataset carries.
+type Occur struct {
+    Min     int
+    Max     int // -1 for unbounded
+    Initial int
+}
+
+type Bind struct {
+    Match string // "once" | "global" | "none" | "dataRef" | ...
+    Ref   string // SOM path when match="dataRef"
+}
+```
+
+Add `Occur *Occur` and `Bind *Bind` to both `FormSection` and `Question`.
+Renderers use this to decide which subforms get an "add another" button and
+which data nodes a question reads/writes to.
+
+pdfer doesn't have to merge, expand instances, or pre-bind. It just hands the
+renderer what the template said.
+
+---
+
+## P2 — Substantially improves the contract
+
+These items are draft proposals — the shapes below are starting points, not
+committed designs. Worth thinking through before implementation.
+
+### 4. SOM path parser and schema resolver (`forms/xfa/som`)
+
+**Why it belongs here.** The test for "is this scope creep?" is whether the
+thing has a single correct implementation that every consumer needs, or
+whether it has policy choices different consumers will make differently. SOM
+resolution is the first kind — the grammar is specified by Adobe, and walking
+dots, resolving `..`, expanding `[n]` indices, distinguishing single-match
+from multi-match all have right answers. If pdfer doesn't ship it, every
+consumer writes the same code and gets subtle edge cases wrong.
+
+It also pairs naturally with things pdfer already exposes — `OwnerPath` is a
+SOM-style path, the dataset round-trip needs to address data nodes by path,
+and the bind/occur metadata above presupposes that consumers can resolve
+paths. The alternative is making pdfer's path format a de-facto public API
+without owning it.
+
+**Scope boundary.** Three things people call "the SOM resolver":
+
+1. **Path parser** — string → structured representation. Belongs in pdfer.
+2. **Schema resolver** — parsed path + schema (+ optional context) → matching
+   `Question` / `FormSection` / `FormElement` / data node. Belongs in pdfer.
+3. **Expression evaluator** — parsing FormCalc or JS source to extract SOM
+   literals from script bodies. **Does not belong in pdfer.**
+
+The trap is that #2 shades into #3 if you're not careful. Consumer hands you
+a script body, asks "what node does this reference?" — and now you're parsing
+JS. Don't. pdfer's resolver takes a path *string* that the caller has already
+extracted. Pattern-matching `xfa.resolveNode("X")` calls out of script source
+is the caller's job.
+
+**Suggested API shape:**
+
+```go
+package som
+
+func Parse(expr string) (Path, error)
+
+func Resolve(schema *types.FormSchema, expr string, ctx *types.Question) ([]Resolved, error)
+func ResolveOne(schema *types.FormSchema, expr string, ctx *types.Question) (Resolved, error)
+```
+
+Document explicitly: *operates on SOM expression strings, not on script
+bodies.*
+
+### 5. Data-DOM cursor API
+
+**Problem.** `UpdateXFAValues` is keyed by flat field name and uses regex to
+find/replace inside `<data>`. This is fine for simple flat datasets but
+doesn't handle nested data nodes well, can't address repeating instances, and
+forces every consumer into the same name-based model.
+
+**Fix.** Add SOM-path-keyed accessors to complement the existing flat-map API:
+
+```go
+func GetDataValue(datasetsXML []byte, somPath string) (string, bool, error)
+func SetDataValue(datasetsXML []byte, somPath, value string) ([]byte, error)
+func ListDataChildren(datasetsXML []byte, somPath string) ([]string, error)
+```
+
+These build on the existing `<datasets>` parse. Anything above this level
+(which question a given data node corresponds to) is the SOM resolver's job,
+not the data API's.
+
+**Open question.** Relationship to the existing name-keyed `UpdateXFAValues`:
+either (a) migrate callers to the SOM-keyed API and remove the name-keyed
+one, or (b) position the name-keyed API as a documented convenience layer
+over the path-keyed core. Decide before shipping — two coexisting APIs with
+no documented relationship is the worst outcome.
+
+### 6. Capture `<validate><script>` child elements
+
+**Problem.** `ValidationRules.CustomScript` captures the `scriptTest`
+attribute string. But `<validate>` can also contain a `<script>` child with
+its own `contentType`. The child-element form appears to be uncaptured.
+
+**Fix.** Treat the child-element form the same as any other event — its body
+appears in `FormSchema.Scripts` with `Event: "validate"`. The attribute form
+can stay where it is or be normalized into the same shape.
+
+---
+
+## What I would *not* add
+
+To keep the scope boundary sharp, these are things that have come up in
+discussion and that pdfer should explicitly leave to consumers:
+
+- **Script execution.** Not FormCalc, not JavaScript, not a sandboxed subset.
+  This is the runtime layer. Consumers ship their own interpreter.
+- **Merge algorithm.** Walking the template against the data DOM to produce a
+  Form DOM with the right occurrence counts. This is the runtime layer.
+- **Instance management.** `addInstance` / `removeInstance` / `setInstances`
+  semantics on repeating subforms. Runtime layer.
+- **Calculate dependency tracking.** Figuring out which scripts to re-run when
+  a field changes. Runtime layer.
+- **Layout engine.** Computing actual page positions from `x`/`y`/`w`/`h` plus
+  layout mode plus content reflow. Renderers do this in CSS or canvas.
+- **Script-body parsing.** Extracting SOM literals or method calls from
+  FormCalc / JS source. The caller pattern-matches if they need to.
+
+These all share a property: they require either (a) a language interpreter or
+(b) a runtime mutable state model that doesn't belong in a parsing library.
+The verbatim-script-body invariant gives consumers everything they need to
+build these themselves.
+
+---
+
+## Suggested order of work
+
+1. **§2 (`Elements` collection).** Surfaces non-question template nodes and
+   lets `FormScript.OwnerID` resolve for the orphan cases §1 created.
+2. **§3 (`<occur>` and `<bind>` metadata).** Pure data extraction, low risk,
+   immediately unlocks dynamic-XFA renderers.
+3. **§4 (SOM resolver).** Largest piece of new code, but bounded scope and
+   no dependencies on the prior changes.
+4. **§5 (data-DOM cursor API).** Builds on the SOM resolver.
+5. **§6 (`<validate><script>` capture).** Small, isolated.
+
+After §2 and §3, downstream renderers have the information they need to do
+real dynamic XFA. §1 is already done.

From e72db4dcb6f92bd7ce4e8233107ab8ee0efbe15a Mon Sep 17 00:00:00 2001
From: Logan Stokols <LFStokols@gmail.com>
Date: Mon, 25 May 2026 23:40:50 -0400
Subject: [PATCH 3/3] refactor(xfa): tighten per-option SOM paths and orphan
 signal docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-up polish on 88b6989 from a self-review pass.

- Per-option script OwnerPath now keys off the option <field>'s name
  attribute (e.g. "group.optA") rather than the option's data value,
  which can contain arbitrary text from <items>. Adds OptionFieldNames
  parallel slice on xfaNode, populated during the exclGroup flatten.
  The resulting path is a real, SOM-resolvable expression.

- populateScriptBackRefs collapsed to a single pass over Questions: a
  preceding section walk records each question's containing section
  path; the question pass then computes the full SOM path and calls
  assign. The previous covered-map / two-pass split is gone.

- New TestNestedSubformFieldBackRef puts a field event three subforms
  deep and asserts both OwnerID and Question.Scripts resolve through
  the nested sections — locks in that the path built by
  extractAllScripts matches the one built by populateScriptBackRefs at
  arbitrary nesting depth.

- TestExclGroupOptionScriptsExtracted updated to use field names
  (optA/optB) distinct from option values (a/b), with a negative
  assertion that the old value-keyed path does NOT appear.

- FormScript doc comment and docs/design/xfa-scope.md §1 reframed
  around the stability contract: OwnerID empty means "owner is not
  currently surfaced as a typed schema entity." That signal is stable
  in meaning even as §2 expands the set of typed entities (Elements,
  etc.) — what shrinks is the orphan set, which is the direction
  audit-style consumers want anyway. The previous enumeration of four
  orphan cases read like a permanent classification.
---
 docs/design/xfa-scope.md                | 12 ++++
 forms/xfa/xfa_form_translator.go        | 67 +++++++++++-----------
 forms/xfa/xfa_script_extraction_test.go | 74 +++++++++++++++++++++++--
 types/form_types.go                     | 13 +++--
 4 files changed, 125 insertions(+), 41 deletions(-)

diff --git a/docs/design/xfa-scope.md b/docs/design/xfa-scope.md
index 58ebc03..f02e391 100644
--- a/docs/design/xfa-scope.md
+++ b/docs/design/xfa-scope.md
@@ -123,6 +123,18 @@ questions that exist. Scripts on filtered nodes appear in the flat list with
 populated to point at Element IDs for the orphan cases listed above —
 giving every script a typed owner reference.
 
+**Stability contract for orphan signaling.** The set of "orphan" scripts
+(`OwnerID == ""`) is *expected to shrink* as `FormSchema.Elements` and
+further typed collections land. The semantic of the empty-`OwnerID` signal
+is stable — "the owner is not currently a typed entity in this schema" —
+but the *enumeration* of orphan cases is not. Consumers that audit orphans
+(e.g. "scripts I cannot attach to anything I render") will see their orphan
+set get smaller over time, which is the intended direction; consumers that
+hard-code today's four orphan cases as a permanent classification will
+break. `FormScript`'s doc comment captures this; callers should treat
+`OwnerID != ""` as "dereferenceable by ID in some typed collection" without
+caring which one.
+
 ### 2. Surface event-bearing and `bind="none"` nodes via a parallel `Elements` collection
 
 **Problem.** `emitField` currently drops `bind="none"` button nodes as "UI
diff --git a/forms/xfa/xfa_form_translator.go b/forms/xfa/xfa_form_translator.go
index 0a9b24d..10c1182 100644
--- a/forms/xfa/xfa_form_translator.go
+++ b/forms/xfa/xfa_form_translator.go
@@ -426,6 +426,12 @@ type xfaNode struct {
 	// can still be surfaced as FormScripts.
 	OptionEvents [][]XFAEvent
 
+	// OptionFieldNames is parallel to Options on exclGroup nodes: the SOM-addressable
+	// name attribute of each flattened option <field>. Used to build the per-option
+	// script OwnerPath as "group.fieldName" (real SOM), independent of the option's
+	// data value (which may contain arbitrary text from <items>).
+	OptionFieldNames []string
+
 	// UI-element-specific constraints
 	AllowNeutral          bool   // checkButton allowNeutral="1" → tri-state checkbox
 	MaxChars              *int   // textEdit maxChars → ValidationRules.MaxLength
@@ -1156,9 +1162,11 @@ func parseXFATemplate(xfaXML string, verbose bool) (*xfaTemplateResult, error) {
 							optValue = currentLeaf.Name
 						}
 						top.Options = append(top.Options, XFAOption{Label: optLabel, Value: optValue})
-						// Preserve per-option events (parallel slice) so they can still
-						// surface as FormScripts even though the option <field> is flattened.
+						// Preserve per-option events and the field's SOM-addressable name
+						// (parallel slices) so they can still surface as FormScripts with
+						// a real SOM OwnerPath even though the option <field> is flattened.
 						top.OptionEvents = append(top.OptionEvents, currentLeaf.Events)
+						top.OptionFieldNames = append(top.OptionFieldNames, currentLeaf.Name)
 						// draws inside exclGroup are decorative labels — fall through and discard
 					} else if top.Kind != xfaKindExclGroup {
 						top.Children = append(top.Children, currentLeaf)
@@ -1518,20 +1526,26 @@ func extractAllScripts(root *xfaNode, schema *types.FormSchema) {
 			schema.Scripts = append(schema.Scripts, buildFormScripts(node.Events, somPath, "")...)
 		}
 
-		// Per-option events on exclGroup — Options and OptionEvents are parallel
-		// slices populated when child <field>s are flattened into the group.
+		// Per-option events on exclGroup — OptionEvents and OptionFieldNames are
+		// parallel slices populated when child <field>s are flattened into the
+		// group. The field's name is the SOM-addressable identifier ("group.optA"),
+		// independent of the option's data value (which may contain arbitrary
+		// text from <items>).
 		if node.Kind == xfaKindExclGroup {
 			for i, optEvents := range node.OptionEvents {
-				if i >= len(node.Options) || len(optEvents) == 0 {
+				if len(optEvents) == 0 {
 					continue
 				}
-				optPath := somPath
-				if v := node.Options[i].Value; v != "" {
-					if optPath == "" {
-						optPath = v
-					} else {
-						optPath = optPath + "." + v
-					}
+				fieldName := ""
+				if i < len(node.OptionFieldNames) {
+					fieldName = node.OptionFieldNames[i]
+				}
+				if fieldName == "" {
+					continue
+				}
+				optPath := fieldName
+				if somPath != "" {
+					optPath = somPath + "." + fieldName
 				}
 				schema.Scripts = append(schema.Scripts, buildFormScripts(optEvents, optPath, "")...)
 			}
@@ -1562,11 +1576,6 @@ func populateScriptBackRefs(schema *types.FormSchema) {
 	if len(byPath) == 0 {
 		return
 	}
-	qByID := make(map[string]*types.Question, len(schema.Questions))
-	for i := range schema.Questions {
-		qByID[schema.Questions[i].ID] = &schema.Questions[i]
-	}
-	covered := make(map[string]bool)
 
 	assign := func(ownerPath, ownerID string) []string {
 		idxs, ok := byPath[ownerPath]
@@ -1581,35 +1590,31 @@ func populateScriptBackRefs(schema *types.FormSchema) {
 		return ids
 	}
 
+	// First, assign section-owned scripts and record each question's containing
+	// section path so the question pass can compute its full SOM path.
+	qSectionPath := make(map[string]string, len(schema.Questions))
 	var walkSections func([]types.FormSection)
 	walkSections = func(secs []types.FormSection) {
 		for i := range secs {
 			sec := &secs[i]
 			sec.Scripts = assign(sec.Path, sec.Path)
 			for _, qID := range sec.Questions {
-				q := qByID[qID]
-				if q == nil {
-					continue
-				}
-				covered[qID] = true
-				somPath := q.Name
-				if sec.Path != "" {
-					somPath = sec.Path + "." + q.Name
-				}
-				q.Scripts = assign(somPath, q.ID)
+				qSectionPath[qID] = sec.Path
 			}
 			walkSections(sec.Children)
 		}
 	}
 	walkSections(schema.Sections)
 
-	// Root-level questions (no enclosing section) — their SOM path is just Name.
+	// Single pass over questions: full SOM path = sectionPath + "." + Name,
+	// or just Name for questions not enclosed in any section.
 	for i := range schema.Questions {
 		q := &schema.Questions[i]
-		if covered[q.ID] {
-			continue
+		somPath := q.Name
+		if sp := qSectionPath[q.ID]; sp != "" {
+			somPath = sp + "." + q.Name
 		}
-		q.Scripts = assign(q.Name, q.ID)
+		q.Scripts = assign(somPath, q.ID)
 	}
 }
 
diff --git a/forms/xfa/xfa_script_extraction_test.go b/forms/xfa/xfa_script_extraction_test.go
index 317a872..db544e5 100644
--- a/forms/xfa/xfa_script_extraction_test.go
+++ b/forms/xfa/xfa_script_extraction_test.go
@@ -512,9 +512,14 @@ func TestDrawEventScriptExtracted(t *testing.T) {
 // TestExclGroupOptionScriptsExtracted verifies that per-option <event>
 // blocks (defined on the individual radio-option <field>s inside an
 // <exclGroup>) are preserved as distinct FormScripts. Each option's script
-// must have its own OwnerPath (exclGroup SOM path + "." + option value) and
-// remain an orphan, while the exclGroup itself (which IS a Question) gets
+// must have its own OwnerPath (exclGroup SOM path + "." + option field name)
+// and remain an orphan, while the exclGroup itself (which IS a Question) gets
 // its own script back-ref via the standard Question.Scripts mechanism.
+//
+// The field <items> values ("a", "b") deliberately differ from the field
+// names ("optA", "optB") to assert that the SOM OwnerPath is keyed by the
+// field's name (real SOM) rather than the option's data value (which can
+// contain arbitrary text).
 func TestExclGroupOptionScriptsExtracted(t *testing.T) {
 	bodyA := `xfa.host.messageBox("A selected");`
 	bodyB := `xfa.host.messageBox("B selected");`
@@ -571,9 +576,9 @@ func TestExclGroupOptionScriptsExtracted(t *testing.T) {
 		t.Errorf("group OwnerID = %q, want question ID %q", groupScript.OwnerID, choiceQ.ID)
 	}
 
-	scriptA := findScript(form.Scripts, "Page1.choice.a", "click")
+	scriptA := findScript(form.Scripts, "Page1.choice.optA", "click")
 	if scriptA == nil {
-		t.Fatalf("no per-option script with OwnerPath=Page1.choice.a; got %+v", form.Scripts)
+		t.Fatalf("no per-option script with OwnerPath=Page1.choice.optA; got %+v", form.Scripts)
 	}
 	if scriptA.Body != bodyA {
 		t.Errorf("option A body = %q, want %q", scriptA.Body, bodyA)
@@ -582,9 +587,9 @@ func TestExclGroupOptionScriptsExtracted(t *testing.T) {
 		t.Errorf("option A OwnerID = %q, want empty (orphan)", scriptA.OwnerID)
 	}
 
-	scriptB := findScript(form.Scripts, "Page1.choice.b", "click")
+	scriptB := findScript(form.Scripts, "Page1.choice.optB", "click")
 	if scriptB == nil {
-		t.Fatalf("no per-option script with OwnerPath=Page1.choice.b; got %+v", form.Scripts)
+		t.Fatalf("no per-option script with OwnerPath=Page1.choice.optB; got %+v", form.Scripts)
 	}
 	if scriptB.Body != bodyB {
 		t.Errorf("option B body = %q, want %q", scriptB.Body, bodyB)
@@ -592,4 +597,61 @@ func TestExclGroupOptionScriptsExtracted(t *testing.T) {
 	if scriptB.OwnerID != "" {
 		t.Errorf("option B OwnerID = %q, want empty (orphan)", scriptB.OwnerID)
 	}
+
+	// Negative assertion: the OLD path (keyed by option <items> value) must
+	// NOT appear, to lock in the SOM-correct field-name keying.
+	if s := findScript(form.Scripts, "Page1.choice.a", "click"); s != nil {
+		t.Errorf("per-option script should NOT use option value as path key; got %+v", s)
+	}
+}
+
+// TestNestedSubformFieldBackRef verifies that a field inside a deeply nested
+// subform gets its Question.Scripts back-reference populated, and the script's
+// OwnerID resolves to the Question.ID. Specifically locks in that the SOM
+// path computed by extractAllScripts (parent walk of named nodes) matches the
+// path computed by populateScriptBackRefs (sec.Path + "." + q.Name) for
+// arbitrary nesting depth.
+func TestNestedSubformFieldBackRef(t *testing.T) {
+	body := `xfa.host.messageBox("deep");`
+	xfaXML := `<template>
+  <subform name="form1">
+    <subform name="outer">
+      <subform name="inner">
+        <field name="deepField">
+          <ui><textEdit/></ui>
+          <event activity="change">
+            <script contentType="application/x-javascript">` + body + `</script>
+          </event>
+        </field>
+      </subform>
+    </subform>
+  </subform>
+</template>`
+
+	form, err := ParseXFAForm(xfaXML, false)
+	if err != nil {
+		t.Fatalf("ParseXFAForm() error = %v", err)
+	}
+
+	var deepQ *types.Question
+	for i := range form.Questions {
+		if form.Questions[i].Name == "deepField" {
+			deepQ = &form.Questions[i]
+		}
+	}
+	if deepQ == nil {
+		t.Fatalf("deepField question missing; got %+v", form.Questions)
+	}
+
+	wantPath := "form1.outer.inner.deepField"
+	s := findScript(form.Scripts, wantPath, "change")
+	if s == nil {
+		t.Fatalf("no script with OwnerPath=%s; got %+v", wantPath, form.Scripts)
+	}
+	if s.OwnerID != deepQ.ID {
+		t.Errorf("OwnerID = %q, want question ID %q (back-ref must resolve through nested sections)", s.OwnerID, deepQ.ID)
+	}
+	if len(deepQ.Scripts) != 1 || deepQ.Scripts[0] != s.ID {
+		t.Errorf("Question.Scripts = %v, want [%q]", deepQ.Scripts, s.ID)
+	}
 }
diff --git a/types/form_types.go b/types/form_types.go
index 5319ec9..062083d 100644
--- a/types/form_types.go
+++ b/types/form_types.go
@@ -100,11 +100,16 @@ type ValidationRules struct {
 // FormScript represents a raw script block extracted from an XFA form.
 // Bodies are exposed verbatim — pdfer does not interpret script semantics.
 //
-// Scripts whose owner node is not emitted as a Question or FormSection (e.g.
+// OwnerID is non-empty iff the owning node is surfaced as a typed schema
+// entity (today: Question or FormSection) that callers can dereference by ID.
+// Scripts whose owner is not currently typed in the schema appear with
+// OwnerPath set and OwnerID empty — at time of writing, these include
 // event-bearing <draw> elements, bind="none" non-AddAttachment buttons,
-// <pageArea> events, individual radio options collapsed into an <exclGroup>)
-// appear here with OwnerPath set and OwnerID empty. Callers that need to
-// correlate orphan scripts must inspect OwnerPath directly.
+// <pageArea> events, and individual radio options collapsed into an
+// <exclGroup>. The set of orphan cases will shrink as more node types become
+// typed (see docs/design/xfa-scope.md §2). Callers should treat OwnerID empty
+// as "not currently dereferenceable" rather than a permanent classification,
+// and rely on OwnerPath when they need owner-keyed addressing in either case.
 type FormScript struct {
 	ID         string                 `json:"id"`                   // stable: SOM owner path + "#" + event + "[" + index + "]"
 	OwnerPath  string                 `json:"owner_path,omitempty"` // SOM path of containing node (e.g. "form1.section.field"); empty for template-level