@texuli/deck 0.0.0-stage → 0.5.0

package/dist/model/plain.js

@@ -0,0 +1,275 @@
+/**
+ * A bounded plain-data copy of untrusted input (ported from Protoyard's
+ * `untrusted.ts` sanitizer). Only JSON data survives: own enumerable data
+ * properties of plain objects and dense arrays, strings, finite numbers,
+ * booleans and `null`. Accessors, class instances, functions, symbols,
+ * cycles, prototype keys and anything past the depth or byte budget are
+ * dropped and reported, never followed. Optionally strips characters that
+ * hide or reorder text. Walked with an explicit stack, so hostile nesting
+ * never costs native recursion. Never throws.
+ */
+import { createDiagnostic, UNSAFE_KEYS, } from "../schema/index.js";
+const UNSAFE = new Set(UNSAFE_KEYS);
+/** How many strings get their own `hidden-characters` warning before one summary. */
+const HIDDEN_REPORTS = 20;
+/**
+ * True for a character that can hide or reorder text: C0 and C1 controls
+ * (except tab, LF and CR), U+061C, U+200B, U+200E, U+200F, the bidi
+ * embeddings, overrides and isolates, U+2060 and the byte-order mark. ZWJ
+ * and ZWNJ (U+200C, U+200D) stay: emoji sequences and several scripts need them.
+ */
+function isHidden(code) {
+    return ((code <= 0x1f && code !== 0x09 && code !== 0x0a && code !== 0x0d) ||
+        (code >= 0x7f && code <= 0x9f) ||
+        code === 0x061c ||
+        code === 0x200b ||
+        code === 0x200e ||
+        code === 0x200f ||
+        (code >= 0x202a && code <= 0x202e) ||
+        code === 0x2060 ||
+        (code >= 0x2066 && code <= 0x2069) ||
+        code === 0xfeff);
+}
+/**
+ * Remove hidden characters (see `isHidden`); U+2028 and U+2029 become a
+ * space. Returns the string unchanged (same reference) when nothing is hidden.
+ */
+export function stripHiddenCharacters(value) {
+    let clean = true;
+    for (let i = 0; i < value.length; i++) {
+        const c = value.charCodeAt(i);
+        if (isHidden(c) || c === 0x2028 || c === 0x2029) {
+            clean = false;
+            break;
+        }
+    }
+    if (clean)
+        return value;
+    let out = '';
+    for (let i = 0; i < value.length; i++) {
+        const c = value.charCodeAt(i);
+        if (c === 0x2028 || c === 0x2029)
+            out += ' ';
+        else if (!isHidden(c))
+            out += value[i];
+    }
+    return out;
+}
+/** UTF-8 byte length without allocating. */
+export function utf8Length(value) {
+    let bytes = 0;
+    for (let i = 0; i < value.length; i++) {
+        const c = value.charCodeAt(i);
+        if (c < 0x80)
+            bytes += 1;
+        else if (c < 0x800)
+            bytes += 2;
+        else if (c >= 0xd800 && c <= 0xdbff && i + 1 < value.length) {
+            const next = value.charCodeAt(i + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                bytes += 4;
+                i++;
+            }
+            else
+                bytes += 3;
+        }
+        else
+            bytes += 3;
+    }
+    return bytes;
+}
+function describe(value) {
+    if (typeof value === 'function')
+        return 'a function';
+    if (typeof value === 'symbol')
+        return 'a symbol';
+    if (typeof value === 'bigint')
+        return 'a bigint';
+    if (value === undefined)
+        return 'undefined';
+    return 'a non-plain object';
+}
+/** Copy `input` as plain JSON data; see the module comment for what is dropped. */
+export function copyPlainData(input, options = {}) {
+    const maxDepth = options.maxDepth ?? 64;
+    const maxBytes = options.maxBytes ?? Number.POSITIVE_INFINITY;
+    const maxIssues = options.maxIssues ?? 200;
+    const strip = options.strip === true;
+    const issues = [];
+    let failed = false;
+    let truncated = false;
+    let stopped = false;
+    let bytes = 0;
+    let hiddenReports = 0;
+    let hiddenStrings = 0;
+    const report = (code, message, path, fix, severity = 'error') => {
+        if (severity === 'error')
+            failed = true;
+        if (issues.length >= maxIssues) {
+            truncated = true;
+            return;
+        }
+        issues.push(createDiagnostic(code, message, path, { severity, fix }));
+    };
+    const text = (value, path) => {
+        if (!strip)
+            return value;
+        const clean = stripHiddenCharacters(value);
+        if (clean !== value) {
+            hiddenStrings++;
+            if (hiddenReports < HIDDEN_REPORTS) {
+                hiddenReports++;
+                report('hidden-characters', `Removed ${value.length - clean.length} hidden or reordering character(s).`, path, 'Remove control, zero-width and bidi characters from the source.', 'warning');
+            }
+        }
+        return clean;
+    };
+    const holder = {};
+    const stack = [
+        { value: input, path: [], depth: 0, target: holder, slot: 'root', ancestors: [] },
+    ];
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if (bytes > maxBytes) {
+            if (!stopped) {
+                stopped = true;
+                report('too-large', `The deck is larger than ${maxBytes} bytes of JSON.`, [], 'Shorten notes, media or blocks, or split the deck.');
+            }
+            break;
+        }
+        const value = frame.value;
+        switch (typeof value) {
+            case 'string': {
+                const clean = text(value, frame.path);
+                bytes += utf8Length(clean) + 2;
+                frame.target[frame.slot] = clean;
+                continue;
+            }
+            case 'number':
+                if (!Number.isFinite(value)) {
+                    report('not-finite', 'NaN and Infinity are not JSON data.', frame.path, 'Use a finite number.');
+                    continue;
+                }
+                bytes += String(value).length;
+                frame.target[frame.slot] = value;
+                continue;
+            case 'boolean':
+                bytes += value ? 4 : 5;
+                frame.target[frame.slot] = value;
+                continue;
+            case 'object':
+                break;
+            default:
+                report('invalid-input', `Received ${describe(value)}, which is not JSON data.`, frame.path, 'Pass JSON text or plain JSON data.');
+                continue;
+        }
+        if (value === null) {
+            bytes += 4;
+            frame.target[frame.slot] = null;
+            continue;
+        }
+        if (frame.ancestors.includes(value)) {
+            report('cycle', 'The value contains itself (a cyclic reference).', frame.path, 'Pass acyclic data.');
+            continue;
+        }
+        if (frame.depth >= maxDepth) {
+            report('too-deep', `The deck nests deeper than ${maxDepth} levels.`, frame.path, 'Flatten nested blocks or props.');
+            continue;
+        }
+        let isArray;
+        let keys;
+        try {
+            isArray = Array.isArray(value);
+            if (!isArray) {
+                const proto = Object.getPrototypeOf(value);
+                if (proto !== null && Object.getPrototypeOf(proto) !== null) {
+                    report('invalid-input', 'Objects must be plain JSON objects (no class instances).', frame.path, 'Pass JSON text or plain objects.');
+                    continue;
+                }
+                if (Object.getOwnPropertySymbols(value).length > 0) {
+                    report('invalid-input', 'Symbol keys are not JSON data.', frame.path, 'Pass JSON data.');
+                }
+            }
+            keys = isArray ? [] : Object.keys(value);
+        }
+        catch {
+            report('invalid-input', 'The value could not be read.', frame.path, 'Pass JSON data.');
+            continue;
+        }
+        const ancestors = [...frame.ancestors, value];
+        const depth = frame.depth + 1;
+        const children = [];
+        const read = (key, path) => {
+            try {
+                const descriptor = Object.getOwnPropertyDescriptor(value, key);
+                if (descriptor && 'value' in descriptor)
+                    return { ok: true, value: descriptor.value };
+                report('invalid-input', descriptor
+                    ? 'Accessor properties are not data; use a plain value.'
+                    : 'Arrays must be dense (no holes).', path, 'Pass JSON data.');
+            }
+            catch {
+                report('invalid-input', 'The property could not be read.', path, 'Pass JSON data.');
+            }
+            return { ok: false };
+        };
+        if (isArray) {
+            let length = 0;
+            try {
+                length = value.length;
+            }
+            catch {
+                report('invalid-input', 'The array could not be read.', frame.path, 'Pass JSON data.');
+                continue;
+            }
+            const out = [];
+            frame.target[frame.slot] = out;
+            bytes += 2 + Math.max(0, length - 1);
+            for (let i = 0; i < length && bytes <= maxBytes; i++) {
+                const path = [...frame.path, i];
+                const child = read(i, path);
+                if (!child.ok)
+                    continue;
+                children.push({
+                    value: child.value,
+                    path,
+                    depth,
+                    target: out,
+                    slot: children.length,
+                    ancestors,
+                });
+            }
+        }
+        else {
+            const out = {};
+            frame.target[frame.slot] = out;
+            bytes += 2;
+            for (const rawKey of keys) {
+                const path = [...frame.path, rawKey];
+                if (UNSAFE.has(rawKey)) {
+                    report('unsafe-key', `The key ${JSON.stringify(rawKey)} is not allowed.`, path, 'Remove the key.');
+                    continue;
+                }
+                const child = read(rawKey, path);
+                if (!child.ok)
+                    continue;
+                if (child.value === undefined)
+                    continue; // JSON drops undefined values
+                const key = text(rawKey, path);
+                if (UNSAFE.has(key)) {
+                    report('unsafe-key', `The key ${JSON.stringify(key)} is not allowed.`, path, 'Remove the key.');
+                    continue;
+                }
+                bytes += utf8Length(key) + 4;
+                children.push({ value: child.value, path, depth, target: out, slot: key, ancestors });
+            }
+        }
+        // Reverse, so children are visited (and reported) in document order.
+        for (let i = children.length - 1; i >= 0; i--)
+            stack.push(children[i]);
+    }
+    if (hiddenStrings > hiddenReports) {
+        report('hidden-characters', `Hidden characters were removed from ${hiddenStrings - hiddenReports} more string(s).`, [], 'Remove control, zero-width and bidi characters from the source.', 'warning');
+    }
+    return { value: holder.root, issues, failed, truncated, bytes };
+}

package/dist/model/shared.d.ts

@@ -0,0 +1,63 @@
+/** Slide, section and block ids: lowercase slug, 1 to 64 characters. */
+export declare const SLIDE_ID_PATTERN = "^[a-z0-9][a-z0-9-]{0,63}$";
+export declare const slideId: import("../index.js").StringSchema;
+/** A trimmed single-line string of at most `max` code points. */
+export declare function line(max: number, min?: number): import("../index.js").StringSchema;
+/** A multi-line string (notes, captions) of at most `max` code points. */
+export declare function multiline(max: number): import("../index.js").StringSchema;
+/** The v2 fragment effects (Protoyard's vocabulary). */
+export declare const FRAGMENT_EFFECTS: readonly ["in", "fade-up", "out", "in-then-out", "grow", "shrink", "highlight", "strike"];
+export type FragmentEffect = (typeof FRAGMENT_EFFECTS)[number];
+/** The legacy block reveal vocabulary (Texuli v1), mapped onto fragments. */
+export declare const BLOCK_REVEALS: readonly ["fade", "fade-up", "grow", "highlight", "strike"];
+export type BlockReveal = (typeof BLOCK_REVEALS)[number];
+/** Highlight tones (reveal.js `highlight-red`/`-blue` map onto these). */
+export declare const FRAGMENT_TONES: readonly ["accent", "info", "success", "warning", "danger"];
+export type FragmentTone = (typeof FRAGMENT_TONES)[number];
+/** The most distinct steps one slide may have (more is an error). */
+export declare const MAX_SLIDE_STEPS = 32;
+/** The largest authored step number before dense renumbering. */
+export declare const MAX_AUTHORED_STEP = 1000;
+/**
+ * Step fields any block, component item or steppable props object may carry.
+ * `fragment` and `reveal` are mutually exclusive (checked by the steps pass).
+ */
+export declare const stepFields: {
+    readonly step: import("../index.js").OptionalSchema<import("../index.js").NumberSchema, false>;
+    readonly fragment: import("../index.js").OptionalSchema<import("../index.js").EnumSchema<"in" | "fade-up" | "out" | "in-then-out" | "grow" | "shrink" | "highlight" | "strike">, false>;
+    readonly reveal: import("../index.js").OptionalSchema<import("../index.js").EnumSchema<"fade-up" | "grow" | "highlight" | "strike" | "fade">, false>;
+    readonly tone: import("../index.js").OptionalSchema<import("../index.js").EnumSchema<"accent" | "info" | "success" | "warning" | "danger">, false>;
+};
+export declare const DECK_TRANSITIONS: readonly ["none", "fade", "fade-up", "slide", "zoom", "morph"];
+export type DeckTransition = (typeof DECK_TRANSITIONS)[number];
+export declare const deckTransition: import("../index.js").EnumSchema<"fade-up" | "fade" | "none" | "slide" | "zoom" | "morph">;
+export declare const DECK_ASPECTS: readonly ["16:9", "4:3", "9:16", "1:1"];
+export type DeckAspect = (typeof DECK_ASPECTS)[number];
+/** The fixed virtual canvas for each aspect, in CSS pixels. */
+export declare const DECK_CANVAS: Readonly<Record<DeckAspect, {
+    width: number;
+    height: number;
+}>>;
+/**
+ * Media source syntax: an `https:` URL, a relative path without `..`,
+ * backslashes or SVG (any case, also percent-encoded), a base64 `data:`
+ * raster or video, or an `avatar:` id. Size caps for `data:` and the trust
+ * tier are the host's, applied later.
+ */
+export declare const MEDIA_SRC_PATTERN = "^(?:https://(?![^?#]*(?:\\.|%2[eE])[sS][vV][gG](?:[?#]|%(?:3[fF]|23)|$))[^\\s\"<>\\\\]+|(?!/)(?!.*\\.\\.)(?!.*(?:\\.|%2[eE])[sS][vV][gG](?:[?#]|%(?:3[fF]|23)|$))[A-Za-z0-9._~/-]+(?:[?#][^\\s\"<>\\\\]*)?|data:(?:image/(?:png|jpeg|gif|webp|avif)|video/(?:mp4|webm));base64,[A-Za-z0-9+/=]+|avatar:av-[0-9]{3})$";
+export declare const mediaSrc: import("../index.js").StringSchema;
+/**
+ * Link syntax: `https:`, `mailto:`, a fragment, the deck's own route
+ * (`#/<slide-id>` or `#/<slide-id>/<step>`, step 0 to 32, as `parseDeckHash`
+ * reads it) or a relative path.
+ */
+export declare const LINK_HREF_PATTERN = "^(?:https://[^\\s\"<>\\\\]+|mailto:[^\\s\"<>\\\\]+|#[A-Za-z0-9._~-]*|#/[a-z0-9][a-z0-9-]{0,63}(?:/(?:[0-9]|[12][0-9]|3[0-2]))?|(?!//)(?!.*\\.\\.)[A-Za-z0-9._~/-]+(?:[?#][^\\s\"<>\\\\]*)?)$";
+export declare const linkHref: import("../index.js").StringSchema;
+/** Bounded JSON props (Protoyard's limits): depth 4, 100 keys, 200 items. */
+export declare const boundedProps: import("../index.js").JsonValueSchema;
+/**
+ * Catalog component props on a slide: deeper and longer than layout props, so
+ * data views and workflow graphs (500 nodes, 2,000 edges) fit. The host's
+ * registry validates the content at its tier.
+ */
+export declare const componentProps: import("../index.js").JsonValueSchema;

package/dist/model/shared.js

@@ -0,0 +1,86 @@
+/**
+ * Schemas every part of deck model v2 shares: ids, text, step markers,
+ * transitions and media syntax (ADR-009). The engine checks syntax only; the
+ * stage applies the URL policy at the host's tier when it paints.
+ */
+import { t } from "../schema/index.js";
+/** Slide, section and block ids: lowercase slug, 1 to 64 characters. */
+export const SLIDE_ID_PATTERN = '^[a-z0-9][a-z0-9-]{0,63}$';
+export const slideId = t.string({ pattern: SLIDE_ID_PATTERN, max: 64 });
+/** A trimmed single-line string of at most `max` code points. */
+export function line(max, min = 0) {
+    return t.string({ min, max, trim: true, text: 'line' });
+}
+/** A multi-line string (notes, captions) of at most `max` code points. */
+export function multiline(max) {
+    return t.string({ max, text: 'multiline' });
+}
+/** The v2 fragment effects (Protoyard's vocabulary). */
+export const FRAGMENT_EFFECTS = [
+    'in',
+    'fade-up',
+    'out',
+    'in-then-out',
+    'grow',
+    'shrink',
+    'highlight',
+    'strike',
+];
+/** The legacy block reveal vocabulary (Texuli v1), mapped onto fragments. */
+export const BLOCK_REVEALS = ['fade', 'fade-up', 'grow', 'highlight', 'strike'];
+/** Highlight tones (reveal.js `highlight-red`/`-blue` map onto these). */
+export const FRAGMENT_TONES = ['accent', 'info', 'success', 'warning', 'danger'];
+/** The most distinct steps one slide may have (more is an error). */
+export const MAX_SLIDE_STEPS = 32;
+/** The largest authored step number before dense renumbering. */
+export const MAX_AUTHORED_STEP = 1000;
+/**
+ * Step fields any block, component item or steppable props object may carry.
+ * `fragment` and `reveal` are mutually exclusive (checked by the steps pass).
+ */
+export const stepFields = {
+    step: t.optional(t.int({ min: 0, max: MAX_AUTHORED_STEP })),
+    fragment: t.optional(t.enum(FRAGMENT_EFFECTS)),
+    reveal: t.optional(t.enum(BLOCK_REVEALS)),
+    tone: t.optional(t.enum(FRAGMENT_TONES)),
+};
+export const DECK_TRANSITIONS = ['none', 'fade', 'fade-up', 'slide', 'zoom', 'morph'];
+export const deckTransition = t.enum(DECK_TRANSITIONS);
+export const DECK_ASPECTS = ['16:9', '4:3', '9:16', '1:1'];
+/** The fixed virtual canvas for each aspect, in CSS pixels. */
+export const DECK_CANVAS = Object.freeze({
+    '16:9': { width: 1280, height: 720 },
+    '4:3': { width: 1024, height: 768 },
+    '9:16': { width: 720, height: 1280 },
+    '1:1': { width: 1080, height: 1080 },
+});
+/**
+ * An SVG path ending, in any letter case, with the dot and the end marker
+ * also percent-encoded: `.svg`, `.SVG`, `%2esvg`, then `?`, `#`, `%3F`,
+ * `%23` or the end. A character class per letter, not the `i` flag: the
+ * pattern travels as a JSON Schema `pattern` string.
+ */
+const SVG_ENDING = '(?:\\.|%2[eE])[sS][vV][gG](?:[?#]|%(?:3[fF]|23)|$)';
+/**
+ * Media source syntax: an `https:` URL, a relative path without `..`,
+ * backslashes or SVG (any case, also percent-encoded), a base64 `data:`
+ * raster or video, or an `avatar:` id. Size caps for `data:` and the trust
+ * tier are the host's, applied later.
+ */
+export const MEDIA_SRC_PATTERN = `^(?:https://(?![^?#]*${SVG_ENDING})[^\\s"<>\\\\]+|(?!/)(?!.*\\.\\.)(?!.*${SVG_ENDING})[A-Za-z0-9._~/-]+(?:[?#][^\\s"<>\\\\]*)?|data:(?:image/(?:png|jpeg|gif|webp|avif)|video/(?:mp4|webm));base64,[A-Za-z0-9+/=]+|avatar:av-[0-9]{3})$`;
+export const mediaSrc = t.string({ min: 1, max: 2_000_000, pattern: MEDIA_SRC_PATTERN });
+/**
+ * Link syntax: `https:`, `mailto:`, a fragment, the deck's own route
+ * (`#/<slide-id>` or `#/<slide-id>/<step>`, step 0 to 32, as `parseDeckHash`
+ * reads it) or a relative path.
+ */
+export const LINK_HREF_PATTERN = '^(?:https://[^\\s"<>\\\\]+|mailto:[^\\s"<>\\\\]+|#[A-Za-z0-9._~-]*|#/[a-z0-9][a-z0-9-]{0,63}(?:/(?:[0-9]|[12][0-9]|3[0-2]))?|(?!//)(?!.*\\.\\.)[A-Za-z0-9._~/-]+(?:[?#][^\\s"<>\\\\]*)?)$';
+export const linkHref = t.string({ min: 1, max: 2048, pattern: LINK_HREF_PATTERN });
+/** Bounded JSON props (Protoyard's limits): depth 4, 100 keys, 200 items. */
+export const boundedProps = t.json({ depth: 4 });
+/**
+ * Catalog component props on a slide: deeper and longer than layout props, so
+ * data views and workflow graphs (500 nodes, 2,000 edges) fit. The host's
+ * registry validates the content at its tier.
+ */
+export const componentProps = t.json({ depth: 8, maxItems: 2000 });

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

@@ -0,0 +1,7 @@
+/**
+ * Fragments and steps of deck model v2 (model-v2 §3.7): one algorithm for
+ * blocks, list items, code highlights and layout props markers, with dense
+ * renumbering and Protoyard's fragment phases.
+ */
+export { activeCodeHighlight, FRAGMENT_PHASES, type FragmentPhase, fragmentPhase, isPhaseShown, } from './phase.js';
+export { type FragmentKind, REVEAL_EFFECT, type SlideFragment, type SlideStep, type SlideSteps, type SlideStepsOptions, STEP_CODES, type StepCode, type StepDiagnostic, type StepMarkerFields, type StepSource, type StepSourceBlock, slideFragments, slideStepCount, slideSteps, steppablePattern, } from './slide-steps.js';

package/dist/model/steps/index.js

@@ -0,0 +1,7 @@
+/**
+ * Fragments and steps of deck model v2 (model-v2 §3.7): one algorithm for
+ * blocks, list items, code highlights and layout props markers, with dense
+ * renumbering and Protoyard's fragment phases.
+ */
+export { activeCodeHighlight, FRAGMENT_PHASES, fragmentPhase, isPhaseShown, } from "./phase.js";
+export { REVEAL_EFFECT, STEP_CODES, slideFragments, slideStepCount, slideSteps, steppablePattern, } from "./slide-steps.js";

package/dist/model/steps/phase.d.ts

@@ -0,0 +1,34 @@
+/**
+ * What a fragment looks like at a step (Protoyard's `fragmentPhase`, as four
+ * named phases):
+ *
+ * - `hidden`: not shown yet (an entering fragment before its step);
+ * - `visible`: shown, effect not applied (or an entrance that has played);
+ * - `active`: shown with its effect applied (grown, shrunk, highlighted,
+ *   struck through);
+ * - `gone`: shown once, now removed (`out` from its step, `in-then-out`
+ *   after its step).
+ *
+ * Hidden and gone fragments keep their layout space and leave the
+ * accessibility tree; that is the stage's job.
+ */
+import type { FragmentEffect } from '../shared.js';
+import type { SlideFragment } from './slide-steps.js';
+export declare const FRAGMENT_PHASES: readonly ["hidden", "visible", "active", "gone"];
+export type FragmentPhase = (typeof FRAGMENT_PHASES)[number];
+/**
+ * The phase of a fragment at `current` (0 = initial state). Steps past the
+ * slide's count behave like its last step.
+ */
+export declare function fragmentPhase(fragment: {
+    step: number;
+    effect: FragmentEffect;
+}, current: number): FragmentPhase;
+/** Whether a phase is rendered (`visible` or `active`). */
+export declare function isPhaseShown(phase: FragmentPhase): boolean;
+/**
+ * The code highlight shown at `current` for the code block (or props code
+ * object) at `ownerPath`: the latest highlight whose step was reached, or
+ * `null` before the first one.
+ */
+export declare function activeCodeHighlight(fragments: readonly SlideFragment[], ownerPath: readonly (string | number)[], current: number): string | null;

package/dist/model/steps/phase.js

@@ -0,0 +1,50 @@
+export const FRAGMENT_PHASES = ['hidden', 'visible', 'active', 'gone'];
+/** The step to evaluate: non-finite or negative is the initial state. */
+function at(current) {
+    return Number.isFinite(current) ? Math.max(0, Math.trunc(current)) : 0;
+}
+/**
+ * The phase of a fragment at `current` (0 = initial state). Steps past the
+ * slide's count behave like its last step.
+ */
+export function fragmentPhase(fragment, current) {
+    const now = at(current);
+    const reached = now >= fragment.step;
+    switch (fragment.effect) {
+        case 'in':
+        case 'fade-up':
+            return reached ? 'visible' : 'hidden';
+        case 'out':
+            return reached ? 'gone' : 'visible';
+        case 'in-then-out':
+            return now < fragment.step ? 'hidden' : now === fragment.step ? 'visible' : 'gone';
+        case 'grow':
+        case 'shrink':
+        case 'highlight':
+        case 'strike':
+            return reached ? 'active' : 'visible';
+    }
+}
+/** Whether a phase is rendered (`visible` or `active`). */
+export function isPhaseShown(phase) {
+    return phase === 'visible' || phase === 'active';
+}
+/**
+ * The code highlight shown at `current` for the code block (or props code
+ * object) at `ownerPath`: the latest highlight whose step was reached, or
+ * `null` before the first one.
+ */
+export function activeCodeHighlight(fragments, ownerPath, current) {
+    const key = JSON.stringify(ownerPath);
+    const now = at(current);
+    let shown = null;
+    for (const fragment of fragments) {
+        if (fragment.kind !== 'highlight' || fragment.lines === undefined)
+            continue;
+        if (JSON.stringify(fragment.path.slice(0, -2)) !== key)
+            continue;
+        if (fragment.step <= now)
+            shown = fragment.lines;
+    }
+    return shown;
+}

package/dist/model/steps/slide-steps.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 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 { type DeckDiagnostic, type PathSegment } from '../../schema/index.js';
+import { type BlockReveal, type FragmentEffect, type FragmentTone } from '../shared.js';
+/** The legacy block `reveal` vocabulary in fragment terms (`fade` is a plain `in`). */
+export declare const REVEAL_EFFECT: Readonly<Record<BlockReveal, FragmentEffect>>;
+/** The step codes this pass reports (model-v2 §3.9 cross-field and lint groups). */
+export declare const STEP_CODES: Readonly<{
+    readonly fragmentConflict: "fragment-conflict";
+    readonly tooManySteps: "too-many-steps";
+    readonly stepUnrevealed: "step-unrevealed";
+    readonly stepMissing: "step-missing";
+}>;
+export type StepCode = (typeof STEP_CODES)[keyof typeof STEP_CODES];
+export type StepDiagnostic = DeckDiagnostic<StepCode>;
+/** The step fields any block, component item or props marker may carry. */
+export interface StepMarkerFields {
+    step?: unknown;
+    fragment?: unknown;
+    reveal?: unknown;
+    tone?: unknown;
+}
+/** A block-like item: a block, a component item or anything with a `type`. */
+export interface StepSourceBlock extends StepMarkerFields {
+    type?: unknown;
+    id?: unknown;
+    /** List items (`type: 'list'`): item *i* enters at `step + i`. */
+    items?: unknown;
+    /** Code highlights (`type: 'code'`): highlight *i* at `step + i`. */
+    highlights?: unknown;
+    /** Nested blocks. */
+    blocks?: unknown;
+    children?: unknown;
+    /** `@texuli/blocks` containers: `columns` (arrays of blocks) and `tabs` panels. */
+    columns?: unknown;
+    panels?: unknown;
+    [key: string]: unknown;
+}
+/** The minimal slide shape the steps pass reads. */
+export interface StepSource {
+    id?: unknown;
+    /** `custom` slides step through their labels only. */
+    layout?: unknown;
+    /** Layout props: any JSON; step markers are found anywhere inside. */
+    props?: unknown;
+    /** Free-slide items (blocks and component items). */
+    blocks?: readonly unknown[] | unknown;
+    /** Step labels: `steps[i]` names step `i + 1`. */
+    steps?: readonly unknown[] | unknown;
+}
+export interface SlideStepsOptions {
+    /**
+     * Where the slide's layout reveals a props marker, relative to `props`:
+     * `''` is the props object, `cta` a nested object, `cards.*` each list
+     * item. Supplied by the layout catalog; omit it to skip the
+     * `step-unrevealed` check.
+     */
+    steppablePaths?: readonly string[];
+    /** Prefix for diagnostic paths (`['slides', 3]`); fragment paths stay slide-relative. */
+    path?: readonly PathSegment[];
+}
+export type FragmentKind = 'block' | 'item' | 'highlight' | 'prop';
+export interface SlideFragment {
+    kind: FragmentKind;
+    /** Path relative to the slide (`['blocks', 0, 'items', 2]`, `['props', 'cards', 1]`). */
+    path: PathSegment[];
+    /** `toJsonPath(path)`: `$.blocks[0].items[2]`. */
+    jsonPath: string;
+    effect: FragmentEffect;
+    tone?: FragmentTone;
+    /** The dense step (0 = initial state, 1…count). */
+    step: number;
+    /** The authored step before renumbering. */
+    authored: number;
+    /** The id of the block the fragment belongs to, when it has one. */
+    blockId?: string;
+    /** The list item index (`item`). */
+    item?: number;
+    /** The highlighted line range (`highlight`), such as `'1-2'`. */
+    lines?: string;
+}
+export interface SlideStep {
+    /** `steps[i].index === i`; 0 is the initial state. */
+    index: number;
+    /** The author's label from `slide.steps[index - 1]`. */
+    label?: string;
+    fragments: SlideFragment[];
+}
+export interface SlideSteps {
+    /** "Next" presses on this slide before the deck moves on (≤ `MAX_SLIDE_STEPS`). */
+    count: number;
+    /** The initial step: always 0. */
+    initial: 0;
+    /** `count + 1` entries: the initial state, then one per step. */
+    steps: SlideStep[];
+    issues: StepDiagnostic[];
+}
+/** `['cards', 2]` → `cards.*`; the props object itself is `''`. */
+export declare function steppablePattern(path: readonly PathSegment[]): string;
+/** Derives the ordered, densely numbered steps of a slide. Never throws. */
+export declare function slideSteps(slide: StepSource, options?: SlideStepsOptions): SlideSteps;
+/** How many "next" presses a slide takes before the deck moves on. */
+export declare function slideStepCount(slide: StepSource, options?: SlideStepsOptions): number;
+/** Every fragment of a slide, initial state first, in step order. */
+export declare function slideFragments(steps: Pick<SlideSteps, 'steps'>): SlideFragment[];