From bec0d2f215b5b664e9919960e7c6f401a39dee28 Mon Sep 17 00:00:00 2001
From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com>
Date: Fri, 23 Oct 2026 12:16:00 -0400
Subject: [PATCH 1/4] fix(demo): never label a PDF field with its raw name when
 labels repeat (#593)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 public/demo.html                |   23 +-
 test/demo-pdf-form.test.ts      |   28 +-
 test/fixtures/sc100-fields.json | 1078 +++++++++++++++++++++++++++++++
 3 files changed, 1121 insertions(+), 8 deletions(-)
 create mode 100644 test/fixtures/sc100-fields.json

diff --git a/public/demo.html b/public/demo.html
index 397fa3a1..5fb4d8f7 100644
--- a/public/demo.html
+++ b/public/demo.html
@@ -453,15 +453,26 @@ <h2 class="visually-hidden">About</h2>
         .replace(/^./, (c) => c.toUpperCase());
       const xfa = (n) => (/\[\d+\]/.test(n) ? words(n.split('.').pop().replace(/\[\d+\]/g, '')) : '');
       const named = (f) => (typeof f.label === 'string' && f.label.trim()) || (f.created ? words(f.name) : xfa(f.name) || f.name);
-      // Two fields must not read the same: a repeat gets its page, and if that still
-      // repeats, its full name.
+      // Two fields must not read the same, and none may read as its raw name (#593: SC-100's
+      // page 2 has four fields labelled "city"). A repeat is read from its name instead
+      // (`Plaintiff mailing city 1`), then given its page, then more of its name, then a number.
       const shown = fields.filter((f) => !f.readonly);
       const count = (xs) => xs.reduce((m, s) => m.set(s, (m.get(s) || 0) + 1), new Map());
+      const tail = (f, k) => words(f.name.split('.').map((p) => p.replace(/\[\d+\]/g, '')).filter(Boolean).slice(-k).join(' '));
+      const page = (f) => (f.page ? ` (page ${f.page})` : '');
       let texts = shown.map(named);
-      let seen = count(texts);
-      texts = texts.map((s, i) => (seen.get(s) > 1 && shown[i].page ? `${s} (page ${shown[i].page})` : s));
-      seen = count(texts);
-      texts = texts.map((s, i) => (seen.get(s) > 1 ? shown[i].name : s));
+      const retell = (to) => {
+        const seen = count(texts);
+        texts = texts.map((s, i) => (seen.get(s) > 1 ? to(shown[i], s) : s));
+      };
+      retell((f, s) => tail(f, 1) || s);
+      retell((f, s) => s + page(f));
+      for (let k = 2; k <= 4; k++) retell((f, s) => tail(f, k) + page(f) || s);
+      const nth = new Map();
+      retell((f, s) => {
+        nth.set(s, (nth.get(s) || 0) + 1);
+        return `${s} (${nth.get(s)})`;
+      });
       const text = new Map(shown.map((f, i) => [f, texts[i]]));
       const label = (f) => text.get(f) + req(f);
       let n = 0;
diff --git a/test/demo-pdf-form.test.ts b/test/demo-pdf-form.test.ts
index 2559ef8e..385fee03 100644
--- a/test/demo-pdf-form.test.ts
+++ b/test/demo-pdf-form.test.ts
@@ -106,11 +106,35 @@ test("an acronym keeps its capitals, and two fields that would read the same are
     "DOB field",
     "Case number (page 1)",
     "Case number (page 2)",
-    "F[0].P2[0].A[0].Name[0]",
-    "F[0].P2[0].B[0].Name[0]",
+    "A name (page 2)",
+    "B name (page 2)",
   ]);
 });
 
+test("no label on SC-100's real form is a raw name or a repeat (#593)", () => {
+  // The field list iris-pdf returned for SC-100 on UIC: page 2 labels four fields "city".
+  const fields = JSON.parse(readFileSync(join(repoRoot, "test", "fixtures", "sc100-fields.json"), "utf8")) as Field[];
+  const doc = new JSDOM('<!DOCTYPE html><html lang="en"><head><title>t</title></head><body><form id="f"></form></body></html>').window.document;
+  const list = doc.getElementById("f")!;
+  assert.equal(renderFields(doc, list, fields), 95);
+  // Each control's own label: a text box's <label>, or a choice's <legend> (not its options').
+  const labels = [...list.querySelectorAll("label:not(.choice label), legend")].map((l) => l.textContent!);
+  assert.equal(labels.length, 95);
+  assert.deepEqual(labels.filter((t) => /\[\d+\]/.test(t)), []);
+  assert.equal(new Set(labels).size, labels.length);
+  assert.ok(labels.includes("Plaintiff mailing city 1"));
+});
+
+test("fields that read the same through their whole name are numbered", () => {
+  const doc = new JSDOM('<!DOCTYPE html><html lang="en"><head><title>t</title></head><body><form id="f"></form></body></html>').window.document;
+  const list = doc.getElementById("f")!;
+  renderFields(doc, list, [
+    { name: "F[0].Name[0]", type: "text", options: [], label: "Name" },
+    { name: "F[1].Name[0]", type: "text", options: [], label: "Name" },
+  ] as Field[]);
+  assert.deepEqual([...list.querySelectorAll("label")].map((l) => l.textContent), ["F name (1)", "F name (2)"]);
+});
+
 test("an untouched form sends nothing, so the PDF keeps what it had", () => {
   assert.deepEqual(fieldValues(form().list), {});
 });
diff --git a/test/fixtures/sc100-fields.json b/test/fixtures/sc100-fields.json
new file mode 100644
index 00000000..b24f1066
--- /dev/null
+++ b/test/fixtures/sc100-fields.json
@@ -0,0 +1,1078 @@
+[
+  {
+    "name": "SC-100[0].Page1[0].CaptionRight[0].County[0].CourtInfo[0]",
+    "type": "text",
+    "options": [],
+    "label": "Superior Court of California, County of",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page1[0].CaptionRight[0].CN[0].CaseNumber[0]",
+    "type": "text",
+    "options": [],
+    "label": "Case Number",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page1[0].CaptionRight[0].CN[0].CaseName[0]",
+    "type": "text",
+    "options": [],
+    "label": "Case Name",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page1[0].Order[0].List1[0].LI1[0].TrialDate1[0]",
+    "type": "text",
+    "options": [],
+    "label": "Trial date 1",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page1[0].Order[0].List1[0].LI1[0].TrialTime1[0]",
+    "type": "text",
+    "options": [],
+    "label": "Trial time 1",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page1[0].Order[0].List1[0].LI1[0].TrialDepartment1[0]",
+    "type": "text",
+    "options": [],
+    "label": "Trial department 1",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page1[0].Order[0].List1[0].LI1[0].TrialDateCourtAdd1[0]",
+    "type": "text",
+    "options": [],
+    "label": "Trial Court address 1, if different from above",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page1[0].Order[0].List1[0].LI2[0].TrialDate2[0]",
+    "type": "text",
+    "options": [],
+    "label": "Trial date 2",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page1[0].Order[0].List1[0].LI2[0].TrialTime2[0]",
+    "type": "text",
+    "options": [],
+    "label": "Trial time 2",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page1[0].Order[0].List1[0].LI2[0].TrialDepartment2[0]",
+    "type": "text",
+    "options": [],
+    "label": "Trial department 2",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page1[0].Order[0].List1[0].LI2[0].TrialDateCourtAdd2[0]",
+    "type": "text",
+    "options": [],
+    "label": "Trial Court address 2, if different from above",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page1[0].Order[0].List1[0].LI3[0].TrialDate3[0]",
+    "type": "text",
+    "options": [],
+    "label": "Trial date 3",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page1[0].Order[0].List1[0].LI3[0].TrialTIme3[0]",
+    "type": "text",
+    "options": [],
+    "label": "Trial time 3",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page1[0].Order[0].List1[0].LI3[0].TrialDepartment3[0]",
+    "type": "text",
+    "options": [],
+    "label": "Trial department 3",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page1[0].Order[0].List1[0].LI3[0].TrialDateCourtAdd3[0]",
+    "type": "text",
+    "options": [],
+    "label": "Trial Court address 3 if different from above",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page1[0].Order[0].List1[0].LI3[0].TrialDateClerkSignDate[0]",
+    "type": "text",
+    "options": [],
+    "label": "Date",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page1[0].Order[0].List1[0].LI3[0].TrialDateClerkSign[0]",
+    "type": "text",
+    "options": [],
+    "label": "Clerk, by",
+    "page": 1,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].PxCaption[0].Plaintiff[0]",
+    "type": "text",
+    "options": [],
+    "label": "Plaintiff list names",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].PxCaption[0].CaseNumber[0]",
+    "type": "text",
+    "options": [],
+    "label": "Case Number",
+    "page": 2,
+    "readonly": true,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffName1[0]",
+    "type": "text",
+    "options": [],
+    "label": "Name",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffPhone1[0]",
+    "type": "text",
+    "options": [],
+    "label": "Phone",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffAddress1[0]",
+    "type": "text",
+    "options": [],
+    "label": "Plaintiff street address",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffCity1[0]",
+    "type": "text",
+    "options": [],
+    "label": "city",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffState1[0]",
+    "type": "text",
+    "options": [],
+    "label": "state",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffZip1[0]",
+    "type": "text",
+    "options": [],
+    "label": "zip",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffMailingAddress1[0]",
+    "type": "text",
+    "options": [],
+    "label": "mailing address if different street",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffMailingCity1[0]",
+    "type": "text",
+    "options": [],
+    "label": "city",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffMailingState1[0]",
+    "type": "text",
+    "options": [],
+    "label": "state",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffMailingZip1[0]",
+    "type": "text",
+    "options": [],
+    "label": "zip",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].EmailAdd1[0]",
+    "type": "text",
+    "options": [],
+    "label": "email address if available",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffName2[0]",
+    "type": "text",
+    "options": [],
+    "label": "name",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffPhone2[0]",
+    "type": "text",
+    "options": [],
+    "label": "phone",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffAddress2[0]",
+    "type": "text",
+    "options": [],
+    "label": "street address",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffCity2[0]",
+    "type": "text",
+    "options": [],
+    "label": "city",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffState2[0]",
+    "type": "text",
+    "options": [],
+    "label": "state",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffZip2[0]",
+    "type": "text",
+    "options": [],
+    "label": "zip",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffMailingAddress2[0]",
+    "type": "text",
+    "options": [],
+    "label": "mailing address if different street",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffMailingCity2[0]",
+    "type": "text",
+    "options": [],
+    "label": "city",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffMailingState2[0]",
+    "type": "text",
+    "options": [],
+    "label": "state",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].PlaintiffMailingZip2[0]",
+    "type": "text",
+    "options": [],
+    "label": "zip",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].EmailAdd2[0]",
+    "type": "text",
+    "options": [],
+    "label": "email address if available",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].Checkbox1[0]",
+    "type": "checkbox",
+    "options": [
+      "1"
+    ],
+    "label": "Check here if more than two plaintiffs and attach form SC-100A.",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].Checkbox2[0]",
+    "type": "checkbox",
+    "options": [
+      "1"
+    ],
+    "label": "Check here if either plaintiff listed above is doing business under a fictitious name and attach form SC-103.",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List1[0].Item1[0].Checkbox3[0]",
+    "type": "checkbox",
+    "options": [
+      "1"
+    ],
+    "label": "Check here if any plaintiff is a “licensee” or “deferred deposit originator” (payday lender) under Financial Code sections 23000 et seq.",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].DefendantName1[0]",
+    "type": "text",
+    "options": [],
+    "label": "defendant name",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].DefendantPhone1[0]",
+    "type": "text",
+    "options": [],
+    "label": "phone",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].DefendantAddress1[0]",
+    "type": "text",
+    "options": [],
+    "label": "street address",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].DefendantCity1[0]",
+    "type": "text",
+    "options": [],
+    "label": "city",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].DefendantState1[0]",
+    "type": "text",
+    "options": [],
+    "label": "state",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].DefendantZip1[0]",
+    "type": "text",
+    "options": [],
+    "label": "zip",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].DefendantMailingAddress1[0]",
+    "type": "text",
+    "options": [],
+    "label": "mailing address if different street",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].DefendantMailingCity1[0]",
+    "type": "text",
+    "options": [],
+    "label": "city",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].DefendantMailingState1[0]",
+    "type": "text",
+    "options": [],
+    "label": "state",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].DefendantMailingZip1[0]",
+    "type": "text",
+    "options": [],
+    "label": "zip",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].DefendantName2[0]",
+    "type": "text",
+    "options": [],
+    "label": "name",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].DefendantJob1[0]",
+    "type": "text",
+    "options": [],
+    "label": "job title if known",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].DefendantAddress2[0]",
+    "type": "text",
+    "options": [],
+    "label": "street",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].DefendantCity2[0]",
+    "type": "text",
+    "options": [],
+    "label": "city",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].DefendantState2[0]",
+    "type": "text",
+    "options": [],
+    "label": "state",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].DefendantZip2[0]",
+    "type": "text",
+    "options": [],
+    "label": "zip",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].Checkbox4[0]",
+    "type": "checkbox",
+    "options": [
+      "1"
+    ],
+    "label": "Check here if your case is against more than one defendant and attach form SC-100A.",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List2[0].item2[0].Checkbox5[0]",
+    "type": "checkbox",
+    "options": [
+      "1"
+    ],
+    "label": "Check here if any defendant is on active military duty and write defendant’s name here:",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List3[0].PlaintiffClaimAmount1[0]",
+    "type": "text",
+    "options": [],
+    "label": "The plaintiff claims the defendant owes",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page2[0].List3[0].Lia[0].FillField2[0]",
+    "type": "text",
+    "options": [],
+    "label": "Why does the defendant owe the plaintiff money?",
+    "page": 2,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].PxCaption[0].Plaintiff[0]",
+    "type": "text",
+    "options": [],
+    "label": "Plintiff (list names)",
+    "page": 3,
+    "readonly": true,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].PxCaption[0].CaseNumber[0]",
+    "type": "text",
+    "options": [],
+    "label": "Case number",
+    "page": 3,
+    "readonly": true,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List3[0].Lib[0].Date1[0]",
+    "type": "text",
+    "options": [],
+    "label": "When did this happen? Date",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List3[0].Lib[0].Date2[0]",
+    "type": "text",
+    "options": [],
+    "label": "Date started",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List3[0].Lib[0].Date3[0]",
+    "type": "text",
+    "options": [],
+    "label": "through",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List3[0].Lic[0].FillField1[0]",
+    "type": "text",
+    "options": [],
+    "label": "How did you calculate the money owed to you? (Do not include court costs or fees for service.)",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List3[0].Checkbox1[0]",
+    "type": "checkbox",
+    "options": [
+      "1"
+    ],
+    "label": "Check here if you need more space. Attach one sheet of paper or form MC-031 and write “SC-100, Item 3” at the top.",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List4[0].Item4[0].FillField2[0]",
+    "type": "text",
+    "options": [],
+    "label": "You must ask the defendant (in person, in writing, or by phone) to pay you before you sue. If your claim is for possession of property, you must ask the defendant to give you the property. Have you done this? If no, explain why not:",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List4[0].Item4[0].Checkbox50[0]",
+    "type": "checkbox",
+    "options": [
+      "1"
+    ],
+    "label": "Check if you asked defendant to pay before you sue",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List4[0].Item4[0].Checkbox50[1]",
+    "type": "checkbox",
+    "options": [
+      "2"
+    ],
+    "label": "Check if you did not ask defendant to pay before you sue",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List5[0].Lia[0].Checkbox5cb[0]",
+    "type": "checkbox",
+    "options": [
+      "1"
+    ],
+    "label": "(1) Where the defendant lives or does business. \r(2) Where the plaintiff’s property was damaged.  \r(3) Where the plaintiff was injured.\r(4) Where a contract (written or spoken) was made, signed, performed, or broken by the defendant or where the defendant lived or did business when the defendant made the contract.",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List5[0].Lib[0].Checkbox5cb[0]",
+    "type": "checkbox",
+    "options": [
+      "2"
+    ],
+    "label": "Where the buyer or lessee signed the contract, lives now, or lived when the contract was made, if this claim, is about an offer or contract for personal, family, or household goods, services, or loans. (Code Civil Procedure, \rsection 395(b).)",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List5[0].Lic[0].Checkbox5cb[0]",
+    "type": "checkbox",
+    "options": [
+      "3"
+    ],
+    "label": "Where the buyer signed the contract, lives now, or lived when the contract was made, if this claim is about a retail installment contract (like a credit card). (Civil Code, section 1812.10.)",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List5[0].Lid[0].Checkbox5cb[0]",
+    "type": "checkbox",
+    "options": [
+      "4"
+    ],
+    "label": "Where the buyer signed the contract, lives now, or lived when the contract was made, or where the vehicle is permanently garaged, if this claim is about a vehicle finance sale. (Civil Code, section 2984.4.)",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List5[0].Lie[0].FillField55[0]",
+    "type": "text",
+    "options": [],
+    "label": "specify",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List5[0].Lie[0].Checkbox5cb[0]",
+    "type": "checkbox",
+    "options": [
+      "5"
+    ],
+    "label": "Other",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List6[0].item6[0].ZipCode1[0]",
+    "type": "text",
+    "options": [],
+    "label": "List the zip code of the place checked in 5 above (if you know):",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List7[0].item7[0].Checkbox60[0]",
+    "type": "checkbox",
+    "options": [
+      "1"
+    ],
+    "label": "Check if your claim is about a client-fee dispute",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List7[0].item7[0].Checkbox60[1]",
+    "type": "checkbox",
+    "options": [
+      "2"
+    ],
+    "label": "Check if your claim is not about a client-fee dispute",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List7[0].item7[0].Checkbox11[0]",
+    "type": "checkbox",
+    "options": [
+      "1"
+    ],
+    "label": "If yes, and if you have had arbitration, fill out form SC-101, attach it to this form, and check here:",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List8[0].item8[0].Checkbox61[0]",
+    "type": "checkbox",
+    "options": [
+      "1"
+    ],
+    "label": "Check if you are suing a public entity",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List8[0].item8[0].Checkbox61[1]",
+    "type": "checkbox",
+    "options": [
+      "2"
+    ],
+    "label": "Check if you are not suing a public entity",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List8[0].item8[0].Checkbox14[0]",
+    "type": "checkbox",
+    "options": [
+      "1"
+    ],
+    "label": "A claim was filed on",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page3[0].List8[0].item8[0].Date4[0]",
+    "type": "text",
+    "options": [],
+    "label": "date",
+    "page": 3,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page4[0].PxCaption[0].Plaintiff[0]",
+    "type": "text",
+    "options": [],
+    "label": "Plaintiff (list names)",
+    "page": 4,
+    "readonly": true,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page4[0].PxCaption[0].CaseNumber[0]",
+    "type": "text",
+    "options": [],
+    "label": "Case number",
+    "page": 4,
+    "readonly": true,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page4[0].List9[0].Item9[0].Checkbox62[0]",
+    "type": "checkbox",
+    "options": [
+      "1"
+    ],
+    "label": "Check if you have filed more than 12 other small claims in the last 12 months in California",
+    "page": 4,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page4[0].List9[0].Item9[0].Checkbox62[1]",
+    "type": "checkbox",
+    "options": [
+      "2"
+    ],
+    "label": "Check if you have not filed more than 12 other small claims in the last 12 months in California",
+    "page": 4,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page4[0].List10[0].li10[0].Checkbox63[0]",
+    "type": "checkbox",
+    "options": [
+      "1"
+    ],
+    "label": "Check if your claim is for more than $2,500.",
+    "page": 4,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page4[0].List10[0].li10[0].Checkbox63[1]",
+    "type": "checkbox",
+    "options": [
+      "2"
+    ],
+    "label": "Check if your claim is not for more than $2,500.",
+    "page": 4,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page4[0].Sign[0].Date1[0]",
+    "type": "text",
+    "options": [],
+    "label": "date",
+    "page": 4,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page4[0].Sign[0].PlaintiffName1[0]",
+    "type": "text",
+    "options": [],
+    "label": "Plaintiff types or prints name here",
+    "page": 4,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page4[0].Sign[0].Date2[0]",
+    "type": "text",
+    "options": [],
+    "label": "date",
+    "page": 4,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page4[0].Sign[0].PlaintiffName2[0]",
+    "type": "text",
+    "options": [],
+    "label": "Second plaintiff types or prints name here",
+    "page": 4,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page5[0].subRIght[0].NeedHelp[0].FillField1[0]",
+    "type": "text",
+    "options": [],
+    "label": "County Small claims advisor Info",
+    "page": 5,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].#pageSet[0].MPLast[0].Print[0]",
+    "type": "button",
+    "options": [],
+    "label": "Print",
+    "page": 6,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].#pageSet[0].MPLast[0].Save[0]",
+    "type": "button",
+    "options": [],
+    "label": "Save",
+    "page": 6,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].#pageSet[0].MPLast[0].Reset[0]",
+    "type": "button",
+    "options": [],
+    "label": "Clear",
+    "page": 6,
+    "readonly": false,
+    "required": false,
+    "created": null
+  },
+  {
+    "name": "SC-100[0].Page6[0].subRight[0].NeedHelpSpanish[0].FillField2[0]",
+    "type": "text",
+    "options": [],
+    "label": "Necesita ayuda",
+    "page": 6,
+    "readonly": false,
+    "required": false,
+    "created": null
+  }
+]

From 726e668a2990f2c721fc093c617149d2eef2d9a9 Mon Sep 17 00:00:00 2001
From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com>
Date: Fri, 23 Oct 2026 12:24:52 -0400
Subject: [PATCH 2/4] fix(demo): page before name, a guarded name step, numbers
 that cannot collide (#601 review)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 public/demo.html           | 23 ++++++++++++++---------
 test/demo-pdf-form.test.ts | 32 ++++++++++++++++++++++++++++++--
 2 files changed, 44 insertions(+), 11 deletions(-)

diff --git a/public/demo.html b/public/demo.html
index 5fb4d8f7..1862600b 100644
--- a/public/demo.html
+++ b/public/demo.html
@@ -453,9 +453,9 @@ <h2 class="visually-hidden">About</h2>
         .replace(/^./, (c) => c.toUpperCase());
       const xfa = (n) => (/\[\d+\]/.test(n) ? words(n.split('.').pop().replace(/\[\d+\]/g, '')) : '');
       const named = (f) => (typeof f.label === 'string' && f.label.trim()) || (f.created ? words(f.name) : xfa(f.name) || f.name);
-      // Two fields must not read the same, and none may read as its raw name (#593: SC-100's
-      // page 2 has four fields labelled "city"). A repeat is read from its name instead
-      // (`Plaintiff mailing city 1`), then given its page, then more of its name, then a number.
+      // Two fields must not read the same, and a repeat is never told apart by a raw XFA path
+      // (#593: SC-100's page 2 has four fields labelled "city"). A repeat gets its page, then
+      // is read from its name (`Plaintiff mailing city 1`), then from more of it, then numbered.
       const shown = fields.filter((f) => !f.readonly);
       const count = (xs) => xs.reduce((m, s) => m.set(s, (m.get(s) || 0) + 1), new Map());
       const tail = (f, k) => words(f.name.split('.').map((p) => p.replace(/\[\d+\]/g, '')).filter(Boolean).slice(-k).join(' '));
@@ -465,13 +465,18 @@ <h2 class="visually-hidden">About</h2>
         const seen = count(texts);
         texts = texts.map((s, i) => (seen.get(s) > 1 ? to(shown[i], s) : s));
       };
-      retell((f, s) => tail(f, 1) || s);
       retell((f, s) => s + page(f));
-      for (let k = 2; k <= 4; k++) retell((f, s) => tail(f, k) + page(f) || s);
-      const nth = new Map();
-      retell((f, s) => {
-        nth.set(s, (nth.get(s) || 0) + 1);
-        return `${s} (${nth.get(s)})`;
+      // What still repeats shares a page, so the page is not repeated here.
+      for (let k = 1; k <= 4; k++) retell((f, s) => tail(f, k) || s);
+      // A number must not land on a label another field already has.
+      const seen = count(texts);
+      const used = new Set(texts.filter((s) => seen.get(s) === 1));
+      texts = texts.map((s) => {
+        if (seen.get(s) === 1) return s;
+        let n = 1;
+        while (used.has(`${s} (${n})`)) n++;
+        used.add(`${s} (${n})`);
+        return `${s} (${n})`;
       });
       const text = new Map(shown.map((f, i) => [f, texts[i]]));
       const label = (f) => text.get(f) + req(f);
diff --git a/test/demo-pdf-form.test.ts b/test/demo-pdf-form.test.ts
index 385fee03..41e9b64b 100644
--- a/test/demo-pdf-form.test.ts
+++ b/test/demo-pdf-form.test.ts
@@ -106,8 +106,8 @@ test("an acronym keeps its capitals, and two fields that would read the same are
     "DOB field",
     "Case number (page 1)",
     "Case number (page 2)",
-    "A name (page 2)",
-    "B name (page 2)",
+    "A name",
+    "B name",
   ]);
 });
 
@@ -135,6 +135,34 @@ test("fields that read the same through their whole name are numbered", () => {
   assert.deepEqual([...list.querySelectorAll("label")].map((l) => l.textContent), ["F name (1)", "F name (2)"]);
 });
 
+test("a number never lands on another field's label", () => {
+  const doc = new JSDOM('<!DOCTYPE html><html lang="en"><head><title>t</title></head><body><form id="f"></form></body></html>').window.document;
+  const list = doc.getElementById("f")!;
+  renderFields(doc, list, [
+    { name: "F[0].Name[0]", type: "text", options: [], label: "Name" },
+    { name: "F[1].Name[0]", type: "text", options: [], label: "Name" },
+    { name: "G[0].Other[0]", type: "text", options: [], label: "F name (1)" },
+  ] as Field[]);
+  assert.deepEqual([...list.querySelectorAll("label")].map((l) => l.textContent), ["F name (2)", "F name (3)", "F name (1)"]);
+});
+
+test("a label repeated on different pages keeps its words and gains the page", () => {
+  const doc = new JSDOM('<!DOCTYPE html><html lang="en"><head><title>t</title></head><body><form id="f"></form></body></html>').window.document;
+  const list = doc.getElementById("f")!;
+  renderFields(doc, list, [
+    { name: "topmostSubform[0].Page1[0].f1_12[0]", type: "text", options: [], label: "Signature", page: 1 },
+    { name: "topmostSubform[0].Page3[0].f3_04[0]", type: "text", options: [], label: "Signature", page: 3 },
+    { name: "[0].[1]", type: "text", options: [], label: "City", page: 2 },
+    { name: "[2].[3]", type: "text", options: [], label: "City", page: 2 },
+  ] as Field[]);
+  assert.deepEqual([...list.querySelectorAll("label")].map((l) => l.textContent), [
+    "Signature (page 1)",
+    "Signature (page 3)",
+    "City (page 2) (1)",
+    "City (page 2) (2)",
+  ]);
+});
+
 test("an untouched form sends nothing, so the PDF keeps what it had", () => {
   assert.deepEqual(fieldValues(form().list), {});
 });

From e27eac42201e00cea2be52438ffed3036e5214e0 Mon Sep 17 00:00:00 2001
From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com>
Date: Fri, 23 Oct 2026 12:34:01 -0400
Subject: [PATCH 3/4] fix(demo): a retold label cannot take another field's
 unique one; type the test field page (#601 review)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 public/demo.html           |  8 +++++++-
 test/demo-pdf-form.test.ts | 13 ++++++++++++-
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/public/demo.html b/public/demo.html
index 1862600b..6f7542f0 100644
--- a/public/demo.html
+++ b/public/demo.html
@@ -461,9 +461,15 @@ <h2 class="visually-hidden">About</h2>
       const tail = (f, k) => words(f.name.split('.').map((p) => p.replace(/\[\d+\]/g, '')).filter(Boolean).slice(-k).join(' '));
       const page = (f) => (f.page ? ` (page ${f.page})` : '');
       let texts = shown.map(named);
+      // A retold label may not take one another field already has by itself.
       const retell = (to) => {
         const seen = count(texts);
-        texts = texts.map((s, i) => (seen.get(s) > 1 ? to(shown[i], s) : s));
+        const unique = new Set(texts.filter((s) => seen.get(s) === 1));
+        texts = texts.map((s, i) => {
+          if (seen.get(s) === 1) return s;
+          const t = to(shown[i], s);
+          return unique.has(t) ? s : t;
+        });
       };
       retell((f, s) => s + page(f));
       // What still repeats shares a page, so the page is not repeated here.
diff --git a/test/demo-pdf-form.test.ts b/test/demo-pdf-form.test.ts
index 41e9b64b..c2cce91d 100644
--- a/test/demo-pdf-form.test.ts
+++ b/test/demo-pdf-form.test.ts
@@ -26,7 +26,7 @@ function extract(name: string): string {
   throw new Error(`unbalanced braces reading ${name} from public/demo.html`);
 }
 
-type Field = { name: string; type: string; options: string[]; label?: string | null; created?: boolean; required?: boolean; readonly?: boolean; maxlen?: number | null; editable?: boolean; multiSelect?: boolean };
+type Field = { name: string; type: string; options: string[]; label?: string | null; page?: number; created?: boolean; required?: boolean; readonly?: boolean; maxlen?: number | null; editable?: boolean; multiSelect?: boolean };
 const renderFields = new Function(`${extract("renderFields")}; return renderFields;`)() as (doc: Document, list: Element, fields: Field[]) => number;
 const fieldValues = new Function(`${extract("fieldValues")}; return fieldValues;`)() as (list: Element) => Record<string, unknown>;
 const pdfNotes = new Function(`${extract("pdfNotes")}; return pdfNotes;`)() as (report: unknown) => string[];
@@ -146,6 +146,17 @@ test("a number never lands on another field's label", () => {
   assert.deepEqual([...list.querySelectorAll("label")].map((l) => l.textContent), ["F name (2)", "F name (3)", "F name (1)"]);
 });
 
+test("a field's own unique label is not taken by another field's name", () => {
+  const doc = new JSDOM('<!DOCTYPE html><html lang="en"><head><title>t</title></head><body><form id="f"></form></body></html>').window.document;
+  const list = doc.getElementById("f")!;
+  renderFields(doc, list, [
+    { name: "F[0].A[0].Zed[0]", type: "text", options: [], label: "Plaintiff city 1", page: 2 },
+    { name: "F[0].B[0].PlaintiffCity1[0]", type: "text", options: [], label: "City", page: 2 },
+    { name: "F[0].C[0].Other[0]", type: "text", options: [], label: "City", page: 2 },
+  ] as Field[]);
+  assert.deepEqual([...list.querySelectorAll("label")].map((l) => l.textContent), ["Plaintiff city 1", "City (page 2)", "Other"]);
+});
+
 test("a label repeated on different pages keeps its words and gains the page", () => {
   const doc = new JSDOM('<!DOCTYPE html><html lang="en"><head><title>t</title></head><body><form id="f"></form></body></html>').window.document;
   const list = doc.getElementById("f")!;

From 4aeffb08589ace5076920a0adf520d5030fa670c Mon Sep 17 00:00:00 2001
From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com>
Date: Fri, 23 Oct 2026 12:42:08 -0400
Subject: [PATCH 4/4] docs(demo): the name-step comment is a usual case, not a
 rule (#601 review)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 public/demo.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/public/demo.html b/public/demo.html
index 6f7542f0..a5e1f2e3 100644
--- a/public/demo.html
+++ b/public/demo.html
@@ -472,7 +472,7 @@ <h2 class="visually-hidden">About</h2>
         });
       };
       retell((f, s) => s + page(f));
-      // What still repeats shares a page, so the page is not repeated here.
+      // What still repeats almost always shares a page, so the page is not added here.
       for (let k = 1; k <= 4; k++) retell((f, s) => tail(f, k) || s);
       // A number must not land on a label another field already has.
       const seen = count(texts);