Package-local referenced styles and group inheritance: compression-only, materialised on flatten

[Mearman]

The package tree's nodes are self-describing: every run and paragraph carries its resolved direct properties, because codecs resolve source style cascades at read time. That is the right semantics but the wrong payload for documents consumed in token-metered contexts (the MCP/LLM path) -- a document with one body style applied to hundreds of paragraphs repeats the property tuple hundreds of times. This issue adds the two standard compression mechanisms, under one hard constraint.

Proposed shape:

{
  "styles": {
    "s1": { "paragraph": { "alignment": "justified", "spacingAfterPt": 6 },
            "run": { "fontPt": 11 } }
  },
  "children": [
    { "node": { "kind": "paragraph", "style": "s1", "styleId": "BodyTextFirstIndent20", "runs": [ ... ] },
      "style": "s1",
      "children": [ ... ] }
  ]
}

• Referenced styles: a package-local styles table; nodes carry style refs into it. Inherited styles: a group's style cascades to descendants. Resolution is one overlay chain -- package base, nearest ancestor group's style, the node's own style ref, the node's direct properties; innermost wins. The same overlay applies one level further down for run defaults vs a run's own properties.

Rules that keep this from re-importing what resolve-at-read was built to avoid:

• Compression only, never semantics: the flat codec-exchange form is always fully materialised (no table, no refs); flatten() expands references and inheritance into direct properties; effective properties are identical in both forms by law. The table is a dictionary, not a program: no basedOn graph inside it, resolved canonical properties only, and never frames -- a position is a fact about a node, not a style.
• style is not styleId: the new ref points at the package's own minted table (producer-side, deterministic -- a frequency pass factoring repeated property tuples into s1, s2, ... in stable order); styleId keeps its existing job as the source format's opaque style name for round-trip fidelity.
• Comparison and hashing operate on effective properties: two serialisations of the same document may differ in how aggressively they factored the table, so content hashing and structural diffing resolve first.

Rides the DocumentPackage promotion (ExaDev/document-schema.js umbrella) without a version bump of its own, but belongs in its design from day one -- minting discipline and effective-property hashing are cheapest to get right before any consumer has hashed a serialised form.

[Mearman]

Corrections before implementation:

• The example's "fontPt" is a typo for the real field sizePt (ContentRunSchema, src/content.ts).
• style refs exist only on tree nodes and groups, never on ContentDocument nodes -- the flat codec-exchange form is always fully materialised, no table, no refs. Stated here so nobody adds the ref field to the content schema.
• The ban list for what a table entry may carry extends beyond frames to also name sourcePath and styleId: those are per-node facts, and letting them into a tuple key fragments the table to uselessness.
• Minting mechanics: factoring is a separate pass from decompose (keeps the idempotence law testable); only property-tuples occurring two or more times are factored (a singleton ref plus its table entry is larger than the inline tuple); paragraph-tuples and run-tuples live in separate namespaces; entry order is (descending frequency, first-occurrence document order, canonical-serialised tuple as tie-break) so the pass is deterministic; tuple identity reuses document-outline.js's stableContentHash canonicalise-then-stringify recipe rather than minting a second one.
• This rides the promotion major of Promote DocumentPackage to the single hierarchical tree: structure, layout, and content in one artefact #20 as a generic package-level definitions-table facility (styles are the first tenant; link and footnote definitions are the same mechanism -- see Fidelity construct inventory: reference links, footnotes, raw HTML, frontmatter markdown-codec#63).

[github-actions]

🎉 This issue has been resolved in version 4.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀