@texuli/deck 0.0.0-stage → 0.5.0

package/dist/markdown/limits.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Bounds of the deck Markdown dialect (ADR-009). Hostile documents stop at a
+ * bound with a diagnostic; nothing past a bound is scanned twice.
+ */
+export declare const DECK_MARKDOWN_LIMITS: Readonly<{
+    /** UTF-8 bytes of the whole document (the untrusted loader's 1 MiB). */
+    bytes: 1048576;
+    /** Lines of the whole document. */
+    lines: 100000;
+    /** UTF-16 units of one line. */
+    lineLength: 20000;
+    /** Lines of the frontmatter block. */
+    frontmatterLines: 64;
+    /** Slides (the model's cap). */
+    slides: 200;
+    /** Attributes in one comment or brace list. */
+    attributes: 32;
+    /** UTF-16 units of one attribute value. */
+    attributeValue: 512;
+    /** Directive nesting: a region may hold a component fence, nothing deeper. */
+    directiveDepth: 2;
+    /** UTF-16 units of one JSON fence body. */
+    jsonBody: 65536;
+    /** Nesting of one JSON fence body. */
+    jsonDepth: 32;
+    /** JSON values across one document. */
+    jsonNodes: 20000;
+    /** Highlight steps of one code fence (`[1-2|4-6]`). */
+    codeSteps: 16;
+    /** Diagnostics kept (the rest set `truncated`). */
+    issues: 200;
+}>;

package/dist/markdown/limits.js

@@ -0,0 +1,32 @@
+/**
+ * Bounds of the deck Markdown dialect (ADR-009). Hostile documents stop at a
+ * bound with a diagnostic; nothing past a bound is scanned twice.
+ */
+export const DECK_MARKDOWN_LIMITS = Object.freeze({
+    /** UTF-8 bytes of the whole document (the untrusted loader's 1 MiB). */
+    bytes: 1_048_576,
+    /** Lines of the whole document. */
+    lines: 100_000,
+    /** UTF-16 units of one line. */
+    lineLength: 20_000,
+    /** Lines of the frontmatter block. */
+    frontmatterLines: 64,
+    /** Slides (the model's cap). */
+    slides: 200,
+    /** Attributes in one comment or brace list. */
+    attributes: 32,
+    /** UTF-16 units of one attribute value. */
+    attributeValue: 512,
+    /** Directive nesting: a region may hold a component fence, nothing deeper. */
+    directiveDepth: 2,
+    /** UTF-16 units of one JSON fence body. */
+    jsonBody: 65_536,
+    /** Nesting of one JSON fence body. */
+    jsonDepth: 32,
+    /** JSON values across one document. */
+    jsonNodes: 20_000,
+    /** Highlight steps of one code fence (`[1-2|4-6]`). */
+    codeSteps: 16,
+    /** Diagnostics kept (the rest set `truncated`). */
+    issues: 200,
+});

package/dist/markdown/parse.d.ts

@@ -0,0 +1,31 @@
+import { type DeckParseResult, type ParseDeckOptions } from '../model/parse.js';
+import { type DiagnosticSource } from '../schema/index.js';
+import { IssueSink } from './issues.js';
+type Bag = Record<string, unknown>;
+export interface ParseDeckMarkdownOptions extends ParseDeckOptions {
+}
+export interface DeckMarkdownResult extends DeckParseResult {
+    /** The deck object read from the Markdown, before model validation (for editors). */
+    draft?: Bag;
+    /** JSON path (`$.slides[2].props.title`) → where it was written. */
+    sourceMap: Map<string, DiagnosticSource>;
+}
+/** The draft deck and everything known about where it came from. */
+export interface DeckDraft {
+    draft: Bag | null;
+    sink: IssueSink;
+    map: Map<string, DiagnosticSource>;
+}
+/** Derive a slide id from its title, unique among the ids before it. */
+export declare function deriveSlideId(slide: Bag, index: number, used: ReadonlySet<string>): string;
+/** The id of a vertical stack's section when the author names none. */
+export declare function stackSectionId(firstSlideId: string): string;
+/** Read the Markdown into a draft deck (not validated) with its issues and source map. */
+export declare function readDeckDraft(text: string): DeckDraft;
+/**
+ * Parse a deck Markdown document into a validated v2 deck. Every dialect and
+ * model issue is reported (capped at 200) with a source line and column;
+ * `ok` is true only when there is no error. Never throws.
+ */
+export declare function parseDeckMarkdown(text: string, options?: ParseDeckMarkdownOptions): DeckMarkdownResult;
+export {};

package/dist/markdown/parse.js

@@ -0,0 +1,283 @@
+/**
+ * `parseDeckMarkdown`: a deck Markdown document → the same validated v2
+ * `Deck` that JSON produces. The dialect's own diagnostics carry a source
+ * line and column; the model's diagnostics (JSON paths) are mapped back to
+ * the Markdown through a source map built while reading.
+ */
+import { DECK_SOLID_TOKENS, isDeckBackgroundPreset } from "../model/backgrounds/schema.js";
+import { DECK_FORMAT_VERSION } from "../model/deck.js";
+import { parseDeck } from "../model/parse.js";
+import { toJsonPath, } from "../schema/index.js";
+import { readSlide } from "./blocks.js";
+import { frontmatterPath, readFrontmatter } from "./frontmatter.js";
+import { IssueSink } from "./issues.js";
+import { DECK_MARKDOWN_LIMITS } from "./limits.js";
+import { normalizeLines, scanDocument } from "./scan.js";
+import { buildSlide, idCandidate } from "./slides.js";
+import { slugify } from "./text.js";
+const HEX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+function expandHex(value) {
+    return value.length === 7 ? value : `#${[...value.slice(1)].map((c) => c + c).join('')}`;
+}
+/** Derive a slide id from its title, unique among the ids before it. */
+export function deriveSlideId(slide, index, used) {
+    const stem = slugify(idCandidate(slide)) || `slide-${index + 1}`;
+    if (!used.has(stem))
+        return stem;
+    for (let n = 2;; n++) {
+        const candidate = `${stem}-${n}`;
+        if (!used.has(candidate))
+            return candidate;
+    }
+}
+/** The id of a vertical stack's section when the author names none. */
+export function stackSectionId(firstSlideId) {
+    return `stack-${firstSlideId}`.slice(0, 64).replace(/-+$/, '');
+}
+/** Read the Markdown into a draft deck (not validated) with its issues and source map. */
+export function readDeckDraft(text) {
+    const sink = new IssueSink();
+    const map = new Map();
+    const lines = normalizeLines(String(text), sink);
+    if (lines === null)
+        return { draft: null, sink, map };
+    const scanned = scanDocument(lines, sink);
+    const front = readFrontmatter(scanned.frontmatter ?? [], sink);
+    // Slides: empty ones (only blank lines) are dropped.
+    const ctx = { sink, map, jsonBudget: { nodes: DECK_MARKDOWN_LIMITS.jsonNodes } };
+    const built = [];
+    for (const raw of scanned.slides) {
+        if (raw.lines.every((line) => line.text.trim() === ''))
+            continue;
+        if (built.length >= DECK_MARKDOWN_LIMITS.slides) {
+            sink.report('md-too-many-slides', `A deck has at most ${DECK_MARKDOWN_LIMITS.slides} slides; the rest were not read.`, { line: raw.line, column: 1 }, ['slides'], 'Split the deck.');
+            break;
+        }
+        const source = readSlide(raw.lines, sink);
+        const first = raw.lines.find((line) => line.text.trim() !== '');
+        const src = { line: first?.n ?? raw.line, column: 1 };
+        let vertical = raw.vertical;
+        if (vertical && built.length === 0) {
+            sink.report('md-stack-start', 'A `--` vertical slide needs a horizontal slide before it.', src);
+            vertical = false;
+        }
+        built.push({ ...buildSlide(source, built.length, src, ctx), vertical });
+    }
+    // Ids
+    const used = new Set();
+    const slides = built.map((entry, index) => {
+        const own = entry.slide.id;
+        const id = typeof own === 'string' ? own : (entry.attrs.id ?? deriveSlideId(entry.slide, index, used));
+        used.add(id);
+        const attr = entry.attrs.at.get('id');
+        map.set(toJsonPath(['slides', index, 'id']), attr ? { line: attr.line, column: attr.column } : entry.src);
+        return { id, ...entry.slide };
+    });
+    // Outline: vertical stacks and named sections, in document order.
+    const sections = [];
+    let named = null;
+    for (let i = 0; i < built.length;) {
+        let end = i + 1;
+        while (end < built.length && built[end]?.vertical)
+            end++;
+        const entry = built[i];
+        const ids = slides.slice(i, end).map((slide) => slide.id);
+        if (end - i > 1) {
+            named = null;
+            const section = {
+                id: entry.attrs.section ?? stackSectionId(ids[0] ?? ''),
+                slideIds: ids,
+                stack: true,
+            };
+            if (entry.attrs.sectionTitle !== undefined)
+                section.title = entry.attrs.sectionTitle;
+            map.set(toJsonPath(['outline', 'sections', sections.length]), entry.src);
+            sections.push(section);
+        }
+        else {
+            if (entry.attrs.sectionEnd)
+                named = null;
+            if (entry.attrs.section !== undefined) {
+                const section = { id: entry.attrs.section, slideIds: ids };
+                if (entry.attrs.sectionTitle !== undefined)
+                    section.title = entry.attrs.sectionTitle;
+                const attr = entry.attrs.at.get('section');
+                map.set(toJsonPath(['outline', 'sections', sections.length]), attr ? { line: attr.line, column: attr.column } : entry.src);
+                sections.push(section);
+                named = section;
+            }
+            else if (named)
+                named.slideIds.push(...ids);
+            else if (entry.attrs.sectionTitle !== undefined) {
+                sink.report('md-attr-conflict', '`section-title` needs `section`.', entry.src, [
+                    'slides',
+                    i,
+                ]);
+            }
+        }
+        i = end;
+    }
+    // Frontmatter → meta, style, navigation, outline title
+    const value = (key) => front.values.get(key);
+    const deck = { formatVersion: DECK_FORMAT_VERSION };
+    const meta = {};
+    const style = {};
+    const navigation = {};
+    for (const key of front.values.keys()) {
+        const line = front.lines.get(key) ?? 1;
+        map.set(frontmatterPath(key), { line, column: 1 });
+    }
+    for (const key of ['title', 'description', 'author', 'date', 'locale', 'dir']) {
+        const v = value(key);
+        if (v !== undefined)
+            meta[key] = v;
+    }
+    if (meta.title === undefined) {
+        const first = slides[0] ? idCandidate(slides[0]) : '';
+        meta.title = first.trim() || 'Untitled deck';
+        sink.report('md-title-missing', 'The frontmatter has no `title`; one was derived.', { line: 1, column: 1 }, ['meta', 'title'], 'Add `title: …` to the frontmatter.');
+    }
+    const theme = value('theme');
+    const themeMode = value('themeMode');
+    const themeSeed = value('themeSeed');
+    if (themeSeed !== undefined) {
+        style.theme =
+            themeMode === undefined
+                ? { kind: 'seed', seed: themeSeed }
+                : { kind: 'seed', seed: themeSeed, mode: themeMode };
+        if (theme !== undefined) {
+            sink.report('md-frontmatter-key', '`theme` and `themeSeed` exclude each other.', {
+                line: front.lines.get('theme') ?? 1,
+                column: 1,
+            });
+        }
+    }
+    else if (themeMode !== undefined) {
+        if (theme === undefined) {
+            sink.report('md-frontmatter-key', '`themeMode` needs `theme` (or `themeSeed`).', {
+                line: front.lines.get('themeMode') ?? 1,
+                column: 1,
+            });
+        }
+        else
+            style.theme = { kind: 'catalog', id: theme, mode: themeMode };
+    }
+    else if (theme !== undefined)
+        style.theme = theme;
+    for (const key of [
+        'fontPair',
+        'aspect',
+        'density',
+        'radius',
+        'motion',
+        'transition',
+        'logo',
+        'footer',
+        'slideNumbers',
+        'progress',
+        'codeTheme',
+        'math',
+    ]) {
+        const v = value(key);
+        if (v !== undefined)
+            style[key] = v;
+    }
+    const background = value('background');
+    if (typeof background === 'string') {
+        if (isDeckBackgroundPreset(background))
+            style.background = background;
+        else if (HEX.test(background))
+            style.background = { kind: 'solid', color: expandHex(background) };
+        else if (DECK_SOLID_TOKENS.includes(background)) {
+            style.background = { kind: 'solid', token: background };
+        }
+        else
+            style.background = background;
+    }
+    const start = value('start');
+    if (start !== undefined)
+        navigation.start = start;
+    const loop = value('loop');
+    if (loop !== undefined)
+        navigation.loop = loop;
+    const autoSlide = value('autoSlide');
+    if (autoSlide !== undefined)
+        navigation.autoSlideMs = autoSlide;
+    const outlineTitle = value('outlineTitle');
+    deck.meta = meta;
+    if (Object.keys(style).length > 0)
+        deck.style = style;
+    if (Object.keys(navigation).length > 0)
+        deck.navigation = navigation;
+    if (sections.length > 0) {
+        deck.outline = outlineTitle === undefined ? { sections } : { title: outlineTitle, sections };
+    }
+    else if (outlineTitle !== undefined) {
+        sink.report('md-frontmatter-value', '`outlineTitle` needs at least one section (`section=` or a `--` stack).', { line: front.lines.get('outlineTitle') ?? 1, column: 1 });
+    }
+    deck.slides = slides;
+    return { draft: deck, sink, map };
+}
+/** The source of the longest prefix of `path` that was recorded. */
+function locate(map, path) {
+    for (let n = path.length; n >= 0; n--) {
+        const found = map.get(toJsonPath(path.slice(0, n)));
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/**
+ * Parse a deck Markdown document into a validated v2 deck. Every dialect and
+ * model issue is reported (capped at 200) with a source line and column;
+ * `ok` is true only when there is no error. Never throws.
+ */
+export function parseDeckMarkdown(text, options = {}) {
+    let read;
+    try {
+        read = readDeckDraft(text);
+    }
+    catch {
+        const sink = new IssueSink();
+        sink.report('md-too-large', 'The document could not be read.', { line: 1, column: 1 });
+        return { ok: false, issues: sink.issues, steps: [], truncated: false, sourceMap: new Map() };
+    }
+    const { draft, sink, map } = read;
+    if (draft === null) {
+        return { ok: false, issues: sink.issues, steps: [], truncated: sink.truncated, sourceMap: map };
+    }
+    const model = parseDeck(draft, options);
+    const issues = [...sink.issues];
+    const max = options.maxIssues !== undefined && options.maxIssues > 0
+        ? options.maxIssues
+        : DECK_MARKDOWN_LIMITS.issues;
+    let truncated = sink.truncated || model.truncated;
+    for (const issue of model.issues) {
+        if (issues.length >= max) {
+            truncated = true;
+            break;
+        }
+        if (issue.source === undefined) {
+            const source = locate(map, issue.path);
+            if (source)
+                issue.source = { ...source };
+        }
+        issues.push(issue);
+    }
+    if (issues.length > max) {
+        issues.length = max;
+        truncated = true;
+    }
+    const ok = model.ok && sink.errors === 0;
+    const result = {
+        ok,
+        issues,
+        steps: model.steps,
+        truncated,
+        draft,
+        sourceMap: map,
+    };
+    if (ok && model.deck)
+        result.deck = model.deck;
+    return result;
+}

package/dist/markdown/scan.d.ts

@@ -0,0 +1,26 @@
+import type { IssueSink } from './issues.js';
+export interface Line {
+    text: string;
+    /** 1-based line number in the source. */
+    n: number;
+}
+export interface RawSlide {
+    lines: Line[];
+    /** Came after a `--` line: part of the previous horizontal slide's stack. */
+    vertical: boolean;
+    /** The line where the slide starts (its first line, or its separator + 1). */
+    line: number;
+}
+export interface Scanned {
+    frontmatter: Line[] | null;
+    /** Line of the opening `---` of the frontmatter. */
+    frontmatterLine: number;
+    slides: RawSlide[];
+}
+/**
+ * Line endings normalized (CR LF, CR, U+2028 and U+2029 become line feeds),
+ * size bounds applied, hidden characters reported and removed.
+ */
+export declare function normalizeLines(text: string, sink: IssueSink): Line[] | null;
+/** Split the frontmatter and the slides. */
+export declare function scanDocument(lines: Line[], sink: IssueSink): Scanned;

package/dist/markdown/scan.js

@@ -0,0 +1,138 @@
+/**
+ * The line scanner: input bounds, line endings and hidden characters, the
+ * frontmatter block, and the split into slides at `---` (horizontal) and
+ * `--` (vertical) lines outside code and math fences. One pass over the
+ * lines (a second, fence-bounded pass only after an unclosed fence).
+ */
+import { utf8Length } from "../model/plain.js";
+import { DECK_MARKDOWN_LIMITS } from "./limits.js";
+import { isHiddenCode } from "./text.js";
+/**
+ * Line endings normalized (CR LF, CR, U+2028 and U+2029 become line feeds),
+ * size bounds applied, hidden characters reported and removed.
+ */
+export function normalizeLines(text, sink) {
+    if (utf8Length(text) > DECK_MARKDOWN_LIMITS.bytes) {
+        sink.report('md-too-large', `The document is over ${DECK_MARKDOWN_LIMITS.bytes} bytes; nothing was read.`, { line: 1, column: 1 }, [], 'Split the deck, or move large data out of the Markdown.');
+        return null;
+    }
+    let source = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    // U+2028 and U+2029 are line terminators to JavaScript regexes (`.` and `$`
+    // stop at them), so they end a line here too: no line holds one.
+    source = source.replace(/\r\n?|[\u2028\u2029]/g, '\n');
+    const raw = source.split('\n');
+    if (raw.length > DECK_MARKDOWN_LIMITS.lines) {
+        sink.report('md-too-large', `The document is over ${DECK_MARKDOWN_LIMITS.lines} lines; the rest was not read.`, { line: DECK_MARKDOWN_LIMITS.lines + 1, column: 1 });
+        raw.length = DECK_MARKDOWN_LIMITS.lines;
+    }
+    const lines = [];
+    for (let index = 0; index < raw.length; index++) {
+        let line = raw[index] ?? '';
+        const n = index + 1;
+        if (line.length > DECK_MARKDOWN_LIMITS.lineLength) {
+            sink.report('md-too-large', `A line is at most ${DECK_MARKDOWN_LIMITS.lineLength} characters; the rest was cut.`, { line: n, column: DECK_MARKDOWN_LIMITS.lineLength + 1 });
+            line = line.slice(0, DECK_MARKDOWN_LIMITS.lineLength);
+        }
+        let clean = '';
+        let start = 0;
+        let reported = false;
+        for (let i = 0; i < line.length; i++) {
+            const code = line.charCodeAt(i);
+            if (code === 0x09 || !isHiddenCode(code))
+                continue;
+            if (!reported) {
+                sink.report('md-invisible-char', `Hidden character U+${code.toString(16).toUpperCase().padStart(4, '0')} (control, bidi or invisible formatting).`, { line: n, column: i + 1 }, [], 'Delete the character; it can hide or reorder text (Trojan Source).');
+                reported = true;
+            }
+            clean += line.slice(start, i);
+            start = i + 1;
+        }
+        lines.push({ text: start === 0 ? line : clean + line.slice(start), n });
+    }
+    return lines;
+}
+const H_SEP = /^-{3,}[ \t]*$/;
+const V_SEP = /^--[ \t]*$/;
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})/;
+const MATH_FENCE = /^ {0,3}\$\$[ \t]*$/;
+function closesFence(text, char, length) {
+    const match = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(text);
+    return match?.[1] !== undefined && match[1][0] === char && match[1].length >= length;
+}
+/** Split the frontmatter and the slides. */
+export function scanDocument(lines, sink) {
+    let start = 0;
+    let frontmatter = null;
+    if (lines.length > 0 && /^---[ \t]*$/.test(lines[0]?.text ?? '')) {
+        let close = -1;
+        const end = Math.min(lines.length, DECK_MARKDOWN_LIMITS.frontmatterLines + 2);
+        for (let i = 1; i < end; i++) {
+            if (/^---[ \t]*$/.test(lines[i]?.text ?? '')) {
+                close = i;
+                break;
+            }
+        }
+        if (close === -1) {
+            sink.report('md-frontmatter-unclosed', `The frontmatter has no closing \`---\` within ${DECK_MARKDOWN_LIMITS.frontmatterLines} lines.`, { line: 1, column: 1 }, [], 'Close the frontmatter with a `---` line.');
+        }
+        else {
+            frontmatter = lines.slice(1, close);
+            start = close + 1;
+        }
+    }
+    const slides = splitSlides(lines, start, false);
+    return {
+        frontmatter,
+        frontmatterLine: 1,
+        slides: slides ?? splitSlides(lines, start, true) ?? [],
+    };
+}
+/**
+ * Split at separators. Returns null when a fence is still open at the end of
+ * the document; the caller then splits again with `bounded`, where every
+ * fence ends at the next separator line (so one bad fence cannot swallow the
+ * rest of the deck).
+ */
+function splitSlides(lines, from, bounded) {
+    const slides = [];
+    let current = { lines: [], vertical: false, line: lines[from]?.n ?? 1 };
+    let fence = null;
+    let math = false;
+    for (let i = from; i < lines.length; i++) {
+        const line = lines[i];
+        const text = line.text;
+        if (fence !== null || math) {
+            const separator = H_SEP.test(text) || V_SEP.test(text);
+            if (bounded && separator) {
+                fence = null;
+                math = false;
+            }
+            else {
+                if (fence !== null && closesFence(text, fence.char, fence.length))
+                    fence = null;
+                else if (math && MATH_FENCE.test(text))
+                    math = false;
+                current.lines.push(line);
+                continue;
+            }
+        }
+        if (H_SEP.test(text) || V_SEP.test(text)) {
+            slides.push(current);
+            current = { lines: [], vertical: V_SEP.test(text), line: line.n + 1 };
+            continue;
+        }
+        const open = FENCE_OPEN.exec(text);
+        if (open?.[1] !== undefined &&
+            !(open[1][0] === '`' && text.slice(open[0].length).includes('`'))) {
+            fence = { char: open[1][0] ?? '`', length: open[1].length };
+        }
+        else if (MATH_FENCE.test(text)) {
+            math = true;
+        }
+        current.lines.push(line);
+    }
+    if ((fence !== null || math) && !bounded)
+        return null;
+    slides.push(current);
+    return slides;
+}

package/dist/markdown/slides.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Slide builder: the nodes of one slide → a v2 slide object (not yet
+ * validated), with fragments numbered the reveal.js way and a source map
+ * from JSON paths to Markdown positions. Free slides get blocks; the 20
+ * catalog layouts map headings, paragraphs, lists, images, tables and `:::`
+ * regions onto their props; `component`, `custom` and `::: props` / `::: slide`
+ * fences carry bounded JSON.
+ */
+import { type SlideAttrRead } from './attrs-closed.js';
+import type { SlideSource, Src } from './blocks.js';
+import type { IssueSink } from './issues.js';
+type Bag = Record<string, unknown>;
+/** Shared state across the slides of one document. */
+export interface BuildContext {
+    sink: IssueSink;
+    /** JSON path → source position. */
+    map: Map<string, Src>;
+    /** JSON values still allowed in fence bodies. */
+    jsonBudget: {
+        nodes: number;
+    };
+}
+export interface BuiltSlide {
+    slide: Bag;
+    attrs: SlideAttrRead;
+    src: Src;
+}
+/** Build one slide. `index` is its position in `slides`. */
+export declare function buildSlide(source: SlideSource, index: number, src: Src, ctx: BuildContext): BuiltSlide;
+/** The text an id is derived from: the slide title, the props title, or a free slide's first heading. */
+export declare function idCandidate(slide: Bag): string;
+export {};