@texuli/deck 0.0.0-stage → 0.5.0

package/dist/model/steps/slide-steps.js

@@ -0,0 +1,256 @@
+/**
+ * Steps and fragments of one slide (model-v2 §3.7, ported from Protoyard's
+ * `motion/steps.ts` and extended with v1's list `items` kind).
+ *
+ * A slide starts at step 0 (its initial state) and advances one step per
+ * "next". Authors give fragments an authored step number (0 to
+ * `MAX_AUTHORED_STEP`); the engine sorts the distinct non-zero numbers and
+ * renumbers them 1, 2, 3…, so gaps ("step": 2 then 5) never cost an empty
+ * click. A fragment at authored step 0 belongs to the initial state.
+ *
+ * Sources, in document order:
+ * - a block or component item with `step` (nested blocks may step too);
+ * - a `list` block with `step`: item *i* enters at `step + i`;
+ * - a `code` block's `highlights` (or a props `{ source, highlights }` code
+ *   object): highlight *i* at `step + i`, `step` defaulting to 0;
+ * - props markers `{ step, fragment | reveal, tone }` anywhere in `props`
+ *   (a marker off the layout's steppable paths still counts, with a
+ *   `step-unrevealed` warning, as in Protoyard); a props object with
+ *   `fragment` or `reveal` but no `step` reveals nothing and is reported as
+ *   the warning `step-missing`;
+ * - `slide.steps` labels, which name steps 1… and may extend the count.
+ * A `custom` slide's props belong to its host component: labels only.
+ *
+ * The input is structural (plain objects, validated or not): anything that is
+ * not a valid step, effect or tone is ignored rather than thrown on.
+ */
+import { createDiagnostic, toJsonPath, } from "../../schema/index.js";
+import { BLOCK_REVEALS, FRAGMENT_EFFECTS, FRAGMENT_TONES, MAX_AUTHORED_STEP, MAX_SLIDE_STEPS, } from "../shared.js";
+/** The legacy block `reveal` vocabulary in fragment terms (`fade` is a plain `in`). */
+export const REVEAL_EFFECT = Object.freeze({
+    fade: 'in',
+    'fade-up': 'fade-up',
+    grow: 'grow',
+    highlight: 'highlight',
+    strike: 'strike',
+});
+/** The step codes this pass reports (model-v2 §3.9 cross-field and lint groups). */
+export const STEP_CODES = Object.freeze({
+    fragmentConflict: 'fragment-conflict',
+    tooManySteps: 'too-many-steps',
+    stepUnrevealed: 'step-unrevealed',
+    stepMissing: 'step-missing',
+});
+/** Nesting guards: well above the model's limits, low enough to stay cheap. */
+const MAX_BLOCK_DEPTH = 32;
+const MAX_PROP_DEPTH = 16;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function validStep(value) {
+    return (typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= MAX_AUTHORED_STEP);
+}
+function isEffect(value) {
+    return typeof value === 'string' && FRAGMENT_EFFECTS.includes(value);
+}
+function isReveal(value) {
+    return typeof value === 'string' && BLOCK_REVEALS.includes(value);
+}
+function isTone(value) {
+    return typeof value === 'string' && FRAGMENT_TONES.includes(value);
+}
+/** `['cards', 2]` → `cards.*`; the props object itself is `''`. */
+export function steppablePattern(path) {
+    return path.map((part) => (typeof part === 'number' ? '*' : part)).join('.');
+}
+class Collector {
+    raw = [];
+    issues = [];
+    base;
+    slideId;
+    constructor(base, slideId) {
+        this.base = base;
+        this.slideId = slideId;
+    }
+    issue(code, message, path, fix, warn = false) {
+        this.issues.push(createDiagnostic(code, message, [...this.base, ...path], {
+            severity: warn ? 'warning' : 'error',
+            fix,
+            ...(this.slideId === undefined ? {} : { slideId: this.slideId }),
+        }));
+    }
+    /** The effect and tone a marker asks for, reporting `fragment` + `reveal` together. */
+    effectOf(fields, path) {
+        if (fields.fragment !== undefined && fields.reveal !== undefined) {
+            this.issue(STEP_CODES.fragmentConflict, 'A step marker sets both "fragment" and "reveal"; "fragment" wins.', [...path, 'reveal'], 'Keep one: "fragment" (the v2 effects) or "reveal" (the legacy block effects).');
+        }
+        if (isEffect(fields.fragment))
+            return fields.fragment;
+        if (isReveal(fields.reveal))
+            return REVEAL_EFFECT[fields.reveal];
+        return 'in';
+    }
+    push(entry) {
+        this.raw.push({ ...entry, order: this.raw.length });
+    }
+}
+function toneOf(fields) {
+    return isTone(fields.tone) ? { tone: fields.tone } : {};
+}
+function fromBlocks(list, path, depth, out) {
+    if (!Array.isArray(list) || depth > MAX_BLOCK_DEPTH)
+        return;
+    list.forEach((value, i) => {
+        if (isRecord(value))
+            fromBlock(value, [...path, i], depth, out);
+    });
+}
+function fromBlock(block, path, depth, out) {
+    const blockId = typeof block.id === 'string' ? { blockId: block.id } : {};
+    const tone = toneOf(block);
+    const stepped = validStep(block.step);
+    const effect = out.effectOf(block, path);
+    const base = stepped ? block.step : 0;
+    if (stepped)
+        out.push({ kind: 'block', path, authored: base, effect, ...tone, ...blockId });
+    if (block.type === 'list' && stepped && Array.isArray(block.items)) {
+        block.items.forEach((_, i) => {
+            out.push({
+                kind: 'item',
+                path: [...path, 'items', i],
+                authored: base + i,
+                effect,
+                ...tone,
+                ...blockId,
+                item: i,
+            });
+        });
+    }
+    if (block.type === 'code')
+        fromHighlights(block.highlights, base, path, tone, blockId, out);
+    // Nested blocks may step (Protoyard); a component item's props are its own.
+    if (block.type === 'component')
+        return;
+    fromBlocks(block.blocks, [...path, 'blocks'], depth + 1, out);
+    fromBlocks(block.children, [...path, 'children'], depth + 1, out);
+    if (Array.isArray(block.columns)) {
+        block.columns.forEach((column, c) => {
+            fromBlocks(column, [...path, 'columns', c], depth + 1, out);
+        });
+    }
+    if (Array.isArray(block.panels)) {
+        block.panels.forEach((panel, p) => {
+            if (isRecord(panel))
+                fromBlocks(panel.blocks, [...path, 'panels', p, 'blocks'], depth + 1, out);
+        });
+    }
+}
+function fromHighlights(highlights, base, path, tone, blockId, out) {
+    if (!Array.isArray(highlights))
+        return;
+    highlights.forEach((lines, i) => {
+        if (typeof lines !== 'string')
+            return;
+        out.push({
+            kind: 'highlight',
+            path: [...path, 'highlights', i],
+            authored: base + i,
+            effect: 'highlight',
+            ...tone,
+            ...blockId,
+            lines,
+        });
+    });
+}
+function fromProps(value, path, depth, walk) {
+    if (depth > MAX_PROP_DEPTH || value === null || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        value.forEach((item, i) => {
+            fromProps(item, [...path, i], depth + 1, walk);
+        });
+        return;
+    }
+    const record = value;
+    const stepped = validStep(record.step);
+    const base = stepped ? record.step : 0;
+    // A props code object (`{ source, highlights }`, as in code-with-callout).
+    if (typeof record.source === 'string' && Array.isArray(record.highlights)) {
+        fromHighlights(record.highlights, base, path, toneOf(record), {}, walk.out);
+    }
+    if (record.step === undefined && (record.fragment !== undefined || record.reveal !== undefined)) {
+        const field = record.fragment !== undefined ? 'fragment' : 'reveal';
+        walk.out.issue(STEP_CODES.stepMissing, `This marker sets "${field}" but no "step", so it is ignored and never reveals.`, path, `Add "step": 1 (or the step it should enter on), or remove "${field}".`, true);
+    }
+    if (stepped) {
+        const effect = walk.out.effectOf(record, path);
+        walk.out.push({ kind: 'prop', path, authored: base, effect, ...toneOf(record) });
+        const relative = path.slice(1);
+        if (walk.steppable && !walk.steppable.has(steppablePattern(relative))) {
+            const allowed = [...walk.steppable].map((p) => (p === '' ? '(props)' : p)).join(', ');
+            walk.out.issue(STEP_CODES.stepUnrevealed, 'This step marker counts as a step, but the layout reveals nothing at this path.', path, allowed
+                ? `Move the marker to a steppable path: ${allowed}.`
+                : 'This layout has no steppable props; remove the marker.', true);
+        }
+    }
+    for (const key of Object.keys(record)) {
+        if (key === 'step' || key === 'fragment' || key === 'reveal' || key === 'tone')
+            continue;
+        fromProps(record[key], [...path, key], depth + 1, walk);
+    }
+}
+/** Derives the ordered, densely numbered steps of a slide. Never throws. */
+export function slideSteps(slide, options = {}) {
+    const slideId = typeof slide?.id === 'string' ? slide.id : undefined;
+    const out = new Collector(options.path ?? [], slideId);
+    if (isRecord(slide)) {
+        if (Array.isArray(slide.blocks))
+            fromBlocks(slide.blocks, ['blocks'], 0, out);
+        if (slide.layout !== 'custom' && slide.props !== undefined) {
+            const steppable = options.steppablePaths ? new Set(options.steppablePaths) : null;
+            fromProps(slide.props, ['props'], 0, { steppable, out });
+        }
+    }
+    const ordered = [...out.raw].sort((a, b) => a.authored - b.authored || a.order - b.order);
+    const distinct = [...new Set(ordered.map((r) => r.authored).filter((n) => n > 0))];
+    if (distinct.length > MAX_SLIDE_STEPS) {
+        const first = ordered.find((r) => r.authored === distinct[MAX_SLIDE_STEPS]);
+        out.issue(STEP_CODES.tooManySteps, `The slide has ${distinct.length} distinct steps; at most ${MAX_SLIDE_STEPS} are allowed (the rest play on step ${MAX_SLIDE_STEPS}).`, first ? first.path : [], 'Group fragments onto shared steps, or split the slide.');
+    }
+    const dense = new Map(distinct.map((n, i) => [n, Math.min(i + 1, MAX_SLIDE_STEPS)]));
+    const labels = Array.isArray(slide?.steps) ? slide.steps : [];
+    const count = Math.min(MAX_SLIDE_STEPS, Math.max(Math.min(distinct.length, MAX_SLIDE_STEPS), labels.length));
+    const steps = Array.from({ length: count + 1 }, (_, index) => {
+        const label = index > 0 ? labels[index - 1] : undefined;
+        return { index, ...(typeof label === 'string' ? { label } : {}), fragments: [] };
+    });
+    for (const r of ordered) {
+        const step = r.authored === 0 ? 0 : dense.get(r.authored);
+        const fragment = {
+            kind: r.kind,
+            path: r.path,
+            jsonPath: toJsonPath(r.path),
+            effect: r.effect,
+            step,
+            authored: r.authored,
+        };
+        if (r.tone !== undefined)
+            fragment.tone = r.tone;
+        if (r.blockId !== undefined)
+            fragment.blockId = r.blockId;
+        if (r.item !== undefined)
+            fragment.item = r.item;
+        if (r.lines !== undefined)
+            fragment.lines = r.lines;
+        steps[step].fragments.push(fragment);
+    }
+    return { count, initial: 0, steps, issues: out.issues };
+}
+/** How many "next" presses a slide takes before the deck moves on. */
+export function slideStepCount(slide, options = {}) {
+    return slideSteps(slide, options).count;
+}
+/** Every fragment of a slide, initial state first, in step order. */
+export function slideFragments(steps) {
+    return steps.steps.flatMap((step) => step.fragments);
+}

package/dist/model/style/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Deck style (model v2 §3.1, §3.8): the `DeckStyle` schema and defaults,
+ * theme references, and the pure resolver to `--tx-deck-*` CSS variables.
+ * Theme data itself is resolved by the stage with `@texuli/tokens`.
+ */
+export { DECK_ASPECT_RATIOS, DECK_DENSITY_SCALE, DECK_RADIUS_VALUES, DECK_REDUCED_MOTION_MS, DECK_SUBTLE_FACTOR, DECK_TRANSITION_CAP_MS, DECK_TRANSITION_MS, DECK_VAR_PREFIX, type DeckCssVar, type DeckResolvedTransition, type DeckStyleResolution, type ResolveDeckStyleOptions, type ResolvedDeckStyle, resolveDeckStyle, resolveDeckTransition, STYLE_CODES, } from './resolve.js';
+export { DECK_DENSITIES, DECK_MOTIONS, DECK_PROGRESS, DECK_RADII, DECK_STYLE_DEFAULTS, type DeckDensity, type DeckMotion, type DeckProgress, type DeckRadius, type DeckStyle, deckStyle, logoSrc, } from './schema.js';
+export { DECK_THEME_MODES, DECK_THEME_SEED_MAX, type DeckResolvedThemeMode, type DeckThemeInput, type DeckThemeMode, type DeckThemeReference, deckThemeObject, deckThemeReference, EMBEDDED_THEME_LIMITS, normalizeThemeReference, resolveThemeMode, STYLE_SLUG_PATTERN, styleSlug, THEME_CODES, } from './theme.js';

package/dist/model/style/index.js

@@ -0,0 +1,8 @@
+/**
+ * Deck style (model v2 §3.1, §3.8): the `DeckStyle` schema and defaults,
+ * theme references, and the pure resolver to `--tx-deck-*` CSS variables.
+ * Theme data itself is resolved by the stage with `@texuli/tokens`.
+ */
+export { DECK_ASPECT_RATIOS, DECK_DENSITY_SCALE, DECK_RADIUS_VALUES, DECK_REDUCED_MOTION_MS, DECK_SUBTLE_FACTOR, DECK_TRANSITION_CAP_MS, DECK_TRANSITION_MS, DECK_VAR_PREFIX, resolveDeckStyle, resolveDeckTransition, STYLE_CODES, } from "./resolve.js";
+export { DECK_DENSITIES, DECK_MOTIONS, DECK_PROGRESS, DECK_RADII, DECK_STYLE_DEFAULTS, deckStyle, logoSrc, } from "./schema.js";
+export { DECK_THEME_MODES, DECK_THEME_SEED_MAX, deckThemeObject, deckThemeReference, EMBEDDED_THEME_LIMITS, normalizeThemeReference, resolveThemeMode, STYLE_SLUG_PATTERN, styleSlug, THEME_CODES, } from "./theme.js";

package/dist/model/style/resolve.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Resolve a deck style (plus an optional slide override) into a complete
+ * style with every default applied, a normalized theme reference, the
+ * transition the stage plays, and the `--tx-deck-*` CSS variables. Theme and
+ * font resolution need token data, so they happen in the stage; here the
+ * caller may pass the known ids to get `unknown-*` warnings.
+ *
+ * Pure and deterministic. It never throws: invalid fields are reported in
+ * `issues` and fall back to their defaults; author strings (footer, logo)
+ * never reach a CSS variable.
+ */
+import { type DeckDiagnostic, type PathSegment } from '../../schema/index.js';
+import { type DeckAspect, type DeckTransition } from '../shared.js';
+import { DECK_STYLE_DEFAULTS, type DeckDensity, type DeckMotion, type DeckRadius, type DeckStyle } from './schema.js';
+import { type DeckResolvedThemeMode, type DeckThemeReference } from './theme.js';
+export declare const STYLE_CODES: Readonly<{
+    readonly unknownTheme: "unknown-theme";
+    readonly unknownFontPair: "unknown-font-pair";
+    readonly unknownCodeTheme: "unknown-code-theme";
+}>;
+/** Every CSS variable the style sets starts with this prefix. */
+export declare const DECK_VAR_PREFIX = "--tx-deck-";
+export type DeckCssVar = `--tx-deck-${string}`;
+/** Density multipliers (inside `@texuli/tokens` `DENSITY_MIN`..`DENSITY_MAX`, 0.75..1.25). */
+export declare const DECK_DENSITY_SCALE: Readonly<Record<DeckDensity, number>>;
+export declare const DECK_RADIUS_VALUES: Readonly<Record<DeckRadius, string>>;
+export declare const DECK_ASPECT_RATIOS: Readonly<Record<DeckAspect, string>>;
+/** Full-motion durations in milliseconds (the motion module's table). */
+export declare const DECK_TRANSITION_MS: Readonly<Record<DeckTransition, number>>;
+/** `subtle` motion scales durations by this factor (and plays `zoom` as `fade`). */
+export declare const DECK_SUBTLE_FACTOR = 0.6;
+/** Under reduced motion every transition is a short fade. */
+export declare const DECK_REDUCED_MOTION_MS = 150;
+/** No transition runs longer than this. */
+export declare const DECK_TRANSITION_CAP_MS = 400;
+export interface DeckResolvedTransition {
+    name: DeckTransition;
+    durationMs: number;
+}
+/**
+ * The transition the stage plays: `none` motion or transition → none;
+ * reduced motion → a 150 ms fade; `subtle` → ×0.6 and zoom → fade; capped at
+ * 400 ms. Delegates to the one resolver, `resolveSlideTransition`.
+ */
+export declare function resolveDeckTransition(transition: DeckTransition, motion: DeckMotion, reducedMotion?: boolean): DeckResolvedTransition;
+type Defaulted = typeof DECK_STYLE_DEFAULTS;
+/** A style with every default applied and the theme in its object form. */
+export type ResolvedDeckStyle = Omit<DeckStyle, 'theme' | keyof Defaulted> & {
+    -readonly [K in keyof Defaulted]-?: NonNullable<DeckStyle[K]>;
+} & {
+    theme?: DeckThemeReference;
+};
+export interface ResolveDeckStyleOptions {
+    /** Slide-level fields (`theme`, `background`, `transition`, …) that win over the deck's. */
+    override?: DeckStyle;
+    /** The host's reduced-motion preference: lowers `motion`, never raises it. */
+    reducedMotion?: boolean;
+    /** The host's mode, used when the theme names none (or `system`). Default `light`. */
+    hostMode?: DeckResolvedThemeMode;
+    /** Known catalog theme ids; when given, an unknown one warns and falls back to the host default. */
+    knownThemes?: readonly string[];
+    /** Known font pairing ids; when given, an unknown one warns and uses the theme font. */
+    knownFontPairs?: readonly string[];
+    /** Known code highlight themes; when given, an unknown one warns and uses the default. */
+    knownCodeThemes?: readonly string[];
+    /** A prefix for issue paths, e.g. `['style']`. */
+    path?: readonly PathSegment[];
+}
+export interface DeckStyleResolution {
+    style: ResolvedDeckStyle;
+    /** The concrete mode: theme reference, else host, else `light`. */
+    mode: DeckResolvedThemeMode;
+    /** The motion actually allowed (reduced motion lowers `full` to `subtle`). */
+    motion: DeckMotion;
+    transition: DeckResolvedTransition;
+    /** The fixed virtual canvas for the aspect, in CSS pixels. */
+    canvas: {
+        width: number;
+        height: number;
+    };
+    cssVars: Record<DeckCssVar, string>;
+    /** Invalid fields (errors, recovered with the default) and unknown ids (warnings). */
+    issues: DeckDiagnostic[];
+}
+/** Resolve `style` (and `options.override`) into defaults, transition and `--tx-deck-*` variables. */
+export declare function resolveDeckStyle(style?: unknown, options?: ResolveDeckStyleOptions): DeckStyleResolution;
+export {};

package/dist/model/style/resolve.js

@@ -0,0 +1,174 @@
+/**
+ * Resolve a deck style (plus an optional slide override) into a complete
+ * style with every default applied, a normalized theme reference, the
+ * transition the stage plays, and the `--tx-deck-*` CSS variables. Theme and
+ * font resolution need token data, so they happen in the stage; here the
+ * caller may pass the known ids to get `unknown-*` warnings.
+ *
+ * Pure and deterministic. It never throws: invalid fields are reported in
+ * `issues` and fall back to their defaults; author strings (footer, logo)
+ * never reach a CSS variable.
+ */
+import { createDiagnostic, validate, } from "../../schema/index.js";
+import { isDeckBackgroundPreset } from "../backgrounds/schema.js";
+import { MAX_MOTION_MS, REDUCED_FADE_MS, resolveSlideTransition, SUBTLE_SCALE, TRANSITION_MS, } from "../motion/transition.js";
+import { DECK_CANVAS } from "../shared.js";
+import { DECK_STYLE_DEFAULTS, deckStyle, } from "./schema.js";
+import { normalizeThemeReference, resolveThemeMode, THEME_CODES, } from "./theme.js";
+export const STYLE_CODES = Object.freeze({
+    unknownTheme: THEME_CODES.unknownTheme,
+    unknownFontPair: 'unknown-font-pair',
+    unknownCodeTheme: 'unknown-code-theme',
+});
+/** Every CSS variable the style sets starts with this prefix. */
+export const DECK_VAR_PREFIX = '--tx-deck-';
+/** Density multipliers (inside `@texuli/tokens` `DENSITY_MIN`..`DENSITY_MAX`, 0.75..1.25). */
+export const DECK_DENSITY_SCALE = Object.freeze({
+    compact: 0.875,
+    default: 1,
+    comfortable: 1.125,
+    spacious: 1.25,
+});
+export const DECK_RADIUS_VALUES = Object.freeze({
+    none: '0',
+    small: '0.25rem',
+    medium: '0.625rem',
+    large: '1rem',
+    full: '9999px',
+});
+export const DECK_ASPECT_RATIOS = Object.freeze({
+    '16:9': '16 / 9',
+    '4:3': '4 / 3',
+    '9:16': '9 / 16',
+    '1:1': '1 / 1',
+});
+/** Full-motion durations in milliseconds (the motion module's table). */
+export const DECK_TRANSITION_MS = TRANSITION_MS;
+/** `subtle` motion scales durations by this factor (and plays `zoom` as `fade`). */
+export const DECK_SUBTLE_FACTOR = SUBTLE_SCALE;
+/** Under reduced motion every transition is a short fade. */
+export const DECK_REDUCED_MOTION_MS = REDUCED_FADE_MS;
+/** No transition runs longer than this. */
+export const DECK_TRANSITION_CAP_MS = MAX_MOTION_MS;
+/**
+ * The transition the stage plays: `none` motion or transition → none;
+ * reduced motion → a 150 ms fade; `subtle` → ×0.6 and zoom → fade; capped at
+ * 400 ms. Delegates to the one resolver, `resolveSlideTransition`.
+ */
+export function resolveDeckTransition(transition, motion, reducedMotion = false) {
+    const resolved = resolveSlideTransition({ slide: { transition }, motion, reducedMotion });
+    return { name: resolved.name, durationMs: resolved.durationMs };
+}
+const SHAPE = deckStyle.shape;
+/** Validate each field on its own so one bad field never discards the rest. */
+function salvage(input, path, issues) {
+    if (input === undefined)
+        return {};
+    const whole = validate(deckStyle, input, { path, maxIssues: 50 });
+    issues.push(...whole.issues);
+    if (whole.ok)
+        return whole.value;
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        return {};
+    const out = {};
+    for (const key of Object.keys(SHAPE)) {
+        if (!Object.hasOwn(input, key))
+            continue;
+        let value;
+        try {
+            value = input[key];
+        }
+        catch {
+            continue;
+        }
+        const field = validate(SHAPE[key], value, { maxIssues: 1 });
+        if (field.ok && field.value !== undefined)
+            out[key] = field.value;
+    }
+    return out;
+}
+function knownOr(value, known, code, label, path, issues) {
+    if (value === undefined || known === undefined || known.includes(value))
+        return value;
+    issues.push(createDiagnostic(code, `Unknown ${label} "${value}"; using the default.`, path, {
+        severity: 'warning',
+        fix: `Use one of: ${known
+            .slice(0, 20)
+            .map((id) => JSON.stringify(id))
+            .join(', ')}${known.length > 20 ? ', …' : ''}.`,
+    }));
+    return undefined;
+}
+/** Resolve `style` (and `options.override`) into defaults, transition and `--tx-deck-*` variables. */
+export function resolveDeckStyle(style, options = {}) {
+    const path = [...(options.path ?? [])];
+    const issues = [];
+    const base = salvage(style, path, issues);
+    const override = salvage(options.override, path, issues);
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        if (value !== undefined)
+            merged[key] = value;
+    }
+    let theme = normalizeThemeReference(merged.theme);
+    if (theme?.kind === 'catalog' && options.knownThemes !== undefined) {
+        const id = knownOr(theme.id, options.knownThemes, STYLE_CODES.unknownTheme, 'theme', [...path, 'theme'], issues);
+        if (id === undefined)
+            theme = undefined;
+    }
+    const fontPair = knownOr(merged.fontPair, options.knownFontPairs, STYLE_CODES.unknownFontPair, 'font pairing', [...path, 'fontPair'], issues);
+    const codeTheme = knownOr(merged.codeTheme, options.knownCodeThemes, STYLE_CODES.unknownCodeTheme, 'code theme', [...path, 'codeTheme'], issues);
+    const resolved = {
+        aspect: merged.aspect ?? DECK_STYLE_DEFAULTS.aspect,
+        density: merged.density ?? DECK_STYLE_DEFAULTS.density,
+        radius: merged.radius ?? DECK_STYLE_DEFAULTS.radius,
+        motion: merged.motion ?? DECK_STYLE_DEFAULTS.motion,
+        transition: merged.transition ?? DECK_STYLE_DEFAULTS.transition,
+        background: merged.background ?? DECK_STYLE_DEFAULTS.background,
+        slideNumbers: merged.slideNumbers ?? DECK_STYLE_DEFAULTS.slideNumbers,
+        progress: merged.progress ?? DECK_STYLE_DEFAULTS.progress,
+        math: merged.math ?? DECK_STYLE_DEFAULTS.math,
+    };
+    if (theme !== undefined)
+        resolved.theme = theme;
+    if (fontPair !== undefined)
+        resolved.fontPair = fontPair;
+    if (codeTheme !== undefined)
+        resolved.codeTheme = codeTheme;
+    if (merged.logo !== undefined)
+        resolved.logo = merged.logo;
+    if (merged.footer !== undefined)
+        resolved.footer = merged.footer;
+    const reduced = options.reducedMotion === true;
+    const motion = reduced && resolved.motion === 'full' ? 'subtle' : resolved.motion;
+    const transition = resolveDeckTransition(resolved.transition, resolved.motion, reduced);
+    const canvas = { ...DECK_CANVAS[resolved.aspect] };
+    const background = resolved.background;
+    const cssVars = {
+        '--tx-deck-aspect-ratio': DECK_ASPECT_RATIOS[resolved.aspect],
+        '--tx-deck-canvas-width': `${canvas.width}px`,
+        '--tx-deck-canvas-height': `${canvas.height}px`,
+        '--tx-deck-density': String(DECK_DENSITY_SCALE[resolved.density]),
+        '--tx-deck-radius': DECK_RADIUS_VALUES[resolved.radius],
+        '--tx-deck-motion': motion,
+        '--tx-deck-transition': transition.name,
+        '--tx-deck-transition-duration': `${transition.durationMs}ms`,
+        // A preset id or the spec kind: enum keywords only, never an author string.
+        '--tx-deck-background': isDeckBackgroundPreset(background)
+            ? background
+            : typeof background === 'object'
+                ? background.kind
+                : DECK_STYLE_DEFAULTS.background,
+        '--tx-deck-progress': resolved.progress,
+        '--tx-deck-slide-numbers': resolved.slideNumbers ? '1' : '0',
+    };
+    return {
+        style: resolved,
+        mode: resolveThemeMode(theme, options.hostMode),
+        motion,
+        transition,
+        canvas,
+        cssVars,
+        issues,
+    };
+}

package/dist/model/style/schema.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `DeckStyle` (model v2 §3.1, §3.2): every field is optional. The schema
+ * keeps the authored document as written (no defaults injected, so text
+ * twins, patches and migration stay faithful); `DECK_STYLE_DEFAULTS` holds
+ * the documented defaults and `resolveDeckStyle` applies them.
+ */
+import { type Infer } from '../../schema/index.js';
+export declare const DECK_DENSITIES: readonly ["compact", "default", "comfortable", "spacious"];
+export type DeckDensity = (typeof DECK_DENSITIES)[number];
+export declare const DECK_RADII: readonly ["none", "small", "medium", "large", "full"];
+export type DeckRadius = (typeof DECK_RADII)[number];
+/** A ceiling: the host's reduced-motion preference only lowers it. */
+export declare const DECK_MOTIONS: readonly ["full", "subtle", "none"];
+export type DeckMotion = (typeof DECK_MOTIONS)[number];
+export declare const DECK_PROGRESS: readonly ["none", "top", "bottom"];
+export type DeckProgress = (typeof DECK_PROGRESS)[number];
+/** `style.logo`: media syntax (an image), at most 512 code points. */
+export declare const logoSrc: import("../../index.js").StringSchema;
+export declare const deckStyle: import("../../index.js").ObjectSchema<{
+    readonly theme: import("../../index.js").OptionalSchema<import("../../index.js").UnionSchema<readonly [import("../../index.js").StringSchema, import("../../index.js").UnionSchema<readonly [import("../../index.js").ObjectSchema<{
+        readonly kind: import("../../index.js").LiteralSchema<"catalog">;
+        readonly id: import("../../index.js").StringSchema;
+        readonly mode: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"dark" | "light" | "high-contrast" | "system">, false>;
+    }>, import("../../index.js").ObjectSchema<{
+        readonly kind: import("../../index.js").LiteralSchema<"embedded">;
+        readonly theme: import("../../index.js").RefineSchema<import("../../index.js").JsonValueSchema>;
+        readonly mode: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"dark" | "light" | "high-contrast" | "system">, false>;
+    }>, import("../../index.js").ObjectSchema<{
+        readonly kind: import("../../index.js").LiteralSchema<"seed">;
+        readonly seed: import("../../index.js").NumberSchema;
+        readonly mode: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"dark" | "light" | "high-contrast" | "system">, false>;
+    }>]>]>, false>;
+    readonly fontPair: import("../../index.js").OptionalSchema<import("../../index.js").StringSchema, false>;
+    readonly aspect: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"16:9" | "4:3" | "9:16" | "1:1">, false>;
+    readonly density: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"compact" | "default" | "comfortable" | "spacious">, false>;
+    readonly radius: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"none" | "small" | "medium" | "large" | "full">, false>;
+    readonly motion: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"none" | "full" | "subtle">, false>;
+    readonly transition: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"fade-up" | "fade" | "none" | "slide" | "zoom" | "morph">, false>;
+    readonly background: import("../../index.js").OptionalSchema<import("../../index.js").UnionSchema<readonly [import("../../index.js").EnumSchema<"solid-color" | "solid-surface" | "solid-primary" | "solid-accent" | "solid-muted" | "solid-inverse" | "gradient-brand" | "gradient-dusk" | "gradient-dawn" | "gradient-forest" | "gradient-mist" | "pattern-dots" | "pattern-grid">, import("../../index.js").UnionSchema<readonly [import("../../index.js").RefineSchema<import("../../index.js").ObjectSchema<{
+        readonly kind: import("../../index.js").LiteralSchema<"solid">;
+        readonly token: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"accent" | "background" | "surface" | "primary" | "muted" | "inverse">, false>;
+        readonly color: import("../../index.js").OptionalSchema<import("../../index.js").StringSchema, false>;
+    }>>, import("../../index.js").ObjectSchema<{
+        readonly kind: import("../../index.js").LiteralSchema<"gradient">;
+        readonly gradient: import("../../index.js").EnumSchema<"brand" | "dusk" | "dawn" | "forest" | "mist">;
+        readonly angle: import("../../index.js").OptionalSchema<import("../../index.js").NumberSchema, false>;
+    }>, import("../../index.js").ObjectSchema<{
+        readonly kind: import("../../index.js").LiteralSchema<"pattern">;
+        readonly pattern: import("../../index.js").EnumSchema<"dots" | "grid">;
+    }>, import("../../index.js").RefineSchema<import("../../index.js").ObjectSchema<{
+        readonly tone: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"dark" | "light">, false>;
+        readonly overlay: import("../../index.js").OptionalSchema<import("../../index.js").NumberSchema, false>;
+        readonly position: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"center" | "top" | "bottom" | "left" | "right">, false>;
+        readonly kind: import("../../index.js").EnumSchema<"image" | "image-full">;
+        readonly src: import("../../index.js").StringSchema;
+        readonly alt: import("../../index.js").OptionalSchema<import("../../index.js").StringSchema, false>;
+        readonly fit: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"cover" | "contain">, false>;
+    }>>, import("../../index.js").RefineSchema<import("../../index.js").ObjectSchema<{
+        readonly tone: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"dark" | "light">, false>;
+        readonly overlay: import("../../index.js").OptionalSchema<import("../../index.js").NumberSchema, false>;
+        readonly position: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"center" | "top" | "bottom" | "left" | "right">, false>;
+        readonly kind: import("../../index.js").EnumSchema<"video" | "video-full">;
+        readonly src: import("../../index.js").StringSchema;
+        readonly poster: import("../../index.js").OptionalSchema<import("../../index.js").StringSchema, false>;
+    }>>]>]>, false>;
+    readonly logo: import("../../index.js").OptionalSchema<import("../../index.js").StringSchema, false>;
+    readonly footer: import("../../index.js").OptionalSchema<import("../../index.js").StringSchema, false>;
+    readonly slideNumbers: import("../../index.js").OptionalSchema<import("../../index.js").BooleanSchema, false>;
+    readonly progress: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"none" | "top" | "bottom">, false>;
+    readonly codeTheme: import("../../index.js").OptionalSchema<import("../../index.js").StringSchema, false>;
+    readonly math: import("../../index.js").OptionalSchema<import("../../index.js").BooleanSchema, false>;
+}>;
+export type DeckStyle = Infer<typeof deckStyle>;
+/** The documented defaults for every field that has one. */
+export declare const DECK_STYLE_DEFAULTS: Readonly<{
+    readonly aspect: "16:9";
+    readonly density: "default";
+    readonly radius: "medium";
+    readonly motion: "full";
+    readonly transition: "fade";
+    readonly background: "solid-color";
+    readonly slideNumbers: true;
+    readonly progress: "bottom";
+    readonly math: false;
+}>;