@evandu/super-pi 0.1.129 → 0.1.131

package/dist/server/knowledge.d.ts

@@ -82,6 +82,8 @@ export type KnowledgeRuntime = {
 export declare function parseRanking(output: string): number[] | null;
 /** Duplicated as a literal in `agents/super-pi-knowledge/index.ts`, the way `TASK_TOOL_NAME` is. */
 export declare const KNOWLEDGE_TOOL_NAME = "knowledge_search";
+/** The import half of the same extension. Duplicated as a literal there, for the same reason. */
+export declare const KNOWLEDGE_IMPORT_TOOL_NAME = "knowledge_import";
 /**
  * Index terms for one string: CJK bigrams plus Latin words.
  *
@@ -152,17 +154,6 @@ export declare class KnowledgeBase {
     private load;
     private invalidate;
     list(workspaceId: string): Promise<Array<Omit<KnowledgeDocument, "text">>>;
-    /**
-     * Whether this workspace has any document at all, which is what decides whether the turn mounts the
-     * extension.
-     *
-     * WHY A DIRECTORY LISTING AND NOT `list()`. This runs once per turn, before every spawn. `list()`
-     * would read and parse every document's full text to answer a yes/no question, so a workspace with
-     * a dozen real documents would pay for parsing all of them on every message - including the
-     * catalogue fetch the extension makes the moment it loads. `readdir` answers the same question for
-     * the price of one directory entry, and a name is all this needs.
-     */
-    hasDocuments(workspaceId: string): Promise<boolean>;
     /**
      * Adds a document, either from a workspace file or from pasted text.
      *
@@ -171,6 +162,10 @@ export declare class KnowledgeBase {
      * newer version that diverges from the one the workspace serves. The path therefore goes through
      * the same `resolveInsideRoot` guard the file editor uses, so symlink and `..` escapes are refused
      * by construction instead of by a check someone has to remember.
+     *
+     * WHO CALLS THIS. The settings window (manage, action "add") AND, since the import tool exists,
+     * the primary agent mid-turn on the user's say-so - through the same guard, the same whitelist and
+     * the same caps, so an agent import can never do more than a person's import could.
      */
     add(workspaceId: string, body: {
         path?: string;
@@ -213,27 +208,42 @@ export declare class KnowledgeBase {
      */
     private rerank;
     /**
-     * Mints a read-only token for one turn. The agent can retrieve, never write: everything a person
-     * puts in a knowledge base is theirs to curate from the settings window.
+     * Mints a token for one turn. The agent can retrieve and IMPORT (a document the user just asked it
+     * to add rides through the same `add` guard the settings window uses), but never remove: curation
+     * that deletes a person's documents stays a settings-window act.
      */
     issue(conversationId: string): string;
     release(token: string): void;
     private identity;
-    /** The agent-facing endpoint: a title catalogue and a search. Nothing that writes. */
+    /**
+     * The agent-facing endpoint: a title catalogue, a search, and an import. The import is the SAME
+     * `add` the settings window calls - path guard, format whitelist, size caps, dedupe - so an agent
+     * cannot do anything a person could not, and the one thing it cannot do is `remove`.
+     */
     tool(token: string, body: {
         kind?: string;
         query?: string;
         limit?: number;
+        path?: string;
+        title?: string;
+        text?: string;
     }, signal?: AbortSignal): Promise<{
         documents: {
             title: string;
             source: string;
             characters: number;
         }[];
+        imported?: undefined;
+        hits?: undefined;
+        reranked?: undefined;
+    } | {
+        documents?: undefined;
+        imported: Omit<KnowledgeDocument, "text">;
         hits?: undefined;
         reranked?: undefined;
     } | {
         documents?: undefined;
+        imported?: undefined;
         hits: KnowledgeHit[];
         reranked: boolean;
     }>;

package/dist/server/knowledge.js

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
 import { looksBinary, resolveInsideRoot } from "./files.js";
+import { documentFormatOf, DocumentError, extractText } from "./documents.js";
 /** 1 MB. Big enough for a design doc or a spec, small enough that chunking stays instant. */
 export const MAX_DOCUMENT_BYTES = 1024 * 1024;
 /** A pasted document rides inside a JSON body, so the request cap leaves room for escaping overhead. */
@@ -53,6 +54,8 @@ const HEADING = /^#{1,6}\s+(.*\S)\s*$/;
 const PASTED_SOURCE = "pasted";
 /** Duplicated as a literal in `agents/super-pi-knowledge/index.ts`, the way `TASK_TOOL_NAME` is. */
 export const KNOWLEDGE_TOOL_NAME = "knowledge_search";
+/** The import half of the same extension. Duplicated as a literal there, for the same reason. */
+export const KNOWLEDGE_IMPORT_TOOL_NAME = "knowledge_import";
 /** Extensions a document may be imported from. Mirrors `files.TEXT_EXTENSIONS`, minus the source languages. */
 const IMPORTABLE = new Set([
     ".md", ".markdown", ".mdx", ".txt", ".text", ".log", ".rst", ".org",
@@ -369,30 +372,6 @@ export class KnowledgeBase {
         const documents = (await this.readAll(workspaceId)).map(document => this.summarise(document));
         return documents.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
     }
-    /**
-     * Whether this workspace has any document at all, which is what decides whether the turn mounts the
-     * extension.
-     *
-     * WHY A DIRECTORY LISTING AND NOT `list()`. This runs once per turn, before every spawn. `list()`
-     * would read and parse every document's full text to answer a yes/no question, so a workspace with
-     * a dozen real documents would pay for parsing all of them on every message - including the
-     * catalogue fetch the extension makes the moment it loads. `readdir` answers the same question for
-     * the price of one directory entry, and a name is all this needs.
-     */
-    async hasDocuments(workspaceId) {
-        if (!this.enabled())
-            return false;
-        if (!this.store.snapshot().workspaces.some(workspace => workspace.id === workspaceId))
-            return false;
-        try {
-            return (await readdir(this.folder(workspaceId))).some(name => name.endsWith(".json"));
-        }
-        catch (error) {
-            if (error.code === "ENOENT")
-                return false;
-            throw error;
-        }
-    }
     /**
      * Adds a document, either from a workspace file or from pasted text.
      *
@@ -401,6 +380,10 @@ export class KnowledgeBase {
      * newer version that diverges from the one the workspace serves. The path therefore goes through
      * the same `resolveInsideRoot` guard the file editor uses, so symlink and `..` escapes are refused
      * by construction instead of by a check someone has to remember.
+     *
+     * WHO CALLS THIS. The settings window (manage, action "add") AND, since the import tool exists,
+     * the primary agent mid-turn on the user's say-so - through the same guard, the same whitelist and
+     * the same caps, so an agent import can never do more than a person's import could.
      */
     async add(workspaceId, body) {
         this.requireWorkspace(workspaceId);
@@ -417,17 +400,42 @@ export class KnowledgeBase {
             if (!info.isFile())
                 throw new Error("只能导入文件");
             format = extname(absolute).toLocaleLowerCase();
-            if (!IMPORTABLE.has(format))
+            const documentFormat = documentFormatOf(format);
+            if (!IMPORTABLE.has(format) && !documentFormat) {
                 throw new Error(`不支持的文件类型 ${format || "(无扩展名)"}；请先转换为 Markdown 或纯文本`);
+            }
             if (info.size > MAX_DOCUMENT_BYTES)
                 throw new Error(`文件过大：${info.size} 字节超过 ${MAX_DOCUMENT_BYTES} 的上限`);
-            const buffer = await readFile(absolute);
-            if (looksBinary(buffer.subarray(0, 4096)))
-                throw new Error("看起来是二进制文件，无法索引");
-            text = buffer.toString("utf8");
             source = body.path.trim();
             if (!title)
                 title = basename(absolute);
+            if (documentFormat) {
+                // A DOCUMENT IS PARSED, NOT DECODED. The bytes on disk are a container - a PDF's or a
+                // docx's - and what goes into the knowledge base is the TEXT they contain. The format
+                // recorded on the document stays the SOURCE format (`.pdf`), because that is what the next
+                // re-import of this path has to parse it as: the extracted text is not a PDF, and treating
+                // it as one would make an update fail to parse at all.
+                //
+                // A DOCUMENT THAT COULD NOT BE READ IS A REFUSAL, NOT AN EMPTY DOCUMENT. The parser's own
+                // reasons are already written for a person - a scan with no text layer, an encrypted file,
+                // a missing package - and they are passed through unchanged, because a person who is told
+                // "读取失败" learns nothing about what to do next.
+                try {
+                    const extracted = await extractText(absolute, documentFormat);
+                    text = extracted.text;
+                }
+                catch (error) {
+                    if (error instanceof DocumentError)
+                        throw new Error(error.message);
+                    throw error;
+                }
+            }
+            else {
+                const buffer = await readFile(absolute);
+                if (looksBinary(buffer.subarray(0, 4096)))
+                    throw new Error("看起来是二进制文件，无法索引");
+                text = buffer.toString("utf8");
+            }
         }
         const trimmed = text.trim();
         if (!trimmed)
@@ -677,8 +685,9 @@ export class KnowledgeBase {
         }
     }
     /**
-     * Mints a read-only token for one turn. The agent can retrieve, never write: everything a person
-     * puts in a knowledge base is theirs to curate from the settings window.
+     * Mints a token for one turn. The agent can retrieve and IMPORT (a document the user just asked it
+     * to add rides through the same `add` guard the settings window uses), but never remove: curation
+     * that deletes a person's documents stays a settings-window act.
      */
     issue(conversationId) {
         const conversation = this.store.snapshot().conversations.find(item => item.id === conversationId);
@@ -697,13 +706,19 @@ export class KnowledgeBase {
             throw new Error("知识库授权已失效");
         return identity;
     }
-    /** The agent-facing endpoint: a title catalogue and a search. Nothing that writes. */
+    /**
+     * The agent-facing endpoint: a title catalogue, a search, and an import. The import is the SAME
+     * `add` the settings window calls - path guard, format whitelist, size caps, dedupe - so an agent
+     * cannot do anything a person could not, and the one thing it cannot do is `remove`.
+     */
     async tool(token, body, signal) {
         const identity = this.identity(token);
         if (!this.enabled())
             throw new Error("知识库已关闭");
         if (body.kind === "catalogue")
             return { documents: (await this.list(identity.workspaceId)).map(document => ({ title: document.title, source: document.source, characters: document.characters })) };
+        if (body.kind === "import")
+            return { imported: await this.add(identity.workspaceId, { path: body.path, title: body.title, text: body.text }) };
         if (body.kind !== "search")
             throw new Error("未知知识库操作");
         // The reranker needs the conversation it is ranking FOR: that is whose model answers, whose

package/dist/server/pi-session-pool.js

@@ -22,7 +22,7 @@
  */
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { createPiSession, sameFingerprint, superPiExtensionPaths, } from "./pi-session.js";
+import { createPiSession, sameFingerprint, superPiExtensionPaths, superPiSkillPaths, } from "./pi-session.js";
 /** How long an idle session survives before it is evicted. */
 const IDLE_EVICTION_MS = 10 * 60_000;
 /**
@@ -170,6 +170,7 @@ export class PiSessionPool {
             sessionId: request.conversationId,
             sessionDir: this.sessionDir,
             extensionPaths: superPiExtensionPaths(this.repositoryRoot),
+            skillPaths: superPiSkillPaths(this.repositoryRoot),
             extensionEnv: request.extensionEnv,
             ...(request.systemPromptFile ? { systemPromptFile: request.systemPromptFile } : {}),
             ...(request.systemPromptMode ? { systemPromptMode: request.systemPromptMode } : {}),

package/dist/server/pi-session.d.ts

@@ -184,6 +184,13 @@ export interface ExtensionEnvironment {
  * concurrent session's environment would otherwise land in the middle of this one.
  */
 export declare function withEnvironment<T>(values: Record<string, string>, work: () => Promise<T>): Promise<T>;
+/**
+ * `withEnvironment` for one session's extension load, serialized across all session creations.
+ *
+ * The extension factories run inside `work` and capture the values into their closures; after the
+ * window closes they never read `process.env` again, so only the WINDOW needs to be exclusive.
+ */
+export declare function withIsolatedSessionEnv<T>(values: Record<string, string>, work: () => Promise<T>): Promise<T>;
 /**
  * The live session for one conversation.
  *
@@ -336,6 +343,8 @@ export interface SessionCreation {
     sessionDir: string;
     /** Super Pi's extensions to mount, as absolute paths. */
     extensionPaths: string[];
+    /** Super Pi's built-in skills to expose beside the user's and workspace's skills. */
+    skillPaths?: string[];
     /** The environment those extensions read when they are loaded. */
     extensionEnv: Record<string, string>;
     /** The agent's system prompt file, or undefined for Pi's own defaults. */
@@ -363,14 +372,17 @@ export interface SessionCreation {
  *
  * The order of operations here IS the isolation mechanism, and each step is load-bearing:
  *
- * 1. The environment is applied, so the extension factories that run during the reload read this
- *    session's values rather than another session's.
- * 2. The loader is created and reloaded, which is when Pi calls the extension factories. The factories
- *    CAPTURE the values; they do not read them later.
+ * 1. The loader is created with Super Pi's extension paths, for PI to load - through its jiti
+ *    transpiler and virtual modules, the same machinery the spawned CLI used. Nothing here imports a
+ *    Super Pi extension file directly; see the comment at the loader below for why that must never
+ *    come back.
+ * 2. The reload runs inside this session's env window (`withIsolatedSessionEnv`), which is when Pi
+ *    calls the extension factories. The factories CAPTURE the values; they do not read them later.
  * 3. The session is created with that loader.
  *
- * Step 2 happening outside step 1 would give every session the same configuration, and step 1 happening
- * after step 2 would give every session no configuration at all. The window is the whole of the reload.
+ * Step 2 happening outside its env window would give every session the same configuration, and the
+ * window would give every session no configuration at all if two creations could interleave - which
+ * the serialization in `withIsolatedSessionEnv` prevents.
  *
  * THE FACTORY IS INJECTABLE. A test needs to drive a session without a real Pi behind it - to check what
  * a session was BUILT with (its working directory, its allowlist) rather than what it eventually
@@ -410,3 +422,5 @@ export interface PromptTemplateSummary {
 }
 export declare function loadPromptTemplateSummaries(cwd: string): Promise<PromptTemplateSummary[]>;
 export declare function superPiExtensionPaths(repositoryRoot: string): string[];
+/** Skills shipped by Super Pi itself. Paths are explicit so installed and development layouts agree. */
+export declare function superPiSkillPaths(repositoryRoot: string): string[];

package/dist/server/pi-session.js

@@ -225,20 +225,39 @@ export async function withEnvironment(values, work) {
         }
     }
 }
+/**
+ * The env window of the session currently being built, so the next one queues behind it.
+ *
+ * `withEnvironment` alone is not safe here: its window is process-global, and two sessions created
+ * concurrently would interleave - A applies its capability, B applies its own, and A's extension
+ * factory captures B's credential. Chaining the windows means a concurrent creation waits for the
+ * other's `reload()` - milliseconds - instead of silently wearing its capability.
+ */
+let extensionEnvWindow = Promise.resolve();
+/**
+ * `withEnvironment` for one session's extension load, serialized across all session creations.
+ *
+ * The extension factories run inside `work` and capture the values into their closures; after the
+ * window closes they never read `process.env` again, so only the WINDOW needs to be exclusive.
+ */
+export function withIsolatedSessionEnv(values, work) {
+    const run = extensionEnvWindow.then(() => withEnvironment(values, work));
+    extensionEnvWindow = run.then(() => undefined, () => undefined);
+    return run;
+}
 export async function createPiSession(creation) {
     const startedAt = performance.now();
     traceSession(creation.sessionId, "sdk.load.begin", startedAt);
     const sdk = await loadSdk();
     traceSession(creation.sessionId, "sdk.load.end", startedAt);
     const agentDir = creation.agentDir ?? defaultAgentDir();
-    // Extension credentials are per-session capabilities. Do not temporarily mutate process.env here:
-    // two concurrent session creations otherwise race and can capture each other's capability.
-    const inlinePaths = creation.extensionPaths.filter((path) => /super-pi-(task|memory|knowledge)/.test(path.replaceAll("\\", "/")));
-    const externalPaths = creation.extensionPaths.filter((path) => !inlinePaths.includes(path));
-    const extensionFactories = await Promise.all(inlinePaths.map(async (path) => {
-        const mod = await import(pathToFileURL(path).href);
-        return async (pi) => mod.default?.(pi, creation.extensionEnv);
-    }));
+    // THE EXTENSIONS ARE PI'S TO LOAD. Every path goes to Pi's own resource loader, which imports them
+    // through its jiti transpiler with its virtual modules - and both of those are load-bearing:
+    // `@sinclair/typebox` is a Pi virtual module that NO node_modules anywhere can resolve, and Node's
+    // type stripping refuses .ts under any `node_modules` segment (which is where a published package
+    // lives). A native `import()` here survived neither - it broke every installed layout the moment it
+    // shipped, invisibly, because nothing in `npm run check` runs from an installed layout.
+    // `scripts/installed-layout.test.mjs` exists to keep that class of breakage visible.
     return (async () => {
         // THE AGENT'S PROMPT. Pi's loader takes the same two shapes the command line took: a `systemPrompt`
         // that REPLACES Pi's own, and an `appendSystemPrompt` list of files that are ADDED to it. An agent
@@ -249,15 +268,18 @@ export async function createPiSession(creation) {
         const loader = new sdk.DefaultResourceLoader({
             cwd: creation.cwd,
             agentDir,
-            ...(externalPaths.length ? { additionalExtensionPaths: externalPaths } : {}),
-            ...(extensionFactories.length ? { extensionFactories } : {}),
+            ...(creation.extensionPaths.length ? { additionalExtensionPaths: creation.extensionPaths } : {}),
+            ...(creation.skillPaths?.length ? { additionalSkillPaths: creation.skillPaths } : {}),
             ...(creation.systemPromptFile && creation.systemPromptMode === "replace"
                 ? { systemPrompt: creation.systemPromptFile }
                 : creation.systemPromptFile
                     ? { appendSystemPrompt: [creation.systemPromptFile] }
                     : {}),
         });
-        await loader.reload();
+        // The extension factories run inside `reload()` and capture this session's env values into their
+        // closures; the window is serialized (`withIsolatedSessionEnv`) so a concurrent creation cannot
+        // land its own capability in the middle.
+        await withIsolatedSessionEnv(creation.extensionEnv, () => loader.reload());
         traceSession(creation.sessionId, "sdk.loader.reload", startedAt, `extensions=${creation.extensionPaths.length}`);
         const sessionManager = creation.persist === false
             ? sdk.SessionManager.inMemory(creation.cwd, { id: creation.sessionId })
@@ -392,6 +414,16 @@ export function superPiExtensionPaths(repositoryRoot) {
         join(repositoryRoot, "agents", "super-pi-task", "index.ts"),
         join(repositoryRoot, "agents", "super-pi-memory", "index.ts"),
         join(repositoryRoot, "agents", "super-pi-knowledge", "index.ts"),
+        join(repositoryRoot, "agents", "super-pi-web", "index.ts"),
+        // The document tools. They are mounted for every session, and the extension itself decides
+        // whether to register anything: with no endpoint in its environment it returns without
+        // registering a tool, so a runtime without a document endpoint mounts nothing harmful.
+        join(repositoryRoot, "agents", "super-pi-documents", "index.ts"),
     ];
     return paths.filter((path) => existsSync(path));
 }
+/** Skills shipped by Super Pi itself. Paths are explicit so installed and development layouts agree. */
+export function superPiSkillPaths(repositoryRoot) {
+    const paths = [join(repositoryRoot, "skills", "presentation")];
+    return paths.filter((path) => existsSync(join(path, "SKILL.md")));
+}

package/dist/server/presentations/schema.d.ts

@@ -0,0 +1,120 @@
+/** Versioned, renderer-independent contract for structured presentation tools. */
+export declare const PRESENTATION_SPEC_VERSION: 1;
+export declare const PRESENTATION_LIMITS: {
+    readonly maxSlides: 200;
+    readonly maxElementsPerSlide: 500;
+    readonly maxTextCharacters: 100000;
+    readonly maxTableCells: 10000;
+    readonly maxChartPoints: 20000;
+};
+export type PresentationSpec = {
+    version: typeof PRESENTATION_SPEC_VERSION;
+    metadata?: {
+        title?: string;
+        subject?: string;
+        author?: string;
+        company?: string;
+        language?: string;
+    };
+    canvas: {
+        width: number;
+        height: number;
+    };
+    theme?: PresentationTheme;
+    slides: PresentationSlide[];
+};
+export type PresentationTheme = {
+    colors?: Record<string, string>;
+    fonts?: {
+        heading?: string;
+        body?: string;
+        mono?: string;
+    };
+};
+export type PresentationSlide = {
+    id: string;
+    title?: string;
+    notes?: string;
+    background?: string;
+    elements: PresentationElement[];
+};
+type Frame = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type BaseElement = Frame & {
+    id: string;
+    altText?: string;
+    name?: string;
+    hidden?: boolean;
+    rotation?: number;
+};
+export type TextElement = BaseElement & {
+    type: "text";
+    text: string;
+    fontFamily?: string;
+    fontSize?: number;
+    color?: string;
+    bold?: boolean;
+    italic?: boolean;
+    align?: "left" | "center" | "right" | "justify";
+    verticalAlign?: "top" | "middle" | "bottom";
+    link?: string;
+};
+export type ShapeElement = BaseElement & {
+    type: "shape";
+    shape: "rectangle" | "roundRectangle" | "ellipse" | "triangle" | "chevron";
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+};
+export type LineElement = BaseElement & {
+    type: "line";
+    stroke?: string;
+    strokeWidth?: number;
+    dash?: "solid" | "dash" | "dot";
+    beginArrow?: boolean;
+    endArrow?: boolean;
+};
+export type ImageElement = BaseElement & {
+    type: "image";
+    source: string;
+    fit?: "contain" | "cover" | "stretch";
+    link?: string;
+};
+export type TableElement = BaseElement & {
+    type: "table";
+    rows: Array<Array<string | number | boolean | null>>;
+    headerRows?: number;
+};
+export type ChartElement = BaseElement & {
+    type: "chart";
+    chart: "bar" | "column" | "line" | "area" | "pie" | "doughnut" | "scatter";
+    categories?: string[];
+    series: Array<{
+        name: string;
+        values: Array<number | null>;
+        xValues?: Array<number | null>;
+    }>;
+    showLegend?: boolean;
+    showValues?: boolean;
+};
+export type PresentationElement = TextElement | ShapeElement | LineElement | ImageElement | TableElement | ChartElement;
+export type PresentationDiagnostic = {
+    code: "invalid_type" | "invalid_value" | "unsupported_version" | "duplicate_id" | "limit_exceeded" | "out_of_bounds";
+    severity: "error" | "warning";
+    path: string;
+    message: string;
+};
+export type PresentationValidationResult = {
+    valid: true;
+    spec: PresentationSpec;
+    diagnostics: PresentationDiagnostic[];
+} | {
+    valid: false;
+    diagnostics: PresentationDiagnostic[];
+};
+export declare function validatePresentationSpec(input: unknown): PresentationValidationResult;
+export {};

package/dist/server/presentations/schema.js

@@ -0,0 +1,128 @@
+/** Versioned, renderer-independent contract for structured presentation tools. */
+export const PRESENTATION_SPEC_VERSION = 1;
+export const PRESENTATION_LIMITS = {
+    maxSlides: 200,
+    maxElementsPerSlide: 500,
+    maxTextCharacters: 100_000,
+    maxTableCells: 10_000,
+    maxChartPoints: 20_000,
+};
+const ELEMENT_TYPES = new Set(["text", "shape", "line", "image", "table", "chart"]);
+const ID_PATTERN = /^[A-Za-z][A-Za-z0-9._-]{0,127}$/;
+export function validatePresentationSpec(input) {
+    const diagnostics = [];
+    const error = (code, path, message) => diagnostics.push({ code, severity: "error", path, message });
+    if (!isObject(input)) {
+        error("invalid_type", "$", "Presentation spec must be an object.");
+        return { valid: false, diagnostics };
+    }
+    if (input.version !== PRESENTATION_SPEC_VERSION) {
+        error("unsupported_version", "$.version", `Only presentation spec version ${PRESENTATION_SPEC_VERSION} is supported.`);
+    }
+    const canvas = input.canvas;
+    if (!isObject(canvas))
+        error("invalid_type", "$.canvas", "Canvas must be an object.");
+    else {
+        positiveNumber(canvas.width, "$.canvas.width", error);
+        positiveNumber(canvas.height, "$.canvas.height", error);
+    }
+    if (!Array.isArray(input.slides)) {
+        error("invalid_type", "$.slides", "Slides must be an array.");
+    }
+    else {
+        if (input.slides.length > PRESENTATION_LIMITS.maxSlides) {
+            error("limit_exceeded", "$.slides", `A deck may contain at most ${PRESENTATION_LIMITS.maxSlides} slides.`);
+        }
+        const ids = new Set();
+        input.slides.forEach((slide, slideIndex) => validateSlide(slide, slideIndex, canvas, ids, error));
+    }
+    if (input.theme !== undefined)
+        validateTheme(input.theme, error);
+    return diagnostics.some((item) => item.severity === "error")
+        ? { valid: false, diagnostics }
+        : { valid: true, spec: input, diagnostics };
+}
+function validateSlide(slide, index, canvas, ids, error) {
+    const path = `$.slides[${index}]`;
+    if (!isObject(slide))
+        return error("invalid_type", path, "Slide must be an object.");
+    validateId(slide.id, `${path}.id`, ids, error);
+    if (!Array.isArray(slide.elements))
+        return error("invalid_type", `${path}.elements`, "Elements must be an array.");
+    if (slide.elements.length > PRESENTATION_LIMITS.maxElementsPerSlide) {
+        error("limit_exceeded", `${path}.elements`, `A slide may contain at most ${PRESENTATION_LIMITS.maxElementsPerSlide} elements.`);
+    }
+    slide.elements.forEach((element, elementIndex) => validateElement(element, `${path}.elements[${elementIndex}]`, canvas, ids, error));
+}
+function validateElement(element, path, canvas, ids, error) {
+    if (!isObject(element))
+        return error("invalid_type", path, "Element must be an object.");
+    validateId(element.id, `${path}.id`, ids, error);
+    if (typeof element.type !== "string" || !ELEMENT_TYPES.has(element.type)) {
+        error("invalid_value", `${path}.type`, "Element type is not supported.");
+        return;
+    }
+    for (const key of ["x", "y", "width", "height"])
+        positiveNumber(element[key], `${path}.${key}`, error, key === "x" || key === "y");
+    if (isObject(canvas) && finite(element.x) && finite(element.y) && finite(element.width) && finite(element.height)
+        && finite(canvas.width) && finite(canvas.height)
+        && (element.x < 0 || element.y < 0 || element.x + element.width > canvas.width || element.y + element.height > canvas.height)) {
+        error("out_of_bounds", path, "Element frame must fit within the canvas.");
+    }
+    if (element.type === "text") {
+        if (typeof element.text !== "string")
+            error("invalid_type", `${path}.text`, "Text must be a string.");
+        else if (element.text.length > PRESENTATION_LIMITS.maxTextCharacters)
+            error("limit_exceeded", `${path}.text`, "Text is too long.");
+    }
+    else if (element.type === "image") {
+        if (typeof element.source !== "string" || !element.source.trim())
+            error("invalid_value", `${path}.source`, "Image source is required.");
+        if (!element.altText)
+            error("invalid_value", `${path}.altText`, "Images require alt text.");
+    }
+    else if (element.type === "table") {
+        if (!Array.isArray(element.rows))
+            error("invalid_type", `${path}.rows`, "Table rows must be an array.");
+        else if (element.rows.reduce((sum, row) => sum + (Array.isArray(row) ? row.length : 0), 0) > PRESENTATION_LIMITS.maxTableCells)
+            error("limit_exceeded", `${path}.rows`, "Table contains too many cells.");
+    }
+    else if (element.type === "chart")
+        validateChart(element, path, error);
+}
+function validateChart(chart, path, error) {
+    if (!Array.isArray(chart.series) || chart.series.length === 0)
+        return error("invalid_value", `${path}.series`, "Chart requires at least one series.");
+    let points = 0;
+    for (const [index, series] of chart.series.entries()) {
+        if (!isObject(series) || typeof series.name !== "string" || !Array.isArray(series.values)) {
+            error("invalid_type", `${path}.series[${index}]`, "Series requires a name and numeric values.");
+            continue;
+        }
+        if (series.values.some((value) => value !== null && !finite(value)))
+            error("invalid_value", `${path}.series[${index}].values`, "Chart values must be finite numbers or null.");
+        points += series.values.length;
+    }
+    if (points > PRESENTATION_LIMITS.maxChartPoints)
+        error("limit_exceeded", `${path}.series`, "Chart contains too many data points.");
+}
+function validateTheme(theme, error) {
+    if (!isObject(theme))
+        return error("invalid_type", "$.theme", "Theme must be an object.");
+    if (theme.colors !== undefined && (!isObject(theme.colors) || Object.values(theme.colors).some((value) => typeof value !== "string"))) {
+        error("invalid_type", "$.theme.colors", "Theme colors must map token names to color strings.");
+    }
+}
+function validateId(value, path, ids, error) {
+    if (typeof value !== "string" || !ID_PATTERN.test(value))
+        return error("invalid_value", path, "ID must start with a letter and contain only letters, digits, dot, underscore, or hyphen.");
+    if (ids.has(value))
+        error("duplicate_id", path, `ID '${value}' is already used in this deck.`);
+    ids.add(value);
+}
+function positiveNumber(value, path, error, allowZero = false) {
+    if (!finite(value) || (allowZero ? value < 0 : value <= 0))
+        error("invalid_value", path, allowZero ? "Value must be a non-negative finite number." : "Value must be a positive finite number.");
+}
+function finite(value) { return typeof value === "number" && Number.isFinite(value); }
+function isObject(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }