@texuli/deck 0.0.0-stage → 0.5.0

package/dist/engine/index.js

@@ -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 { createAutoSlideScheduler, } from "./auto-slide.js";
+export { DECK_ASPECTS, DECK_CANVAS, DEFAULT_DECK_ASPECT, deckCanvasSize, fitDeckCanvas, isDeckAspect, } from "./canvas.js";
+export { createDeckController, } 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, decideDeckInput, deckControlFor, deckKeyBindings, inputPathFrom, } from "./controls.js";
+export { DECK_HASH_ID_MAX, DECK_HASH_STEP_MAX, formatDeckHash, formatDeckRoute, parseDeckHash, parseDeckRoute, } from "./hash.js";
+export { DECK_MESSAGES, formatMessage, resolveDeckLocale, } from "./messages.js";
+export { DECK_TRANSITIONS, DEFAULT_MOTION, DEFAULT_TRANSITION, effectiveMotion, isDeckTransition, isMotionLevel, MAX_MOTION_MS, MOTION_LEVELS, morphPairsFor, REDUCED_FADE_MS, resolveDeckTransition, SUBTLE_SCALE, TRANSITION_MS, } from "./motion.js";
+export { createDeckNavigator, modelSlideStepCount, } from "./navigation.js";
+export { createBroadcastPresenterTransport, createMemoryPresenterTransport, createPresenterTransport, isPresenterMessage, PRESENTER_MESSAGE_TYPES, PRESENTER_PROTOCOL_PREFIX, PRESENTER_PROTOCOL_VERSION, parsePresenterMessage, presenterChannelName, presenterMessage, sanitizePresenterNamespace, } from "./presenter.js";

package/dist/engine/messages.d.ts

@@ -0,0 +1,138 @@
+/**
+ * English defaults for every stage chrome string, plus `formatMessage`.
+ *
+ * Consumers pass per-key overrides; `meta.locale` / `meta.dir` flow through
+ * {@link resolveDeckLocale}. Placeholders use `{name}` syntax.
+ */
+export declare const DECK_MESSAGES: Readonly<{
+    readonly 'controls.previous': "Previous step or slide";
+    readonly 'controls.previousDescription': "Goes back one step, or to the previous slide.";
+    readonly 'controls.chooseSlide': "Choose a slide";
+    readonly 'controls.chooseSlideDescription': "Opens the slide list so you can jump directly to a slide.";
+    readonly 'controls.next': "Next step or slide";
+    readonly 'controls.nextDescription': "Shows the next step, or advances to the next slide.";
+    readonly 'controls.first': "First slide";
+    readonly 'controls.firstDescription': "Jumps to the first slide.";
+    readonly 'controls.last': "Last slide";
+    readonly 'controls.lastDescription': "Jumps to the last slide.";
+    readonly 'controls.overview': "Overview of all slides";
+    readonly 'controls.overviewDescription': "Shows every slide as a grid.";
+    readonly 'controls.fullscreen': "Full screen";
+    readonly 'controls.fullscreenDescription': "Fills the screen with the slides.";
+    readonly 'controls.leaveFullscreen': "Leave full screen";
+    readonly 'controls.leaveFullscreenDescription': "Returns the deck to its normal place.";
+    readonly 'controls.presenter': "Presenter view";
+    readonly 'controls.presenterDescription': "Shows notes, the next slide and timers.";
+    readonly 'controls.blackout': "Black out the screen";
+    readonly 'controls.blackoutDescription': "Turns the screen black.";
+    readonly 'controls.laser': "Laser pointer";
+    readonly 'controls.laserDescription': "Turns the pointer into a bright dot.";
+    readonly 'controls.copyLink': "Copy link to this slide";
+    readonly 'controls.copyLinkDescription': "Copies a link to this slide and step.";
+    readonly 'controls.print': "Print, one slide per page";
+    readonly 'controls.printDescription': "Prints the deck or saves it as a PDF.";
+    readonly 'controls.help': "Controls and shortcuts";
+    readonly 'controls.helpDescription': "Lists every control and its keys.";
+    readonly 'controls.debug': "Debug for agents";
+    readonly 'controls.debugDescription': "Shows this slide source, checks and reference.";
+    readonly 'chrome.toolbar': "Deck controls";
+    readonly 'chrome.navigate': "Navigate";
+    readonly 'chrome.more': "More presentation controls";
+    readonly 'chrome.fullscreenControls': "Full screen controls";
+    readonly 'chrome.blackoutHint': "Screen blacked out. Press B or select to show the slide.";
+    readonly 'chrome.hintMove': "Use {key} to move,";
+    readonly 'chrome.hintFullscreen': "{key} for full screen,";
+    readonly 'chrome.hintHelp': "{key} for every control.";
+    readonly 'chrome.buttonOnly': "Button only";
+    readonly 'chrome.copied': "Copied";
+    readonly 'chrome.copyFailed': "Could not copy";
+    readonly 'chrome.slideProgress': "Deck progress";
+    readonly 'chrome.chooseSlide': "Choose a slide";
+    readonly 'chrome.laserOn': "Laser on";
+    readonly 'chrome.close': "Close";
+    readonly 'overview.title': "Slide overview";
+    readonly 'overview.loading': "Loading overview…";
+    readonly 'overview.loadError': "The overview could not be loaded.";
+    readonly 'overview.slideNumber': "Slide {current}";
+    readonly 'overview.selectSlide': "Go to slide {current}: {title}";
+    readonly 'presenter.title': "Presenter";
+    readonly 'presenter.viewLabel': "Presenter view";
+    readonly 'presenter.elapsed': "Elapsed";
+    readonly 'presenter.slideTime': "Slide";
+    readonly 'presenter.now': "Now";
+    readonly 'presenter.next': "Next";
+    readonly 'presenter.currentSlide': "Current slide";
+    readonly 'presenter.nextSlide': "Next slide";
+    readonly 'presenter.endOfDeck': "End of deck";
+    readonly 'presenter.previous': "Previous";
+    readonly 'presenter.advance': "Next";
+    readonly 'presenter.notes': "Speaker notes";
+    readonly 'presenter.upNext': "Up next";
+    readonly 'presenter.noNotes': "No notes for this slide.";
+    readonly 'presenter.popupBlocked': "Presenter window could not be opened.";
+    readonly 'presenter.loading': "Loading presenter…";
+    readonly 'presenter.pause': "Pause presentation";
+    readonly 'presenter.resume': "Resume presentation";
+    readonly 'print.button': "Print";
+    readonly 'print.noSlides': "This deck has no slides to print.";
+    readonly 'print.notes': "Speaker notes";
+    readonly 'print.notesAppendix': "Notes";
+    readonly 'print.noNotes': "No notes for this slide.";
+    readonly 'debug.title': "Debug for agents";
+    readonly 'debug.close': "Close";
+    readonly 'debug.thisSlide': "This slide";
+    readonly 'debug.slide': "Slide";
+    readonly 'debug.position': "Position";
+    readonly 'debug.layout': "Layout";
+    readonly 'debug.pointer': "Pointer";
+    readonly 'debug.props': "Props";
+    readonly 'debug.deck': "Deck";
+    readonly 'debug.notes': "Notes";
+    readonly 'debug.actions': "Actions";
+    readonly 'debug.copyReference': "Copy agent reference";
+    readonly 'debug.copyPrompt': "Copy as agent prompt";
+    readonly 'debug.copySlideJson': "Copy slide JSON";
+    readonly 'debug.downloadJson': "Download deck JSON";
+    readonly 'debug.copyOutline': "Copy outline";
+    readonly 'debug.checks': "Checks on this slide";
+    readonly 'debug.noFindings': "No findings on this slide.";
+    readonly 'debug.otherFindings': "Other slides with findings";
+    readonly 'debug.blocks': "Blocks";
+    readonly 'debug.slideText': "Slide text";
+    readonly 'debug.noText': "(no text)";
+    readonly 'debug.loading': "Loading the debug panel…";
+    readonly 'debug.loadError': "The debug panel could not be loaded.";
+    readonly 'debug.unnamedDeck': "unnamed";
+    readonly 'layout.contentUnavailable': "This part of the slide could not be shown.";
+    readonly 'layout.emptySlide': "This slide has no content yet.";
+    readonly 'layout.contentLoadError': "Slide content could not be loaded.";
+    readonly 'layout.contentLoading': "Loading slide content…";
+    readonly 'stage.controls': "Presentation controls";
+    readonly 'stage.elapsedTime': "Elapsed time";
+    readonly 'stage.notes': "Speaker notes";
+    readonly 'stage.upNext': "Up next";
+    readonly 'stage.slides': "Slides";
+    readonly 'stage.emptyNotes': "No notes for this slide.";
+    readonly 'stage.emptyContent': "This slide has no content yet.";
+    readonly 'stage.loadingOverview': "Loading overview…";
+    readonly 'stage.overviewError': "The overview could not be loaded.";
+    readonly 'stage.loadingPresenter': "Loading presenter…";
+    readonly 'stage.loadingDebug': "Loading the debug panel…";
+    readonly 'stage.debugError': "The debug panel could not be loaded.";
+    readonly 'stage.slideOf': "Slide {current} of {total}";
+    readonly 'stage.stepOf': "Step {current} of {total}";
+}>;
+export type DeckMessageKey = keyof typeof DECK_MESSAGES;
+export type DeckMessages = Partial<Record<DeckMessageKey, string>>;
+export type MessageValues = Readonly<Record<string, string | number>>;
+export interface DeckLocale {
+    locale?: string;
+    dir?: 'ltr' | 'rtl' | 'auto';
+}
+/**
+ * Resolve a message key with optional overrides and `{name}` placeholders.
+ * Unknown placeholders are left intact.
+ */
+export declare function formatMessage(key: DeckMessageKey, values?: MessageValues, overrides?: DeckMessages): string;
+/** Merge deck meta and host overrides into a concrete locale. */
+export declare function resolveDeckLocale(deck?: DeckLocale | null, override?: DeckLocale | null): Required<DeckLocale>;

package/dist/engine/messages.js

@@ -0,0 +1,140 @@
+/**
+ * English defaults for every stage chrome string, plus `formatMessage`.
+ *
+ * Consumers pass per-key overrides; `meta.locale` / `meta.dir` flow through
+ * {@link resolveDeckLocale}. Placeholders use `{name}` syntax.
+ */
+export const DECK_MESSAGES = Object.freeze({
+    'controls.previous': 'Previous step or slide',
+    'controls.previousDescription': 'Goes back one step, or to the previous slide.',
+    'controls.chooseSlide': 'Choose a slide',
+    'controls.chooseSlideDescription': 'Opens the slide list so you can jump directly to a slide.',
+    'controls.next': 'Next step or slide',
+    'controls.nextDescription': 'Shows the next step, or advances to the next slide.',
+    'controls.first': 'First slide',
+    'controls.firstDescription': 'Jumps to the first slide.',
+    'controls.last': 'Last slide',
+    'controls.lastDescription': 'Jumps to the last slide.',
+    'controls.overview': 'Overview of all slides',
+    'controls.overviewDescription': 'Shows every slide as a grid.',
+    'controls.fullscreen': 'Full screen',
+    'controls.fullscreenDescription': 'Fills the screen with the slides.',
+    'controls.leaveFullscreen': 'Leave full screen',
+    'controls.leaveFullscreenDescription': 'Returns the deck to its normal place.',
+    'controls.presenter': 'Presenter view',
+    'controls.presenterDescription': 'Shows notes, the next slide and timers.',
+    'controls.blackout': 'Black out the screen',
+    'controls.blackoutDescription': 'Turns the screen black.',
+    'controls.laser': 'Laser pointer',
+    'controls.laserDescription': 'Turns the pointer into a bright dot.',
+    'controls.copyLink': 'Copy link to this slide',
+    'controls.copyLinkDescription': 'Copies a link to this slide and step.',
+    'controls.print': 'Print, one slide per page',
+    'controls.printDescription': 'Prints the deck or saves it as a PDF.',
+    'controls.help': 'Controls and shortcuts',
+    'controls.helpDescription': 'Lists every control and its keys.',
+    'controls.debug': 'Debug for agents',
+    'controls.debugDescription': 'Shows this slide source, checks and reference.',
+    'chrome.toolbar': 'Deck controls',
+    'chrome.navigate': 'Navigate',
+    'chrome.more': 'More presentation controls',
+    'chrome.fullscreenControls': 'Full screen controls',
+    'chrome.blackoutHint': 'Screen blacked out. Press B or select to show the slide.',
+    'chrome.hintMove': 'Use {key} to move,',
+    'chrome.hintFullscreen': '{key} for full screen,',
+    'chrome.hintHelp': '{key} for every control.',
+    'chrome.buttonOnly': 'Button only',
+    'chrome.copied': 'Copied',
+    'chrome.copyFailed': 'Could not copy',
+    'chrome.slideProgress': 'Deck progress',
+    'chrome.chooseSlide': 'Choose a slide',
+    'chrome.laserOn': 'Laser on',
+    'chrome.close': 'Close',
+    'overview.title': 'Slide overview',
+    'overview.loading': 'Loading overview…',
+    'overview.loadError': 'The overview could not be loaded.',
+    'overview.slideNumber': 'Slide {current}',
+    'overview.selectSlide': 'Go to slide {current}: {title}',
+    'presenter.title': 'Presenter',
+    'presenter.viewLabel': 'Presenter view',
+    'presenter.elapsed': 'Elapsed',
+    'presenter.slideTime': 'Slide',
+    'presenter.now': 'Now',
+    'presenter.next': 'Next',
+    'presenter.currentSlide': 'Current slide',
+    'presenter.nextSlide': 'Next slide',
+    'presenter.endOfDeck': 'End of deck',
+    'presenter.previous': 'Previous',
+    'presenter.advance': 'Next',
+    'presenter.notes': 'Speaker notes',
+    'presenter.upNext': 'Up next',
+    'presenter.noNotes': 'No notes for this slide.',
+    'presenter.popupBlocked': 'Presenter window could not be opened.',
+    'presenter.loading': 'Loading presenter…',
+    'presenter.pause': 'Pause presentation',
+    'presenter.resume': 'Resume presentation',
+    'print.button': 'Print',
+    'print.noSlides': 'This deck has no slides to print.',
+    'print.notes': 'Speaker notes',
+    'print.notesAppendix': 'Notes',
+    'print.noNotes': 'No notes for this slide.',
+    'debug.title': 'Debug for agents',
+    'debug.close': 'Close',
+    'debug.thisSlide': 'This slide',
+    'debug.slide': 'Slide',
+    'debug.position': 'Position',
+    'debug.layout': 'Layout',
+    'debug.pointer': 'Pointer',
+    'debug.props': 'Props',
+    'debug.deck': 'Deck',
+    'debug.notes': 'Notes',
+    'debug.actions': 'Actions',
+    'debug.copyReference': 'Copy agent reference',
+    'debug.copyPrompt': 'Copy as agent prompt',
+    'debug.copySlideJson': 'Copy slide JSON',
+    'debug.downloadJson': 'Download deck JSON',
+    'debug.copyOutline': 'Copy outline',
+    'debug.checks': 'Checks on this slide',
+    'debug.noFindings': 'No findings on this slide.',
+    'debug.otherFindings': 'Other slides with findings',
+    'debug.blocks': 'Blocks',
+    'debug.slideText': 'Slide text',
+    'debug.noText': '(no text)',
+    'debug.loading': 'Loading the debug panel…',
+    'debug.loadError': 'The debug panel could not be loaded.',
+    'debug.unnamedDeck': 'unnamed',
+    'layout.contentUnavailable': 'This part of the slide could not be shown.',
+    'layout.emptySlide': 'This slide has no content yet.',
+    'layout.contentLoadError': 'Slide content could not be loaded.',
+    'layout.contentLoading': 'Loading slide content…',
+    'stage.controls': 'Presentation controls',
+    'stage.elapsedTime': 'Elapsed time',
+    'stage.notes': 'Speaker notes',
+    'stage.upNext': 'Up next',
+    'stage.slides': 'Slides',
+    'stage.emptyNotes': 'No notes for this slide.',
+    'stage.emptyContent': 'This slide has no content yet.',
+    'stage.loadingOverview': 'Loading overview…',
+    'stage.overviewError': 'The overview could not be loaded.',
+    'stage.loadingPresenter': 'Loading presenter…',
+    'stage.loadingDebug': 'Loading the debug panel…',
+    'stage.debugError': 'The debug panel could not be loaded.',
+    'stage.slideOf': 'Slide {current} of {total}',
+    'stage.stepOf': 'Step {current} of {total}',
+});
+const PLACEHOLDER = /\{([a-zA-Z][a-zA-Z0-9_]*)\}/g;
+/**
+ * Resolve a message key with optional overrides and `{name}` placeholders.
+ * Unknown placeholders are left intact.
+ */
+export function formatMessage(key, values = {}, overrides = {}) {
+    const template = overrides[key] ?? DECK_MESSAGES[key];
+    return template.replace(PLACEHOLDER, (match, name) => Object.hasOwn(values, name) ? String(values[name]) : match);
+}
+/** Merge deck meta and host overrides into a concrete locale. */
+export function resolveDeckLocale(deck, override) {
+    return {
+        locale: override?.locale ?? deck?.locale ?? 'en',
+        dir: override?.dir ?? deck?.dir ?? 'auto',
+    };
+}

package/dist/engine/motion.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Pure transition resolution metadata. Rendering is owned by the stage.
+ *
+ * Precedence: slide override → deck style → `fade`. The motion ceiling
+ * (`full` | `subtle` | `none`) shortens or drops motion; the viewer's
+ * reduced-motion preference only lowers it. Durations never exceed 400 ms.
+ *
+ * Self-contained: does not import `@texuli/deck/model` (import-guard).
+ */
+export declare const DECK_TRANSITIONS: readonly ["none", "fade", "fade-up", "slide", "zoom", "morph"];
+export type DeckTransition = (typeof DECK_TRANSITIONS)[number];
+export declare const MOTION_LEVELS: readonly ["full", "subtle", "none"];
+export type DeckMotion = (typeof MOTION_LEVELS)[number];
+export declare const MAX_MOTION_MS = 400;
+export declare const REDUCED_FADE_MS = 150;
+export declare const SUBTLE_SCALE = 0.6;
+export declare const DEFAULT_TRANSITION: DeckTransition;
+export declare const DEFAULT_MOTION: DeckMotion;
+export declare const TRANSITION_MS: Readonly<Record<DeckTransition, number>>;
+export type TransitionReason = 'motion-none' | 'reduced-motion' | 'subtle' | 'slide-override' | 'deck-default' | 'engine-default';
+export interface ResolvedTransition {
+    name: DeckTransition;
+    requested: DeckTransition;
+    durationMs: number;
+    motion: DeckMotion;
+    reason: TransitionReason;
+}
+export interface ResolveTransitionInput {
+    slide?: {
+        transition?: unknown;
+        id?: unknown;
+    } | null;
+    style?: {
+        transition?: unknown;
+        motion?: unknown;
+    } | null;
+    /** Ceiling; defaults to `style.motion`, then `full`. */
+    motion?: DeckMotion;
+    reducedMotion?: boolean;
+}
+export declare function isDeckTransition(value: unknown): value is DeckTransition;
+export declare function isMotionLevel(value: unknown): value is DeckMotion;
+/** Effective motion ceiling, lowered (never raised) by reduced motion. */
+export declare function effectiveMotion(input?: ResolveTransitionInput): DeckMotion;
+/**
+ * Resolve the transition into a slide from the slide override, the deck
+ * default and the motion level.
+ */
+export declare function resolveDeckTransition(input?: ResolveTransitionInput): ResolvedTransition;
+/**
+ * Morph/auto-animate pairing metadata for the stage: pairs of slide ids that
+ * share a `morph` transition on the destination. The stage matches elements
+ * by `data-tx-deck-morph-id` (or equivalent); this only reports the pair.
+ */
+export interface MorphPair {
+    fromSlideId: string;
+    toSlideId: string;
+}
+export declare function morphPairsFor(slides: readonly {
+    id: string;
+    transition?: unknown;
+}[], style?: {
+    transition?: unknown;
+} | null): readonly MorphPair[];

package/dist/engine/motion.js

@@ -0,0 +1,112 @@
+/**
+ * Pure transition resolution metadata. Rendering is owned by the stage.
+ *
+ * Precedence: slide override → deck style → `fade`. The motion ceiling
+ * (`full` | `subtle` | `none`) shortens or drops motion; the viewer's
+ * reduced-motion preference only lowers it. Durations never exceed 400 ms.
+ *
+ * Self-contained: does not import `@texuli/deck/model` (import-guard).
+ */
+export const DECK_TRANSITIONS = ['none', 'fade', 'fade-up', 'slide', 'zoom', 'morph'];
+export const MOTION_LEVELS = ['full', 'subtle', 'none'];
+export const MAX_MOTION_MS = 400;
+export const REDUCED_FADE_MS = 150;
+export const SUBTLE_SCALE = 0.6;
+export const DEFAULT_TRANSITION = 'fade';
+export const DEFAULT_MOTION = 'full';
+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);
+}
+function clampMs(ms) {
+    return Math.max(0, Math.min(MAX_MOTION_MS, Math.round(ms)));
+}
+/** Effective motion ceiling, lowered (never raised) by reduced motion. */
+export function effectiveMotion(input = {}) {
+    const level = isMotionLevel(input.motion)
+        ? input.motion
+        : isMotionLevel(input.style?.motion)
+            ? input.style.motion
+            : DEFAULT_MOTION;
+    if (level === 'none')
+        return 'none';
+    return input.reducedMotion ? 'subtle' : level;
+}
+/**
+ * Resolve the transition into a slide from the slide override, the deck
+ * default and the motion level.
+ */
+export function resolveDeckTransition(input = {}) {
+    const own = input.slide?.transition;
+    const deckTransition = input.style?.transition;
+    const requested = isDeckTransition(own)
+        ? own
+        : isDeckTransition(deckTransition)
+            ? deckTransition
+            : DEFAULT_TRANSITION;
+    const source = isDeckTransition(own)
+        ? 'slide-override'
+        : isDeckTransition(deckTransition)
+            ? 'deck-default'
+            : 'engine-default';
+    const motion = effectiveMotion(input);
+    if (motion === 'none' || requested === 'none') {
+        return {
+            name: 'none',
+            requested,
+            durationMs: 0,
+            motion,
+            reason: motion === 'none' ? 'motion-none' : source,
+        };
+    }
+    if (input.reducedMotion) {
+        return {
+            name: 'fade',
+            requested,
+            durationMs: REDUCED_FADE_MS,
+            motion,
+            reason: 'reduced-motion',
+        };
+    }
+    if (motion === 'subtle') {
+        const name = requested === 'zoom' ? 'fade' : requested;
+        return {
+            name,
+            requested,
+            durationMs: clampMs(TRANSITION_MS[name] * SUBTLE_SCALE),
+            motion,
+            reason: 'subtle',
+        };
+    }
+    return {
+        name: requested,
+        requested,
+        durationMs: clampMs(TRANSITION_MS[requested]),
+        motion,
+        reason: source,
+    };
+}
+export function morphPairsFor(slides, style) {
+    const pairs = [];
+    for (let i = 1; i < slides.length; i += 1) {
+        const to = slides[i];
+        const from = slides[i - 1];
+        if (!to || !from)
+            continue;
+        const resolved = resolveDeckTransition({ slide: to, style });
+        if (resolved.name === 'morph') {
+            pairs.push({ fromSlideId: from.id, toSlideId: to.id });
+        }
+    }
+    return pairs;
+}

package/dist/engine/navigation.d.ts

@@ -0,0 +1,87 @@
+export interface EngineSlide {
+    id: string;
+    hidden?: boolean;
+    /** Step labels: `steps[i]` names step `i + 1`. */
+    steps?: readonly string[];
+    blocks?: readonly unknown[];
+    props?: unknown;
+    layout?: string;
+    transition?: string;
+}
+export interface EngineSection {
+    id: string;
+    slideIds: readonly string[];
+    /** When true, the section is a vertical stack (Reveal-style). */
+    stack?: boolean;
+}
+export interface EngineDeck {
+    slides: readonly EngineSlide[];
+    outline?: {
+        sections?: readonly EngineSection[];
+    };
+    navigation?: {
+        start?: string;
+        loop?: boolean;
+        autoSlideMs?: number;
+    };
+    style?: {
+        transition?: string;
+        motion?: string;
+        aspect?: string;
+        progress?: string;
+    };
+    meta?: {
+        locale?: string;
+        dir?: 'ltr' | 'rtl' | 'auto';
+        title?: string;
+    };
+}
+/** Current place in the deck (immutable snapshot). */
+export interface DeckLocation {
+    /** Index into the full `deck.slides` array. */
+    slideIndex: number;
+    slideId: string;
+    /** 0-based step on the current slide. */
+    step: number;
+    /** Maximum step index (number of advances). Navigable range is 0…stepCount. */
+    stepCount: number;
+    /** Set when the slide belongs to a stacked outline section. */
+    sectionId?: string;
+    /** 0-based index inside the stacked section. */
+    verticalIndex?: number;
+}
+export interface NavigatorOptions {
+    initialSlideId?: string;
+    initialStep?: number;
+    /**
+     * How many advances each slide has (max step index). Defaults to
+     * {@link modelSlideStepCount}.
+     */
+    stepCount?: (slide: EngineSlide) => number;
+}
+export interface DeckNavigator {
+    getLocation(): DeckLocation;
+    visibleSlides(): readonly EngineSlide[];
+    next(): DeckLocation;
+    prev(): DeckLocation;
+    first(): DeckLocation;
+    last(): DeckLocation;
+    /**
+     * Jump by slide id, by visible index (number), or by a full location.
+     * Unknown or hidden ids fall back to the first visible slide.
+     */
+    goTo(slide: string | number | DeckLocation, step?: number): DeckLocation;
+    goToVertical(sectionId: string, verticalIndex: number, step?: number): DeckLocation;
+    stepCountFor(slideId: string): number;
+}
+/**
+ * Count distinct positive model-v2 step markers plus explicit step labels.
+ * Never throws; unknown shapes contribute nothing. The result is the maximum
+ * step index (0 when the slide has no advances).
+ */
+export declare function modelSlideStepCount(slide: EngineSlide): number;
+/**
+ * Create a pure navigator over a deck-shaped object. The deck is read once;
+ * later mutations of the input are ignored.
+ */
+export declare function createDeckNavigator(deck: EngineDeck, options?: NavigatorOptions): DeckNavigator;