@texuli/deck 0.0.0-stage → 0.5.0

package/dist/model/motion/transition.js

@@ -0,0 +1,127 @@
+/**
+ * Slide transitions and fragment motion under a motion level (ported from
+ * Protoyard's `motion/transition.ts`, plus v1's `fade-up` transition).
+ *
+ * - The deck's `style.motion` (`full` | `subtle` | `none`) is the ceiling;
+ *   an explicit `motion` option replaces it.
+ * - The viewer's reduced-motion preference only lowers it, never raises it:
+ *   with it, every transition is `none` or a short fade, and moving
+ *   fragments become plain fades.
+ * - Durations are opacity and transform only and never exceed
+ *   `MAX_MOTION_MS`.
+ *
+ * Inputs are structural plain objects; unknown values fall through to the
+ * next source (slide → deck → `fade`) instead of throwing.
+ */
+import { DECK_TRANSITIONS } from "../shared.js";
+export const MOTION_LEVELS = ['full', 'subtle', 'none'];
+export const MAX_MOTION_MS = 400;
+/** A reduced-motion fade: short enough to read as a cut, long enough not to flash. */
+export const REDUCED_FADE_MS = 150;
+/** Subtle motion runs at this share of the full duration. */
+export const SUBTLE_SCALE = 0.6;
+/** A fragment's full-motion duration. */
+export const FRAGMENT_MS = 300;
+export const DEFAULT_TRANSITION = 'fade';
+export const DEFAULT_MOTION = 'full';
+/** Full-motion transition durations, in milliseconds. */
+export const TRANSITION_MS = Object.freeze({
+    none: 0,
+    fade: 300,
+    'fade-up': 300,
+    slide: 400,
+    zoom: 350,
+    morph: 400,
+});
+export function isDeckTransition(value) {
+    return typeof value === 'string' && DECK_TRANSITIONS.includes(value);
+}
+export function isMotionLevel(value) {
+    return typeof value === 'string' && MOTION_LEVELS.includes(value);
+}
+/** The requested level (option, then deck style, then `full`), lowered by reduced motion. */
+export function effectiveMotion(options = {}) {
+    const style = options.deck?.style;
+    const level = isMotionLevel(options.motion)
+        ? options.motion
+        : isMotionLevel(style?.motion)
+            ? style.motion
+            : DEFAULT_MOTION;
+    if (level === 'none')
+        return 'none';
+    return options.reducedMotion ? 'subtle' : level;
+}
+function clampMs(ms) {
+    return Math.max(0, Math.min(MAX_MOTION_MS, Math.round(ms)));
+}
+/** The transition into `slide`: slide override → deck default → `fade`, under the motion level. */
+export function resolveSlideTransition(input = {}) {
+    const own = input.slide?.transition;
+    const deckDefault = input.deck?.style?.transition;
+    const [requested, source] = isDeckTransition(own)
+        ? [own, 'slide-override']
+        : isDeckTransition(deckDefault)
+            ? [deckDefault, 'deck-default']
+            : [DEFAULT_TRANSITION, 'engine-default'];
+    const motion = effectiveMotion(input);
+    if (motion === 'none' || requested === 'none') {
+        return {
+            name: 'none',
+            durationMs: 0,
+            requested,
+            motion,
+            reason: motion === 'none' ? 'motion-none' : source,
+        };
+    }
+    if (input.reducedMotion) {
+        return {
+            name: 'fade',
+            durationMs: REDUCED_FADE_MS,
+            requested,
+            motion,
+            reason: 'reduced-motion',
+        };
+    }
+    if (motion === 'subtle') {
+        // Subtle keeps direction (slide, fade-up, morph) but drops scaling and shortens everything.
+        const name = requested === 'zoom' ? 'fade' : requested;
+        return {
+            name,
+            durationMs: clampMs(TRANSITION_MS[name] * SUBTLE_SCALE),
+            requested,
+            motion,
+            reason: 'subtle',
+        };
+    }
+    return {
+        name: requested,
+        durationMs: clampMs(TRANSITION_MS[requested]),
+        requested,
+        motion,
+        reason: source,
+    };
+}
+/** The transition into every slide of a deck, in order. */
+export function resolveDeckTransitions(deck, options = {}) {
+    const slides = Array.isArray(deck?.slides) ? deck.slides : [];
+    return slides.map((slide, index) => ({
+        index,
+        ...(typeof slide?.id === 'string' ? { slideId: slide.id } : {}),
+        transition: resolveSlideTransition({ ...options, slide, deck }),
+    }));
+}
+const MOVING = new Set(['fade-up', 'grow', 'shrink']);
+/** How a fragment animates under the motion level. */
+export function resolveFragmentMotion(effect, options = {}) {
+    const motion = effectiveMotion(options);
+    const still = MOVING.has(effect) ? 'in' : effect;
+    if (motion === 'none')
+        return { effect: still, durationMs: 0, motion, reason: 'motion-none' };
+    if (options.reducedMotion) {
+        return { effect: still, durationMs: REDUCED_FADE_MS, motion, reason: 'reduced-motion' };
+    }
+    if (motion === 'subtle') {
+        return { effect, durationMs: clampMs(FRAGMENT_MS * SUBTLE_SCALE), motion, reason: 'subtle' };
+    }
+    return { effect, durationMs: clampMs(FRAGMENT_MS), motion, reason: 'full' };
+}

package/dist/model/parse.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `parseDeck`: validate a v2 deck and collect every issue (model-v2 §3.4).
+ *
+ * 1. The structural pass (the schema kit): every field, limit and union.
+ * 2. The cross-field passes, which run even when the structural pass failed
+ *    (on a bounded plain copy of the input), so authors see all problems at
+ *    once: unique slide, section and block ids, outline references, stacks,
+ *    `navigation.start`, hidden slides, and the steps of every slide.
+ * 3. The host phase: the optional `validateBlock`, `validateComponent` and
+ *    `knownComponents` options check block bodies and component props, which
+ *    this L0 package cannot know.
+ *
+ * Issues are capped (default 200, `truncated: true` past it). Never throws.
+ */
+import { type DeckDiagnostic, type PathSegment } from '../schema/index.js';
+import { type Deck, type JsonObject, type SlideBlock } from './deck.js';
+import { type SlideSteps } from './steps/slide-steps.js';
+/** A whole-slide component or an inline component item, as the host validator sees it. */
+export interface DeckComponentInput {
+    component: string;
+    props: JsonObject;
+}
+/** What a host hook returns: issues with absolute paths (or nothing when valid). */
+export type DeckHookResult = readonly DeckDiagnostic[] | undefined;
+export interface ParseDeckOptions {
+    /**
+     * Validate one top-level block of a free slide (its step fields removed),
+     * e.g. with `@texuli/blocks` `safeParseBlock`. `path` is absolute
+     * (`['slides', 2, 'blocks', 0]`); return issues with absolute paths.
+     */
+    validateBlock?(block: SlideBlock, path: PathSegment[]): DeckHookResult;
+    /** Validate a component's props with the host registry (inline items and component slides). */
+    validateComponent?(component: DeckComponentInput, path: PathSegment[]): DeckHookResult;
+    /** Component ids the host can paint; any other id is `unknown-component`. */
+    knownComponents?: readonly string[];
+    /** Issues kept before `truncated` (default 200). */
+    maxIssues?: number;
+}
+export interface DeckParseResult {
+    /** True when no error was found (warnings may remain in `issues`). */
+    ok: boolean;
+    /** The validated, trimmed copy; only when `ok`. */
+    deck?: Deck;
+    issues: DeckDiagnostic[];
+    /** The steps of each slide, in order (computed on partial input too). */
+    steps: SlideSteps[];
+    /** More issues existed than `maxIssues`. */
+    truncated: boolean;
+}
+/**
+ * A copy of a block without the deck's step fields (at every nesting level,
+ * including chart `series` entries, which the chart block parser refuses
+ * with step fields).
+ */
+export declare function stripStepFields<T>(block: T): T;
+/** Validate a v2 deck: every structural, cross-field and host issue. Never throws. */
+export declare function parseDeck(input: unknown, options?: ParseDeckOptions): DeckParseResult;

package/dist/model/parse.js

@@ -0,0 +1,307 @@
+/**
+ * `parseDeck`: validate a v2 deck and collect every issue (model-v2 §3.4).
+ *
+ * 1. The structural pass (the schema kit): every field, limit and union.
+ * 2. The cross-field passes, which run even when the structural pass failed
+ *    (on a bounded plain copy of the input), so authors see all problems at
+ *    once: unique slide, section and block ids, outline references, stacks,
+ *    `navigation.start`, hidden slides, and the steps of every slide.
+ * 3. The host phase: the optional `validateBlock`, `validateComponent` and
+ *    `knownComponents` options check block bodies and component props, which
+ *    this L0 package cannot know.
+ *
+ * Issues are capped (default 200, `truncated: true` past it). Never throws.
+ */
+import { createDiagnostic, MAX_DIAGNOSTICS, toJsonPath, validate, } from "../schema/index.js";
+import { DECK_MODEL_LIMITS, deckSchema, forEachNested, STEP_FIELD_KEYS, } from "./deck.js";
+import { layoutSteppablePaths } from "./layouts/catalog.js";
+import { copyPlainData } from "./plain.js";
+import { slideSteps } from "./steps/slide-steps.js";
+function isBag(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** The issue list with its cap; errors are counted even past the cap. */
+class Sink {
+    issues = [];
+    errors = 0;
+    truncated = false;
+    max;
+    constructor(max) {
+        this.max = max;
+    }
+    add(issue) {
+        if (issue.severity === 'error')
+            this.errors++;
+        if (this.issues.length >= this.max) {
+            this.truncated = true;
+            return;
+        }
+        this.issues.push(issue);
+    }
+    report(code, message, path, extra) {
+        this.add(createDiagnostic(code, message, path, extra));
+    }
+}
+/**
+ * A copy of a block without the deck's step fields (at every nesting level,
+ * including chart `series` entries, which the chart block parser refuses
+ * with step fields).
+ */
+export function stripStepFields(block) {
+    if (!isBag(block))
+        return block;
+    const out = {};
+    for (const key of Object.keys(block)) {
+        if (STEP_FIELD_KEYS.includes(key))
+            continue;
+        out[key] = block[key];
+    }
+    for (const key of ['blocks', 'children', 'series']) {
+        if (Array.isArray(out[key]))
+            out[key] = out[key].map(stripStepFields);
+    }
+    if (Array.isArray(out.columns)) {
+        out.columns = out.columns.map((column) => Array.isArray(column) ? column.map(stripStepFields) : column);
+    }
+    if (Array.isArray(out.panels)) {
+        out.panels = out.panels.map((panel) => isBag(panel) && Array.isArray(panel.blocks)
+            ? { ...panel, blocks: panel.blocks.map(stripStepFields) }
+            : panel);
+    }
+    return out;
+}
+function runHook(sink, code, path, call) {
+    let result;
+    try {
+        result = call();
+    }
+    catch {
+        sink.report(code, 'The host validator failed on this value.', path, {
+            fix: 'Check the value against the host registry.',
+        });
+        return;
+    }
+    if (!Array.isArray(result))
+        return;
+    for (const issue of result) {
+        if (isBag(issue) && typeof issue.code === 'string' && typeof issue.message === 'string') {
+            sink.add(issue);
+        }
+    }
+}
+function checkComponent(sink, options, value, path) {
+    const id = value.component;
+    if (typeof id !== 'string')
+        return;
+    if (options.knownComponents !== undefined && !options.knownComponents.includes(id)) {
+        sink.report('unknown-component', `The host has no component "${id.slice(0, 64)}".`, [...path, 'component'], {
+            fix: 'Use a component id from the host catalog, or a block.',
+        });
+        return;
+    }
+    if (options.validateComponent && isBag(value.props)) {
+        const input = { component: id, props: value.props };
+        runHook(sink, 'component-props', path, () => options.validateComponent?.(input, [...path]));
+    }
+}
+/** Block ids (deck-wide), nested component items and the host block hook. */
+function walkItem(pass, item, path, top, depth) {
+    if (!isBag(item) || depth > 16)
+        return;
+    const id = item.id;
+    if (typeof id === 'string') {
+        const first = pass.blockIds.get(id);
+        if (first !== undefined) {
+            pass.sink.report('duplicate-block-id', `The block id "${id}" is already used at ${first}.`, [...path, 'id'], { fix: 'Give every block a unique id (they key interactive state and deep links).' });
+        }
+        else
+            pass.blockIds.set(id, toJsonPath(path));
+    }
+    if (item.type === 'component') {
+        checkComponent(pass.sink, pass.options, item, path);
+        return;
+    }
+    if (top && typeof item.type === 'string' && pass.options.validateBlock) {
+        const block = stripStepFields(item);
+        runHook(pass.sink, 'block-props', path, () => pass.options.validateBlock?.(block, [...path]));
+    }
+    forEachNested(item, path, (child, childPath) => {
+        walkItem(pass, child, childPath, false, depth + 1);
+    });
+}
+function crossField(tree, options, sink) {
+    const deck = isBag(tree) ? tree : {};
+    const slides = Array.isArray(deck.slides)
+        ? deck.slides.slice(0, DECK_MODEL_LIMITS.slides)
+        : [];
+    // Slide ids
+    const slideIndex = new Map();
+    const hidden = new Set();
+    let visible = 0;
+    slides.forEach((slide, i) => {
+        if (!isBag(slide))
+            return;
+        if (slide.hidden !== true)
+            visible++;
+        const id = slide.id;
+        if (typeof id !== 'string')
+            return;
+        const first = slideIndex.get(id);
+        if (first !== undefined) {
+            sink.report('duplicate-id', `The slide id "${id}" is already used by slides[${first}].`, ['slides', i, 'id'], { fix: 'Give every slide a unique id.' });
+        }
+        else {
+            slideIndex.set(id, i);
+            if (slide.hidden === true)
+                hidden.add(id);
+        }
+    });
+    if (slides.length > 0 && visible === 0) {
+        sink.report('all-hidden', 'Every slide is hidden, so the deck presents nothing.', ['slides'], {
+            fix: 'Show at least one slide (remove `hidden: true`).',
+        });
+    }
+    // Navigation start
+    const navigation = isBag(deck.navigation) ? deck.navigation : undefined;
+    const start = navigation?.start;
+    if (typeof start === 'string') {
+        if (!slideIndex.has(start)) {
+            sink.report('unknown-slide', `No slide has the id "${start}".`, ['navigation', 'start'], {
+                fix: 'Use the id of a slide in `slides`.',
+            });
+        }
+        else if (hidden.has(start)) {
+            sink.report('start-hidden', `The start slide "${start}" is hidden.`, ['navigation', 'start'], {
+                fix: 'Start on a visible slide, or show this one.',
+            });
+        }
+    }
+    // Outline
+    const outline = isBag(deck.outline) ? deck.outline : undefined;
+    const sections = Array.isArray(outline?.sections)
+        ? outline.sections.slice(0, DECK_MODEL_LIMITS.sections)
+        : [];
+    const sectionIds = new Map();
+    const owner = new Map();
+    sections.forEach((section, s) => {
+        if (!isBag(section))
+            return;
+        const base = ['outline', 'sections', s];
+        const sectionId = typeof section.id === 'string' ? section.id : `#${s}`;
+        if (typeof section.id === 'string') {
+            const first = sectionIds.get(section.id);
+            if (first !== undefined) {
+                sink.report('duplicate-id', `The section id "${section.id}" is already used by sections[${first}].`, [...base, 'id'], { fix: 'Give every section a unique id.' });
+            }
+            else
+                sectionIds.set(section.id, s);
+        }
+        const ids = Array.isArray(section.slideIds)
+            ? section.slideIds.slice(0, DECK_MODEL_LIMITS.sectionSlides)
+            : [];
+        const seen = new Set();
+        const indexes = [];
+        ids.forEach((id, k) => {
+            if (typeof id !== 'string')
+                return;
+            const path = [...base, 'slideIds', k];
+            if (seen.has(id)) {
+                sink.report('duplicate-id', `"${id}" is listed twice in this section.`, path, {
+                    fix: 'List each slide once.',
+                });
+                return;
+            }
+            seen.add(id);
+            const index = slideIndex.get(id);
+            if (index === undefined) {
+                sink.report('unknown-slide', `No slide has the id "${id}".`, path, {
+                    fix: 'Use the id of a slide in `slides`, or remove it from the section.',
+                });
+                return;
+            }
+            indexes.push(index);
+            const other = owner.get(id);
+            if (other !== undefined) {
+                sink.report('section-overlap', `The slide "${id}" is already in section "${other}"; a slide belongs to one section.`, path, { fix: 'Remove the slide from one of the sections.' });
+            }
+            else
+                owner.set(id, sectionId);
+        });
+        if (section.stack === true && indexes.length > 1) {
+            const lowest = Math.min(...indexes);
+            const highest = Math.max(...indexes);
+            if (highest - lowest + 1 !== indexes.length) {
+                sink.report('stack-not-contiguous', 'A vertical stack lists slides that are not adjacent in `slides`.', [...base, 'slideIds'], { fix: 'Move the stacked slides next to each other, or drop `stack`.' });
+            }
+        }
+    });
+    // Blocks, components and steps, per slide
+    const pass = { sink, options, blockIds: new Map() };
+    const steps = [];
+    slides.forEach((slide, i) => {
+        const path = ['slides', i];
+        if (isBag(slide)) {
+            if (slide.layout === 'free' && Array.isArray(slide.blocks)) {
+                slide.blocks.slice(0, DECK_MODEL_LIMITS.freeBlocks).forEach((item, b) => {
+                    walkItem(pass, item, [...path, 'blocks', b], true, 0);
+                });
+            }
+            else if (slide.layout === 'component' && isBag(slide.component)) {
+                checkComponent(sink, options, slide.component, [...path, 'component']);
+            }
+        }
+        const result = slideSteps(isBag(slide) ? slide : {}, {
+            steppablePaths: isBag(slide) ? layoutSteppablePaths(slide.layout) : [],
+            path,
+        });
+        for (const issue of result.issues)
+            sink.add(issue);
+        steps.push(result);
+    });
+    return steps;
+}
+/** Fill `slideId` on issues under `slides[n]` (for editors and agent feedback). */
+function tagSlides(issues, tree) {
+    const slides = isBag(tree) && Array.isArray(tree.slides) ? tree.slides : [];
+    for (const issue of issues) {
+        if (issue.slideId !== undefined || issue.path[0] !== 'slides')
+            continue;
+        const index = issue.path[1];
+        if (typeof index !== 'number')
+            continue;
+        const slide = slides[index];
+        if (isBag(slide) && typeof slide.id === 'string')
+            issue.slideId = slide.id;
+    }
+}
+/** Validate a v2 deck: every structural, cross-field and host issue. Never throws. */
+export function parseDeck(input, options = {}) {
+    const max = options.maxIssues !== undefined && options.maxIssues > 0
+        ? Math.floor(options.maxIssues)
+        : MAX_DIAGNOSTICS;
+    const sink = new Sink(max);
+    const structural = validate(deckSchema, input, { maxIssues: max });
+    for (const issue of structural.issues)
+        sink.add(issue);
+    if (structural.truncated)
+        sink.truncated = true;
+    if (!structural.ok)
+        sink.errors = Math.max(sink.errors, 1);
+    // Partial input still gets the cross-field passes, on a bounded plain copy.
+    const tree = structural.ok
+        ? structural.value
+        : copyPlainData(input, { maxDepth: 64, maxBytes: 16 * 1024 * 1024, maxIssues: 0 }).value;
+    let steps = [];
+    try {
+        steps = crossField(tree, options, sink);
+    }
+    catch {
+        sink.report('invalid-input', 'The deck could not be checked as plain data.', []);
+    }
+    tagSlides(sink.issues, tree);
+    const ok = structural.ok && sink.errors === 0;
+    const result = { ok, issues: sink.issues, steps, truncated: sink.truncated };
+    if (ok)
+        result.deck = structural.value;
+    return result;
+}

package/dist/model/plain.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 { type DeckDiagnostic } from '../schema/index.js';
+export interface PlainCopyOptions {
+    /** Containers along one path (the root object is depth 1). Default 64. */
+    maxDepth?: number;
+    /** An estimate of the JSON size in UTF-8 bytes; the copy stops past it. Default unbounded. */
+    maxBytes?: number;
+    /** Strip hidden characters from strings and keys (and report them). Default false. */
+    strip?: boolean;
+    /** Issues kept (default 200); later ones only set `truncated`. */
+    maxIssues?: number;
+}
+export interface PlainCopyResult {
+    /** The copy; `undefined` when the root itself was refused. */
+    value: unknown;
+    issues: DeckDiagnostic[];
+    /** True when an error was reported (the copy is partial). */
+    failed: boolean;
+    truncated: boolean;
+    /** Estimated UTF-8 JSON size of the copy. */
+    bytes: number;
+}
+/**
+ * Remove hidden characters (see `isHidden`); U+2028 and U+2029 become a
+ * space. Returns the string unchanged (same reference) when nothing is hidden.
+ */
+export declare function stripHiddenCharacters(value: string): string;
+/** UTF-8 byte length without allocating. */
+export declare function utf8Length(value: string): number;
+/** Copy `input` as plain JSON data; see the module comment for what is dropped. */
+export declare function copyPlainData(input: unknown, options?: PlainCopyOptions): PlainCopyResult;