synthos 0.10.1 → 0.11.0

package/src/service/transformPage.ts

@@ -1,7 +1,9 @@
 import { AgentCompletion } from "../models";
+import { ToolDefinition, ToolHandler } from "../models/types";
 import * as cheerio from "cheerio";
 import { Customizer } from "../customizer";
 import { Attachment, Builder, ContextSection } from "../builders/types";
+import { PageValidationResult } from "./pageValidator";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -19,6 +21,14 @@ export interface TransformPageArgs {
     productName?: string;
     /** Optional image attachments sent alongside the user message. */
     attachments?: Attachment[];
+    /** Chat history from the shell — used for newBuild detection instead of counting DOM elements. */
+    history?: { role: string; content: string }[];
+    /** Optional tool definitions exposed to the builder (on-demand context loading). */
+    tools?: ToolDefinition[];
+    /** Executors keyed by tool name. Required when `tools` is provided. */
+    toolHandlers?: Record<string, ToolHandler>;
+    /** Fired once per tool-use iteration with the names of tools about to execute. */
+    onToolCall?: (names: string[]) => void;
 }
 
 export type ChangeOp =
@@ -39,6 +49,22 @@ export type ChangeList = ChangeOp[];
 export interface TransformPageResult {
     html: string;
     changeCount: number;
+    /** For 'reply' results — the assistant's text response (shell displays it). */
+    replyText?: string;
+    /** For 'error' results — the error message (shell displays it). */
+    errorText?: string;
+    /** Page validation results (undefined if validation was skipped). */
+    validation?: PageValidationResult;
+    /** Number of change ops that were silently skipped (missing target, locked, etc.). */
+    skippedOps?: number;
+    /** Short human-readable reasons for each skipped op, in order. */
+    skipReasons?: string[];
+}
+
+export interface ApplyChangeListReport {
+    html: string;
+    skippedOps: number;
+    skipReasons: string[];
 }
 
 export async function transformPage(args: TransformPageArgs): Promise<AgentCompletion<TransformPageResult>> {
@@ -47,182 +73,86 @@ export async function transformPage(args: TransformPageArgs): Promise<AgentCompl
     // 0. Strip the early error-capture script so the LLM never sees it
     const pageState = stripErrorCapture(args.pageState);
 
-    // 1. Assign data-node-id to every element
+    // 1. Assign data-nid to every element
     const { html: annotatedHtml } = assignNodeIds(pageState);
 
+    // 1b. Strip HTML comments from the annotated copy sent to the LLM (saves tokens).
+    // The original pageState is preserved — changes are applied to the annotated copy
+    // and then node IDs are stripped, so comments survive in the saved page.
+    const llmHtml = annotatedHtml.replace(/<!--[\s\S]*?-->/g, '');
+
     try {
         // 2. Build CURRENT_PAGE section
         const currentPage: ContextSection = {
             title: '<CURRENT_PAGE>',
-            content: annotatedHtml,
+            content: llmHtml,
+            sketch: null,
+            mode: 'always-full',
             instructions: '',
         };
 
-        // 3. Determine newBuild: if isBuilder, count .chat-message in annotated HTML
+        // 3. Determine newBuild: if isBuilder, check chat history length
         let newBuild = false;
         if (args.isBuilder) {
-            const $ = cheerio.load(annotatedHtml, { decodeEntities: false });
-            const messageCount = $('#chatMessages .chat-message').length;
-            newBuild = messageCount <= 1;
+            if (args.history) {
+                // Shell provides explicit history — empty or greeting-only means new build
+                newBuild = args.history.length <= 1;
+            } else {
+                // Fallback: count .chat-message in annotated HTML (legacy pages without chat-history.json)
+                const $ = cheerio.load(annotatedHtml, { decodeEntities: false });
+                const messageCount = $('#chatMessages .chat-message').length;
+                newBuild = messageCount <= 1;
+            }
         }
 
-        // 4. Call builder
-        const result = await builder.run(currentPage, additionalSections, message, newBuild, args.attachments);
+        // 4. Call builder (with timeout guard)
+        const TRANSFORM_TIMEOUT_MS = 600_000; // 10 minutes
+        const result = await Promise.race([
+            builder.run(currentPage, additionalSections, message, newBuild, args.attachments, args.tools, args.toolHandlers, args.onToolCall),
+            new Promise<never>((_, reject) =>
+                setTimeout(() => reject(new Error('Page transform timed out — the AI took too long to respond. Please try again.')), TRANSFORM_TIMEOUT_MS)
+            ),
+        ]);
 
         // 5. Switch on result kind
         switch (result.kind) {
             case 'transforms': {
-                const applied = applyChangeList(annotatedHtml, result.changes);
-                const clean = stripNodeIds(applied);
-                const deduped = deduplicateInlineScripts(clean);
-                const safe = ensureScriptsBeforeBodyClose(deduped);
-                return { completed: true, value: { html: safe, changeCount: result.changes.length } };
+                const report = applyChangeListWithReport(annotatedHtml, result.changes);
+                const safe = postProcessHtml(report.html);
+                return { completed: true, value: {
+                    html: safe,
+                    changeCount: result.changes.length,
+                    replyText: result.message,
+                    skippedOps: report.skippedOps,
+                    skipReasons: report.skipReasons,
+                } };
             }
             case 'reply': {
-                const productName = args.productName ?? 'SynthOS';
-                const withReply = appendChatReply(annotatedHtml, message, result.text, productName);
-                const clean = stripNodeIds(withReply);
-                const deduped = deduplicateInlineScripts(clean);
-                const safe = ensureScriptsBeforeBodyClose(deduped);
-                return { completed: true, value: { html: safe, changeCount: -1 } };
+                const safe = postProcessHtml(annotatedHtml);
+                return { completed: true, value: { html: safe, changeCount: -1, replyText: result.text } };
             }
             case 'error': {
-                const productName = args.productName ?? 'SynthOS';
-                const errorHtml = appendChatError(annotatedHtml, message, result.error.message, productName);
-                const clean = stripNodeIds(errorHtml);
-                return { completed: true, value: { html: clean, changeCount: -1 } };
+                const clean = stripNodeIds(annotatedHtml);
+                return { completed: true, value: { html: clean, changeCount: -1, errorText: result.error.message } };
             }
         }
     } catch (err: unknown) {
-        // On any error: append error message to chat
-        const productName = args.productName ?? 'SynthOS';
         const errorMessage = err instanceof Error ? err.message : String(err);
-        const errorHtml = appendChatError(annotatedHtml, message, errorMessage, productName);
-        const clean = stripNodeIds(errorHtml);
-        return { completed: true, value: { html: clean, changeCount: -1 } };
+        const clean = stripNodeIds(annotatedHtml);
+        return { completed: true, value: { html: clean, changeCount: -1, errorText: errorMessage } };
     }
 }
 
-// ---------------------------------------------------------------------------
-// Chat reply helper
-// ---------------------------------------------------------------------------
-
-/**
- * Append a user message and a reply to #chatMessages using cheerio.
- */
-function appendChatReply(annotatedHtml: string, userMessage: string, replyText: string, productName: string): string {
-    const $ = cheerio.load(annotatedHtml, { decodeEntities: false });
-    const chatMessages = $('#chatMessages');
-    if (chatMessages.length > 0) {
-        chatMessages.append(`<div class="chat-message"><p><strong>User:</strong> ${escapeHtml(userMessage)}</p></div>`);
-        const replyHtml = simpleMarkdown(replyText);
-        chatMessages.append(`<div class="chat-message"><p><strong>${escapeHtml(productName)}:</strong> ${replyHtml}</p></div>`);
-    }
-    return $.html();
-}
-
-function escapeHtml(text: string): string {
-    return text
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;');
-}
-
-/**
- * Lightweight markdown-to-HTML converter for chat reply text.
- * Handles: code blocks, inline code, bold, italic, links, unordered/ordered lists, paragraphs.
- */
-export function simpleMarkdown(text: string): string {
-    // Extract fenced code blocks first to protect their contents
-    const codeBlocks: string[] = [];
-    let processed = text.replace(/```(\w*)\n([\s\S]*?)```/g, (_match, lang, code) => {
-        const idx = codeBlocks.length;
-        const escaped = escapeHtml(code.replace(/\n$/, ''));
-        const langAttr = lang ? ` class="language-${escapeHtml(lang)}"` : '';
-        codeBlocks.push(`<pre><code${langAttr}>${escaped}</code></pre>`);
-        return `\x00CODEBLOCK${idx}\x00`;
-    });
-
-    // Split into paragraphs by blank lines
-    const blocks = processed.split(/\n{2,}/);
-    const htmlBlocks: string[] = [];
-
-    for (const block of blocks) {
-        const trimmed = block.trim();
-        if (!trimmed) continue;
-
-        // Code block placeholder
-        if (/^\x00CODEBLOCK\d+\x00$/.test(trimmed)) {
-            htmlBlocks.push(trimmed);
-            continue;
-        }
-
-        // Unordered list (lines starting with - or *)
-        if (/^[\-\*] /m.test(trimmed) && trimmed.split('\n').every(l => /^[\-\*] /.test(l.trim()) || l.trim() === '')) {
-            const items = trimmed.split('\n')
-                .map(l => l.trim())
-                .filter(l => l)
-                .map(l => `<li>${inlineMarkdown(l.replace(/^[\-\*] /, ''))}</li>`)
-                .join('');
-            htmlBlocks.push(`<ul>${items}</ul>`);
-            continue;
-        }
-
-        // Ordered list (lines starting with 1. 2. etc.)
-        if (/^\d+\. /m.test(trimmed) && trimmed.split('\n').every(l => /^\d+\. /.test(l.trim()) || l.trim() === '')) {
-            const items = trimmed.split('\n')
-                .map(l => l.trim())
-                .filter(l => l)
-                .map(l => `<li>${inlineMarkdown(l.replace(/^\d+\. /, ''))}</li>`)
-                .join('');
-            htmlBlocks.push(`<ol>${items}</ol>`);
-            continue;
-        }
-
-        // Regular paragraph
-        htmlBlocks.push(`<p>${inlineMarkdown(trimmed.replace(/\n/g, '<br>'))}</p>`);
-    }
-
-    // Restore code blocks
-    let result = htmlBlocks.join('');
-    result = result.replace(/\x00CODEBLOCK(\d+)\x00/g, (_m, idx) => codeBlocks[parseInt(idx)]);
-    return result;
-}
-
-/** Apply inline markdown formatting: bold, italic, inline code, links. */
-function inlineMarkdown(text: string): string {
-    // Inline code (protect from further processing)
-    const codes: string[] = [];
-    let result = text.replace(/`([^`]+)`/g, (_m, code) => {
-        const idx = codes.length;
-        codes.push(`<code>${escapeHtml(code)}</code>`);
-        return `\x00CODE${idx}\x00`;
-    });
-
-    // Bold (**text** or __text__)
-    result = result.replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>');
-    result = result.replace(/__(.+?)__/g, '<strong>$1</strong>');
-
-    // Italic (*text* or _text_)
-    result = result.replace(/\*(.+?)\*/g, '<em>$1</em>');
-    result = result.replace(/(?<!\w)_(.+?)_(?!\w)/g, '<em>$1</em>');
-
-    // Links [text](url)
-    result = result.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
-
-    // Restore inline code
-    result = result.replace(/\x00CODE(\d+)\x00/g, (_m, idx) => codes[parseInt(idx)]);
-
-    return result;
-}
-
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+/** Tags the LLM will never target — skip annotation to save tokens. */
+const SKIP_ANNOTATION_TAGS = new Set(['br', 'wbr', 'col', 'source']);
+
 /**
- * Assign sequential `data-node-id` to every element in the HTML.
+ * Assign sequential `data-nid` to every element in the HTML.
+ * Skips trivial elements (br, wbr, col, source) that the LLM never targets.
  */
 export function assignNodeIds(html: string): { html: string; nodeCount: number } {
     const $ = cheerio.load(html, { decodeEntities: false });
@@ -231,18 +161,100 @@ export function assignNodeIds(html: string): { html: string; nodeCount: number }
     $('*').each(function (this: cheerio.Element) {
         const el = $(this);
         if (this.type === 'tag' || this.type === 'script' || this.type === 'style') {
-            el.attr('data-node-id', String(counter++));
+            const tag = (this as any).tagName?.toLowerCase() ?? (this as any).name?.toLowerCase();
+            if (SKIP_ANNOTATION_TAGS.has(tag)) return;
+            el.attr('data-nid', String(counter++));
         }
     });
     return { html: $.html(), nodeCount: counter };
 }
 
 /**
- * Remove all `data-node-id` attributes from the HTML.
+ * Remove all `data-nid` attributes from the HTML.
  */
 export function stripNodeIds(html: string): string {
     const $ = cheerio.load(html, { decodeEntities: false });
-    $('[data-node-id]').removeAttr('data-node-id');
+    $('[data-nid]').removeAttr('data-nid');
+    return $.html();
+}
+
+/**
+ * Consolidated post-processing: strip node IDs, deduplicate scripts, and
+ * ensure script ordering — all in a single cheerio parse/serialize cycle.
+ */
+function postProcessHtml(html: string): string {
+    const $ = cheerio.load(html, { decodeEntities: false });
+
+    // Strip data-nid attributes
+    $('[data-nid]').removeAttr('data-nid');
+
+    // Deduplicate inline scripts (ID-based pass)
+    const SYSTEM_IDS = new Set(['page-info', 'page-helpers', 'page-script', 'error', 'shell-v3', 'server-v3', 'storage-v3', 'script-v3', 'connector-v3', 'agent-v3']);
+    const idGroups = new Map<string, cheerio.Cheerio[]>();
+    $('script').each(function (_, rawEl) {
+        const el = $(rawEl);
+        if (el.attr('src')) return;
+        const id = el.attr('id');
+        if (!id || SYSTEM_IDS.has(id)) return;
+        if (!idGroups.has(id)) idGroups.set(id, []);
+        idGroups.get(id)!.push(el);
+    });
+    for (const [id, group] of idGroups) {
+        if (group.length < 2) continue;
+        for (let i = 0; i < group.length - 1; i++) {
+            console.log(`deduplicateInlineScripts: removing duplicate script id="${id}" (keeping last of ${group.length})`);
+            group[i].remove();
+        }
+    }
+
+    // Deduplicate inline scripts (declaration-overlap pass for id-less scripts)
+    const declPattern = /(?:^|;|\n)\s*(?:let|const|var|function|class)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/g;
+    interface ScriptInfo { el: cheerio.Cheerio; declarations: Set<string>; }
+    const scripts: ScriptInfo[] = [];
+    $('script').each(function (_, rawEl) {
+        const el = $(rawEl);
+        if (el.attr('src')) return;
+        if (el.attr('id')) return;
+        if ((el.attr('type') ?? '').toLowerCase() === 'application/json') return;
+        const code = (el.html() ?? '').trim();
+        if (!code) return;
+        const declarations = new Set<string>();
+        let m: RegExpExecArray | null;
+        declPattern.lastIndex = 0;
+        while ((m = declPattern.exec(code)) !== null) declarations.add(m[1]);
+        scripts.push({ el, declarations });
+    });
+    const toRemove = new Set<number>();
+    for (let i = 0; i < scripts.length; i++) {
+        if (toRemove.has(i)) continue;
+        for (let j = i + 1; j < scripts.length; j++) {
+            if (toRemove.has(j)) continue;
+            const a = scripts[i].declarations, b = scripts[j].declarations;
+            if (a.size < 2 || b.size < 2) continue;
+            let overlap = 0;
+            for (const name of a) if (b.has(name)) overlap++;
+            if (overlap / Math.min(a.size, b.size) >= 0.6) {
+                console.log(`deduplicateInlineScripts: removing duplicate script (${overlap}/${Math.min(a.size, b.size)} declaration overlap)`);
+                toRemove.add(i);
+                break;
+            }
+        }
+    }
+    for (const idx of toRemove) scripts[idx].el.remove();
+
+    // Ensure page-helpers and page-script are last children of <body>
+    const body = $('body');
+    if (body.length > 0) {
+        const helpers = $('script#page-helpers');
+        const pageScript = $('script#page-script');
+        const helpersHtml = helpers.length > 0 ? $.html(helpers.first()) : '';
+        const pageScriptHtml = pageScript.length > 0 ? $.html(pageScript.first()) : '';
+        if (helpers.length > 0) helpers.remove();
+        if (pageScript.length > 0) pageScript.remove();
+        if (helpersHtml) body.append(helpersHtml);
+        if (pageScriptHtml) body.append(pageScriptHtml);
+    }
+
     return $.html();
 }
 
@@ -325,7 +337,7 @@ export function normalizedIndexOf(haystack: string, needle: string): { start: nu
 export function deduplicateInlineScripts(html: string): string {
     const $ = cheerio.load(html, { decodeEntities: false });
 
-    const SYSTEM_IDS = new Set(['page-info', 'page-helpers', 'page-script', 'error']);
+    const SYSTEM_IDS = new Set(['page-info', 'page-helpers', 'page-script', 'error', 'shell-v3', 'server-v3', 'storage-v3', 'script-v3', 'connector-v3', 'agent-v3']);
 
     // ── Pass 1: ID-based dedup ──────────────────────────────────────────
     const idGroups = new Map<string, cheerio.Cheerio[]>();
@@ -428,8 +440,8 @@ export function ensureScriptsBeforeBodyClose(html: string): string {
     const helpers = $('script#page-helpers');
     const pageScript = $('script#page-script');
 
-    const helpersHtml = helpers.length > 0 ? $.html(helpers) : '';
-    const pageScriptHtml = pageScript.length > 0 ? $.html(pageScript) : '';
+    const helpersHtml = helpers.length > 0 ? $.html(helpers.first()) : '';
+    const pageScriptHtml = pageScript.length > 0 ? $.html(pageScript.first()) : '';
 
     // Remove from current position and re-append at end of <body>
     if (helpers.length > 0) helpers.remove();
@@ -448,15 +460,39 @@ function isElementLocked(el: cheerio.Cheerio, $: cheerio.Root): boolean {
 }
 
 /**
- * If the target element is a <script> or <style> and the html is wrapped in a
- * redundant matching tag, strip the outer tag to avoid nesting (e.g.
- * `<script>` inside `<script>`). Returns the inner content when unwrapped.
+ * If the provided html is wrapped in a redundant tag that matches the target
+ * element, strip the outer tag to avoid nesting (e.g. `<div id="x">` inside
+ * the existing `<div id="x">`). For script/style elements the tag name alone
+ * is sufficient; for other elements we require an id or class match to avoid
+ * false positives.
  */
-function unwrapRedundantTag(tagName: string | undefined, html: string): string {
-    if (tagName !== 'script' && tagName !== 'style') return html;
-    const re = new RegExp(`^\\s*<${tagName}[^>]*>([\\s\\S]*)</${tagName}>\\s*$`, 'i');
+function unwrapRedundantTag(tagName: string | undefined, html: string, targetId?: string, targetClass?: string): string {
+    if (!tagName) return html;
+    const re = new RegExp(`^\\s*<${tagName}\\b([^>]*)>([\\s\\S]*)</${tagName}>\\s*$`, 'i');
     const match = html.match(re);
-    return match ? match[1] : html;
+    if (!match) return html;
+
+    // For script/style, always unwrap (original behaviour)
+    if (tagName === 'script' || tagName === 'style') {
+        return match[2];
+    }
+
+    // For other elements, require an id or class match to avoid false positives
+    const outerAttrs = match[1];
+    if (targetId) {
+        const idMatch = outerAttrs.match(/\bid=["']([^"']*)["']/);
+        if (idMatch && idMatch[1] === targetId) return match[2];
+    }
+    if (targetClass) {
+        const classMatch = outerAttrs.match(/\bclass=["']([^"']*)["']/);
+        if (classMatch) {
+            const targetClasses = targetClass.split(/\s+/);
+            const outerClasses = classMatch[1].split(/\s+/);
+            if (targetClasses.some(c => outerClasses.includes(c))) return match[2];
+        }
+    }
+
+    return html;
 }
 
 /**
@@ -471,31 +507,48 @@ function stripNestedBlockTags(tagName: string | undefined, text: string): string
 }
 
 /**
- * Apply a list of CRUD operations to annotated HTML (elements must have `data-node-id`).
+ * Apply a list of CRUD operations to annotated HTML (elements must have `data-nid`).
+ * Returns just the resulting HTML string. For diagnostic info about skipped ops,
+ * use `applyChangeListWithReport` instead.
  */
 export function applyChangeList(html: string, changes: ChangeList): string {
+    return applyChangeListWithReport(html, changes).html;
+}
+
+/**
+ * Apply a list of CRUD operations and return the resulting HTML plus a report
+ * of any ops that were silently skipped (missing target node, locked element,
+ * search text not found, etc.). Callers can surface the skip report to the
+ * user so that partial/broken builds do not fail silently.
+ */
+export function applyChangeListWithReport(html: string, changes: ChangeList): ApplyChangeListReport {
     const $ = cheerio.load(html, { decodeEntities: false });
+    const skipReasons: string[] = [];
+    const recordSkip = (reason: string) => {
+        console.warn(`applyChangeList: ${reason}`);
+        skipReasons.push(reason);
+    };
 
     for (const change of changes) {
         switch (change.op) {
             case 'update': {
-                const el = $(`[data-node-id="${change.nodeId}"]`);
+                const el = $(`[data-nid="${change.nodeId}"]`);
                 if (el.length === 0) {
-                    console.warn(`applyChangeList: skipping update — node ${change.nodeId} not found (already removed?)`);
+                    recordSkip(`skipping update — node ${change.nodeId} not found (already removed?)`);
                     break;
                 }
                 const tag = el.prop('tagName')?.toLowerCase();
-                el.html(unwrapRedundantTag(tag, change.html));
+                el.html(unwrapRedundantTag(tag, change.html, el.attr('id'), el.attr('class')));
                 break;
             }
             case 'replace': {
-                const el = $(`[data-node-id="${change.nodeId}"]`);
+                const el = $(`[data-nid="${change.nodeId}"]`);
                 if (el.length === 0) {
-                    console.warn(`applyChangeList: skipping replace — node ${change.nodeId} not found (already removed?)`);
+                    recordSkip(`skipping replace — node ${change.nodeId} not found (already removed?)`);
                     break;
                 }
                 if (isElementLocked(el, $)) {
-                    console.warn(`applyChangeList: skipping replace — node ${change.nodeId} is data-locked`);
+                    recordSkip(`skipping replace — node ${change.nodeId} is data-locked`);
                     break;
                 }
                 // If the target is a <script> or <style> and the html doesn't
@@ -511,22 +564,22 @@ export function applyChangeList(html: string, changes: ChangeList): string {
                 break;
             }
             case 'delete': {
-                const el = $(`[data-node-id="${change.nodeId}"]`);
+                const el = $(`[data-nid="${change.nodeId}"]`);
                 if (el.length === 0) {
-                    console.warn(`applyChangeList: skipping delete — node ${change.nodeId} not found (already removed?)`);
+                    recordSkip(`skipping delete — node ${change.nodeId} not found (already removed?)`);
                     break;
                 }
                 if (isElementLocked(el, $)) {
-                    console.warn(`applyChangeList: skipping delete — node ${change.nodeId} is data-locked`);
+                    recordSkip(`skipping delete — node ${change.nodeId} is data-locked`);
                     break;
                 }
                 el.remove();
                 break;
             }
             case 'insert': {
-                const parent = $(`[data-node-id="${change.parentId}"]`);
+                const parent = $(`[data-nid="${change.parentId}"]`);
                 if (parent.length === 0) {
-                    console.warn(`applyChangeList: skipping insert — parent node ${change.parentId} not found`);
+                    recordSkip(`skipping insert — parent node ${change.parentId} not found`);
                     break;
                 }
                 // Unwrap redundant tags when inserting into script/style
@@ -538,27 +591,27 @@ export function applyChangeList(html: string, changes: ChangeList): string {
                     case 'before': parent.before(insertHtml); break;
                     case 'after': parent.after(insertHtml); break;
                     default:
-                        console.warn(`applyChangeList: skipping insert — unknown position "${(change as any).position}"`);
+                        recordSkip(`skipping insert — unknown position "${(change as any).position}"`);
                 }
                 break;
             }
             case 'style-element': {
-                const el = $(`[data-node-id="${change.nodeId}"]`);
+                const el = $(`[data-nid="${change.nodeId}"]`);
                 if (el.length === 0) {
-                    console.warn(`applyChangeList: skipping style-element — node ${change.nodeId} not found (already removed?)`);
+                    recordSkip(`skipping style-element — node ${change.nodeId} not found (already removed?)`);
                     break;
                 }
                 if (isElementLocked(el, $)) {
-                    console.warn(`applyChangeList: skipping style-element — node ${change.nodeId} is data-locked`);
+                    recordSkip(`skipping style-element — node ${change.nodeId} is data-locked`);
                     break;
                 }
                 el.attr('style', change.style);
                 break;
             }
             case 'search-replace': {
-                const el = $(`[data-node-id="${change.nodeId}"]`);
+                const el = $(`[data-nid="${change.nodeId}"]`);
                 if (el.length === 0) {
-                    console.warn(`applyChangeList: skipping search-replace — node ${change.nodeId} not found (already removed?)`);
+                    recordSkip(`skipping search-replace — node ${change.nodeId} not found (already removed?)`);
                     break;
                 }
                 const srTag = el.prop('tagName')?.toLowerCase();
@@ -572,15 +625,15 @@ export function applyChangeList(html: string, changes: ChangeList): string {
                     if (norm) {
                         el.html(content.slice(0, norm.start) + replaceText + content.slice(norm.end));
                     } else {
-                        console.warn(`applyChangeList: skipping search-replace — search text not found in node ${change.nodeId}`);
+                        recordSkip(`skipping search-replace — search text not found in node ${change.nodeId}`);
                     }
                 }
                 break;
             }
             case 'search-insert': {
-                const el = $(`[data-node-id="${change.nodeId}"]`);
+                const el = $(`[data-nid="${change.nodeId}"]`);
                 if (el.length === 0) {
-                    console.warn(`applyChangeList: skipping search-insert — node ${change.nodeId} not found (already removed?)`);
+                    recordSkip(`skipping search-insert — node ${change.nodeId} not found (already removed?)`);
                     break;
                 }
                 const siTag = el.prop('tagName')?.toLowerCase();
@@ -595,7 +648,7 @@ export function applyChangeList(html: string, changes: ChangeList): string {
                     if (norm) {
                         el.html(content.slice(0, norm.end) + insertContent + content.slice(norm.end));
                     } else {
-                        console.warn(`applyChangeList: skipping search-insert — after text not found in node ${change.nodeId}`);
+                        recordSkip(`skipping search-insert — after text not found in node ${change.nodeId}`);
                     }
                 }
                 break;
@@ -605,36 +658,73 @@ export function applyChangeList(html: string, changes: ChangeList): string {
         }
     }
 
-    return $.html();
+    return { html: $.html(), skippedOps: skipReasons.length, skipReasons };
 }
 
+/** Known op types and their required fields (beyond `op`). */
+const CHANGE_OP_REQUIRED_FIELDS: Record<string, string[]> = {
+    'update': ['nodeId', 'html'],
+    'replace': ['nodeId', 'html'],
+    'delete': ['nodeId'],
+    'insert': ['parentId', 'position', 'html'],
+    'style-element': ['nodeId', 'style'],
+    'search-replace': ['nodeId', 'search', 'replace'],
+    'search-insert': ['nodeId', 'after', 'content'],
+};
+
+const VALID_INSERT_POSITIONS = new Set(['prepend', 'append', 'before', 'after']);
+
 /**
- * Append a user message and a styled error message to #chatMessages.
+ * Validate and filter a raw parsed array into a well-formed ChangeList.
+ * Invalid ops are logged as warnings and dropped rather than crashing.
  */
-function appendChatError(html: string, userMessage: string, errorDetails: string, productName: string): string {
-    const $ = cheerio.load(html, { decodeEntities: false });
-    const chatMessages = $('#chatMessages');
-    if (chatMessages.length > 0) {
-        chatMessages.append(
-            `<div class="chat-message"><p><strong>User:</strong> ${escapeHtml(userMessage)}</p></div>`
-        );
-        chatMessages.append(
-            `<div class="chat-message chat-message-error"><p><strong>${escapeHtml(productName)}:</strong> Something went wrong \u2014 please try again.</p>`
-            + `<p class="chat-error-details">${escapeHtml(errorDetails)}</p></div>`
-        );
+export function validateChangeOps(raw: unknown[]): ChangeList {
+    const valid: ChangeList = [];
+    for (let i = 0; i < raw.length; i++) {
+        const item = raw[i] as Record<string, unknown>;
+        if (!item || typeof item !== 'object') {
+            console.warn(`validateChangeOps: skipping op[${i}] — not an object`);
+            continue;
+        }
+        const op = item.op;
+        if (typeof op !== 'string') {
+            console.warn(`validateChangeOps: skipping op[${i}] — missing or non-string 'op' field`);
+            continue;
+        }
+        const requiredFields = CHANGE_OP_REQUIRED_FIELDS[op];
+        if (!requiredFields) {
+            console.warn(`validateChangeOps: skipping op[${i}] — unknown op type '${op}'`);
+            continue;
+        }
+        let missingField = false;
+        for (const field of requiredFields) {
+            if (typeof item[field] !== 'string') {
+                console.warn(`validateChangeOps: skipping op[${i}] (${op}) — missing or non-string '${field}' field`);
+                missingField = true;
+                break;
+            }
+        }
+        if (missingField) continue;
+        // Extra validation for insert position
+        if (op === 'insert' && !VALID_INSERT_POSITIONS.has(item.position as string)) {
+            console.warn(`validateChangeOps: skipping op[${i}] (insert) — invalid position '${item.position}'`);
+            continue;
+        }
+        valid.push(item as unknown as ChangeOp);
     }
-    return $.html();
+    return valid;
 }
 
 /**
  * Parse a JSON change list from the model's raw response text.
  * Handles responses that may include markdown fences or extra text around the JSON.
+ * Invalid ops are logged as warnings and filtered out.
  */
 export function parseChangeList(response: string): ChangeList {
     // Try direct parse first
     try {
         const parsed = JSON.parse(response);
-        if (Array.isArray(parsed)) return parsed as ChangeList;
+        if (Array.isArray(parsed)) return validateChangeOps(parsed);
     } catch {
         // fall through to extraction
     }
@@ -644,7 +734,7 @@ export function parseChangeList(response: string): ChangeList {
     if (match) {
         try {
             const parsed = JSON.parse(match[0]);
-            if (Array.isArray(parsed)) return parsed as ChangeList;
+            if (Array.isArray(parsed)) return validateChangeOps(parsed);
         } catch {
             // fall through
         }
@@ -657,43 +747,55 @@ export function parseChangeList(response: string): ChangeList {
 // Prompt constants
 // ---------------------------------------------------------------------------
 
-export function getMessageFormat(productName: string): string {
-    return `<MESSAGE_FORMAT>
-<div class="chat-message"><p><strong>{${productName}: | User:}</strong> {message contents}</p></div>
-`;
-}
-
 export function getTransformInstr(productName: string): string {
     return `Apply the users <USER_MESSAGE> to the .viewerPanel of the <CURRENT_PAGE> by generating a list of changes in JSON format.
-Never remove any element that has a data-locked attribute. You may modfiy the inner text of a data-locked element or any of its unlocked child elements.
+Your response is a JSON object with two fields: "message" and "changes". The "message" field is REQUIRED on every response and must be a brief (1 sentence) message written directly to the user explaining what you did — it is shown in the chat feed as your reply. Do not describe the JSON; speak to the user (e.g. "Added a dark-mode toggle to the header."). The "changes" field is the array of change operations.
+Never remove any element that has a data-locked attribute. You may modify the inner text of a data-locked element or any of its unlocked child elements.
 
-If the <USER_MESSAGE> involves clearning the chat history, remove all .chat-message elements inside the #chatMessages container except for the first ${productName}: message. You may modify that message contents if requested.
-If there's no <USER_MESSAGE> add a ${productName}: message to the chat with aasking the user what they would like to do.
-If there is a <USER_MESSAGE> but the intent is unclear, add a User: message with the <USER_MESSAGE> to the chat and add a ${productName}: message asking the user for clarification on their intent.
-If there is a <USER_MESSAGE> with clear intent, add a User: message with the <USER_MESSAGE> to the chat and add a ${productName}: message explaining your change or answering their question.
-If a <USER_MESSAGE> is overly long, summarize the User: message.
+Your page runs inside an iframe. The chat panel, toolbar, and all shell chrome are in the parent frame — they are NOT part of your page HTML. Do not generate chat messages, chat-message divs, or any shell markup. Focus only on the page content inside .viewerPanel.
 
-When updating the .viewerPanel you may alse add/remove/update style blocks to the header unless they're data-locked. Use inline styles if you need to modify the .viewerPanel itself.
+When updating the .viewerPanel you may also add/remove/update style blocks in the head unless they're data-locked. Use inline styles if you need to modify the .viewerPanel itself.
 You may add/remove new script blocks to the body but all script & style blocks should have a unique id.
 You may modify the contents of a data-locked script block but may not remove it.
 
 Every <CURRENT_PAGE> has hidden data-locked "thoughts" and "instructions" divs.
-The instruction div, if pressent, contains custom <INSTRUCTIONS> for that page that should be followed in addition to these general instructions. You may modify the instructions div if needed (e.g. to add new instructions or update existing ones), but do not remove it. Add it if it's missing though.
+The instructions div, if present, contains custom <INSTRUCTIONS> for that page that should be followed in addition to these general instructions. You may modify the instructions div if needed (e.g. to add new instructions or update existing ones), but do not remove it. Add it if it's missing.
 The thoughts block is for your internal use only — you can write anything in there to help you reason through the user's request, but it is not visible to the user. You can also use it to keep track of any relevant state or information that may be useful across multiple turns.
 If the <USER_MESSAGE> indicates that a change didn't work, use your thoughts to diagnose the problem before fixing the issue.
+Your first operation should always be an update to your thoughts block, where you can reason through the user's request and plan your changes before applying them to the page.
 
-The <MESSAGE_FORMAT> section provides the HTML structure for chat messages in the chat panel. Use this format when generating new messages to ensure they display correctly.
-The <SERVER_APIS> section provides a list of available server APIs and helper functions you can call from injected scripts. You should use the synthos.* helper functions for any server API calls instead of raw fetch().
-The <SERVER_SCRIPTS> section provides a list of available scripts you can call from injected scripts. These are user-created scripts stored on the server that can be executed by calling synthos.scripts.run(id, variables).
-The <THEME> section provides details on the current theme's color scheme and shared shell classes to help you generate theme-aware pages that fit seamlessly into the user experience.
-The viewer panel can be resized by the user, so for animations, games, and presentations should always add the ",full-viewer" class to the viewer-panel element and ensure content stays centered and uses the maximum available space (use 100% width/height, flexbox centering, or viewport-relative sizing as appropriate).
-window.themeInfo is available and has a structure like this: { mode: 'light' | 'dark', colors: { primary: '#hex', secondary: '#hex', background: '#hex', text: '#hex', ... } }. Use these colors instead of hardcoded values to ensure your page works with the user's selected theme and any custom themes they may have. You can also use the shared shell classes defined in the theme info for consistent styling of common elements like the chat panel and header.
-
-Do not add duplicate script blocks with the same logic! Consolidate inline scrips if needed and double check that variables and functions are defined in the correct order.
+Patchable Data Convention — When a page stores editable metadata that should survive round-trips and be independently updatable, use data-* attributes on identifiable elements (elements with an id or a unique, stable CSS selector). This allows the patch API to update individual values without a full page re-render. Do NOT store patchable data as text content inside elements.
+Examples: data-notes on .slide elements (speaker notes), data-duration on .slide elements (slide timing), data-label on interactive elements (accessible names).
 
-Each element in the CURRENT_PAGE has a data-node-id attribute. Don't use the id attribute for targeting nodes (reserve it for scripts and styles) — use data-node-id.
+The <SERVER_APIS> section provides a list of available server APIs and helper functions you can call from injected scripts. You should use the synthos.* helper functions for any server API calls instead of raw fetch().
+The <SERVER_SCRIPTS> section provides a list of available scripts you can call from injected scripts. These are user-created scripts stored on the server that can be executed by calling synthos.script.run(id, variables).
+The <THEME> section provides details on the current theme's color scheme to help you generate theme-aware pages.
+The viewer panel can be resized by the user, so for animations, games, and presentations should always add the "full-viewer" class to the viewer-panel element and ensure content stays centered and uses the maximum available space (use 100% width/height, flexbox centering, or viewport-relative sizing as appropriate).
+window.themeInfo is available and has a structure like this: { mode: 'light' | 'dark', colors: { primary: '#hex', secondary: '#hex', background: '#hex', text: '#hex', ... } }. Use these colors instead of hardcoded values to ensure your page works with the user's selected theme and any custom themes they may have.
+
+Visual Design Guide — CRITICAL: Follow these rules exactly so pages look polished. Pages that ignore spacing rules look broken.
+- SPACING TOKENS: --spacingS2: 4px, --spacingS1: 8px, --spacingM: 16px, --spacingL1: 20px, --spacingL2: 32px.
+- PAGE HEADER: padding MUST be at least var(--spacingM) vertically and var(--spacingL1) horizontally (e.g. padding: var(--spacingM) var(--spacingL1)). Never use --spacingS1 for page header padding — it looks cramped.
+- CONTENT AREAS: Main content sections (tab panels, card bodies, scroll areas) MUST have at least padding: var(--spacingL1) (20px). Use var(--spacingL2) (32px) for primary page content padding when there is room.
+- SECTION GAPS: Leave at least var(--spacingL1) (20px) gap between major sections (header-to-tabs, tabs-to-content, between card groups). Use var(--spacingM) (16px) minimum between related items within a section.
+- CARD/PANEL PADDING: Cards and panels MUST have at least padding: var(--spacingM) (16px) inside. Use var(--spacingL1) for larger content cards.
+- TAB BARS (flm-pivot): Tab container should have padding: var(--spacingM) var(--spacingL1) — never --spacingS1 which makes tabs look squished.
+- TYPOGRAPHY HIERARCHY: Use FluentLM text classes — flm-text--xxLarge or flm-text--xLarge + flm-text--semibold for page titles, flm-text--large for section headings, flm-text (default 14px) for body, flm-text--small + flm-text--secondary for captions. Always apply flm-text--block on block-level text.
+- SURFACES & CARDS: Use theme color variables only: background var(--white) with border 1px solid var(--neutralLight), or box-shadow var(--elevation4) for elevated cards. Section backgrounds: var(--neutralLighterAlt). NEVER use custom variables like --bg-secondary, --border-color, --text-primary — these do not exist. Always use the real theme variables: --white, --black, --neutralLight, --neutralLighter, --neutralLighterAlt, --neutralPrimary, --neutralSecondary, --themePrimary, --themeLight, --themeLighter, --themeLighterAlt, --themeDark, --themeDarker.
+- ELEVATION: var(--elevation4) for cards, var(--elevation8) for dropdowns, var(--elevation16) for modals.
+- BORDER RADIUS: 4px on containers, 2px on badges/chips, 4px on buttons.
+- DATA TABLES: Headers: background var(--neutralLighterAlt), font-weight 600, padding var(--spacingS1) var(--spacingM). Rows: border-bottom 1px solid var(--neutralLight), cell padding var(--spacingS1) var(--spacingM).
+- LAYOUT: Use flm-stack / flm-stack--horizontal with gap via spacing tokens. CSS grid with gap: var(--spacingM). Use max-width on wide layouts.
+- VISUAL WEIGHT: var(--themePrimary) for interactive elements only, not large backgrounds. var(--neutralPrimary) for body text, var(--neutralSecondary) for secondary text.
+- EMPTY STATES: Center the message vertically and horizontally with an icon. Add generous padding (at least var(--spacingL2)) around empty state messages.
+
+Do not add duplicate script blocks with the same logic! Consolidate inline scripts if needed and double check that variables and functions are defined in the correct order.
+Prefer a single inline <script> block for all of your page's JavaScript. If you must split logic across two blocks, that's acceptable, but one is strongly preferred.
+Inline <script> blocks on your page are automatically wrapped in an IIFE (except scripts with src, data-locked scripts, or scripts already wrapped in (function(){ ... })()). This means top-level \`function\`, \`const\`, \`let\`, and \`var\` declarations inside a script are LOCAL to that script and cannot be called from another script. Put functions that need to call each other in the same <script> block, or explicitly attach them to \`window\` (e.g. \`window.myFunc = function(){...}\`) if they must be shared across blocks.
+Place all <script> blocks at the end of <body>, never in <head> — scripts in <head> run before the DOM is parsed and will crash if they reference body elements.
+
+Each element in the CURRENT_PAGE has a data-nid attribute. Don't use the id attribute for targeting nodes (reserve it for scripts and styles) — use data-nid.
 If you're trying to assign an id to script or style block, use "replace" not "update".
-Your first operation should always be an update to your thoughts block, where you can reason through the user's request and plan your changes before applying them to the page.
 
 CRITICAL — FluentLM components: If a <FLUENTLM_COMPONENTS> section is present, you MUST use those components for all standard UI elements (buttons, inputs, selects, dialogs, tabs, cards, toggles, etc.). Never create custom CSS classes for UI controls that have a FluentLM equivalent. Refer to <FLUENTLM_COMPONENTS> for the exact class names and markup patterns.`;
 }
@@ -702,19 +804,19 @@ export const AGENT_API_REFERENCE =
 `## Agent API
 
 Check availability first (required):
-  const agents = await synthos.agents.list({ enabled: true });
+  const agents = await synthos.agent.list({ enabled: true });
 
 Send a message (returns full response):
-  const result = await synthos.agents.send(agentId, message);
+  const result = await synthos.agent.send(agentId, message);
   // result: { kind: 'message', text: 'response text', raw: {...} }
 
 Send with file/image attachments:
-  const result = await synthos.agents.send(agentId, message, [
+  const result = await synthos.agent.send(agentId, message, [
     { fileName: 'photo.jpg', mimeType: 'image/jpeg', content: '<base64-string>' }
   ]);
 
 Stream a response (token-by-token deltas):
-  const handle = synthos.agents.sendStream(agentId, message, function(event) {
+  const handle = synthos.agent.sendStream(agentId, message, function(event) {
     switch (event.kind) {
       case 'text':   // event.data = text delta string — append to output
       case 'status': // event.data = status info object
@@ -725,11 +827,11 @@ Stream a response (token-by-token deltas):
   handle.close(); // call to abort the stream early
 
 Stream with attachments:
-  synthos.agents.sendStream(agentId, message, onEvent, [
+  synthos.agent.sendStream(agentId, message, onEvent, [
     { fileName: 'doc.pdf', mimeType: 'application/pdf', content: '<base64>' }
   ]);
 
-IMPORTANT: Always check synthos.agents.list({ enabled: true }) before calling an agent.
+IMPORTANT: Always check synthos.agent.list({ enabled: true }) before calling an agent.
 If no agents are configured, show the user a link to Settings > Agents (/settings?tab=agents).`;
 
 // ---------------------------------------------------------------------------
@@ -767,12 +869,19 @@ request: { prompt: string, shape: 'square' | 'portrait' | 'landscape', style: 'v
 response: { url: string }
 
 POST /api/generate/completion
-description: Generates a text completion based on a prompt
-request: { prompt: string, temperature?: number }
-response: { answer: string, explanation: string }
+description: Generates a completion based on a prompt. When \`schema\` is provided, the model is constrained to emit JSON conforming to it (structured output) and the parsed object is returned directly. Without \`schema\`, returns plain text.
+request: { prompt: string, temperature?: number, schema?: object (JSON schema) }
+response (no schema): { answer: string }
+response (with schema): the parsed JSON object matching \`schema\` (e.g. \`{ items: [...] }\`)
+
+Schema notes:
+  - Use this when you need structured data — never tell the model "return JSON with these fields" via the prompt and parse \`answer\`.
+  - Top-level schema must be \`type: 'object'\`. To return a list, wrap it: \`{ type: 'object', additionalProperties: false, required: ['items'], properties: { items: { type: 'array', items: {...} } } }\`.
+  - Every nested \`type: 'object'\` MUST set \`additionalProperties: false\` — Anthropic structured-output rejects schemas that omit it.
+  - Mark every required field in \`required: [...]\` so the model is forced to emit them.
 
-  synthos.generate.image({ prompt, shape, style })       — POST /api/generate/image
-  synthos.generate.completion({ prompt, temperature? })  — POST /api/generate/completion`],
+  synthos.generate.image({ prompt, shape, style })                  — POST /api/generate/image
+  synthos.generate.completion({ prompt, temperature?, schema? })    — POST /api/generate/completion`],
 
     ['pages', `GET /api/pages
 description: Retrieve a list of all pages with metadata
@@ -796,18 +905,18 @@ description: Ask a question about a page with full HTML context
 request: { question: string }
 response: { answer: string }
 
-  synthos.pages.list()                  — GET /api/pages
-  synthos.pages.get(name)               — GET /api/pages/:name
-  synthos.pages.update(name, metadata)  — POST /api/pages/:name
-  synthos.pages.remove(name)            — DELETE /api/pages/:name
-  synthos.pages.ask(name, question)     — POST /api/pages/:name/ask`],
+  synthos.page.list()                   — GET /api/pages
+  synthos.page.get(name)                — GET /api/pages/:name
+  synthos.page.update(name, metadata)   — POST /api/pages/:name
+  synthos.page.remove(name)             — DELETE /api/pages/:name
+  synthos.page.ask(name, question)      — POST /api/pages/:name/ask`],
 
     ['scripts', `POST /api/scripts/:id
 description: Execute a script with the passed in variables
 request: { [key: string]: string }
 response: string
 
-  synthos.scripts.run(id, variables)    — POST /api/scripts/:id`],
+  synthos.script.run(id, variables)     — POST /api/scripts/:id`],
 
     ['search', `POST /api/search/web
 description: Search the web using Brave Search (must be enabled in Settings > Connectors)
@@ -830,11 +939,11 @@ description: Send a message and receive a streaming SSE response (text/event-str
 request: { message: string, attachments?: [{ fileName: string, mimeType: string, content: string }] }
 response: SSE stream
 
-  synthos.agents.list(opts?)             — GET /api/agents  (returns configured agents; opts: { enabled?, provider? }; returns [{ id, name, description, url, enabled, provider, capabilities }])
-  synthos.agents.send(agentId, message, attachments?) — POST /api/agents/:id/send  (sends a text message to any agent, returns normalized { kind, text, raw }; attachments: [{ fileName, mimeType, content }])
-  synthos.agents.sendStream(agentId, message, onEvent, attachments?) — POST /api/agents/:id/stream  (SSE streaming; onEvent receives { kind, data }; returns { close() } handle; attachments: [{ fileName, mimeType, content }])
-  synthos.agents.isEnabled(agentId)     — checks if an agent is enabled (returns Promise<boolean>)
-  synthos.agents.getCapabilities(agentId) — returns agent capabilities object (streaming, skills, etc.)`],
+  synthos.agent.list(opts?)              — GET /api/agents  (returns configured agents; opts: { enabled?, provider? }; returns [{ id, name, description, url, enabled, provider, capabilities }])
+  synthos.agent.send(agentId, message, attachments?) — POST /api/agents/:id/send  (sends a text message to any agent, returns normalized { kind, text, raw }; attachments: [{ fileName, mimeType, content }])
+  synthos.agent.sendStream(agentId, message, onEvent, attachments?) — POST /api/agents/:id/stream  (SSE streaming; onEvent receives { kind, data }; returns { close() } handle; attachments: [{ fileName, mimeType, content }])
+  synthos.agent.isEnabled(agentId)      — checks if an agent is enabled (returns Promise<boolean>)
+  synthos.agent.getCapabilities(agentId) — returns agent capabilities object (streaming, skills, etc.)`],
 
     ['connectors', `GET /api/connectors
 description: List available connectors (REST API proxies). Supports ?category=X and ?id=X filters.
@@ -849,8 +958,8 @@ description: Proxy a request through a configured connector. The connector attac
 request: { connector: string, method: string, path: string, headers?: object, body?: any, query?: object }
 response: Upstream API response (JSON or text)
 
-  synthos.connectors.call(connector, method, path, opts?) — POST /api/connectors  (proxy call; opts: { headers?, body?, query? })
-  synthos.connectors.list(opts?)        — GET /api/connectors  (opts: { category?, id? })`],
+  synthos.connector.call(connector, method, path, opts?) — POST /api/connectors  (proxy call; opts: { headers?, body?, query? })
+  synthos.connector.list(opts?)         — GET /api/connectors  (opts: { category?, id? })`],
 
     ['files', `GET /api/files/:page
 description: List files stored for a page (with sizes)
@@ -973,9 +1082,10 @@ request: { prompt: string, shape: 'square' | 'portrait' | 'landscape', style: 'v
 response: { url: string }
 
 POST /api/generate/completion
-description: Generates a text completion based on a prompt
-request: { prompt: string, temperature?: number }
-response: { answer: string, explanation: string }
+description: Generates a completion based on a prompt. When \`schema\` is provided, the model is constrained to emit JSON conforming to it and the parsed object is returned directly.
+request: { prompt: string, temperature?: number, schema?: object (JSON schema) }
+response (no schema): { answer: string }
+response (with schema): the parsed JSON object matching \`schema\`. Top-level must be \`type: 'object'\`; every nested object MUST set \`additionalProperties: false\`.
 
 GET /api/pages
 description: Retrieve a list of all pages with metadata
@@ -1041,20 +1151,20 @@ PAGE HELPERS (available globally as window.synthos):
   synthos.data.get(table, id)           — GET /api/data/:page/:table/:id  (auto-scoped to current page)
   synthos.data.save(table, row)         — POST /api/data/:page/:table  (auto-scoped to current page)
   synthos.data.remove(table, id)        — DELETE /api/data/:page/:table/:id  (auto-scoped to current page)
-  synthos.generate.image({ prompt, shape, style })       — POST /api/generate/image
-  synthos.generate.completion({ prompt, temperature? })  — POST /api/generate/completion
-  synthos.scripts.run(id, variables)    — POST /api/scripts/:id
-  synthos.pages.list()                  — GET /api/pages
-  synthos.pages.get(name)               — GET /api/pages/:name
-  synthos.pages.update(name, metadata)  — POST /api/pages/:name
-  synthos.pages.remove(name)            — DELETE /api/pages/:name
-  synthos.pages.ask(name, question)     — POST /api/pages/:name/ask
+  synthos.generate.image({ prompt, shape, style })                  — POST /api/generate/image
+  synthos.generate.completion({ prompt, temperature?, schema? })    — POST /api/generate/completion  (schema: optional JSON schema for structured output; returns parsed object)
+  synthos.script.run(id, variables)     — POST /api/scripts/:id
+  synthos.page.list()                   — GET /api/pages
+  synthos.page.get(name)                — GET /api/pages/:name
+  synthos.page.update(name, metadata)   — POST /api/pages/:name
+  synthos.page.remove(name)             — DELETE /api/pages/:name
+  synthos.page.ask(name, question)      — POST /api/pages/:name/ask
   synthos.search.web(query, opts?)      — POST /api/search/web  (opts: { count?, country?, freshness? })
-  synthos.connectors.call(connector, method, path, opts?) — POST /api/connectors  (proxy call; opts: { headers?, body?, query? })
-  synthos.connectors.list(opts?)        — GET /api/connectors  (opts: { category?, id? })
-  synthos.agents.list(opts?)             — GET /api/agents  (returns configured agents; opts: { enabled?, provider? }; returns [{ id, name, description, url, enabled, provider, capabilities }])
-  synthos.agents.send(agentId, message, attachments?) — POST /api/agents/:id/send  (sends a text message to any agent, returns normalized { kind, text, raw }; attachments: [{ fileName, mimeType, content }])
-  synthos.agents.sendStream(agentId, message, onEvent, attachments?) — POST /api/agents/:id/stream  (SSE streaming; onEvent receives { kind, data }; returns { close() } handle; attachments: [{ fileName, mimeType, content }])
-  synthos.agents.isEnabled(agentId)     — checks if an agent is enabled (returns Promise<boolean>)
-  synthos.agents.getCapabilities(agentId) — returns agent capabilities object (streaming, skills, etc.)
+  synthos.connector.call(connector, method, path, opts?) — POST /api/connectors  (proxy call; opts: { headers?, body?, query? })
+  synthos.connector.list(opts?)         — GET /api/connectors  (opts: { category?, id? })
+  synthos.agent.list(opts?)              — GET /api/agents  (returns configured agents; opts: { enabled?, provider? }; returns [{ id, name, description, url, enabled, provider, capabilities }])
+  synthos.agent.send(agentId, message, attachments?) — POST /api/agents/:id/send  (sends a text message to any agent, returns normalized { kind, text, raw }; attachments: [{ fileName, mimeType, content }])
+  synthos.agent.sendStream(agentId, message, onEvent, attachments?) — POST /api/agents/:id/stream  (SSE streaming; onEvent receives { kind, data }; returns { close() } handle; attachments: [{ fileName, mimeType, content }])
+  synthos.agent.isEnabled(agentId)      — checks if an agent is enabled (returns Promise<boolean>)
+  synthos.agent.getCapabilities(agentId) — returns agent capabilities object (streaming, skills, etc.)
 All methods return Promises. Prefer these helpers over raw fetch().`;