@texuli/deck 0.0.0-stage → 0.5.0

package/dist/engine/navigation.js

@@ -0,0 +1,156 @@
+/**
+ * Framework-free deck navigation over a model-v2-shaped deck.
+ *
+ * Locations are pure data. Hidden slides are skipped by sequential moves;
+ * `goTo` of a hidden or unknown id falls back to the first visible slide.
+ * Vertical stacks come from `outline.sections` with `stack: true`: next/prev
+ * walk steps, then vertical siblings, then the surrounding horizontal order.
+ * `stepCount` is the maximum step index on the slide (number of advances);
+ * navigable steps are `0 … stepCount` inclusive.
+ */
+import { layoutSteppablePaths } from "../model/layouts/index.js";
+import { slideSteps } from "../model/steps/index.js";
+/**
+ * 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 function modelSlideStepCount(slide) {
+    return slideSteps(slide, {
+        steppablePaths: layoutSteppablePaths(slide.layout ?? 'free'),
+    }).count;
+}
+function clamp(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.max(min, Math.min(max, Math.floor(value)));
+}
+/**
+ * Create a pure navigator over a deck-shaped object. The deck is read once;
+ * later mutations of the input are ignored.
+ */
+export function createDeckNavigator(deck, options = {}) {
+    const slides = deck.slides ?? [];
+    const steps = slides.map((slide) => Math.max(0, Math.floor(options.stepCount?.(slide) ?? modelSlideStepCount(slide)) || 0));
+    const visible = slides
+        .map((slide, index) => ({ slide, index }))
+        .filter(({ slide }) => slide.hidden !== true);
+    const byId = new Map(slides.map((slide, index) => [slide.id, index]));
+    const stackBySlide = new Map();
+    for (const section of deck.outline?.sections ?? []) {
+        if (!section.stack)
+            continue;
+        const ids = section.slideIds ?? [];
+        ids.forEach((id, index) => {
+            stackBySlide.set(id, { sectionId: section.id, index, ids });
+        });
+    }
+    const fallback = visible[0] ?? (slides[0] ? { slide: slides[0], index: 0 } : undefined);
+    let current = fallback?.index ?? 0;
+    let step = clamp(options.initialStep ?? 0, 0, steps[current] ?? 0);
+    const resolveStart = (id) => {
+        if (!id)
+            return;
+        const initial = visible.find(({ slide }) => slide.id === id);
+        if (initial) {
+            current = initial.index;
+            step = clamp(options.initialStep ?? 0, 0, steps[current] ?? 0);
+        }
+    };
+    if (options.initialSlideId)
+        resolveStart(options.initialSlideId);
+    else
+        resolveStart(deck.navigation?.start);
+    const make = () => {
+        const slide = slides[current];
+        if (!slide)
+            return { slideIndex: 0, slideId: '', step: 0, stepCount: 0 };
+        const stack = stackBySlide.get(slide.id);
+        return {
+            slideIndex: current,
+            slideId: slide.id,
+            step,
+            stepCount: steps[current] ?? 0,
+            ...(stack ? { sectionId: stack.sectionId, verticalIndex: stack.index } : {}),
+        };
+    };
+    const set = (index, nextStep = 0) => {
+        current = index;
+        step = clamp(nextStep, 0, steps[current] ?? 0);
+        return make();
+    };
+    const atVisible = (index) => visible[index]?.index;
+    const moveVertical = (direction, fromId) => {
+        const stack = stackBySlide.get(fromId);
+        if (!stack)
+            return undefined;
+        for (let offset = stack.index + direction; offset >= 0 && offset < stack.ids.length; offset += direction) {
+            const nextIndex = byId.get(stack.ids[offset] ?? '');
+            if (nextIndex !== undefined && slides[nextIndex]?.hidden !== true)
+                return nextIndex;
+        }
+        return undefined;
+    };
+    const moveAcross = (direction) => {
+        const now = make();
+        if (direction > 0 && now.step < now.stepCount)
+            return set(current, step + 1);
+        if (direction < 0 && now.step > 0)
+            return set(current, step - 1);
+        const vertical = moveVertical(direction, now.slideId);
+        if (vertical !== undefined) {
+            return set(vertical, direction > 0 ? 0 : (steps[vertical] ?? 0));
+        }
+        const visibleIndex = visible.findIndex(({ index }) => index === current);
+        let target = atVisible(visibleIndex + direction);
+        if (target === undefined && deck.navigation?.loop === true && visible.length > 0) {
+            target = direction > 0 ? visible[0]?.index : visible[visible.length - 1]?.index;
+        }
+        if (target === undefined)
+            return make();
+        return set(target, direction > 0 ? 0 : (steps[target] ?? 0));
+    };
+    return {
+        getLocation: make,
+        visibleSlides: () => visible.map(({ slide }) => slide),
+        next: () => moveAcross(1),
+        prev: () => moveAcross(-1),
+        first: () => (visible[0] ? set(visible[0].index, 0) : make()),
+        last: () => {
+            const last = visible[visible.length - 1];
+            return last ? set(last.index, steps[last.index] ?? 0) : make();
+        },
+        goTo: (target, targetStep = 0) => {
+            let index;
+            let resolvedStep = targetStep;
+            if (typeof target === 'string') {
+                index = byId.get(target);
+            }
+            else if (typeof target === 'number') {
+                if (visible.length === 0)
+                    return make();
+                index = visible[clamp(target, 0, visible.length - 1)]?.index;
+            }
+            else {
+                index = byId.get(target.slideId);
+                resolvedStep = target.step;
+            }
+            if (index === undefined || slides[index]?.hidden === true) {
+                return fallback ? set(fallback.index, 0) : make();
+            }
+            return set(index, resolvedStep);
+        },
+        goToVertical: (sectionId, verticalIndex, targetStep = 0) => {
+            const section = deck.outline?.sections?.find((item) => item.id === sectionId && item.stack);
+            const id = section?.slideIds[clamp(verticalIndex, 0, (section?.slideIds.length ?? 1) - 1)];
+            const index = id ? byId.get(id) : undefined;
+            if (index === undefined || slides[index]?.hidden === true)
+                return make();
+            return set(index, targetStep);
+        },
+        stepCountFor: (slideId) => {
+            const index = byId.get(slideId);
+            return index === undefined ? 0 : (steps[index] ?? 0);
+        },
+    };
+}

package/dist/engine/presenter.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Closed, versioned presenter protocol v1.
+ *
+ * Message shape: `{ type, slideId, step }` only (`hello` | `sync` | `request`).
+ * Channel name: `texuli-deck-presenter/1:<namespace>`.
+ * No `window`, `document` or `BroadcastChannel` is touched at import time;
+ * transports are created only when a transport function is called.
+ */
+export declare const PRESENTER_MESSAGE_TYPES: readonly ["hello", "sync", "request"];
+export type PresenterMessageType = (typeof PRESENTER_MESSAGE_TYPES)[number];
+export interface PresenterMessage {
+    type: PresenterMessageType;
+    slideId: string;
+    step: number;
+}
+/** Protocol prefix; the full channel name is `${prefix}${namespace}`. */
+export declare const PRESENTER_PROTOCOL_PREFIX = "texuli-deck-presenter/1:";
+export declare const PRESENTER_PROTOCOL_VERSION: 1;
+/** Sanitize a deck namespace for a channel name. */
+export declare function sanitizePresenterNamespace(namespace: string): string;
+/** Channel name for one deck namespace (same-origin BroadcastChannel). */
+export declare function presenterChannelName(namespace: string): string;
+/** Type guard: closed shape, lowercase slide id, step 0…32. */
+export declare function isPresenterMessage(value: unknown): value is PresenterMessage;
+/** Parse an untrusted payload. Returns `null` when malformed (never throws). */
+export declare function parsePresenterMessage(value: unknown): PresenterMessage | null;
+/**
+ * Build a protocol message. Returns `null` when the arguments are invalid
+ * (never throws; the stage decides how to handle a rejected build).
+ */
+export declare function presenterMessage(type: PresenterMessageType, slideId: string, step: number): PresenterMessage | null;
+export interface PresenterTransport {
+    readonly name: string;
+    post(message: PresenterMessage): void;
+    subscribe(listener: (message: PresenterMessage) => void): () => void;
+    close(): void;
+}
+/** Duck-typed channel (BroadcastChannel or a test double). */
+export interface PresenterChannelLike {
+    postMessage(value: unknown): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    close(): void;
+}
+/** Wrap an existing channel-like object. Does not construct globals. */
+export declare function createPresenterTransport(channel: PresenterChannelLike, name?: string): PresenterTransport;
+/** In-memory bus for unit tests (same process, no DOM). */
+export declare function createMemoryPresenterTransport(namespace?: string): PresenterTransport;
+/**
+ * Optional BroadcastChannel transport. Returns `null` when the host has no
+ * BroadcastChannel or construction fails. The factory is injected so the
+ * module never reads `globalThis.BroadcastChannel` at import time.
+ */
+export declare function createBroadcastPresenterTransport(namespace: string, channelFactory?: new (name: string) => PresenterChannelLike): PresenterTransport | null;

package/dist/engine/presenter.js

@@ -0,0 +1,157 @@
+/**
+ * Closed, versioned presenter protocol v1.
+ *
+ * Message shape: `{ type, slideId, step }` only (`hello` | `sync` | `request`).
+ * Channel name: `texuli-deck-presenter/1:<namespace>`.
+ * No `window`, `document` or `BroadcastChannel` is touched at import time;
+ * transports are created only when a transport function is called.
+ */
+export const PRESENTER_MESSAGE_TYPES = ['hello', 'sync', 'request'];
+/** Protocol prefix; the full channel name is `${prefix}${namespace}`. */
+export const PRESENTER_PROTOCOL_PREFIX = 'texuli-deck-presenter/1:';
+export const PRESENTER_PROTOCOL_VERSION = 1;
+const SLIDE_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const MAX_STEP = 32;
+/** Sanitize a deck namespace for a channel name. */
+export function sanitizePresenterNamespace(namespace) {
+    // Bounded and linear: cap the host string before any pattern runs, then
+    // trim the edge dashes with index scans (no `^-+|-+$` backtracking).
+    const raw = typeof namespace === 'string' ? namespace.slice(0, 512).trim() : '';
+    const dashed = raw.toLowerCase().replace(/[^a-z0-9._:-]+/g, '-');
+    let start = 0;
+    let end = dashed.length;
+    while (start < end && dashed[start] === '-')
+        start += 1;
+    while (end > start && dashed[end - 1] === '-')
+        end -= 1;
+    const cleaned = dashed.slice(start, end).slice(0, 96);
+    return cleaned || 'default';
+}
+/** Channel name for one deck namespace (same-origin BroadcastChannel). */
+export function presenterChannelName(namespace) {
+    return `${PRESENTER_PROTOCOL_PREFIX}${sanitizePresenterNamespace(namespace)}`;
+}
+/** Type guard: closed shape, lowercase slide id, step 0…32. */
+export function isPresenterMessage(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const message = value;
+    const keys = Object.keys(message);
+    if (keys.length !== 3)
+        return false;
+    if (!PRESENTER_MESSAGE_TYPES.includes(message.type))
+        return false;
+    if (typeof message.slideId !== 'string' || !SLIDE_ID.test(message.slideId))
+        return false;
+    if (typeof message.step !== 'number' || !Number.isInteger(message.step))
+        return false;
+    if (message.step < 0 || message.step > MAX_STEP)
+        return false;
+    return true;
+}
+/** Parse an untrusted payload. Returns `null` when malformed (never throws). */
+export function parsePresenterMessage(value) {
+    return isPresenterMessage(value)
+        ? { type: value.type, slideId: value.slideId, step: value.step }
+        : null;
+}
+/**
+ * Build a protocol message. Returns `null` when the arguments are invalid
+ * (never throws; the stage decides how to handle a rejected build).
+ */
+export function presenterMessage(type, slideId, step) {
+    return parsePresenterMessage({ type, slideId, step });
+}
+/** Wrap an existing channel-like object. Does not construct globals. */
+export function createPresenterTransport(channel, name = 'channel') {
+    const listeners = new Set();
+    const onMessage = (event) => {
+        const message = parsePresenterMessage(event.data);
+        if (!message)
+            return;
+        for (const listener of [...listeners])
+            listener(message);
+    };
+    channel.addEventListener('message', onMessage);
+    return {
+        name,
+        post(message) {
+            if (!isPresenterMessage(message))
+                return;
+            try {
+                channel.postMessage(message);
+            }
+            catch {
+                // Closed or structured-clone failure — drop silently.
+            }
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        close() {
+            listeners.clear();
+            channel.removeEventListener('message', onMessage);
+            try {
+                channel.close();
+            }
+            catch {
+                // already closed
+            }
+        },
+    };
+}
+/** In-memory bus for unit tests (same process, no DOM). */
+export function createMemoryPresenterTransport(namespace = 'test') {
+    const name = presenterChannelName(namespace);
+    const listeners = new Set();
+    return {
+        name,
+        post(message) {
+            if (!isPresenterMessage(message))
+                return;
+            const copy = {
+                type: message.type,
+                slideId: message.slideId,
+                step: message.step,
+            };
+            for (const listener of [...listeners])
+                listener(copy);
+        },
+        subscribe(handler) {
+            listeners.add(handler);
+            return () => {
+                listeners.delete(handler);
+            };
+        },
+        close() {
+            listeners.clear();
+        },
+    };
+}
+/**
+ * Optional BroadcastChannel transport. Returns `null` when the host has no
+ * BroadcastChannel or construction fails. The factory is injected so the
+ * module never reads `globalThis.BroadcastChannel` at import time.
+ */
+export function createBroadcastPresenterTransport(namespace, channelFactory) {
+    const Factory = channelFactory ??
+        (typeof globalThis !== 'undefined' &&
+            typeof globalThis.BroadcastChannel === 'function'
+            ? globalThis
+                .BroadcastChannel
+            : undefined);
+    if (typeof Factory !== 'function')
+        return null;
+    const name = presenterChannelName(namespace);
+    let channel;
+    try {
+        channel = new Factory(name);
+    }
+    catch {
+        return null;
+    }
+    return createPresenterTransport(channel, name);
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @texuli/deck: the framework-free, dependency-free deck engine (ADR-009).
+ * In development (PLAN_008). This root re-exports the deck model v2
+ * (`./model`) and the owned schema kit (`./schema`); import the engine,
+ * Markdown, math, authoring and templates from their own subpaths so a host
+ * loads only what it uses.
+ */
+export * from './model/index.js';
+export * from './schema/index.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @texuli/deck: the framework-free, dependency-free deck engine (ADR-009).
+ * In development (PLAN_008). This root re-exports the deck model v2
+ * (`./model`) and the owned schema kit (`./schema`); import the engine,
+ * Markdown, math, authoring and templates from their own subpaths so a host
+ * loads only what it uses.
+ */
+export * from "./model/index.js";
+export * from "./schema/index.js";

package/dist/markdown/attributes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The attribute lexer for `<!-- .slide: … -->`, `<!-- .element: … -->` and
+ * `{#id name=value flag}` brace lists. One left-to-right pass; values are
+ * quoted (`"…"`, `'…'`, no escapes) or bare tokens. The closed attribute sets
+ * themselves live with the code that reads them.
+ */
+import type { IssueSink } from './issues.js';
+export interface Attr {
+    name: string;
+    /** `true` for a bare flag (`hidden`, `numbers`). */
+    value: string | true;
+    line: number;
+    /** 1-based column of the attribute name. */
+    column: number;
+}
+/**
+ * Read attributes from `text`, which starts at `column` on `line`. In brace
+ * mode `#slug` is an `id` and `.name` is a `class`.
+ */
+export declare function readAttributes(text: string, line: number, column: number, sink: IssueSink, brace?: boolean): Attr[];
+/** An attribute value as written in canonical output: bare when it is a plain token. */
+export declare function writeAttribute(name: string, value: string | number | true): string;
+/** True when a value can be written as an attribute at all (one quote style fits). */
+export declare function attributeWritable(value: string): boolean;

package/dist/markdown/attributes.js

@@ -0,0 +1,94 @@
+import { DECK_MARKDOWN_LIMITS } from "./limits.js";
+const NAME_START = /[A-Za-z_]/;
+const NAME_CHAR = /[A-Za-z0-9_.:-]/;
+const BARE_CHAR = /[^\s"'=<>`{}]/;
+/**
+ * Read attributes from `text`, which starts at `column` on `line`. In brace
+ * mode `#slug` is an `id` and `.name` is a `class`.
+ */
+export function readAttributes(text, line, column, sink, brace = false) {
+    const out = [];
+    let i = 0;
+    const bad = (message) => {
+        sink.report('md-attr-value', message, { line, column: column + i });
+    };
+    while (i < text.length) {
+        const c = text[i] ?? '';
+        if (c === ' ' || c === '\t') {
+            i++;
+            continue;
+        }
+        if (out.length >= DECK_MARKDOWN_LIMITS.attributes) {
+            bad(`At most ${DECK_MARKDOWN_LIMITS.attributes} attributes per comment or brace list.`);
+            return out;
+        }
+        const start = i;
+        if (brace && (c === '#' || c === '.')) {
+            i++;
+            while (i < text.length && NAME_CHAR.test(text[i] ?? ''))
+                i++;
+            const value = text.slice(start + 1, i);
+            if (value === '') {
+                bad(`\`${c}\` needs a name after it.`);
+                continue;
+            }
+            out.push({ name: c === '#' ? 'id' : 'class', value, line, column: column + start });
+            continue;
+        }
+        if (!NAME_START.test(c)) {
+            bad(`Unexpected \`${c}\`; attributes look like name="value".`);
+            return out;
+        }
+        while (i < text.length && NAME_CHAR.test(text[i] ?? ''))
+            i++;
+        const name = text.slice(start, i);
+        if (text[i] !== '=') {
+            out.push({ name, value: true, line, column: column + start });
+            continue;
+        }
+        i++;
+        const quote = text[i];
+        let value;
+        if (quote === '"' || quote === "'") {
+            const end = text.indexOf(quote, i + 1);
+            if (end === -1) {
+                bad(`The value of "${name.slice(0, 40)}" has no closing ${quote}.`);
+                return out;
+            }
+            value = text.slice(i + 1, end);
+            i = end + 1;
+        }
+        else {
+            const valueStart = i;
+            while (i < text.length && BARE_CHAR.test(text[i] ?? ''))
+                i++;
+            value = text.slice(valueStart, i);
+            if (value === '') {
+                bad(`"${name.slice(0, 40)}=" needs a value.`);
+                return out;
+            }
+        }
+        if (value.length > DECK_MARKDOWN_LIMITS.attributeValue) {
+            bad(`An attribute value is at most ${DECK_MARKDOWN_LIMITS.attributeValue} characters.`);
+            continue;
+        }
+        out.push({ name, value, line, column: column + start });
+    }
+    return out;
+}
+/** An attribute value as written in canonical output: bare when it is a plain token. */
+export function writeAttribute(name, value) {
+    if (value === true)
+        return name;
+    const text = String(value);
+    if (/^[A-Za-z0-9._/:#+-]+$/.test(text))
+        return `${name}=${text}`;
+    return text.includes('"') ? `${name}='${text}'` : `${name}="${text}"`;
+}
+/** True when a value can be written as an attribute at all (one quote style fits). */
+export function attributeWritable(value) {
+    return (value.length <= DECK_MARKDOWN_LIMITS.attributeValue &&
+        !value.includes('\n') &&
+        !value.includes('-->') &&
+        !(value.includes('"') && value.includes("'")));
+}

package/dist/markdown/attrs-closed.d.ts

@@ -0,0 +1,52 @@
+import { BLOCK_REVEALS, type FragmentEffect, type FragmentTone } from '../model/shared.js';
+import type { Attr } from './attributes.js';
+import type { IssueSink } from './issues.js';
+/** A fragment request read from attributes. */
+export interface MarkSpec {
+    /** A fragment was asked for (`fragment`, `class="fragment"`, `step` or `reveal`). */
+    fragment: boolean;
+    effect?: FragmentEffect;
+    tone?: FragmentTone | 'neutral';
+    reveal?: (typeof BLOCK_REVEALS)[number];
+    /** An explicit step number. */
+    step?: number;
+    line: number;
+    column: number;
+}
+export interface ElementRead {
+    mark?: MarkSpec;
+    id?: string;
+    /** Other allowed attributes, by name. */
+    other: Map<string, Attr>;
+}
+/** reveal.js and deck effect names → a deck fragment effect (and tone). */
+export declare function mapEffect(name: string): {
+    effect: FragmentEffect;
+    tone?: FragmentTone;
+    approximate?: boolean;
+} | null;
+/**
+ * Read `.element` or brace attributes. `allowed` names the extra attributes
+ * this target accepts (width, height, avatar…); the fragment attributes and
+ * `id` are always read.
+ */
+export declare function readElement(attrs: readonly Attr[], allowed: ReadonlySet<string>, sink: IssueSink): ElementRead;
+/** What `.slide` attributes set on a slide (before ids and layouts are resolved). */
+export interface SlideAttrRead {
+    id?: string;
+    layout?: string;
+    master?: string;
+    title?: string;
+    theme?: string;
+    transition?: string;
+    hidden?: boolean;
+    steps?: string[];
+    background?: unknown;
+    section?: string;
+    sectionTitle?: string;
+    sectionEnd?: boolean;
+    /** Where each field was written (for the source map). */
+    at: Map<string, Attr>;
+}
+/** Read `.slide` attributes: aliases mapped, refusals reported, the background assembled. */
+export declare function readSlideAttrs(attrs: readonly Attr[], sink: IssueSink): SlideAttrRead;