bronto/annotations

DOCUMENTATION / DOGFOOD-SELF-REPORT

Dogfood Self Report

This report records a self-dogfood pass where a clean consumer renders a package-readiness report from the repository's actual readiness and completion evidence. It is intentionally not demo data: the host report uses docs/readiness-matrix.json, docs/completion-audit.json, and package.json as its data source.

Consumer

  • Host app or report: clean Vite release-evidence report generated by scripts/dogfood-self-report.mjs
  • Surface type: DOM report metric cards, completion-audit table rows, generated SVG readiness chart, and generated SVG release-flow diagram
  • Package source: local packed tarball installed into .tmp/dogfood-self-report
  • Data source: current docs/readiness-matrix.json, docs/completion-audit.json, and package.json
  • Commit/version: current checkout via npm pack

Integration Path

  • Public imports used:
    • @ponchia/annotations
    • @ponchia/annotations/dom
    • @ponchia/annotations/bronto.css
  • Adapter/helper used:
    • prepareDomAnnotations
    • annotationFrameFromSvg
    • resolvePreparedAnnotationLayout
    • renderAnnotationsSvg
  • Bounds source:
    • Report summary section: getBoundingClientRect()
    • Generated chart: SVG viewBox expanded with annotationFrameFromSvg()
    • Generated diagram: SVG viewBox expanded with annotationFrameFromSvg()
  • Anchor source:
    • Rendered metric cards from readiness counts
    • Rendered completion-audit table row
    • Rendered SVG bars generated from readiness/audit counts
    • Rendered SVG flow node and edge generated from release-evidence state
  • Obstacles source:
    • Report metric cards
    • Generated SVG chart bars
    • Generated SVG flow nodes
  • Manual placement needed: yes, for editorial table-row and diagram-edge notes
  • Target-alignment checks used: yes
  • Layout-quality checks used: yes

Evidence

npm run test:dogfood:self-report proves the integration by:

  • Packing the annotations package with npm pack
  • Installing the tarball into a separate clean Vite consumer
  • Rendering a release-evidence report from current project JSON files
  • Verifying no console errors
  • Verifying six rendered annotation notes and connectors
  • Verifying DOM, generated SVG chart, and generated SVG diagram anchor validation
  • Verifying generated-target alignment for every self-dogfood surface
  • Verifying the browser report uses the exact current evidence counts from the source JSON files
  • Capturing .tmp-dogfood/dogfood-self-report.png

Friction

Area Observation Severity Proposed Fix
Real report data Using current repository JSON made the host report more representative than static demo values and caught that prepareDomAnnotations obstacle specs must stay array-shaped. low Keep the self-dogfood harness in npm run check so API drift in clean consumers is caught quickly.
Generated SVG surfaces The chart and diagram behaved like ordinary host-owned SVG: generate the marks first, call annotationFrameFromSvg(), then resolve annotations in the same viewBox. low Keep this as the preferred recipe for host-generated SVG that is not owned by a vendor adapter.
Manual editorial placement Manual notes remain useful for audit rows and flow edges, but the author must think in the surface coordinate system. medium Pair manual placement with edit handles and the opt-in static SVG includeQualityIssues or React qualityDebug issue overlay when integrating into a production host.

Outcome

  • Would ship with this API today: yes for 0.1.x self-dogfood and canary use
  • Required package changes before public release: none blocking from this pass
  • Changes that should happen before a broader public release: keep collecting friction from an external production host, not only this self-report
  • Screenshots or browser evidence: .tmp-dogfood/dogfood-self-report.png from npm run test:dogfood:self-report
Edit Markdown source ↗All docs ↗