@texuli/deck 0.0.0-stage → 0.4.0

package/dist/authoring/lint.d.ts

@@ -0,0 +1,36 @@
+import { type Deck } from '../model/index.js';
+import { type DeckDiagnostic } from '../schema/index.js';
+export declare const DECK_LINT_RULES: Readonly<{
+    readonly errors: readonly ["unknown-layout", "layout-props", "image-alt", "image-size", "step-order"];
+    readonly warnings: readonly ["empty-steps", "unknown-background", "custom-slide", "step-unrevealed", "notes-missing", "notes-duplicate", "notes-boilerplate", "layout-repetition", "too-many-words"];
+    readonly suggestions: readonly ["prefer-layout"];
+}>;
+export type DeckLintRule = (typeof DECK_LINT_RULES.errors)[number] | (typeof DECK_LINT_RULES.warnings)[number] | 'prefer-layout' | (string & {});
+export interface DeckLintIssue extends DeckDiagnostic {
+    rule: DeckLintRule;
+}
+export interface DeckLintReport {
+    ok: boolean;
+    /** Every distinct error found, also past the `issues` cap. */
+    errors: number;
+    /** Every distinct warning found, also past the `issues` cap. */
+    warnings: number;
+    /** At most `DECK_LINT_MAX_ISSUES`, one per rule and path. */
+    issues: DeckLintIssue[];
+    /** True when issues past the cap were counted but not listed. */
+    truncated: boolean;
+}
+/** Issues listed in one report (the model's diagnostics cap); the rest are counted. */
+export declare const DECK_LINT_MAX_ISSUES = 200;
+/**
+ * Static quality checks. It accepts untrusted input and never throws. Work is
+ * bounded: one issue per rule and path (a set, not a scan), at most
+ * `DECK_LINT_MAX_ISSUES` listed, and a deck over the model's structural
+ * limits (`too-many`, `too-deep`) reports the model issues without the
+ * quality pass.
+ */
+export declare function lintDeck(value: unknown): DeckLintReport;
+export declare const DECK_AUTHORING_LIMITS: Readonly<{
+    slides: 200;
+}>;
+export type { Deck };

package/dist/authoring/lint.js

@@ -0,0 +1,325 @@
+import { DECK_BACKGROUND_PRESET_IDS } from "../model/backgrounds/index.js";
+import { DECK_MODEL_LIMITS, DECK_SLIDE_LAYOUTS, parseDeck, slideSteps, } from "../model/index.js";
+import { validateLayoutProps } from "../model/layouts/index.js";
+import { createDiagnostic } from "../schema/index.js";
+export const DECK_LINT_RULES = Object.freeze({
+    errors: ['unknown-layout', 'layout-props', 'image-alt', 'image-size', 'step-order'],
+    warnings: [
+        'empty-steps',
+        'unknown-background',
+        'custom-slide',
+        'step-unrevealed',
+        'notes-missing',
+        'notes-duplicate',
+        'notes-boilerplate',
+        'layout-repetition',
+        'too-many-words',
+    ],
+    suggestions: ['prefer-layout'],
+});
+/** Issues listed in one report (the model's diagnostics cap); the rest are counted. */
+export const DECK_LINT_MAX_ISSUES = 200;
+/** How deep `wordCount` reads a value (the model refuses deeper values anyway). */
+const WORD_DEPTH = 32;
+const asRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : undefined;
+/**
+ * Keys whose strings are text a viewer reads: titles, bodies, list items,
+ * labels and captions. Everything else (chart kinds, ids, URLs, alt text,
+ * code, sizes, widths, tones, step fields) is a setting, not words on the
+ * slide. A string inside an array counts when the array's key does
+ * (`bullets`, comparison `columns` and `values`).
+ */
+const HUMAN_TEXT_KEYS = new Set([
+    'title',
+    'subtitle',
+    'eyebrow',
+    'meta',
+    'heading',
+    'body',
+    'text',
+    'markdown',
+    'quote',
+    'cite',
+    'caption',
+    'credit',
+    'label',
+    'description',
+    'context',
+    'footnote',
+    'name',
+    'role',
+    'number',
+    'bullets',
+    'items',
+    'columns',
+    'values',
+    'time',
+    'summary',
+    'content',
+]);
+const WORD = /[\p{L}\p{N}]+(?:['’][\p{L}\p{N}]+)*/gu;
+/** Link destinations in Markdown text: `](https://…)` is not words on the slide. */
+const LINK_DESTINATION = /\]\([^)\s]*\)/g;
+/**
+ * Words of human text in a value (see `HUMAN_TEXT_KEYS`). `all` counts every
+ * string below (the cells of a table block's `rows`, keyed by column id).
+ */
+function wordCount(value, human = false, all = false, depth = 0) {
+    if (typeof value === 'string') {
+        if (!human && !all)
+            return 0;
+        return (value.replace(LINK_DESTINATION, ']').match(WORD) ?? []).length;
+    }
+    if (depth >= WORD_DEPTH)
+        return 0;
+    if (Array.isArray(value))
+        return value.reduce((sum, item) => sum + wordCount(item, human, all, depth + 1), 0);
+    const record = asRecord(value);
+    if (!record)
+        return 0;
+    let sum = 0;
+    for (const [key, child] of Object.entries(record)) {
+        const rows = all || (record.type === 'table' && key === 'rows');
+        sum += wordCount(child, all || HUMAN_TEXT_KEYS.has(key), rows, depth + 1);
+    }
+    return sum;
+}
+/** Boilerplate notes phrases, matched inside normalized notes (lowercase, punctuation as spaces). */
+const BOILERPLATE_NOTES = [
+    'do not read the slide',
+    "don't read the slide",
+    'dont read the slide',
+    'no leer la diapositiva',
+];
+/** Notes lowercased with punctuation as single spaces (`’` read as `'`). */
+const normalizeNotes = (notes) => notes
+    .toLowerCase()
+    .replace(/’/g, "'")
+    .replace(/[^\p{L}\p{N}']+/gu, ' ')
+    .trim();
+/** How a message names a slide: `slide "pricing"`, or its position when it has no id. */
+const slideName = (item, index) => typeof item.id === 'string' && item.id !== ''
+    ? `slide ${JSON.stringify(item.id.slice(0, 64))}`
+    : `slide ${index + 1}`;
+const quoted = (text, max = 60) => JSON.stringify(text.length > max ? `${text.slice(0, max - 1)}…` : text);
+/**
+ * Static quality checks. It accepts untrusted input and never throws. Work is
+ * bounded: one issue per rule and path (a set, not a scan), at most
+ * `DECK_LINT_MAX_ISSUES` listed, and a deck over the model's structural
+ * limits (`too-many`, `too-deep`) reports the model issues without the
+ * quality pass.
+ */
+export function lintDeck(value) {
+    const parsed = parseDeck(value);
+    const issues = [];
+    const seen = new Set();
+    let errors = 0;
+    let warnings = 0;
+    const add = (rule, severity, message, path, fix) => {
+        const key = JSON.stringify([rule, path]);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        if (severity === 'error')
+            errors++;
+        else
+            warnings++;
+        if (issues.length >= DECK_LINT_MAX_ISSUES)
+            return;
+        issues.push({
+            ...createDiagnostic(rule, message, path, fix ? { fix } : undefined),
+            rule,
+            severity,
+        });
+    };
+    const report = () => ({
+        ok: errors === 0,
+        errors,
+        warnings,
+        issues,
+        truncated: errors + warnings > issues.length || parsed.truncated === true,
+    });
+    const raw = asRecord(value);
+    const slides = Array.isArray(raw?.slides) ? raw.slides : [];
+    for (const issue of parsed.issues) {
+        if (issue.code === 'unknown-background' || issue.code === 'step-unrevealed')
+            continue;
+        const path = issue.path;
+        const layout = path.at(-1) === 'layout' || path.at(-2) === 'layout';
+        const rule = issue.code === 'unknown-layout' || layout
+            ? 'unknown-layout'
+            : path.includes('props')
+                ? 'layout-props'
+                : issue.code;
+        add(rule, issue.severity, issue.message, path, issue.fix);
+    }
+    // Over a structural limit: the model issues say what to fix; a quality pass
+    // over 16,000 slides or a 5,000-deep value would only add noise and work.
+    if (parsed.issues.some((issue) => issue.code === 'too-many' || issue.code === 'too-deep')) {
+        return report();
+    }
+    const notesSeen = new Map();
+    let previousLayout = '';
+    let run = 0;
+    slides.forEach((rawSlide, index) => {
+        const item = asRecord(rawSlide);
+        if (!item)
+            return;
+        const base = ['slides', index];
+        const layout = item.layout;
+        if (typeof layout === 'string' &&
+            DECK_SLIDE_LAYOUTS.includes(layout) &&
+            layout !== 'free' &&
+            layout !== 'component' &&
+            layout !== 'custom' &&
+            asRecord(item.props)) {
+            const result = validateLayoutProps(layout, item.props, { path: [...base, 'props'] });
+            for (const problem of result.issues)
+                add('layout-props', 'error', problem.message, problem.path, problem.fix);
+        }
+        if (layout === 'custom')
+            add('custom-slide', 'warning', 'Custom slides depend on a host renderer and may not travel with the deck.', [...base, 'props', 'component']);
+        if (typeof item.background === 'string' &&
+            !DECK_BACKGROUND_PRESET_IDS.includes(item.background)) {
+            add('unknown-background', 'warning', `Unknown background "${item.background}".`, [
+                ...base,
+                'background',
+            ]);
+        }
+        const props = asRecord(item.props);
+        const imageCheck = (record, path, isImage) => {
+            if (!isImage || !Object.hasOwn(record, 'src'))
+                return;
+            if (typeof record.alt !== 'string' || !record.alt.trim())
+                add('image-alt', 'error', 'Images need descriptive alt text.', [...path, 'alt']);
+            if (typeof record.width !== 'number' || typeof record.height !== 'number')
+                add('image-size', 'error', 'Images need intrinsic width and height.', path);
+        };
+        if (props)
+            walk(props, [...base, 'props'], (record, path) => imageCheck(record, path, path.at(-1) === 'image'));
+        if (Array.isArray(item.blocks))
+            walk(item.blocks, [...base, 'blocks'], (record, path) => imageCheck(record, path, record.type === 'image'));
+        const name = slideName(item, index);
+        const labels = Array.isArray(item.steps) ? item.steps : [];
+        const stepResult = slideSteps(item);
+        // A custom slide's host component reveals its own steps: its labels are the steps.
+        if (layout !== 'custom') {
+            labels.forEach((label, i) => {
+                const step = stepResult.steps[i + 1];
+                if (step && step.fragments.length > 0)
+                    return;
+                const text = typeof label === 'string' ? ` (${quoted(label)})` : '';
+                add('empty-steps', 'warning', `The ${name} labels step ${i + 1}${text} in "steps", but nothing reveals on it.`, [...base, 'steps', i], `Add a fragment with "step": ${i + 1}, or remove this label.`);
+            });
+        }
+        for (const problem of stepResult.issues)
+            if (problem.code === 'step-unrevealed')
+                add('step-unrevealed', 'warning', problem.message, [...base, ...problem.path], problem.fix);
+        let latest = 0;
+        const authoredSteps = [];
+        const collectSteps = (value, path) => walk(value, path, (record, current) => {
+            if (typeof record.step === 'number' && Number.isInteger(record.step) && record.step > 0)
+                authoredSteps.push({ value: record.step, path: [...current, 'step'] });
+        });
+        if (Array.isArray(item.blocks))
+            collectSteps(item.blocks, [...base, 'blocks']);
+        if (props)
+            collectSteps(props, [...base, 'props']);
+        for (const fragment of authoredSteps) {
+            if (fragment.value < latest)
+                add('step-order', 'error', 'A later element is revealed before an earlier element.', fragment.path);
+            latest = Math.max(latest, fragment.value);
+        }
+        const notes = typeof item.notes === 'string' ? item.notes.trim() : '';
+        const visible = item.hidden !== true;
+        if (visible && notes.length < 40)
+            add('notes-missing', 'warning', 'Visible slides should include useful speaker notes.', [
+                ...base,
+                'notes',
+            ]);
+        if (visible && notes) {
+            const normalized = normalizeNotes(notes);
+            const prior = notesSeen.get(normalized);
+            if (prior !== undefined)
+                add('notes-duplicate', 'warning', `Notes repeat slide ${prior + 1}.`, [...base, 'notes']);
+            else
+                notesSeen.set(normalized, index);
+            const padded = ` ${normalized} `;
+            const phrase = BOILERPLATE_NOTES.find((text) => padded.includes(` ${text} `));
+            if (phrase)
+                add('notes-boilerplate', 'warning', `The ${name} "notes" contain the boilerplate phrase "${phrase}".`, [...base, 'notes'], 'Replace it with what to say: the point, the evidence and the transition.');
+        }
+        if (visible) {
+            if (typeof layout === 'string' && layout === previousLayout)
+                run++;
+            else
+                run = 1;
+            if (run > 2)
+                add('layout-repetition', 'warning', `Layout "${layout}" repeats more than twice in a row.`, [...base, 'layout']);
+            previousLayout = typeof layout === 'string' ? layout : '';
+            const allowed = layout === 'title-hero' || layout === 'big-stat' ? 60 : 55;
+            // Words per part: free blocks, layout props by top-level key, or component props.
+            const parts = [];
+            if (layout === 'free' && Array.isArray(item.blocks)) {
+                item.blocks.forEach((block, b) => {
+                    const type = asRecord(block)?.type;
+                    parts.push({
+                        path: [...base, 'blocks', b],
+                        field: `blocks[${b}]${typeof type === 'string' ? ` (${type.slice(0, 32)})` : ''}`,
+                        words: wordCount(block),
+                    });
+                });
+            }
+            else if (layout === 'component') {
+                const component = asRecord(item.component);
+                parts.push({
+                    path: [...base, 'component', 'props'],
+                    field: 'component.props',
+                    words: wordCount(component?.props, false, false, 1),
+                });
+            }
+            else if (props) {
+                for (const [key, child] of Object.entries(props))
+                    parts.push({
+                        path: [...base, 'props'],
+                        field: `props.${key}`,
+                        words: wordCount({ [key]: child }),
+                    });
+            }
+            const textWords = parts.reduce((sum, part) => sum + part.words, 0);
+            const most = parts.reduce((best, part) => (best === undefined || part.words > best.words ? part : best), undefined);
+            if (textWords > allowed && most)
+                add('too-many-words', 'warning', `The ${name} has ${textWords} words of text; the suggested limit is ${allowed}. ${most.field} holds the most (${most.words}).`, most.path, 'Cut the text, split the slide, or move the detail into the speaker notes.');
+        }
+        if (visible && layout === 'free') {
+            const types = Array.isArray(item.blocks)
+                ? item.blocks.map((block) => asRecord(block)?.type)
+                : [];
+            const suggestion = types.find((type) => type === 'chart' ||
+                type === 'table' ||
+                type === 'quote' ||
+                type === 'code' ||
+                type === 'image');
+            if (typeof suggestion === 'string')
+                add('prefer-layout', 'warning', `A ${suggestion} block may fit a catalog layout better.`, [...base, 'layout'], 'Choose a matching catalog layout when its props fit the content.');
+        }
+    });
+    return report();
+}
+function walk(value, path, visit, depth = 0) {
+    if (depth > 12 || value === null || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+            walk(item, [...path, index], visit, depth + 1);
+        });
+        return;
+    }
+    const record = value;
+    visit(record, path);
+    for (const [key, child] of Object.entries(record))
+        walk(child, [...path, key], visit, depth + 1);
+}
+export const DECK_AUTHORING_LIMITS = Object.freeze({ slides: DECK_MODEL_LIMITS.slides });

package/dist/authoring/outlines.d.ts

@@ -0,0 +1,34 @@
+import type { Deck } from '../model/index.js';
+import { selectDeckLayouts } from './select-layouts.js';
+export declare const DECK_OUTLINE_IDS: readonly ["pitch", "qbr", "launch", "status", "training", "lesson", "report", "talk"];
+export type DeckOutlineId = (typeof DECK_OUTLINE_IDS)[number];
+export type DeckPacing = 'punch' | 'idea' | 'diagram' | 'story';
+export interface OutlineSlide {
+    key: string;
+    role: string;
+    pacing: DeckPacing;
+    title: string;
+    purpose: string;
+    optional?: boolean;
+}
+export interface DeckOutlineTemplate {
+    id: DeckOutlineId;
+    label: string;
+    cues: readonly string[];
+    slides: readonly OutlineSlide[];
+}
+/** Eight conservative, deterministic brief outlines. They contain prompts, never invented evidence. */
+export declare const DECK_OUTLINES: readonly DeckOutlineTemplate[];
+export interface GenerateBriefOptions {
+    brief: string;
+    title?: string;
+    outline?: DeckOutlineId;
+    locale?: string;
+}
+export interface GeneratedDeck {
+    deck: Deck;
+    outline: DeckOutlineId;
+    selection: ReturnType<typeof selectDeckLayouts>;
+}
+/** Build an honest, reproducible draft from a brief; missing evidence stays explicit. */
+export declare function generateDeckFromBrief(options: GenerateBriefOptions): GeneratedDeck;

package/dist/authoring/outlines.js

@@ -0,0 +1,255 @@
+import { DECK_LAYOUTS, parseDeck } from "../model/index.js";
+import { selectDeckLayouts } from "./select-layouts.js";
+export const DECK_OUTLINE_IDS = [
+    'pitch',
+    'qbr',
+    'launch',
+    'status',
+    'training',
+    'lesson',
+    'report',
+    'talk',
+];
+const core = (key, role, pacing, title, purpose, optional = false) => ({ key, role, pacing, title, purpose, ...(optional ? { optional: true } : {}) });
+const title = core('title', 'title', 'punch', '', 'Introduce the topic and presenter.');
+const close = core('close', 'close', 'punch', 'Close and next steps', 'Summarize the ask and give a follow-up path.');
+/** Eight conservative, deterministic brief outlines. They contain prompts, never invented evidence. */
+export const DECK_OUTLINES = Object.freeze([
+    {
+        id: 'pitch',
+        label: 'Pitch',
+        cues: ['pitch', 'investor', 'fundraise'],
+        slides: [
+            title,
+            core('problem', 'problem', 'story', 'The problem', 'Describe who has the problem and when.'),
+            core('solution', 'solution', 'idea', 'The solution', 'Explain the proposed solution.'),
+            core('why-now', 'hook', 'idea', 'Why now', 'Name the verified change that makes this timely.', true),
+            core('product', 'demo', 'story', 'How it works', 'Walk through the user journey.', true),
+            core('traction', 'metrics', 'punch', 'Evidence of demand', 'Add sourced traction measures.'),
+            core('business-model', 'solution', 'idea', 'Business model', 'Explain who pays and why.', true),
+            core('competition', 'comparison', 'diagram', 'Alternatives', 'Compare approaches fairly.', true),
+            core('team', 'team', 'idea', 'The team', 'Introduce contributors and relevant experience.'),
+            core('roadmap', 'roadmap', 'diagram', 'Roadmap', 'List milestones and evidence needed.', true),
+            core('ask', 'ask', 'punch', 'The ask', 'State the request and what it enables.'),
+            close,
+        ],
+    },
+    {
+        id: 'qbr',
+        label: 'Quarterly business review',
+        cues: ['qbr', 'quarterly business review', 'quarterly review'],
+        slides: [
+            title,
+            core('agenda', 'agenda', 'idea', 'Agenda', 'List the review topics.'),
+            core('highlights', 'metrics', 'punch', 'Quarter highlights', 'Add sourced performance measures.'),
+            core('trend', 'chart', 'diagram', 'Trend', 'Chart a verified measure.', true),
+            core('wins', 'findings', 'idea', 'Wins', 'Explain what worked and why.'),
+            core('misses', 'risks', 'idea', 'Misses and lessons', 'Describe gaps and lessons.'),
+            core('customer', 'quote', 'story', 'Customer voice', 'Add an approved customer quote.', true),
+            core('risks', 'risks', 'idea', 'Risks', 'Name risks and mitigation.'),
+            core('next', 'roadmap', 'diagram', 'Next quarter', 'List next priorities.'),
+            core('asks', 'ask', 'punch', 'Decisions needed', 'State the decisions needed.', true),
+            close,
+        ],
+    },
+    {
+        id: 'launch',
+        label: 'Product launch',
+        cues: ['launch', 'release', 'go to market'],
+        slides: [
+            title,
+            core('audience', 'problem', 'idea', 'Who this is for', 'Define the intended audience.'),
+            core('need', 'problem', 'story', 'The need', 'Describe the verified user need.'),
+            core('promise', 'solution', 'punch', 'The promise', 'State the product promise.'),
+            core('experience', 'demo', 'story', 'The experience', 'Show the core user journey.'),
+            core('proof', 'metrics', 'punch', 'Proof', 'Add sourced validation.', true),
+            core('plan', 'roadmap', 'diagram', 'Launch plan', 'Sequence launch work.'),
+            core('risks', 'risks', 'idea', 'Risks', 'Identify launch risks.'),
+            core('next', 'ask', 'punch', 'Next steps', 'Name owners and next actions.'),
+            close,
+        ],
+    },
+    {
+        id: 'status',
+        label: 'Project status',
+        cues: ['status', 'project update', 'weekly update'],
+        slides: [
+            title,
+            core('summary', 'hook', 'punch', 'Status at a glance', 'State overall status and date.'),
+            core('progress', 'roadmap', 'diagram', 'Progress', 'Show completed and active work.'),
+            core('evidence', 'metrics', 'punch', 'Measures', 'Add current, sourced measures.', true),
+            core('risks', 'risks', 'idea', 'Risks and blockers', 'Explain the effect and response.'),
+            core('decisions', 'ask', 'punch', 'Decisions needed', 'List decisions and due dates.'),
+            core('next', 'roadmap', 'diagram', 'Next period', 'Name upcoming milestones.'),
+            close,
+        ],
+    },
+    {
+        id: 'training',
+        label: 'Training',
+        cues: ['training', 'workshop', 'enablement'],
+        slides: [
+            title,
+            core('objectives', 'agenda', 'idea', 'Learning objectives', 'List observable outcomes.'),
+            core('context', 'problem', 'story', 'Why this matters', 'Connect the topic to a task.'),
+            core('concept', 'solution', 'idea', 'Core concept', 'Explain one key idea.'),
+            core('demo', 'demo', 'story', 'Demonstration', 'Show the method in context.'),
+            core('practice', 'steps', 'diagram', 'Practice', 'Give a guided activity.'),
+            core('check', 'quiz', 'punch', 'Check understanding', 'Add a question and expected reasoning.'),
+            core('resources', 'findings', 'idea', 'Resources', 'Link trusted follow-up material.'),
+            close,
+        ],
+    },
+    {
+        id: 'lesson',
+        label: 'Lesson',
+        cues: ['lesson', 'teach', 'class'],
+        slides: [
+            title,
+            core('question', 'hook', 'punch', 'Opening question', 'Ask a question that frames the topic.'),
+            core('goals', 'agenda', 'idea', 'Goals', 'State what learners can do.'),
+            core('idea', 'solution', 'idea', 'Main idea', 'Explain the central concept.'),
+            core('example', 'demo', 'story', 'Worked example', 'Walk through a representative case.'),
+            core('practice', 'steps', 'diagram', 'Try it', 'Provide a practice sequence.'),
+            core('recap', 'findings', 'idea', 'Recap', 'Summarize the core points.'),
+            close,
+        ],
+    },
+    {
+        id: 'report',
+        label: 'Report',
+        cues: ['report', 'findings', 'research'],
+        slides: [
+            title,
+            core('question', 'hook', 'punch', 'Question', 'State the question this report answers.'),
+            core('method', 'steps', 'diagram', 'Method', 'Describe the method and limits.'),
+            core('findings', 'findings', 'idea', 'Findings', 'Present evidence with sources.'),
+            core('detail', 'chart', 'diagram', 'Evidence', 'Visualize verified data.', true),
+            core('implications', 'solution', 'idea', 'Implications', 'Explain what the evidence supports.'),
+            core('limitations', 'risks', 'idea', 'Limitations', 'State uncertainty and missing evidence.'),
+            core('recommendations', 'recommendations', 'diagram', 'Recommendations', 'Connect actions to findings.'),
+            close,
+        ],
+    },
+    {
+        id: 'talk',
+        label: 'Talk',
+        cues: ['talk', 'keynote', 'presentation'],
+        slides: [
+            title,
+            core('hook', 'hook', 'punch', 'A question to carry', 'Open with a question or observation.'),
+            core('story', 'demo', 'story', 'A concrete story', 'Tell one sourced or personal story.'),
+            core('idea', 'solution', 'idea', 'The idea', 'Explain the central insight.'),
+            core('evidence', 'metrics', 'punch', 'Evidence', 'Show supporting evidence.', true),
+            core('practice', 'steps', 'diagram', 'What to try', 'Offer a practical next step.'),
+            core('recap', 'findings', 'idea', 'Takeaways', 'Repeat the memorable points.'),
+            close,
+        ],
+    },
+]);
+/** Build an honest, reproducible draft from a brief; missing evidence stays explicit. */
+export function generateDeckFromBrief(options) {
+    const brief = options.brief.slice(0, 5_000).trim();
+    const outline = options.outline ?? detectOutline(brief);
+    const template = DECK_OUTLINES.find((item) => item.id === outline);
+    if (!template)
+        throw new TypeError(`Unknown deck outline "${outline}".`);
+    const slides = template.slides.filter((item) => !item.optional);
+    const requests = slides.map((item) => ({
+        id: `slide-${item.key}`,
+        role: item.role,
+        pacing: item.pacing,
+        purpose: item.purpose,
+    }));
+    const selection = selectDeckLayouts(requests);
+    const deckSlides = slides.map((item, index) => {
+        const chosen = selection[index];
+        if (!chosen)
+            throw new TypeError(`No layout was selected for slide ${item.key}.`);
+        const note = `Draft guidance: ${item.purpose} Add only verified details from the brief or cited sources.`;
+        if (chosen.layout === 'free')
+            return {
+                id: chosen.id,
+                title: item.title || options.title || template.label,
+                notes: note,
+                layout: 'free',
+                blocks: [{ type: 'text', markdown: `Draft: ${item.purpose}` }],
+            };
+        const props = draftProps(structuredClone(DECK_LAYOUTS[chosen.layout].sample));
+        if ('title' in props)
+            props.title = item.title || `Draft: ${item.purpose}`;
+        if ('label' in props)
+            props.label = item.title || `Draft: ${item.purpose}`;
+        return {
+            id: chosen.id,
+            title: item.title || options.title || template.label,
+            notes: note,
+            layout: chosen.layout,
+            props,
+        };
+    });
+    const parsed = parseDeck({
+        formatVersion: 2,
+        meta: {
+            title: options.title?.trim() || titleFromBrief(brief) || template.label,
+            ...(options.locale ? { locale: options.locale } : {}),
+        },
+        slides: deckSlides,
+    });
+    if (!parsed.ok || !parsed.deck)
+        throw new TypeError(`Generated ${outline} outline failed validation: ${parsed.issues.map((issue) => issue.message).join('; ')}`);
+    return { deck: parsed.deck, outline, selection };
+}
+function detectOutline(brief) {
+    const normalized = brief
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, ' ')
+        .trim();
+    for (const item of DECK_OUTLINES)
+        if (item.cues.some((cue) => ` ${normalized} `.includes(` ${cue} `)))
+            return item.id;
+    return 'talk';
+}
+function titleFromBrief(brief) {
+    return (brief
+        .split(/[.!?\n]/u)[0]
+        ?.trim()
+        .slice(0, 80) || undefined);
+}
+const STRUCTURAL_KEYS = new Set([
+    'avatar',
+    'icon',
+    'lang',
+    'kind',
+    'type',
+    'id',
+    'height',
+    'overlay',
+    'gradient',
+    'pattern',
+    'token',
+    'muted',
+    'autoplay',
+    'loop',
+    'showTable',
+    'width',
+]);
+function draftProps(value, key = '') {
+    if (Array.isArray(value))
+        return value.map((item) => draftProps(item, key));
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([childKey, child]) => [childKey, draftProps(child, childKey)]));
+    }
+    if (typeof value === 'string') {
+        if (key === 'src')
+            return 'https://example.com/media/draft-placeholder.webp';
+        if (key === 'href')
+            return 'https://example.com/';
+        if (key === 'alt')
+            return 'Draft image placeholder.';
+        return STRUCTURAL_KEYS.has(key) ? value : 'Draft: add verified details.';
+    }
+    if (typeof value === 'number')
+        return STRUCTURAL_KEYS.has(key) ? value : 0;
+    return value;
+}