Re-charter around the package artefact: decompose/flatten with bijection tests, then builder migration

[Mearman]

Companion to the DocumentPackage promotion (umbrella in ExaDev/document-schema.js#20). This package becomes the migration path and then re-charters around the artefact.

Phase 1 (now): add decompose(pkg: DocumentPackage): PackageNode[] and flatten(nodes): ContentDocument over the current package shape, with the bijection property tests (decompose(flatten(x)) === x and both ways) run over real corpus documents of all five kinds -- these tests are the gate for the whole promotion. Hashing and equality helpers resolve over effective properties so they are stable across serialisation choices. The existing buildOutline stays; it is the TOC projection and can be expressed over decompose's output.

Phase 2 (at promotion): the builder logic migrates into documents.js's package boundary (one implementation, one authority -- no second copy of the grouping semantics); buildOutline deprecates in favour of the boundary's decompose. The package survives as artefact utilities for consumers holding a package JSON without importing the producer: TOC projection, flatten-to-leaves, leaf text, stable content hash -- the small, tree-shakeable dependency shape the edge-runtime consumers are asking for (ExaDev/documents.js#582's read-only pressure).

The grouping semantics (stack behaviour on headingLevel skips, list nesting resets at plain paragraphs, synthetic group labels) are already implemented and reviewed here; phase 2 ports rather than redesigns them, so the bijection tests travel unchanged.

[Mearman]

Phase-1 scope corrections from the implementation review, before this work starts:

• The tree this package builds follows the amended shape in Promote DocumentPackage to the single hierarchical tree: structure, layout, and content in one artefact document-schema.js#20's latest comment: section groups are mandatory, and grouping never crosses container boundaries -- the current presentation handler's "slide's paragraphs across its shapes in shape order" is a lossy TOC projection; decompose groups within one container's block flow and shapes survive as groups with their inner blocks intact.
• The OutlineNode { text, level, children } type is a projected label -- exactly what decompose must not embed. Phase 1 introduces a new PackageNode type ({ node, children } groups embedding anchor paragraphs or container descriptors; bare leaves with kind and no children); buildOutline keeps its projection as the TOC view, expressed over the new types.
• The bijection tests are new work in phase 1 (nothing existing travels): three laws -- strict structural equality for table-free packages, effective-property equality universally, minting idempotence -- over an outline-local corpus plus schema-shaped generators. documents.js later re-runs the same assertions over its real corpus as the promotion's merge gate.
• Phase 2's port rewrites the node type and re-scopes the slide grouping per above; what genuinely travels is the wordprocessing stack semantics and the per-kind handler structure.

[Mearman]

Phase 1 landed in #3 — decompose/flatten over the package shape, the three bijection laws pinned over the five-kind corpus, and the effective-property resolution seam, all on main now.

Leaving this open: phase 2 (porting the grouping semantics into the documents.js package boundary and deprecating buildOutline in favour of it) is still to come, tracked under the promotion umbrella in ExaDev/document-schema.js#20.

[Mearman]

Both phases landed. Phase 1: decompose/flatten with the three-law bijection tests (PR #3). Phase 2: the grouping semantics ported into documents.js's package boundary as assemblePackage/decompose/flattenPackage/factorStyles (documents.js PRs #634 and #635, with the bijection suite re-proven over documents.js's real corpus in src/convert/bijection.test.ts); this package re-charted around the artefact utilities over schema 4's tree types (PR #4). One implementation, one authority.