From bc9041b8905e9c4ea479137d2d8d220793851323 Mon Sep 17 00:00:00 2001
From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com>
Date: Thu, 21 May 2026 13:34:55 -0700
Subject: [PATCH] feat(pipeline): form fields agent for accessible HTML form
 controls

Add a vision-based Form Fields step to the Translation phase. A Haiku
agent compares each page image against its markdown and reports the form
fields it sees (text, textarea, checkbox, radio/checkbox group, select,
date, signature). A deterministic injector then replaces each field's
anchor text with an accessible, static HTML representation: labelled
controls wired via for/id, fieldset+legend for option groups, aria-required
for required fields, and readonly/disabled so the document advertises the
form's structure to a screen reader without implying it is fillable.

- new prompt module src/agents/prompts/form_fields.py
- FormFieldType/FormFieldOption/FormFieldInfo/FormFieldsPageOutput models
- _step_form_fields + _render_form_field_html/_apply_form_field in
  pipeline_viewer, wired after code_blocks
- viewer PIPELINE_STAGES + StageTabs nameMap updated for the new step
- pipeline-phases reference updated
- unit tests covering every field type, anchor hit/miss, and orchestration

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../components/pipeline-viewer/StageTabs.tsx  |   2 +-
 clients/viewer/src/types/pipeline-viewer.ts   |   2 +-
 docs/reference/pipeline-phases.md             |   7 +-
 src/agents/prompts/form_fields.py             | 101 ++++++
 src/services/pipeline_viewer.py               | 248 +++++++++++++++
 src/services/pipeline_viewer_models.py        |  78 +++++
 tests/unit/services/test_form_fields.py       | 299 ++++++++++++++++++
 7 files changed, 732 insertions(+), 5 deletions(-)
 create mode 100644 src/agents/prompts/form_fields.py
 create mode 100644 tests/unit/services/test_form_fields.py

diff --git a/clients/viewer/src/components/pipeline-viewer/StageTabs.tsx b/clients/viewer/src/components/pipeline-viewer/StageTabs.tsx
index d2bf4dc..baf50e5 100644
--- a/clients/viewer/src/components/pipeline-viewer/StageTabs.tsx
+++ b/clients/viewer/src/components/pipeline-viewer/StageTabs.tsx
@@ -141,7 +141,7 @@ function isProcessingInStage(
     extraction: ['Docling Extraction', 'OCR Re-extraction', 'Extraction'],
     analysis: ['PDF Classification', 'Structure Analysis'],
     headings: ['Heading Levels', 'Heading Reconciliation'],
-    translation: ['Page Content Corrections', 'Code Block Languages'],
+    translation: ['Page Content Corrections', 'Code Block Languages', 'Form Fields'],
     assembly: ['Cross-Page Fixes', 'Final Cleanup'],
   };
   const names = nameMap[stage.name];
diff --git a/clients/viewer/src/types/pipeline-viewer.ts b/clients/viewer/src/types/pipeline-viewer.ts
index e539880..eda1baf 100644
--- a/clients/viewer/src/types/pipeline-viewer.ts
+++ b/clients/viewer/src/types/pipeline-viewer.ts
@@ -45,7 +45,7 @@ export const PIPELINE_STAGES: StageDefinition[] = [
   { name: 'extraction',  label: 'Extraction',   steps: ['docling', 'docling_ocr'] },
   { name: 'analysis',    label: 'Analysis',      steps: ['classification', 'structure'] },
   { name: 'headings',    label: 'Headings',      steps: ['heading_levels', 'heading_reconciliation'] },
-  { name: 'translation', label: 'Translation',   steps: ['page_content', 'code_blocks'] },
+  { name: 'translation', label: 'Translation',   steps: ['page_content', 'code_blocks', 'form_fields'] },
   { name: 'assembly',    label: 'Assembly',       steps: ['boundaries', 'cleanup'] },
 ];
 
diff --git a/docs/reference/pipeline-phases.md b/docs/reference/pipeline-phases.md
index 2db405f..8a1f1e2 100644
--- a/docs/reference/pipeline-phases.md
+++ b/docs/reference/pipeline-phases.md
@@ -12,14 +12,14 @@ The pipeline has **5 versioned conversion phases** plus a **PII Review** gate th
 | 1. **Extraction** | `docling`, `docling_ocr` (conditional) | No | PDF → markdown + page images via IBM Docling. `docling_ocr` only fires when the classifier flags a scanned document. |
 | 2. **Analysis** | `classification`, `structure` | Yes | `classification` tags the document as digital / scanned / malformed. `structure` identifies headings, footnotes, code blocks, per-page layout attributes. |
 | 3. **Headings** | `heading_reconciliation`, `heading_levels` | Yes | `heading_reconciliation` reconciles per-page heading candidates against the global outline. `heading_levels` normalises the hierarchy (H1 → H2 → H3, no skips). |
-| 4. **Translation** | `page_content`, `code_blocks` | Yes | `page_content` does per-page accessibility corrections (invokes image / table / list subagents). `code_blocks` tags fenced blocks with detected programming language. |
+| 4. **Translation** | `page_content`, `code_blocks`, `form_fields` | Yes | `page_content` does per-page accessibility corrections (invokes image / table / list subagents). `code_blocks` tags fenced blocks with detected programming language. `form_fields` detects form controls from each page image and injects accessible HTML (labelled inputs, `<fieldset>`/`<legend>` option groups). |
 | 5. **Assembly** | `boundaries`, `cleanup` | Mixed | `boundaries` rejoins cross-page split content and relocates footnotes (AI). `cleanup` normalises whitespace and lints the markdown (deterministic). |
 
 The viewer also shows a dynamic **Review** stage that catches any orphan steps (`revision_*`, `feedback_*`, custom steps) not listed above.
 
 ## Internal step → `_step_*` method map
 
-Nine methods in `src/services/pipeline_viewer.py`, plus `pii_scan` which runs inline in `src/api/pipeline_viewer.py` (no `_step_*` method — it's pre-extraction gate logic, not a PipelineViewerService method):
+Ten methods in `src/services/pipeline_viewer.py`, plus `pii_scan` which runs inline in `src/api/pipeline_viewer.py` (no `_step_*` method — it's pre-extraction gate logic, not a PipelineViewerService method):
 
 | Step name | Method | Phase | Deterministic / AI |
 |---|---|---|---|
@@ -32,10 +32,11 @@ Nine methods in `src/services/pipeline_viewer.py`, plus `pii_scan` which runs in
 | `heading_levels` | `_step_heading_levels` | Headings | AI |
 | `page_content` | `_step_page_content` | Translation | AI + subagents |
 | `code_blocks` | `_step_code_blocks` | Translation | AI |
+| `form_fields` | `_step_form_fields` | Translation | AI (vision) + deterministic injection |
 | `boundaries` | `_step_boundaries` | Assembly | AI + subagent |
 | `cleanup` | `_step_cleanup` | Assembly | Deterministic |
 
-`classification` is not its own `_step_*` method — it's a `StepResult` emitted from within `_step_docling` when the classifier runs. Up to 10 named step results can appear in one run.
+`classification` is not its own `_step_*` method — it's a `StepResult` emitted from within `_step_docling` when the classifier runs. Up to 11 named step results can appear in one run.
 
 ## Subagents
 
diff --git a/src/agents/prompts/form_fields.py b/src/agents/prompts/form_fields.py
new file mode 100644
index 0000000..ead1a99
--- /dev/null
+++ b/src/agents/prompts/form_fields.py
@@ -0,0 +1,101 @@
+"""System prompt and user message template for the Form Fields agent.
+
+This agent examines one page of a PDF at a time, comparing the page image
+(visual ground truth) against its extracted markdown, and reports any form
+fields it finds. It does NOT modify the markdown — a deterministic injector
+turns each reported field into accessible HTML and splices it in afterwards.
+"""
+
+FORM_FIELDS_SYSTEM_PROMPT = """\
+You are a form accessibility analyst. You examine one page of a PDF at a \
+time, comparing the page image (visual ground truth) against its extracted \
+markdown, and you identify form fields a person would be expected to fill in.
+
+Your job is strictly detection — you do NOT modify the markdown. You report \
+what you find so that a later deterministic step can replace each field with \
+accessible HTML.
+
+## What counts as a form field
+
+Look at the page image for anything a person fills in by hand or on screen:
+
+- **Text fields** — a label followed by a blank line or box to write in, e.g. \
+"Name: ____________", "Email", an empty ruled box.
+- **Textareas** — large multi-line blank areas for long answers, comments, \
+or essays.
+- **Checkboxes** — a single square/box to tick (☐, [ ], a small empty box) \
+next to a statement, e.g. "☐ I agree to the terms".
+- **Checkbox groups** — several checkboxes under one prompt where more than \
+one may be ticked, e.g. "Select all that apply".
+- **Radio groups** — several mutually-exclusive options under one prompt \
+where exactly one is chosen, e.g. "Marital status: ☐ Single ☐ Married".
+- **Select / dropdowns** — a labelled choice list (often a box with a chevron).
+- **Date fields** — a labelled blank for a date (e.g. "Date of birth: __/__/____").
+- **Signature lines** — a ruled line labelled "Signature".
+
+Decorative rules, table borders, and underlines used purely for emphasis are \
+NOT form fields. Only report something a person is meant to complete.
+
+## What to report for each field
+
+- **field_type**: one of text, textarea, checkbox, checkbox_group, \
+radio_group, select, date, signature.
+- **label**: the accessible label, read from the IMAGE (not the markdown, \
+which may have OCR errors). For a single field this is the prompt next to \
+the blank (e.g. "Full name"). For a grouped field (radio_group, \
+checkbox_group, select) this is the group prompt/legend (e.g. "Marital \
+status"). If a field has no visible label, write a short descriptive one.
+- **anchor_text**: copy, VERBATIM, the exact text in the extracted markdown \
+that represents this field — for example the line "Name: ____________" or \
+"☐ I agree". This is used to locate and replace the field, so it must match \
+the markdown character-for-character. If the field is visible in the image \
+but absent from the markdown, set anchor_text to the nearest preceding \
+markdown line (e.g. the section heading) so the field can be inserted after it.
+- **options**: for radio_group, checkbox_group, and select only — the list of \
+choices, each with its visible label and whether it appears pre-ticked. \
+Empty for all other types.
+- **required**: true if the field is visibly marked required (an asterisk, \
+the word "required", bold "must").
+- **reasoning**: one sentence on how you determined the type and label.
+
+## Rules
+
+- Report fields in the order they appear top-to-bottom on the page.
+- A page with no form fields is a valid result — return an empty list.
+- Never invent options or labels that are not visible in the image.
+- Do not report the same field twice.
+"""
+
+
+def build_form_fields_user_message(
+    page_markdown: str,
+    page_number: int,
+    total_pages: int,
+) -> str:
+    """Build the text portion of the user message for one page.
+
+    The page image is passed separately as a binary content part.
+
+    Args:
+        page_markdown: Extracted markdown for this page (newest version).
+        page_number: Current page number (1-indexed).
+        total_pages: Total number of pages in the document.
+
+    Returns:
+        Text portion of the user message.
+    """
+    parts: list[str] = []
+    parts.append(f"## Page {page_number} of {total_pages}")
+    parts.append("")
+    parts.append("### Extracted markdown for this page")
+    parts.append("")
+    parts.append("```markdown")
+    parts.append(page_markdown)
+    parts.append("```")
+    parts.append("")
+    parts.append(
+        "The page image is attached. Compare the image (ground truth) against "
+        "the markdown above and report every form field you find. Copy each "
+        "field's anchor_text verbatim from the markdown."
+    )
+    return "\n".join(parts)
diff --git a/src/services/pipeline_viewer.py b/src/services/pipeline_viewer.py
index 10188ee..d11fea1 100644
--- a/src/services/pipeline_viewer.py
+++ b/src/services/pipeline_viewer.py
@@ -13,6 +13,7 @@
 import asyncio
 import base64
 import difflib
+import html
 import logging
 import re
 import time
@@ -26,6 +27,9 @@
     DocumentChange,
     FigureData,
     FootnoteInfo,
+    FormFieldInfo,
+    FormFieldsPageOutput,
+    FormFieldType,
     HeadingReconciliationOutput,
     ImageDescriptionResult,
     LayoutType,
@@ -273,6 +277,126 @@ def _apply_code_block_fence(
     )
 
 
+def _render_form_field_html(field: FormFieldInfo, field_id: str) -> str:
+    """Render a detected form field as an accessible, static HTML control.
+
+    The output is a *representation* of the form for accessibility, not a
+    working form: there is no surrounding ``<form>`` and inputs are marked
+    ``readonly`` / ``disabled`` so they advertise their role and label to a
+    screen reader without implying the document is fillable.
+
+    Every control is paired with a programmatic label:
+      - text / textarea / date / select use ``<label for=...>``,
+      - checkbox / single fields put the label after the control,
+      - radio_group / checkbox_group / multi-option select wrap options in a
+        ``<fieldset>`` with the prompt as the ``<legend>``.
+
+    Args:
+        field: The detected field.
+        field_id: A document-unique id stem (e.g. "ff-p1-2") used to wire
+            labels to controls.
+
+    Returns:
+        An HTML fragment.
+    """
+    label = html.escape(field.label or "Field")
+    required_attr = ' aria-required="true"' if field.required else ""
+    req_marker = ' <abbr title="required">*</abbr>' if field.required else ""
+
+    if field.field_type in (FormFieldType.TEXT, FormFieldType.DATE):
+        input_type = "date" if field.field_type == FormFieldType.DATE else "text"
+        return (
+            f'<label for="{field_id}">{label}{req_marker}</label>\n'
+            f'<input type="{input_type}" id="{field_id}" '
+            f'name="{field_id}"{required_attr} readonly>'
+        )
+
+    if field.field_type == FormFieldType.TEXTAREA:
+        return (
+            f'<label for="{field_id}">{label}{req_marker}</label>\n'
+            f'<textarea id="{field_id}" name="{field_id}"{required_attr} '
+            f"readonly></textarea>"
+        )
+
+    if field.field_type == FormFieldType.SIGNATURE:
+        return (
+            f'<label for="{field_id}">{label}{req_marker}</label>\n'
+            f'<input type="text" id="{field_id}" name="{field_id}" '
+            f'aria-label="{label} (signature)"{required_attr} readonly>'
+        )
+
+    if field.field_type == FormFieldType.CHECKBOX:
+        checked = " checked" if (field.options and field.options[0].checked) else ""
+        return (
+            f'<input type="checkbox" id="{field_id}" name="{field_id}"'
+            f"{checked}{required_attr} disabled> "
+            f'<label for="{field_id}">{label}{req_marker}</label>'
+        )
+
+    if field.field_type == FormFieldType.SELECT:
+        opts = "\n".join(
+            f'  <option{" selected" if o.checked else ""}>'
+            f"{html.escape(o.label)}</option>"
+            for o in field.options
+        )
+        return (
+            f'<label for="{field_id}">{label}{req_marker}</label>\n'
+            f'<select id="{field_id}" name="{field_id}"{required_attr} disabled>\n'
+            f"{opts}\n"
+            f"</select>"
+        )
+
+    # radio_group / checkbox_group — fieldset + legend, one control per option
+    input_type = (
+        "checkbox" if field.field_type == FormFieldType.CHECKBOX_GROUP else "radio"
+    )
+    parts = ["<fieldset>", f"  <legend>{label}{req_marker}</legend>"]
+    for i, opt in enumerate(field.options):
+        opt_id = f"{field_id}-{i}"
+        checked = " checked" if opt.checked else ""
+        # All radios in a group share a name; checkboxes get distinct names.
+        name = field_id if input_type == "radio" else opt_id
+        parts.append(
+            f'  <input type="{input_type}" id="{opt_id}" name="{name}"'
+            f"{checked} disabled> "
+            f'<label for="{opt_id}">{html.escape(opt.label)}</label>'
+        )
+    parts.append("</fieldset>")
+    return "\n".join(parts)
+
+
+def _apply_form_field(
+    page_md: str,
+    field: FormFieldInfo,
+    field_id: str,
+) -> tuple[str, DocumentChange | None]:
+    """Replace a detected field's ``anchor_text`` with accessible HTML.
+
+    Fuzzy-finds the anchor line in *page_md* and swaps it for the rendered
+    control. Returns ``(new_markdown, change)`` or ``(original, None)`` if the
+    anchor could not be located.
+    """
+    lines = page_md.split("\n")
+    idx = _fuzzy_find_line(lines, field.anchor_text)
+    if idx < 0:
+        return page_md, None
+
+    new_html = _render_form_field_html(field, field_id)
+    old_text = lines[idx]
+    new_lines = lines[:idx] + [new_html] + lines[idx + 1 :]
+
+    return "\n".join(new_lines), DocumentChange(
+        page=field.page,
+        old_text=old_text[:200] + ("..." if len(old_text) > 200 else ""),
+        new_text=new_html[:200] + ("..." if len(new_html) > 200 else ""),
+        reasoning=(
+            f"Replaced {field.field_type.value} field "
+            f"'{field.label}' with accessible HTML ({field.reasoning})"
+        ),
+        stage="form_field",
+    )
+
+
 def _replace_image_placeholders(
     markdown: str,
     figures: list[FigureData],
@@ -637,6 +761,8 @@ def _emit_phase(name: str, display_name: str) -> None:
             await self._step_page_content(result, structure, page_hints=page_hints)
             _emit_phase("code_blocks", "Code Block Languages")
             await self._step_code_blocks(result, structure)
+            _emit_phase("form_fields", "Form Fields")
+            await self._step_form_fields(result)
 
         if enable_boundaries and structure is not None:
             if section_map is None and structure is not None:
@@ -2669,6 +2795,128 @@ async def _step_code_blocks(
             )
         )
 
+    async def _step_form_fields(
+        self,
+        result: PipelineViewerResult,
+    ) -> None:
+        """Detect form fields per page and inject accessible HTML controls.
+
+        A vision agent compares each page image (ground truth) against its
+        markdown and reports the form fields it sees. A deterministic injector
+        then replaces each field's ``anchor_text`` with accessible HTML
+        (labelled controls, ``<fieldset>``/``<legend>`` for option groups).
+
+        Detection-only pages (no form) cost one cheap call and change nothing.
+        Edits whichever per-page version is newest (v1 if present, else v0)
+        in-place — does not introduce a new version.
+        """
+        from pydantic_ai import Agent
+        from pydantic_ai.messages import BinaryContent
+
+        from ..agents.model_factory import get_model_for_tier
+        from ..agents.model_tiers import ModelTier
+        from ..agents.prompts.form_fields import (
+            FORM_FIELDS_SYSTEM_PROMPT,
+            build_form_fields_user_message,
+        )
+        from ..shared.llm_cost import calculate_estimated_cost
+
+        step_start = time.time()
+        source_version = "v1" if "v1" in result.page_markdowns else "v0"
+        page_mds = result.page_markdowns.get(source_version, {})
+
+        model = get_model_for_tier(ModelTier.EFFICIENT)
+        agent: Agent[None, FormFieldsPageOutput] = Agent(
+            model=model,
+            output_type=FormFieldsPageOutput,
+            system_prompt=FORM_FIELDS_SYSTEM_PROMPT,
+        )
+
+        changes: list[DocumentChange] = []
+        fields_found = 0
+        total_input_tokens = 0
+        total_output_tokens = 0
+
+        for page_num in range(1, result.total_pages + 1):
+            page_key = str(page_num)
+            page_md = page_mds.get(page_key, "")
+            page_image_b64 = result.page_images.get(page_key)
+            if not page_md or not page_image_b64:
+                continue
+
+            text_msg = build_form_fields_user_message(
+                page_markdown=page_md,
+                page_number=page_num,
+                total_pages=result.total_pages,
+            )
+            messages: list[Any] = [
+                BinaryContent(
+                    data=base64.b64decode(page_image_b64), media_type="image/png"
+                ),
+                text_msg,
+            ]
+
+            try:
+                agent_result = await agent.run(messages)
+                page_output = agent_result.output
+                usage = agent_result.usage()
+                total_input_tokens += usage.request_tokens or 0
+                total_output_tokens += usage.response_tokens or 0
+            except Exception as e:
+                logger.error(f"Form field detection failed on page {page_num}: {e}")
+                continue
+
+            if not page_output.form_fields:
+                continue
+
+            fields_found += len(page_output.form_fields)
+            current_md = page_mds[page_key]
+            for i, field in enumerate(page_output.form_fields):
+                field.page = page_num
+                field_id = f"ff-p{page_num}-{i}"
+                new_md, change = _apply_form_field(current_md, field, field_id)
+                if change:
+                    current_md = new_md
+                    changes.append(change)
+                else:
+                    logger.info(
+                        f"Form field anchor not found on page {page_num}: "
+                        f"{field.anchor_text!r}"
+                    )
+            page_mds[page_key] = current_md
+
+            logger.info(
+                f"Form fields page {page_num}/{result.total_pages}: "
+                f"detected={len(page_output.form_fields)}"
+            )
+
+        # Rebuild the full version from corrected pages
+        if changes:
+            result.versions[source_version] = "\n\n".join(
+                page_mds.get(str(p), "") for p in range(1, result.total_pages + 1)
+            )
+
+        elapsed_ms = int((time.time() - step_start) * 1000)
+        cost_cents = calculate_estimated_cost(total_input_tokens, total_output_tokens)
+
+        result.steps.append(
+            StepResult(
+                name="form_fields",
+                display_name="Form Fields",
+                version_before=source_version,
+                version_after=source_version,
+                elapsed_ms=elapsed_ms,
+                changes=changes,
+                metadata={
+                    "fields_detected": fields_found,
+                    "fields_injected": len(changes),
+                },
+                input_tokens=total_input_tokens,
+                output_tokens=total_output_tokens,
+                cost_cents=cost_cents,
+            )
+        )
+
     # ------------------------------------------------------------------
     # Phase 3 — Cross-page fixes (on assembled document)
     # ------------------------------------------------------------------
diff --git a/src/services/pipeline_viewer_models.py b/src/services/pipeline_viewer_models.py
index 558f73c..bc28ba9 100644
--- a/src/services/pipeline_viewer_models.py
+++ b/src/services/pipeline_viewer_models.py
@@ -98,6 +98,84 @@ class CodeBlockInfo(BaseModel):
     """How the language was identified (syntax, surrounding context, etc.)."""
 
 
+class FormFieldType(str, Enum):
+    """Type of form control to render for a detected field."""
+
+    TEXT = "text"
+    """Single-line free-text input (name, email, short answer)."""
+
+    TEXTAREA = "textarea"
+    """Multi-line free-text input (comments, essay box)."""
+
+    CHECKBOX = "checkbox"
+    """A single standalone checkbox (e.g. "I agree to the terms")."""
+
+    CHECKBOX_GROUP = "checkbox_group"
+    """A set of checkboxes where more than one may be ticked."""
+
+    RADIO_GROUP = "radio_group"
+    """A set of mutually-exclusive options (exactly one selected)."""
+
+    SELECT = "select"
+    """A dropdown / choice list."""
+
+    DATE = "date"
+    """A date entry field."""
+
+    SIGNATURE = "signature"
+    """A signature line."""
+
+
+class FormFieldOption(BaseModel):
+    """One selectable option within a radio, checkbox, or select group."""
+
+    label: str
+    """Visible option text as read from the page image."""
+
+    checked: bool = False
+    """True if the option appears pre-selected / ticked in the image."""
+
+
+class FormFieldInfo(BaseModel):
+    """A form field detected on a page from the page image.
+
+    The agent reports what it sees; the deterministic injector turns this
+    into accessible HTML and splices it into the page markdown by replacing
+    ``anchor_text``.
+    """
+
+    field_type: FormFieldType
+    """The kind of control this field represents."""
+
+    label: str
+    """Accessible label for the field, as read from the image (e.g. "Full name").
+    For grouped fields this is the group prompt/legend (e.g. "Marital status")."""
+
+    anchor_text: str
+    """The exact existing markdown text representing this field (e.g.
+    "Name: ____________" or "☐ I agree"). The injector replaces this text
+    with the rendered accessible HTML. Copy it verbatim from the markdown."""
+
+    options: list[FormFieldOption] = Field(default_factory=list)
+    """Options for radio_group / checkbox_group / select fields. Empty otherwise."""
+
+    required: bool = False
+    """True if the field is marked required (asterisk, "required", etc.)."""
+
+    page: int = 0
+    """Page where this field appears (1-indexed). Set by the orchestrator."""
+
+    reasoning: str = ""
+    """How the field type and label were determined."""
+
+
+class FormFieldsPageOutput(BaseModel):
+    """What the form-fields agent returns for a single page."""
+
+    form_fields: list[FormFieldInfo] = Field(default_factory=list)
+    """Form fields found on this page. Empty list if the page has no form."""
+
+
 class StructurePageOutput(BaseModel):
     """What the Phase 1 agent returns for a single page.
 
diff --git a/tests/unit/services/test_form_fields.py b/tests/unit/services/test_form_fields.py
new file mode 100644
index 0000000..dd772b8
--- /dev/null
+++ b/tests/unit/services/test_form_fields.py
@@ -0,0 +1,299 @@
+"""Unit tests for the Form Fields pipeline step.
+
+Covers the pure accessible-HTML renderer (`_render_form_field_html`), the
+deterministic anchor-replacement injector (`_apply_form_field`), and the
+`_step_form_fields` orchestration (with the vision agent mocked).
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from src.services.pipeline_viewer import (
+    PipelineViewerService,
+    _apply_form_field,
+    _render_form_field_html,
+)
+from src.services.pipeline_viewer_models import (
+    FormFieldInfo,
+    FormFieldOption,
+    FormFieldsPageOutput,
+    FormFieldType,
+    PipelineViewerResult,
+)
+
+pytestmark = pytest.mark.unit
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def service():
+    return PipelineViewerService()
+
+
+@pytest.fixture
+def base_result():
+    """A 1-page result whose newest per-page version is v0."""
+    return PipelineViewerResult(
+        filename="form.pdf",
+        total_pages=1,
+        versions={"v0": "# Application\n\nName: ____________"},
+        page_images={"1": "AAAA"},
+        page_markdowns={"v0": {"1": "# Application\n\nName: ____________"}},
+        figures=[],
+        steps=[],
+        stats={},
+    )
+
+
+# ---------------------------------------------------------------------------
+# _render_form_field_html — accessible markup per field type
+# ---------------------------------------------------------------------------
+
+
+class TestRenderFormFieldHtml:
+    def test_text_field_label_wired_to_input(self):
+        field = FormFieldInfo(field_type=FormFieldType.TEXT, label="Full name", anchor_text="Name:")
+        html = _render_form_field_html(field, "ff-p1-0")
+        assert '<label for="ff-p1-0">Full name</label>' in html
+        assert '<input type="text" id="ff-p1-0"' in html
+        assert "readonly" in html
+
+    def test_required_field_gets_aria_required(self):
+        field = FormFieldInfo(
+            field_type=FormFieldType.TEXT,
+            label="Email",
+            anchor_text="Email",
+            required=True,
+        )
+        html = _render_form_field_html(field, "ff-p1-1")
+        assert 'aria-required="true"' in html
+        assert '<abbr title="required">*</abbr>' in html
+
+    def test_date_field_uses_date_input(self):
+        field = FormFieldInfo(field_type=FormFieldType.DATE, label="DOB", anchor_text="Date of birth")
+        html = _render_form_field_html(field, "ff-p1-0")
+        assert '<input type="date"' in html
+
+    def test_textarea_field(self):
+        field = FormFieldInfo(field_type=FormFieldType.TEXTAREA, label="Comments", anchor_text="Comments")
+        html = _render_form_field_html(field, "ff-p1-0")
+        assert '<textarea id="ff-p1-0"' in html
+        assert "</textarea>" in html
+
+    def test_checkbox_label_after_control(self):
+        field = FormFieldInfo(
+            field_type=FormFieldType.CHECKBOX,
+            label="I agree",
+            anchor_text="I agree",
+            options=[FormFieldOption(label="I agree", checked=True)],
+        )
+        html = _render_form_field_html(field, "ff-p1-0")
+        assert '<input type="checkbox" id="ff-p1-0"' in html
+        assert "checked" in html
+        # control comes before its label
+        assert html.index("<input") < html.index("<label")
+
+    def test_radio_group_uses_fieldset_legend_and_shared_name(self):
+        field = FormFieldInfo(
+            field_type=FormFieldType.RADIO_GROUP,
+            label="Marital status",
+            anchor_text="Marital status",
+            options=[
+                FormFieldOption(label="Single"),
+                FormFieldOption(label="Married", checked=True),
+            ],
+        )
+        html = _render_form_field_html(field, "ff-p1-0")
+        assert "<fieldset>" in html
+        assert "<legend>Marital status</legend>" in html
+        # both radios share the group name
+        assert html.count('name="ff-p1-0"') == 2
+        assert '<input type="radio" id="ff-p1-0-0"' in html
+        assert '<input type="radio" id="ff-p1-0-1"' in html
+        assert "checked" in html
+
+    def test_checkbox_group_uses_distinct_names(self):
+        field = FormFieldInfo(
+            field_type=FormFieldType.CHECKBOX_GROUP,
+            label="Toppings",
+            anchor_text="Toppings",
+            options=[FormFieldOption(label="Cheese"), FormFieldOption(label="Olives")],
+        )
+        html = _render_form_field_html(field, "ff-p1-0")
+        assert "<fieldset>" in html
+        assert 'name="ff-p1-0-0"' in html
+        assert 'name="ff-p1-0-1"' in html
+
+    def test_select_renders_options(self):
+        field = FormFieldInfo(
+            field_type=FormFieldType.SELECT,
+            label="State",
+            anchor_text="State",
+            options=[
+                FormFieldOption(label="Illinois", checked=True),
+                FormFieldOption(label="Iowa"),
+            ],
+        )
+        html = _render_form_field_html(field, "ff-p1-0")
+        assert '<select id="ff-p1-0"' in html
+        assert "<option selected>Illinois</option>" in html
+        assert "<option>Iowa</option>" in html
+
+    def test_signature_field(self):
+        field = FormFieldInfo(field_type=FormFieldType.SIGNATURE, label="Signature", anchor_text="Sign")
+        html = _render_form_field_html(field, "ff-p1-0")
+        assert "(signature)" in html
+
+    def test_option_labels_are_html_escaped(self):
+        field = FormFieldInfo(
+            field_type=FormFieldType.SELECT,
+            label="Pick <one>",
+            anchor_text="Pick",
+            options=[FormFieldOption(label="A & B")],
+        )
+        html = _render_form_field_html(field, "ff-p1-0")
+        assert "Pick &lt;one&gt;" in html
+        assert "A &amp; B" in html
+
+
+# ---------------------------------------------------------------------------
+# _apply_form_field — anchor replacement
+# ---------------------------------------------------------------------------
+
+
+class TestApplyFormField:
+    def test_replaces_matching_anchor_line(self):
+        md = "# Application\n\nName: ____________\n\nThanks"
+        field = FormFieldInfo(
+            field_type=FormFieldType.TEXT,
+            label="Full name",
+            anchor_text="Name: ____________",
+            page=1,
+        )
+        new_md, change = _apply_form_field(md, field, "ff-p1-0")
+        assert change is not None
+        assert "Name: ____________" not in new_md
+        assert '<input type="text" id="ff-p1-0"' in new_md
+        # surrounding lines preserved
+        assert new_md.startswith("# Application")
+        assert new_md.endswith("Thanks")
+        assert change.stage == "form_field"
+
+    def test_missing_anchor_returns_original(self):
+        md = "# Application\n\nNothing to fill in here."
+        field = FormFieldInfo(
+            field_type=FormFieldType.TEXT,
+            label="Full name",
+            anchor_text="zzz totally absent anchor zzz",
+            page=1,
+        )
+        new_md, change = _apply_form_field(md, field, "ff-p1-0")
+        assert change is None
+        assert new_md == md
+
+
+# ---------------------------------------------------------------------------
+# _step_form_fields — orchestration
+# ---------------------------------------------------------------------------
+
+
+def _mock_agent_returning(output: FormFieldsPageOutput) -> MagicMock:
+    mock_agent = MagicMock()
+    mock_run_result = MagicMock()
+    mock_run_result.output = output
+    mock_run_result.usage.return_value = MagicMock(request_tokens=10, response_tokens=5)
+    mock_agent.run = AsyncMock(return_value=mock_run_result)
+    return mock_agent
+
+
+def _patches():
+    return (
+        patch("pydantic_ai.Agent"),
+        patch("pydantic_ai.models.bedrock.BedrockConverseModel"),
+        patch("pydantic_ai.messages.BinaryContent"),
+    )
+
+
+class TestStepFormFields:
+    @pytest.mark.asyncio
+    async def test_injects_detected_field_and_rebuilds_version(self, service, base_result):
+        output = FormFieldsPageOutput(
+            form_fields=[
+                FormFieldInfo(
+                    field_type=FormFieldType.TEXT,
+                    label="Full name",
+                    anchor_text="Name: ____________",
+                )
+            ]
+        )
+        mock_agent = _mock_agent_returning(output)
+        p1, p2, p3 = _patches()
+        with p1 as agent_cls, p2, p3:
+            agent_cls.return_value = mock_agent
+            await service._step_form_fields(base_result)
+
+        page_md = base_result.page_markdowns["v0"]["1"]
+        assert '<input type="text" id="ff-p1-0"' in page_md
+        # full version rebuilt from the corrected page
+        assert '<input type="text" id="ff-p1-0"' in base_result.versions["v0"]
+
+        step = next(s for s in base_result.steps if s.name == "form_fields")
+        assert step.display_name == "Form Fields"
+        assert step.metadata["fields_detected"] == 1
+        assert step.metadata["fields_injected"] == 1
+        assert len(step.changes) == 1
+
+    @pytest.mark.asyncio
+    async def test_no_fields_records_empty_step(self, service, base_result):
+        mock_agent = _mock_agent_returning(FormFieldsPageOutput(form_fields=[]))
+        original = base_result.versions["v0"]
+        p1, p2, p3 = _patches()
+        with p1 as agent_cls, p2, p3:
+            agent_cls.return_value = mock_agent
+            await service._step_form_fields(base_result)
+
+        step = next(s for s in base_result.steps if s.name == "form_fields")
+        assert step.metadata["fields_detected"] == 0
+        assert step.metadata["fields_injected"] == 0
+        assert step.changes == []
+        # markdown untouched
+        assert base_result.versions["v0"] == original
+
+    @pytest.mark.asyncio
+    async def test_detected_but_anchor_missing_is_not_injected(self, service, base_result):
+        output = FormFieldsPageOutput(
+            form_fields=[
+                FormFieldInfo(
+                    field_type=FormFieldType.TEXT,
+                    label="Phantom",
+                    anchor_text="zzz absent anchor zzz",
+                )
+            ]
+        )
+        mock_agent = _mock_agent_returning(output)
+        p1, p2, p3 = _patches()
+        with p1 as agent_cls, p2, p3:
+            agent_cls.return_value = mock_agent
+            await service._step_form_fields(base_result)
+
+        step = next(s for s in base_result.steps if s.name == "form_fields")
+        assert step.metadata["fields_detected"] == 1
+        assert step.metadata["fields_injected"] == 0
+
+    @pytest.mark.asyncio
+    async def test_agent_failure_skips_page_without_raising(self, service, base_result):
+        mock_agent = MagicMock()
+        mock_agent.run = AsyncMock(side_effect=RuntimeError("LLM error"))
+        p1, p2, p3 = _patches()
+        with p1 as agent_cls, p2, p3:
+            agent_cls.return_value = mock_agent
+            await service._step_form_fields(base_result)
+
+        step = next(s for s in base_result.steps if s.name == "form_fields")
+        assert step.metadata["fields_injected"] == 0