0.16 → 0.17: deprecate UI-owned annotations

This edge is recorded in MIGRATIONS.json. There is no runtime removal in 0.17. The exported @ponchia/ui/annotations helpers, @ponchia/ui/css/annotations.css, .ui-annotation* selectors and annotation class recipes remain available through this minor. The earliest intended breaking removal is 0.18, after the 0.17 deprecation has shipped and consumers have a migration opportunity.

Package ownership

Neither package imports or re-exports the other. Keep the UI package dependency-free. Annotations reads optional Bronto theme tokens through CSS fallbacks; its core works with no UI package or DOM.

Migrate a geometry consumer

Use the published stable Annotations 0.7.0 package for a legacy UI-helper migration. The 0.7.0 npm tarball has been checked against the historical UI geometry contract; an earlier release candidate is no longer required:

npm install @ponchia/annotations@0.7.0

// Before:
import { annotationParts, notePlacement } from '@ponchia/ui/annotations';

// After:
import { annotationParts, notePlacement } from '@ponchia/annotations';

Runtime floor: the published @ponchia/ui@0.19.0 package supports Node 18+, while the published @ponchia/annotations@0.7.0 package declares Node 20.19+. This is a real compatibility change for Node 18 applications and build pipelines. Upgrade and verify the consumer runtime before replacing the UI subpath; do not disguise the difference by re-exporting the newer package through UI.

The standalone engine includes the legacy geometry helpers, with source parity checks documented in bronto-ui-annotation-parity.json. Do not assume all type signatures, higher-level layout policies or results remain identical without consumer tests. The standalone package additionally provides resolveAnnotationLayout, React/SVG rendering, editing and adapters.

Verified stable geometry contract

On 24 October 2026, the published @ponchia/annotations@0.7.0 tarball was downloaded from npm and its bytes verified against the registry's SHA-512 integrity:

sha512-aFzPefUhK/y8hzcsqTjrbpBX9wyWGMQAQRjkIHUuzBSsYmPnNxzM9BvRR1ZUU4uJ/KPQ0ngrJB/jJlhlyIAdJA==

It was installed with lifecycle scripts disabled in a clean consumer with no UI or React dependency. All 20 legacy UI geometry test groups from test/annotations.test.mjs passed with only the import redirected to the installed package. This covers the oversized-note fallback and invalid timeline/subject cases that differed in 0.6.10; that older stable version passed 18 of the 20 groups.

This establishes the tested legacy helper contract, not every higher-level API or computed style. Review the 0.7 API migration when upgrading an existing Annotations 0.6 application. In particular, diagnostic retention, React render inputs and D3-specific import paths changed. The registry's published version is the installation authority; older release notes may describe the preceding candidate.

Migrate CSS and class names

/* Before, from Bronto UI's legacy SVG annotation leaf: */
@import '@ponchia/ui/css/annotations.css';

/* After, standalone package owns presentation: */
@import '@ponchia/annotations/bronto.css';

Keep @ponchia/ui for application styling or @ponchia/ui/css/figure.css for figure stages. Do not import both legacy annotation leaves into the same page: duplicate selectors can have competing precedence.

@ponchia/annotations/bronto.css supports the legacy .ui-annotation* selectors, so old static SVG can migrate stylesheets before migrating markup. Prefer the package's .pa-annotation* classes for new code:

import { annotationClassName, brontoAnnotationClassName } from '@ponchia/annotations';

annotationClassName({ variant: 'callout', tone: 'accent' });
// 'pa-annotation pa-annotation--callout pa-annotation--accent'
brontoAnnotationClassName({ variant: 'callout', tone: 'accent' });
// legacy: 'ui-annotation ui-annotation--callout ui-annotation--accent'

The legacy Bronto ui.annotation() recipe and cls.annotation* keys remain through 0.17 so applications can migrate gradually. Port source references rather than re-exporting them from Bronto UI.

Avoid indirect duplicate styles

During 0.17, both @ponchia/ui/css/analytical.css and @ponchia/ui/css/report-kit.css still include the deprecated annotation leaf for compatibility. Replacing only a direct annotations.css import is not sufficient if a roll-up also loads it. A migrated consumer should import the UI leaves it actually uses, rather than these two roll-ups:

@import '@ponchia/ui';
@import '@ponchia/ui/css/report.css';
@import '@ponchia/ui/css/figure.css';
@import '@ponchia/ui/css/dataviz.css';
@import '@ponchia/ui/css/legend.css';
@import '@ponchia/annotations/bronto.css';

Add other UI leaves as needed. The default UI bundle itself does not include annotation CSS. Preserve meaningful contrast, reduced motion, forced colors and print behavior when reviewing the replacement stylesheet: coverage of legacy selector names does not establish identical computed styles.

Installed-package integration proof

The independent annotations example installs this UI candidate from its packed tarball and Annotations 0.7.0 from npm. It creates a real annotation, changes its target, hides/restores it, resizes the shared coordinate space and switches UI themes without any legacy UI annotation import. Neither library depends on the other. Run:

npm run test:examples:cross-browser -- annotations-vite
npm run test:examples:visual -- annotations-vite

This is first-party installed-package evidence, not an independent-user acceptance or a replacement for the later application-integration review.

Audit source without rewriting it

The opt-in source audit first shipped with UI 0.17.1 (and remains available in 0.18.1); UI 0.17.0 did not include this CLI mode. Future patches may add conservative review markers without changing the ordinary markup validator. From a checkout containing the audit, run:

node bin/bronto-ui-check.mjs --migration 0.17 /path/to/consumer/src
node bin/bronto-ui-check.mjs --migration 0.17 --json /path/to/consumer/src

After installing a package that includes the mode, use npx --no-install bronto-ui-check --migration 0.17 src. Ordinary validation without --migration still accepts the deprecated 0.17 surface.

The audit checks geometry imports, direct layered/unlayered annotation styles, the analytical/report-kit roll-ups, legacy markup, and conventional ui.annotation / cls.annotation* references. It also recognizes named ESM/CJS aliases imported from @ponchia/ui/classes, direct quoted-bracket members, and simple constant keys such as const key = 'annotation'; ui[key](). Two-part static concatenations of known UI specifiers are reported. Rules and review guidance live with this migration in MIGRATIONS.json. Output names source files and lines; JSON also includes the guide, coverage scope and scanned file count. Source files are never rewritten. Exit 1 means findings require review; exit 2 means invocation/read failure, an unsupported migration, or no supported source files. A clean literal scan exits 0.

A finding is a review marker, not proof that a consumer loads UI-owned annotation styles: the standalone compatibility stylesheet deliberately supports old markup. Mutable/indirect aliases, computed names that depend on runtime data, locally re-exported CSS, generated output and runtime behavior still require separate inspection. Comments and standard generated/vendor directories are ignored during source traversal. This scan does not establish geometry, deployment or accessibility acceptance and does not authorize physical API removal.

Acceptance before the removal PR

1. Run the source audit above where available. Also inspect import aliases, local stylesheet re-exports and generated code that a literal scan cannot resolve.
2. Upgrade actual package dependencies and lockfiles; do not rely only on checkout-relative aliases or fixture mocks.
3. Verify geometry, overlay alignment and labels at narrow/large viewport sizes, changed zoom/pan, dark/light themes and printed output.
4. Verify keyboard and physical touch interaction where annotation editing is enabled; passing unit or axe checks are not a substitute.
5. Run the host's permission, persistence, undo/redo, collaboration and renderer-lifecycle tests where applicable (including Spatial).
6. The 0.17 deprecation release is published. Confirm real consumers have migrated before scheduling 0.18's separate BREAKING removal of the public API, CSS, recipes, generated exports, deprecated tests and demos.

Generic @ponchia/ui/connectors and initConnectors() remain independent UI leader-line primitives; this migration does not delete them.