Dogfood Clean Consumer Report

This report records the first clean-consumer dogfood pass for @ponchia/annotations. It uses the packed package from the current checkout in a separate Vite consumer rather than package examples or workspace imports.

Consumer

Host app or report: clean Vite report generated by scripts/dogfood-clean-consumer.mjs
Surface type: DOM/report regions, Vega-Lite generated chart, Mermaid generated diagram
Package source: local packed tarball installed into .tmp/dogfood-clean-consumer
Commit/version: current checkout via npm pack

Integration Path

Public imports used:
- @ponchia/annotations
- @ponchia/annotations/dom
- @ponchia/annotations/vega
- @ponchia/annotations/mermaid
- @ponchia/annotations/bronto.css
Adapter/helper used:
- prepareDomAnnotations
- prepareVegaScenegraphAnnotations
- prepareMermaidAnnotations
- resolvePreparedAnnotationLayout
- renderAnnotationsSvg
Bounds source:
- DOM report surface: getBoundingClientRect()
- Vega-Lite chart: annotationFrameFromSvg()
- Mermaid diagram: annotationFrameFromSvg()
Anchor source:
- DOM selectors measured relative to the report surface
- Vega-Lite compiled to Vega, then anchored from Vega scenegraph marks
- Mermaid rendered SVG labels and rendered edge path selectors
Obstacles source:
- DOM region cards
- Vega scenegraph marks plus rendered SVG marks
- Mermaid rendered SVG nodes and paths
Manual placement needed: yes, for editorial DOM and Mermaid edge callouts
Target-alignment checks used: yes
Layout-quality checks used: yes

Evidence

npm run test:dogfood proves the integration by:

Packing the package with npm pack
Installing the tarball plus optional peers into a clean Vite consumer
Rendering the report in Chromium through Playwright
Verifying no console errors
Verifying five rendered annotation notes and connectors
Verifying DOM, Vega-Lite, and Mermaid anchor validation
Verifying generated-target alignment for every dogfood surface
Verifying an external note list with roving focus, note focus sync, keyboard activation, and a screen-reader summary from validation and layout-quality results
Capturing .tmp-dogfood/dogfood-report.png

Friction

Area	Observation	Severity	Proposed Fix
API naming	The prepared-layout flow is coherent, but first use requires learning several assertion option names.	low	Keep `resolvePreparedAnnotationLayout` as the recommended path; the mixed DOM/SVG report recipe now covers the combined report path.
Coordinate space	Matching host `viewBox`, overlay bounds, and DOM pixel coordinates remains the main thing a consumer must get right.	medium	Keep emphasizing `annotationFrameFromSvg()` and same-coordinate manual placement in recipes.
Generated geometry timing	Vega-Lite must compile and Vega must run before scenegraph anchors exist; Mermaid must render before SVG anchors exist.	low	Add timing callouts to generated-surface recipes.
Styling	`@ponchia/annotations/bronto.css` worked from a clean package install without `@ponchia/ui`.	low	No package change required.
Accessibility	`noteTabIndex` made SVG notes focusable, and the clean dogfood now verifies a host-owned external note list with roving focus, note focus sync, keyboard activation, and a screen-reader summary.	low	Keep the recipe backed by `npm run test:dogfood`; broader production apps can still add their own command palettes or workflows.
Performance	Five annotations across three surfaces resolved quickly in Chromium.	low	Keep separate 10/50/200 stress benchmark as the practical limit signal.
Docs/examples	Existing examples are strong per adapter, and the mixed DOM/SVG report recipe now reduces first-use uncertainty for combined report surfaces.	low	Keep the recipe backed by `npm run test:dogfood:bronto-report`.

Outcome

Would ship with this API today: yes for 0.1.x dogfood and canary use
Required package changes before public release: none blocking from this pass
Changes that can wait: app-specific command palettes or workflows
Screenshots or browser evidence: .tmp-dogfood/dogfood-report.png from npm run test:dogfood

Edit Markdown source ↗All docs ↗