@texuli/deck 0.0.0-stage → 0.5.0

package/dist/engine/controls.js

@@ -0,0 +1,460 @@
+/**
+ * Controls registry and pure input decisions.
+ *
+ * `DECK_CONTROLS` is the single source for the toolbar, help dialog and
+ * `decideDeckInput` key map. No DOM: the host describes the event target as a
+ * path of plain element facts (`inputPathFrom` builds it from a real path).
+ *
+ * Keys (Protoyard registry + Texuli Enter/Backspace):
+ * → ↓ PageDown Space Enter / ← ↑ PageUp Shift+Space Backspace, Home/End,
+ * O, F, S|P, B|., L, ?, Ctrl/⌘+P, D, Esc stack.
+ * Swipe: ≥50 px, 1.5× dominance, <800 ms.
+ */
+export const DECK_INPUT_ACTIONS = [
+    'next',
+    'prev',
+    'first',
+    'last',
+    'overview',
+    'presenter',
+    'fullscreen',
+    'blackout',
+    'laser',
+    'help',
+    'print',
+    'fullscreen-exit',
+    'copy-link',
+    'jump',
+    'debug',
+];
+export const DECK_CONTROL_GROUPS = [
+    'navigate',
+    'view',
+    'present',
+    'share',
+    'help',
+    'debug',
+];
+export const DECK_CONTROL_CAPABILITIES = [
+    'fullscreen',
+    'popup',
+    'clipboard',
+    'print',
+    'debug',
+];
+export const DEFAULT_DECK_CONTROL_ENVIRONMENT = Object.freeze({
+    fullscreen: true,
+    popup: true,
+    clipboard: true,
+    print: true,
+    debug: false,
+});
+const ESC = { key: 'Escape', label: 'Esc', closes: true };
+function control(spec) {
+    const requires = Object.freeze([...(spec.requires ?? [])]);
+    return Object.freeze({
+        action: spec.action,
+        group: spec.group,
+        labelKey: spec.labelKey,
+        descriptionKey: spec.descriptionKey,
+        keys: Object.freeze(spec.keys.map((key) => Object.freeze({ ...key }))),
+        toggle: spec.toggle,
+        requires,
+        available: (env) => requires.every((need) => env[need] === true),
+    });
+}
+/** Every deck control, in display order. */
+export const DECK_CONTROLS = Object.freeze([
+    control({
+        action: 'prev',
+        group: 'navigate',
+        labelKey: 'controls.previous',
+        descriptionKey: 'controls.previousDescription',
+        keys: [
+            { key: 'ArrowLeft', label: '←' },
+            { key: 'ArrowUp', label: '↑' },
+            { key: 'PageUp', label: 'Page Up' },
+            { key: ' ', label: 'Shift + Space', shift: 'required' },
+            { key: 'Backspace', label: 'Backspace' },
+        ],
+        toggle: false,
+    }),
+    control({
+        action: 'jump',
+        group: 'navigate',
+        labelKey: 'controls.chooseSlide',
+        descriptionKey: 'controls.chooseSlideDescription',
+        keys: [],
+        toggle: false,
+    }),
+    control({
+        action: 'next',
+        group: 'navigate',
+        labelKey: 'controls.next',
+        descriptionKey: 'controls.nextDescription',
+        keys: [
+            { key: 'ArrowRight', label: '→' },
+            { key: 'ArrowDown', label: '↓' },
+            { key: 'PageDown', label: 'Page Down' },
+            { key: ' ', label: 'Space' },
+            { key: 'Enter', label: 'Enter' },
+        ],
+        toggle: false,
+    }),
+    control({
+        action: 'first',
+        group: 'navigate',
+        labelKey: 'controls.first',
+        descriptionKey: 'controls.firstDescription',
+        keys: [{ key: 'Home', label: 'Home' }],
+        toggle: false,
+    }),
+    control({
+        action: 'last',
+        group: 'navigate',
+        labelKey: 'controls.last',
+        descriptionKey: 'controls.lastDescription',
+        keys: [{ key: 'End', label: 'End' }],
+        toggle: false,
+    }),
+    control({
+        action: 'overview',
+        group: 'view',
+        labelKey: 'controls.overview',
+        descriptionKey: 'controls.overviewDescription',
+        keys: [{ key: 'o', label: 'O' }, ESC],
+        toggle: true,
+    }),
+    control({
+        action: 'fullscreen',
+        group: 'view',
+        labelKey: 'controls.fullscreen',
+        descriptionKey: 'controls.fullscreenDescription',
+        keys: [{ key: 'f', label: 'F' }],
+        toggle: true,
+        requires: ['fullscreen'],
+    }),
+    control({
+        action: 'fullscreen-exit',
+        group: 'view',
+        labelKey: 'controls.leaveFullscreen',
+        descriptionKey: 'controls.leaveFullscreenDescription',
+        keys: [ESC],
+        toggle: false,
+        requires: ['fullscreen'],
+    }),
+    control({
+        action: 'presenter',
+        group: 'present',
+        labelKey: 'controls.presenter',
+        descriptionKey: 'controls.presenterDescription',
+        keys: [
+            { key: 's', label: 'S' },
+            { key: 'p', label: 'P' },
+        ],
+        toggle: true,
+    }),
+    control({
+        action: 'blackout',
+        group: 'present',
+        labelKey: 'controls.blackout',
+        descriptionKey: 'controls.blackoutDescription',
+        keys: [{ key: 'b', label: 'B' }, { key: '.', label: '.' }, ESC],
+        toggle: true,
+    }),
+    control({
+        action: 'laser',
+        group: 'present',
+        labelKey: 'controls.laser',
+        descriptionKey: 'controls.laserDescription',
+        keys: [{ key: 'l', label: 'L' }, ESC],
+        toggle: true,
+    }),
+    control({
+        action: 'copy-link',
+        group: 'share',
+        labelKey: 'controls.copyLink',
+        descriptionKey: 'controls.copyLinkDescription',
+        keys: [],
+        toggle: false,
+        requires: ['clipboard'],
+    }),
+    control({
+        action: 'print',
+        group: 'share',
+        labelKey: 'controls.print',
+        descriptionKey: 'controls.printDescription',
+        keys: [
+            { key: 'p', label: 'Ctrl + P', modifier: 'ctrl' },
+            { key: 'p', label: '⌘ + P', modifier: 'meta' },
+        ],
+        toggle: false,
+        requires: ['print'],
+    }),
+    control({
+        action: 'help',
+        group: 'help',
+        labelKey: 'controls.help',
+        descriptionKey: 'controls.helpDescription',
+        keys: [{ key: '?', label: '?', shift: 'allowed' }, ESC],
+        toggle: true,
+    }),
+    control({
+        action: 'debug',
+        group: 'debug',
+        labelKey: 'controls.debug',
+        descriptionKey: 'controls.debugDescription',
+        keys: [{ key: 'd', label: 'D' }, ESC],
+        toggle: true,
+        requires: ['debug'],
+    }),
+]);
+const BY_ACTION = new Map(DECK_CONTROLS.map((item) => [item.action, item]));
+/** Look up a control by action. Throws when the action is unknown. */
+export function deckControlFor(action) {
+    const found = BY_ACTION.get(action);
+    if (!found)
+        throw new RangeError(`No deck control for the action "${action}".`);
+    return found;
+}
+/** The controls that work in `env`, in display order. */
+export function availableDeckControls(env = DEFAULT_DECK_CONTROL_ENVIRONMENT) {
+    return DECK_CONTROLS.filter((item) => item.available(env));
+}
+/** Help-dialog rows for the controls available in `env`. */
+export function deckKeyBindings(env = DEFAULT_DECK_CONTROL_ENVIRONMENT) {
+    return availableDeckControls(env)
+        .filter((item) => item.keys.length > 0)
+        .map((item) => ({
+        keys: item.keys.map((key) => key.label),
+        action: item.action,
+        labelKey: item.labelKey,
+    }));
+}
+/** Default-environment key bindings (debug omitted). */
+export const DECK_KEY_BINDINGS = Object.freeze(deckKeyBindings(DEFAULT_DECK_CONTROL_ENVIRONMENT));
+/** A swipe must travel this far (CSS px) along its axis. */
+export const DECK_SWIPE_MIN_DISTANCE = 50;
+/** …and be this much longer on its axis than across it (axis lock). */
+export const DECK_SWIPE_AXIS_RATIO = 1.5;
+/** Slower drags are not swipes (they are reading or selecting). */
+export const DECK_SWIPE_MAX_DURATION_MS = 800;
+/** Interactive blocks put this on their root so clicks/swipes never move the deck. */
+export const DECK_INTERACTIVE_ATTRIBUTE = 'data-tx-deck-interactive';
+/** Deck chrome (progress, slide number, toolbar) carries this attribute. */
+export const DECK_CHROME_ATTRIBUTE = 'data-tx-deck-chrome';
+const EDITABLE_TAGS = new Set(['input', 'textarea', 'select']);
+const CONTROL_TAGS = new Set([
+    'a',
+    'button',
+    'input',
+    'textarea',
+    'select',
+    'option',
+    'label',
+    'summary',
+    'details',
+    'iframe',
+    'video',
+    'audio',
+    'object',
+    'embed',
+]);
+const CONTROL_ROLES = new Set([
+    'button',
+    'link',
+    'checkbox',
+    'radio',
+    'switch',
+    'slider',
+    'spinbutton',
+    'tab',
+    'menuitem',
+    'option',
+    'textbox',
+    'combobox',
+    'listbox',
+    'scrollbar',
+]);
+const hasAttribute = (target, name) => target.attributes?.includes(name) === true;
+const isEditable = (target) => EDITABLE_TAGS.has(target.tag) || target.editable === true || target.role === 'textbox';
+function isGuardedTarget(path) {
+    return path.some((target) => CONTROL_TAGS.has(target.tag) ||
+        target.href === true ||
+        target.editable === true ||
+        (target.role !== undefined && CONTROL_ROLES.has(target.role)) ||
+        hasAttribute(target, DECK_INTERACTIVE_ATTRIBUTE) ||
+        hasAttribute(target, DECK_CHROME_ATTRIBUTE));
+}
+const anyModifier = (event) => event.ctrlKey === true ||
+    event.metaKey === true ||
+    event.altKey === true ||
+    event.shiftKey === true;
+/** Keys derived from the registry (never typed twice). */
+const NAVIGATION_KEYS = {};
+const SHIFTED_NAVIGATION_KEYS = {};
+const TOGGLE_KEYS = {};
+const SHIFT_ALLOWED_TOGGLES = new Set();
+const MODIFIER_KEYS = {};
+for (const item of DECK_CONTROLS) {
+    for (const spec of item.keys) {
+        if (spec.closes)
+            continue;
+        const key = spec.key.length === 1 ? spec.key.toLowerCase() : spec.key;
+        if (spec.modifier) {
+            MODIFIER_KEYS[key] = item.action;
+        }
+        else if (item.group === 'navigate') {
+            const table = spec.shift === 'required' ? SHIFTED_NAVIGATION_KEYS : NAVIGATION_KEYS;
+            // Navigation keys keep their KeyboardEvent.key form (ArrowRight, ' ').
+            table[spec.key] = item.action;
+        }
+        else {
+            TOGGLE_KEYS[key] = item.action;
+            if (spec.shift === 'allowed')
+                SHIFT_ALLOWED_TOGGLES.add(key);
+        }
+    }
+}
+const ESCAPE_ORDER = [
+    ['debug', (state) => state.debug === true],
+    ['help', (state) => state.help === true],
+    ['overview', (state) => state.overview === 'open'],
+    ['blackout', (state) => state.blackout === true],
+    ['laser', (state) => state.laser === true],
+    ['fullscreen-exit', (state) => state.fullscreen === true],
+];
+/** The actions Esc can reach, innermost first. */
+export const DECK_ESCAPE_ORDER = ESCAPE_ORDER.map(([action]) => action);
+function decideKey(event, state) {
+    if (event.isComposing)
+        return null;
+    const path = event.path ?? [];
+    if (path.some(isEditable))
+        return null;
+    let key = event.key;
+    const lower = key.length === 1 ? key.toLowerCase() : key;
+    // RTL: flip horizontal arrows before the registry lookup.
+    if (state.dir === 'rtl') {
+        if (key === 'ArrowLeft')
+            key = 'ArrowRight';
+        else if (key === 'ArrowRight')
+            key = 'ArrowLeft';
+    }
+    const shortcut = MODIFIER_KEYS[lower];
+    if ((event.ctrlKey || event.metaKey) && !event.altKey && shortcut) {
+        return event.repeat ? null : shortcut;
+    }
+    if (event.ctrlKey || event.metaKey || event.altKey)
+        return null;
+    if (key === 'Escape') {
+        if (event.repeat)
+            return null;
+        return ESCAPE_ORDER.find(([, isOn]) => isOn(state))?.[0] ?? null;
+    }
+    const found = TOGGLE_KEYS[lower];
+    const toggle = found === 'debug' && state.debugAvailable !== true ? undefined : found;
+    if (toggle && (SHIFT_ALLOWED_TOGGLES.has(lower) || !event.shiftKey)) {
+        if (event.repeat)
+            return null;
+        if (state.overview === 'closing')
+            return null;
+        if (state.help)
+            return toggle === 'help' ? 'help' : null;
+        if (state.overview === 'open')
+            return toggle === 'overview' ? 'overview' : null;
+        if (state.blackout)
+            return toggle === 'blackout' ? 'blackout' : null;
+        return toggle;
+    }
+    const plain = NAVIGATION_KEYS[key];
+    const shifted = SHIFTED_NAVIGATION_KEYS[key];
+    if (!plain && !shifted)
+        return null;
+    if (state.overview === 'open' || state.overview === 'closing' || state.help || state.blackout) {
+        return null;
+    }
+    if (isGuardedTarget(path))
+        return null;
+    if (event.shiftKey)
+        return shifted ?? null;
+    return plain ?? null;
+}
+function decideClick(event, state) {
+    if ((event.button ?? 0) !== 0)
+        return null;
+    if (anyModifier(event))
+        return null;
+    if (state.overview === 'open' || state.overview === 'closing')
+        return null;
+    if (state.help || state.blackout || state.laser)
+        return null;
+    if ((event.selectionLength ?? 0) > 0)
+        return null;
+    if (isGuardedTarget(event.path ?? []))
+        return null;
+    return 'next';
+}
+function decideSwipe(event, state) {
+    if (event.pointerType === 'mouse')
+        return null;
+    if (!Number.isFinite(event.dx) || !Number.isFinite(event.dy))
+        return null;
+    if (state.overview === 'open' || state.overview === 'closing')
+        return null;
+    if (state.help || state.blackout)
+        return null;
+    if (isGuardedTarget(event.path ?? []))
+        return null;
+    if ((event.durationMs ?? 0) >= DECK_SWIPE_MAX_DURATION_MS)
+        return null; // reject at == max (< 800 ms)
+    const ax = Math.abs(event.dx);
+    const ay = Math.abs(event.dy);
+    if (ax < DECK_SWIPE_MIN_DISTANCE || ax < ay * DECK_SWIPE_AXIS_RATIO)
+        return null;
+    // RTL: a swipe left still means "forward" in reading order? Keep physical
+    // direction (left = next) so the gesture matches the slide motion.
+    return event.dx < 0 ? 'next' : 'prev';
+}
+/** The action an input event asks for, or `null` when the deck should ignore it. */
+export function decideDeckInput(event, state = {}) {
+    switch (event.kind) {
+        case 'key':
+            return decideKey(event, state);
+        case 'click':
+            return decideClick(event, state);
+        case 'swipe':
+            return decideSwipe(event, state);
+        default:
+            return null;
+    }
+}
+const WATCHED_ATTRIBUTES = [DECK_INTERACTIVE_ATTRIBUTE, DECK_CHROME_ATTRIBUTE];
+/**
+ * Turns an event path (`event.composedPath()`, innermost first) into the
+ * plain targets `decideDeckInput` reads. Non-elements are skipped; the walk
+ * stops at `stopAt` (the deck root) when given.
+ */
+export function inputPathFrom(nodes, stopAt) {
+    const out = [];
+    for (const node of nodes) {
+        if (stopAt !== undefined && node === stopAt)
+            break;
+        const el = node;
+        if (!el || typeof el.tagName !== 'string' || typeof el.getAttribute !== 'function')
+            continue;
+        const tag = el.tagName.toLowerCase();
+        const role = el.getAttribute('role') ?? undefined;
+        const attributes = WATCHED_ATTRIBUTES.filter((name) => typeof el.hasAttribute === 'function'
+            ? el.hasAttribute(name)
+            : el.getAttribute?.(name) !== null);
+        out.push({
+            tag,
+            ...(role ? { role } : {}),
+            ...(el.isContentEditable === true ? { editable: true } : {}),
+            ...(tag === 'a' && el.getAttribute('href') !== null ? { href: true } : {}),
+            ...(attributes.length > 0 ? { attributes } : {}),
+        });
+    }
+    return out;
+}

package/dist/engine/hash.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure hash route parsing and formatting. Browser `location` is owned by hosts.
+ *
+ * Format: `#/<slide-id>/<step>` where `slide-id` is a lowercase slug and
+ * `step` is a non-negative integer ≤ 32. Hostile input (traversal, uppercase,
+ * percent-encoding, query/fragment inside the hash) yields `null`.
+ * Print and notes flags live on the search string: `?print=1&notes=1`.
+ */
+import type { DeckLocation } from './navigation.js';
+/** Maximum slide-id length accepted in a hash (matches model slug bound). */
+export declare const DECK_HASH_ID_MAX = 64;
+/** Maximum step index accepted in a hash (matches deck step cap). */
+export declare const DECK_HASH_STEP_MAX = 32;
+export interface DeckHashLocation {
+    slideId: string;
+    step: number;
+}
+export interface DeckRouteFlags {
+    print: boolean;
+    notes: boolean;
+}
+export interface ParsedDeckRoute {
+    location: DeckHashLocation | null;
+    flags: DeckRouteFlags;
+}
+/**
+ * Parse a deck deep link. Accepts `#/id/step`, `#/id`, `/id/step`, or `id/step`.
+ * Returns `null` for empty, hostile, or malformed input (never throws).
+ */
+export declare function parseDeckHash(raw: string | null | undefined): DeckHashLocation | null;
+/**
+ * Format a deck deep link as `#/<slide-id>/<step>`. Clamps step to 0…32.
+ * Returns `#/` when the id is empty or invalid.
+ */
+export declare function formatDeckHash(slideId: string, step?: number): string;
+/** Parse hash + search into a location and the print/notes flags. */
+export declare function parseDeckRoute(hash: string | null | undefined, search?: string): ParsedDeckRoute;
+/**
+ * Format a route string. Flags become a leading query string when set:
+ * `?print=1&notes=1#/slide/0`.
+ */
+export declare function formatDeckRoute(location: Pick<DeckLocation, 'slideId' | 'step'> | DeckHashLocation, flags?: Partial<DeckRouteFlags>): string;

package/dist/engine/hash.js

@@ -0,0 +1,86 @@
+/**
+ * Pure hash route parsing and formatting. Browser `location` is owned by hosts.
+ *
+ * Format: `#/<slide-id>/<step>` where `slide-id` is a lowercase slug and
+ * `step` is a non-negative integer ≤ 32. Hostile input (traversal, uppercase,
+ * percent-encoding, query/fragment inside the hash) yields `null`.
+ * Print and notes flags live on the search string: `?print=1&notes=1`.
+ */
+/** Maximum slide-id length accepted in a hash (matches model slug bound). */
+export const DECK_HASH_ID_MAX = 64;
+/** Maximum step index accepted in a hash (matches deck step cap). */
+export const DECK_HASH_STEP_MAX = 32;
+const SLIDE_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/**
+ * Parse a deck deep link. Accepts `#/id/step`, `#/id`, `/id/step`, or `id/step`.
+ * Returns `null` for empty, hostile, or malformed input (never throws).
+ */
+export function parseDeckHash(raw) {
+    if (typeof raw !== 'string' || raw.length === 0 || raw.length > 256)
+        return null;
+    let value = raw.startsWith('#') ? raw.slice(1) : raw;
+    if (value.startsWith('/'))
+        value = value.slice(1);
+    if (value.includes('?') ||
+        value.includes('#') ||
+        value.includes('\\') ||
+        value.includes('..') ||
+        value.includes('//') ||
+        value.includes('%')) {
+        return null;
+    }
+    const parts = value.split('/');
+    if (parts.length < 1 || parts.length > 2)
+        return null;
+    const slideId = parts[0] ?? '';
+    if (!SLIDE_ID.test(slideId) || slideId.length > DECK_HASH_ID_MAX)
+        return null;
+    if (parts.length === 1)
+        return { slideId, step: 0 };
+    const stepRaw = parts[1] ?? '';
+    if (!/^\d{1,3}$/.test(stepRaw))
+        return null;
+    const step = Number(stepRaw);
+    if (!Number.isInteger(step) || step < 0 || step > DECK_HASH_STEP_MAX)
+        return null;
+    return { slideId, step };
+}
+/**
+ * Format a deck deep link as `#/<slide-id>/<step>`. Clamps step to 0…32.
+ * Returns `#/` when the id is empty or invalid.
+ */
+export function formatDeckHash(slideId, step = 0) {
+    const id = typeof slideId === 'string' && SLIDE_ID.test(slideId) ? slideId : '';
+    const safeStep = Number.isFinite(step)
+        ? Math.max(0, Math.min(DECK_HASH_STEP_MAX, Math.floor(step)))
+        : 0;
+    if (!id)
+        return '#/';
+    return `#/${id}/${safeStep}`;
+}
+/** Parse hash + search into a location and the print/notes flags. */
+export function parseDeckRoute(hash, search = '') {
+    const raw = typeof search === 'string' ? search : '';
+    const params = new URLSearchParams(raw.startsWith('?') ? raw.slice(1) : raw);
+    return {
+        location: parseDeckHash(hash),
+        flags: {
+            print: params.get('print') === '1',
+            notes: params.get('notes') === '1',
+        },
+    };
+}
+/**
+ * Format a route string. Flags become a leading query string when set:
+ * `?print=1&notes=1#/slide/0`.
+ */
+export function formatDeckRoute(location, flags = {}) {
+    const hash = formatDeckHash(location.slideId, location.step);
+    const params = new URLSearchParams();
+    if (flags.print)
+        params.set('print', '1');
+    if (flags.notes)
+        params.set('notes', '1');
+    const query = params.toString();
+    return query ? `?${query}${hash}` : hash;
+}

package/dist/engine/index.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `@texuli/deck/engine` — framework-free presentation runtime (ADR-009).
+ *
+ * ## Public API
+ *
+ * ### Navigation (`navigation.ts`)
+ * - `createDeckNavigator(deck, options?)` → `DeckNavigator`
+ *   - `next` / `prev` / `first` / `last` / `goTo(id | visibleIndex | location, step?)`
+ *   - `goToVertical(sectionId, verticalIndex, step?)`
+ *   - `getLocation()` → `DeckLocation` (`slideIndex`, `slideId`, `step`,
+ *     `stepCount` = max step index / advances, optional `sectionId` /
+ *     `verticalIndex` for stacked outline sections)
+ *   - `visibleSlides()`, `stepCountFor(slideId)`
+ * - `modelSlideStepCount(slide)` — default advance count from blocks/props/labels
+ * - Types: `EngineDeck`, `EngineSlide`, `EngineSection`, `DeckLocation`,
+ *   `NavigatorOptions`, `DeckNavigator`
+ *
+ * ### Hash routing (`hash.ts`)
+ * - `parseDeckHash(raw)` / `formatDeckHash(slideId, step)` — `#/<id>/<step>`
+ *   Rejects traversal (`..`), uppercase ids, percent-encoding, `?`/`#`/`\` inside.
+ * - `parseDeckRoute(hash, search?)` / `formatDeckRoute(location, flags?)` —
+ *   `?print=1&notes=1` flags
+ * - Constants: `DECK_HASH_ID_MAX` (64), `DECK_HASH_STEP_MAX` (32)
+ *
+ * ### Controls + input (`controls.ts`)
+ * - `DECK_CONTROLS` registry (single source for help/toolbar/docs)
+ * - `decideDeckInput(event, state?)` → `DeckAction | null`
+ *   Keys: →↓PageDown Space Enter / ←↑PageUp Shift+Space Backspace, Home/End,
+ *   O, F, S|P, B|., L, ?, Ctrl/⌘+P, D, Esc stack (debug→help→overview→
+ *   blackout→laser→fullscreen-exit). Swipe ≥50 px, 1.5× dominance, <800 ms.
+ *   Guards: fields/IME/modifiers/interactive targets/`data-tx-deck-*`.
+ * - `inputPathFrom(nodes, stopAt?)`, `deckControlFor`, `availableDeckControls`,
+ *   `deckKeyBindings`, `DECK_KEY_BINDINGS`, `DECK_ESCAPE_ORDER`
+ * - Swipe constants, `DECK_INTERACTIVE_ATTRIBUTE`, `DECK_CHROME_ATTRIBUTE`
+ *
+ * ### Canvas fit (`canvas.ts`)
+ * - `DECK_CANVAS` / `deckCanvasSize(aspect)` / `fitDeckCanvas(w, h, aspect?, fit?)`
+ *   Aspects 16:9, 4:3, 9:16, 1:1. Fit: `contain` | `cover` | `container`
+ *   (`container` ≡ letterboxed contain for embedded decks).
+ *
+ * ### Motion (`motion.ts`)
+ * - `resolveDeckTransition({ slide, style, motion, reducedMotion })`
+ * - `effectiveMotion`, `morphPairsFor`, `TRANSITION_MS`, `MAX_MOTION_MS`
+ *
+ * ### Auto-slide (`auto-slide.ts`)
+ * - `createAutoSlideScheduler({ intervalMs, onAdvance, clock?, startPaused? })`
+ *   Injectable clock; `input()` pauses; clamp 1s…600s.
+ *
+ * ### Presenter protocol v1 (`presenter.ts`)
+ * - Closed messages `{ type: 'hello'|'sync'|'request', slideId, step }`
+ * - Namespace `texuli-deck-presenter/1:<ns>` via `presenterChannelName`
+ * - `parsePresenterMessage` / `presenterMessage` / `isPresenterMessage`
+ * - Transports (no globals at import): `createPresenterTransport(channel)`,
+ *   `createMemoryPresenterTransport(ns?)`,
+ *   `createBroadcastPresenterTransport(ns, factory?)`
+ *
+ * ### Controller (`controller.ts`)
+ * - `createDeckController(deck, options?)` → `DeckController`
+ *   - Navigation: `goTo` / `next` / `prev` / `first` / `last` / `getState`
+ *   - `subscribe(listener)` or `subscribe(event, listener)` —
+ *     events: `slidechange` | `stepchange` | `statechange` | `overview` |
+ *     `blackout` | `pause` | `action` | `destroy`
+ *   - `setOverview` / `setBlackout` / `pause` / `resume` / `handleInput` /
+ *     `destroy`
+ *   - Plugins (ordered): `setup`, `beforeNavigate`, `afterNavigate`,
+ *     `beforeRender` (read-only slide/context), `afterRender`, `onAction`,
+ *     `onDestroy`. Stage calls `controller.beforeRender()` / `afterRender()`
+ *     around a paint; hooks observe only (no HTML injection).
+ *
+ * ### Messages (`messages.ts`)
+ * - `DECK_MESSAGES` English defaults; `formatMessage(key, values?, overrides?)`
+ * - `resolveDeckLocale(deck?, override?)` → `{ locale, dir }`
+ *
+ * ## Constraints
+ * - Framework-free and DOM-free at import (no `window`/`document` access).
+ * - Imports stay inside `packages/deck/src/` (the engine uses the package's own model;
+ *   import-guard enforced), and nothing touches window, document or navigator at load.
+ * - Zero third-party runtime dependencies; erasable TypeScript only.
+ */
+export { type AutoSlideOptions, type AutoSlideScheduler, createAutoSlideScheduler, type SchedulerClock, } from './auto-slide.js';
+export { type CanvasFit, DECK_ASPECTS, DECK_CANVAS, DEFAULT_DECK_ASPECT, type DeckAspect, type DeckCanvasSize, type DeckFitMode, deckCanvasSize, fitDeckCanvas, isDeckAspect, } from './canvas.js';
+export { type BeforeNavigateResult, createDeckController, type DeckActionSource, type DeckController, type DeckControllerOptions, type DeckEventMap, type DeckEventName, type DeckListener, type DeckPlugin, type DeckRenderContext, type DeckState, type DeckStateChange, } from './controller.js';
+export { availableDeckControls, DECK_CHROME_ATTRIBUTE, DECK_CONTROL_CAPABILITIES, DECK_CONTROL_GROUPS, DECK_CONTROLS, DECK_ESCAPE_ORDER, DECK_INPUT_ACTIONS, DECK_INTERACTIVE_ATTRIBUTE, DECK_KEY_BINDINGS, DECK_SWIPE_AXIS_RATIO, DECK_SWIPE_MAX_DURATION_MS, DECK_SWIPE_MIN_DISTANCE, DEFAULT_DECK_CONTROL_ENVIRONMENT, type DeckAction, type DeckControl, type DeckControlCapability, type DeckControlEnvironment, type DeckControlGroup, type DeckControlKey, type DeckInputAction, type DeckInputEvent, type DeckInputState, type DeckInputTarget, type DeckKeyBinding, decideDeckInput, deckControlFor, deckKeyBindings, inputPathFrom, } from './controls.js';
+export { DECK_HASH_ID_MAX, DECK_HASH_STEP_MAX, type DeckHashLocation, type DeckRouteFlags, formatDeckHash, formatDeckRoute, type ParsedDeckRoute, parseDeckHash, parseDeckRoute, } from './hash.js';
+export { DECK_MESSAGES, type DeckLocale, type DeckMessageKey, type DeckMessages, formatMessage, type MessageValues, resolveDeckLocale, } from './messages.js';
+export { DECK_TRANSITIONS, DEFAULT_MOTION, DEFAULT_TRANSITION, type DeckMotion, type DeckTransition, effectiveMotion, isDeckTransition, isMotionLevel, MAX_MOTION_MS, MOTION_LEVELS, type MorphPair, morphPairsFor, REDUCED_FADE_MS, type ResolvedTransition, type ResolveTransitionInput, resolveDeckTransition, SUBTLE_SCALE, TRANSITION_MS, type TransitionReason, } from './motion.js';
+export { createDeckNavigator, type DeckLocation, type DeckNavigator, type EngineDeck, type EngineSection, type EngineSlide, modelSlideStepCount, type NavigatorOptions, } from './navigation.js';
+export { createBroadcastPresenterTransport, createMemoryPresenterTransport, createPresenterTransport, isPresenterMessage, PRESENTER_MESSAGE_TYPES, PRESENTER_PROTOCOL_PREFIX, PRESENTER_PROTOCOL_VERSION, type PresenterChannelLike, type PresenterMessage, type PresenterMessageType, type PresenterTransport, parsePresenterMessage, presenterChannelName, presenterMessage, sanitizePresenterNamespace, } from './presenter.js';