Tag Studio — Interaction Design Spec

Epic: #3866 · Product: Gevell Tags at tags.gevell.com (add it to packages/accessible-org-ui/src/products.ts when it ships) · Status: draft for review.

This spec covers how the editor behaves: layout, selection, keyboard, task modes, validation, bulk operations, AI review, undo, save and export. It does not cover the Rust/WASM engine internals (phase 1), except for the operation vocabulary that the UI emits. The design starts from scratch. It does not inherit the interaction model of apps/web’s tag views or apps/tag-editor.

Standards targets: the output is validated for PDF/UA-1 (ISO 14289-1, Matterhorn Protocol 1.1) and WCAG 2.1 AA content requirements. The tool itself must meet WCAG 2.2 AA and must be fully usable with a keyboard only and with NVDA, JAWS and VoiceOver.

---

0. Principles

1. One structure model, many views. The canvas, tree, reader preview and inspector all render the same in-memory structure. No view keeps its own copy, so views cannot drift out of sync.
2. Every edit is an operation. Each change is a typed, validated, reversible op with an inverse and an origin (user, fix-all, select-similar, AI, template). Nothing mutates the model any other way. Undo is reliable because it is part of the model, not added afterwards.
3. Invalid ops are refused before they apply. Each op checks its preconditions (for example “LI may only be a child of L”). A refused op leaves the document unchanged and gives a plain-language reason that says what to do instead.
4. Guided first, raw one toggle away. Task modes are the default workspace. Raw tree is a peer mode, not a hidden “advanced” screen.
5. No false green. Items that need human judgment (alt text quality, reading order meaning, heading semantics) are never shown as passing. They show as Needs review until a person marks them reviewed, and that attestation is recorded.
6. Never alter what the page looks like. Saving is gated on a pixel-identity check. Tagging changes structure only, never appearance.
7. Non-modal by default. Properties are edited in the inspector, with no blocking dialogs. The only modal surfaces are unsaved-changes and destructive-confirm prompts, and the save-gate failure sheet.
8. Every pointer action has a keyboard path and a non-drag path (WCAG 2.5.7). Drag is a shortcut, never the only way.
9. Say what happened. Every op result is announced in a live region in the words the history panel uses (“Retyped P to H2 · 1 item”).
10. The AI proposes and the human decides. AI output arrives as proposed ops with a confidence level and a one-line reason. By default it changes nothing until someone accepts it. Users can opt in to auto-apply above a confidence threshold (§9.4). Auto-applied changes are marked as AI, can be undone, and never count as human review.
11. The server holds the record. Documents, versions and the op log sync to Gevell’s servers (AWS). The browser keeps a local outbox so work continues offline and nothing is lost (§11.3).

Terms

Term	Meaning
Node	A structure element (StructElem) such as H2, P, Figure or TD
Content item	A leaf of page content: marked-content sequence (MCR/MCID), annotation (OBJR), or untagged run
Orphan	Page content that is neither tagged nor artifacted. Every orphan is a PDF/UA failure
Op	An atomic, reversible edit (see §3)
Group	One or more ops applied as one undo step (bulk, fix-all, AI accept)
Primary	The most recently selected item in a multi-selection. The inspector shows the primary
Mode	A guided task workspace (Reading order, Headings, …) or Raw tree
Proposal	An op (or group) suggested by AI or a detector, not yet applied

---

1. Layout

1.1 Regions (all breakpoints)

Each region is a landmark: <header>, <nav aria-label="Modes">, <main> containing the view regions, each a <section aria-labelledby> with a visible heading. Screen reader users can move between views with landmark and heading navigation as well as with F6.

Region	Contents
App bar	File name, sync status (“Synced” / “Syncing 3…” / “Offline · 12 changes on this device” / “Sync problem”), version state (“v7 + 14 changes” / “v8 · verifying…”), undo/redo, validation summary chip, Save, Export, command palette button, help, theme
Mode rail	Vertical tablist of task modes with per-mode issue counts
Task panel	Mode-specific work queue: outline, figure queue, table picker, artifact groups, and so on
Structure tree	Virtualized treegrid. In guided modes it shares a column with the task panel as a split pane. In Raw tree mode it fills the column
Canvas	Rendered page(s) with overlays, reading-order path and orphan highlighting
Reader	Screen reader preview: linear announcements, plus a reflow tab
Inspector	Non-modal properties of the primary selection
Dock tabs	Issues · History · Suggestions (AI) · Similar
Status bar	Page x of N, zoom, selection count, validation progress, engine status, and a live-region echo of the last announcement

1.2 Wide desktop (≥ 1920 CSS px)

All four views are visible at once, and the dock sits under the right column.

┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ◧ Tag Studio  annual-report-2025.pdf  ☁ Synced · v7 + 14 changes  ↶ ↷  [ ✕ 12 fail · ? 31 review ] ⌘K [Save] [Export▾]│
├────┬──────────────────────────────┬──────────────────────────────────────┬────────────────────┬────────────────┤
│ ≡  │ READING ORDER · page 3       │  ◀ p3/48 ▶   100% ▾   Overlays ▾     │ READER   Reflow    │ INSPECTOR      │
│ RO │ ┌──────────────────────────┐ │ ┌──────────────────────────────────┐ │ heading level 1,   │ H2 · page 3    │
│ 3  │ │ 1 H1  Annual Report 2025 │ │ │ ①━━━━━━━━━━━━━━━━━━━━━━━━┓[H1]   │ │   Annual Report    │ Type  [H2   ▾] │
│ Hd │ │ 2 P   The fiscal year…   │ │ │ ┃②┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┐[P]      │ │ The fiscal year…   │ Lang  [inherit]│
│ 1  │ │ 3 H2  Budget overview  ◀ │ │ │ ┃ ③━━━━━━━━━━━┓[H2] ◀sel        │ │▶heading level 2,   │ Title [       ]│
│ Fg │ │ 4 ▦   Table 1 (4×3)      │ │ │ ┃ ④▦▦▦▦▦▦▦▦▦▦▦[Table]           │ │   Budget overview  │ ActualText     │
│ 7  │ │ 5 P   Revenue grew…      │ │ │ ┃ ⑤┈┈┈┈┈┈┈┈┈┈┈┈[P]              │ │ table with 4 rows  │ [             ]│
│ Tb │ └──────────────────────────┘ │ │ ░░░ untagged ░░░ ⚠              │ │   and 3 columns    │ BBox 72,540 …  │
│ 2  ├──────────────────────────────┤ │ └──────────────────────────────────┘ │ …                  │ [Attributes ▸] │
│ Ar │ STRUCTURE           / filter │ │                                      │                    ├────────────────┤
│ Ls │ ▾ Document                   │ │                                      │                    │ Issues History │
│ Lk │   ▾ Sect                     │ │                                      │                    │ Suggest Similar│
│ Fm │     H1  Annual Report 2025   │ │                                      │                    │ ✕ Figure has no│
│ Nt │     P   The fiscal year…     │ │                                      │                    │   alt (p3)[Fix]│
│ La │   ▸ H2  Budget overview  ✕1  │ │                                      │                    │ ? Reading order│
│ TC │     Table  4×3               │ │                                      │                    │   p3 [Review]  │
│ {} │                              │ │                                      │                    │                │
├────┴──────────────────────────────┴──────────────────────────────────────┴────────────────────┴────────────────┤
│ Page 3 of 48 · 100% · 1 selected (H2) · Validating… 62% ▓▓▓▓░░ · Engine ready │ Retyped P to H2 · 1 item       │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Column widths: rail 56 · task/tree 360 · canvas flex (min 640) · reader 340 · inspector/dock 380. Every splitter can be resized with the pointer and with the keyboard. Each splitter is a focusable role="separator" with aria-valuenow; the arrow keys move it 16px and Home/End collapse or restore it. Layout is saved per user in localStorage (a convenience only).

1.3 Standard desktop (1280–1919 CSS px)

The reader moves into the right-hand dock as a tab. The inspector stays pinned at the top of the right column. The dock tabs are Reader · Issues · History · Suggestions · Similar.

┌───────────────────────────────────────────────────────────────────────────────────────────┐
│ ◧ annual-report-2025.pdf  ☁ Synced · v7+14  ↶ ↷  [✕12 ?31]  ⌘K  [Save] [Export▾]          │
├────┬───────────────────────────┬──────────────────────────────────┬───────────────────────┤
│ RO │ READING ORDER · p3        │ ◀ p3/48 ▶ 100% ▾ Overlays ▾       │ INSPECTOR  H2 · p3    │
│ Hd │ 1 H1 Annual Report 2025   │ ┌──────────────────────────────┐ │ Type [H2 ▾] Lang[inh] │
│ Fg │ 2 P  The fiscal year…     │ │ ①━━━━━━━━━━━━━━━━━┓[H1]       │ │ ActualText [        ] │
│ Tb │ 3 H2 Budget overview ◀    │ │ ┃②┈┈┈┈┈┈┈┈┈┈┈┈┈┈[P]           │ │ [Attributes ▸]        │
│ Ar ├───────────────────────────┤ │ ┃ ③━━━━━━━┓[H2]               │ ├───────────────────────┤
│ Ls │ STRUCTURE        / filter │ │ ┃ ④▦▦▦▦▦▦▦[Table]              │ │ Reader Issues History │
│ Lk │ ▾ Document                │ │ ░░ untagged ░░ ⚠             │ │ Suggest  Similar      │
│ Fm │   H1 Annual Report 2025   │ │                              │ │ heading level 2,      │
│ Nt │ ▸ H2 Budget overview ✕1   │ └──────────────────────────────┘ │   Budget overview     │
│ La │   Table 4×3               │                                  │ table with 4 rows …   │
│ TC │                           │                                  │                       │
│ {} │                           │                                  │                       │
├────┴───────────────────────────┴──────────────────────────────────┴───────────────────────┤
│ p3/48 · 100% · 1 selected · Validating 62% ▓▓▓░ │ Retyped P to H2 · 1 item                  │
└───────────────────────────────────────────────────────────────────────────────────────────┘

Column widths: rail 56 · task/tree 300 · canvas flex (min 520) · right 360.

1.4 Compact desktop (1024–1279 CSS px): minimum for the multi-pane workspace

• 1024 CSS px is the minimum width for the synchronized multi-pane workspace. This equals a 1280px screen at 125% browser zoom, which is a common setup for remediators.
• The mode rail shrinks to icons with visible short labels (2–3 letters, as in the wireframes) and a tooltip. The tooltip is not the only label: each tab’s accessible name is the full mode name.
• The right column becomes a drawer that overlays the canvas. It is toggled with the Inspector button or Mod+I (see §5, with its conflict note). The drawer is non-modal: focus is not trapped, and Esc closes it and returns focus to where it came from.
• The task panel and tree stack vertically in the left column, with a draggable splitter.

1.5 Below 1024 CSS px: single-pane mode (required, not optimized)

This is a desktop pro tool, but WCAG 1.4.10 Reflow still applies. A remediator with low vision may run 1280px at 400% zoom, which gives a 320px viewport. The tool must remain fully functional there, without being optimized for it.

• One view at a time. A view switcher (tablist: Task · Tree · Page · Reader · Inspector · Issues · History · Suggestions) sits under the app bar. Selection is shared, so choosing an item in Tree and switching to Page shows it selected and scrolled into view.
• The app bar collapses to: file name (truncated, with the full name in title and the accessible name), save state icon + text, and an overflow menu holding Undo, Redo, Save, Export and Palette.
• The canvas is a documented 1.4.10 exception (two-dimensional content). It pans in both directions inside its own scroll container, and the page itself never scrolls horizontally.
• The table grid editor is also a 2D exception. It scrolls inside its container and the header row and header column stay sticky.
• Below 1024px a dismissible notice appears once per session: “Tag Studio works best at 1024 pixels wide or more. All features remain available one view at a time.”
• There is no “unsupported” wall at any width.

1.6 Zoom, text spacing and motion

• Browser zoom (Mod+=, Mod+-, Mod+0) is never overridden. Canvas zoom has its own keys (§5).
• All UI text respects WCAG 1.4.12 text-spacing overrides. Truncation uses ellipsis plus a full-text accessible name, and never clips with overflow:hidden alone.
• prefers-reduced-motion: no animated scrolling on sync, no path-drawing animation, and the proposal “ghost” pulse is replaced by a static dashed style.
• Minimum UI font size 12px. Tree rows are 28px tall by default, with a comfortable density of 36px. Hit targets are ≥ 24×24 CSS px (WCAG 2.2 AA 2.5.8). Primary buttons are 44px.

---

2. Selection model and sync rules

2.1 What can be selected

A single shared selection holds either:

• Structure selection: a set of node IDs, or
• Content selection: a set of content-item refs (MCRs, OBJRs, orphan runs, artifact runs).

The two kinds never mix in one selection. If you shift-click an orphan while nodes are selected, the selection becomes content-only and the status bar says “Selection changed to content (3 items)”. This rule removes a whole class of ambiguous ops, such as “retype this orphan run”.

The selection also carries:

• a primary item, which is the last one added and is what the inspector shows;
• an anchor for Shift-range extension;
• a scope (page range) for select-similar and mode queues.

Selection lives in the session store, not in any view.

2.2 Focus is separate from selection

• Each view has its own focus (DOM focus or aria-activedescendant). Only the view the user is working in holds DOM focus.
• In the tree and canvas, selection follows focus by default: arrow keys move focus and set a single selection. With Ctrl (Windows/Linux) or Cmd (macOS) held, arrow keys move focus without changing selection, and Space toggles the focused item (APG multi-select convention).
• Other views reflect a selection change visually. They never take DOM focus and never announce it. Announcing mirror updates would double-speak every keystroke.

2.3 Sync rules

Source → Target	Rule
Any → Canvas	Highlights the bounding boxes of all content under each selected node. If the primary’s first content item is off-screen, scroll it into view (instant with reduced motion, otherwise 150ms). If any part of the primary is already visible, do not scroll. Multi-page selections show a page-strip badge ”+ on pages 4, 7, 12” with clickable links
Any → Tree	Expands ancestors of the primary and scrolls it into view (virtualized). Other selected rows are marked but not expanded to. If a selected node is hidden by the current filter, a non-modal bar above the tree says: “1 selected item is hidden by the filter. [Show it] [Clear filter]“
Any → Reader	Scrolls to the first utterance generated by the primary and outlines every utterance from selected nodes
Any → Inspector	Shows the primary. For a multi-selection it shows the shared fields; fields that differ show “Mixed (3 values)”. Editing a mixed field applies to all selected items as one group
Canvas click	Selects the innermost node that owns the clicked content. Clicking the same point again (within 600ms, or with Alt+click) walks up one ancestor per click, cycling back to the innermost after the root. A click on orphan content selects that orphan run (content selection). A click on artifact content selects the artifact run. Empty space clears the selection
Hover (pointer only)	A “peek” highlight in the other views, without changing selection and without any announcement. Keyboard users get the same peek on the focused row
After an op	Every op returns a result selection: wrap selects the new parent, unwrap selects the former children, retype keeps the node, artifact selects nothing and moves focus to the next item in the mode queue. Undo and redo restore the selection that was current before or after that op
Mode switch	The selection is kept if the new mode can show it. For example, a Figure selection carries into Figures mode and opens that figure in the queue. Otherwise it is kept but the mode shows “Your selection (H2) isn’t part of Figures. [Go to Headings]“
Page change	Paging the canvas does not clear the selection. The page strip shows where selected items live

2.4 Selection tools (pointer and keyboard parity)

Action	Pointer	Keyboard / non-drag alternative
Select one	Click	Arrow keys in tree or canvas
Add/remove	Mod+click	Mod+arrows then Space
Range	Shift+click (tree: row range; canvas: reading-order range)	Shift+arrows
Box select	Drag a marquee on empty canvas	Mark mode Alt+B: arrows move a crosshair, Enter sets the first corner, arrows (with Shift for ×10) size the box, Enter finishes. Each corner is announced as a percentage of the page (“Corner at 12% across, 30% down”)
Lasso	Shift+drag on empty canvas	Mark mode + L switches to a polygon: Enter adds a vertex, Mod+Enter closes it
Select text range	Drag across text	In the Reader, Shift+arrows extends across utterances, then “Select content” (Alt+Enter)
Select all on page	—	Mod+A in canvas (the page), or in tree (siblings of focus; press again for the whole visible tree)
Clear	Click empty space	Esc (first press closes any open popover, second press clears selection)

---

3. Operation vocabulary (what the UI emits)

The UI calls the engine only through these ops. Each has preconditions, an inverse, and a human-readable label template (i18n key ts.op.<name>.label). Ops are batched into groups when they come from one gesture.

Op	Args	Inverse	Notes
retype	node, newType	retype to old	Refused if the parent/child rules break (for example TD outside TR)
wrap	nodes[] (contiguous siblings), newType, attrs?	unwrap	Creates a parent
unwrap	node	wrap	Removes the node and promotes its children in place
move	node(s), newParent, index	move back	Used by drag, cut/paste and Alt+arrows
reorder	parent, permutation	inverse permutation	Reading-order edits within one parent
mergeNodes	a, b (same type, adjacent)	splitNode	For example a P split across a page break
splitNode	node, childIndex	mergeNodes
tagContent	contentRefs[], parent, index, type	untagContent	Orphan → new node
untagContent	contentRefs[]	tagContent	Leaves content orphaned (flagged)
splitContent	contentRef, glyphOffset	joinContent	Splits a marked-content sequence, for example a bullet glyph from list text. Engine phase 1
artifact	contentRefs[] | node, kind (Pagination/Layout/Page/Background), subtype? (Header/Footer/Watermark/PageNum)	unartifact	Artifacting a node artifacts all of its content and removes the node
unartifact	contentRefs[]	artifact	Content becomes orphan, then is tagged by a follow-up op in the same group
setAttr	node, key, value	setAttr old	Alt, ActualText, E, Lang, ID, Title; Table: Scope, Headers, RowSpan, ColSpan, Summary; List: ListNumbering; Layout: BBox, Placement; any owner/key in Raw mode
setAnnot	annot, key, value	old	Link /Contents, widget /TU (tooltip)
linkAnnot	annot, node	unlinkAnnot	Adds an OBJR; also sets /StructParent
setTabOrder	page, S|R|C	old	Forms and Links modes offer S (structure order), which PDF/UA requires
setDoc	key, value	old	Lang, Title, DisplayDocTitle, PDF/UA identifier (XMP), Suspects
setRoleMap / setClassMap	name, value | null	old	Raw mode
attest	issueKey, reviewer, note?	unattest	Records “reviewed by a human”. This changes the report, not the PDF. It is still in the op log so it can be undone and replayed

Every op is undoable, with no exceptions. Acrobat’s Content and Reading Order panels have no undo, and some axesPDF operations cannot be undone. In Tag Studio, an operation without a tested inverse cannot ship: the engine’s op registry rejects any op type that lacks one, and CI round-trips op → inverse on the corpus. This guarantee appears in the product copy and the help site.

Empty tags: “Remove empty tags” is a document-wide command (palette + Issues fix-all). It emits one group of unwrap ops on nodes with no content and no children (keeping TD/TH cells that hold a table shape, and Form nodes with widgets).

Group envelope (as seen in the history panel): { groupId, label, origin: user|fixAll|similar|ai|template|mode, ops[], selectionBefore, selectionAfter, validationDelta: {fixed, introduced}, at }.

---

4. Views

4.1 Page canvas

Rendering: a PDF page raster tiled at the current zoom, with a vector overlay layer (SVG) on top. In both themes the page is always drawn as printed; dark mode never inverts the page. Only the surrounding canvas background changes (bone #F7F5F1 in light, ink #0E1116 in dark).

Overlays (each can be toggled from the “Overlays” menu or the command palette; defaults are set per mode):

Overlay	Rendering	Default on in
Tag boxes	Stroke in the tag-family color and stroke pattern (§14), label chip at top-left (“H2”, “P”, “Fig”)	All modes
Reading-order path	Numbered ink badges (white number on #0E1116, with a white 2px ring) at each block’s start, joined by a 2px ink polyline with arrowheads. Page-to-page continuation shows ”→ p4”	Reading order, Raw
Orphans	Diagonal hatch fill in orphan color at 25% opacity, dashed stroke, and a ”!” glyph chip labelled “Untagged”	Always on; cannot be turned off while orphans exist (a toggle would hide a failure)
Artifacts	Dotted gray stroke, 40% white wash over the content, chip “Art”	Artifacts mode, Raw
Proposals	Dashed stroke in the target type’s color, chip “Suggested H2 · 92%“	Whenever the Suggestions queue has items for this page
Tab order	Numbered squares (as opposed to the round reading-order badges)	Forms, Links
Issues	Small severity glyph at the node’s top-right (✕ fail, ? review)	All modes

Filters: “Show only: [Headings] [Figures] [Tables] [Lists] [Links] [Forms] [Artifacts] [Untagged] [Issues]” (checkbox menu), and “Dim everything else” (on by default in guided modes).

Selection style: a 2px ink (#0E1116) stroke with a 2px white outer halo, plus 8×8 corner handles. This double stroke passes 3:1 against any page background. Keyboard focus on a canvas item uses the brand focus ring (3px solid #046307, 3px offset; #5CCB60 in dark mode) drawn outside the selection halo, so focus and selection are never confused. The palette excludes green (§14), so the focus ring is never mistaken for a tag color.

Canvas ARIA: role="application" with aria-roledescription="page canvas" and aria-label="Page 3 of 48". It is a single tab stop. Its content items are exposed through aria-activedescendant pointing into an offscreen role="listbox" mirror, in which each option’s name is the node announcement (§4.2.3). The listbox mirror lets screen readers announce the focused item without the SVG overlay needing an accessibility tree. The application role is justified because the canvas has custom 2D navigation. Its keys are listed in the help dialog (?), and aria-describedby gives a short key hint: “Arrow keys move between items in reading order; Alt plus arrows moves spatially; press question mark for all keys.”

4.2 Structure tree

4.2.1 Rows and columns

Each row shows: disclosure · tag chip (family color + pattern + text label) · content preview · issue badges · page number(s).

Content preview rules. “<MCID 12>” is never shown as a node’s preview.

Node	Preview
Text container	First 80 characters of its actual extracted text, whitespace collapsed; ActualText wins if set (shown with an “AT” marker)
Figure/Formula	32px thumbnail + alt text in quotes, or “No alt text” in the error style (text, not color only)
Table	”Table · 4 rows × 3 cols · 1 header row”
L	”List · 5 items · numbered”
Link	Link text + ”→ example.gov/budget”
Form widget	Field name + “Tooltip: …” or “No tooltip”
Content item (Raw mode only)	“Text: The fiscal ye…” / “Image 640×480” / “Annot: Link” and, in muted mono, MCID 12 · p3

4.2.2 ARIA pattern

• The container is role="treegrid" with aria-label="Structure tree", aria-multiselectable="true", aria-rowcount set to the total number of visible (expanded) rows, and aria-colcount="4".
• Each row is role="row" with aria-level, aria-setsize, aria-posinset, aria-expanded (only on rows that have children), aria-selected, and aria-rowindex, which is required because rows are virtualized.
• The cells are role="gridcell" for Tag, Content, Issues and Page. There is one tab stop, using roving tabindex on rows. Focus is on the row by default (APG treegrid “row-first” behavior). Right arrow on an expanded row moves into the cells, where Left and Right move between cells and Left from the first cell returns to the row.
• A row’s accessible name is built explicitly (aria-label on the row). The implementation does not rely on concatenated cells, because verbosity differs across screen readers.
• Virtualization renders the viewport ± 50 rows. Focus is never placed on a row that isn’t mounted, and the virtualizer mounts the target row before moving focus. This holds for 10k+ nodes.
• Drag and drop is pointer-only sugar. Every drop has a keyboard op (§5.3).

4.2.3 Row announcement text

Template (i18n ts.tree.row.name, ICU):

{tagSpoken}, {preview}{issues, select, 0 {} other {, {issues, plural, one {# issue} other {# issues}}: {firstIssue}}}{pages}

The level, set size and position come from the ARIA attributes, so the screen reader adds “level 3, 2 of 5”. The template must not repeat them. tagSpoken uses a spoken form, not the raw tag: “Heading 2”, “Paragraph”, “Figure”, “Table”, “List item”, “Artifact”. In Raw mode it becomes “H2 (Heading 2)”, so experts hear the literal tag.

Examples (NVDA-style rendering; the ARIA suffix is added by the AT):

• “Heading 2, Budget overview, 1 issue: heading level skipped from 1, page 3, level 3, 2 of 5, collapsed”
• “Figure, No alt text, 1 issue: missing alternate text, page 4, level 4, 1 of 3”
• “Paragraph, The fiscal year closed with…, page 3, level 3, 4 of 5, selected”
• “Untagged content, 3 runs, page 3” (orphan group pseudo-row, only in Raw mode and Reading order)

Rules for drop indicators:

• A 2px ink insertion line with a left circle marks “insert between” (sibling). A full-row outline with a 12% tint marks “insert as last child”.
• An illegal target shows a struck-through line and a tooltip giving the reason (“LI can only go inside L”).
• The drop position is also written as text in the status bar: “Move ‘Budget overview’ after ‘Table 1’, inside Sect”.

4.2.4 Search and filter

/ focuses the filter field above the tree. It accepts free text (matching previews) and facets, which are chips with autocomplete:

• type:Figure, has:alt, no:alt, issue:any, issue:<ruleId>, page:3-7, lang:fr, origin:ai, changed:session
• Saved presets: “Figures with no alt”, “Headings out of sequence”, “Empty tags”, “Tables without headers”, “Links without text”, “Untagged content”, “Changed this session”.

Filtering shows matching rows with their ancestor path as muted context rows (aria-level intact). A live count (“23 matches”) appears in a polite live region, debounced to 500ms.

4.3 Screen reader preview (Reader)

The Reader is a linear, virtualized list of utterances, one per announceable unit in structure order, rendered with the grammar in §4.3.2. It is role="list" inside a <section>, so it can be read with browse-mode or virtual-cursor navigation. It is deliberately not an application widget, so screen reader users can read it with their normal reading keys. Each utterance is a list item holding a button, “Edit …”, that jumps selection to the node and focuses the inspector field that produced the text.

Tabs: Reader (announcements) · Reflow (the document rendered as semantic HTML at the reading width, which shows what reflow and Liquid Mode would produce).

Verbosity profile selector: Generic (default) · NVDA-like · JAWS-like · VoiceOver-like. The profiles only change role words and ordering, for example “heading level 2” versus “heading 2” and whether the role comes before or after the name. A persistent caption reads: “Preview approximates what assistive technology announces. Always spot-check with a real screen reader.” We do not claim the preview is equivalent to a real screen reader.

4.3.1 Inline editing

Pressing Enter on an utterance’s Edit button opens an inline editor for the governing text:

• a figure edits Alt;
• a heading offers a level picker and ActualText;
• a link edits the annotation’s Contents;
• a text node with ActualText edits ActualText.

Mod+Enter commits the edit (as a setAttr op) and Esc cancels it. After a commit, the utterance re-renders and the new text is announced politely.

4.3.2 Announcement grammar (Generic profile)

Notation: {x} is a value, […] is optional, | separates alternatives. Strings are ICU templates in ts.reader.*.

Structure	Utterance
H1–H6	heading level {n}, {text}
H (unnumbered)	heading, {text} + flag “Unnumbered heading, level unknown to most AT”
P, Span, Quote, BlockQuote	{text} (BlockQuote: block quote, {text} … out of block quote)
L	list, {count, plural, one {# item} other {# items}} … out of list
LI	{Lbl} {LBody text}; nested list: list, {count} items, nesting level {depth}
Table	table with {rows} rows and {cols} columns [, {caption}] … out of table
TD (first visit to a row)	row {r}, {rowHeaders}, column {c}, {colHeaders}, {text}; later cells in the same row omit the row part
TH	{text}, column header | row header (from Scope)
Figure	graphic, {Alt}; missing Alt: graphic + flag “No alternate text; AT may read the file name or skip it”
Figure + Caption	graphic, {Alt} then {caption text}
Formula	math, {Alt}
Link	link, {text}; if annotation Contents differ: link, {text} + hint (description: {Contents})
Note	footnote, {text} (from a Note following a Reference)
Reference	{text}, link to note {n} when an ID/Ref pair resolves
TOC / TOCI	table of contents, list, {n} items / {text}
Form widget	{role: edit text|check box|radio button|combo box|button}, {TU}[, required][, {state}]; missing TU: {role}, unlabeled + flag
Lang change	{text} with a leading chip (French). Generic mode inserts the phrase “switches to French” once
E (expansion)	Speaks the expansion instead of the text, with a chip abbr
ActualText	Speaks ActualText instead of the content; chip AT
Artifact	Not announced. With the “Show skipped” toggle, a muted row reads (skipped: running header "Annual Report 2025")
Orphan	Not reliably announced. Shown as an error row “(untagged: may be read out of order or not at all) {text}“
Page boundary	A thin divider “page 4” (visual only; not an utterance)

Flags are rendered as text chips and linked to the Issues entry. They are never color-only.

4.4 Inspector

The inspector is a non-modal panel that always shows the primary selection. Sections are disclosure widgets (<details>-style buttons with aria-expanded):

1. Identity: Type (combobox of allowed types for this parent, with a type-ahead filter and invalid types shown disabled with the reason), page(s), node path breadcrumb (each crumb is a button that selects that ancestor).
2. Text alternatives: Alt, ActualText, E. There is a character counter, and lint hints appear inline below the field (“Starts with ‘image of’; AT already says ‘graphic’”).
3. Language: Lang (combobox of BCP 47 tags with names such as “French (fr)”; “inherit” shows the effective value “inherits en-US from Document”).
4. Type-specific: Table (scope, headers, IDs, spans, summary) · List (ListNumbering) · Link (Contents, target URL read-only) · Form (TU, field name read-only) · Note (ID).
5. Layout: BBox (x, y, w, h with units; a “Recompute from content” button), Placement.
6. Attributes (Raw mode, or when expanded): an owner/key/value table, plus + Add attribute.
7. Issues on this node: a mini-list linked to the Issues panel.

Commit rules: text fields commit on blur, Enter (single-line) or Mod+Enter (multi-line). Each commit is one setAttr op. Typing does not create an op per keystroke, and native text undo works inside the field until it is committed. Esc reverts the field to its committed value. A pending uncommitted edit is shown by a left border and the text “Not applied”.

Multi-selection: shared fields are editable and apply to all as one group (“Set Lang = fr on 12 nodes”). Fields that don’t apply to every selected type are hidden and a note lists them: “Alt applies to 3 of 12 selected; select Figures only to edit.”

Document (nothing selected, or root selected): Title, DisplayDocTitle, document Lang, PDF/UA identifier, Tab order summary, RoleMap and ClassMap counts (links to Raw mode).

---

5. Keyboard map

5.1 Conventions and conflict policy

• Mod means Ctrl on Windows/Linux and Cmd on macOS. When a binding says Ctrl literally it is Ctrl on every platform.
• No shortcut ever uses the NVDA key (Insert/CapsLock), the JAWS key (Insert/CapsLock), or the VoiceOver key (Ctrl+Option). No shortcut uses Ctrl+Alt+Arrows, which NVDA and JAWS use for table navigation, or Ctrl+Alt+<letter> / Ctrl+Alt+<digit>, which are AltGr combinations on European layouts (for example AltGr+Q = @ on German keyboards).
• No Alt+<letter> for the letters that open browser menus on Windows: D, E, F, H, S, T, V, B (Chrome: Alt+F/E, Alt+D address bar; Firefox: Alt+F/E/V/S/B/T/H; Edge: Alt+F).
• Browser zoom and tab keys are never captured: Mod+=, Mod+-, Mod+0, Mod+1..9, Mod+T/W/N, Mod+Tab, Mod+L, Mod+Shift+T, Mod+F (Find in page is left to the browser; our search is /).
• Alt+<letter> accelerators only fire when focus is in a non-text widget (tree, canvas, grid, queues). In text fields they are passed through, because macOS Option+letter types characters.
• Single unmodified letters are used only inside our own composite widgets, which screen readers switch into focus/forms mode automatically. They are never bound in the Reader, because that is a browse-mode document.
• The keymap can be customized (Settings → Keyboard). The editor refuses bindings from the reserved lists above and names the conflict: “Ctrl+Alt+Down is used by NVDA and JAWS to move down a table column.”
• ? (in a widget) or Mod+/ (anywhere) opens the keyboard help dialog, filtered to the current view and mode.

5.2 Global

Keys	Action	Notes
F6 / Shift+F6	Next / previous region (Mode rail → Task → Tree → Canvas → Reader → Inspector → Dock → App bar)	Browsers usually let pages capture F6; verify in usability testing (§16, scenario U14). Fallback: Mod+K “Go to …” and landmark navigation
Mod+K	Command palette (every command, mode and panel, with shortcut hints)	Palette is a combobox + listbox dialog
Mod+Z	Undo (group)	In a text field with uncommitted edits, native text undo runs instead
Mod+Shift+Z, Ctrl+Y (Win)	Redo
Mod+S	Save a version (runs the gate, §11). Edits sync continuously anyway; Save makes a verified PDF version	preventDefault of the browser’s Save Page
Mod+Shift+S	Save as new version with a note
Mod+Enter	Commit / Accept (context: inspector field, proposal, fix preview, mark-mode)
Esc	Close popover → cancel inline edit → clear selection (one per press)	NVDA may also switch from focus to browse mode on Esc; focus stays put (see §5.6)
Mod+/	Keyboard help
Mod+I	Toggle inspector drawer (compact layouts); focus inspector (wide)	Firefox Ctrl+I = Page Info; captured only when focus is inside the app. Palette alternative “Go to Inspector”
Mod+Shift+. / Mod+Shift+,	Next / previous mode	Ordering follows the rail
Alt+PageDown / Alt+PageUp	Next / previous issue in the whole document (selects the node, announces the issue)
Mod+Shift+J	Jump to page… (dialog with number field)	Chrome Ctrl+Shift+J = DevTools console on Windows. Conflict, see §5.6; palette “Go to page” is the primary route

5.3 Structure tree (focus in treegrid)

Keys	Action	Op
↑ / ↓	Previous / next row (selection follows)	—
→	Expand; if expanded, move to first child; with cell focus, next cell	—
←	Collapse; if collapsed, move to parent	—
Home / End	First / last visible row	—
PageUp / PageDown	± one viewport	—
*	Expand all siblings (APG)	—
Mod+↑/↓	Move focus without changing selection	—
Space	Toggle selection of the focused row	—
Shift+↑/↓, Shift+Home/End	Extend selection	—
Mod+A	Select siblings; press again to select all visible	—
Printable character	Opens the inline Retype combobox seeded with that character (like typing into a spreadsheet cell). Enter commits, Esc cancels. Only types allowed under the parent are listed	retype
F2 / Enter	Open Retype with the current type	retype
Alt+↑ / Alt+↓	Move node up / down among siblings	move
Alt+←	Promote (outdent: become next sibling of parent)	move
Alt+→	Demote (indent: become last child of previous sibling)	move
Ctrl+[ / Ctrl+]	Promote / demote (alternative for Alt+←/→, see conflict C1)	move
Mod+X then Mod+V	Cut then paste after the focused row; Mod+Shift+V pastes as last child. Cut rows are dimmed until pasted or Esc. Nothing is removed until the paste	move
Alt+W	Wrap the selection in a new parent (type prompt)	wrap
Delete	Unwrap (remove the tag and keep its children and content)	unwrap
Shift+Delete	Mark as artifact (kind prompt with a sensible default)	artifact
Alt+M / Alt+P	Merge with next sibling / split at focused child	mergeNodes / splitNode
Alt+L	Select similar (§8)	—
Alt+I	Focus the issue badge of this row / open its issue	—
/	Focus filter field	—
Alt+R	Find on page: reveal on canvas (scroll only; ignores the “don’t scroll if visible” rule)	—

5.4 Canvas (focus in page canvas)

Keys	Action	Op
↑/↓ or ←/→	Previous / next item in reading order (the path numbers)	—
Alt+arrows	Spatial move to the nearest item in that direction	—
Alt+Shift+↑	Select parent (walk up); Alt+Shift+↓ back to child	—
Space, Shift+arrows, Mod+A	Toggle, extend, select all on page	—
PageDown / PageUp	Next / previous page	—
+ / - / 0 / 1	Canvas zoom in / out / fit page / 100% (unmodified; browser zoom untouched)	—
Alt+B	Mark mode (keyboard box select, §2.4); L inside switches to lasso	—
Printable character (with a content or box selection)	Tag as… type-ahead combobox (“h2”, “fig”, “p”). Enter applies	tagContent / retype / wrap
Enter	Open Tag as… with the suggested type	same
Shift+Delete	Artifact	artifact
Delete	Untag (content becomes orphan). Asks for confirmation the first time per session, because it creates failures	untagContent
Alt+L	Select similar	—
O	Cycle overlay preset (All · Mode default · Issues only · None but orphans)	—
N	Toggle reading-order numbers	—
Alt+R	Find in tree: reveal the focused item’s node in the tree (expands ancestors, clears a filter that hides it after asking)	—

Find works in both directions (page → tree and tree → page) and is also on each view’s context menu, so neither view ever loses track of the other. This is the Acrobat problem where the reading-order view desyncs from the tree.

5.5 Mode-specific keys

These apply only while focus is in that mode’s task panel or grid. Every one is also a visible button.

Mode	Keys
Reading order	Alt+↑/↓ move block; Alt+C “click-sequence” tool (then Enter on canvas items in the new order; Mod+Enter finish); Alt+1..3 apply 1/2/3-column heuristic (proposal)
Headings	1–6 set level of focused outline row; Alt+←/→ promote/demote level; 0 demote heading to paragraph (P)
Figures	Mod+Enter save alt & next; Alt+N next without saving; Alt+A mark decorative (artifact); Alt+G request AI suggestion
Tables (grid)	Arrows move cell; Shift+arrows range; Alt+C toggle column header; Alt+R toggle row header; Alt+M merge cells; Alt+P split cell; Alt+Y cycle Scope (Column/Row/Both); Alt+J edit Headers/IDs for cell
Artifacts	Space toggle group; Alt+A artifact selected groups; Alt+U un-artifact; Alt+X exclude page from group
Lists	Alt+W make list from selection; Alt+→/← nest/unnest item; Alt+N cycle numbering
Links	Mod+Enter save & next; Alt+G AI description
Forms	Alt+↑/↓ move in tab order; Mod+Enter save tooltip & next
Notes	Alt+K link reference ↔ note
Language	Alt+G detect languages (proposal)
TOC	Alt+G generate from headings (proposal)
Suggestions dock	Mod+Enter accept; Alt+X reject; Alt+E edit then accept; ↓/↑ next/prev proposal
Issues dock	Enter go to node; Alt+F apply first fix; Alt+Shift+F fix all like this (preview)

Alt+F is on the Windows reserved list. Exception: in the Issues dock it is captured only while focus is on an issue row (a non-text widget), where Chrome/Firefox menu activation is suppressed by preventDefault. It is listed as conflict C3 in case testing disproves this.

5.6 Screen reader and browser conflicts

#	Binding	Conflicts with	Resolution	Status
C1	Alt+← / Alt+→ (tree promote/demote)	Windows browser Back/Forward. macOS Option+←/→ = word navigation (only in text fields, which we skip)	Captured only in the treegrid with preventDefault. A beforeunload guard protects unsaved work if capture fails. Alternative keys Ctrl+[ / Ctrl+] are always available	Resolved with alternative; verify Firefox capture
C2	F6 region cycle	Chrome/Edge/Firefox use F6 to focus the address bar	Pages can intercept F6 keydown in current Chromium and Gecko; if not, users fall back to Mod+K “Go to …” and landmarks	Unverified — test U14
C3	Alt+F in Issues dock	Chrome/Edge/Firefox File/app menu	Captured only on issue rows. The button “Fix” is always adjacent	Unverified — may need rebinding to Alt+Enter
C4	Mod+Shift+J jump to page	Chrome/Edge DevTools console (Windows/Linux)	Primary route is palette “Go to page”; binding is user-rebindable	Unresolved — no universally free combo; kept for macOS only (Cmd+Shift+J free in Safari/Chrome mac), off by default on Windows
C5	Mod+I	Firefox Page Info (Ctrl+I)	Captured only when focus is in the app; palette alternative	Resolved
C6	Printable-character retype / tag-as	NVDA and JAWS browse-mode single-letter navigation (H, T, L, F, K, B …); VoiceOver Quick Nav single-key mode	The tree and canvas are composite widgets (treegrid, application), so NVDA/JAWS switch to focus/forms mode automatically. VoiceOver users with single-key Quick Nav on must turn it off (VO+Q / Quick Nav toggle); the tree’s aria-describedby hint says so on first focus per session. Accidental retype is harmless: nothing commits without Enter	Resolved with a hint; verify in U10
C7	Arrow keys in tree/canvas	VoiceOver arrow Quick Nav (Left+Right toggles) intercepts arrows	Same hint as C6. With Quick Nav off, VO passes arrows to the widget	Documented
C8	Esc	NVDA: Esc in auto focus mode can drop to browse mode	Our handler still runs (NVDA passes the key on). Focus stays on the same element, so Space/Enter or NVDA+Space returns to focus mode. No action is lost	Documented; test U10
C9	Mod+Shift+. / , mode cycling	None known (Chrome/Firefox free; macOS Cmd+Shift+. = show hidden files, only in file dialogs)	—	Resolved
C10	Alt+number (reading-order columns)	Firefox on Linux: Alt+1..9 switches tabs	Only in the Reading order task panel; buttons adjacent; rebindable	Partially unresolved on Linux Firefox
C11	Ctrl+Y redo (Windows)	Firefox Windows: none; Chrome: History on some builds (Ctrl+H, not Y)	—	Resolved
C12	* expand all	JAWS: none in forms mode; NVDA: none in focus mode	—	Resolved

---

6. Task modes

Every mode has the same frame:

• Task panel (left): a queue or outline, with a progress meter (“14 of 23 figures reviewed”) in text and a <progress> element.
• Canvas (center): the mode’s overlay preset, with items outside the mode dimmed.
• Inspector (right): trimmed to the fields the mode needs, with a “More properties” disclosure.
• Done criteria: the mode’s rail badge turns to a check with text (“Figures: done”) when there are 0 failures in that category. It never shows a check while Needs-review items remain unattested. It shows “Figures: 3 to review” instead.

Mode switching never loses the selection or the undo history. Each mode’s first visit shows a dismissible 2-line explainer (not a tour).

6.1 Reading order

Goal: the top-level structure order matches the logical reading sequence on every page, and there are no orphans.

┌────┬───────────────────────────────┬────────────────────────────────────────┬──────────────────────┐
│▶RO │ READING ORDER     page 3 of 48│  ◀ p3 ▶   Path ●  Numbers ●            │ INSPECTOR            │
│ Hd │ ⚠ Possible column interleave  │ ┌────────────────────────────────────┐ │ P · page 3           │
│ Fg │   [Apply 2-column order]      │ │ ①━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓      │ │ Order: 4 of 9        │
│ Tb │ ┌───────────────────────────┐ │ │ ┌─────────────┐  ┌─────────────┐   │ │ Continues on p4? [ ] │
│ Ar │ │ ≡ 1 H1 Annual Report 2025 │ │ │ │②  col A     │  │④  col B     │   │ │                      │
│ Ls │ │ ≡ 2 P  The fiscal year…   │ │ │ │  ↓          │  │  ↓          │   │ │ [Merge with next ▸]  │
│ Lk │ │ ≡ 3 P  Our revenue…     ◀ │ │ │ │③            │  │⑤            │   │ │                      │
│ Fm │ │ ≡ 4 P  Expenses fell…     │ │ │ └─────────────┘  └─────────────┘   │ │                      │
│ Nt │ │ ≡ 5 Figure  "Bar chart…"  │ │ │ ░░ page footer "3" (untagged) ░░ ⚠ │ │                      │
│ La │ └───────────────────────────┘ │ └────────────────────────────────────┘ │                      │
│ TC │ Untagged on this page: 1 [▸]  │ [Click-sequence ✎] [Tag as… ] [Artifact]│                      │
│ {} │ [◀ Prev page]   [Next page ▶] │                                        │                      │
└────┴───────────────────────────────┴────────────────────────────────────────┴──────────────────────┘

Steps:

1. Enter the mode. The queue opens on the first page with an order issue, or on page 1. A detector flags likely problems: column interleave, a z-order-driven sequence (a caption read before its figure), a top-to-bottom sweep across columns, and orphans. These appear as banners with actions.
2. Review the path. The numbered path is drawn on the canvas. The task panel lists the page’s top-level blocks in order, and each row has a drag handle (≡) and a position number.
3. Fix order, using any of these:
   • Drag rows in the list, or blocks on the canvas → one reorder(parent, perm).
   • Alt+↑/↓ on a row → move (one position), announced as “Moved to position 3 of 9”.
   • Click-sequence tool (Alt+C): click (or press Enter on) blocks in the intended order. The badges renumber live as you go. Mod+Enter commits → one reorder group; Esc abandons with no op. Blocks you didn’t click keep their relative order after the sequenced ones, and a notice says so.
   • Tag as List: when blocks in the sequence (or a canvas box selection) look like list items, “Tag as…” offers List, which runs the Lists-mode “Make list” group (§6.6), including nesting by indent. Acrobat’s reading-order tool has no List type.
   • Apply N-column order banner → a proposal group of reorder ops, previewed as a ghost path until accepted.
4. Resolve orphans: “Untagged on this page” expands to a list of orphan runs. For each run, choose “Tag as…” → tagContent(refs, parent, index, type) at the position implied by its location, or “Artifact” → artifact(refs, kind).
5. Cross-page continuity: if a block continues on the next page, the “Continues on p4” checkbox → mergeNodes(a, b) (a paragraph split by a page break becomes one P).
6. Tab order (end of mode): if any page has annotations and /Tabs ≠ S, a banner offers “Use structure order for Tab key on all pages” → group of setTabOrder(page, S).
7. Review attestation: reading-order meaning cannot be machine-verified. Each page shows “Reading order on this page: Needs review · [Mark reviewed]” → attest(ro:page3). The page queue shows reviewed pages with a check and the reviewer’s initials.

Ops emitted: reorder, move, mergeNodes, tagContent, artifact, setTabOrder, attest.

6.2 Headings

Goal: a logical heading hierarchy with no skipped levels, where every visually-heading text is tagged as a heading and nothing non-heading is.

┌────┬──────────────────────────────────┬──────────────────────────────────┬────────────────────┐
│ RO │ HEADINGS OUTLINE                 │ ◀ p3 ▶  Headings only ●          │ INSPECTOR          │
│▶Hd │ Level  Text                 Page │ ┌──────────────────────────────┐ │ H3 · page 3        │
│ Fg │ [1]  Annual Report 2025       1  │ │ ━━[H1]━━━━━━━━━━━━━━━━━━━━   │ │ Level ① ② ●③ ④ ⑤ ⑥ │
│ Tb │ [2]    Message from the CEO   2  │ │ ━━[H2]━━━━━━━━━━             │ │   ⚠ Skips level 2  │
│ Ar │ [3] ✕    Budget overview      3◀ │ │ ━━[H3]━━━━━  ◀               │ │ Font: Archivo 18 B │
│ Ls │ [2]    Operations             5  │ │ ┈┈┈ Revenue (P, looks like  │ │ Similar looking: 6 │
│ Lk │ [ ] ?  "Revenue" (P) looks    3  │ │     a heading)  [Make H3]     │ │ [Select similar]   │
│ Fm │        like a heading [H3▾]      │ └──────────────────────────────┘ │                    │
│ Nt │ Doc title: [Annual Report 2025]  │                                  │                    │
│ La │ Level map: 24pt→H1 18pt→H2 14→H3 │                                  │                    │
└────┴──────────────────────────────────┴──────────────────────────────────┴────────────────────┘

Steps:

1. The outline lists every H/H1–H6 in document order, indented by level, with a level chip (number + “H” + indentation, never color alone). Skipped levels show a ✕ and the text “Skips level 2”.
2. Candidate headings: a detector clusters text by visual signature (font, size, weight, spacing before) and lists P nodes that look like headings as ”?” rows with a suggested level.
3. Set levels by pressing 1–6 on an outline row, using the inspector’s level radio group, or using Alt+←/→ for relative moves → retype(node, Hn). 0 → retype(node, P).
4. Level map (optional): “Apply level map” assigns levels by font-size cluster across the whole document → a proposal group of retype ops for review (see §9 for how proposals are shown).
5. Select similar from any heading applies the same level to everything that looks like it → one retype group.
6. Document title: prefilled from the first H1. Commit → setDoc(Title) + setDoc(DisplayDocTitle, true).
7. Optional sectioning: “Wrap sections under headings” → proposal group of wrap(nodes, Sect). Off by default, because PDF/UA does not require it.
8. Attest: “Heading text describes its section: Needs review” → attest(headings:doc).

Ops: retype, setDoc, wrap, attest.

6.3 Figures

Goal: every Figure has meaningful Alt or is artifacted as decorative, with a caption association and a BBox.

┌────┬──────────────────────────────┬──────────────────────────────────────┬────────────────────┐
│ RO │ FIGURES   14 of 23 reviewed  │  ┌──────────────────────────────┐    │ FIGURE 15 · p12    │
│ Hd │ ▓▓▓▓▓▓▓▓▓▓░░░░░              │  │                              │    │ ( ) Informative    │
│▶Fg │ Filter: [Needs alt ▾]        │  │      [ large figure crop ]   │    │ ( ) Decorative →   │
│ Tb │ ┌──────────────────────────┐ │  │                              │    │     artifact       │
│ Ar │ │ ▣ 13 Logo (decorative) ✓ │ │  └──────────────────────────────┘    │ ( ) Text in image →│
│ Ls │ │ ▣ 14 "Bar chart of…"   ✓ │ │  Context before: "…grew 12% as shown │     ActualText     │
│ Lk │ │ ▣ 15 No alt text   ✕   ◀ │ │  below." Caption: "Figure 3: Revenue │ Alt text           │
│ Fm │ │ ▣ 16 No alt text   ✕     │ │  by quarter"                         │ [                 ]│
│ Nt │ │ ▣ 17 "image1.png"  ✕     │ │                                      │ [                 ]│
│ La │ └──────────────────────────┘ │  ✦ Suggestion (High, 91%): "Bar chart│ 0/250 · lint: —    │
│ TC │                              │  of revenue by quarter; Q4 highest at│ Caption: [Linked ✓]│
│ {} │                              │  $4.2M." Reason: chart with legible  │ [Save & next ⌘↵]   │
│    │                              │  axis labels. [Use] [Edit] [Dismiss] │ [Skip]             │
└────┴──────────────────────────────┴──────────────────────────────────────┴────────────────────┘

Steps:

1. The queue holds every Figure/Formula node plus image content that is not a Figure (orphan images, and images tagged P), grouped by status: Needs alt · Suspicious alt (file name, “image”, single word, over 250 characters, or identical to nearby text) · Has alt (needs review) · Reviewed · Decorative. The default filter is “Needs attention”.
2. The focused figure shows a large crop plus context (the text before and after in reading order, and the detected caption).
3. Choose its role (radio group):
   • Informative → setAttr(Alt) (+ retype(node, Figure) if it wasn’t one; + tagContent if it was orphan)
   • Decorative → artifact(node, Layout)
   • Text in image → setAttr(ActualText) (retype to P/Span where appropriate)
   • Math → retype(Formula) + setAttr(Alt)
4. Alt text field: live lint for “image of”, “picture of”, file names, duplicated caption text (hint: “Caption already read; alt can be shorter”), or length > 250 (hint to use a long description in adjacent text).
5. Caption: if a Caption node is detected nearby, “Linked ✓” means it is a child of the Figure, or Figure and Caption are wrapped together. “Link caption” → move(caption, figure, 0).
6. BBox is computed automatically on save of Alt if missing → setAttr(BBox) in the same group.
7. AI assist: Alt+G or “Suggest” → proposal inline (§9). “Use” puts the text into the field unapplied; Mod+Enter commits it as origin ai-accepted (or ai-edited if changed).
8. List view (bulk, the Grackle-style alt-text panel): a toggle above the queue switches to a grid with the columns thumbnail · page · role · Alt (editable) · lint · AI band. Arrow keys move between cells, Enter edits, and Mod+Enter commits a cell. Each commit is its own setAttr group, so undo stays granular. Sorting by page or lint lets a remediator sweep 200 figures without opening each one.
9. Mod+Enter = save + next. Saving counts as a human attestation of this figure’s alt (the person read the image and wrote or accepted the text), so no separate attest is needed. The history records who saved it.

Ops: setAttr(Alt|ActualText|BBox), retype, tagContent, artifact, move.

6.4 Tables

Goal: a correct Table/TR/TH/TD structure, header cells with Scope (simple tables) or Headers/IDs (irregular tables), correct spans, and optional THead/TBody/TFoot.

┌────┬─────────────────────────┬────────────────────────────────────────────────────┬──────────────────┐
│ RO │ TABLES   2 of 6 done    │ TABLE GRID · Table 3 · page 7   [Grid ● | Canvas]  │ CELL B1          │
│ Hd │ ✓ Table 1  p3  4×3      │      ┌──────────┬──────────┬──────────┬─────────┐  │ Type  (●)TH ( )TD│
│ Fg │ ✓ Table 2  p5  6×4      │      │    A     │    B     │    C     │    D    │  │ Scope [Column ▾] │
│▶Tb │ ✕ Table 3  p7  5×4    ◀ │ ┌────┼──────────┼──────────┼──────────┼─────────┤  │ ID    [t3-b1   ] │
│ Ar │ ? Table 4  p9  12×6     │ │ 1 ▤│ Region ▤ │[Q1   ▤] ◀│ Q2     ▤ │ Q3    ▤ │  │ Spans ↔1 ↕1      │
│ Ls │ ✕ Table 5  p9  3×2      │ ├────┼──────────┼──────────┼──────────┼─────────┤  │ Headers (auto)   │
│ Lk │ ? Table 6  p14 2×2      │ │ 2  │ North ▥  │ 4.1      │ 4.3      │ 4.8     │  │                  │
│ Fm │                         │ │ 3  │ South ▥  │ 3.2      │ 3.0      │ 3.9     │  │ Announces as:    │
│ Nt │ Structure: THead ✓      │ │ 4  │ East  ▥  │ 2.7   ╎merged╎ 2.9  │ 3.1     │  │ "row 2, North,   │
│ La │ Header rows: [1]        │ └────┴──────────┴──────────┴──────────┴─────────┘  │  column Q1, 4.1" │
│ TC │ Header cols: [1]        │ ▤ column header  ▥ row header  ╎ span              │                  │
│ {} │ Pattern: Simple (Scope) │ [Header row] [Header col] [Merge] [Split] [Headers/IDs…] │ [Preview row ▶]│
└────┴─────────────────────────┴────────────────────────────────────────────────────┴──────────────────┘

Steps:

1. Pick a table from the queue. Detection covers Table nodes and table-like orphan or P regions, which get “Make table” → a proposal that builds wrap(Table), wrap(TR) and tagContent(TD) groups from the detected grid.
2. The grid editor replaces per-cell properties dialogs. Every header, scope, span and Headers/ID edit happens in place, and bulk selection of rows, columns or ranges applies TH/TD and Scope in one group. It is an ARIA grid built from the structure (rows = TR, cells = TH/TD with spans resolved). It can toggle between an abstract grid and “Canvas”, which draws the grid over the page. Header cells are marked by a glyph (▤ column header, ▥ row header) and a bold label, in addition to the fill.
3. Header rows/columns: set the count on the task panel spinbutton or with Alt+C/Alt+R on a cell → retype(TD→TH) and setAttr(Scope) for each cell as one group. If the table has no THead, “Put header rows in THead” (default on) → wrap(rows, THead) + wrap(rest, TBody).
4. Spans: select a range and press Alt+M (Merge) → setAttr(ColSpan/RowSpan) on the surviving cell + move content from the absorbed cells + unwrap of the empty cells. This is refused if the absorbed cells hold content that would change reading order, and the refusal explains why. Alt+P (Split) reverses it.
5. Pattern detection: the task panel shows “Simple (Scope is enough)” or “Irregular: needs Headers/IDs”. Irregular tables have multi-level headers, spanning headers, or headers mid-table. For irregular tables, “Generate Headers/IDs” → group of setAttr(ID) on all TH plus setAttr(Headers) on all TD, computed from the grid. The per-cell editor (Alt+J) is a checklist of all TH cells in the table, where ticking one adds its ID.
6. Split/merge tables: a table that continues across a page break → “Merge with Table 4 (p8)” (mergeNodes, then unwrap of the duplicated header rows, which become artifacts via artifact when they repeat). “Split table here” → splitNode.
7. Announcement preview: the inspector’s “Announces as” shows the Reader grammar for the focused cell. “Preview row ▶” plays the whole row into the live region. Screen reader users hear the same string by pressing Alt+Q.
8. Flatten layout table: “This is a layout table” → unwrap of Table/TR/TD down to their content (proposal preview first), because PDF/UA has no layout-table role.
9. Attest: “Header associations are correct: Needs review” → attest(table:t3).

Ops: retype, setAttr(Scope|ID|Headers|RowSpan|ColSpan|Summary), wrap, unwrap, move, mergeNodes, splitNode, tagContent, artifact, attest.

6.5 Artifacts

Goal: running headers and footers, page numbers, decorative rules, backgrounds and watermarks are artifacted, and real content is not.

┌────┬──────────────────────────────────────┬───────────────────────────────────┬──────────────┐
│ RO │ REPEATING CONTENT (detected)         │ Page strip:  1 2 3 4 5 … 48        │ GROUP        │
│ Hd │ [✓] Header "Annual Report 2025"      │ ┌─────┐┌─────┐┌─────┐┌─────┐      │ Header       │
│ Fg │     top band · 46 of 48 pages   ◀    │ │▀▀▀▀▀││▀▀▀▀▀││▀▀▀▀▀││     │ …    │ Kind [Pagin▾]│
│ Tb │     ▢▢▢▢▢▢▢▢▢▢ thumbnails            │ │     ││     ││     ││ p4  │      │ Sub  [Header▾│
│▶Ar │ [✓] Page number  "{n}"  bottom-right │ │  ▄  ││  ▄  ││  ▄  ││excl.│      │ 46 pages     │
│ Ls │     48 of 48 pages                   │ └─────┘└─────┘└─────┘└─────┘      │ Excluded: p4 │
│ Lk │ [ ] Logo image (same XObject)        │ ▀ header band   ▄ page number     │ (title page) │
│ Fm │     top-left · 47 of 48              │                                   │ [Include p4] │
│ Nt │ [ ] Horizontal rule · 48 pages       │                                   │              │
│ La │ ── Already artifacts: 212 runs [▸]   │                                   │              │
│ TC │ ── Tagged but looks like artifact: 3 │                                   │              │
│ {} │ [Artifact 2 selected groups]         │                                   │              │
└────┴──────────────────────────────────────┴───────────────────────────────────┴──────────────┘

Steps:

1. Detection runs on entry (with progress if > 2s). Content is grouped by signature: position band (top/bottom 12%, margins), normalized text (digits → {n}, so “Page 3 of 48” matches), image XObject identity, and vector path hash. Groups list a sample, coverage (“46 of 48 pages”) and thumbnails.
2. Review a group: selecting it highlights every instance on the page strip and canvas. Pages where the item is missing or differs are listed. Individual pages can be excluded (Alt+X), for example a title page where “Annual Report 2025” is real content.
3. Apply: “Artifact N selected groups” → one group of artifact(refs, Pagination, Header|Footer| PageNum) (or Layout/Background for rules and images). This includes untagContent/unwrap for instances that were wrongly tagged (for example P “3” per page), all in the same group.
4. Reverse check: “Tagged but looks like artifact” and “Artifacted but looks like content” (text in the body band, over 20 words, or a heading-sized font inside an artifact) are listed for review → artifact / unartifact + tagContent.
5. The Already artifacts browser can unartifact anything.

Ops: artifact, unartifact, untagContent, unwrap, tagContent.

6.6 Lists

┌────┬──────────────────────────────┬─────────────────────────────────────┬─────────────────┐
│▶Ls │ LISTS                        │ ┌─────────────────────────────────┐ │ LIST · p6       │
│    │ ✓ List 1 p2 · 4 items · •    │ │ [L]┏━━━━━━━━━━━━━━━━━━━━━━━━━┓  │ │ Numbering       │
│    │ ✕ Looks like a list p6 ◀     │ │    ┃[Lbl]• [LBody]Reduce cost┃  │ │ [Disc ▾]        │
│    │   5 paragraphs start with •  │ │    ┃[Lbl]• [LBody]Grow sales ┃  │ │ Items 5         │
│    │   [Make list]                │ │    ┃   [Lbl]– nested item    ┃  │ │ Nested lists 1  │
│    │ ? List 3 p9 · Lbl missing    │ │    ┗━━━━━━━━━━━━━━━━━━━━━━━━━┛  │ │ Announces: "list│
│    │   [Split labels]             │ └─────────────────────────────────┘ │ 5 items"        │
└────┴──────────────────────────────┴─────────────────────────────────────┴─────────────────┘

Steps:

1. The queue holds existing L nodes with issues (LI outside L, missing Lbl/LBody, flat lists that look nested) plus candidates: runs of sibling P that start with a bullet glyph, numbering pattern or hanging indent.
2. Make list: select the items (the candidate pre-selects them) → one group: wrap(items, L), a wrap(item, LI) for each item, splitContent at the label boundary, tagContent(Lbl) + tagContent(LBody), and setAttr(ListNumbering) inferred from the glyph (•→Disc, 1.→Decimal, a.→LowerAlpha).
3. Nest: Alt+→ on an item → move into a new or existing sub-L inside the previous LI’s LBody. Alt+← unnests.
4. Split labels for lists that lack Lbl → splitContent + tagContent for each item. If the label cannot be split without changing the content stream (a glyph shared in one text show operator), the op is refused and “Keep label inside LBody” is offered, which is valid under PDF/UA.
5. Numbering: Alt+N cycles → setAttr(ListNumbering).

Ops: wrap, splitContent, tagContent, setAttr(ListNumbering), move, unwrap.

6.7 Links

┌────┬──────────────────────────────────────┬──────────────────────────┬────────────────────┐
│▶Lk │ LINKS  31 · 4 need attention         │  canvas: link boxes      │ LINK · p11         │
│    │ ✕ "click here"  → gevell.com/…  p11◀ │  numbered in tab order   │ Link text (tagged) │
│    │ ✕ (no tagged text) annot only   p12  │                          │ "click here"       │
│    │ ? "https://example.gov/…" (raw URL)  │                          │ ⚠ Not descriptive  │
│    │ ✓ "Budget portal"               p3   │                          │ Description (Cont.)│
│    │ Tab order: 3 pages not structure [Fix]│                         │ [Budget portal    ]│
│    │                                      │                          │ [Save & next ⌘↵]   │
└────┴──────────────────────────────────────┴──────────────────────────┴────────────────────┘

Steps:

1. The queue lists every Link annotation, joined with its tagged text. Issues: annotation with no Link node (the OBJR is missing), a Link node with no annotation, a Link without text, generic text (“click here”, “more”, “link”), a raw URL, and the same text pointing to different targets.
2. Missing structure: “Tag link” → wrap(textRuns, Link) + linkAnnot(annot, node). The text runs are found under the annotation rectangle, and you can adjust them with Mark mode.
3. Description: edit the annotation’s Contents → setAnnot(Contents). This is recommended when the visible text is not descriptive (visible text can’t be changed without altering the page).
4. Tab order: the banner → setTabOrder(page, S) group.

Ops: wrap, linkAnnot, unlinkAnnot, setAnnot(Contents), setTabOrder.

6.8 Forms

┌────┬─────────────────────────────────────┬───────────────────────────┬──────────────────────┐
│▶Fm │ FORM FIELDS  18 · tab order ▾       │ ┌───────────────────────┐ │ FIELD "applicant_nm" │
│    │ ≡ 1 Name          ✓ "Full name"     │ │ [1]Name  [____]       │ │ Type: text           │
│    │ ≡ 2 DOB           ✕ no tooltip    ◀ │ │ [2]DOB   [____]  ◀    │ │ Tooltip (TU)         │
│    │ ≡ 3 Email         ✓ "Email address" │ │ [3]Email [____]       │ │ [Date of birth, MM/DD│
│    │ ≡ 4 Agree [x]     ? "Check"(vague)  │ │ [4][x] I agree        │ │ Required: yes (read) │
│    │ Tab order = structure order ✓       │ └───────────────────────┘ │ Announces: "edit     │
│    │                                     │ ■ = tab stop number       │ text, Date of birth, │
│    │                                     │                           │ required"            │
└────┴─────────────────────────────────────┴───────────────────────────┴──────────────────────┘

Steps:

1. List every widget in the current tab order (numbered squares on the canvas). Issues: no TU, a TU that duplicates the field name (“Text1”), a widget missing a Form struct element/OBJR, and tab order ≠ structure order.
2. Tooltip: the field is prefilled with the nearest visible label text (suggestion, not applied). Commit → setAnnot(TU).
3. Structure: “Tag field” → tagContent/wrap(Form) + linkAnnot(widget, formNode) at the position of its label in reading order.
4. Tab order: drag or Alt+↑/↓ reorders the structure position of Form nodes (move), and setTabOrder(page, S) makes Tab follow it. The list mirrors the result immediately.

Ops: setAnnot(TU), wrap, tagContent, linkAnnot, move, setTabOrder.

6.9 Notes

1. Detect superscript reference markers and note bodies (small font, bottom band or end section).
2. For each pair: retype(body, Note) + setAttr(ID) (unique, required by PDF/UA) + optionally wrap(marker, Reference), then Alt+K links them (stored as a structure Ref/ID association). If the author made the marker a link, linkAnnot is used.
3. Placement: offer “Move note after its reference” → move (off by default; the reading-order trade-off is explained inline).

Ops: retype, setAttr(ID), wrap, move, linkAnnot.

6.10 Language

1. Document language: required. It is prefilled from metadata or detection and committed with setDoc(Lang).
2. Passages (Alt+G): a detector proposes spans whose language differs from the document’s, with a confidence level. Accept → setAttr(Lang) on the node, or wrap(runs, Span) + setAttr(Lang) for inline phrases.
3. Filter lang:* in the tree shows everything with explicit Lang.

Ops: setDoc(Lang), setAttr(Lang), wrap.

6.11 TOC

1. Detect an existing TOC page (dot leaders, page numbers, links).
2. “Structure TOC” → wrap(TOC), a wrap(TOCI) for each entry, and linkAnnot when entries are links. Nesting follows heading levels.
3. “Check against headings” compares TOC entries with H nodes (missing entries or mismatched text) and lists the differences for review. There is no auto-fix.
4. Bookmarks (Outlines) from headings: “Generate bookmarks” → setDoc(Outlines) (a document-level op, shown in the change report).

Ops: wrap, linkAnnot, setDoc(Outlines).

6.12 Raw tree (expert)

┌────┬──────────────────────────────────────────────────┬──────────────────────┬──────────────────────┐
│ {} │ RAW TREE          / type:Span lang:fr   [Contents]│ canvas               │ INSPECTOR (full)     │
│    │ ▾ StructTreeRoot                                 │                      │ Span · p8            │
│    │   ▾ Document                                     │                      │ Type [Span ▾] std    │
│    │     ▾ Part                                       │                      │ Lang [fr        ]    │
│    │       ▾ Art                                      │                      │ Attributes           │
│    │         P   Bonjour à tous…                      │                      │ Owner  Key   Value   │
│    │         ▾ Span (lang fr)                         │                      │ Layout BBox  […]     │
│    │             MCR  MCID 4 · p8  "Bonjour"          │                      │ [+ Add attribute]    │
│    │         OBJR Link annot · p8                     │                      │ ClassMap: —          │
│    │ RoleMap (3)  ClassMap (0)  ParentTree ✓  IDTree ✓│                      │ Raw: /S /Span /P 41 0│
└────┴──────────────────────────────────────────────────┴──────────────────────┴──────────────────────┘

• Every standard PDF 1.7 structure type is available in Retype, plus RoleMapped custom types (shown as “Custom → maps to P”).
• Content items (MCR/OBJR) are visible as leaf rows, and the Contents toggle hides or shows them.
• RoleMap editor: a table of custom → standard with validation (no cycles, and no mapping of standard types, which PDF/UA forbids) → setRoleMap. ClassMap editor → setClassMap.
• Attribute editor: any owner and key. Unknown keys are allowed with a warning.
• Read-only diagnostics: ParentTree and IDTree consistency, and the object number/generation for cross-reference with other tools.
• Raw mode still uses ops. There is no direct object editing.

---

7. Validation panel and fix-all

7.1 Model

• The engine validates incrementally. Each op returns a validationDelta, and a full pass runs in the background after open and after bulk groups. While results are stale, the summary chip reads “Checking…”, and it never shows old numbers as current.
• Each result has: ruleId (Matterhorn checkpoint, for example 13-004, and/or WCAG SC, for example 1.1.1), severity, node/content refs, message, and zero or more fixes.

Status vocabulary (text + icon shape + color; never color alone):

Status	Icon	Meaning
Fail	✕ in octagon	Machine-verified failure
Needs review	? in triangle	A human must judge. Never shown as passing
Reviewed	✓ with a person glyph, “Reviewed by LA · 09-28”	A human attested (an attest op)
Pass	✓ in circle	Machine-verified checkpoint only
Not applicable	—	For example, no tables in the document
Could not check	⊘	The check errored or the input is unsupported. Counted with failures in the summary (it is not a phantom pass)

7.2 Panel layout

┌───────────────────────────────────────────────┐
│ ISSUES  ✕ 12 fail · ? 31 review · ⊘ 0         │
│ Group by: [Rule ▾]  Show: [Fail ✓][Review ✓]  │
│ Scope: [Whole document ▾]                     │
│ ▾ ✕ Figure without alternate text (13-004,    │
│     WCAG 1.1.1) · 7                           │
│     [Fix all like this… (AI suggest)]         │
│     ✕ Figure p4 "chart" region      [Go][Fix▾]│
│     ✕ Figure p12                    [Go][Fix▾]│
│ ▾ ✕ Content not tagged (01-005) · 3           │
│     [Fix all like this…]                      │
│ ▾ ? Reading order logical (09-001) · 48 pages │
│     [Review in Reading order mode]            │
│ ▸ ✓ Document title set (07-001)               │
└───────────────────────────────────────────────┘

• Grouping: by Rule (default), Page, Mode, or Severity. Each group heading is an h3, and each issue row is a list item with a Go button (selects the node and moves focus to the canvas or tree, whichever was last used) and a Fix menu button.
• Selecting any node filters the panel to “Issues on selection” with a “Show all” toggle.
• The summary chip in the app bar is a button that opens the panel.
• Rules that need a human link to the mode that supports the review, rather than offering a fix.

7.3 Fix and fix-all flow

1. Fix (one issue): the menu lists the fixes the engine offers for that rule, with the exact op described (“Mark as artifact (Layout)”, “Tag as P under Sect”). Choosing one applies it as a group and announces “Fixed: Content not tagged, page 3. 11 failures remain.”
2. Fix all like this…: shown only when the fix is deterministic (no judgment needed), for example artifacting page numbers, setting Scope on first-row THs, setTabOrder(S), adding a missing BBox, or retyping H → Hn where the level is unambiguous. It opens a preview sheet inside the panel. The sheet is non-modal, and focus moves to its heading:
   • “Apply ‘Mark as artifact (Pagination/PageNum)’ to 47 issues on 47 pages”
   • a checklist of every instance (virtualized) with thumbnails; each can be unticked
   • a “Show on canvas” toggle that steps through instances (↓/↑)
   • a before/after validation delta: “Fixes 47 · introduces 0”
   • buttons: Apply to 47 (Mod+Enter) · Cancel
3. Apply → one group, origin fixAll, labelled “Fix all: artifact page numbers (47)”. One undo reverts all of them.
4. Judgment fixes (alt text, heading level meaning) have no Fix all. The group instead offers “Suggest for all (AI)…”, which routes to the Suggestions queue (§9) as proposals, never applied directly.
5. If some ops in a fix-all are refused (their preconditions fail), the others still apply, and the result says “Applied 45 of 47. 2 skipped: [view]” with each reason. Skipped items stay in the list.

---

8. Select similar

1. Start from any selection: Alt+L, the Similar dock tab, or the context menu → Similar tab opens, seeded with the primary’s signature.
2. Signature chips (toggle buttons with aria-pressed). The defaults on are marked with ●:
   • Visual: ● font family · ● size (±0.5pt) · ● weight/style · color · position band (top/bottom/left margin, column)
   • Structural: ● current tag type · parent type · depth · has alt / no alt
   • Content: text pattern (starts with bullet / number / “Figure N:” / all caps / same text), same image XObject, size ±10%
   • Scope: this page · page range · whole document (default)
3. The live result shows “43 matches on 12 pages” (polite announcement, debounced), a list of matches with page and preview, and canvas highlights with the “Dim everything else” style. Each match has an exclude checkbox.
4. Select all matches (Mod+Enter) → the shared selection becomes the match set. The inspector shows mixed values, and any op now applies to all of them as one group, origin similar, labelled “Retype 43 similar items to H3”.
5. Shortcut actions in the tab: “Retype all to…”, “Artifact all”, “Set Lang…”, which create the same groups directly.
6. “Save as rule” (phase 5): stores the signature plus the op as a replayable template for later documents.

A result set larger than 500 shows a warning chip (“Large selection. Review a sample before applying.”) and a “Review 10 random samples” stepper.

---

9. AI suggestion review

9.1 What a suggestion is

A suggestion is a proposal: { id, ops[] (or group), target refs, confidence (0–1), band (High ≥ 0.85, Medium 0.6–0.85, Low < 0.6), reason (one line), model, cost, createdAgainst (document state hash) }. Proposals never change the document until accepted. The feature is branded “Gevell AI”. For audit purposes, the history panel and the change report show the model identifier recorded by the AI service for every AI-originated group, whether accepted or auto-applied.

9.2 Requesting suggestions

• Per item (Alt+G in Figures, Links, Language, TOC) or in bulk from a mode or issue group (“Suggest alt for 23 figures”).
• Before a bulk request, a confirmation shows the estimated credits/cost and count, because every AI call is cost-tracked per the platform rules. Requests run in the background with a determinate progress bar in the Suggestions tab and status bar (“Generating 23 suggestions… 9 done”). You can keep working meanwhile.

9.3 Review queue

┌───────────────────────────────────────────────┐
│ SUGGESTIONS  23 pending · 4 accepted · 1 rej. │
│ Group: [Figures alt ▾]  Sort: [Confidence ▾]  │
│ ┌───────────────────────────────────────────┐ │
│ │ ✦ Figure p12 · High (91%)            ◀    │ │
│ │ Set Alt: "Bar chart of revenue by quarter;│ │
│ │ Q4 highest at $4.2M."                     │ │
│ │ Why: legible axis labels and caption.     │ │
│ │ [Accept ⌘↵] [Edit] [Reject] [Show]        │ │
│ ├───────────────────────────────────────────┤ │
│ │ ✦ Figure p4 · Low (48%)                   │ │
│ │ Set Alt: "Decorative swirl"  → artifact?  │ │
│ │ Why: no text, repeated on 3 pages.        │ │
│ └───────────────────────────────────────────┘ │
│ [Accept all High (12)…]                        │
└───────────────────────────────────────────────┘

• The confidence is always shown as a word + number (“High, 91%”), never as a color bar alone.
• Ghost preview: the focused proposal is drawn on the canvas as a dashed overlay with a “Suggested” chip, and as an italic ghost row in the tree labelled “(suggested)”. The Reader shows the would-be utterance with a “Suggested” chip.
• Accept → applies the ops as a group, origin ai, labelled “AI: set alt on Figure p12”. The proposal moves to Accepted.
• Edit → opens the inspector with the proposed values prefilled but not applied. Committing applies with origin ai-edited.
• Reject → no document change. It is recorded in the history as a non-document entry (for quality metrics), and Restore in the Rejected list brings it back.
• Accept all High (N)… → the same preview-sheet pattern as fix-all (§7.3), with a sample stepper. One group, origin ai. Low-confidence items are never included in bulk accept. They must be handled one at a time.
• Staleness: if a proposal’s targets change after it was generated (an op touches them), it is marked “Outdated — the item changed since this was suggested. [Regenerate] [Dismiss]” and cannot be accepted as-is.
• Auto-apply is off by default. When a user turns it on, proposals at or above their threshold are applied on arrival (§9.4). Proposals below the threshold, Outdated proposals, and proposals for types the user excluded stay in this queue as normal.

9.4 Auto-apply (user setting)

Settings → Gevell AI → Auto-apply. This is a per-user setting. It is also shown, and can be changed, from the Suggestions tab header (“Auto-apply: on, 90% and above · [Change]”) so its state is never hidden.

┌─────────────────── Settings · Gevell AI ───────────────────┐
│ Apply suggestions automatically                            │
│ ( ) Off — every suggestion waits for review   ← default    │
│ (●) On, when confidence is at least [ 90 ]% (80–99)        │
│                                                            │
│ Apply automatically for:                                   │
│ [✓] Alt text for figures      [✓] Heading levels           │
│ [✓] Passage language          [✓] List detection           │
│ [ ] Mark as decorative (artifact)   [ ] Table headers      │
│                                                            │
│ Auto-applied changes are marked "AI (auto)", can be undone │
│ one at a time or as a batch, and still need human review   │
│ where a check requires it.                                 │
│                                            [Save settings] │
└────────────────────────────────────────────────────────────┘

• The controls are a radio group (Off / On) and a labelled number input (type="number", min 80, max 99, step 1, inputmode="numeric") with a visible range hint. The 80% floor is fixed (agreed 2026-09-28) so that Medium-band suggestions can never auto-apply. The type checklist defaults to the four types shown as ticked. Artifacting and table headers are unticked by default because a wrong change removes or reshapes content that screen reader users rely on.

• Organization lock: in the organization admin settings (Admin → Gevell AI), admins get the option “Allow members to auto-apply AI suggestions”. It is on by default. When an admin turns it off:

  • Auto-apply is off for every member, whatever each member had set. Members’ own choices are kept and come back if the lock is lifted.
  • In Settings, the section stays visible and readable. The radio group, threshold and type checklist are read-only (aria-readonly), with a lock icon and the text “Turned off by your organization’s admin. Contact your admin to change it.” This text is linked to the group through aria-describedby, so the reason isn’t color- or icon-only. The controls stay focusable, so screen reader users can find and hear the explanation.
  • The Suggestions tab header reads “Auto-apply: off (set by your organization)”.
  • Taking effect is immediate: a suggestion batch already running finishes as normal review items, and nothing more is auto-applied. Changes that were already auto-applied stay in history as they are.
  • The admin change is recorded in the organization audit log (who, when). The change report shows the auto-apply state that was in effect for each AI batch.

• When it runs: whenever a suggestion batch completes (§9.2). Auto-apply never triggers a new AI request or cost by itself. The request and cost confirmation are unchanged.

• How it applies: each qualifying proposal becomes its own group (origin ai-auto). The groups from one suggestion batch are wrapped in a batch entry. The batch goes through the same precondition checks as any op, and refused ops stay in the queue with their reason.

• History: the batch entry reads “AI auto-applied 18 suggestions (90% and above)”. It shows an “AI (auto)” origin chip and expands to one row per change. Each row shows its label, the model identifier, the confidence (“High, 94%”), and the one-line reason.

  ├ 14:40 AI auto-applied 18 suggestions (≥ 90%)   AI (auto)  [Undo batch]
  │   ├ Set alt on Figure p12 · model gv-vision-2026-09 · High 94% · "chart with legible axes" [Revert]
  │   ├ Retype P to H3 p14 · model gv-structure-2026-09 · High 91% · "matches 18pt bold cluster" [Revert]
  │   └ … 16 more

• Undo: Mod+Z right after the batch undoes the whole batch as one step. Undo batch in history does the same at any time, subject to the dependency check in §10.1. Revert on a row undoes that single change as a new forward group. Undone auto-applied proposals return to the queue as Pending, marked “Auto-apply undone”, and they are never auto-applied again. That prevents an undo from being silently re-applied.

• Review status is unchanged by auto-apply. An auto-applied change never produces an attest. A check that needs human review (alt text quality, heading meaning, language of passage) stays Needs review with an extra “AI (auto)” chip. In Figures mode those items appear under the filter “Auto-applied — needs review”. The reviewer confirms with Mod+Enter (which records the attestation) or edits. Tree rows and canvas chips carry a text “AI” marker until the item is reviewed.

• Announcement (polite, once per batch): “Applied 18 AI suggestions automatically. They still need review. Undo with Control Z.”

• Reports: the change report lists auto-applied changes in their own section (model, confidence, reviewed yes/no). The conformance report treats unreviewed auto-applied items as Needs review.

---

10. Undo and history

10.1 Semantics

• The unit of undo is the group: one keystroke, one fix-all (47 ops), one AI bulk accept, one click-sequence commit. Mod+Z undoes the most recent group. Announcement: “Undid: Fix all: artifact page numbers (47). Redo with Control Shift Z.”
• Linear stack. A new group after undo discards the redo stack. The discarded groups stay in the history panel, collapsed as “3 undone changes (discarded)”, with Re-apply available if they still apply cleanly (validated as new ops). This covers accidentally undoing and then typing.
• Selective revert from the history panel (“Revert this change”) makes a new forward group of the inverse ops. The engine first checks that later groups don’t depend on the same nodes. If they do, the panel lists the dependent changes and offers “Undo back to here” (a linear undo of everything after it) instead. Nothing is reverted silently out of order.
• Undo of AI-accepted ops reverts the document and returns the proposals to Pending in the Suggestions queue (not lost, no re-charge). Undo of an AI bulk accept returns all N.
• Undo of fix-all restores all instances, and the issues reappear in the panel.
• Undo of attest removes the reviewed mark, and the item returns to Needs review.
• Undo of auto-applied AI changes: one at a time or as a batch (§9.4).
• Undo survives save, reload and device changes. Every group is written to the local outbox (IndexedDB) immediately and synced to the server op log (§11.3). The server log is the record of truth. Saving creates a version marker in history (“Saved v7”), and undo can go past it, which puts the document ahead of its last version again. Opening the document on any device restores its history from the server. The op log is kept for the life of the document and is never trimmed. Deleting the document is the only thing that removes it.
• Undo is per session and linear across the synced log. If another session appended groups (§11.3 take-over), Mod+Z only undoes this session’s own groups when they don’t depend on later ones. Otherwise the history panel’s dependency flow applies.
• Undo restores selection and view: the selection, active mode and canvas page from before the group.
• Inline text fields use native text undo until committed. After commit, Mod+Z undoes the setAttr group.

10.2 History panel

┌───────────────────────────────────────────────┐
│ HISTORY   Filter: [All origins ▾]  🔍          │
│ ● Now                                          │
│ ├ 14:32 AI: set alt on Figure p12       ai  ↶  │
│ ├ 14:30 Fix all: artifact page numbers (47) ↶  │
│ │        fixAll · fixed 47 · introduced 0      │
│ ├ 14:21 Retype 43 similar items to H3  similar │
│ ├ 14:05 ── Saved v7 ──                         │
│ ├ 13:58 Reorder page 3 (click-sequence)        │
│ ▸ 3 undone changes (discarded) [Re-apply]      │
│ └ 13:40 Opened annual-report-2025.pdf (v6)     │
└───────────────────────────────────────────────┘

• role="list". Each entry shows its label, time, origin chip, validation delta, and actions (Show affected, Revert this, Undo back to here). Expanding an entry lists its ops in plain language.
• The filters (origin, page, node) and a search field make an audit trail usable in 3,000-op sessions.
• The entry labels come from the same ts.op.* templates as the live announcements.

---

11. Save and export

11.1 Save (Mod+S)

1. Pre-flight (≤ 1s): make sure no inline edit is uncommitted (offer to commit it or discard it).
2. Serialize in the engine (WASM worker): incremental write where possible.
3. Pixel-identity gate: render every page of the original and the candidate at 150 dpi (with a 300 dpi recheck of any page that differs) and compare exactly. Separately, verify that the content streams differ only in marked-content operators (BDC/BMC/EMC) and property-list references. Progress: a determinate bar “Checking page 18 of 48…”. Pages already proven unchanged by stream analysis skip rendering.
4. Pass → upload the new version to the server, show “Saved v8” in the app bar, and announce “Saved version 8. Pages verified identical.” Validation summary numbers are stored with the version. A veraPDF PDF/UA-1 recheck then runs on the server in the background (§11.1.2).
5. Fail → by default nothing is saved. A modal Save blocked sheet (this is one of the few modals) appears:

┌──────────────────────── Save blocked: page appearance changed ─────────────────────────┐
│ 2 of 48 pages would look different after saving. Tagging must never change            │
│ what a page looks like, so this version was not saved.                                 │
│                                                                                        │
│  Page 7   ████ 0.4% of pixels differ   [View diff]                                     │
│  Page 12  ██   0.1% of pixels differ   [View diff]                                     │
│                                                                                        │
│ Likely cause: "Split cell B4 (Table 3)" at 14:12 — content split inside a text run.   │
│   [Undo that change]   [Show all changes to page 7 and 12]                             │
│                                                                                        │
│ [Keep editing]            [Save with pixel changes…]            [Report a problem]     │
└────────────────────────────────────────────────────────────────────────────────────────┘

• View diff opens a diff viewer: before / after / difference (a magenta+ink overlay with an outline around changed regions, and a text summary “Changed region at 72,540, 110×18 pt”), with keyboard stepping between regions.
• Likely cause: the engine bisects the unsaved groups (replaying subsets through the gate on the affected pages only) to name the responsible change(s). A progress indicator shows while this runs.
• Save with pixel changes… is the deliberate override (§11.1.1). Blocking stays the default. The button is never the primary (filled) button, and Enter in the sheet activates Keep editing.
• The engine error is logged with context (structured logger), and an unexpected engine failure (as opposed to a legitimate diff) goes to error alerting.

11.1.1 Save with pixel changes: confirm step

Choosing Save with pixel changes… replaces the sheet’s contents with a confirm step in the same modal. Focus moves to its heading.

┌──────────────────── Save version 8 with pixel changes? ────────────────────┐
│ These pages will look different from version 7:                            │
│   Page 7   0.4% of pixels · 1 region   [View diff]                         │
│   Page 12  0.1% of pixels · 1 region   [View diff]                         │
│                                                                            │
│ Reason (required, kept in the change report)                               │
│ [ Kerning shift from splitting the Q4 cell; not visible at 100%.      ]    │
│                                                                            │
│ [ ] I have viewed the differences and accept them on pages 7 and 12        │
│                                                                            │
│ After saving, Gevell re-renders every page and runs a veraPDF check.       │
│ Results appear on the version and in the change report.                    │
│                                                                            │
│ [Back]                                  [Save version 8 with changes]      │
└────────────────────────────────────────────────────────────────────────────┘

• Required: a reason (textarea, labelled, at least 10 characters) and the acknowledgement checkbox. The primary button is not disabled, because disabled buttons can’t be focused and give no reason. If either is missing, activating it shows inline errors linked with aria-describedby, and focus moves to the first invalid field: “Enter a reason for accepting the page changes.” / “Confirm you have viewed the differences.”
• The pages listed are the ones found by the save gate. A “View diff” was not required, but the acknowledgement says so explicitly.
• Saving writes version 8 flagged “Pixel changes: pages 7, 12”. It is a normal version (not a side copy) and becomes the current version. Version 7 remains restorable.
• History adds “Saved v8 with pixel changes (pages 7, 12) · reason: …”, attributed to the user.
• The announcement (polite) reads: “Saved version 8 with pixel changes on 2 pages. Verification running.”

11.1.2 Post-save verification and how results are shown

After every save the server runs a verification job on the stored file. Pixel-change saves get the full treatment:

Check	Runs after	What it does
veraPDF recheck (PDF/UA-1 profile)	Every save	Independent validation of the stored file. Results are merged into the version’s conformance data (they don’t replace our checks); disagreements are flagged
Per-page render-diff report	Saves with pixel changes	Server renders every page of the new version and of the original source file (not only the previous version) at 150 dpi, re-checks differing pages at 300 dpi, and records per page: % pixels changed, changed-region boxes, diff image, and the op groups that touched the page

Where the results appear:

1. Version chip in the app bar: “v8 · pixel changes · verifying…” (with a progress indicator) → “v8 · 2 pages changed · veraPDF 0 failures” → or, if problems are found, “v8 · verification found problems” in the error style (text + icon).
2. Versions panel (History tab → Versions): each version lists its verification status, the render-diff report (an accessible HTML page with per-page before / after / diff images, alt text describing each changed region, and a data table of the numbers) and the veraPDF report.
3. Announcements: a polite message when verification finishes (“Verification finished for version 8: 2 pages changed as accepted; veraPDF found no failures.”). It is assertive only if verification finds problems.
4. Problems are: pages changed that the save gate did not report, a larger change than accepted (more than 2× the accepted % or new regions), or new veraPDF failures. In that case a non-modal banner appears on the workspace: “Version 8 changed more than you accepted: page 9 also differs. [View report] [Restore version 7] [Keep version 8]”. Restore creates version 9 from version 7’s content plus the op log after it, re-run through the gate. Nothing is deleted.
5. If the verification job fails (the job itself errors), the status is “Could not verify”, which is treated like a failure in reports, never as a pass. It retries automatically, and the error goes to alerting.
6. Change report (§11.2): a “Pages with visual changes” section at the top listing every changed page with a diff thumbnail, % pixels changed, region count, the accepting user, the reason, and the responsible changes. The conformance report states “Page appearance differs from the source on pages 7, 12 (accepted by LA, 2026-09-28)” and includes the veraPDF result.
7. Each later save carries the flag forward (“differs from source on pages 7, 12”) until a version is saved that is identical to the source on those pages again.

11.2 Export (Export ▾)

Output	Contents
Tagged PDF	The saved version (the export is disabled while unsaved; the button says “Save first”)
Change report (accessible HTML + tagged PDF)	“Pages with visual changes” first when any exist (§11.1.2); summary counts by op and origin; before/after validation; every group in plain language with page links; AI-accepted, AI-edited and AI auto-applied items (model, confidence, reviewed yes/no) listed separately
Conformance report (accessible HTML + tagged PDF)	veraPDF result for the version, PDF/UA-1 Matterhorn checkpoint table (Pass / Fail / Needs review / Reviewed by / N/A / Could not check) and a WCAG 2.1 AA SC table for document content. Needs-review items are listed as not yet verified, and Reviewed items name the reviewer and date. There is no single “compliant” badge unless every applicable item is Pass or Reviewed
Op log (JSON)	A replayable group/op list for audit and templates

The export runs with a progress indicator. Report generation is cost-free (no AI). If the version’s verification is still running, the export dialog says so and offers “Export when verification finishes” (the default) or “Export now”. Export now puts “Verification pending” on the report.

11.3 Sync, autosave, conflicts and offline

What lives where: the source PDF, every saved version, verification reports and the op log live on Gevell’s servers (AWS: files in S3, op log and version metadata in the database). The browser runs the engine (WASM) against a local copy, and keeps an outbox in IndexedDB.

Autosave = op-log sync. There is no “unsaved work” in the sense of losable edits:

• Every group is written to the outbox immediately, then sent to the server in order (batched, within about 2 seconds). Each group carries the server sequence number it was based on.
• Saving (Mod+S) creates a verified PDF version, which is a separate step. Closing the tab with changes since the last version does not lose them. On reopen: “You have 14 changes since version 7. [Keep working] [Save a version]”.
• beforeunload warns only when the outbox has not finished syncing, not merely when there is no new version.

Sync status indicator (app bar; text + icon, never icon or color alone; a button that opens a details popover):

State	Text	Details popover
Synced	”Synced”	Last sync time
Syncing	”Syncing 3…”	Count pending
Offline	”Offline · 12 changes on this device"	"Your changes are stored on this device and will sync when you’re back online.”
Sync problem	”Sync problem · retrying”	Error in plain language, next retry time, [Retry now], [Download a backup of my changes] (op log JSON)
Read-only	”Read-only · open elsewhere”	See the conflict flow below

Announcements only fire on transitions to Offline, back to Synced after being offline (“Back online. 12 changes synced.”), and to Sync problem (assertive). Routine syncing is silent.

Same document open twice. Editing needs a document lease, held by one session and renewed by heartbeat every 15 seconds:

1. If you open a document whose lease is held (another tab of yours, detected at once through BroadcastChannel, or another user or device, detected through the server), a non-modal choice appears before the workspace becomes editable: “This document is being edited in another tab / by Laura Hopkins on another device (since 14:02).” [Open read-only] · [Take over editing] · [Open a copy].
2. Read-only follows the live op log: new groups appear, the history updates, and edit commands are disabled with the reason “Read-only while this document is edited elsewhere.”
3. Take over asks the other session to flush its outbox, then moves the lease. The other session switches to read-only and shows “Editing moved to another tab / to Larry Anglin at 14:31. Your changes up to then are synced.” (assertive, since it interrupts work).
4. If the previous holder is unreachable (crashed or offline), take-over waits for the lease to expire (up to 45 seconds, with a countdown and progress) and then proceeds.
5. Open a copy creates a new document from the current version plus synced ops.

Offline:

• Editing, validation (WASM), select-similar, undo/redo and the pixel-identity gate all keep working.
• AI requests, the veraPDF recheck and version upload need the network. Those buttons stay focusable and explain why: “Needs a connection. Your request will not be queued, to avoid unexpected costs.”
• Save while offline runs the local gate and then queues the version upload: “Version 8 will be uploaded when you’re back online.” A Download PDF now option gives a local copy marked “not yet uploaded” in the file name.
• Reconnecting after someone else took over (your lease expired while offline): your outbox groups are rebased onto the server head. Each group is re-validated against the current state. Groups that still apply are appended, labelled “Synced after reconnecting”. Groups that no longer apply go to a “Couldn’t sync” list in the History tab. Each one has its reason, [Re-apply] (after you edit the conflict) and [Discard]. [Save all as a copy] creates a separate document from your offline state. Nothing is silently dropped.

Recovery: after an engine crash or browser restart, the workspace rebuilds from the latest version plus the server op log plus any unsynced outbox groups, in that order.

---

12. Loading, empty and error states

12.1 Progress rule

Anything that may exceed 2 seconds shows a progress indicator. It is determinate when the total is known, and it has text, a <progress> element, and a polite announcement at start, at 25% steps (at most every 5s) and at the end. The UI stays interactive during background work unless the work blocks editing (save gate).

Operation	Indicator
Upload	Determinate bytes (“12.4 of 30 MB”)
Parse / open	Determinate by objects. Progressive: page 1 and the top tree levels become interactive before the whole document is parsed; the status bar shows “Loading structure… 40%“
Page render	Per-page skeleton (gray page with the page number) then tiles. No spinner for < 300 ms
Full validation	Status bar bar + the summary chip reads “Checking…”
Detection (artifacts, lists, headings)	Task-panel skeleton rows + “Scanning 48 pages… 12”
Select similar on large docs	Count rises live; “Still searching (page 30 of 480)“
AI suggestions	Per-request determinate count; per-item skeleton in the queue
Save gate / bisect / export	Determinate by page; can be cancelled (except the final write)
Version upload	Determinate bytes
Post-save verification (render diff + veraPDF)	Version chip “verifying…” + determinate page count in the Versions panel; runs on the server and does not block editing
Lease take-over wait	Countdown + progress (up to 45 s)

12.2 Empty states

Situation	What the user sees
No file open	A drop zone with a file picker button, recent files (with version and date), and a short note that the file is uploaded to Gevell and edited in your browser. The keyboard path is the button itself
Untagged PDF (no StructTreeRoot)	“This PDF has no tags. Screen readers will read it poorly or not at all.” Options: Start in Reading order mode (build structure page by page) · Auto-tag first (proposal-based, reviewed like AI suggestions) · Tag manually in Raw tree. No option is preselected
No text layer (scanned)	“This PDF is images of text, so it has nothing to tag yet. It needs OCR first.” A link to the OCR path (see Q2). Figures mode still works for true images
Mode has nothing to do	”No tables found in this document.” + “Tag a region as a table” (Mark mode) + a check in the rail with the text “Tables: none”
Filter with no matches	”No nodes match type:Figure no:alt.” + Clear filter
All issues resolved	”No failures. 6 items still need review.” (Never “All clear” while any review items remain)

12.3 Errors

• Op refused (precondition): nothing changes. An assertive announcement plus a toast (error toasts use role="alert"; everything else is polite) states the reason and the alternative: “Can’t move LI here. List items must be inside a List (L). Wrap it in a list first with Alt+W.”
• Password-protected: a password field (labelled, autocomplete="off"). A wrong password says “That password didn’t open the file. Check caps lock and try again.”
• Encrypted with permissions that forbid modification: open read-only with a banner explaining that saving needs the owner password.
• Corrupt / unsupported (for example XFA forms, PDF 2.0 in phase 1): a specific message with the detected reason, plus “Open read-only to inspect” when parsing got far enough.
• Engine crash / out of memory (WASM): the workspace shows “The editor stopped unexpectedly. Your changes up to 14:32 are safe.” and Recover, which reloads the engine and rebuilds from the server op log and the local outbox (§11.3). The error is logged and alerted.
• Network lost: the work continues offline (§11.3). Nothing is lost.
• Same document open elsewhere: the lease flow in §11.3. Real-time co-editing is phase 6.
• Large documents (over 2,000 pages or 200k nodes): a warning on open with the expected memory use, and a page-range open option.

---

13. Live-region announcements

Two always-mounted regions: polite (role="status") and assertive (role="alert", errors only). The status-bar echo mirrors the last message visually (WCAG 4.1.3). Messages are short, lead with the result, and follow the i18n templates ts.op.<name>.done.

Event	Text (en)
Retype	”Retyped Paragraph to Heading 2.” (multi: “Retyped 43 items to Heading 3.”)
Move	”Moved Budget overview to position 3 of 9 in Section.”
Promote/demote	”Promoted to level 2.” / “Demoted into Table 1.”
Wrap / unwrap	”Wrapped 5 items in List.” / “Removed List tag; 5 items kept.”
Artifact	”Marked 47 page numbers as artifacts.”
Fix	”Fixed: Figure without alternate text, page 12. 11 failures remain.”
Undo / redo	”Undid: Retype 43 items to Heading 3.” / “Redid: …”
AI ready	”12 suggestions ready for Figures.” (once per batch)
Accept	”Accepted suggestion: alt text on Figure, page 12.”
Validation done	”Check complete: 12 failures, 31 need review.”
Save	”Saved version 8. Pages verified identical.”
Save with pixel changes	”Saved version 8 with pixel changes on 2 pages. Verification running.”
Verification done	”Verification finished for version 8: …” (assertive if problems found)
Auto-apply	”Applied 18 AI suggestions automatically. They still need review. Undo with Control Z.”
Sync transitions	”Offline. Changes are stored on this device.” / “Back online. 12 changes synced.” / “Sync problem…” (assertive)
Lease moved	”Editing moved to another tab at 14:31. This window is now read-only.” (assertive)
Save blocked (assertive)	“Save blocked. Two pages would change appearance. Details are open.”
Refused op (assertive)	as in §12.3

Selection sync, hover and background scrolling are never announced.

---

14. Overlay color palette

14.1 Design rules

• Nine tag families. Each is encoded three ways: color, stroke pattern, and a text label chip. Color is never the only signal (WCAG 1.4.1). With labels on (the default), every overlay can be identified without color vision.
• No green in the palette, so the brand focus ring (#046307 / #5CCB60) is unique on the canvas. This also avoids blue–green adjacency with the brand blue.
• Light variant colors (used for canvas strokes in both themes, because the page is always drawn as printed, and for UI chips in light mode) are ≥ 4.5:1 on white. This means white chip text passes AA, and strokes exceed the 3:1 non-text minimum.
• Dark variant colors (UI chips, tree tags and legend in dark mode) are ≥ 4.5:1 against the dark surfaces and carry ink (#0E1116) text.
• Every canvas stroke is drawn with a 1px white outer keyline, so it stays ≥ 3:1 against dark or colorful page backgrounds (flyers, reversed text).

14.2 Palette

Family (tags)	Light (canvas + light UI)	on white	on bone	Dark UI	on #161B23	on #0E1116	on #1D2330	Stroke pattern	Chip
Heading (H, H1–H6)	#B34700	5.50	5.05	#F0862E	6.71	7.34	6.11	Solid 3px	H2
Text (P, Span, Quote, BlockQuote, Code, Caption)	#4A5464	7.65	7.03	#B9BEC8	9.27	10.14	8.43	Solid 1px	P
Figure (Figure, Formula)	#A3238F	6.57	6.04	#F08BDF	7.79	8.52	7.09	Solid 2px + corner ticks	Fig
Table (Table, TR, TH, TD, THead, TBody, TFoot)	#0B4FC7	7.10	6.52	#6FA3F5	6.78	7.41	6.17	Solid 2px + inner cell grid	Tbl/TH/TD
List (L, LI, Lbl, LBody)	#735A00	6.58	6.04	#E6C34A	10.10	11.05	9.19	Dashed 6-3, 2px	L/LI
Link / Note (Link, Annot, Reference, Note)	#6B2FA8	8.09	7.43	#C9A6FF	8.54	9.35	7.77	Dotted 2px + underline	Lnk
Form (Form)	#0E1116 (ink)	18.91	17.37	#F7F5F1 (bone)	15.87	17.37	14.44	Double 1px-2-1px	Frm
Artifact	#6B7686	4.60	4.23 †	#8A94A6	5.65	6.18	5.14	Dotted 1px + 40% white wash	Art
Untagged (orphan)	#C4001A	6.25	5.74	#FF8A80	7.57	8.28	6.89	Dashed 4-2, 2px + diagonal hatch fill	! Untagged
Containers (Document, Part, Sect, Div, Art, TOC, TOCI…)	#4A5464	7.65	7.03	#B9BEC8	9.27	10.14	8.43	Long-dash 10-4, 1px, no fill	Sect

† Artifact on bone is 4.23: that passes 3:1 for strokes, but artifact chips must sit on white or on the chip’s own fill, not on bone. Chips in light mode always use white text on the family fill (ratios = the “on white” column, all ≥ 4.5). Chips in dark mode use ink text on the dark-variant fill (ratios = the “on #0E1116” column, all ≥ 6.1).

UI state colors (not tag families):

Element	Light	Ratio	Dark	Ratio
Focus ring	#046307 3px, 3px offset	7.52 on white, 6.91 on bone	#5CCB60	8.37 on #161B23, 9.16 on ink
Selection	2px ink #0E1116 + 2px white halo	≥ 3:1 on any background (by construction)	same (the page is drawn as printed)	same
Reading-order badge	White on ink circle with white ring	18.91	same	18.91
Error text/chips	#B3261E on #FBE4E2	5.38	#F28B84 on #33110F	7.17
Review/warning	#A24A00 on #FBEADC	5.09	#F0862E on #2C1B0C	6.43

14.3 Color-vision check (simulated, CIELAB ΔE between family pairs)

Simulated with Machado et al. (2009) matrices at full severity. Pairs under ΔE 12 are “hard to tell apart by color” and are deliberately separated by stroke pattern:

Vision	Closest pairs (ΔE)	Disambiguated by
Typical	Text/Artifact 14 · Table/Link 25	Solid vs dotted+wash; solid+grid vs dotted+underline
Deuteranopia	Heading/Orphan 4 · List/Orphan 7 · Heading/List 11	Solid 3px vs dashed+hatch fill; dashed vs hatch; solid vs dashed
Protanopia	Heading/List 0 · Table/Link 10 · Text/Artifact 14	Solid 3px vs dashed; solid+grid vs dotted; solid vs dotted+wash
Tritanopia	Text/Artifact 14 · Table/Artifact 20	Stroke patterns + chips

With nine families, perfect separation by hue alone is impossible under protanopia with AA contrast (all colors must sit in the dark half of the luminance range), so hue collisions are expected. The stroke pattern and label make each family unique. Usability scenario U12 checks this with participants who have color-vision deficiencies. A “Patterns only” overlay setting renders all families in ink with their patterns and chips, for users who prefer no color. A high-contrast mode follows forced-colors: active: strokes use CanvasText, selection uses Highlight, and focus uses system focus colors.

---

15. i18n

All UI strings are externalized from day one: flat JSON in locales/{lang}.json with one level of dotted keys, ICU MessageFormat for plurals and select, and Intl for numbers, dates and percentages. Tag names in Raw mode (H2, LBody) are not translated. Their spoken forms are.

Namespace	Holds	Example key
ts.shell.*	App bar, status bar, landmarks, region headings	ts.shell.saveState.unsaved
ts.mode.<mode>.*	Mode names, explainers, task panel labels, done criteria (readingOrder, headings, figures, tables, artifacts, lists, links, forms, notes, language, toc, raw)	ts.mode.figures.queue.needsAlt
ts.tree.*	Treegrid labels, row name template, filters, presets	ts.tree.row.name
ts.canvas.*	Overlay menu, mark-mode announcements, canvas description	ts.canvas.mark.corner
ts.reader.*	Announcement grammar templates and profiles (§4.3.2)	ts.reader.heading = heading level {level}, {text}
ts.inspector.*	Field labels, hints, lint messages	ts.inspector.alt.lint.imageOf
ts.tag.<Type>.*	name, spoken, description for each structure type	ts.tag.LBody.spoken
ts.op.<op>.*	label (history), done (announcement), refused.<reason>	ts.op.move.refused.liOutsideL
ts.rule.<ruleId>.*	Validation message, fix labels, help link text (ruleId uses mp-13-004, wcag-1-1-1)	ts.rule.mp-13-004.title
ts.issues.*	Panel chrome, statuses, fix-all sheet	ts.issues.status.needsReview
ts.similar.*	Signature chip labels, result counts	ts.similar.result.count
ts.ai.*	Suggestion queue, confidence bands, reasons scaffolding, cost confirm	ts.ai.band.high
ts.history.*	History panel chrome, origin chips, versions panel	ts.history.origin.aiAuto
ts.sync.*	Sync status, lease/conflict flow, offline messages	ts.sync.state.offline
ts.verify.*	Post-save verification, render-diff report, veraPDF summary	ts.verify.chip.problems
ts.settings.*	Settings, including AI auto-apply and the org-locked state	ts.settings.ai.autoApply.lockedByOrg
ts.save.* / ts.export.*	Gate progress, blocked sheet, report headings	ts.save.blocked.title
ts.keys.*	Key names and shortcut descriptions, platform variants (.mac, .win)	ts.keys.undo.mac
ts.state.*	Empty, loading, error states	ts.state.untagged.title
ts.progress.*	Progress texts for >2s operations	ts.progress.validating

Reports (change and conformance) use the same catalog under ts.export.report.*, so they can be generated in the user’s locale. The Reader’s grammar is in the user’s UI locale; the spoken document content stays in the document’s language (and is marked up with lang in the Reader HTML).

---

16. Usability-test scenarios

Participants: at least 5 professional remediators (Acrobat Pro users), 3 of them screen reader users (NVDA, JAWS, VoiceOver on macOS), and 2 with color-vision deficiency. Test files come from the tag-tree golden corpus (#3856). Success = task complete without moderator help, within the time target, with no unintended ops in the history.

#	Scenario	Measures / pass bar
U1	Open an untagged 12-page two-column newsletter and produce a correct reading order with no orphans	≤ 15 min; zero orphans; path correct; used click-sequence or column proposal
U2	Fix a skipped heading level and apply the level map document-wide, then undo the level map	≤ 3 min; one undo restores all; participant can say what was undone
U3	Write alt text for 10 figures, mark 2 as decorative, link 1 caption	≤ 10 min; no suspicious-alt lint left
U4	Repair a 3-level-header irregular table with a spanning header (Headers/IDs), confirming via announcement preview	≤ 8 min; announcement preview matches expected for 5 sampled cells
U5	Artifact running headers, footers and page numbers on a 48-page report while keeping the title-page header as content	≤ 4 min; exclusion used; fix count correct
U6	Convert bullet paragraphs to a nested list with labels	≤ 5 min; Lbl/LBody present; nesting correct
U7	Fix 3 “click here” links and set tab order to structure	≤ 4 min
U8	Add tooltips to 8 form fields and reorder tab order to match the visual layout	≤ 6 min
U9	Use select-similar to retype 40 mis-tagged captions (P → Caption), excluding two false matches	≤ 3 min; exclusions correct
U10	Screen reader only: move a paragraph under a different heading, promote a heading, retype a node and read the result in the Reader, with no pointer	Completes on NVDA, JAWS and VoiceOver; every op announced; no lost focus; notes on C6–C8
U11	Review 20 AI alt-text suggestions: accept High, edit 2, reject 1, then undo the bulk accept and confirm the proposals return to Pending	Understands confidence; no Low items bulk-accepted; undo understood
U12	Color-vision participants: identify the tag family of 10 highlighted regions with labels on, then with “Patterns only”	≥ 9/10 correct in both
U13	Save after an op that changes page appearance (seeded), then find and undo the cause from the Save blocked sheet	Finds cause ≤ 2 min; understands nothing was saved
U13b	Same file: choose Save with pixel changes, complete the confirm step, then find the verification result and the changed-pages list in the change report	Completes confirm without help; can state which pages changed and whether verification passed
U14	Keyboard only: cycle regions with F6 across Chrome, Edge, Firefox, Safari; fall back to Mod+K where F6 fails	Records which browsers pass C2
U15	Work at 400% zoom (320px) in single-pane mode: fix one figure and one heading	Completes; no horizontal page scroll outside the canvas
U16	Use fix-all for 47 page-number issues, untick 2, apply, and read the change report	Report lists 45 fixes and origin fixAll
U17	Compare against Acrobat Pro: same file, same 5 tasks, timed (benchmark from epic phase 0)	Tag Studio ≥ 30% faster median; fewer errors
U18	Recover after a forced engine crash mid-session	No lost ops; participant trusts the recovery message
U19	Open the same document in two tabs, take over editing in the second, then go offline in the first and reconnect	Understands read-only state; no lost or silently dropped changes; can explain the “Couldn’t sync” list if seeded
U20	Turn on AI auto-apply at 90%, run suggestions on 30 figures, then find the auto-applied items, revert one, undo the rest as a batch, and review two	Finds them via history and the “Auto-applied — needs review” filter; knows they are not yet reviewed

---

17. Competitor pain points designed out, and parity

Seen in (Acrobat Pro / Grackle / Siteimprove / our older editors)	Tag Studio answer
Tags, Content and Order are separate panels that each hold their own model and drift	One model, synchronized views (§2)
Modal Properties dialogs that hide the page	Non-modal inspector (§4.4)
Unreliable undo and “undo not available” after Reading Order tool actions	Every edit is an op with an inverse, and undo is group-level and persisted (§10)
Nodes shown as “<MCID 12>” or “Container”	Real content previews (§4.2.1)
Drag-only reordering; tiny drop zones	Keyboard ops, cut/paste move, explicit drop indicators with text (§4.2.3, §5.3)
Checkers that mark “Passed manually” by default or collapse review items into passes	Needs review is never a pass; attestation is explicit and reported (§7)
Auto-tag that silently rewrites structure	Proposals with preview and confidence (§9)
Saving that silently re-renders or re-encodes content	Pixel-identity gate (§11)
Acrobat Content / Reading Order panels have no undo; some axesPDF ops can’t be undone	Every op has a tested inverse, and none ship without one (§3)
Acrobat’s reading-order view desyncs from the tag tree	Both are renderings of one model; bidirectional Find on page / Find in tree (§5.4)
Acrobat’s reading-order tool has no List type	Tag as List from the sequence or canvas, including nesting (§6.1, §6.6)
Per-cell table properties dialogs (Acrobat, CommonLook)	In-place grid editor with bulk TH/TD, scope, spans, Headers/IDs (§6.4)
AI alt text without confidence (several tools)	Every proposal shows its confidence band, number and reason (§9)
No competitor documents how its editor works with a screen reader	This spec does: ARIA patterns, announcements and conflicts (§4.2, §5.6, §13), and U10 tests them

Parity features we must match (from the phase-0 competitor teardown): wrap in a new container, move up a level, merge, and delete empty tags (axesPDF, CommonLook) → wrap, promote, mergeNodes, Remove empty tags. Tag Similar by font style (CommonLook) → Select similar (§8). List building from a selection, including nested lists (CommonLook) → §6.6. Table grid with bulk TH/TD, scope, headers, spans, merge/split and flatten layout table → §6.4. One-click document-wide fixes (axesPDF) → Fix all (§7.3). A color-coded structure preview and screen reader preview (PAC, axesPDF) → overlays and Reader (§4.1, §4.3). Bulk alt-text and links panels (Grackle) → Figures list view and Links mode (§6.3, §6.7). An AI first pass with a review queue → §9 and the “Auto-tag first” empty state (§12.2).

---

18. Open questions for Larry

• Q1: Does saving Alt text in Figures mode count as human attestation (as specified), or should there be a separate explicit “Reviewed” step for audit-heavy customers?
• Q2: For scanned PDFs, should Tag Studio hand off to Gevell PDF for OCR, or refuse outright?
• Q3: Should Mod+Shift+J (Jump to page) be dropped on Windows (conflict C4), keeping only the palette?
• Q4: Should verbosity profiles name the products (“NVDA-like”) or stay generic (“Profile A/B/C”) to avoid implying equivalence? Resolved 2026-09-28: pixel-diff saves are allowed as a confirmed override (§11.1.1); documents, versions and the op log sync to the server (§11.3); AI auto-apply is an opt-in user setting with a fixed 80% floor that org admins can lock off (§9.4); the op log is kept for the life of the document (§10.1).