postext 1.33.11 → 1.34.1

package/dist/composed/templates.js

@@ -0,0 +1,702 @@
+// Page templates (composed pages, #853): defaults, `extends` and variant
+// resolution, and the normalisation of frames, groups and label styles.
+// Pure; nothing here lays anything out (that is P4, #855).
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const ZERO = { value: 0, unit: 'mm' };
+export const DEFAULT_FRAME_FIT = {
+    shrinkText: true,
+    minScale: 0.9,
+    scaleImages: true,
+    imageMinScale: 0.8,
+};
+/** What a frame that sets nothing comes to (besides its name). */
+export const DEFAULT_FRAME = {
+    width: 'fill',
+    height: 'auto',
+    layer: 1,
+    rotate: 0,
+    verticalAlign: 'top',
+    columns: 1,
+    exclude: 'none',
+    flow: false,
+    pin: false,
+    grow: 0,
+    shrink: 0,
+    priority: 0,
+    optional: false,
+    crossGutter: false,
+};
+export const DEFAULT_FRAME_GROUP = {
+    kind: 'stack',
+    gap: ZERO,
+    align: 'start',
+};
+export const DEFAULT_PAGE_TEMPLATE = {
+    area: 'content',
+    spread: false,
+    gutter: ZERO,
+    role: 'composed',
+};
+export const DEFAULT_LABEL_STYLE = {
+    fontStyle: 'normal',
+    textTransform: 'none',
+    minScale: 0.85,
+};
+export const FRAME_VERTICAL_ALIGNS = ['top', 'middle', 'bottom', 'justify'];
+export const FRAME_EXCLUDES = ['none', 'push'];
+export const FRAME_TAKES = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
+export const FRAME_GROUP_KINDS = ['stack', 'row'];
+export const FRAME_GROUP_ALIGNS = ['start', 'center', 'end', 'space-between'];
+export const TEMPLATE_AREAS = ['content', 'trim', 'bleed'];
+export const FRAME_WRITING_MODES = ['horizontal-tb', 'vertical-rl'];
+export const FRAME_DIRECTIONS = ['ltr', 'rtl'];
+export const LABEL_FONT_STYLES = ['normal', 'italic'];
+export const LABEL_TEXT_TRANSFORMS = ['none', 'uppercase'];
+const DIMENSION_UNITS = ['cm', 'mm', 'in', 'pt', 'px', 'em', 'rem'];
+// ---------------------------------------------------------------------------
+// Small readers
+// ---------------------------------------------------------------------------
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+const oneOf = (list, v) => typeof v === 'string' && list.includes(v);
+/** A length the engine can use: a finite, non-negative value in a known
+ *  unit. */
+export function isFrameDimension(v) {
+    return isRecord(v) && finite(v.value) && v.value >= 0 && typeof v.unit === 'string' && DIMENSION_UNITS.includes(v.unit);
+}
+/** `v` as a frame size, or undefined when it is none. A percentage is
+ *  clamped to 0 … 100. */
+export function normalizeFrameSize(v) {
+    if (v === 'auto' || v === 'fill')
+        return v;
+    if (isRecord(v) && 'percent' in v) {
+        return finite(v.percent) ? { percent: Math.min(100, Math.max(0, v.percent)) } : undefined;
+    }
+    return isFrameDimension(v) ? { value: v.value, unit: v.unit } : undefined;
+}
+/** The id an anchor names (`'#dinero'` → `'dinero'`), or undefined. */
+export function anchorTarget(placement) {
+    const to = isRecord(placement) && isRecord(placement.anchor) ? placement.anchor.to : undefined;
+    return typeof to === 'string' && to.startsWith('#') && to.length > 1 ? to.slice(1) : undefined;
+}
+/** The frame a `continueIn` of the form `'#frame'` names. */
+export function continueInFrame(continueIn) {
+    return typeof continueIn === 'string' && continueIn.startsWith('#') && continueIn.length > 1 ? continueIn.slice(1) : undefined;
+}
+/** The template a `continueIn` of the form `'template:<id>'` names. */
+export function continueInTemplate(continueIn) {
+    return typeof continueIn === 'string' && continueIn.startsWith('template:') && continueIn.length > 9 ? continueIn.slice(9) : undefined;
+}
+// ---------------------------------------------------------------------------
+// The template table: which template each id means
+// ---------------------------------------------------------------------------
+/** id → index of the first template with it. */
+function idTable(templates) {
+    const byId = new Map();
+    templates.forEach((t, i) => {
+        if (isRecord(t) && typeof t.id === 'string' && t.id !== '' && !byId.has(t.id))
+            byId.set(t.id, i);
+    });
+    return byId;
+}
+/** The chain of template indices from `index` up to its root, nearest
+ *  first; `null` when it loops back on itself. A parent that does not
+ *  exist ends the chain (the template stands alone). */
+export function templateChain(templates, index, byId = idTable(templates)) {
+    const chain = [];
+    const seen = new Set();
+    let at = index;
+    while (at !== undefined) {
+        if (seen.has(at))
+            return null;
+        seen.add(at);
+        chain.push(at);
+        const parent = templates[at]?.extends;
+        at = typeof parent === 'string' ? byId.get(parent) : undefined;
+    }
+    return chain;
+}
+/** The index of the template `id` means: the first with that id. */
+export function templateIndex(templates, id) {
+    return templates ? idTable(templates).get(id) : undefined;
+}
+/** The template-level keys a child or a variant inherits and overrides. */
+const SCALAR_KEYS = ['area', 'overflowTemplate', 'bodyStyle', 'palette', 'header', 'footer'];
+const INHERITED_KEYS = ['spread', 'gutter', 'role'];
+/** Frame fields merged key by key rather than replaced. */
+const MERGED_OBJECT_KEYS = new Set(['fit', 'overflow', 'padding']);
+function mergeNamed(list, entries, basePath, issues) {
+    if (!Array.isArray(entries))
+        return;
+    const seen = new Set();
+    entries.forEach((raw, j) => {
+        if (!isRecord(raw) || typeof raw.name !== 'string' || raw.name === '')
+            return;
+        const name = raw.name;
+        const path = `${basePath}/${j}`;
+        if (seen.has(name)) {
+            issues.push({ kind: 'frameDuplicate', path, value: name, used: '' });
+            return;
+        }
+        seen.add(name);
+        const at = list.findIndex((e) => e.value.name === name);
+        if (raw.remove === true) {
+            if (at >= 0)
+                list.splice(at, 1);
+            return;
+        }
+        const entry = at >= 0
+            ? { value: { ...list[at].value }, configPath: path, fieldPaths: { ...list[at].fieldPaths } }
+            : { value: { name }, configPath: path, fieldPaths: {} };
+        for (const [key, value] of Object.entries(raw)) {
+            if (key === 'name' || key === 'remove' || value === undefined)
+                continue;
+            const target = entry.value;
+            if (MERGED_OBJECT_KEYS.has(key) && isRecord(value)) {
+                const before = target[key];
+                const merged = isRecord(before) ? { ...before } : {};
+                for (const [sub, v] of Object.entries(value)) {
+                    if (v === undefined)
+                        continue;
+                    merged[sub] = v;
+                    entry.fieldPaths[`${key}/${sub}`] = `${path}/${key}/${sub}`;
+                }
+                target[key] = merged;
+            }
+            else {
+                target[key] = value;
+            }
+            entry.fieldPaths[key] = `${path}/${key}`;
+        }
+        if (at >= 0)
+            list[at] = entry;
+        else
+            list.push(entry);
+    });
+}
+function mergePatch(target, patch, path, issues) {
+    if (!isRecord(patch))
+        return;
+    for (const key of SCALAR_KEYS) {
+        const value = patch[key];
+        if (value === undefined)
+            continue;
+        target.fields[key] = value;
+        target.fieldPaths[key] = `${path}/${key}`;
+    }
+    if (isRecord(patch.grid)) {
+        const before = target.fields.grid;
+        const merged = isRecord(before) ? { ...before } : {};
+        for (const [k, v] of Object.entries(patch.grid))
+            if (v !== undefined)
+                merged[k] = v;
+        target.fields.grid = merged;
+        target.fieldPaths.grid = `${path}/grid`;
+    }
+    mergeNamed(target.frames, patch.frames, `${path}/frames`, issues);
+    mergeNamed(target.groups, patch.groups, `${path}/groups`, issues);
+    const elements = isRecord(patch.decoration) ? patch.decoration.elements : undefined;
+    if (Array.isArray(elements)) {
+        elements.forEach((el, j) => {
+            if (!isRecord(el))
+                return;
+            const element = el;
+            const elementPath = `${path}/decoration/elements/${j}`;
+            const id = typeof el.id === 'string' && el.id !== '' ? el.id : undefined;
+            const at = id === undefined ? -1 : target.elements.findIndex((e) => e.value.id === id);
+            if (at >= 0) {
+                const merged = { ...target.elements[at].value };
+                for (const [k, v] of Object.entries(el))
+                    if (v !== undefined)
+                        merged[k] = v;
+                target.elements[at] = { value: merged, configPath: elementPath };
+            }
+            else {
+                target.elements.push({ value: element, configPath: elementPath });
+            }
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Normalisation
+// ---------------------------------------------------------------------------
+function normalizeGrid(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const columns = finite(raw.columns) && raw.columns >= 1 ? Math.round(raw.columns) : undefined;
+    const rows = finite(raw.rows) && raw.rows >= 1 ? Math.round(raw.rows) : undefined;
+    if (columns === undefined || rows === undefined)
+        return undefined;
+    return {
+        columns,
+        rows,
+        columnGap: isFrameDimension(raw.columnGap) ? raw.columnGap : ZERO,
+        rowGap: isFrameDimension(raw.rowGap) ? raw.rowGap : ZERO,
+    };
+}
+/** A grid cell clamped to the grid; undefined without a grid or a cell. */
+function normalizeCell(raw, grid) {
+    if (!grid || !isRecord(raw) || !finite(raw.col) || !finite(raw.row))
+        return undefined;
+    const col = Math.min(grid.columns, Math.max(1, Math.round(raw.col)));
+    const row = Math.min(grid.rows, Math.max(1, Math.round(raw.row)));
+    const cols = finite(raw.cols) ? Math.min(grid.columns - col + 1, Math.max(1, Math.round(raw.cols))) : 1;
+    const rows = finite(raw.rows) ? Math.min(grid.rows - row + 1, Math.max(1, Math.round(raw.rows))) : 1;
+    return { col, row, cols, rows };
+}
+const scale = (v, fallback) => (finite(v) && v > 0 ? Math.min(1, v) : fallback);
+function normalizeFit(raw) {
+    const f = isRecord(raw) ? raw : {};
+    return {
+        shrinkText: typeof f.shrinkText === 'boolean' ? f.shrinkText : DEFAULT_FRAME_FIT.shrinkText,
+        minScale: scale(f.minScale, DEFAULT_FRAME_FIT.minScale),
+        scaleImages: typeof f.scaleImages === 'boolean' ? f.scaleImages : DEFAULT_FRAME_FIT.scaleImages,
+        imageMinScale: scale(f.imageMinScale, DEFAULT_FRAME_FIT.imageMinScale),
+    };
+}
+function normalizeOverflow(raw) {
+    if (!isRecord(raw))
+        return {};
+    const out = {};
+    if (typeof raw.continueIn === 'string' && raw.continueIn !== '')
+        out.continueIn = raw.continueIn;
+    if (typeof raw.mark === 'string' || raw.mark === false)
+        out.mark = raw.mark;
+    return out;
+}
+const dim = (v) => (isFrameDimension(v) ? v : undefined);
+const nonNegative = (v, fallback) => (finite(v) && v >= 0 ? v : fallback);
+/** A frame as the layout reads it: every default filled in, sizes read
+ *  from `width`/`height` and else `placement.size`, values the engine
+ *  cannot use replaced by their default. */
+export function normalizeFrame(frame, grid, where = { configPath: '', fieldPaths: {} }) {
+    const f = frame;
+    const placement = isRecord(f.placement) ? f.placement : undefined;
+    const cell = normalizeCell(f.grid, grid);
+    const out = {
+        name: f.name,
+        ...(placement ? { placement } : {}),
+        ...(cell ? { grid: cell } : {}),
+        width: normalizeFrameSize(f.width) ?? normalizeFrameSize(placement?.size?.width) ?? DEFAULT_FRAME.width,
+        height: normalizeFrameSize(f.height) ?? normalizeFrameSize(placement?.size?.height) ?? DEFAULT_FRAME.height,
+        layer: finite(f.layer) ? f.layer : DEFAULT_FRAME.layer,
+        rotate: finite(f.rotate) ? f.rotate : DEFAULT_FRAME.rotate,
+        verticalAlign: oneOf(FRAME_VERTICAL_ALIGNS, f.verticalAlign) ? f.verticalAlign : DEFAULT_FRAME.verticalAlign,
+        columns: finite(f.columns) && f.columns >= 1 ? Math.round(f.columns) : DEFAULT_FRAME.columns,
+        exclude: oneOf(FRAME_EXCLUDES, f.exclude) ? f.exclude : DEFAULT_FRAME.exclude,
+        flow: f.flow === true,
+        pin: f.pin === true,
+        grow: nonNegative(f.grow, DEFAULT_FRAME.grow),
+        shrink: nonNegative(f.shrink, DEFAULT_FRAME.shrink),
+        priority: finite(f.priority) ? f.priority : DEFAULT_FRAME.priority,
+        fit: normalizeFit(f.fit),
+        overflow: normalizeOverflow(f.overflow),
+        optional: f.optional === true,
+        crossGutter: f.crossGutter === true,
+        configPath: where.configPath,
+        fieldPaths: where.fieldPaths,
+    };
+    for (const key of ['minWidth', 'maxWidth', 'minHeight', 'maxHeight', 'columnGap']) {
+        const d = dim(f[key]);
+        if (d)
+            out[key] = d;
+    }
+    if (typeof f.style === 'string' && f.style !== '')
+        out.style = f.style;
+    if (isRecord(f.padding)) {
+        const padding = {};
+        for (const side of ['top', 'right', 'bottom', 'left']) {
+            const d = dim(f.padding[side]);
+            if (d)
+                padding[side] = d;
+        }
+        out.padding = padding;
+    }
+    if (typeof f.next === 'string' && f.next !== '')
+        out.next = f.next;
+    if (oneOf(FRAME_TAKES, f.takes))
+        out.takes = f.takes;
+    if (oneOf(FRAME_WRITING_MODES, f.writingMode))
+        out.writingMode = f.writingMode;
+    if (oneOf(FRAME_DIRECTIONS, f.direction))
+        out.direction = f.direction;
+    return out;
+}
+function normalizeGroup(entry, grid) {
+    const g = entry.value;
+    const placement = isRecord(g.placement) ? g.placement : undefined;
+    const cell = normalizeCell(g.grid, grid);
+    return {
+        name: g.name,
+        kind: oneOf(FRAME_GROUP_KINDS, g.kind) ? g.kind : DEFAULT_FRAME_GROUP.kind,
+        frames: Array.isArray(g.frames) ? g.frames.filter((n) => typeof n === 'string') : [],
+        gap: dim(g.gap) ?? DEFAULT_FRAME_GROUP.gap,
+        ...(placement ? { placement } : {}),
+        ...(cell ? { grid: cell } : {}),
+        align: oneOf(FRAME_GROUP_ALIGNS, g.align) ? g.align : DEFAULT_FRAME_GROUP.align,
+        configPath: entry.configPath,
+        fieldPaths: entry.fieldPaths,
+    };
+}
+// ---------------------------------------------------------------------------
+// References: groups, anchors, chains
+// ---------------------------------------------------------------------------
+/** Where a placement's anchor sits among a frame's or group's fields. */
+const ANCHOR_FIELD = 'placement/anchor/to';
+function withContainerAnchor(placement) {
+    return { ...placement, anchor: { ...placement.anchor, to: 'container' } };
+}
+/** The first loop of `edges` reachable in `order`, as the node list from
+ *  the node it closes on back to it, or undefined. */
+function findLoop(order, edges) {
+    const state = new Map();
+    const stack = [];
+    const visit = (n) => {
+        state.set(n, 1);
+        stack.push(n);
+        for (const m of edges.get(n) ?? []) {
+            const s = state.get(m);
+            if (s === 1)
+                return [...stack.slice(stack.indexOf(m)), m];
+            if (s === undefined) {
+                const found = visit(m);
+                if (found)
+                    return found;
+            }
+        }
+        stack.pop();
+        state.set(n, 2);
+        return undefined;
+    };
+    for (const n of order) {
+        if (state.has(n))
+            continue;
+        const found = visit(n);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/** Settle the references of a merged template: group members that do not
+ *  exist or are claimed twice are skipped, anchors to nothing (or in a
+ *  loop) read as `'container'`, `next`/`continueIn` links to nothing (or
+ *  closing a loop) are dropped. Each fix is an issue. */
+function settleReferences(frames, groups, decoration, context, overflowTemplate, issues) {
+    const frameNames = frames.map((f) => f.name);
+    const frameSet = new Set(frameNames);
+    // A group named like a frame: anchors read the frame.
+    for (const g of groups) {
+        if (frameSet.has(g.name))
+            issues.push({ kind: 'frameDuplicate', path: g.configPath, value: g.name, used: '' });
+    }
+    const boxNames = [...frameNames, ...groups.map((g) => g.name).filter((n) => !frameSet.has(n))];
+    const boxSet = new Set(boxNames);
+    // Styles.
+    if (context.calloutStyleIds) {
+        for (const f of frames) {
+            if (f.style !== undefined && !context.calloutStyleIds.has(f.style)) {
+                issues.push({ kind: 'frameStyleUnknown', path: f.fieldPaths.style ?? `${f.configPath}/style`, value: f.style, used: '', known: [...context.calloutStyleIds] });
+                delete f.style;
+            }
+        }
+    }
+    // Group members.
+    const claimed = new Set();
+    for (const g of groups) {
+        const raw = g.frames;
+        const kept = [];
+        raw.forEach((name, k) => {
+            const path = `${g.fieldPaths.frames ?? `${g.configPath}/frames`}/${k}`;
+            if (!frameSet.has(name)) {
+                issues.push({ kind: 'groupFrameUnknown', path, value: name, used: '', known: frameNames });
+            }
+            else if (claimed.has(name)) {
+                issues.push({ kind: 'groupFrameTwice', path, value: name, used: '' });
+            }
+            else {
+                claimed.add(name);
+                kept.push(name);
+            }
+        });
+        g.frames = kept;
+    }
+    const boxes = new Map();
+    for (const f of frames)
+        if (!boxes.has(f.name))
+            boxes.set(f.name, f);
+    for (const g of groups)
+        if (!boxes.has(g.name))
+            boxes.set(g.name, g);
+    const anchorPath = (b) => b.fieldPaths.placement ? `${b.fieldPaths.placement}/anchor/to` : `${b.configPath}/${ANCHOR_FIELD}`;
+    const anchored = (b) => (b.grid ? undefined : anchorTarget(b.placement));
+    for (const b of boxes.values()) {
+        const target = anchored(b);
+        if (target !== undefined && !boxSet.has(target)) {
+            issues.push({ kind: 'frameAnchorUnknown', path: anchorPath(b), value: `#${target}`, used: 'container', known: boxNames.map((n) => `#${n}`) });
+            b.placement = withContainerAnchor(b.placement);
+        }
+    }
+    for (;;) {
+        const edges = new Map();
+        for (const [name, b] of boxes) {
+            const out = [];
+            const target = anchored(b);
+            if (target !== undefined)
+                out.push(target);
+            // A group with no box of its own is the union of its frames' boxes.
+            if ('kind' in b && !b.placement && !b.grid)
+                out.push(...b.frames);
+            edges.set(name, out);
+        }
+        const loop = findLoop(boxNames, edges);
+        if (!loop)
+            break;
+        // Drop the explicit anchor of the loop set latest in template order.
+        let drop;
+        for (let k = 0; k < loop.length - 1; k++) {
+            const b = boxes.get(loop[k]);
+            if (anchored(b) === loop[k + 1] && (!drop || boxNames.indexOf(b.name) > boxNames.indexOf(drop.name)))
+                drop = b;
+        }
+        if (!drop)
+            break; // cannot happen: a group's members never loop by themselves
+        issues.push({ kind: 'frameAnchorUnknown', path: anchorPath(drop), value: loop.join(' → '), used: 'container' });
+        drop.placement = withContainerAnchor(drop.placement);
+    }
+    // Decoration anchors: another element of the decoration, or a box.
+    const elementIds = new Set(decoration.map((e) => e.value.id).filter((id) => typeof id === 'string'));
+    decoration.forEach((e) => {
+        const target = anchorTarget(e.value.placement);
+        if (target !== undefined && !elementIds.has(target) && !boxSet.has(target)) {
+            issues.push({ kind: 'frameAnchorUnknown', path: `${e.configPath}/${ANCHOR_FIELD}`, value: `#${target}`, used: 'container', known: [...boxNames, ...elementIds].map((n) => `#${n}`) });
+            e.value = { ...e.value, placement: withContainerAnchor(e.value.placement) };
+        }
+    });
+    // Chains: `next` and `overflow.continueIn`.
+    for (const f of frames) {
+        if (f.next !== undefined && !frameSet.has(f.next)) {
+            issues.push({ kind: 'overflowTargetUnknown', path: f.fieldPaths.next ?? `${f.configPath}/next`, value: f.next, used: '', known: frameNames });
+            delete f.next;
+        }
+        const continueIn = f.overflow.continueIn;
+        if (continueIn !== undefined) {
+            const frameTarget = continueInFrame(continueIn);
+            const templateTarget = continueInTemplate(continueIn);
+            const ok = continueIn === 'next-page'
+                || (frameTarget !== undefined && frameSet.has(frameTarget))
+                || (templateTarget !== undefined && context.templateIds.has(templateTarget));
+            if (!ok) {
+                const known = frameTarget !== undefined ? frameNames.map((n) => `#${n}`)
+                    : templateTarget !== undefined ? [...context.templateIds].map((id) => `template:${id}`)
+                        : ['next-page'];
+                issues.push({ kind: 'overflowTargetUnknown', path: f.fieldPaths['overflow/continueIn'] ?? `${f.configPath}/overflow/continueIn`, value: continueIn, used: '', known });
+                f.overflow = { ...f.overflow };
+                delete f.overflow.continueIn;
+            }
+        }
+    }
+    const byName = new Map(frames.map((f) => [f.name, f]));
+    for (;;) {
+        const edges = new Map();
+        for (const f of frames) {
+            const out = [];
+            if (f.next !== undefined)
+                out.push(f.next);
+            const target = continueInFrame(f.overflow.continueIn);
+            if (target !== undefined)
+                out.push(target);
+            edges.set(f.name, out);
+        }
+        const loop = findLoop(frameNames, edges);
+        if (!loop)
+            break;
+        // The link that closes the loop: from its last frame back to its first.
+        const from = byName.get(loop[loop.length - 2]);
+        const to = loop[loop.length - 1];
+        if (from.next === to) {
+            issues.push({ kind: 'frameChainLoop', path: from.fieldPaths.next ?? `${from.configPath}/next`, value: loop.join(' → '), used: '' });
+            delete from.next;
+        }
+        else {
+            issues.push({ kind: 'frameChainLoop', path: from.fieldPaths['overflow/continueIn'] ?? `${from.configPath}/overflow/continueIn`, value: loop.join(' → '), used: '' });
+            from.overflow = { ...from.overflow };
+            delete from.overflow.continueIn;
+        }
+    }
+    if (overflowTemplate && overflowTemplate.value !== undefined) {
+        const id = overflowTemplate.value;
+        if (typeof id === 'string' && context.templateIds.has(id))
+            return { overflowTemplate: id };
+        issues.push({ kind: 'overflowTargetUnknown', path: overflowTemplate.path, value: String(id), used: '', known: [...context.templateIds] });
+    }
+    return {};
+}
+/** The usable template ids: the first of each id, chains that do not loop. */
+function usableIds(templates) {
+    const ids = new Set();
+    const byId = idTable(templates);
+    for (const [id, index] of byId)
+        if (templateChain(templates, index, byId))
+            ids.add(id);
+    return ids;
+}
+/**
+ * Resolve the template at `index` of `templates` (see
+ * {@link resolvePageTemplate}), with the issues met on the way. `prefix`
+ * is the JSON pointer of the list (`/pageTemplates`).
+ * @internal the validator's; hosts call `resolvePageTemplate`.
+ */
+export function resolveTemplateAt(templates, index, options = {}) {
+    const chain = templateChain(templates, index);
+    const own = templates[index];
+    if (!chain || !isRecord(own) || typeof own.id !== 'string')
+        return undefined;
+    const prefix = options.prefix ?? '/pageTemplates';
+    const issues = [];
+    const merged = { fields: {}, fieldPaths: {}, frames: [], groups: [], elements: [] };
+    const inherited = {};
+    for (const i of [...chain].reverse()) {
+        const t = templates[i];
+        mergePatch(merged, t, `${prefix}/${i}`, issues);
+        for (const key of INHERITED_KEYS)
+            if (t[key] !== undefined)
+                inherited[key] = t[key];
+    }
+    const spread = inherited.spread === true;
+    const side = spread || options.spread ? undefined : options.parity;
+    let variant;
+    if (side) {
+        for (const i of [...chain].reverse()) {
+            const patch = templates[i].variants?.[side];
+            if (isRecord(patch)) {
+                mergePatch(merged, patch, `${prefix}/${i}/variants/${side}`, issues);
+                variant = side;
+            }
+        }
+    }
+    const grid = normalizeGrid(merged.fields.grid);
+    const frames = merged.frames.map((e) => normalizeFrame(e.value, grid, { configPath: e.configPath, fieldPaths: e.fieldPaths }));
+    const groups = merged.groups.map((e) => normalizeGroup(e, grid));
+    const settled = settleReferences(frames, groups, merged.elements, { templateIds: usableIds(templates), calloutStyleIds: options.calloutStyleIds }, merged.fields.overflowTemplate !== undefined ? { value: merged.fields.overflowTemplate, path: merged.fieldPaths.overflowTemplate } : undefined, issues);
+    const f = merged.fields;
+    const template = {
+        id: own.id,
+        ...(typeof own.name === 'string' ? { name: own.name } : {}),
+        area: oneOf(TEMPLATE_AREAS, f.area) ? f.area : DEFAULT_PAGE_TEMPLATE.area,
+        ...(grid ? { grid } : {}),
+        frames,
+        groups,
+        decoration: { elements: merged.elements.map((e) => e.value) },
+        decorationPaths: merged.elements.map((e) => e.configPath),
+        ...(f.header === false || isRecord(f.header) ? { header: f.header } : {}),
+        ...(f.footer === false || isRecord(f.footer) ? { footer: f.footer } : {}),
+        ...settled,
+        ...(typeof f.bodyStyle === 'string' ? { bodyStyle: f.bodyStyle } : {}),
+        ...(typeof f.palette === 'string' ? { palette: f.palette } : {}),
+        spread,
+        gutter: dim(inherited.gutter) ?? DEFAULT_PAGE_TEMPLATE.gutter,
+        role: typeof inherited.role === 'string' && inherited.role !== '' ? inherited.role : DEFAULT_PAGE_TEMPLATE.role,
+        ...(variant ? { variant } : {}),
+        chain: chain.map((i) => templates[i].id),
+        configPath: `${prefix}/${index}`,
+    };
+    return { template, issues };
+}
+const resolvedCache = new WeakMap();
+/**
+ * The template `id` of `config.pageTemplates`, ready to lay out: its
+ * `extends` chain merged (scalar fields replace, `grid` merges key by key,
+ * frames and groups merge by `name` with `remove: true` dropping one,
+ * decoration elements merge by `id`), then the variant of the page's side
+ * (`options.parity`; none on a spread), then every default filled in and
+ * every reference settled (see `validatePageTemplates` for what is fixed
+ * and reported). Undefined when no template has that id, or its chain
+ * loops. The first template with an id is the one it means.
+ *
+ * Memoised per `pageTemplates` array (the resolved configuration holds a
+ * copy of its own): treat the result as read-only, and give a changed list
+ * as a new array.
+ */
+export function resolvePageTemplate(config, id, options = {}) {
+    const templates = config?.pageTemplates;
+    if (!Array.isArray(templates))
+        return undefined;
+    const index = templateIndex(templates, id);
+    if (index === undefined)
+        return undefined;
+    const styleIds = config?.calloutStyles ? config.calloutStyles.map((s) => s.id).join('\u0000') : '';
+    const key = `${index}|${options.parity ?? ''}|${options.spread ? 1 : 0}|${config?.calloutStyles ? 1 : 0}|${styleIds}`;
+    let cache = resolvedCache.get(templates);
+    if (!cache) {
+        cache = new Map();
+        resolvedCache.set(templates, cache);
+    }
+    if (cache.has(key))
+        return cache.get(key) ?? undefined;
+    const calloutStyleIds = config?.calloutStyles ? new Set(config.calloutStyles.map((s) => s.id)) : undefined;
+    const result = resolveTemplateAt(templates, index, { ...options, calloutStyleIds })?.template;
+    cache.set(key, result ?? null);
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Label styles
+// ---------------------------------------------------------------------------
+/** The label styles with their defaults filled in. */
+export function resolveLabelStyles(styles) {
+    if (!Array.isArray(styles))
+        return [];
+    return styles.filter((s) => isRecord(s) && typeof s.id === 'string').map((s) => ({
+        ...s,
+        fontStyle: oneOf(LABEL_FONT_STYLES, s.fontStyle) ? s.fontStyle : DEFAULT_LABEL_STYLE.fontStyle,
+        textTransform: oneOf(LABEL_TEXT_TRANSFORMS, s.textTransform) ? s.textTransform : DEFAULT_LABEL_STYLE.textTransform,
+        minScale: scale(s.minScale, DEFAULT_LABEL_STYLE.minScale),
+    }));
+}
+// ---------------------------------------------------------------------------
+// Stripping defaults (what the Sandbox saves)
+// ---------------------------------------------------------------------------
+/** A deep copy of `value` with the keys set to `undefined` left out. */
+function withoutUndefined(value) {
+    if (Array.isArray(value))
+        return value.map(withoutUndefined);
+    if (!isRecord(value))
+        return value;
+    const out = {};
+    for (const [k, v] of Object.entries(value))
+        if (v !== undefined)
+            out[k] = withoutUndefined(v);
+    return out;
+}
+/**
+ * The page templates as stored. Every field is kept as written, a value
+ * equal to its default included: in a template that `extends` another, or
+ * in a variant, it overrides the parent's, so it is never a restated
+ * default. Keys set to `undefined` are left out, and an empty list is no
+ * list.
+ */
+export function stripPageTemplatesDefaults(templates) {
+    if (!Array.isArray(templates) || templates.length === 0)
+        return undefined;
+    return withoutUndefined([...templates]);
+}
+/** The label styles without the values that restate a default (and `name`
+ *  equal to `id`); an empty list is no list. */
+export function stripLabelStylesDefaults(styles) {
+    if (!Array.isArray(styles) || styles.length === 0)
+        return undefined;
+    return styles.map((s) => {
+        const out = withoutUndefined({ ...s });
+        if (out.name === out.id)
+            delete out.name;
+        if (out.fontStyle === DEFAULT_LABEL_STYLE.fontStyle)
+            delete out.fontStyle;
+        if (out.textTransform === DEFAULT_LABEL_STYLE.textTransform)
+            delete out.textTransform;
+        if (out.minScale === DEFAULT_LABEL_STYLE.minScale)
+            delete out.minScale;
+        return out;
+    });
+}
+//# sourceMappingURL=templates.js.map