kritya 0.8.2-beta

package/dist/tools/deepResearch.js

@@ -0,0 +1,126 @@
+import { truncateResult } from "./common.js";
+import { tavilyRaw } from "./webSearch.js";
+import { fetchUrlText } from "./fetchUrl.js";
+const MAX_QUERIES = 5;
+const DEFAULT_PAGES_PER_QUERY = 2;
+const MAX_PAGES_PER_QUERY = 4;
+/** Keep each fetched page compact so a multi-source bundle still fits in context. */
+const PER_PAGE_CHARS = 6_000;
+/**
+ * Deep research: the caller (the model) breaks a big question into a handful of
+ * focused sub-queries; this tool runs a web search for each, then fetches the
+ * full text of the top result pages and returns one consolidated bundle. It is
+ * web_search + fetch_url in a loop — use it only for questions that genuinely
+ * need multiple sources, since it makes many external calls.
+ */
+async function runDeepResearch(queries, pagesPerQuery, recencyDays) {
+    const seenUrls = new Set();
+    const sections = [];
+    // When a recency window is requested, search the news topic so Tavily both
+    // filters to the last N days and returns publish dates the model can check.
+    const searchOpts = recencyDays ? { topic: "news", days: recencyDays } : {};
+    for (const query of queries) {
+        const block = [`## Sub-query: ${query}`];
+        let search;
+        try {
+            search = await tavilyRaw(query, 5, searchOpts);
+        }
+        catch (err) {
+            block.push(`(search failed: ${err instanceof Error ? err.message : String(err)})`);
+            sections.push(block.join("\n"));
+            continue;
+        }
+        if (search.answer)
+            block.push(`Search summary: ${search.answer}`);
+        const results = (search.results ?? []).filter((r) => r.url && !seenUrls.has(r.url));
+        if (results.length === 0)
+            block.push("(no new sources found)");
+        let fetched = 0;
+        for (const r of results) {
+            if (fetched >= pagesPerQuery)
+                break;
+            seenUrls.add(r.url);
+            const date = r.published_date ? `published ${r.published_date}` : "publish date unknown";
+            block.push(`\n### Source: ${r.title ?? "(untitled)"} (${date})\n${r.url}`);
+            try {
+                const page = await fetchUrlText(r.url, PER_PAGE_CHARS);
+                block.push(page);
+            }
+            catch (err) {
+                // A single unreachable page shouldn't sink the whole research run;
+                // fall back to the search snippet so the source still contributes.
+                block.push(`(could not fetch full page: ${err instanceof Error ? err.message : String(err)})`);
+                if (r.content)
+                    block.push(`Snippet: ${r.content}`);
+            }
+            fetched++;
+        }
+        sections.push(block.join("\n"));
+    }
+    const today = new Date().toISOString().slice(0, 10);
+    const window = recencyDays
+        ? `The user asked for information from the last ${recencyDays} day(s) (today is ${today}). ` +
+            `Each source is labeled with its publish date. Check those dates: exclude or explicitly ` +
+            `flag any source that falls outside this window or whose date is unknown — do NOT present ` +
+            `older material as current. `
+        : `Today is ${today}; do not assume a source is recent unless its content indicates so. `;
+    const preamble = `Deep research bundle: ${queries.length} sub-quer${queries.length === 1 ? "y" : "ies"}, ` +
+        `${seenUrls.size} source page(s). ${window}` +
+        `Synthesize an answer strictly from these sources and cite the URLs used. ` +
+        `Attribute rumors or secondary reports rather than stating them as established fact, ` +
+        `and note where sources disagree.\n`;
+    return truncateResult(preamble + "\n" + sections.join("\n\n---\n\n"));
+}
+export const deepResearchTool = {
+    name: "deep_research",
+    description: "Research a topic in depth across multiple web sources. You supply 1-5 focused sub-queries " +
+        "that break the question apart; the tool runs a web search for each and reads the full text " +
+        "of the top result pages, returning one consolidated, cited bundle to synthesize from. " +
+        "Reserve this for broad, multi-source questions (comparisons, surveys, 'how do people do X') " +
+        "— for a single known URL use fetch_url, and for a quick fact use web_search. " +
+        "For recent or time-sensitive topics ('latest', 'this week', news), set recency_days so " +
+        "sources are restricted to that window and labeled with publish dates.",
+    parameters: {
+        type: "object",
+        properties: {
+            queries: {
+                type: "array",
+                items: { type: "string" },
+                description: `1-${MAX_QUERIES} focused sub-queries covering different angles of the question`,
+            },
+            pages_per_query: {
+                type: "number",
+                description: `Full pages to read per sub-query, 1-${MAX_PAGES_PER_QUERY} (default ${DEFAULT_PAGES_PER_QUERY})`,
+            },
+            recency_days: {
+                type: "number",
+                description: "Restrict sources to the last N days and return publish dates. Set this whenever the " +
+                    "question is about recent/current events (e.g. 7 for 'past week'); omit for timeless topics.",
+            },
+        },
+        required: ["queries"],
+    },
+    requiresPermission: true,
+    external: true,
+    summarize: (args) => {
+        const qs = Array.isArray(args.queries) ? args.queries : [];
+        return `Deep research (${qs.length} quer${qs.length === 1 ? "y" : "ies"}): ${qs.join("; ").slice(0, 80)}`;
+    },
+    async execute(args) {
+        const raw = Array.isArray(args.queries) ? args.queries : [];
+        const queries = raw
+            .map((q) => String(q).trim())
+            .filter(Boolean)
+            .slice(0, MAX_QUERIES);
+        if (queries.length === 0) {
+            throw new Error("deep_research needs at least one non-empty query");
+        }
+        const pagesPerQuery = args.pages_per_query === undefined || args.pages_per_query === null
+            ? DEFAULT_PAGES_PER_QUERY
+            : Math.min(Math.max(Number(args.pages_per_query), 1), MAX_PAGES_PER_QUERY);
+        const recencyDays = args.recency_days === undefined || args.recency_days === null
+            ? undefined
+            : Math.max(1, Math.floor(Number(args.recency_days)));
+        return runDeepResearch(queries, pagesPerQuery, recencyDays);
+    },
+};

package/dist/tools/diff.js

@@ -0,0 +1,70 @@
+const MAX_SIDE_LINES = 30;
+/**
+ * Naive line diff: trims common leading/trailing lines, shows the changed
+ * middle as removals then additions. Good enough for a permission preview;
+ * not a real Myers diff.
+ */
+export function diffLines(oldText, newText) {
+    const oldLines = oldText === "" ? [] : oldText.split("\n");
+    const newLines = newText === "" ? [] : newText.split("\n");
+    let start = 0;
+    while (start < oldLines.length &&
+        start < newLines.length &&
+        oldLines[start] === newLines[start]) {
+        start++;
+    }
+    let endOld = oldLines.length;
+    let endNew = newLines.length;
+    while (endOld > start && endNew > start && oldLines[endOld - 1] === newLines[endNew - 1]) {
+        endOld--;
+        endNew--;
+    }
+    const out = [];
+    const context = oldLines.slice(Math.max(0, start - 2), start);
+    for (const line of context)
+        out.push(`  ${line}`);
+    const removed = oldLines.slice(start, endOld);
+    const added = newLines.slice(start, endNew);
+    // For a single-line change, mark the exact characters that differ with «».
+    if (removed.length === 1 && added.length === 1) {
+        const [oldMarked, newMarked] = markIntraLine(removed[0], added[0]);
+        out.push(`- ${oldMarked}`);
+        out.push(`+ ${newMarked}`);
+    }
+    else {
+        for (const line of cap(removed))
+            out.push(`- ${line}`);
+        for (const line of cap(added))
+            out.push(`+ ${line}`);
+    }
+    const trailing = oldLines.slice(endOld, Math.min(oldLines.length, endOld + 2));
+    for (const line of trailing)
+        out.push(`  ${line}`);
+    return out.join("\n");
+}
+/**
+ * Wrap the differing middle of two single lines in «» so the reader sees
+ * exactly which characters changed, not just that the whole line changed.
+ * Returns [oldMarked, newMarked]. If the lines share nothing, returns them
+ * unmarked.
+ */
+function markIntraLine(a, b) {
+    let pre = 0;
+    const maxPre = Math.min(a.length, b.length);
+    while (pre < maxPre && a[pre] === b[pre])
+        pre++;
+    let suf = 0;
+    while (suf < Math.min(a.length, b.length) - pre &&
+        a[a.length - 1 - suf] === b[b.length - 1 - suf]) {
+        suf++;
+    }
+    if (pre === 0 && suf === 0)
+        return [a, b];
+    const mark = (s) => `${s.slice(0, pre)}«${s.slice(pre, s.length - suf)}»${s.slice(s.length - suf)}`;
+    return [mark(a), mark(b)];
+}
+function cap(lines) {
+    if (lines.length <= MAX_SIDE_LINES)
+        return lines;
+    return [...lines.slice(0, MAX_SIDE_LINES), `… (${lines.length - MAX_SIDE_LINES} more lines)`];
+}

package/dist/tools/document/docx.js

@@ -0,0 +1,44 @@
+import mammoth from "mammoth";
+import { Document, HeadingLevel, Packer, Paragraph, TextRun } from "docx";
+import { validateBlocks } from "./types.js";
+export async function readDocx(buf) {
+    const result = await mammoth.extractRawText({ buffer: buf });
+    return result.value;
+}
+const HEADING_LEVELS = {
+    heading1: HeadingLevel.HEADING_1,
+    heading2: HeadingLevel.HEADING_2,
+    heading3: HeadingLevel.HEADING_3,
+};
+export async function writeDocx(input) {
+    const children = validateBlocks(input).map((block) => {
+        if (block.type in HEADING_LEVELS) {
+            return new Paragraph({
+                heading: HEADING_LEVELS[block.type],
+                children: [new TextRun(block.text)],
+            });
+        }
+        if (block.type === "bullet") {
+            return new Paragraph({ bullet: { level: 0 }, children: [new TextRun(block.text)] });
+        }
+        if (block.type === "numbered") {
+            return new Paragraph({
+                numbering: { reference: "doc-numbering", level: 0 },
+                children: [new TextRun(block.text)],
+            });
+        }
+        return new Paragraph({ children: [new TextRun(block.text)] });
+    });
+    const doc = new Document({
+        numbering: {
+            config: [
+                {
+                    reference: "doc-numbering",
+                    levels: [{ level: 0, format: "decimal", text: "%1.", alignment: "start" }],
+                },
+            ],
+        },
+        sections: [{ children }],
+    });
+    return Packer.toBuffer(doc);
+}

package/dist/tools/document/pdf.js

@@ -0,0 +1,190 @@
+import { fileURLToPath } from "node:url";
+import { getDocument } from "pdfjs-dist/legacy/build/pdf.mjs";
+import { PDFDocument, StandardFonts, degrees } from "pdf-lib";
+import { validateBlocks } from "./types.js";
+// Points pdfjs at its own bundled standard-font metrics so it doesn't warn
+// about missing font data when a PDF references one of the base 14 fonts.
+// pdfjs-dist requires this to be a string ending in "/" (it does a literal
+// `.endsWith("/")` check before reading via fs.readFile), but on Windows
+// fileURLToPath yields backslash-separated paths — normalize to forward
+// slashes, which fs.readFile accepts on every platform.
+const STANDARD_FONT_DATA_URL = fileURLToPath(new URL("../../../node_modules/pdfjs-dist/standard_fonts/", import.meta.url)).replace(/\\/g, "/");
+export async function readPdf(buf) {
+    const loadingTask = getDocument({
+        data: new Uint8Array(buf),
+        standardFontDataUrl: STANDARD_FONT_DATA_URL,
+    });
+    const doc = await loadingTask.promise;
+    const pageTexts = [];
+    for (let i = 1; i <= doc.numPages; i++) {
+        const page = await doc.getPage(i);
+        const content = await page.getTextContent();
+        const text = content.items
+            .map((item) => ("str" in item ? item.str : ""))
+            .join(" ");
+        pageTexts.push(text);
+    }
+    await loadingTask.destroy();
+    return pageTexts.join("\n\n");
+}
+const PAGE_WIDTH = 612; // US Letter, points
+const PAGE_HEIGHT = 792;
+const MARGIN = 54;
+const LINE_GAP = 4;
+const BLOCK_STYLE = {
+    heading1: { size: 22, bold: true, prefix: "" },
+    heading2: { size: 17, bold: true, prefix: "" },
+    heading3: { size: 14, bold: true, prefix: "" },
+    paragraph: { size: 11, bold: false, prefix: "" },
+    bullet: { size: 11, bold: false, prefix: "• " },
+    numbered: { size: 11, bold: false, prefix: "" },
+};
+// The base-14 fonts are WinAnsi-encoded, so pdf-lib throws on anything outside
+// it (emoji, CJK, Greek, box drawing). Fold the characters that have an obvious
+// ASCII equivalent and mark the rest, rather than failing the whole document.
+const CHAR_FOLDS = [
+    [/[‘’‚‛]/g, "'"],
+    [/[“”„‟]/g, '"'],
+    [/[‐‑‒–]/g, "-"],
+    [/[—―]/g, "—"],
+    [/[•‣◦●▪]/g, "•"],
+    [/…/g, "..."],
+    [/[→⇒]/g, "->"],
+    [/[←⇐]/g, "<-"],
+    [/[\u00A0\u2002\u2003\u2007\u2009\u202F]/g, " "], // non-breaking and typographic spaces
+    // Alternation, not a character class: ZWJ in a class trips no-misleading-character-class.
+    [/\u00AD|\u200B|\u200C|\u200D|\uFEFF/g, ""], // soft hyphen and zero-width marks
+    [/\t/g, "    "],
+];
+// WinAnsi: printable Latin-1 plus the named characters in the 0x80-0x9F block.
+const WINANSI_OK = /[\u0020-\u007E\u00A1-\u00FF\u20AC\u201A\u0192\u201E\u2026\u2020\u2021\u02C6\u2030\u0160\u2039\u0152\u017D\u2018\u2019\u201C\u201D\u2022\u2013\u2014\u02DC\u2122\u0161\u203A\u0153\u017E\u0178]/;
+/** Make one block of text safe for a WinAnsi-encoded standard font. */
+function toWinAnsi(text) {
+    let out = text.normalize("NFC");
+    for (const [pattern, replacement] of CHAR_FOLDS)
+        out = out.replace(pattern, replacement);
+    return [...out].map((ch) => (WINANSI_OK.test(ch) ? ch : "?")).join("");
+}
+export async function writePdf(input) {
+    const blocks = validateBlocks(input);
+    const doc = await PDFDocument.create();
+    const regular = await doc.embedFont(StandardFonts.Helvetica);
+    const bold = await doc.embedFont(StandardFonts.HelveticaBold);
+    let page = doc.addPage([PAGE_WIDTH, PAGE_HEIGHT]);
+    let y = PAGE_HEIGHT - MARGIN;
+    const maxWidth = PAGE_WIDTH - MARGIN * 2;
+    let numberedIndex = 0;
+    for (const block of blocks) {
+        const style = BLOCK_STYLE[block.type];
+        const font = style.bold ? bold : regular;
+        numberedIndex = block.type === "numbered" ? numberedIndex + 1 : 0;
+        const prefix = block.type === "numbered" ? `${numberedIndex}. ` : style.prefix;
+        const lines = wrapText(toWinAnsi(prefix + block.text), font, style.size, maxWidth);
+        for (const line of lines) {
+            if (y - style.size < MARGIN) {
+                page = doc.addPage([PAGE_WIDTH, PAGE_HEIGHT]);
+                y = PAGE_HEIGHT - MARGIN;
+            }
+            page.drawText(line, { x: MARGIN, y: y - style.size, size: style.size, font });
+            y -= style.size + LINE_GAP;
+        }
+        y -= LINE_GAP; // extra space between blocks
+    }
+    // pdf-lib defaults to compressed object streams (PDF 1.5+), which the
+    // bundled pdfjs in pdf-parse (an old release) fails to parse. Plain
+    // xref tables keep round-trip reading working.
+    const bytes = await doc.save({ useObjectStreams: false });
+    return Buffer.from(bytes);
+}
+/** Ensure every entry of `pages` (1-based) is a real page in a `count`-page doc. */
+function assertPagesInRange(pages, count) {
+    for (const p of pages) {
+        if (!Number.isInteger(p) || p < 1 || p > count) {
+            throw new Error(`Page ${p} is out of range (document has ${count} page(s))`);
+        }
+    }
+}
+/**
+ * Apply one structural page operation to an existing PDF, preserving its
+ * content. PDF text is positioned glyphs with no reflow, so there is no
+ * reliable text find/replace — these operations act on whole pages instead.
+ * Returns the resulting file bytes and a short human-readable summary.
+ */
+export async function editPdf(buf, edit) {
+    const doc = await PDFDocument.load(new Uint8Array(buf));
+    const count = doc.getPageCount();
+    let summary;
+    let result = doc;
+    switch (edit.op) {
+        case "delete_pages": {
+            assertPagesInRange(edit.pages, count);
+            // Remove from the end so earlier indexes stay valid as we go.
+            const toRemove = [...new Set(edit.pages)].sort((a, b) => b - a);
+            if (toRemove.length >= count) {
+                throw new Error("Cannot delete every page — a PDF must keep at least one page");
+            }
+            for (const p of toRemove)
+                doc.removePage(p - 1);
+            summary = `${count} page(s) → ${count - toRemove.length} page(s)`;
+            break;
+        }
+        case "rotate_page": {
+            assertPagesInRange([edit.page], count);
+            if (edit.degrees % 90 !== 0) {
+                throw new Error(`Rotation must be a multiple of 90°, got ${edit.degrees}`);
+            }
+            const page = doc.getPage(edit.page - 1);
+            const next = (((page.getRotation().angle + edit.degrees) % 360) + 360) % 360;
+            page.setRotation(degrees(next));
+            summary = `Rotated page ${edit.page} to ${next}°`;
+            break;
+        }
+        case "reorder_pages": {
+            assertPagesInRange(edit.order, count);
+            const unique = new Set(edit.order);
+            if (edit.order.length !== count || unique.size !== count) {
+                throw new Error(`reorder_pages requires each page 1..${count} exactly once, got [${edit.order.join(", ")}]`);
+            }
+            result = await PDFDocument.create();
+            const copied = await result.copyPages(doc, edit.order.map((p) => p - 1));
+            for (const page of copied)
+                result.addPage(page);
+            summary = `Reordered ${count} pages`;
+            break;
+        }
+        case "extract_pages": {
+            assertPagesInRange(edit.pages, count);
+            if (edit.pages.length === 0)
+                throw new Error("extract_pages requires at least one page");
+            result = await PDFDocument.create();
+            const copied = await result.copyPages(doc, edit.pages.map((p) => p - 1));
+            for (const page of copied)
+                result.addPage(page);
+            summary = `Extracted ${edit.pages.length} page(s)`;
+            break;
+        }
+        default:
+            throw new Error(`Unknown PDF op "${edit.op}"`);
+    }
+    // Match writePdf: plain xref tables keep the bundled reader able to re-read the file.
+    const bytes = await result.save({ useObjectStreams: false });
+    return { buf: Buffer.from(bytes), summary };
+}
+function wrapText(text, font, size, maxWidth) {
+    const words = text.split(/\s+/).filter(Boolean);
+    const lines = [];
+    let current = "";
+    for (const word of words) {
+        const candidate = current ? `${current} ${word}` : word;
+        if (font.widthOfTextAtSize(candidate, size) > maxWidth && current) {
+            lines.push(current);
+            current = word;
+        }
+        else {
+            current = candidate;
+        }
+    }
+    if (current)
+        lines.push(current);
+    return lines.length ? lines : [""];
+}

package/dist/tools/document/pptx.js

@@ -0,0 +1,148 @@
+import { createRequire } from "node:module";
+import JSZip from "jszip";
+// pptxgenjs is CommonJS-only and its bundled types don't resolve cleanly
+// under NodeNext + esModuleInterop (the default import type-checks as the
+// module namespace, not the constructor). Load it via require and type the
+// handful of methods this module actually calls.
+const require = createRequire(import.meta.url);
+const PptxGenJS = require("pptxgenjs");
+// Matches text runs inside slide XML, e.g. <a:t>Hello</a:t>.
+const TEXT_RUN_RE = /<a:t>([^<]*)<\/a:t>/g;
+export async function readPptx(buf) {
+    const zip = await JSZip.loadAsync(buf);
+    const slideFiles = Object.keys(zip.files)
+        .filter((name) => /^ppt\/slides\/slide\d+\.xml$/.test(name))
+        .sort((a, b) => slideNumber(a) - slideNumber(b));
+    const parts = [];
+    for (const name of slideFiles) {
+        const xml = await zip.files[name].async("text");
+        const texts = [...xml.matchAll(TEXT_RUN_RE)].map((m) => decodeXmlEntities(m[1]));
+        parts.push(`## Slide ${slideNumber(name)}`);
+        parts.push(texts.join("\n"));
+        parts.push("");
+    }
+    return parts.join("\n");
+}
+function slideNumber(name) {
+    return Number(name.match(/slide(\d+)\.xml$/)?.[1] ?? 0);
+}
+function decodeXmlEntities(s) {
+    return s
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, "&");
+}
+// Inches, matching pptxgenjs's default 16:9 layout (10 x 5.625).
+const SLIDE_WIDTH = 10;
+const SLIDE_HEIGHT = 5.625;
+const MARGIN_X = 0.5;
+const MARGIN_TOP = 0.4;
+const MARGIN_BOTTOM = 0.4;
+const TITLE_HEIGHT = 0.9;
+const BODY_WIDTH = SLIDE_WIDTH - MARGIN_X * 2;
+/**
+ * Field names models reach for when they mean `bullets`. Anything not listed
+ * here used to be dropped without a word, which is how a deck ends up with a
+ * title on every slide and nothing else.
+ */
+const BULLET_ALIASES = ["bullets", "content", "points", "body", "items", "lines", "text"];
+const TITLE_ALIASES = ["title", "heading", "header", "name"];
+/** Coerce one model-supplied bullet into display text, or null if there's nothing to show. */
+function toBulletText(value) {
+    if (value == null)
+        return null;
+    if (typeof value === "string")
+        return value.trim() || null;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (typeof value === "object") {
+        // Bullets sometimes arrive as {text: "..."} / {label: "..."} run objects.
+        for (const key of ["text", "label", "title", "value"]) {
+            const inner = value[key];
+            if (typeof inner === "string" && inner.trim())
+                return inner.trim();
+        }
+    }
+    return null;
+}
+/** Pull a slide's title and bullets out of whatever shape the model sent. */
+function normalizeSlide(slide, index) {
+    const raw = (slide ?? {});
+    if (typeof raw !== "object") {
+        throw new Error(`write_document: slide ${index + 1} is not an object`);
+    }
+    let title;
+    for (const key of TITLE_ALIASES) {
+        const v = raw[key];
+        if (typeof v === "string" && v.trim()) {
+            title = v.trim();
+            break;
+        }
+    }
+    const bullets = [];
+    for (const key of BULLET_ALIASES) {
+        if (!(key in raw))
+            continue;
+        const v = raw[key];
+        // `title` may also be the source of `text`; don't repeat it as a bullet.
+        const entries = Array.isArray(v) ? v.flat() : [v];
+        for (const entry of entries) {
+            const text = toBulletText(entry);
+            if (text && text !== title)
+                bullets.push(text);
+        }
+        if (bullets.length)
+            break;
+    }
+    if (!title && bullets.length === 0) {
+        const keys = Object.keys(raw);
+        throw new Error(`write_document: slide ${index + 1} has no title or bullets` +
+            (keys.length ? ` (got keys: ${keys.join(", ")})` : "") +
+            `. Each slide needs "title" and/or "bullets" (an array of strings).`);
+    }
+    return { title, bullets };
+}
+export async function writePptx(slides) {
+    const pptx = new PptxGenJS();
+    for (const [index, slide] of slides.entries()) {
+        const { title, bullets } = normalizeSlide(slide, index);
+        const s = pptx.addSlide();
+        let y = MARGIN_TOP;
+        if (title) {
+            // An explicit height matters: with none, pptxgenjs emits cy="0" and
+            // renderers other than PowerPoint clip the title away entirely.
+            s.addText(title, {
+                x: MARGIN_X,
+                y,
+                w: BODY_WIDTH,
+                h: TITLE_HEIGHT,
+                valign: "top",
+                fontSize: 28,
+                bold: true,
+                shrinkText: true,
+            });
+            y += TITLE_HEIGHT + 0.1;
+        }
+        if (bullets.length) {
+            // Claim the rest of the slide rather than a fixed 60% of its height, and
+            // let PowerPoint shrink the text so a long list stays on the slide.
+            s.addText(bullets.map((text) => ({ text, options: { bullet: true, breakLine: true } })), {
+                x: MARGIN_X,
+                y,
+                w: BODY_WIDTH,
+                h: SLIDE_HEIGHT - y - MARGIN_BOTTOM,
+                valign: "top",
+                fontSize: 18,
+                shrinkText: true,
+            });
+        }
+        const notes = slide?.notes;
+        if (typeof notes === "string" && notes.trim()) {
+            s.addNotes(notes);
+        }
+    }
+    const data = await pptx.write({ outputType: "nodebuffer" });
+    return data;
+}

package/dist/tools/document/types.js

@@ -0,0 +1,26 @@
+export const BLOCK_TYPES = [
+    "heading1",
+    "heading2",
+    "heading3",
+    "paragraph",
+    "bullet",
+    "numbered",
+];
+/**
+ * Check every block before any writer indexes a style table with `block.type`.
+ * Models do stray outside the schema enum, and without this the docx writer
+ * silently demotes the block to a plain paragraph while the pdf writer dies
+ * with an unrelated "cannot read properties of undefined".
+ */
+export function validateBlocks(blocks) {
+    return blocks.map((block, i) => {
+        if (!block || typeof block !== "object") {
+            throw new Error(`write_document: block ${i + 1} is not an object`);
+        }
+        if (!BLOCK_TYPES.includes(block.type)) {
+            throw new Error(`write_document: block ${i + 1} has unknown type "${block.type}". ` +
+                `Valid types: ${BLOCK_TYPES.join(", ")}`);
+        }
+        return { type: block.type, text: block.text == null ? "" : String(block.text) };
+    });
+}