@uniweb/press 0.4.4 → 0.4.5

package/src/docx/parseStyledString.js

@@ -1,13 +1,17 @@
 /**
- * Parses a styled string with inline HTML marks (<strong>, <em>, <u>, <a>)
- * into an array of text/link part objects with style flags.
+ * Parses a styled string with inline HTML marks (<strong>, <em>, <u>, <a>,
+ * <span data-type="math">) into an array of text / link / math part
+ * objects with style flags.
  *
  * Ported from legacy report-sdk/src/utils.js:116-186, extended to support
  * <a href="..."> hyperlinks so paragraphs with auto-linked emails and URLs
- * produce real hyperlinks in the docx output.
+ * produce real hyperlinks in the docx output, and <span data-type="math">
+ * so inline math reaches the print adapters as a structured atom rather
+ * than being walked as opaque DOM (which turns MathML into raw operator
+ * text).
  *
  * @param {string} inputString - HTML string with inline marks.
- * @returns {Array<{type: string, content: string, bold?: boolean, italics?: boolean, underline?: object, href?: string}>}
+ * @returns {Array<{type: string, content?: string, bold?: boolean, italics?: boolean, underline?: object, href?: string, latex?: string, display?: boolean}>}
  *
  * @example
  * parseStyledString('Hello <strong>World</strong>')
@@ -22,7 +26,34 @@
  * //   { type: 'text', content: 'Visit ' },
  * //   { type: 'link', content: 'Example', href: 'https://example.com' }
  * // ]
+ *
+ * @example
+ * parseStyledString('Let $G$ be a graph')   // after semantic-parser wrapping
+ * // input: 'Let <span data-type="math" data-latex="G" data-display="false">…mathml…</span> be a graph'
+ * // => [
+ * //   { type: 'text', content: 'Let ' },
+ * //   { type: 'math', latex: 'G', display: false },
+ * //   { type: 'text', content: ' be a graph' }
+ * // ]
  */
+
+// Decode HTML-attribute entities written by sequence.js's escapeAttr().
+// Inverse of the four replacements there. `&amp;` last so a literal
+// `&amp;quot;` round-trips correctly.
+function decodeAttr(s) {
+    return String(s)
+        .replace(/&quot;/g, '"')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&amp;/g, '&')
+}
+
+function readAttr(attrs, name) {
+    const re = new RegExp(`${name}="([^"]*)"`)
+    const m = attrs.match(re)
+    return m ? decodeAttr(m[1]) : null
+}
+
 export function parseStyledString(inputString) {
     const createTextPart = (content, styles) => ({
         type: 'text',
@@ -48,8 +79,7 @@ export function parseStyledString(inputString) {
 
             // Handle <a> tags as links
             if (tag === 'a' && attrs) {
-                const hrefMatch = attrs.match(/href="([^"]*)"/)
-                const href = hrefMatch?.[1]
+                const href = readAttr(attrs, 'href')
                 if (href) {
                     result.push({
                         type: 'link',
@@ -61,6 +91,29 @@ export function parseStyledString(inputString) {
                 }
             }
 
+            // Handle <span data-type="math"> as an inline atom. The inner
+            // text is the pre-compiled MathML — discarded here because
+            // print adapters consume the LaTeX source instead. Browser-
+            // side renderers don't go through parseStyledString; they use
+            // dangerouslySetInnerHTML on the original paragraph HTML where
+            // the MathML survives intact.
+            if (tag === 'span' && attrs) {
+                const dataType = readAttr(attrs, 'data-type')
+                if (dataType === 'math') {
+                    const latex = readAttr(attrs, 'data-latex') || ''
+                    const display = readAttr(attrs, 'data-display') === 'true'
+                    const id = readAttr(attrs, 'data-id')
+                    result.push({
+                        type: 'math',
+                        latex,
+                        display,
+                        ...(id ? { id } : {}),
+                    })
+                    lastIndex = offset + match.length
+                    return
+                }
+            }
+
             const newStyles = { ...styles }
             if (tag === 'strong' || tag === 'b') newStyles.bold = true
             if (tag === 'em' || tag === 'i') newStyles.italics = true

package/src/docx/units.js

@@ -73,3 +73,24 @@ export function convertCentimetersToTwip(centimeters) {
 export function convertPointsToHalfPoints(points) {
     return Math.round(points * 2)
 }
+
+// ---------------------------------------------------------------------------
+// Short aliases — for terse JSX. The longer names above remain canonical
+// (and match the docx library's own helpers); these are sugar so foundation
+// code can write `columnWidths={[cm(15), cm(4), cm(1.5), cm(4)]}` instead of
+// `[convertCentimetersToTwip(15), convertCentimetersToTwip(4), …]`.
+// ---------------------------------------------------------------------------
+
+/** Centimeters to twips. Alias of `convertCentimetersToTwip`. */
+export const cm = convertCentimetersToTwip
+
+/** Millimeters to twips. Alias of `convertMillimetersToTwip`. */
+export const mm = convertMillimetersToTwip
+
+/** Inches to twips. Alias of `convertInchesToTwip`. */
+export const inch = convertInchesToTwip
+
+/** Points to twips. There are 20 twips in a point. */
+export function pt(points) {
+    return Math.round(points * 20)
+}

package/src/format/index.jsx

@@ -0,0 +1,171 @@
+/**
+ * @uniweb/press/format — locale-aware text formatters.
+ *
+ * Stage 6.1 of kb/framework/plans/press-professional-docx.md.
+ *
+ * The same JSX feeds the React preview and the docx fragment, so
+ * these are React components that emit <span data-type="text"> and
+ * route through the standard IR walker. Each takes a `value` prop
+ * (or `from`/`to` for ranges) plus optional locale + format props,
+ * and produces a single text node with the formatted string. They
+ * are theme-aware: an active <DocumentProvider> supplies the
+ * default locale and (for currency) the default ISO code, so
+ * foundations don't have to repeat them at every call site.
+ *
+ * The motivation: foundations had been writing `String(invoice.due)`
+ * which yields `"Sat Feb 28 2026 19:00:00 GMT-0500 …"` whenever
+ * YAML eagerly turns an ISO string into a JS Date. The IR layer
+ * also has a defensive Date->ISO coercion (src/adapters/docx.js),
+ * but the right way to render dates is to choose a format
+ * explicitly via these builders.
+ */
+import { useDocumentTheme } from '../ThemeContext.js'
+
+/**
+ * Coerce a value to a JS Date for formatting. Accepts:
+ *   - Date instance (used as-is)
+ *   - ISO string ('2026-03-31')
+ *   - epoch number
+ * Returns null on invalid input so the builder renders nothing.
+ */
+function toDate(value) {
+    if (value == null || value === '') return null
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? null : value
+    }
+    const d = new Date(value)
+    return Number.isNaN(d.getTime()) ? null : d
+}
+
+/**
+ * Map our small set of format names onto Intl.DateTimeFormat option
+ * bags. 'iso' is special-cased — it returns the YYYY-MM-DD form
+ * exactly, using UTC components (not local) so a date like
+ * `2026-03-31` doesn't shift across timezones.
+ */
+const DATE_FORMATS = {
+    iso: null, // sentinel — handled before Intl
+    short: { year: 'numeric', month: 'numeric', day: 'numeric' },
+    medium: { year: 'numeric', month: 'short', day: 'numeric' },
+    long: { year: 'numeric', month: 'long', day: 'numeric' },
+    full: {
+        weekday: 'long',
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+    },
+}
+
+function formatIso(d) {
+    const y = d.getUTCFullYear()
+    const m = String(d.getUTCMonth() + 1).padStart(2, '0')
+    const day = String(d.getUTCDate()).padStart(2, '0')
+    return `${y}-${m}-${day}`
+}
+
+function formatDate(value, { locale = 'en-CA', format = 'medium' } = {}) {
+    const d = toDate(value)
+    if (!d) return ''
+    if (format === 'iso') return formatIso(d)
+    const opts = DATE_FORMATS[format] || DATE_FORMATS.medium
+    try {
+        // Force UTC so date-only ISO inputs ('2026-03-31') don't drift
+        // by the local timezone — without this, en-CA in EST renders
+        // 'Mar 30, 2026' instead of 'Mar 31, 2026'.
+        return new Intl.DateTimeFormat(locale, { ...opts, timeZone: 'UTC' }).format(d)
+    } catch {
+        // Bad locale — fall back to ISO.
+        return formatIso(d)
+    }
+}
+
+function formatDateRange(from, to, opts) {
+    const f = formatDate(from, opts)
+    const t = formatDate(to, opts)
+    if (f && t) return `${f} – ${t}`
+    return f || t || ''
+}
+
+function formatCurrency(value, { locale = 'en-CA', code = 'CAD' } = {}) {
+    if (value == null || value === '') return ''
+    const n = typeof value === 'number' ? value : Number(value)
+    if (!Number.isFinite(n)) return ''
+    try {
+        return new Intl.NumberFormat(locale, {
+            style: 'currency',
+            currency: code,
+            maximumFractionDigits: 2,
+        }).format(n)
+    } catch {
+        // Unknown currency code — fall back to plain number with the code.
+        return `${n.toFixed(2)} ${code}`
+    }
+}
+
+/**
+ * Inline date — emits a single text node with a formatted date.
+ *
+ * @param {Object} props
+ * @param {Date|string|number} props.value
+ * @param {'iso'|'short'|'medium'|'long'|'full'} [props.format='medium']
+ * @param {string} [props.locale] - BCP-47. Defaults to theme.locale.
+ */
+export function DateText({ value, format = 'medium', locale }) {
+    const theme = useDocumentTheme()
+    const text = formatDate(value, {
+        locale: locale ?? theme.locale,
+        format,
+    })
+    return <span data-type="text">{text}</span>
+}
+
+/**
+ * Inline date range — emits a single text node with two formatted
+ * dates joined by an en dash. When one bound is missing, only the
+ * other one renders.
+ */
+export function DateRangeText({
+    from,
+    to,
+    period,
+    format = 'medium',
+    locale,
+}) {
+    const theme = useDocumentTheme()
+    const f = period?.from ?? from
+    const t = period?.to ?? to
+    const text = formatDateRange(f, t, {
+        locale: locale ?? theme.locale,
+        format,
+    })
+    return <span data-type="text">{text}</span>
+}
+
+/**
+ * Inline currency — emits a single text node with a locale- and
+ * code-aware money amount.
+ *
+ * @param {Object} props
+ * @param {number|string} props.value
+ * @param {string} [props.code] - ISO 4217. Defaults to theme.currency.
+ * @param {string} [props.locale]
+ */
+export function Currency({ value, code, locale }) {
+    const theme = useDocumentTheme()
+    const text = formatCurrency(value, {
+        locale: locale ?? theme.locale,
+        code: code ?? theme.currency,
+    })
+    return <span data-type="text">{text}</span>
+}
+
+/**
+ * Imperative versions for callers that need a string outside JSX
+ * (cell content building, header data, etc.). These don't touch the
+ * theme — pass locale/code explicitly.
+ */
+export const formatters = {
+    date: formatDate,
+    dateRange: formatDateRange,
+    currency: formatCurrency,
+}

package/src/index.js

@@ -17,3 +17,9 @@ export {
     compileSubtree,
     compileDocument,
 } from './compileRegistrations.js'
+export {
+    useDocumentTheme,
+    resolveThemeColor,
+    resolveThemeFont,
+    DEFAULT_THEME,
+} from './ThemeContext.js'

package/src/ir/attributes.js

@@ -46,6 +46,23 @@ const toInt = (v) => {
     return Number.isFinite(n) ? n : v
 }
 
+/**
+ * Parse a comma-separated list of integers (whitespace tolerant).
+ * Used by `data-table-column-widths`, where the attribute encodes an
+ * array of twip values like "8504,2268,851,2268". Empty / non-numeric
+ * tokens are dropped — downstream callers treat an empty array the
+ * same as "no column widths declared".
+ */
+const parseIntList = (v) => {
+    if (typeof v !== 'string') return v
+    return v
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => parseInt(s, 10))
+        .filter((n) => Number.isFinite(n))
+}
+
 /**
  * Explicit attribute → IR path mapping. Entries are listed in the same
  * order as the legacy switch for ease of cross-reference.
@@ -94,6 +111,124 @@ export const attributeMap = {
     'data-borders-right-size': { path: ['borders', 'right', 'size'] },
     'data-borders-right-color': { path: ['borders', 'right', 'color'] },
 
+    // ------------------------------------------------------------------
+    // Table-cell additions (Stage 1 of the press-professional-docx plan)
+    // ------------------------------------------------------------------
+
+    // Cell shading. `data-shading-fill` is the load-bearing attribute
+    // (the solid background color). `data-shading-type` defaults to
+    // 'clear' in the adapter so a plain fill JSX prop produces a solid
+    // background without callers having to remember the OOXML idiom.
+    'data-shading-fill': { path: ['shading', 'fill'] },
+    'data-shading-color': { path: ['shading', 'color'] },
+    'data-shading-type': { path: ['shading', 'type'] },
+
+    // Vertical alignment of the cell's content. `top` | `center` | `bottom`.
+    // Maps to docx's VerticalAlignTable enum at the adapter layer.
+    'data-valign': { path: ['verticalAlign'] },
+
+    // Cell column merge: how many adjacent columns this cell spans.
+    'data-grid-span': { path: ['columnSpan'], transform: toInt },
+
+    // Cell row merge: how many rows this cell spans (vertical merge).
+    // The adapter uses docx's `rowSpan` shorthand, which expects only
+    // the *starting* cell to declare a count; library handles the
+    // merge-continue rows internally.
+    'data-row-span': { path: ['rowSpan'], transform: toInt },
+
+    // ------------------------------------------------------------------
+    // Stage 3 — paragraph polish
+    // ------------------------------------------------------------------
+
+    // Paragraph indentation. All values are twips. `firstLine` and
+    // `hanging` are positive; `left` and `right` may be negative.
+    'data-indent-left': { path: ['indent', 'left'], transform: toInt },
+    'data-indent-right': { path: ['indent', 'right'], transform: toInt },
+    'data-indent-firstline': { path: ['indent', 'firstLine'], transform: toInt },
+    'data-indent-hanging': { path: ['indent', 'hanging'], transform: toInt },
+
+    // Paragraph tab stops. JSON-encoded array of TabStopDefinition objects:
+    //   [{ position: 6804, type: 'right', leader: 'dot' }, …]
+    // Position is in twips; type is left/right/center/decimal/etc;
+    // leader is none/dot/hyphen/underscore/middleDot. Foundations
+    // typically construct these via the <Paragraph tabStops=…> prop
+    // and the unit helpers (cm, mm, inch, pt).
+    // Paragraph-level named style ('Title', 'Heading1', 'Body', …).
+    // Maps to `<w:pStyle w:val="…"/>` in the docx adapter. Distinct
+    // from the run-level `data-style` (default fallthrough), which
+    // emits `<w:rStyle>`.
+    'data-paragraph-style': { path: ['paragraphStyle'] },
+
+    'data-tab-stops': {
+        path: ['tabStops'],
+        transform: (v) => {
+            if (typeof v !== 'string') return v
+            try {
+                const parsed = JSON.parse(v)
+                return Array.isArray(parsed) ? parsed : v
+            } catch {
+                return v
+            }
+        },
+    },
+
+    // TextRun toggles — explicit map entries route the lower-case
+    // HTML attribute names to camelCase IR fields the adapter reads.
+    'data-smallcaps': { path: ['smallCaps'], transform: asTrue },
+    'data-allcaps': { path: ['allCaps'], transform: asTrue },
+    'data-strike': { path: ['strike'], transform: asTrue },
+
+    // Row-level: whether the row repeats as a header on each new page
+    // when the table breaks. Presence-only — any truthy value counts.
+    'data-row-header': { path: ['tableHeader'], transform: asTrue },
+
+    // ------------------------------------------------------------------
+    // Table-level options (Stage 1)
+    //
+    // Stored under the prefixed `tableXxx` namespace so they don't
+    // collide with the cell-level `width` / `borders` properties that
+    // existed before. `irToTable` reads these on table-typed nodes.
+    // ------------------------------------------------------------------
+
+    // Column widths in twips. Emitted as a comma-separated string on
+    // the `<table>` element by Table.jsx; parsed back to an int array
+    // here. Used with `tableLayout: 'fixed'` to lock columns; without
+    // a fixed layout, Word redistributes columns to fit content.
+    'data-table-column-widths': {
+        path: ['tableColumnWidths'],
+        transform: parseIntList,
+    },
+
+    // 'fixed' | 'autofit'. Default in the adapter is 'fixed' when
+    // tableColumnWidths is set, undefined otherwise (Word's default).
+    'data-table-layout': { path: ['tableLayout'] },
+
+    // Whole-table width. Distinct from per-cell width. Same { size, type }
+    // shape (pct/dxa/auto) as cell widths.
+    'data-table-width-size': { path: ['tableWidth', 'size'] },
+    'data-table-width-type': { path: ['tableWidth', 'type'] },
+
+    // Table-level default borders. Per-cell borders still win (and
+    // already exist via `data-borders-*`); these set the table grid.
+    'data-table-borders-top-style': { path: ['tableBorders', 'top', 'style'] },
+    'data-table-borders-top-size': { path: ['tableBorders', 'top', 'size'] },
+    'data-table-borders-top-color': { path: ['tableBorders', 'top', 'color'] },
+    'data-table-borders-bottom-style': { path: ['tableBorders', 'bottom', 'style'] },
+    'data-table-borders-bottom-size': { path: ['tableBorders', 'bottom', 'size'] },
+    'data-table-borders-bottom-color': { path: ['tableBorders', 'bottom', 'color'] },
+    'data-table-borders-left-style': { path: ['tableBorders', 'left', 'style'] },
+    'data-table-borders-left-size': { path: ['tableBorders', 'left', 'size'] },
+    'data-table-borders-left-color': { path: ['tableBorders', 'left', 'color'] },
+    'data-table-borders-right-style': { path: ['tableBorders', 'right', 'style'] },
+    'data-table-borders-right-size': { path: ['tableBorders', 'right', 'size'] },
+    'data-table-borders-right-color': { path: ['tableBorders', 'right', 'color'] },
+    'data-table-borders-insideh-style': { path: ['tableBorders', 'insideHorizontal', 'style'] },
+    'data-table-borders-insideh-size': { path: ['tableBorders', 'insideHorizontal', 'size'] },
+    'data-table-borders-insideh-color': { path: ['tableBorders', 'insideHorizontal', 'color'] },
+    'data-table-borders-insidev-style': { path: ['tableBorders', 'insideVertical', 'style'] },
+    'data-table-borders-insidev-size': { path: ['tableBorders', 'insideVertical', 'size'] },
+    'data-table-borders-insidev-color': { path: ['tableBorders', 'insideVertical', 'color'] },
+
     'data-image-type': { path: ['imageType'] },
 
     'data-floating-horizontalposition-relative': {

package/src/styles/buildStylePack.js

@@ -0,0 +1,190 @@
+/**
+ * Synthesize OOXML style definitions from a Press theme.
+ *
+ * Stage 6.0 of kb/framework/plans/press-professional-docx.md.
+ *
+ * The theme.typography registry is the foundation-facing API:
+ *
+ *   theme.typography.Title = {
+ *     font: 'heading',         // theme key or literal family
+ *     size: 56,                // half-points (28pt)
+ *     bold: true,
+ *     color: 'accent',         // theme key or hex
+ *     paragraph: { spacing: { after: 240 } },
+ *   }
+ *
+ * docx@9.x is opinionated about where named styles live. It ships
+ * built-in styles for Title, Heading1-6, Hyperlink, Strong, and
+ * ListParagraph; entries with those ids in the custom `paragraphStyles`
+ * array are ignored in favor of the built-ins. The library exposes
+ * `default.{title, heading1, …, hyperlink, strong, listParagraph}`
+ * slots specifically for overriding the built-ins. We route role
+ * specs to the right slot:
+ *
+ *   - 'Body' / 'Normal'             -> default.document       (doc-wide rPrDefault/pPrDefault)
+ *   - 'Title'                       -> default.title
+ *   - 'Heading1'..'Heading6'        -> default.heading1..6
+ *   - 'Hyperlink'                   -> default.hyperlink
+ *   - 'Strong'                      -> default.strong
+ *   - 'ListParagraph'               -> default.listParagraph
+ *   - everything else, kind=paragraph  -> custom paragraphStyles[]
+ *   - everything else, kind=character  -> custom characterStyles[]
+ *
+ * Foundations may also pass `paragraphStyles` / `characterStyles`
+ * directly through compile options; those merge on top of the
+ * synthesized entries (caller wins on style id conflict).
+ */
+
+import { resolveThemeColor, resolveThemeFont, DEFAULT_THEME } from '../ThemeContext.js'
+
+// Roles that map to docx's named built-in slots in `default.*`.
+const BUILT_IN_DEFAULT_SLOTS = {
+    Body: 'document',
+    Normal: 'document',
+    Title: 'title',
+    Heading1: 'heading1',
+    Heading2: 'heading2',
+    Heading3: 'heading3',
+    Heading4: 'heading4',
+    Heading5: 'heading5',
+    Heading6: 'heading6',
+    Hyperlink: 'hyperlink',
+    Strong: 'strong',
+    ListParagraph: 'listParagraph',
+}
+
+/**
+ * Resolve a single typography-role spec against the theme, producing
+ * the `{ paragraph, run }` shape the docx library expects.
+ */
+function resolveRoleSpec(spec, theme) {
+    const run = {}
+    if (spec.bold) run.bold = true
+    if (spec.italics) run.italics = true
+    if (spec.smallCaps) run.smallCaps = true
+    if (spec.allCaps) run.allCaps = true
+    if (spec.strike) run.strike = true
+    if (spec.size != null) run.size = spec.size
+    const color = resolveThemeColor(spec.color, theme)
+    if (color) run.color = color
+    const font = resolveThemeFont(spec.font, theme)
+    if (font) run.font = font
+    if (spec.underline) {
+        run.underline =
+            typeof spec.underline === 'string'
+                ? { type: spec.underline }
+                : spec.underline
+    }
+
+    const out = {}
+    if (Object.keys(run).length) out.run = run
+    if (spec.paragraph) out.paragraph = spec.paragraph
+    return out
+}
+
+/**
+ * Build the `styles` block for `new Document({ styles: … })` from a
+ * theme.typography registry.
+ *
+ * @param {Object} theme
+ * @param {Object} [overrides]
+ * @param {Array} [overrides.paragraphStyles] - merged on top, caller wins.
+ * @param {Array} [overrides.characterStyles] - merged on top, caller wins.
+ * @returns {{ default: Object, paragraphStyles: Array, characterStyles: Array }}
+ */
+export function buildStylePack(theme = DEFAULT_THEME, overrides = {}) {
+    const typography = theme?.typography || DEFAULT_THEME.typography
+    const kinds = theme?.typographyKinds || DEFAULT_THEME.typographyKinds
+
+    const defaults = {}
+    const paragraphStyles = []
+    const characterStyles = []
+
+    for (const [roleName, spec] of Object.entries(typography)) {
+        const resolved = resolveRoleSpec(spec, theme)
+        const slot = BUILT_IN_DEFAULT_SLOTS[roleName]
+
+        if (slot === 'document') {
+            // Doc-wide defaults — applies to every paragraph and run.
+            // The OOXML <w:rPrDefault>/<w:pPrDefault>. This is what
+            // pins the body font (no more Times New Roman fallback).
+            defaults.document = {
+                ...(resolved.run ? { run: resolved.run } : {}),
+                ...(resolved.paragraph ? { paragraph: resolved.paragraph } : {}),
+            }
+            continue
+        }
+
+        if (slot) {
+            // Override a built-in named style (Title, Heading1-6, etc.).
+            defaults[slot] = resolved
+            continue
+        }
+
+        // Custom role — falls into paragraphStyles or characterStyles.
+        const kind = kinds[roleName] || 'character'
+        if (kind === 'paragraph') {
+            paragraphStyles.push({
+                id: roleName,
+                name: roleName,
+                basedOn: 'Normal',
+                next: 'Normal',
+                quickFormat: true,
+                ...resolved,
+            })
+        } else {
+            characterStyles.push({
+                id: roleName,
+                name: roleName,
+                basedOn: 'Normal',
+                quickFormat: true,
+                ...(resolved.run ? { run: resolved.run } : {}),
+            })
+        }
+    }
+
+    // Caller-supplied paragraph/character styles take effect in two
+    // ways. Entries with built-in style IDs (Title, Heading1-6,
+    // Hyperlink, Strong) route to `default.{slot}` since docx ignores
+    // those IDs in the custom `paragraphStyles` / `characterStyles`
+    // arrays. Everything else appends/overrides in the array.
+    const callerParagraphs = overrides.paragraphStyles || []
+    const callerCharacters = overrides.characterStyles || []
+
+    for (const style of [...callerParagraphs, ...callerCharacters]) {
+        const slot = BUILT_IN_DEFAULT_SLOTS[style.id]
+        if (!slot) continue
+        const { id: _id, name: _name, basedOn: _b, next: _n, quickFormat: _q, run, paragraph } =
+            style
+        defaults[slot] = {
+            ...(run ? { run } : {}),
+            ...(paragraph ? { paragraph } : {}),
+        }
+    }
+
+    const filteredCallerParagraphs = callerParagraphs.filter(
+        (s) => !BUILT_IN_DEFAULT_SLOTS[s.id],
+    )
+    const filteredCallerCharacters = callerCharacters.filter(
+        (s) => !BUILT_IN_DEFAULT_SLOTS[s.id],
+    )
+
+    return {
+        default: defaults,
+        paragraphStyles: mergeById(paragraphStyles, filteredCallerParagraphs),
+        characterStyles: mergeById(characterStyles, filteredCallerCharacters),
+    }
+}
+
+function mergeById(synthesized, caller) {
+    if (!Array.isArray(caller) || caller.length === 0) return synthesized
+    const callerById = new Map(caller.map((s) => [s.id, s]))
+    const out = synthesized.map((s) =>
+        callerById.has(s.id) ? callerById.get(s.id) : s,
+    )
+    const synthIds = new Set(synthesized.map((s) => s.id))
+    for (const s of caller) {
+        if (!synthIds.has(s.id)) out.push(s)
+    }
+    return out
+}

package/src/typst/Math.jsx

@@ -0,0 +1,23 @@
+/**
+ * Math equation — non-text inline atom. Emits a marker span the IR
+ * walker turns into a `math` IR node. The typst adapter dispatches on
+ * the node and emits `#mitex(`<latex>`)` (inline) or `$ #mitex(`<latex>`) $`
+ * (display); foundations consuming `outputs.typst` import mitex in
+ * their preamble.
+ *
+ * Inline and block math share the same builder, distinguished by the
+ * `display` flag. The optional `id` flows through as data-id so the
+ * typst adapter can emit a typst label (`<id>`) for native
+ * cross-references.
+ *
+ * Mirrors `Image` — same role (non-text inline atom), same attribute
+ * convention, same dispatch shape on the adapter side.
+ */
+export default function Math({ latex, display = false, id, ...props }) {
+    const attrs = { 'data-type': 'math' }
+    attrs['data-latex'] = latex || ''
+    attrs['data-display'] = display ? 'true' : 'false'
+    if (id) attrs['data-id'] = id
+
+    return <span {...attrs} {...props} />
+}