@texuli/deck 0.0.0-stage → 0.5.0

package/dist/markdown/twin.js

@@ -0,0 +1,374 @@
+/**
+ * Text twins of a deck, ported from Protoyard's `text/deck.ts` onto model
+ * v2: `deckToText` (a readable Markdown document for accessibility, artifact
+ * descriptions and LLM context; one-way, unlike `deckToMarkdown`) and
+ * `deckOutline` (one compact row per slide). Both are pure and
+ * deterministic, and nothing an author typed can become HTML or a link
+ * target in them: plain fields are escaped and Markdown fields made inert
+ * (no raw HTML, and a link whose target is not `https:`, `http:`,
+ * `mailto:`, a fragment or a relative path keeps its label and loses its
+ * URL; see `neutralizeLinks`).
+ */
+import { mathText, texToMath } from "../math/index.js";
+import { escapeInline, escapeText, fenceFor, inertMarkdown, inlineCode, linkTarget, neutralizeLinks, stripHidden, trimCharEnd, } from "./text.js";
+const join = (parts) => parts
+    .filter((part) => typeof part === 'string' && part.trim().length > 0)
+    .join('\n\n');
+const h = (level, text) => `${'#'.repeat(Math.min(6, Math.max(1, level)))} ${escapeInline(text)}`;
+const str = (value) => typeof value === 'string' ? value : value === undefined || value === null ? '' : String(value);
+const italic = (text) => (text.trim() ? `*${escapeInline(text)}*` : '');
+function image(alt, src) {
+    const source = str(src);
+    return source && !source.startsWith('data:') && !source.startsWith('avatar:')
+        ? `![${escapeInline(str(alt))}](${linkTarget(source)})`
+        : `*\\[Image: ${escapeInline(str(alt))}\\]*`;
+}
+const video = (label) => `*\\[Video${str(label) ? `: ${escapeInline(str(label))}` : ''}\\]*`;
+function table(header, rows) {
+    if (header.length === 0)
+        return '';
+    const cell = (value) => escapeInline(value ?? '') || ' ';
+    const line = (cells) => `| ${header.map((_, i) => cell(cells[i])).join(' | ')} |`;
+    return [line(header), `| ${header.map(() => '---').join(' | ')} |`, ...rows.map(line)].join('\n');
+}
+function codeFence(code, lang) {
+    const body = trimCharEnd(stripHidden(code), '\n');
+    const fence = fenceFor(body);
+    return `${fence}${lang.replace(/[^\w+-]/g, '').slice(0, 24)}\n${body}\n${fence}`;
+}
+const markdown = (value) => inertMarkdown(neutralizeLinks(str(value))).trim();
+/** Every string of a value, labelled by key path (unknown shapes, component props). */
+function strings(value, path = [], out = [], depth = 0) {
+    if (depth > 6 || out.length >= 100)
+        return out;
+    if (typeof value === 'string') {
+        out.push(`- ${path.length ? `${escapeInline(path.join('.'))}: ` : ''}${escapeInline(value)}`);
+    }
+    else if (typeof value === 'number' || typeof value === 'boolean') {
+        out.push(`- ${escapeInline(path.join('.'))}: ${String(value)}`);
+    }
+    else if (Array.isArray(value)) {
+        value.forEach((item, i) => {
+            strings(item, [...path, String(i + 1)], out, depth + 1);
+        });
+    }
+    else if (value && typeof value === 'object') {
+        for (const [key, item] of Object.entries(value))
+            strings(item, [...path, key], out, depth + 1);
+    }
+    return out;
+}
+function chartText(spec) {
+    const series = Array.isArray(spec.series) ? spec.series : [];
+    const labels = Array.isArray(spec.labels) ? spec.labels.map(str) : [];
+    const head = `*Chart (${escapeInline(str(spec.kind))}): ${escapeInline(str(spec.title))}*`;
+    if (series.length === 0 || labels.length === 0)
+        return join([head, spec.description ? escapeInline(str(spec.description)) : '']);
+    const rows = labels.map((label, i) => [
+        label,
+        ...series.map((s) => {
+            const values = Array.isArray(s.values) ? s.values : [];
+            const v = values[i];
+            return typeof v === 'number' ? String(Math.round(v * 1000) / 1000) : '';
+        }),
+    ]);
+    return join([
+        head,
+        spec.description ? escapeInline(str(spec.description)) : '',
+        table(['', ...series.map((s) => str(s.label))], rows),
+    ]);
+}
+function blockText(block, level) {
+    switch (block.type) {
+        case 'heading':
+            return join([
+                block.eyebrow ? italic(str(block.eyebrow)) : '',
+                h(level + Math.max(0, Number(block.level ?? 2) - 1), str(block.text)),
+                block.subtitle ? escapeText(str(block.subtitle)) : '',
+            ]);
+        case 'text':
+            return markdown(block.markdown);
+        case 'list':
+            return (Array.isArray(block.items) ? block.items : [])
+                .map((item, i) => `${block.ordered === true ? `${i + 1}.` : '-'} ${markdown(item.text).split('\n').join('\n   ')}`)
+                .join('\n');
+        case 'quote':
+            return [
+                ...markdown(block.quote).split('\n'),
+                ...(block.cite ? ['', `— ${escapeInline(str(block.cite))}`] : []),
+            ]
+                .map((line) => (line ? `> ${line}` : '>'))
+                .join('\n');
+        case 'callout':
+            return join([
+                block.title ? `**${escapeInline(str(block.title))}**` : '',
+                markdown(block.body),
+            ])
+                .split('\n')
+                .map((line) => (line ? `> ${line}` : '>'))
+                .join('\n');
+        case 'divider':
+            return '***';
+        case 'image':
+            return join([image(block.alt, block.src), block.caption ? italic(str(block.caption)) : '']);
+        case 'video':
+            return video(block.label);
+        case 'table': {
+            const columns = Array.isArray(block.columns) ? block.columns : [];
+            const rows = Array.isArray(block.rows) ? block.rows : [];
+            return join([
+                block.caption ? italic(str(block.caption)) : '',
+                table(columns.map((c) => str(c.label)), rows.map((row) => columns.map((c) => str(row[str(c.id)])))),
+            ]);
+        }
+        case 'code':
+            return join([
+                block.filename ? italic(str(block.filename)) : '',
+                codeFence(str(block.code), str(block.lang)),
+                block.caption ? italic(str(block.caption)) : '',
+            ]);
+        case 'math': {
+            const result = texToMath(str(block.tex), { display: true });
+            return `*Formula: ${escapeInline(result.ok ? mathText(result.node) : str(block.tex))}* ${inlineCode(str(block.tex))}`;
+        }
+        case 'chart':
+            return chartText(block);
+        case 'component': {
+            const lines = strings(block.props);
+            return join([`*Component ${inlineCode(str(block.component))}*`, lines.join('\n')]);
+        }
+        default: {
+            const nested = [];
+            for (const key of ['blocks', 'children']) {
+                if (Array.isArray(block[key]))
+                    nested.push(blocksText(block[key], level));
+            }
+            if (Array.isArray(block.columns) && block.type === 'columns') {
+                for (const column of block.columns)
+                    if (Array.isArray(column))
+                        nested.push(blocksText(column, level));
+            }
+            if (Array.isArray(block.panels)) {
+                for (const panel of block.panels) {
+                    nested.push(join([
+                        h(level, str(panel.label)),
+                        Array.isArray(panel.blocks) ? blocksText(panel.blocks, level + 1) : '',
+                    ]));
+                }
+            }
+            if (nested.length > 0)
+                return join(nested);
+            const copy = { ...block };
+            delete copy.type;
+            delete copy.id;
+            const lines = strings(copy);
+            return join([`*\\[${escapeInline(str(block.type))}\\]*`, lines.join('\n')]);
+        }
+    }
+}
+function blocksText(blocks, level) {
+    return join(blocks.map((block) => blockText(block, level)));
+}
+/** Body Markdown per catalog layout, from its validated props. */
+const LAYOUT_TEXT = {
+    'title-hero': (p) => join([p.subtitle ? escapeText(str(p.subtitle)) : '', p.meta ? italic(str(p.meta)) : '']),
+    'section-divider': (p) => (p.eyebrow ? italic(str(p.eyebrow)) : ''),
+    'two-column-split': (p, level) => join([p.left, p.right].flatMap((side) => [
+        side?.heading ? h(level, str(side.heading)) : '',
+        escapeText(str(side?.body)),
+    ])),
+    'three-column-cards': (p, level) => join(p.cards.flatMap((card) => [
+        h(level, str(card.heading)),
+        escapeText(str(card.body)),
+    ])),
+    'image-left': imageSide,
+    'image-right': imageSide,
+    'image-centered': (p) => join([
+        image(p.image.alt, p.image.src),
+        p.caption ? italic(str(p.caption)) : '',
+    ]),
+    'image-full-bleed': (p) => join([
+        image(p.image.alt, p.image.src),
+        p.caption ? italic(str(p.caption)) : '',
+        p.credit ? italic(`Credit: ${str(p.credit)}`) : '',
+    ]),
+    quote: (p) => [
+        ...escapeText(str(p.quote)).split('\n'),
+        ...(p.cite ? ['', `— ${escapeInline(str(p.cite))}`] : []),
+    ]
+        .map((line) => (line ? `> ${line}` : '>'))
+        .join('\n'),
+    'code-with-callout': (p, level) => {
+        const code = p.code;
+        const highlights = Array.isArray(code.highlights)
+            ? code.highlights.map(str)
+            : [];
+        return join([
+            codeFence(str(code.source), str(code.lang)),
+            highlights.length
+                ? `*Highlighted lines, step by step: ${highlights.map(escapeInline).join(' → ')}*`
+                : '',
+            p.heading ? h(level, str(p.heading)) : '',
+            p.bullets.map((bullet) => `- ${escapeInline(str(bullet))}`).join('\n'),
+        ]);
+    },
+    'big-stat': (p) => join([
+        `**${escapeInline(str(p.number))}** ${escapeInline(str(p.label))}`,
+        p.context ? escapeText(str(p.context)) : '',
+        p.source ? italic(`Source: ${str(p.source)}`) : '',
+    ]),
+    'comparison-table': (p) => table(['', ...p.columns.map(str)], p.rows.map((row) => [
+        str(row.label),
+        ...row.values.map((v) => (v === true ? 'Yes' : v === false ? 'No' : str(v))),
+    ])),
+    'process-steps': (p) => p.steps
+        .map((step, i) => `${i + 1}. **${escapeInline(str(step.title))}**${step.body ? ` ${escapeInline(str(step.body))}` : ''}`)
+        .join('\n'),
+    timeline: (p) => p.events
+        .map((event) => `- **${escapeInline(str(event.time))}** ${escapeInline(str(event.text))}`)
+        .join('\n'),
+    'team-avatars': (p) => p.people
+        .map((person) => `- **${escapeInline(str(person.name))}**${person.role ? ` — ${escapeInline(str(person.role))}` : ''}`)
+        .join('\n'),
+    'closing-cta': (p) => {
+        const cta = p.cta;
+        const href = str(cta.href);
+        const safe = /^(?:https:|mailto:|#)/.test(href) || (/^[A-Za-z0-9._~/-]/.test(href) && !href.includes(':'));
+        return join([
+            p.text ? escapeText(str(p.text)) : '',
+            safe
+                ? `[${escapeInline(str(cta.label))}](${linkTarget(href)})`
+                : escapeInline(str(cta.label)),
+            p.footnote ? italic(str(p.footnote)) : '',
+        ]);
+    },
+    'video-centered': (p) => join([video(p.video.label), p.caption ? italic(str(p.caption)) : '']),
+    'video-left': videoSide,
+    'video-right': videoSide,
+    chart: (p) => chartText(p.spec),
+};
+function imageSide(p, level) {
+    return join([
+        image(p.image.alt, p.image.src),
+        p.heading ? h(level, str(p.heading)) : '',
+        escapeText(str(p.body)),
+    ]);
+}
+function videoSide(p, level) {
+    return join([
+        video(p.video.label),
+        p.heading ? h(level, str(p.heading)) : '',
+        escapeText(str(p.body)),
+    ]);
+}
+/** The title a slide is known by: its own, else the layout's title prop, else the first heading. */
+export function slideTitle(slide) {
+    const own = slide.title?.trim();
+    if (own)
+        return own;
+    const bag = slide;
+    if (Array.isArray(bag.blocks)) {
+        const first = bag.blocks.find((block) => block.type === 'heading');
+        return first ? str(first.text).trim() || null : null;
+    }
+    const props = (bag.props ?? {});
+    if (slide.layout === 'custom')
+        return null;
+    for (const key of ['title', 'heading', 'number']) {
+        const value = props[key];
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    if (slide.layout === 'quote' && typeof props.quote === 'string') {
+        const quote = props.quote.trim().replace(/\s+/g, ' ');
+        return quote.length > 60 ? `${quote.slice(0, 59)}…` : quote;
+    }
+    return null;
+}
+function slideBody(slide, level) {
+    const bag = slide;
+    if (slide.layout === 'free')
+        return blocksText(bag.blocks, level);
+    if (slide.layout === 'component') {
+        const component = bag.component;
+        return blockText({ type: 'component', component: component.component, props: component.props }, level);
+    }
+    if (slide.layout === 'custom') {
+        const props = bag.props;
+        return join([
+            `*Custom slide ${inlineCode(str(props.component))}*`,
+            strings(props.data).join('\n'),
+        ]);
+    }
+    const render = LAYOUT_TEXT[slide.layout];
+    return render ? render(bag.props, level) : strings(bag.props).join('\n');
+}
+function listed(deck, includeHidden) {
+    const sectionOf = new Map();
+    for (const section of deck.outline?.sections ?? []) {
+        for (const id of section.slideIds) {
+            if (!sectionOf.has(id))
+                sectionOf.set(id, section.title === undefined
+                    ? { id: section.id }
+                    : { id: section.id, title: section.title });
+        }
+    }
+    return deck.slides
+        .filter((slide) => includeHidden || !slide.hidden)
+        .map((slide, i) => ({ slide, number: i + 1, section: sectionOf.get(slide.id) ?? null }));
+}
+/** Never a valid section id (ids are lowercase slugs). */
+const UNGROUPED = '#ungrouped';
+/** The deck as a readable, inert Markdown document (one-way; see `deckToMarkdown` for the round-trip form). */
+export function deckToText(deck, options = {}) {
+    const includeNotes = options.notes ?? true;
+    const slides = listed(deck, options.includeHidden ?? false);
+    const hasSections = slides.some((entry) => entry.section !== null);
+    const slideLevel = hasSections ? 3 : 2;
+    const parts = [
+        h(1, deck.outline?.title?.trim() || options.title?.trim() || deck.meta.title),
+    ];
+    let current = null;
+    for (const { slide, number, section } of slides) {
+        if (hasSections && section && section.id !== current) {
+            current = section.id;
+            parts.push(h(2, section.title?.trim() || section.id));
+        }
+        else if (hasSections && !section && current !== null && current !== UNGROUPED) {
+            current = UNGROUPED;
+            parts.push(h(2, 'Other slides'));
+        }
+        const title = slideTitle(slide);
+        parts.push(join([
+            `${'#'.repeat(slideLevel)} ${number}. ${title ? escapeInline(title) : `Slide ${number}`}`,
+            slideBody(slide, slideLevel + 1),
+            includeNotes &&
+                slide.notes?.trim() &&
+                join([h(slideLevel + 1, 'Notes'), escapeText(slide.notes)]),
+        ]));
+    }
+    return `${parts.join('\n\n')}\n`;
+}
+/** A title for the outline, with unsafe link targets dropped (see `neutralizeLinks`). */
+const outlineTitle = (title) => (title === null ? null : neutralizeLinks(title));
+/** One compact row per slide: id, layout and title (for authoring hints, MCP and agents). */
+export function deckOutline(deck, options = {}) {
+    return {
+        title: outlineTitle(deck.outline?.title?.trim() || deck.meta.title.trim() || null),
+        slides: listed(deck, options.includeHidden ?? true).map(({ slide, number, section }) => ({
+            number,
+            id: slide.id,
+            layout: slide.layout,
+            title: outlineTitle(slideTitle(slide)),
+            section: section?.id ?? null,
+            hidden: slide.hidden === true,
+        })),
+    };
+}
+/** The outline as plain lines: `3. pricing · comparison-table · Plans compared`. */
+export function formatDeckOutline(outline) {
+    const clean = (text) => neutralizeLinks(text).replace(/\s+/g, ' ').trim();
+    return outline.slides
+        .map((slide) => `${slide.number}. ${slide.id} · ${slide.layout}${slide.title ? ` · ${clean(slide.title)}` : ''}${slide.hidden ? ' (hidden)' : ''}`)
+        .join('\n');
+}

package/dist/markdown/write.d.ts

@@ -0,0 +1,17 @@
+import type { Deck, DeckSlide } from '../model/deck.js';
+import { type DeckDiagnostic } from '../schema/index.js';
+export interface DeckMarkdownWriteResult {
+    markdown: string;
+    /** `md-unrepresentable` warnings: deck fields the Markdown could not carry. */
+    issues: DeckDiagnostic[];
+}
+/**
+ * Write a validated deck as canonical deck Markdown, with `md-unrepresentable`
+ * warnings for deck-level fields the dialect cannot hold. Slides and blocks
+ * always round-trip (as Markdown when it reads back exactly, otherwise as JSON
+ * fences).
+ */
+export declare function writeDeckMarkdown(deck: Deck): DeckMarkdownWriteResult;
+/** A validated deck as canonical deck Markdown (see `writeDeckMarkdown` for the warnings). */
+export declare function deckToMarkdown(deck: Deck): string;
+export type { DeckSlide };