@texuli/deck 0.0.0-stage → 0.5.0

package/dist/authoring/patch.d.ts

@@ -0,0 +1,23 @@
+export type JsonPatchOperation = {
+    op: 'add' | 'replace' | 'test';
+    path: string;
+    value: unknown;
+} | {
+    op: 'remove';
+    path: string;
+} | {
+    op: 'move' | 'copy';
+    path: string;
+    from: string;
+};
+export type JsonPatchResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    index: number;
+    reason: string;
+};
+export declare const MAX_DECK_PATCH_OPERATIONS = 1000;
+/** Apply a bounded RFC 6902 patch to plain JSON data; failures leave input untouched. */
+export declare function applyDeckPatch(document: unknown, operations: readonly JsonPatchOperation[]): JsonPatchResult;

package/dist/authoring/patch.js

@@ -0,0 +1,166 @@
+export const MAX_DECK_PATCH_OPERATIONS = 1_000;
+const unsafe = new Set(['__proto__', 'prototype', 'constructor']);
+/** Apply a bounded RFC 6902 patch to plain JSON data; failures leave input untouched. */
+export function applyDeckPatch(document, operations) {
+    if (!Array.isArray(operations) || operations.length > MAX_DECK_PATCH_OPERATIONS)
+        return {
+            ok: false,
+            index: -1,
+            reason: `A patch may contain at most ${MAX_DECK_PATCH_OPERATIONS} operations.`,
+        };
+    let value;
+    try {
+        value = clone(document);
+    }
+    catch {
+        return { ok: false, index: -1, reason: 'The document must be finite plain JSON data.' };
+    }
+    for (let index = 0; index < operations.length; index++) {
+        const operation = operations[index];
+        try {
+            if (!operation ||
+                !['add', 'remove', 'replace', 'move', 'copy', 'test'].includes(operation.op))
+                throw new TypeError('Unsupported RFC 6902 operation.');
+            const path = pointer(operation.path);
+            if (operation.op === 'move' || operation.op === 'copy') {
+                const from = pointer(operation.from);
+                if (operation.op === 'move' &&
+                    path.length > from.length &&
+                    from.every((part, i) => path[i] === part))
+                    throw new TypeError('Cannot move a value into its own descendant.');
+                const got = read(value, from);
+                if (operation.op === 'move')
+                    value = mutate(value, from, 'remove');
+                value = mutate(value, path, 'add', clone(got));
+            }
+            else if (operation.op === 'test') {
+                if (!equal(read(value, path), operation.value))
+                    throw new TypeError('The test operation failed.');
+            }
+            else
+                value = mutate(value, path, operation.op, operation.op === 'remove' ? undefined : clone(operation.value));
+        }
+        catch (error) {
+            return {
+                ok: false,
+                index,
+                reason: error instanceof Error ? error.message : 'Patch operation refused.',
+            };
+        }
+    }
+    return { ok: true, value };
+}
+function pointer(value) {
+    if (typeof value !== 'string' || (value !== '' && !value.startsWith('/')))
+        throw new TypeError('A JSON Pointer must be empty or begin with /.');
+    const parts = value === ''
+        ? []
+        : value
+            .slice(1)
+            .split('/')
+            .map((part) => {
+            if (/~(?![01])/u.test(part))
+                throw new TypeError('Malformed JSON Pointer escape.');
+            const decoded = part.replace(/~1/gu, '/').replace(/~0/gu, '~');
+            if (unsafe.has(decoded))
+                throw new TypeError('Prototype-related JSON Pointer paths are refused.');
+            return decoded;
+        });
+    return parts;
+}
+function clone(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value))
+        return value.map(clone);
+    if (value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+        const result = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (unsafe.has(key))
+                throw new TypeError('Prototype-related keys are refused.');
+            result[key] = clone(child);
+        }
+        return result;
+    }
+    throw new TypeError('The document must be finite plain JSON data.');
+}
+function parentAt(root, parts) {
+    if (!parts.length)
+        throw new TypeError('The document root cannot be used as a parent path.');
+    let current = root;
+    for (const part of parts.slice(0, -1))
+        current = child(current, part);
+    if (current === null || typeof current !== 'object')
+        throw new TypeError('The JSON Pointer parent does not exist.');
+    const key = parts.at(-1);
+    if (key === undefined)
+        throw new TypeError('The JSON Pointer parent path is empty.');
+    return { parent: current, key };
+}
+function child(value, key) {
+    if (Array.isArray(value)) {
+        const index = arrayIndex(key, value.length, false);
+        return value[index];
+    }
+    if (value && typeof value === 'object' && Object.hasOwn(value, key))
+        return value[key];
+    throw new TypeError('The JSON Pointer does not exist.');
+}
+function read(root, parts) {
+    return parts.reduce(child, root);
+}
+function mutate(root, parts, operation, next) {
+    if (!parts.length) {
+        if (operation === 'remove')
+            throw new TypeError('The document root cannot be removed.');
+        return next;
+    }
+    const { parent, key } = parentAt(root, parts);
+    if (Array.isArray(parent)) {
+        const index = arrayIndex(key, parent.length, operation === 'add');
+        if (operation === 'add')
+            parent.splice(index, 0, next);
+        else if (operation === 'remove')
+            parent.splice(index, 1);
+        else {
+            if (index >= parent.length)
+                throw new TypeError('The array index does not exist.');
+            parent[index] = next;
+        }
+    }
+    else if (operation === 'add')
+        parent[key] = next;
+    else if (!Object.hasOwn(parent, key))
+        throw new TypeError('The object property does not exist.');
+    else if (operation === 'remove')
+        delete parent[key];
+    else
+        parent[key] = next;
+    return root;
+}
+function arrayIndex(value, length, allowEnd) {
+    if (value === '-' && allowEnd)
+        return length;
+    if (!/^(?:0|[1-9]\d*)$/u.test(value))
+        throw new TypeError('Invalid array index.');
+    const index = Number(value);
+    if (!Number.isSafeInteger(index) || index > length || (!allowEnd && index === length))
+        throw new TypeError('Array index is out of bounds.');
+    return index;
+}
+function equal(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (Array.isArray(left) && Array.isArray(right))
+        return left.length === right.length && left.every((value, index) => equal(value, right[index]));
+    if (left && right && typeof left === 'object' && typeof right === 'object') {
+        const a = Object.keys(left);
+        const b = Object.keys(right);
+        return (a.length === b.length &&
+            a.every((key) => Object.hasOwn(right, key) &&
+                equal(left[key], right[key])));
+    }
+    return false;
+}

package/dist/authoring/select-layouts.d.ts

@@ -0,0 +1,19 @@
+import { type DeckCatalogLayoutId, type LayoutPacing } from '../model/index.js';
+export interface LayoutRequest {
+    id: string;
+    role: string;
+    pacing?: LayoutPacing | string;
+    purpose?: string;
+    layout?: string;
+    blockTypes?: readonly string[];
+}
+export interface LayoutChoice {
+    id: string;
+    layout: DeckCatalogLayoutId | 'free';
+    rationale: string;
+    override: boolean;
+}
+/** Deterministic role/block/pacing selection; author overrides always win. */
+export declare function selectDeckLayouts(requests: readonly LayoutRequest[], options?: {
+    aspect?: string;
+}): LayoutChoice[];

package/dist/authoring/select-layouts.js

@@ -0,0 +1,90 @@
+import { DECK_LAYOUTS } from "../model/index.js";
+const roleLayouts = Object.freeze({
+    title: ['title-hero'],
+    agenda: ['section-divider', 'process-steps'],
+    close: ['closing-cta'],
+    ask: ['closing-cta'],
+    section: ['section-divider'],
+    hook: ['title-hero', 'big-stat', 'quote'],
+    problem: ['two-column-split', 'image-left'],
+    solution: ['three-column-cards', 'process-steps'],
+    metrics: ['big-stat', 'chart'],
+    chart: ['chart', 'big-stat'],
+    comparison: ['comparison-table'],
+    team: ['team-avatars'],
+    quote: ['quote'],
+    steps: ['process-steps'],
+    timeline: ['timeline'],
+    roadmap: ['timeline', 'process-steps'],
+    code: ['code-with-callout'],
+    demo: ['image-centered', 'video-centered'],
+    findings: ['three-column-cards', 'chart'],
+    risks: ['two-column-split'],
+    recommendations: ['process-steps'],
+});
+const blockLayouts = Object.freeze({
+    chart: ['chart'],
+    table: ['comparison-table'],
+    steps: ['process-steps'],
+    timeline: ['timeline'],
+    quote: ['quote'],
+    code: ['code-with-callout'],
+    image: ['image-centered', 'image-left'],
+    video: ['video-centered', 'video-left'],
+    stat: ['big-stat'],
+});
+const pacingLayouts = Object.freeze({
+    punch: ['big-stat', 'quote', 'section-divider', 'free'],
+    idea: ['two-column-split', 'three-column-cards', 'process-steps', 'free'],
+    diagram: ['process-steps', 'timeline', 'chart', 'comparison-table', 'free'],
+    story: ['timeline', 'process-steps', 'quote', 'image-full-bleed', 'free'],
+});
+/** Deterministic role/block/pacing selection; author overrides always win. */
+export function selectDeckLayouts(requests, options = {}) {
+    const choices = [];
+    const previous = [];
+    for (const request of requests) {
+        const override = request.layout?.trim();
+        if (override && (override === 'free' || Object.hasOwn(DECK_LAYOUTS, override))) {
+            choices.push({
+                id: request.id,
+                layout: override,
+                rationale: `Author override: layout "${override}".`,
+                override: true,
+            });
+            previous.push(override);
+            continue;
+        }
+        const pacing = normalizePacing(request.pacing);
+        const role = roleLayouts[request.role.trim().toLowerCase()] ?? [];
+        const block = (request.blockTypes ?? []).flatMap((type) => blockLayouts[type] ?? []);
+        const candidates = unique([...block, ...role, ...pacingLayouts[pacing], 'free']).filter((id) => id === 'free' ||
+            DECK_LAYOUTS[id].pacing.includes(pacing) ||
+            role.includes(id) ||
+            block.includes(id));
+        let chosen = candidates[0] ?? 'free';
+        let avoidedRepeat = false;
+        if (previous.length >= 2 && previous.at(-1) === previous.at(-2) && previous.at(-1) === chosen) {
+            const alternate = candidates.find((candidate) => candidate !== chosen);
+            if (alternate) {
+                chosen = alternate;
+                avoidedRepeat = true;
+            }
+        }
+        const label = chosen === 'free' ? 'Free slide' : DECK_LAYOUTS[chosen].label;
+        choices.push({
+            id: request.id,
+            layout: chosen,
+            rationale: `Role "${request.role}" with pacing "${pacing}"; fits catalog "${chosen}" (${label})${avoidedRepeat ? '; avoided a third identical layout in a row' : ''}${options.aspect && options.aspect !== '16:9' ? `; aspect ${options.aspect}` : ''}.`,
+            override: false,
+        });
+        previous.push(chosen);
+    }
+    return choices;
+}
+function normalizePacing(value) {
+    return value === 'punch' || value === 'diagram' || value === 'story' ? value : 'idea';
+}
+function unique(values) {
+    return [...new Set(values)];
+}

package/dist/engine/auto-slide.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Injectable, deterministic auto-slide scheduler.
+ *
+ * Pure with respect to the clock: pass a {@link SchedulerClock} in tests.
+ * User input pauses the timer (`input()`); `resume()` starts it again.
+ * No DOM. The default clock reads `globalThis` only when a method is called.
+ */
+export interface SchedulerClock {
+    setTimeout(callback: () => void, delayMs: number): unknown;
+    clearTimeout(handle: unknown): void;
+    now(): number;
+}
+export interface AutoSlideOptions {
+    /** Interval in ms; clamped to 1_000…600_000. */
+    intervalMs: number;
+    /** Called when the timer fires (typically `controller.next({ source: 'auto' })`). */
+    onAdvance(): void;
+    clock?: SchedulerClock;
+    /** Start paused (the host calls `resume()` when ready). */
+    startPaused?: boolean;
+}
+export interface AutoSlideScheduler {
+    start(): void;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    isPaused(): boolean;
+    isRunning(): boolean;
+    /** User input: pause and clear the pending tick. */
+    input(): void;
+}
+export declare function createAutoSlideScheduler(options: AutoSlideOptions): AutoSlideScheduler;

package/dist/engine/auto-slide.js

@@ -0,0 +1,67 @@
+/**
+ * Injectable, deterministic auto-slide scheduler.
+ *
+ * Pure with respect to the clock: pass a {@link SchedulerClock} in tests.
+ * User input pauses the timer (`input()`); `resume()` starts it again.
+ * No DOM. The default clock reads `globalThis` only when a method is called.
+ */
+const MIN_MS = 1_000;
+const MAX_MS = 600_000;
+const defaultClock = {
+    setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+    clearTimeout: (handle) => {
+        globalThis.clearTimeout(handle);
+    },
+    now: () => Date.now(),
+};
+export function createAutoSlideScheduler(options) {
+    const clock = options.clock ?? defaultClock;
+    const interval = Math.max(MIN_MS, Math.min(MAX_MS, Math.floor(Number.isFinite(options.intervalMs) ? options.intervalMs : MIN_MS)));
+    let timer;
+    let paused = options.startPaused === true;
+    let stopped = true;
+    const clear = () => {
+        if (timer !== undefined) {
+            clock.clearTimeout(timer);
+            timer = undefined;
+        }
+    };
+    const schedule = () => {
+        clear();
+        if (stopped || paused)
+            return;
+        timer = clock.setTimeout(() => {
+            timer = undefined;
+            if (stopped || paused)
+                return;
+            options.onAdvance();
+            schedule();
+        }, interval);
+    };
+    return {
+        start() {
+            stopped = false;
+            schedule();
+        },
+        pause() {
+            paused = true;
+            clear();
+        },
+        resume() {
+            if (stopped)
+                return;
+            paused = false;
+            schedule();
+        },
+        stop() {
+            stopped = true;
+            clear();
+        },
+        isPaused: () => paused,
+        isRunning: () => !stopped && !paused && timer !== undefined,
+        input() {
+            paused = true;
+            clear();
+        },
+    };
+}

package/dist/engine/canvas.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Virtual canvas fit and letterboxing. Independent of browser globals.
+ *
+ * Aspects: 16:9 → 1280×720, 4:3 → 1024×768, 9:16 → 720×1280, 1:1 → 1080×1080.
+ * `fit: 'contain' | 'container'` letterboxes; `cover` fills and may crop.
+ */
+export declare const DECK_ASPECTS: readonly ["16:9", "4:3", "9:16", "1:1"];
+export type DeckAspect = (typeof DECK_ASPECTS)[number];
+export declare const DEFAULT_DECK_ASPECT: DeckAspect;
+export declare const DECK_CANVAS: Readonly<{
+    readonly '16:9': Readonly<{
+        width: 1280;
+        height: 720;
+    }>;
+    readonly '4:3': Readonly<{
+        width: 1024;
+        height: 768;
+    }>;
+    readonly '9:16': Readonly<{
+        width: 720;
+        height: 1280;
+    }>;
+    readonly '1:1': Readonly<{
+        width: 1080;
+        height: 1080;
+    }>;
+}>;
+export type DeckCanvasSize = Readonly<{
+    width: number;
+    height: number;
+}>;
+export type DeckFitMode = 'contain' | 'cover' | 'container';
+export interface CanvasFit {
+    /** Uniform scale applied to the virtual canvas. */
+    scale: number;
+    /** Rendered width after scale (CSS px). */
+    width: number;
+    /** Rendered height after scale (CSS px). */
+    height: number;
+    /** Letterbox offset on the inline axis. */
+    offsetX: number;
+    /** Letterbox offset on the block axis. */
+    offsetY: number;
+    canvasWidth: number;
+    canvasHeight: number;
+    aspect: DeckAspect;
+    fit: DeckFitMode;
+}
+export declare function isDeckAspect(value: unknown): value is DeckAspect;
+/** The virtual canvas size for an aspect; unknown values fall back to 16:9. */
+export declare function deckCanvasSize(aspect?: unknown): DeckCanvasSize;
+/**
+ * Scale and letterbox a virtual canvas inside a container.
+ * `container` is an alias of `contain` for embedded decks.
+ */
+export declare function fitDeckCanvas(containerWidth: number, containerHeight: number, aspect?: unknown, fit?: DeckFitMode): CanvasFit;

package/dist/engine/canvas.js

@@ -0,0 +1,48 @@
+/**
+ * Virtual canvas fit and letterboxing. Independent of browser globals.
+ *
+ * Aspects: 16:9 → 1280×720, 4:3 → 1024×768, 9:16 → 720×1280, 1:1 → 1080×1080.
+ * `fit: 'contain' | 'container'` letterboxes; `cover` fills and may crop.
+ */
+export const DECK_ASPECTS = ['16:9', '4:3', '9:16', '1:1'];
+export const DEFAULT_DECK_ASPECT = '16:9';
+export const DECK_CANVAS = Object.freeze({
+    '16:9': Object.freeze({ width: 1280, height: 720 }),
+    '4:3': Object.freeze({ width: 1024, height: 768 }),
+    '9:16': Object.freeze({ width: 720, height: 1280 }),
+    '1:1': Object.freeze({ width: 1080, height: 1080 }),
+});
+export function isDeckAspect(value) {
+    return typeof value === 'string' && DECK_ASPECTS.includes(value);
+}
+/** The virtual canvas size for an aspect; unknown values fall back to 16:9. */
+export function deckCanvasSize(aspect = DEFAULT_DECK_ASPECT) {
+    return DECK_CANVAS[isDeckAspect(aspect) ? aspect : DEFAULT_DECK_ASPECT];
+}
+/**
+ * Scale and letterbox a virtual canvas inside a container.
+ * `container` is an alias of `contain` for embedded decks.
+ */
+export function fitDeckCanvas(containerWidth, containerHeight, aspect = DEFAULT_DECK_ASPECT, fit = 'contain') {
+    const resolvedAspect = isDeckAspect(aspect) ? aspect : DEFAULT_DECK_ASPECT;
+    const canvas = DECK_CANVAS[resolvedAspect];
+    const width = Number.isFinite(containerWidth) ? Math.max(0, containerWidth) : 0;
+    const height = Number.isFinite(containerHeight) ? Math.max(0, containerHeight) : 0;
+    const mode = fit === 'cover' ? 'cover' : fit === 'container' ? 'container' : 'contain';
+    const sx = canvas.width > 0 ? width / canvas.width : 0;
+    const sy = canvas.height > 0 ? height / canvas.height : 0;
+    const scale = mode === 'cover' ? Math.max(sx, sy) : Math.min(sx, sy);
+    const renderedWidth = canvas.width * scale;
+    const renderedHeight = canvas.height * scale;
+    return {
+        scale,
+        width: renderedWidth,
+        height: renderedHeight,
+        offsetX: (width - renderedWidth) / 2,
+        offsetY: (height - renderedHeight) / 2,
+        canvasWidth: canvas.width,
+        canvasHeight: canvas.height,
+        aspect: resolvedAspect,
+        fit: mode,
+    };
+}

package/dist/engine/controller.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Imperative framework-free controller with typed events and ordered plugin hooks.
+ *
+ * `createDeckController(deck, options)` owns navigation, overview/blackout/pause
+ * flags, optional auto-slide, and routes `handleInput` through `decideDeckInput`.
+ * Stage chrome (help, laser, fullscreen, presenter window) stays with the host:
+ * the controller emits the action and leaves rendering to the stage.
+ */
+import { type SchedulerClock } from './auto-slide.js';
+import { type DeckAction, type DeckInputEvent, type DeckInputState } from './controls.js';
+import { type DeckLocation, type EngineDeck, type EngineSlide, type NavigatorOptions } from './navigation.js';
+export interface DeckState extends DeckLocation {
+    overview: boolean;
+    blackout: boolean;
+    paused: boolean;
+}
+export type DeckActionSource = 'api' | 'keyboard' | 'pointer' | 'swipe' | 'auto' | 'presenter' | 'route';
+export interface DeckStateChange {
+    state: DeckState;
+    previous: DeckState;
+    source: DeckActionSource;
+}
+/** Read-only context the stage passes around a paint (plugins may observe only). */
+export interface DeckRenderContext {
+    state: DeckState;
+    /** The slide at `state.slideIndex`, when the deck still has it. */
+    slide?: EngineSlide;
+    source?: DeckActionSource;
+}
+export type DeckEventMap = {
+    slidechange: DeckStateChange;
+    stepchange: DeckStateChange;
+    statechange: DeckStateChange;
+    overview: {
+        open: boolean;
+        state: DeckState;
+    };
+    blackout: {
+        active: boolean;
+        state: DeckState;
+    };
+    pause: {
+        paused: boolean;
+        state: DeckState;
+    };
+    action: {
+        action: DeckAction;
+        source: DeckActionSource;
+    };
+    destroy: {
+        state: DeckState;
+    };
+};
+export type DeckEventName = keyof DeckEventMap;
+export type DeckListener<K extends DeckEventName> = (detail: DeckEventMap[K]) => void;
+/** Plugin beforeNavigate result: cancel, redirect, or continue (void/undefined). */
+export type BeforeNavigateResult = boolean | DeckLocation | undefined;
+export interface DeckPlugin {
+    name: string;
+    /** Called once after the controller is built; may return a cleanup. */
+    setup?(controller: DeckController): undefined | (() => void);
+    /**
+     * Return `false` to cancel, a location to redirect, or void to continue.
+     * Plugins run in registration order.
+     */
+    beforeNavigate?(target: string | number | DeckLocation, current: DeckState): // Plugins may return bare void to continue.
+    BeforeNavigateResult | void;
+    afterNavigate?(state: DeckState, previous: DeckState): void;
+    /**
+     * Called by the stage immediately before a paint. Read-only: plugins must
+     * not inject HTML or mutate the model. Runs in registration order.
+     */
+    beforeRender?(context: DeckRenderContext): void;
+    /**
+     * Called by the stage immediately after a paint. Runs in registration order.
+     */
+    afterRender?(context: DeckRenderContext): void;
+    onAction?(action: DeckAction, source: DeckActionSource): void;
+    onDestroy?(): void;
+}
+export interface DeckControllerOptions extends NavigatorOptions {
+    plugins?: readonly DeckPlugin[];
+    /** Override deck.navigation.autoSlideMs; 0 or omitted disables. */
+    autoSlideMs?: number;
+    clock?: SchedulerClock;
+    /** Start the auto-slide scheduler paused. */
+    autoSlidePaused?: boolean;
+}
+export interface DeckController {
+    goTo(target: string | number | DeckLocation, options?: {
+        source?: DeckActionSource;
+    }): DeckState;
+    next(options?: {
+        source?: DeckActionSource;
+    }): DeckState;
+    prev(options?: {
+        source?: DeckActionSource;
+    }): DeckState;
+    first(options?: {
+        source?: DeckActionSource;
+    }): DeckState;
+    last(options?: {
+        source?: DeckActionSource;
+    }): DeckState;
+    getState(): DeckState;
+    subscribe(listener: (state: DeckState, previous: DeckState) => void): () => void;
+    subscribe<K extends DeckEventName>(event: K, listener: DeckListener<K>): () => void;
+    setOverview(open: boolean): void;
+    setBlackout(active: boolean): void;
+    pause(): void;
+    resume(): void;
+    handleInput(event: DeckInputEvent, state?: DeckInputState, source?: DeckActionSource): DeckAction | null;
+    /**
+     * Stage calls this immediately before painting. Invokes each plugin's
+     * `beforeRender` in registration order with a read-only context.
+     */
+    beforeRender(context?: Partial<Omit<DeckRenderContext, 'state'>>): void;
+    /**
+     * Stage calls this immediately after painting. Invokes each plugin's
+     * `afterRender` in registration order.
+     */
+    afterRender(context?: Partial<Omit<DeckRenderContext, 'state'>>): void;
+    destroy(): void;
+}
+export declare function createDeckController(deck: EngineDeck, options?: DeckControllerOptions): DeckController;
+export type { EngineSlide };