document-content-model 3.0.0 → 3.2.0

package/README.md

@@ -48,7 +48,7 @@ graph TD
     style schema fill:#f9a825,stroke:#333,stroke-width:3px
 ```
 
-`ContentDocument` (the semantic pivot) is a discriminated union of five kinds: `wordprocessing` (docx/odt sections of paragraphs/runs/tables/images), `presentation` (pptx/odp slides of shapes), `spreadsheet` (xlsx/ods sheets of cells, columns, rows, print settings), `drawing` (odg pages of shapes plus vector primitives — rect/ellipse/line/path), and `formula` (an equation carrying its own MathML node tree plus StarMath source when the producing format had one). `ContentEmbeddedObjectSchema` lets any of the five embed another whole `ContentDocument`. Every paragraph/run/image/table/shape/vector/spreadsheet-cell leaf also carries its own canonical `headingLevel`-or-position fields directly: a `ContentParagraph`'s optional `headingLevel` (1 = the outermost heading, independent of the round-trip-only `styleId`), and every such leaf's optional `frames: LayoutFrame[]` — that node's own rendered page position(s) (`pageIndex` plus PDF user-space `xPt`/`yPt`/`widthPt`/`heightPt`), fused directly onto the content tree once a layout pass has run. `LayoutDocument` (the PDF-rendering pivot pdf-codec's `readPdf`/`writePdf` operate on directly, independent of any `ContentDocument`) is pages of positioned `LayoutItem`s (`text`/`image`/`rect`/`line`/`ellipse`/`path`/`link`) in PDF user-space coordinates. `DocumentPackageSchema` wraps `content` (required) with `pages` (optional, derived: each rendered page's own size, indexed to match every node's own `frames[].pageIndex`) — a single fused tree rather than a second, independent `LayoutDocument` correlated back to `content` only by matching `sourcePath` strings; the schema does not keep `content`'s populated `frames` fields and `pages` in sync or detect staleness.
+`ContentDocument` (the semantic pivot) is a discriminated union of five kinds: `wordprocessing` (docx/odt sections of paragraphs/runs/tables/images), `presentation` (pptx/odp slides of shapes), `spreadsheet` (xlsx/ods sheets of cells, columns, rows, print settings), `drawing` (odg pages of shapes plus vector primitives — rect/ellipse/line/path), and `formula` (an equation carrying its own MathML node tree plus StarMath source when the producing format had one, extended with the two-layer math model: an optional verbatim-LaTeX `presentation` authoritative for rendering, an optional semantic `content: MathExpression` tree authoritative for computation, and provenance — neither layer stored derived from the other, so editing one never silently mutates the other). `ContentEmbeddedObjectSchema` lets any of the five embed another whole `ContentDocument`. Every paragraph/run/image/table/shape/vector/spreadsheet-cell leaf also carries its own canonical `headingLevel`-or-position fields directly: a `ContentParagraph`'s optional `headingLevel` (1 = the outermost heading, independent of the round-trip-only `styleId`), and every such leaf's optional `frames: LayoutFrame[]` — that node's own rendered page position(s) (`pageIndex` plus PDF user-space `xPt`/`yPt`/`widthPt`/`heightPt`), fused directly onto the content tree once a layout pass has run. `LayoutDocument` (the PDF-rendering pivot pdf-codec's `readPdf`/`writePdf` operate on directly, independent of any `ContentDocument`) is pages of positioned `LayoutItem`s (`text`/`image`/`rect`/`line`/`ellipse`/`path`/`link`) in PDF user-space coordinates. `DocumentPackageSchema` wraps `content` (required) with `pages` (optional, derived: each rendered page's own size, indexed to match every node's own `frames[].pageIndex`) — a single fused tree rather than a second, independent `LayoutDocument` correlated back to `content` only by matching `sourcePath` strings; the schema does not keep `content`'s populated `frames` fields and `pages` in sync or detect staleness. Every one of the five kinds also accepts an optional document-level `symbolTable` — the math curation layer mapping each written symbol glyph (within a scope) to its id, quantity kind, preferred unit, and definition source, alongside the unit registry (SI dimension-exponent vectors, exact rational conversions, per-unit-system normalisation contexts) that the `qty` nodes of lowered formulas resolve against.
 
 The package contains only [Zod](https://zod.dev) schemas, their inferred types, trivial schema-attached helpers (hex-colour conversion, recursive structural type guards), and two small structural interfaces (`ContentCodec`/`LayoutCodec`, see [Codecs](#codecs)). No XML, ZIP, PDF, or binary handling; the sole dependency is `zod`.
 
@@ -114,11 +114,11 @@ node_modules/document-schema.js/schemas/content-document.schema.json
 node_modules/document-schema.js/schemas/layout-document.schema.json
 ```
 
-Each file's `$id` is a jsdelivr URL pinned to the exact npm version — immutable and live on publish. The three files cross-reference via `$ref`s, so a validator resolving refs over HTTP can validate a whole `DocumentPackage`. `content-document.schema.json` carries a hand-authored `$defs` block for the recursive paragraph/table/embedded-object and MathML node models (Zod's converter cannot express these directly); `content-json-schema-defs.ts` holds those fragments, and a regression test compares each against a live `z.toJSONSchema()` of its real Zod counterpart so a field changed without updating its fragment fails a test. Fragments downstream of a `z.custom()` node (`ContentBlock`, `ContentTable`/`Cell`/`Row`, `ContentEmbeddedObjectBlock`, `MathMlNode`/`Element`/`Attribute`) still need hand re-verification against `src/content.ts`/`src/mathml.ts` — see below.
+Each file's `$id` is a jsdelivr URL pinned to the exact npm version — immutable and live on publish. The three files cross-reference via `$ref`s, so a validator resolving refs over HTTP can validate a whole `DocumentPackage`. `content-document.schema.json` carries a hand-authored `$defs` block for the recursive paragraph/table/embedded-object and MathML node models (Zod's converter cannot express these directly); `content-json-schema-defs.ts` holds those fragments, and a regression test compares each against a live `z.toJSONSchema()` of its real Zod counterpart so a field changed without updating its fragment fails a test. Fragments downstream of a `z.custom()` node (`ContentBlock`, `ContentTable`/`Cell`/`Row`, `ContentEmbeddedObjectBlock`, `MathMlNode`/`Element`/`Attribute`, `ContentFormula`, `MathExpression` and its recursive variants) still need hand re-verification against `src/content.ts`/`src/mathml.ts`/`src/math.ts` — see below.
 
 ### `z.custom()` vs `z.lazy()` for recursive schemas
 
-`ContentBlockSchema`, `ContentEmbeddedObjectSchema`, and `MathMlNodeSchema` are `z.custom()` type-guard predicates rather than real Zod schemas, because `z.lazy()` was believed to collapse to `unknown` for recursive children. A throwaway spike (reverted) re-tested `MathMlNodeSchema` (the simplest case) against `zod@4.4.3`.
+`ContentBlockSchema`, `ContentEmbeddedObjectSchema`, `MathMlNodeSchema`, and `MathExpressionSchema` are `z.custom()` type-guard predicates rather than real Zod schemas, because `z.lazy()` was believed to collapse to `unknown` for recursive children. A throwaway spike (reverted) re-tested `MathMlNodeSchema` (the simplest case) against `zod@4.4.3`.
 
 **Finding: `z.lazy()` works now, with one constructional gotcha.** The naive rewrite —
 

package/dist/content-json-schema-defs.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_math = require("./math.cjs");
 const require_schema_io = require("./schema-io.cjs");
 //#region src/content-json-schema-defs.ts
 const MAX_SAFE_INTEGER = Number.MAX_SAFE_INTEGER;
@@ -10,6 +11,29 @@ const EMBEDDED_OBJECT_KINDS = [
 	"drawing"
 ];
 const CONTENT_DOCUMENT_URI = require_schema_io.schemaUriFor("ContentDocument");
+function mathBinderDef(kind) {
+	return {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: kind
+			},
+			binder: { type: "string" },
+			lower: { $ref: "#/$defs/MathExpression" },
+			upper: { $ref: "#/$defs/MathExpression" },
+			body: { $ref: "#/$defs/MathExpression" }
+		},
+		required: [
+			"kind",
+			"binder",
+			"lower",
+			"upper",
+			"body"
+		],
+		additionalProperties: false
+	};
+}
 const CONTENT_DEFS = {
 	Color: {
 		type: "object",
@@ -477,6 +501,270 @@ const CONTENT_DEFS = {
 			additionalProperties: false
 		},
 		{ $ref: "#/$defs/MathMlElement" }
+	] },
+	ContentFormula: {
+		type: "object",
+		properties: {
+			mathml: {
+				type: "array",
+				items: { $ref: "#/$defs/MathMlNode" }
+			},
+			starMath: { type: "string" },
+			presentation: { $ref: "#/$defs/MathPresentation" },
+			content: { $ref: "#/$defs/MathExpression" },
+			provenance: { $ref: "#/$defs/MathProvenance" }
+		},
+		required: ["mathml"],
+		additionalProperties: false
+	},
+	ExactRational: {
+		type: "object",
+		properties: {
+			numerator: {
+				type: "string",
+				pattern: "^(0|-?[1-9]\\d*)$"
+			},
+			denominator: {
+				type: "string",
+				pattern: "^[1-9]\\d*$"
+			}
+		},
+		required: ["numerator", "denominator"],
+		additionalProperties: false
+	},
+	DimensionVector: {
+		type: "object",
+		propertyNames: {
+			type: "string",
+			enum: [...require_math.SI_BASE_DIMENSIONS]
+		},
+		additionalProperties: {
+			type: "integer",
+			minimum: -MAX_SAFE_INTEGER,
+			maximum: MAX_SAFE_INTEGER
+		}
+	},
+	MathPresentation: {
+		type: "object",
+		properties: { latex: { type: "string" } },
+		required: ["latex"],
+		additionalProperties: false
+	},
+	MathProvenance: {
+		type: "object",
+		properties: {
+			source: { type: "string" },
+			pageRef: { type: "string" },
+			editTrail: {
+				type: "array",
+				items: { type: "string" }
+			}
+		},
+		required: ["source", "editTrail"],
+		additionalProperties: false
+	},
+	MathUncertainty: {
+		type: "object",
+		properties: {
+			magnitude: { $ref: "#/$defs/ExactRational" },
+			unit: { type: "string" },
+			coverageFactor: {
+				type: "number",
+				exclusiveMinimum: 0
+			}
+		},
+		required: ["magnitude"],
+		additionalProperties: false
+	},
+	MathSymbolEntry: {
+		type: "object",
+		properties: {
+			glyph: { type: "string" },
+			scope: { type: "string" },
+			id: { type: "string" },
+			quantityKind: { type: "string" },
+			preferredUnit: { type: "string" },
+			definitionSource: { type: "string" }
+		},
+		required: [
+			"glyph",
+			"scope",
+			"id"
+		],
+		additionalProperties: false
+	},
+	MathUnit: {
+		type: "object",
+		properties: {
+			id: { type: "string" },
+			symbol: { type: "string" },
+			name: { type: "string" },
+			dimension: { $ref: "#/$defs/DimensionVector" },
+			factorToSi: { $ref: "#/$defs/ExactRational" },
+			offsetToSi: { $ref: "#/$defs/ExactRational" },
+			context: { type: "string" }
+		},
+		required: [
+			"id",
+			"symbol",
+			"dimension",
+			"factorToSi"
+		],
+		additionalProperties: false
+	},
+	MathNormalisationContext: {
+		type: "object",
+		properties: {
+			id: { type: "string" },
+			bases: {
+				type: "array",
+				items: {
+					type: "object",
+					properties: {
+						unit: { type: "string" },
+						value: { $ref: "#/$defs/ExactRational" }
+					},
+					required: ["unit", "value"],
+					additionalProperties: false
+				}
+			}
+		},
+		required: ["id", "bases"],
+		additionalProperties: false
+	},
+	SymbolTable: {
+		type: "object",
+		properties: {
+			symbols: {
+				type: "array",
+				items: { $ref: "#/$defs/MathSymbolEntry" }
+			},
+			units: {
+				type: "array",
+				items: { $ref: "#/$defs/MathUnit" }
+			},
+			contexts: {
+				type: "array",
+				items: { $ref: "#/$defs/MathNormalisationContext" }
+			}
+		},
+		required: ["symbols", "units"],
+		additionalProperties: false
+	},
+	MathNum: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "num"
+			},
+			numerator: {
+				type: "string",
+				pattern: "^(0|-?[1-9]\\d*)$"
+			},
+			denominator: {
+				type: "string",
+				pattern: "^[1-9]\\d*$"
+			}
+		},
+		required: [
+			"kind",
+			"numerator",
+			"denominator"
+		],
+		additionalProperties: false
+	},
+	MathQty: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "qty"
+			},
+			value: { $ref: "#/$defs/ExactRational" },
+			unit: { type: "string" },
+			uncertainty: { $ref: "#/$defs/MathUncertainty" }
+		},
+		required: [
+			"kind",
+			"value",
+			"unit"
+		],
+		additionalProperties: false
+	},
+	MathSym: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "sym"
+			},
+			id: { type: "string" }
+		},
+		required: ["kind", "id"],
+		additionalProperties: false
+	},
+	MathApp: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "app"
+			},
+			operator: { type: "string" },
+			args: {
+				type: "array",
+				items: { $ref: "#/$defs/MathExpression" }
+			}
+		},
+		required: [
+			"kind",
+			"operator",
+			"args"
+		],
+		additionalProperties: false
+	},
+	MathSum: mathBinderDef("sum"),
+	MathProd: mathBinderDef("prod"),
+	MathMatrix: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "matrix"
+			},
+			rows: {
+				type: "array",
+				items: {
+					type: "array",
+					items: { $ref: "#/$defs/MathExpression" }
+				}
+			}
+		},
+		required: ["kind", "rows"],
+		additionalProperties: false
+	},
+	MathUnparsed: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "unparsed"
+			},
+			latex: { type: "string" }
+		},
+		required: ["kind", "latex"],
+		additionalProperties: false
+	},
+	MathExpression: { oneOf: [
+		{ $ref: "#/$defs/MathNum" },
+		{ $ref: "#/$defs/MathQty" },
+		{ $ref: "#/$defs/MathSym" },
+		{ $ref: "#/$defs/MathApp" },
+		{ $ref: "#/$defs/MathSum" },
+		{ $ref: "#/$defs/MathProd" },
+		{ $ref: "#/$defs/MathMatrix" },
+		{ $ref: "#/$defs/MathUnparsed" }
 	] }
 };
 //#endregion

package/dist/content-json-schema-defs.js

@@ -1,3 +1,4 @@
+import { SI_BASE_DIMENSIONS } from "./math.js";
 import { schemaUriFor } from "./schema-io.js";
 //#region src/content-json-schema-defs.ts
 const MAX_SAFE_INTEGER = Number.MAX_SAFE_INTEGER;
@@ -9,6 +10,29 @@ const EMBEDDED_OBJECT_KINDS = [
 	"drawing"
 ];
 const CONTENT_DOCUMENT_URI = schemaUriFor("ContentDocument");
+function mathBinderDef(kind) {
+	return {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: kind
+			},
+			binder: { type: "string" },
+			lower: { $ref: "#/$defs/MathExpression" },
+			upper: { $ref: "#/$defs/MathExpression" },
+			body: { $ref: "#/$defs/MathExpression" }
+		},
+		required: [
+			"kind",
+			"binder",
+			"lower",
+			"upper",
+			"body"
+		],
+		additionalProperties: false
+	};
+}
 const CONTENT_DEFS = {
 	Color: {
 		type: "object",
@@ -476,6 +500,270 @@ const CONTENT_DEFS = {
 			additionalProperties: false
 		},
 		{ $ref: "#/$defs/MathMlElement" }
+	] },
+	ContentFormula: {
+		type: "object",
+		properties: {
+			mathml: {
+				type: "array",
+				items: { $ref: "#/$defs/MathMlNode" }
+			},
+			starMath: { type: "string" },
+			presentation: { $ref: "#/$defs/MathPresentation" },
+			content: { $ref: "#/$defs/MathExpression" },
+			provenance: { $ref: "#/$defs/MathProvenance" }
+		},
+		required: ["mathml"],
+		additionalProperties: false
+	},
+	ExactRational: {
+		type: "object",
+		properties: {
+			numerator: {
+				type: "string",
+				pattern: "^(0|-?[1-9]\\d*)$"
+			},
+			denominator: {
+				type: "string",
+				pattern: "^[1-9]\\d*$"
+			}
+		},
+		required: ["numerator", "denominator"],
+		additionalProperties: false
+	},
+	DimensionVector: {
+		type: "object",
+		propertyNames: {
+			type: "string",
+			enum: [...SI_BASE_DIMENSIONS]
+		},
+		additionalProperties: {
+			type: "integer",
+			minimum: -MAX_SAFE_INTEGER,
+			maximum: MAX_SAFE_INTEGER
+		}
+	},
+	MathPresentation: {
+		type: "object",
+		properties: { latex: { type: "string" } },
+		required: ["latex"],
+		additionalProperties: false
+	},
+	MathProvenance: {
+		type: "object",
+		properties: {
+			source: { type: "string" },
+			pageRef: { type: "string" },
+			editTrail: {
+				type: "array",
+				items: { type: "string" }
+			}
+		},
+		required: ["source", "editTrail"],
+		additionalProperties: false
+	},
+	MathUncertainty: {
+		type: "object",
+		properties: {
+			magnitude: { $ref: "#/$defs/ExactRational" },
+			unit: { type: "string" },
+			coverageFactor: {
+				type: "number",
+				exclusiveMinimum: 0
+			}
+		},
+		required: ["magnitude"],
+		additionalProperties: false
+	},
+	MathSymbolEntry: {
+		type: "object",
+		properties: {
+			glyph: { type: "string" },
+			scope: { type: "string" },
+			id: { type: "string" },
+			quantityKind: { type: "string" },
+			preferredUnit: { type: "string" },
+			definitionSource: { type: "string" }
+		},
+		required: [
+			"glyph",
+			"scope",
+			"id"
+		],
+		additionalProperties: false
+	},
+	MathUnit: {
+		type: "object",
+		properties: {
+			id: { type: "string" },
+			symbol: { type: "string" },
+			name: { type: "string" },
+			dimension: { $ref: "#/$defs/DimensionVector" },
+			factorToSi: { $ref: "#/$defs/ExactRational" },
+			offsetToSi: { $ref: "#/$defs/ExactRational" },
+			context: { type: "string" }
+		},
+		required: [
+			"id",
+			"symbol",
+			"dimension",
+			"factorToSi"
+		],
+		additionalProperties: false
+	},
+	MathNormalisationContext: {
+		type: "object",
+		properties: {
+			id: { type: "string" },
+			bases: {
+				type: "array",
+				items: {
+					type: "object",
+					properties: {
+						unit: { type: "string" },
+						value: { $ref: "#/$defs/ExactRational" }
+					},
+					required: ["unit", "value"],
+					additionalProperties: false
+				}
+			}
+		},
+		required: ["id", "bases"],
+		additionalProperties: false
+	},
+	SymbolTable: {
+		type: "object",
+		properties: {
+			symbols: {
+				type: "array",
+				items: { $ref: "#/$defs/MathSymbolEntry" }
+			},
+			units: {
+				type: "array",
+				items: { $ref: "#/$defs/MathUnit" }
+			},
+			contexts: {
+				type: "array",
+				items: { $ref: "#/$defs/MathNormalisationContext" }
+			}
+		},
+		required: ["symbols", "units"],
+		additionalProperties: false
+	},
+	MathNum: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "num"
+			},
+			numerator: {
+				type: "string",
+				pattern: "^(0|-?[1-9]\\d*)$"
+			},
+			denominator: {
+				type: "string",
+				pattern: "^[1-9]\\d*$"
+			}
+		},
+		required: [
+			"kind",
+			"numerator",
+			"denominator"
+		],
+		additionalProperties: false
+	},
+	MathQty: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "qty"
+			},
+			value: { $ref: "#/$defs/ExactRational" },
+			unit: { type: "string" },
+			uncertainty: { $ref: "#/$defs/MathUncertainty" }
+		},
+		required: [
+			"kind",
+			"value",
+			"unit"
+		],
+		additionalProperties: false
+	},
+	MathSym: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "sym"
+			},
+			id: { type: "string" }
+		},
+		required: ["kind", "id"],
+		additionalProperties: false
+	},
+	MathApp: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "app"
+			},
+			operator: { type: "string" },
+			args: {
+				type: "array",
+				items: { $ref: "#/$defs/MathExpression" }
+			}
+		},
+		required: [
+			"kind",
+			"operator",
+			"args"
+		],
+		additionalProperties: false
+	},
+	MathSum: mathBinderDef("sum"),
+	MathProd: mathBinderDef("prod"),
+	MathMatrix: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "matrix"
+			},
+			rows: {
+				type: "array",
+				items: {
+					type: "array",
+					items: { $ref: "#/$defs/MathExpression" }
+				}
+			}
+		},
+		required: ["kind", "rows"],
+		additionalProperties: false
+	},
+	MathUnparsed: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "unparsed"
+			},
+			latex: { type: "string" }
+		},
+		required: ["kind", "latex"],
+		additionalProperties: false
+	},
+	MathExpression: { oneOf: [
+		{ $ref: "#/$defs/MathNum" },
+		{ $ref: "#/$defs/MathQty" },
+		{ $ref: "#/$defs/MathSym" },
+		{ $ref: "#/$defs/MathApp" },
+		{ $ref: "#/$defs/MathSum" },
+		{ $ref: "#/$defs/MathProd" },
+		{ $ref: "#/$defs/MathMatrix" },
+		{ $ref: "#/$defs/MathUnparsed" }
 	] }
 };
 //#endregion