markdown-codec 5.0.2 → 6.0.0

package/README.md

@@ -2,9 +2,9 @@
 
 [![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/documents.js/tree/main/packages/markdown-codec) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/markdown-codec) [![npm version](https://img.shields.io/npm/v/markdown-codec)](https://www.npmjs.com/package/markdown-codec) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/documents.js/ci.yml?branch=main)](https://github.com/ExaDev/documents.js/actions)
 
-> Hand-written CommonMark+GFM ⇄ `DocumentPackage` codec, built on [document-schema.js](../document-schema.js/README.md).
+> Hand-written CommonMark+GFM ⇄ `DocumentTree` codec, built on [document-schema.js](../document-schema.js/README.md).
 
-The same "hand-write the format instead of wrapping a third-party library" bet as [`pdf-codec`](../pdf-codec/README.md), aimed at CommonMark and GFM. No `micromark`/`remark`/`marked`/`markdown-it`/`commonmark`/`mdast`/`unified`/`turndown`/`showdown` dependency (enforced by eslint `no-restricted-imports`). Runtime dependencies: `document-schema.js` (the shared pivot) and `zod`. `readMarkdown`/`writeMarkdown` read and write that pivot's tree-form `DocumentPackage`; `readMarkdownContent`/`writeMarkdownContent` read and write the flat `ContentDocument` underneath it — the same model [`documents.js`](https://github.com/ExaDev/documents.js) builds docx/pptx/odt/odp conversions around. See [Two encodings](#two-encodings-documentpackage-and-contentdocument).
+The same "hand-write the format instead of wrapping a third-party library" bet as [`pdf-codec`](../pdf-codec/README.md), aimed at CommonMark and GFM. No `micromark`/`remark`/`marked`/`markdown-it`/`commonmark`/`mdast`/`unified`/`turndown`/`showdown` dependency (enforced by eslint `no-restricted-imports`). Runtime dependencies: `document-schema.js` (the shared pivot) and `zod`. `readMarkdown`/`writeMarkdown` read and write that pivot's tree-form `DocumentTree`; `readMarkdownContent`/`writeMarkdownContent` read and write the flat `ContentDocument` underneath it — the same model [`documents.js`](https://github.com/ExaDev/documents.js) builds docx/pptx/odt/odp conversions around. See [Two encodings](#two-encodings-documentpackage-and-contentdocument).
 
 ```mermaid
 graph TD
@@ -91,9 +91,9 @@ const markdown = writeMarkdown(documentPackage, {
 });
 ```
 
-`documentPackage` is a `DocumentPackage` — document-schema.js's tree form, with a minted styles table (see [Two encodings](#two-encodings-documentpackage-and-contentdocument)). The field is named `documentPackage` rather than `package` because `package` is a reserved word in strict mode, so `const { package } = readMarkdown(src)` would not parse.
+`documentPackage` is a `DocumentTree` — document-schema.js's tree form, with a minted styles table (see [Two encodings](#two-encodings-documentpackage-and-contentdocument)). The field is named `documentPackage` rather than `package` because `package` is a reserved word in strict mode, so `const { package } = readMarkdown(src)` would not parse.
 
-Both accept an optional `signal` (`AbortSignal`) and `sink` (`MarkdownDiagnosticSink`, called once per recoverable issue or construct-mapping gap — see [Gotchas](#gotchas-and-quirks)). `writeMarkdown` throws `MarkdownUnsupportedDocumentKindError` for a package whose `kind` is not `'wordprocessing'`, checked before flattening so every non-`'wordprocessing'` package reaches it the same way regardless of what else about that package would have failed document-schema.js's own `flattenPackage`. A `'wordprocessing'` package can still fail to flatten — a group carrying a style reference the package's own `styles` table has no entry for — and that failure surfaces as `MarkdownPackageFlattenError`, not a bare `Error` from the dependency. A `DocumentPackage`'s own `layers`/`attachments`/`destinations`/`pages` tables have no flat-`ContentDocument` home to land in; `writeMarkdown` reports one `PACKAGE_TABLE_DROPPED` diagnostic per non-empty table it finds rather than dropping them without a trace. The `definitions` table is the one exemption: this package's own link-tenant entries (what `readMarkdown` splices there from the source's reference definitions) render back out as `[label]: destination "title"` lines, so only a table holding foreign tenants reports.
+Both accept an optional `signal` (`AbortSignal`) and `sink` (`MarkdownDiagnosticSink`, called once per recoverable issue or construct-mapping gap — see [Gotchas](#gotchas-and-quirks)). `writeMarkdown` throws `MarkdownUnsupportedDocumentKindError` for a package whose `kind` is not `'wordprocessing'`, checked before flattening so every non-`'wordprocessing'` package reaches it the same way regardless of what else about that package would have failed document-schema.js's own `flattenTree`. A `'wordprocessing'` package can still fail to flatten — a group carrying a style reference the package's own `styles` table has no entry for — and that failure surfaces as `MarkdownPackageFlattenError`, not a bare `Error` from the dependency. A `DocumentTree`'s own `layers`/`attachments`/`destinations`/`pages` tables have no flat-`ContentDocument` home to land in; `writeMarkdown` reports one `PACKAGE_TABLE_DROPPED` diagnostic per non-empty table it finds rather than dropping them without a trace. The `definitions` table is the one exemption: this package's own link-tenant entries (what `readMarkdown` splices there from the source's reference definitions) render back out as `[label]: destination "title"` lines, so only a table holding foreign tenants reports.
 
 The same round trip as a schema-validated [`z.codec()`](https://zod.dev) pair, mirroring `pdf-codec`'s `pdfCodec`:
 
@@ -107,20 +107,20 @@ const bytes2 = z.encode(markdownCodec, documentPackage);
 
 `MarkdownBytesSchema` checks for well-formed UTF-8. The no-options form only; `readMarkdown`/`writeMarkdown` remain the entry points for an `AbortSignal` or diagnostic sink. Every construct-mapping gap reports through the sink as a stable code (e.g. `md/nested-emphasis-flattened`) — see `MarkdownDiagnosticCodes` and [Gotchas](#gotchas-and-quirks).
 
-## Two encodings: `DocumentPackage` and `ContentDocument`
+## Two encodings: `DocumentTree` and `ContentDocument`
 
-document-schema.js states one document in two shapes, and owns the transform between them: the flat `ContentDocument` every codec's lowering pipeline actually builds, and the tree-form `DocumentPackage` a serialised artefact carries — sections, headings, lists, and construct boundaries as real nested groups, plus a styles table minted over repeated property tuples. `assemblePackage` goes flat → tree (`decompose` then `factorStyles`), `flattenPackage` goes tree → flat. Only one direction is a genuine round trip: `flattenPackage(assemblePackage(document))` reproduces `document` exactly, for any `ContentDocument` this package's own read side produces (checked against the full CommonMark and GFM conformance corpora, not just a hand-picked fixture — see `src/conformance.test.ts`/`src/gfm-conformance.test.ts`'s own "tree pair matches the flat pair" suite). `assemblePackage(flattenPackage(documentPackage))` does not, in general, reproduce `documentPackage` — a package carrying `definitions`/`layers`/`attachments`/`destinations`/`pages` loses all of them on the way through `flattenPackage`, which carries forward only `metadata` and `symbolTable` (see [Gotchas](#gotchas-and-quirks)).
+document-schema.js states one document in two shapes, and owns the transform between them: the flat `ContentDocument` every codec's lowering pipeline actually builds, and the tree-form `DocumentTree` a serialised artefact carries — sections, headings, lists, and construct boundaries as real nested groups, plus a styles table minted over repeated property tuples. `assembleTree` goes flat → tree (`decompose` then `factorStyles`), `flattenTree` goes tree → flat. Only one direction is a genuine round trip: `flattenTree(assembleTree(document))` reproduces `document` exactly, for any `ContentDocument` this package's own read side produces (checked against the full CommonMark and GFM conformance corpora, not just a hand-picked fixture — see `src/conformance.test.ts`/`src/gfm-conformance.test.ts`'s own "tree pair matches the flat pair" suite). `assembleTree(flattenTree(documentPackage))` does not, in general, reproduce `documentPackage` — a package carrying `definitions`/`layers`/`attachments`/`destinations`/`pages` loses all of them on the way through `flattenTree`, which carries forward only `metadata` and `symbolTable` (see [Gotchas](#gotchas-and-quirks)).
 
 This package exposes a read/write pair and a codec at each level. The unsuffixed names are the tree-form ones and are what to reach for by default — a codec is a construction site, so the tree is what a caller gets unless they ask for otherwise. The `Content`-suffixed names are the flat pair one level down, mirroring the `readXlsx`/`readXlsxContent` naming already in [`ooxml.js`](../ooxml.js/README.md):
 
 | Level | Read | Write | Codec | Value type |
 | --- | --- | --- | --- | --- |
-| Tree (default) | `readMarkdown` | `writeMarkdown` | `markdownCodec` | `DocumentPackage` |
+| Tree (default) | `readMarkdown` | `writeMarkdown` | `markdownCodec` | `DocumentTree` |
 | Flat | `readMarkdownContent` | `writeMarkdownContent` | `markdownContentCodec` | `ContentDocument` |
 
-The tree pair is the flat pair with the transform composed on — `readMarkdown` is `assemblePackage` over `readMarkdownContent`, `writeMarkdown` is `flattenPackage` before `writeMarkdownContent` — plus the two tree-only carries the flat form has no root for: the source's reference definitions splice into `documentPackage.definitions` (link tenant, keyed by normalised label) and the verbatim front-matter block into `documentPackage.source.frontmatter`, both rendered back out by `writeMarkdown` (`[label]: dest "title"` lines after the body; the original front matter verbatim in place of the regenerated block). Sources carrying neither render identically to the flat pair, pinned in `src/package.test.ts`; a source carrying either renders its extra block, which is the point of reaching for the tree. Options, diagnostics, and error behaviour are identical at both levels.
+The tree pair is the flat pair with the transform composed on — `readMarkdown` is `assembleTree` over `readMarkdownContent`, `writeMarkdown` is `flattenTree` before `writeMarkdownContent` — plus the two tree-only carries the flat form has no root for: the source's reference definitions splice into `documentPackage.definitions` (link tenant, keyed by normalised label) and the verbatim front-matter block into `documentPackage.source.frontmatter`, both rendered back out by `writeMarkdown` (`[label]: dest "title"` lines after the body; the original front matter verbatim in place of the regenerated block). Sources carrying neither render identically to the flat pair, pinned in `src/package.test.ts`; a source carrying either renders its extra block, which is the point of reaching for the tree. Options, diagnostics, and error behaviour are identical at both levels.
 
-Reach for the flat pair when composing a package boundary by hand (`decompose`/`flattenPackage` directly, or `factorStyles` with your own minting policy), when feeding a `ContentDocument`-consuming builder such as `documents.js`'s conversion pipeline, or when a layout stage needs to stamp frames onto content before it is decomposed. Everything else wants the tree.
+Reach for the flat pair when composing a package boundary by hand (`decompose`/`flattenTree` directly, or `factorStyles` with your own minting policy), when feeding a `ContentDocument`-consuming builder such as `documents.js`'s conversion pipeline, or when a layout stage needs to stamp frames onto content before it is decomposed. Everything else wants the tree.
 
 ```ts
 import { readMarkdownContent, writeMarkdownContent } from 'markdown-codec';
@@ -144,7 +144,7 @@ Modelled on `pdf-codec`'s own layering, aimed at CommonMark+GFM instead of PDF:
 - **`src/shared/`** — string-shape conventions `src/lower`/`src/emit` agree on (`style-constants.ts`, `list-id.ts`'s opaque `numId`). Re-exported so `documents.js`'s `MarkdownEditor` reuses the identical grammar.
 - **`src/lower/`** — AST → `ContentDocument` lowering (thin adapter, not a second parser); top-of-file table maps each construct to its diagnostic gap.
 - **`src/emit/`** — `ContentDocument` → markdown text emission, the structural inverse of `src/lower`.
-- **`src/read.ts`** / **`src/write.ts`** / **`src/codec.ts`** — the public entry points at both levels: `readMarkdown`/`writeMarkdown`/`markdownCodec` over `DocumentPackage`, and `readMarkdownContent`/`writeMarkdownContent`/`markdownContentCodec` over `ContentDocument`. The tree-form functions are thin compositions of `document-schema.js`'s `assemblePackage`/`flattenPackage` onto the flat ones; no conversion logic of their own lives here.
+- **`src/read.ts`** / **`src/write.ts`** / **`src/codec.ts`** — the public entry points at both levels: `readMarkdown`/`writeMarkdown`/`markdownCodec` over `DocumentTree`, and `readMarkdownContent`/`writeMarkdownContent`/`markdownContentCodec` over `ContentDocument`. The tree-form functions are thin compositions of `document-schema.js`'s `assembleTree`/`flattenTree` onto the flat ones; no conversion logic of their own lives here.
 
 ## Vendored assets
 
@@ -202,7 +202,7 @@ Every construct `src/lower`/`src/emit` cannot represent losslessly is a document
 - **`md/duplicate-footnote-definition`** — two definitions share a label; every reference resolves to the first, both are kept as written.
 - **`md/footnote-body-heading-flattened`** — a heading inside a definition body is carried as literal ATX text, since a construct extent may not open or close a heading scope.
 - **`md/construct-unrepresented`** — a construct kind markdown has no syntax for renders transparently: its extent still appears, the construct itself does not.
-- **`md/package-table-dropped`** — `writeMarkdown` only, ahead of flattening: a `DocumentPackage`'s own `definitions`/`layers`/`attachments`/`destinations`/`pages` table has no flat-`ContentDocument` home (`flattenPackage`'s own envelope carries forward only `metadata` and `symbolTable`); fires once per non-empty table present.
+- **`md/package-table-dropped`** — `writeMarkdown` only, ahead of flattening: a `DocumentTree`'s own `definitions`/`layers`/`attachments`/`destinations`/`pages` table has no flat-`ContentDocument` home (`flattenTree`'s own envelope carries forward only `metadata` and `symbolTable`); fires once per non-empty table present.
 
 ## Footnotes
 
@@ -210,8 +210,8 @@ GitHub's footnote extension (`[^label]` markers, `[^label]: body` definitions) i
 
 The two halves of a footnote map onto the **same `anchor` construct at two different scopes**, and that split is structural rather than a choice:
 
-- **A definition becomes an `anchor` construct.** Lowering emits document-schema.js's construct boundary markers — a `constructStart` carrying `{ kind: 'anchor', anchorType: 'footnote', name }`, the definition's own lowered body blocks, and a `constructEnd` — which is what `readMarkdownContent` returns in its block flow, and what `decompose` promotes to a construct group of its own in the `DocumentPackage` `readMarkdown` returns (the descriptor rides the group's `node`, the body blocks its `children`). The body rides the construct's extent rather than `AnchorDescriptor.definition`, which names a key in a package-level definitions table: `DocumentPackage` does carry that table as a root (unlike the flat `ContentDocument`), but a table entry there is a flat descriptor record, not a container for block content, so a body that is genuinely several paragraphs, a code block, or a list still has nowhere to live as a table value either way — the construct's own bracketed extent is the one shape in this schema built to hold real block content. A bodyless `[^1]:` lowers to the point anchor the same descriptor describes: a pair with nothing between it.
-- **A reference site becomes a point run-level `anchor` extent.** A reference sits between two runs inside a paragraph, so no block-level boundary marker can bracket it without splitting the paragraph in two — but a run-level construct extent (`RunConstructExtent` on `ContentParagraph.constructs`, document-schema.js 4.5.0) names exactly that shape. Lowering emits an ordinary text run keeping the reference's own `[^label]` spelling (the materialised rendering, so a consumer that ignores constructs still shows `[^1]`) plus a point extent — `{ kind: 'anchor', anchorType: 'footnote', name }` at `startRun === endRun` naming that run, the same wiring ooxml.js's docx reader mints for a `w:footnoteReference` — carried through `decompose`/`flattenPackage` verbatim, exactly the way a table cell's own markers are. The writer spells `[^label]` back out from the covering extent rather than from anything about the run's text (which is what still distinguishes a genuine reference from a deliberately-escaped literal `\[^1\]`), gated by the same label grammar as the definition marker: a foreign name that grammar cannot spell degrades to the run's own escaped text plus `md/construct-unrepresented`.
+- **A definition becomes an `anchor` construct.** Lowering emits document-schema.js's construct boundary markers — a `constructStart` carrying `{ kind: 'anchor', anchorType: 'footnote', name }`, the definition's own lowered body blocks, and a `constructEnd` — which is what `readMarkdownContent` returns in its block flow, and what `decompose` promotes to a construct group of its own in the `DocumentTree` `readMarkdown` returns (the descriptor rides the group's `node`, the body blocks its `children`). The body rides the construct's extent rather than `AnchorDescriptor.definition`, which names a key in a package-level definitions table: `DocumentTree` does carry that table as a root (unlike the flat `ContentDocument`), but a table entry there is a flat descriptor record, not a container for block content, so a body that is genuinely several paragraphs, a code block, or a list still has nowhere to live as a table value either way — the construct's own bracketed extent is the one shape in this schema built to hold real block content. A bodyless `[^1]:` lowers to the point anchor the same descriptor describes: a pair with nothing between it.
+- **A reference site becomes a point run-level `anchor` extent.** A reference sits between two runs inside a paragraph, so no block-level boundary marker can bracket it without splitting the paragraph in two — but a run-level construct extent (`RunConstructExtent` on `ContentParagraph.constructs`, document-schema.js 4.5.0) names exactly that shape. Lowering emits an ordinary text run keeping the reference's own `[^label]` spelling (the materialised rendering, so a consumer that ignores constructs still shows `[^1]`) plus a point extent — `{ kind: 'anchor', anchorType: 'footnote', name }` at `startRun === endRun` naming that run, the same wiring ooxml.js's docx reader mints for a `w:footnoteReference` — carried through `decompose`/`flattenTree` verbatim, exactly the way a table cell's own markers are. The writer spells `[^label]` back out from the covering extent rather than from anything about the run's text (which is what still distinguishes a genuine reference from a deliberately-escaped literal `\[^1\]`), gated by the same label grammar as the definition marker: a foreign name that grammar cannot spell degrades to the run's own escaped text plus `md/construct-unrepresented`.
 
 Definitions are recognised only at the document's own top level. Inside a block quote or a list item, the pair's extent would sit inside a scope the enclosing container had already opened, which the marker contract forbids a producer from emitting — so the text stays an ordinary paragraph there. A heading inside a definition body is flattened to literal ATX text for the same reason.
 
@@ -245,7 +245,7 @@ Conventional Commits, enforced workspace-wide by commitlint through a root `comm
 
 ## References
 
-- [document-schema.js](../document-schema.js/README.md) — owns both shared encodings (`ContentDocument`, `DocumentPackage`) and the `assemblePackage`/`flattenPackage` transform between them.
+- [document-schema.js](../document-schema.js/README.md) — owns both shared encodings (`ContentDocument`, `DocumentTree`) and the `assembleTree`/`flattenTree` transform between them.
 - [pdf-codec](../pdf-codec/README.md) — the sibling whose scaffold, tooling, and "hand-write the format" philosophy this project mirrors.
 - [documents.js](https://github.com/ExaDev/documents.js) — bridges markdown to docx/odt/PDF via this package's `ContentDocument` (the flat pair; its own conversion pipeline assembles the package itself). Markdown has no presentation/spreadsheet/drawing variant, so pptx/odp/ods/odg are structurally out of reach.
 - [CommonMark Spec](https://spec.commonmark.org/) — the base specification targeted.

package/dist/codec.cjs

@@ -13,7 +13,7 @@ function isWellFormedUtf8Text(bytes) {
 	}
 }
 const MarkdownBytesSchema = zod.z.instanceof(Uint8Array).refine(isWellFormedUtf8Text, { message: "not well-formed UTF-8 text" });
-const markdownCodec = zod.z.codec(MarkdownBytesSchema, document_schema_js.DocumentPackageSchema, {
+const markdownCodec = zod.z.codec(MarkdownBytesSchema, document_schema_js.DocumentTreeSchema, {
 	decode: (bytes) => require_read.readMarkdown(new TextDecoder().decode(bytes)).documentPackage,
 	encode: (documentPackage) => new TextEncoder().encode(require_write.writeMarkdown(documentPackage))
 });

package/dist/codec.js

@@ -1,7 +1,7 @@
 import { readMarkdown, readMarkdownContent } from "./read.js";
 import { writeMarkdown, writeMarkdownContent } from "./write.js";
 import { z } from "zod";
-import { ContentDocumentSchema, DocumentPackageSchema } from "document-schema.js";
+import { ContentDocumentSchema, DocumentTreeSchema } from "document-schema.js";
 //#region src/codec.ts
 function isWellFormedUtf8Text(bytes) {
 	try {
@@ -12,7 +12,7 @@ function isWellFormedUtf8Text(bytes) {
 	}
 }
 const MarkdownBytesSchema = z.instanceof(Uint8Array).refine(isWellFormedUtf8Text, { message: "not well-formed UTF-8 text" });
-const markdownCodec = z.codec(MarkdownBytesSchema, DocumentPackageSchema, {
+const markdownCodec = z.codec(MarkdownBytesSchema, DocumentTreeSchema, {
 	decode: (bytes) => readMarkdown(new TextDecoder().decode(bytes)).documentPackage,
 	encode: (documentPackage) => new TextEncoder().encode(writeMarkdown(documentPackage))
 });

package/dist/read.cjs

@@ -32,7 +32,7 @@ function linkDefinitionEntries(references) {
 }
 function readMarkdown(text, options = {}) {
 	const detail = readMarkdownDetail(text, options);
-	const assembled = (0, document_schema_js.assemblePackage)(detail.document);
+	const assembled = (0, document_schema_js.assembleTree)(detail.document);
 	const definitions = linkDefinitionEntries(detail.references);
 	const frontMatterResidue = detail.frontMatterSource === void 0 ? void 0 : {
 		format: "markdown",

package/dist/read.d.cts

@@ -1,9 +1,9 @@
 import { t as MarkdownDiagnostic } from "./diagnostics-CkcSYZf1.cjs";
 import { ReadMarkdownOptions } from "./options/options.cjs";
-import { ContentDocument, DocumentPackage } from "document-schema.js";
+import { ContentDocument, DocumentTree } from "document-schema.js";
 //#region src/read.d.ts
 interface ReadMarkdownResult {
-  readonly documentPackage: DocumentPackage;
+  readonly documentPackage: DocumentTree;
   readonly diagnostics: readonly MarkdownDiagnostic[];
 }
 interface ReadMarkdownContentResult {

package/dist/read.d.ts

@@ -1,9 +1,9 @@
 import { t as MarkdownDiagnostic } from "./diagnostics-CkcSYZf1.js";
 import { ReadMarkdownOptions } from "./options/options.js";
-import { ContentDocument, DocumentPackage } from "document-schema.js";
+import { ContentDocument, DocumentTree } from "document-schema.js";
 //#region src/read.d.ts
 interface ReadMarkdownResult {
-  readonly documentPackage: DocumentPackage;
+  readonly documentPackage: DocumentTree;
   readonly diagnostics: readonly MarkdownDiagnostic[];
 }
 interface ReadMarkdownContentResult {

package/dist/read.js

@@ -1,5 +1,5 @@
 import { lowerMarkdownDetailed } from "./lower/lower.js";
-import { assemblePackage } from "document-schema.js";
+import { assembleTree } from "document-schema.js";
 //#region src/read.ts
 function readMarkdownDetail(text, options) {
 	options.signal?.throwIfAborted();
@@ -31,7 +31,7 @@ function linkDefinitionEntries(references) {
 }
 function readMarkdown(text, options = {}) {
 	const detail = readMarkdownDetail(text, options);
-	const assembled = assemblePackage(detail.document);
+	const assembled = assembleTree(detail.document);
 	const definitions = linkDefinitionEntries(detail.references);
 	const frontMatterResidue = detail.frontMatterSource === void 0 ? void 0 : {
 		format: "markdown",

package/dist/write.cjs

@@ -34,7 +34,7 @@ function reportDroppedPackageTables(documentPackage, definitionsRendered, sink)
 		sink({
 			code: require_diagnostics_diagnostics.MarkdownDiagnosticCodes.PACKAGE_TABLE_DROPPED,
 			severity: "info",
-			message: `the package's own "${name}" table has no markdown representation; flattenPackage's envelope carries forward only metadata and symbolTable, so "${name}" is dropped rather than rendered`
+			message: `the package's own "${name}" table has no markdown representation; flattenTree's envelope carries forward only metadata and symbolTable, so "${name}" is dropped rather than rendered`
 		});
 	}
 }
@@ -46,7 +46,7 @@ function writeMarkdown(documentPackage, options = {}) {
 	reportDroppedPackageTables(documentPackage, definitionsBlock !== void 0, sink);
 	let flattened;
 	try {
-		flattened = (0, document_schema_js.flattenPackage)(documentPackage);
+		flattened = (0, document_schema_js.flattenTree)(documentPackage);
 	} catch (error) {
 		throw new require_diagnostics_diagnostics.MarkdownPackageFlattenError(error);
 	}

package/dist/write.d.cts

@@ -1,7 +1,7 @@
 import { WriteMarkdownOptions } from "./options/options.cjs";
-import { ContentDocument, DocumentPackage } from "document-schema.js";
+import { ContentDocument, DocumentTree } from "document-schema.js";
 //#region src/write.d.ts
-declare function writeMarkdown(documentPackage: DocumentPackage, options?: WriteMarkdownOptions): string;
+declare function writeMarkdown(documentPackage: DocumentTree, options?: WriteMarkdownOptions): string;
 declare function writeMarkdownContent(document: ContentDocument, options?: WriteMarkdownOptions): string;
 //#endregion
 export { writeMarkdown, writeMarkdownContent };

package/dist/write.d.ts

@@ -1,7 +1,7 @@
 import { WriteMarkdownOptions } from "./options/options.js";
-import { ContentDocument, DocumentPackage } from "document-schema.js";
+import { ContentDocument, DocumentTree } from "document-schema.js";
 //#region src/write.d.ts
-declare function writeMarkdown(documentPackage: DocumentPackage, options?: WriteMarkdownOptions): string;
+declare function writeMarkdown(documentPackage: DocumentTree, options?: WriteMarkdownOptions): string;
 declare function writeMarkdownContent(document: ContentDocument, options?: WriteMarkdownOptions): string;
 //#endregion
 export { writeMarkdown, writeMarkdownContent };

package/dist/write.js

@@ -2,7 +2,7 @@ import { MarkdownDiagnosticCodes, MarkdownPackageFlattenError, MarkdownUnsupport
 import { emitFrontMatter } from "./emit/front-matter.js";
 import { escapeLinkDestination, renderLinkTitle } from "./emit/inline.js";
 import { emitMarkdown } from "./emit/emit.js";
-import { flattenPackage } from "document-schema.js";
+import { flattenTree } from "document-schema.js";
 //#region src/write.ts
 function renderLinkDefinition(label, entry) {
 	const destination = entry.destination;
@@ -33,7 +33,7 @@ function reportDroppedPackageTables(documentPackage, definitionsRendered, sink)
 		sink({
 			code: MarkdownDiagnosticCodes.PACKAGE_TABLE_DROPPED,
 			severity: "info",
-			message: `the package's own "${name}" table has no markdown representation; flattenPackage's envelope carries forward only metadata and symbolTable, so "${name}" is dropped rather than rendered`
+			message: `the package's own "${name}" table has no markdown representation; flattenTree's envelope carries forward only metadata and symbolTable, so "${name}" is dropped rather than rendered`
 		});
 	}
 }
@@ -45,7 +45,7 @@ function writeMarkdown(documentPackage, options = {}) {
 	reportDroppedPackageTables(documentPackage, definitionsBlock !== void 0, sink);
 	let flattened;
 	try {
-		flattened = flattenPackage(documentPackage);
+		flattened = flattenTree(documentPackage);
 	} catch (error) {
 		throw new MarkdownPackageFlattenError(error);
 	}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "markdown-codec",
-  "version": "5.0.2",
-  "description": "Hand-written CommonMark+GFM <-> DocumentPackage codec, built on document-schema.js",
+  "version": "6.0.0",
+  "description": "Hand-written CommonMark+GFM <-> DocumentTree codec, built on document-schema.js",
   "type": "module",
   "repository": {
     "type": "git",
@@ -81,7 +81,7 @@
   "license": "MIT",
   "packageManager": "pnpm@11.6.0",
   "dependencies": {
-    "document-schema.js": "^4.9.1",
+    "document-schema.js": "^5.0.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {