bronto/annotations

DOCUMENTATION / PUBLIC-RELEASE-DECISIONS

Public Release Decisions

This document records the release-positioning decisions for the 0.1.x hardening lane. npm run test:repo and npm run test:pre-release check these decisions so package metadata, docs, and release automation do not drift.

Package Name

  • Public package name: @ponchia/annotations
  • Rationale: the package is a public annotation engine for host-supplied geometry, not an add-on for one private product or report surface.
  • Enforcement: package.json, docs/api-stability.manifest.json, scripts/prepare-github-canary.mjs, and registry smoke tests all use @ponchia/annotations.
  • Current canary evidence: the GitHub Packages smoke test installed @ponchia/annotations@0.1.0-canary.1.e754177 from a clean consumer.

Ownership

  • GitHub owner: Ponchia
  • Package owner/scope: @ponchia
  • CODEOWNERS and GitHub Actions release environments own repository guardrails.
  • Product boundary: this package owns annotation models, anchors, placement, collision handling, connector geometry, render helpers, and adapter contracts. It does not own chart rendering, diagram parsing, graph layout, app state, persistence, routing, workflow execution, or a design system.

Repository Name And Visibility

  • Repository for 0.1.x: Ponchia/bronto-annotations
  • Policy: make the repository public for the real 0.1.0 npm release after final git-history, tarball, metadata, CI, and clean-consumer checks pass.
  • Rename policy: do not rename before 0.1.0.
  • If the repository is renamed later, update package.json repository, homepage, and bugs metadata; canary linkage checks; release docs; README links; and registry smoke evidence in the same change.

Npm Access And Provenance

  • Public npm access: publishConfig.access is public.
  • Public release path: pushed v* tags run the Release workflow, pause at the protected npm-publish GitHub Environment, and publish with npm publish --ignore-scripts --provenance --access public --tag "$dist_tag".
  • Future releases should use npm Trusted Publishing for OIDC/provenance rather than a long-lived NPM_TOKEN.
  • Canary path: GitHub Packages publishes unique 0.1.0-canary.* versions and installs the exact version from a clean registry consumer.
  • Required proof before public npm release: npm run check, npm pack --dry-run, canary registry smoke, root import without optional peers, and declarations for every exported subpath.

README Positioning

  • README headline stays # @ponchia/annotations.
  • First-viewport positioning: DOM-independent annotation engine for host geometry from SVG, DOM/report surfaces, Vega/Vega-Lite, Mermaid, D2, and React Flow.
  • Boundary positioning: this is not a chart engine, diagram or graph layout engine, app-state layer, persistence layer, router, workflow engine, or design system.

Examples Hosting

  • Examples remain in-repository under examples/.
  • Browser evidence is generated by npm run test:browser and archived by CI as screenshot artifacts.
  • Visual baselines live in test/visual-baselines/browser-screenshots.json.
  • No separate hosted examples site is required before 0.1.0; README and packaged docs are the canonical public entry points.

October 2026: Published Presentation (0.3.x)

The historical 0.1.x decision to keep examples solely within the repository was sufficient for the initial npm release. At 0.3.x the repo publishes a static, framework-independent product site and all compiled example fixtures using GitHub Pages: https://ponchia.github.io/bronto-annotations/.

The website is generated from the existing examples and authored Markdown. The package still owns only annotation geometry, placements and adapters; BrontoUI remains a separate, optional visual system. Site-specific CSS and playground code are never included in the headless npm runtime.

Edit Markdown source ↗All docs ↗