bronto/annotations

DOCUMENTATION / DOGFOOD-EXTERNAL-CONSUMER-REPORT

Dogfood External Consumer Report

This report records a local dogfood pass against a real external Astro/React writing site. The public package does not name or depend on that host; the harness receives the host root through an environment variable, builds it, serves its static output, measures rendered DOM geometry in Chromium, and injects an annotation SVG generated by @ponchia/annotations.

Consumer

  • Host app or report: external Astro/React writing site
  • Surface types:
    • rendered DOM stack diagram, metric group, tool chip, and ordered flow step
    • rendered React Flow diagram with generated nodes, handles, and SVG edge routes
  • Package source: current checkout through public package imports after npm run build
  • DOM stack command: PONCHIA_ANNOTATIONS_EXTERNAL_CONSUMER_ROOT=<external-checkout> PONCHIA_ANNOTATIONS_EXTERNAL_CONSUMER_BUILD_SCRIPT=build:public npm run test:dogfood:external
  • React Flow command: PONCHIA_ANNOTATIONS_EXTERNAL_CONSUMER_ROOT=<external-checkout> PONCHIA_ANNOTATIONS_EXTERNAL_CONSUMER_BUILD_SCRIPT=<preview-build-script> PONCHIA_ANNOTATIONS_EXTERNAL_CONSUMER_MODE=react-flow PONCHIA_ANNOTATIONS_EXTERNAL_CONSUMER_PATH=<external-react-flow-route> npm run test:dogfood:external
  • Commit/version: current annotations checkout and current external host checkout at local verification time

Integration Path

  • Public imports used:
    • @ponchia/annotations
    • @ponchia/annotations/dom
    • @ponchia/annotations/react-flow
    • @ponchia/annotations/bronto.css
  • Adapter/helper used:
    • anchorFromDOMRect
    • prepareReactFlowAnnotations
    • generatedSurfaceLayoutDefaults
    • resolvePreparedAnnotationLayout
    • renderAnnotationsSvg
  • Bounds source:
    • Body-wide document bounds from Chromium after the host page rendered
  • Anchor source:
    • getBoundingClientRect() measurements for real host DOM selectors
    • rendered React Flow node data-id, handle data-nodeid and data-handlepos, and sampled generated SVG edge routes
  • Obstacles source:
    • Rendered stack layers, metric cards, examples, and tool chips
    • React Flow nodes, handles, and edge route boxes through the React Flow adapter
  • Manual placement needed: no for this pass; deterministic scored placement handled the page
  • Target-alignment checks used: yes
  • Layout-quality checks used: yes

Evidence

The local DOM stack verification command proved the integration by:

  • Building the external Astro/React host
  • Serving the built site from a local static server
  • Opening the real stack page in Chromium
  • Measuring real DOM boxes for four annotation targets and page obstacles
  • Resolving annotations with target-alignment and layout-quality assertions
  • Injecting the package-generated SVG layer into the host page
  • Verifying four visible notes and four visible connectors
  • Verifying no browser console or page errors
  • Capturing .tmp-dogfood/dogfood-external-consumer.png
  • Writing .tmp-dogfood/dogfood-external-consumer.json

The local React Flow verification command proved the generated-surface adapter path by:

  • Building the external Astro/React host with its preview route enabled
  • Opening a real rendered React Flow diagram in Chromium
  • Waiting for hydrated React Flow nodes before measuring geometry
  • Measuring 2 rendered React Flow surfaces on the page
  • Feeding 7 rendered nodes, 6 rendered edges, and 12 rendered handles into prepareReactFlowAnnotations
  • Sampling 42 generated SVG edge-route points from the rendered React Flow edge paths
  • Resolving 4 annotations through target-alignment and layout-quality assertions
  • Verifying 4 visible notes, 4 visible connectors, and no browser console or page errors
  • Capturing .tmp-dogfood/dogfood-external-react-flow.png
  • Writing .tmp-dogfood/dogfood-external-react-flow.json

npm run check includes npm run test:dogfood:external; without PONCHIA_ANNOTATIONS_EXTERNAL_CONSUMER_ROOT it skips with a clear message so public CI does not depend on a private local checkout.

Friction

Area Observation Severity Proposed Fix
Cross-repo verification The most realistic proof needs a local external checkout that public CI does not have. low Keep the optional env-gated dogfood harness and record local evidence in this report; public CI continues to prove clean consumers and examples.
Overlay mounting A body-wide injected SVG overlay worked for the dogfood harness, but a permanent host integration should mount a relative overlay inside the owning page section. low No package change required; document host-owned overlay mounting as an integration choice.
Coordinate space getBoundingClientRect() plus document scroll offsets produced stable body-space anchors for mixed page sections. low Keep anchorFromDOMRect and DOM coordinate recipes as the recommended path for page-level overlays.
React Flow state access The static rendered page did not expose host-owned React Flow state to the dogfood harness. The harness reconstructed adapter input from public rendered DOM attributes and generated SVG route points. medium In permanent host integrations, prefer passing public React Flow node/edge/viewport state directly to prepareReactFlowAnnotations; keep the DOM bridge as proof that rendered output can still be annotated.
React Flow timing Hydrated React Flow geometry is only available after the surface becomes visible and nodes render. low Wait for .react-flow__node or a host-owned readiness signal before measuring or resolving annotations.
FitView transforms fitView changes the final rendered coordinate space; post-layout DOM boxes were the stable source for this dogfood pass. low Pass the current React Flow viewport when using state, or measure rendered boxes when annotating the final screen position.
Styling Injecting @ponchia/annotations/bronto.css produced visible notes/connectors without requiring a hard design-system dependency. low No package change required.
API ergonomics The prepared-layout path was still the right route for external DOM hosts because it keeps validation, quality, and target alignment in one place. low Keep resolvePreparedAnnotationLayout stable for 0.1.x.

Outcome

  • Would ship with this API today: yes for 0.1.x dogfood and canary use
  • Required package changes before public release: none from this external host pass
  • Changes that can wait: richer permanent host recipes for relative overlay mounting, direct host-state React Flow examples, and edit-mode persistence
  • Screenshots or browser evidence: .tmp-dogfood/dogfood-external-consumer.png, .tmp-dogfood/dogfood-external-consumer.json, .tmp-dogfood/dogfood-external-react-flow.png, and .tmp-dogfood/dogfood-external-react-flow.json
Edit Markdown source ↗All docs ↗