feat!: migrate --dump-package and from-package to documents.js 3.0.0's tree-form package - #229
Merged
Conversation
…s tree-form package
DocumentPackage is the single hierarchical tree since document-schema.js 4:
content grouped one group per container (section, slide, sheet, draw page)
under children, with the content nodes carrying their own rendered frames,
the pages geometry at the root, and the minted styles table beside it -- so
a dump written now holds {$schema, kind, metadata, children, pages} and no
formatVersion integer at all: the version-pinned $schema URI the dumper
stamps IS the package's version.
from-package reads the tree through documentFromJson's dispatch and
flattens once at its boundary (flattenPackage), handing the flat
ContentDocument to buildCsvText/buildSvgText (whose signatures never
changed) and the tree itself to buildDocumentBytes. Pre-4.0.0 dumps --
the flat { formatVersion, content, pages } envelope documents.js 1.x/2.x
wrote, whatever its formatVersion -- are refused by documentFromJson's
own version gate with SchemaVersionMismatchError, surfaced as a readable
line naming the pinned release, the flat-to-tree change, and the remedy;
the CLI-level formatVersion-1 intercept this command carried existed only
because the old dispatch had no gate and died in DocumentPackageSchema.parse
with a raw ZodError wall. A layout-document dump (a document-schema.js 3.x
layout artefact, e.g. an old pdf-inspect --full output) gets the demotion
pointer: that schema moved to pdf-codec.
pdf-inspect --full dumps the plain LayoutDocument: layoutDocumentWithSchema
retired with the demotion (a LayoutDocument is a pdf-codec value with no
schema-stamped envelope any more), so there is nothing to tag the dump with.
BREAKING CHANGE: from-package no longer reads documents.js 1.x/2.x dump
files; --dump-package output follows documents.js 3.0.0 and pdf-inspect
--full output no longer carries a $schema key.
Nothing in this tree imports document-outline.js, and its file: specifier resolved against a local checkout path -- the lockfile entries it produced (file:../outline-pinned) point at a directory that exists only on the machine that generated them, so a clean frozen-lockfile install dies with ENOENT before any job runs. A registry specifier is the only kind a published lockfile can carry.
The command stopped stamping a $schema key when layoutDocumentWithSchema retired with the pdf-codec demotion -- the README passage still described the old schema-tagged dump without saying so.
This was referenced Aug 18, 2026
Contributor
|
🎉 This PR is included in version 3.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 join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Part of the DocumentPackage tree promotion tracked on ExaDev/document-schema.js#20, following the documents.js 3.0.0 / document-schema.js 4.0.0 / pdf-codec 3.0.0 majors.
What changed
documents.js^3.0.1(+pdf-codecdevDep^3.0.0, one coherent set with the majorodf.js^4.0.0already carries):ConversionResult.packageis now the tree-formDocumentPackage— content grouped one group per container (section, slide, sheet, draw page) underchildren, content nodes carrying their own renderedframes,pagesgeometry at the root, mintedstylestable beside it.--dump-packagewrites the tree package, self-describing through the version-pinned$schemaURIdocumentPackageWithSchemastamps (the URI is the package's version — theformatVersioninteger is gone from schema 4).from-packagereads tree dumps throughdocumentFromJson's dispatch and flattens once at its boundary (flattenPackage): the flatContentDocumentgoes tobuildCsvText/buildSvgText(signatures unchanged), the tree itself tobuildDocumentBytes. Pre-4.0.0 dumps — the flat{ formatVersion, content, pages }envelope documents.js 1.x/2.x wrote — are refused bydocumentFromJson's version gate withSchemaVersionMismatchError, surfaced as a readable line naming the pinned release, the flat-to-tree change, and the remedy (extending the formatVersion-1 intercept precedent; the CLI-level intercept is gone because the dispatch itself now gates versions). A layout-document dump (an oldpdf-inspect --fulloutput) gets the demotion pointer instead.pdf-inspect --fulldumps the plainLayoutDocument—layoutDocumentWithSchemaretired with the demotion (aLayoutDocumentis a pdf-codec value with no schema-stamped envelope any more), and theLayout*names this CLI uses still import fromdocuments.js, which re-exports them from pdf-codec unchanged.Follow-up held on an external blocker: a
--outlinemode rendering the TOC projection over the tree viabuildOutlinefrom document-outline.js (that package's first real consumer, the retention criterion on document-outline.js#2) is prepared as a second PR and held until document-outline.js publishes a real npm release — its CI release job is currently blocked on the npmjs trusted-publisher registration for the package, which only the maintainer can add in the npm web UI.Refs ExaDev/document-schema.js#20, ExaDev/document-outline.js#2.
Generated by Claude Code