This repository was archived by the owner on Aug 20, 2026. It is now read-only.
feat!: re-charter around schema 4's tree-form DocumentPackage - #4
Merged
Conversation
…tPackage DocumentPackage is itself the tree since schema 4.0.0, so the tree vocabulary now imports from the schema and this package keeps no second copy of it. Drop decompose/flatten/documentEnvelope and the local PackageNode module wholesale: the lossless tree <-> flat pair and its bijection property tests live in documents.js's package boundary now (one implementation, one authority), and the removal is outright -- no deprecated residue. buildOutline keeps its own OutlineNode output shape and unchanged stack semantics, now projecting pkg.children per kind over the tree groups; it deliberately re-groups across container boundaries, which is the lossiness a table of contents wants and why the lossless pair belongs to the package boundary. effectivePackage replaces effective/effectiveTree: group style refs resolve through the schema's own overlay helpers (resolveStyleChain, applyParagraphStyleProperties, applyRunStyleProperties) with nearest-wins chains, gap-fill-never-overwrite semantics, the block flow as the walk's boundary, the styles table dropped from the result, and unknown refs throwing loudly; effectivePackage(factored) deep-equals effectivePackage(unfactored), and the resolve-then-hash route rides it. stableContentHash strips $schema keys recursively before canonicalising, matching the schema's serialisation stamp, so a serialised dump and its rehashed original agree while no content field changes hash. BREAKING CHANGE: removes decompose, flatten, documentEnvelope, the DocumentEnvelope type, the PackageNode type family with PackageNodeSchema and its guards, and effective/effectiveTree. The lossless tree <-> flat transform now lives in documents.js's package boundary; tree node types (PackageNode, PackageGroup, SectionGroupNode, and the rest) import from document-schema.js, which this package now requires at ^4.0.0.
The package is now utilities for consumers holding a tree-form package JSON without importing the producer: buildOutline is the TOC projection over PackageNode trees with its own OutlineNode output shape, effectivePackage resolves style refs through the schema's overlay helpers, and the flatten/leaf-text/hash helpers keep their contract with the $schema-exclusion step now documented in the recipe. decompose and flatten are documented as documents.js's, and the removal is the release note -- no deprecated residue anywhere.
|
🎉 This PR is included in version 1.0.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Schema 4.0.0 made
DocumentPackageitself the tree, so this drops the phase-1decompose/flattenpair and the localPackageNodevocabulary wholesale and re-charters the package around what a consumer holding a tree-form package JSON actually needs. This is the outline side of #2 phase 2 (the decompose/flatten port into documents.js's own major is tracked separately in the same wave); it also completes the consumption side of the tree promotion from ExaDev/document-schema.js#20. The issue stays open until the documents.js port lands.What changed:
document-schema.jsbumped to^4.0.0. All tree types (PackageNode,PackageGroup,SectionGroupNode,SlideGroupNode,SheetGroupNode,DrawPageGroupNode,ShapeGroupNode,HeadingGroupNode,ListGroupNode,PackageLeaf) now import from the schema — one authority, no second copy here.OutlineLeafis aliased to the schema'sPackageLeafandisOutlineLeafdelegates to its guard.decompose,flatten,documentEnvelope/DocumentEnvelope,outline/package-node, and their tests and corpus are deleted outright, not deprecated. The lossless tree↔flat pair and its bijection now live in documents.js's package boundary.buildOutlineprojectspkg.childrenper kind, keeping its ownOutlineNodeoutput shape and the same stack semantics. It is documented as the TOC projection (it re-groups across container boundaries — sections flow into one tree, a slide's paragraphs cross its shapes), which is the deliberate lossiness that separates it from the lossless pair.effectivePackagereplaceseffective/effectiveTree: resolves groupstylerefs through the schema's own overlay helpers (resolveStyleChain,applyParagraphStyleProperties,applyRunStyleProperties), chains outermost-first so nearest wins, own properties always win, the run half applies to every run, the walk stops at the block-flow boundary (table cells and embedded documents are leaf-local), the styles table is dropped from the result, unknown refs throw.effectivePackage(factored)deep-equalseffectivePackage(unfactored)— pinned by test.stableContentHashnow strips$schemakeys recursively before canonicalising, so a serialised dump and its rehashed original agree; no content field is named$schema, so no issued content hash changes.leafContentHashdocuments the resolve-then-hash route (effectivePackagefirst, then hash the resolved leaves) without folding resolution into the leaf call itself.One CI note: the Release job on main currently fails at its
actions/create-github-app-tokenstep (the documents-js App grant is still pending). That failure predates this branch and is expected; if it is the only red check here I will treat the run as green rather than gate on it.Generated by Claude Code