smartrte-core 0.2.0 → 1.0.0-beta.1

package/dist/foundation/formats/docx/styledImport.js

@@ -0,0 +1,205 @@
+import JSZip from "jszip";
+import { DOMParser } from "@xmldom/xmldom";
+import { parseFragment, serialize } from "parse5";
+import { parseCanonicalListHtml, serializeCanonicalListHtml } from "../../list/formats.js";
+import { importDocxDocumentWithMammoth } from "./import.js";
+import { restorePortableDocxAtoms } from "./portableAtoms.js";
+const ELEMENT_NODE = 1;
+const isElement = (node) => node.nodeType === ELEMENT_NODE;
+const directChildren = (node) => Array.from(node.childNodes || []).filter(isElement);
+const firstChildByName = (node, localName) => node ? directChildren(node).find((child) => child.localName === localName) : undefined;
+const childrenByName = (node, localName) => node ? directChildren(node).filter((child) => child.localName === localName) : [];
+const docxAttr = (node, name) => {
+    if (!node)
+        return "";
+    return node.getAttribute(`w:${name}`)
+        || node.getAttribute(name)
+        || node.getAttributeNS("http://schemas.openxmlformats.org/wordprocessingml/2006/main", name)
+        || "";
+};
+const escapeHtml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+const docxHexColor = (value) => {
+    if (!value || value.toLowerCase() === "auto")
+        return "";
+    const normalized = value.replace(/[^0-9a-f]/gi, "");
+    return normalized.length === 6 ? `#${normalized}` : "";
+};
+const twipsToPt = (value) => {
+    if (!value)
+        return "";
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? `${Math.max(numeric / 20, 0)}pt` : "";
+};
+const halfPointsToPt = (value) => {
+    if (!value)
+        return "";
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? `${Math.max(numeric / 2, 1)}pt` : "";
+};
+const cssRules = (rules) => rules.filter(([, value]) => Boolean(value)).map(([name, value]) => `${name}: ${value}`).join("; ");
+const styleAttr = (style) => style ? ` style="${escapeHtml(style)}"` : "";
+const borderCss = (border) => {
+    if (!border)
+        return "";
+    const value = docxAttr(border, "val");
+    if (!value || value === "nil" || value === "none")
+        return "";
+    const size = Number(docxAttr(border, "sz")) || 4;
+    const color = docxHexColor(docxAttr(border, "color")) || "#d1d5db";
+    return `${Math.max(size / 8, 0.5)}px solid ${color}`;
+};
+const paragraphStyle = (paragraph) => {
+    const properties = firstChildByName(paragraph, "pPr");
+    if (!properties)
+        return "";
+    const spacing = firstChildByName(properties, "spacing");
+    const justification = firstChildByName(properties, "jc");
+    const indent = firstChildByName(properties, "ind");
+    const bottomBorder = firstChildByName(firstChildByName(properties, "pBdr"), "bottom");
+    const line = docxAttr(spacing, "line");
+    return cssRules([
+        ["text-align", docxAttr(justification, "val")],
+        ["margin-top", twipsToPt(docxAttr(spacing, "before"))],
+        ["margin-bottom", twipsToPt(docxAttr(spacing, "after"))],
+        ["margin-left", twipsToPt(docxAttr(indent, "left"))],
+        ["text-indent", twipsToPt(docxAttr(indent, "firstLine"))],
+        ["line-height", line && docxAttr(spacing, "lineRule") === "auto" ? `${Number(line) / 240}` : ""],
+        ["border-bottom", borderCss(bottomBorder)],
+    ]);
+};
+const runStyle = (run) => {
+    const properties = firstChildByName(run, "rPr");
+    if (!properties)
+        return "";
+    const color = docxHexColor(docxAttr(firstChildByName(properties, "color"), "val"));
+    const highlight = docxHexColor(docxAttr(firstChildByName(properties, "highlight"), "val"));
+    const shade = docxHexColor(docxAttr(firstChildByName(properties, "shd"), "fill"));
+    return cssRules([
+        ["font-weight", firstChildByName(properties, "b") ? "700" : ""],
+        ["font-style", firstChildByName(properties, "i") ? "italic" : ""],
+        ["text-decoration", firstChildByName(properties, "u") ? "underline" : ""],
+        ["color", color],
+        ["background-color", highlight || shade],
+        ["font-size", halfPointsToPt(docxAttr(firstChildByName(properties, "sz"), "val"))],
+    ]);
+};
+const runHtml = (run) => {
+    const properties = firstChildByName(run, "rPr");
+    const verticalAlignment = docxAttr(firstChildByName(properties, "vertAlign"), "val");
+    const content = directChildren(run).map((child) => {
+        if (child.localName === "t")
+            return escapeHtml(child.textContent || "");
+        if (child.localName === "tab")
+            return "&emsp;";
+        if (child.localName === "br")
+            return docxAttr(child, "type") === "page" ? '<hr class="srte-docx-page-break">' : "<br>";
+        return "";
+    }).join("");
+    if (!content)
+        return "";
+    const tag = verticalAlignment === "superscript" ? "sup" : verticalAlignment === "subscript" ? "sub" : "span";
+    return `<${tag}${styleAttr(runStyle(run))}>${content}</${tag}>`;
+};
+const paragraphHtml = (paragraph) => {
+    const content = childrenByName(paragraph, "r").map(runHtml).join("");
+    return `<p${styleAttr(paragraphStyle(paragraph))}>${content || "<br>"}</p>`;
+};
+const cellStyle = (cell) => {
+    const properties = firstChildByName(cell, "tcPr");
+    const borders = firstChildByName(properties, "tcBorders");
+    return cssRules([
+        ["width", twipsToPt(docxAttr(firstChildByName(properties, "tcW"), "w"))],
+        ["background-color", docxHexColor(docxAttr(firstChildByName(properties, "shd"), "fill"))],
+        ["border-top", borderCss(firstChildByName(borders, "top"))],
+        ["border-right", borderCss(firstChildByName(borders, "right"))],
+        ["border-bottom", borderCss(firstChildByName(borders, "bottom"))],
+        ["border-left", borderCss(firstChildByName(borders, "left"))],
+        ["padding", "8px"],
+        ["vertical-align", "top"],
+    ]);
+};
+const tableHtml = (table) => {
+    const rows = childrenByName(table, "tr").map((row) => {
+        const cells = childrenByName(row, "tc").map((cell) => {
+            const content = directChildren(cell)
+                .filter((child) => child.localName === "p" || child.localName === "tbl")
+                .map((child) => child.localName === "p" ? paragraphHtml(child) : tableHtml(child))
+                .join("");
+            return `<td${styleAttr(cellStyle(cell))}>${content || "<p><br></p>"}</td>`;
+        }).join("");
+        return `<tr>${cells}</tr>`;
+    }).join("");
+    return `<table style="border-collapse: collapse; width: 100%; margin: 12px 0;"><tbody>${rows}</tbody></table>`;
+};
+const styleDeclarations = (attrs) => Object.fromEntries((attrs.find((attr) => attr.name === "style")?.value || "").split(";")
+    .map((rule) => rule.split(":").map((part) => part.trim()))
+    .filter(([property]) => property));
+/** Defensive baseline styling for any table missing explicit inline styles (e.g. the mammoth fallback path, which produces plain semantic HTML with no inline CSS at all). */
+export const enhanceDocxTables = (html) => {
+    const visit = (node) => {
+        if (!node.childNodes)
+            return node;
+        const childNodes = node.childNodes.map((child) => {
+            if (child.tagName !== "table" && child.tagName !== "td" && child.tagName !== "th")
+                return visit(child);
+            const attrs = [...(child.attrs || [])];
+            const styleIndex = attrs.findIndex((attr) => attr.name === "style");
+            const declarations = styleDeclarations(attrs);
+            if (child.tagName === "table") {
+                declarations["border-collapse"] || (declarations["border-collapse"] = "collapse");
+                declarations.width || (declarations.width = "100%");
+            }
+            else {
+                const hasBorder = ["border", "border-top", "border-right", "border-bottom", "border-left"].some((key) => declarations[key]);
+                if (!hasBorder)
+                    declarations.border = "1px solid #d1d5db";
+                declarations.padding || (declarations.padding = "8px");
+                declarations["vertical-align"] || (declarations["vertical-align"] = "top");
+            }
+            const style = Object.entries(declarations).map(([property, value]) => `${property}: ${value}`).join("; ");
+            const next = { name: "style", value: style };
+            if (styleIndex >= 0)
+                attrs[styleIndex] = next;
+            else
+                attrs.push(next);
+            return { ...visit(child), attrs };
+        });
+        return { ...node, childNodes };
+    };
+    const fragment = visit(parseFragment(html));
+    return serialize(fragment);
+};
+const mammothFallback = async (arrayBuffer) => {
+    const document = await importDocxDocumentWithMammoth(arrayBuffer);
+    const layoutHtml = enhanceDocxTables(serializeCanonicalListHtml(document, { clean: true }));
+    return { document, layoutHtml, source: "mammoth" };
+};
+/** Fidelity: `semantic` for structure, richer visual reproduction than plain mammoth import via inline CSS reconstructed from raw wordprocessingml formatting XML, with graceful fallback to mammoth if that XML is missing or malformed. */
+export const importStyledDocxDocument = async (arrayBuffer) => {
+    try {
+        const zip = await JSZip.loadAsync(arrayBuffer);
+        const documentXml = await zip.file("word/document.xml")?.async("text");
+        if (!documentXml)
+            return mammothFallback(arrayBuffer);
+        const parsed = new DOMParser().parseFromString(documentXml, "text/xml");
+        if (!parsed || parsed.getElementsByTagName("parsererror").length)
+            return mammothFallback(arrayBuffer);
+        const body = Array.from(parsed.getElementsByTagName("*")).find((node) => node.localName === "body");
+        if (!body)
+            return mammothFallback(arrayBuffer);
+        const rawHtml = directChildren(body).filter((node) => node.localName !== "sectPr").map((node) => {
+            if (node.localName === "p")
+                return paragraphHtml(node);
+            if (node.localName === "tbl")
+                return tableHtml(node);
+            return "";
+        }).join("");
+        if (!rawHtml.trim())
+            return mammothFallback(arrayBuffer);
+        const layoutHtml = enhanceDocxTables(restorePortableDocxAtoms(rawHtml));
+        return { document: parseCanonicalListHtml(layoutHtml), layoutHtml, source: "wordprocessingml" };
+    }
+    catch {
+        return mammothFallback(arrayBuffer);
+    }
+};

package/dist/foundation/formats/featureCodecs.d.ts

@@ -0,0 +1,37 @@
+import type { FeatureFormatCodec } from "./codec.js";
+import { type FidelityFeature } from "./fidelity.js";
+/**
+ * The 44 (feature x format) FeatureFormatCodec declarations Phase 9 SS3
+ * gate 3 requires. feature/format/fidelity/note are mechanically derived
+ * from builtInFormatFidelity (fidelity.ts) - that table is the single
+ * source of truth for fidelity claims; this file must never restate a
+ * level or note independently of it.
+ *
+ * parse/serialize are only attached where a genuine single-node function
+ * already exists, never a fabricated per-node wrapper around whole-document
+ * logic:
+ * - atom/formats.ts's atomTo{Html,Markdown,Docx,Pdf} and atomFromHtmlElement
+ *   operate on one SmartElementNode at a time, so images-media and formulas
+ *   get real wiring for all four formats (Phase 9).
+ * - marks/formats.ts's docxProperties and block/formats.ts's blockToDocxEntry
+ *   (Phase 11 Tier 2, per docs/PHASE_9_CODEC_REFACTOR_SCOPE.md's recommended
+ *   marks-then-blocks order) were already genuinely single-node - or, for
+ *   blocks, extracted from canonicalBlocksToDocx's per-node visit() body
+ *   with canonicalBlocksToDocx refactored to call the extracted function
+ *   rather than duplicate it - so inline-marks/colors-fonts-sizes (marks)
+ *   and headings-alignment/blockquote-code (block) get real DOCX wiring
+ *   here. No parse direction exists for either (no reverse
+ *   properties-to-marks/DocxBlock-to-node mapping was ever built), so only
+ *   `serialize` is attached, matching the general "wire what already exists"
+ *   rule.
+ *
+ * HTML/Markdown/PDF for marks and blocks, and every format for lists/tables,
+ * remain whole-document walkers (docx/export.ts, pdf/format.ts,
+ * list/formats.ts's HTML/Markdown serializers, table's own
+ * canonical*To{Docx,Pdf} functions) that resolve every feature together in
+ * one pass (see codec.ts's own doc comment) - per the scope doc, HTML/
+ * Markdown is deliberately not scheduled ("if at all"), so those cells still
+ * carry fidelity metadata only. Closing the rest is tracked in
+ * docs/PHASE_9_EXIT_GATES.md's gate 3 entry.
+ */
+export declare const builtInFeatureFormatCodecs: readonly FeatureFormatCodec<FidelityFeature>[];

package/dist/foundation/formats/featureCodecs.js

@@ -0,0 +1,69 @@
+import { atomFromHtmlElement, atomToDocx, atomToHtml, atomToMarkdown, atomToPdf } from "../atom/formats.js";
+import { markRunDocxProperties } from "../marks/formats.js";
+import { blockToDocxEntry } from "../block/formats.js";
+import { builtInFormatFidelity } from "./fidelity.js";
+const asAtom = (node) => node;
+/**
+ * The 44 (feature x format) FeatureFormatCodec declarations Phase 9 SS3
+ * gate 3 requires. feature/format/fidelity/note are mechanically derived
+ * from builtInFormatFidelity (fidelity.ts) - that table is the single
+ * source of truth for fidelity claims; this file must never restate a
+ * level or note independently of it.
+ *
+ * parse/serialize are only attached where a genuine single-node function
+ * already exists, never a fabricated per-node wrapper around whole-document
+ * logic:
+ * - atom/formats.ts's atomTo{Html,Markdown,Docx,Pdf} and atomFromHtmlElement
+ *   operate on one SmartElementNode at a time, so images-media and formulas
+ *   get real wiring for all four formats (Phase 9).
+ * - marks/formats.ts's docxProperties and block/formats.ts's blockToDocxEntry
+ *   (Phase 11 Tier 2, per docs/PHASE_9_CODEC_REFACTOR_SCOPE.md's recommended
+ *   marks-then-blocks order) were already genuinely single-node - or, for
+ *   blocks, extracted from canonicalBlocksToDocx's per-node visit() body
+ *   with canonicalBlocksToDocx refactored to call the extracted function
+ *   rather than duplicate it - so inline-marks/colors-fonts-sizes (marks)
+ *   and headings-alignment/blockquote-code (block) get real DOCX wiring
+ *   here. No parse direction exists for either (no reverse
+ *   properties-to-marks/DocxBlock-to-node mapping was ever built), so only
+ *   `serialize` is attached, matching the general "wire what already exists"
+ *   rule.
+ *
+ * HTML/Markdown/PDF for marks and blocks, and every format for lists/tables,
+ * remain whole-document walkers (docx/export.ts, pdf/format.ts,
+ * list/formats.ts's HTML/Markdown serializers, table's own
+ * canonical*To{Docx,Pdf} functions) that resolve every feature together in
+ * one pass (see codec.ts's own doc comment) - per the scope doc, HTML/
+ * Markdown is deliberately not scheduled ("if at all"), so those cells still
+ * carry fidelity metadata only. Closing the rest is tracked in
+ * docs/PHASE_9_EXIT_GATES.md's gate 3 entry.
+ */
+export const builtInFeatureFormatCodecs = builtInFormatFidelity.flatMap((contract) => ["html", "markdown", "docx", "pdf"].map((format) => {
+    const capability = contract.formats[format];
+    const base = {
+        feature: contract.feature,
+        format,
+        fidelity: capability.level,
+        note: capability.note,
+    };
+    if (contract.feature === "images-media" || contract.feature === "formulas") {
+        if (format === "html") {
+            return {
+                ...base,
+                serialize: (node) => atomToHtml(asAtom(node)),
+                parse: (input) => atomFromHtmlElement(input),
+            };
+        }
+        if (format === "markdown")
+            return { ...base, serialize: (node) => atomToMarkdown(asAtom(node)) };
+        if (format === "docx")
+            return { ...base, serialize: (node) => atomToDocx(asAtom(node)) };
+        return { ...base, serialize: (node) => atomToPdf(asAtom(node)) };
+    }
+    if (format === "docx" && (contract.feature === "inline-marks" || contract.feature === "colors-fonts-sizes")) {
+        return { ...base, serialize: (node) => markRunDocxProperties(node) };
+    }
+    if (format === "docx" && (contract.feature === "headings-alignment" || contract.feature === "blockquote-code")) {
+        return { ...base, serialize: (node) => blockToDocxEntry(asAtom(node)) };
+    }
+    return base;
+}));

package/dist/foundation/formats/fidelity.d.ts

@@ -0,0 +1,31 @@
+import type { FormatFidelityLevel, FormatId } from "./codec.js";
+export type FidelityFormat = FormatId;
+export type FidelityLevel = FormatFidelityLevel;
+export type FidelityFeature = "inline-marks" | "colors-fonts-sizes" | "headings-alignment" | "blockquote-code" | "lists" | "checklists" | "tables" | "links" | "images-media" | "formulas" | "special-characters";
+export interface FormatFidelityCapability {
+    level: FidelityLevel;
+    note: string;
+}
+export interface FeatureFidelityContract {
+    feature: FidelityFeature;
+    formats: Record<FidelityFormat, FormatFidelityCapability>;
+}
+/**
+ * Public, test-enforced compatibility contract for built-in document
+ * formats (Phase 9 SS2.2's fidelity table deliverable).
+ *
+ * Verification status as of Phase 9 SS3 gate 4 (2026-08-13): every one of
+ * the 44 (feature, format) cells below now has a passing round-trip fixture.
+ * DOCX cells: packages/core/src/foundation/formats/docx/format.test.ts.
+ * PDF cells: packages/core/src/foundation/formats/pdf/format.test.ts,
+ * atom/formats.test.ts, marks/formats.test.ts, block/formats.test.ts,
+ * list/formats.test.ts. HTML/Markdown cells: list/formats.test.ts,
+ * marks/formats.test.ts, block/formats.test.ts, table/formats.test.ts,
+ * atom/formats.test.ts. special-characters had zero coverage across all
+ * four formats until SS3's gate 4 audit found the gap; see the "Unicode
+ * special characters" tests added to each of those files. See also
+ * featureCodecs.ts, which declares the actual FeatureFormatCodec per cell
+ * gate 3 requires.
+ */
+export declare const builtInFormatFidelity: readonly FeatureFidelityContract[];
+export declare const getFormatFidelity: (feature: FidelityFeature, format: FidelityFormat) => FormatFidelityCapability;

package/dist/foundation/formats/fidelity.js

@@ -0,0 +1,123 @@
+const capability = (level, note) => ({
+    level,
+    note,
+});
+/**
+ * Public, test-enforced compatibility contract for built-in document
+ * formats (Phase 9 SS2.2's fidelity table deliverable).
+ *
+ * Verification status as of Phase 9 SS3 gate 4 (2026-08-13): every one of
+ * the 44 (feature, format) cells below now has a passing round-trip fixture.
+ * DOCX cells: packages/core/src/foundation/formats/docx/format.test.ts.
+ * PDF cells: packages/core/src/foundation/formats/pdf/format.test.ts,
+ * atom/formats.test.ts, marks/formats.test.ts, block/formats.test.ts,
+ * list/formats.test.ts. HTML/Markdown cells: list/formats.test.ts,
+ * marks/formats.test.ts, block/formats.test.ts, table/formats.test.ts,
+ * atom/formats.test.ts. special-characters had zero coverage across all
+ * four formats until SS3's gate 4 audit found the gap; see the "Unicode
+ * special characters" tests added to each of those files. See also
+ * featureCodecs.ts, which declares the actual FeatureFormatCodec per cell
+ * gate 3 requires.
+ */
+export const builtInFormatFidelity = [
+    {
+        feature: "inline-marks",
+        formats: {
+            html: capability("full", "Canonical marks round-trip."),
+            markdown: capability("semantic", "Bold, italic, strike, code, and links round-trip; underline is lossy."),
+            docx: capability("semantic", "All twelve marks are written as Word run properties on export. On import, mammoth's default HTML conversion recognizes and round-trips bold/italic/code/strike/superscript/subscript/link; underline/textColor/backgroundColor/fontSize/fontFamily are not mapped back without an explicit mammoth style map - text content survives, that specific formatting does not (SS2.1: verified per-mark via a dedicated round-trip fixture, not inferred)."),
+            pdf: capability("lossy", "Visual emphasis is inferred from extracted font metadata."),
+        },
+    },
+    {
+        feature: "colors-fonts-sizes",
+        formats: {
+            html: capability("full", "Inline style marks round-trip."),
+            markdown: capability("unsupported", "Portable Markdown has no standard representation."),
+            docx: capability("semantic", "Colors and sizes are supported; font-family fidelity depends on importer styles."),
+            pdf: capability("lossy", "Font size/style are inferred; colors are extraction-dependent."),
+        },
+    },
+    {
+        feature: "headings-alignment",
+        formats: {
+            html: capability("full", "Levels, alignment, and indentation round-trip."),
+            markdown: capability("lossy", "Heading levels round-trip; alignment and indentation do not."),
+            docx: capability("semantic", "Heading styles (w:pStyle), alignment (w:jc), and indentation (w:ind) are emitted (SS2.1, re-verified)."),
+            pdf: capability("lossy", "Levels and alignment are inferred geometrically."),
+        },
+    },
+    {
+        feature: "blockquote-code",
+        formats: {
+            html: capability("full", "Canonical block structure round-trips."),
+            markdown: capability("semantic", "Portable blockquote and code syntax round-trip."),
+            docx: capability("lossy", "Blockquote is represented as indentation (w:ind), not a native Word quote style; code uses a character-level code mark, not a code paragraph style."),
+            pdf: capability("lossy", "Export is visual and import reconstruction is heuristic."),
+        },
+    },
+    {
+        feature: "lists",
+        formats: {
+            html: capability("full", "Nested list structure and styles round-trip."),
+            markdown: capability("semantic", "Nested ordered and unordered structure round-trips; custom markers are lossy."),
+            docx: capability("semantic", "Nested lists export with native Word numbering definitions (w:numId/w:ilvl) and level metadata; verified for decimal/lower-alpha/disc through 9 levels (SS2.1, re-verified)."),
+            pdf: capability("lossy", "List structure is inferred from extracted markers."),
+        },
+    },
+    {
+        feature: "checklists",
+        formats: {
+            html: capability("full", "Checked state uses canonical data attributes."),
+            markdown: capability("semantic", "GFM task-list state round-trips."),
+            docx: capability("lossy", "Checklist semantics degrade to plain bulleted/numbered list content - checked state is not emitted (SS2.1, re-verified: docx/export.ts's list branch does not read list.attrs.checkable or list_item.attrs.checked)."),
+            pdf: capability("lossy", "Checklist semantics are visual only."),
+        },
+    },
+    {
+        feature: "tables",
+        formats: {
+            html: capability("full", "Spans, headers, colors, borders, and dimensions round-trip."),
+            markdown: capability("lossy", "GFM tables preserve text but not spans, dimensions, colors, or borders."),
+            docx: capability("semantic", "Column spans (gridSpan), row spans (vMerge), header rows, cell background, and borders export via occupancyGridFor (SS2.1, re-verified); per-cell vertical alignment is not yet emitted."),
+            pdf: capability("lossy", "Export is visual and import uses column-position heuristics."),
+        },
+    },
+    {
+        feature: "links",
+        formats: {
+            html: capability("full", "Safe href and target semantics round-trip."),
+            markdown: capability("semantic", "Href and label round-trip; target metadata is lossy."),
+            docx: capability("semantic", "Links export as native external Word hyperlink relationships (w:hyperlink); target=_blank is preserved as w:history (SS2.1, re-verified)."),
+            pdf: capability("lossy", "Links are visual text in the current print/export path."),
+        },
+    },
+    {
+        feature: "images-media",
+        formats: {
+            html: capability("semantic", "Images, audio, and video round-trip; host-only metadata may be lossy."),
+            markdown: capability("lossy", "Inline and block images round-trip as ![alt](src) (SS2.3: fixed a real silent-data-loss bug - markdownInlineText/markdownBlock's fallback for any atom node was an empty string, deleting images with no trace; images are now routed through atomToMarkdown/parsed back via a real image AST case). Audio and video degrade to a readable [video: url](url) link on export - the link and URL survive, but re-import produces a generic link, not a video/audio atom."),
+            docx: capability("semantic", "Data-URL PNG/JPEG/GIF images embed as native Word media relationships; remote or unsupported sources fall back to a portable text marker recovered on import (SS2.1, re-verified). No canonical DOCX projection exists yet for video/audio (block_image only)."),
+            pdf: capability("lossy", "Export is visual; semantic media import is unsupported."),
+        },
+    },
+    {
+        feature: "formulas",
+        formats: {
+            html: capability("full", "Formula source is stored canonically (data-smart-formula); displayText is presentation-only and is not preserved by canonical's own HTML round-trip, in any format."),
+            markdown: capability("semantic", "Dollar-delimited formula source round-trips: $source$ for inline, $$\\nsource\\n$$ for block (SS2.3: fixed the same silent-data-loss bug as images-media/markdown - formulas were being deleted with no trace on export, and remark's core parser has no math extension so $...$ survived as inert literal text on import even after the export side was fixed; both are now handled via a dedicated post-parse regex split, not a library dependency)."),
+            docx: capability("lossy", "Formula source is written inside an <m:oMath> zone as literal LaTeX text, not translated to real OMML (no partial-OMML build, an explicit standing scope decision) - Word will show the raw LaTeX string, not typeset math. A hidden portable-marker text run carries the source for lossless round-trip back through Smart RTE specifically, independent of whether Word renders it usefully (SS2.1: this replaces a stale note that described a since-retired export path, which no longer applies)."),
+            pdf: capability("lossy", "Rendered output is visual; source cannot be reconstructed reliably."),
+        },
+    },
+    {
+        feature: "special-characters",
+        formats: {
+            html: capability("full", "Unicode text round-trips."),
+            markdown: capability("full", "Unicode text round-trips."),
+            docx: capability("full", "Unicode text is emitted as Word text (SS2.1, re-verified)."),
+            pdf: capability("semantic", "Depends on font embedding and extractor Unicode maps."),
+        },
+    },
+];
+export const getFormatFidelity = (feature, format) => builtInFormatFidelity.find((entry) => entry.feature === feature).formats[format];

package/dist/foundation/formats/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./docx/export.js";
+export * from "./docx/import.js";
+export * from "./docx/styledImport.js";
+export * from "./pdf/format.js";
+export * from "./codec.js";
+export * from "./fidelity.js";
+export * from "./featureCodecs.js";

package/dist/foundation/formats/index.js

@@ -0,0 +1,7 @@
+export * from "./docx/export.js";
+export * from "./docx/import.js";
+export * from "./docx/styledImport.js";
+export * from "./pdf/format.js";
+export * from "./codec.js";
+export * from "./fidelity.js";
+export * from "./featureCodecs.js";

package/dist/foundation/formats/pdf/format.d.ts

@@ -0,0 +1,29 @@
+import type { SmartDocument } from "../../types.js";
+export declare const PDF_MEDIA_TYPE = "application/pdf";
+export interface PdfTextItemSnapshot {
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fontFamily?: string;
+}
+export interface PdfPageSnapshot {
+    width: number;
+    items: readonly PdfTextItemSnapshot[];
+}
+export interface PdfImportResult {
+    document: SmartDocument;
+    layoutHtml: string;
+    pages: number;
+}
+/**
+ * Fidelity: `lossy` for everything - PDF has no structural document model to
+ * recover, only positioned text runs. This is a best-effort layout
+ * reconstruction (lines -> paragraphs/headings/lists/tables via position
+ * heuristics), not a round-trip format. Matches the standing scope decision
+ * since Phase 1.
+ */
+export declare const reconstructPdfPages: (pages: readonly PdfPageSnapshot[]) => PdfImportResult;
+export declare const importPdfDocument: (arrayBuffer: ArrayBuffer) => Promise<PdfImportResult>;
+export declare const buildPdfPrintDocument: (document: SmartDocument) => string;