@compilr-dev/sdk 0.17.2 → 0.17.3

package/dist/platform/tools/canvas-tools.d.ts

@@ -1,7 +1,9 @@
 /**
  * Canvas Tools — agent authoring + management of visual canvases.
  *
- * 4 tools: canvas_write (create/update), canvas_list, canvas_get, canvas_delete.
+ * 5 tools: canvas_write (create/full replace), canvas_edit (server-side
+ * str_replace/append/prepend — the token-cheap edit path), canvas_list,
+ * canvas_get (targeted read: outline / line slice), canvas_delete.
  *
  * `content` is the agent's raw HTML/SVG; the host renderer injects the CSP +
  * bridge and renders it in a sandboxed iframe. `controls` is the optional Tweaks
@@ -19,4 +21,14 @@ export declare function createCanvasTools(config: PlatformToolsConfig): (import(
     project_id?: number;
 }> | import("@compilr-dev/agents").Tool<{
     canvas_id: number;
+    outline?: boolean;
+    startLine?: number;
+    maxLines?: number;
+}> | import("@compilr-dev/agents").Tool<{
+    canvas_id: number;
+    operation: "str_replace" | "append" | "prepend";
+    old_str?: string;
+    new_str?: string;
+    content?: string;
+    replace_all?: boolean;
 }>)[];

package/dist/platform/tools/canvas-tools.js

@@ -1,7 +1,9 @@
 /**
  * Canvas Tools — agent authoring + management of visual canvases.
  *
- * 4 tools: canvas_write (create/update), canvas_list, canvas_get, canvas_delete.
+ * 5 tools: canvas_write (create/full replace), canvas_edit (server-side
+ * str_replace/append/prepend — the token-cheap edit path), canvas_list,
+ * canvas_get (targeted read: outline / line slice), canvas_delete.
  *
  * `content` is the agent's raw HTML/SVG; the host renderer injects the CSP +
  * bridge and renders it in a sandboxed iframe. `controls` is the optional Tweaks
@@ -13,6 +15,43 @@ import { truncateContent } from './truncate.js';
 import { seedValues } from '../../canvas/types.js';
 import { validateControlManifest } from '../../canvas/validate.js';
 const CANVAS_TYPES = ['infographic', 'carousel', 'board'];
+/** Render content as numbered lines (1-based), optionally a slice. */
+function numberedLines(content, startLine, maxLines) {
+    const lines = content.split('\n');
+    const start = Math.max(1, startLine ?? 1);
+    const end = maxLines ? Math.min(lines.length, start - 1 + maxLines) : lines.length;
+    const out = [];
+    for (let i = start; i <= end; i++)
+        out.push(`${String(i)}\t${lines[i - 1]}`);
+    return out.join('\n');
+}
+/**
+ * Lightweight HTML skeleton: lines carrying an id/class on a structural tag, with
+ * line numbers — enough for the agent to locate an anchor for a str_replace edit
+ * without pulling the whole document.
+ */
+function htmlOutline(content) {
+    const lines = content.split('\n');
+    const rows = [];
+    const re = /<(section|div|header|nav|main|footer|aside|article|button|form|ul|ol|table|h[1-6])\b[^>]*\b(id|class)=/i;
+    lines.forEach((line, i) => {
+        if (re.test(line))
+            rows.push(`${String(i + 1)}\t${line.trim().slice(0, 100)}`);
+    });
+    return rows.length ? rows.join('\n') : '(no structural elements with id/class found)';
+}
+/** Count non-overlapping occurrences of needle in haystack. */
+function countOccurrences(haystack, needle) {
+    if (!needle)
+        return 0;
+    let count = 0;
+    let idx = haystack.indexOf(needle);
+    while (idx !== -1) {
+        count++;
+        idx = haystack.indexOf(needle, idx + needle.length);
+    }
+    return count;
+}
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 export function createCanvasTools(config) {
     const ctx = config.context;
@@ -29,7 +68,8 @@ export function createCanvasTools(config) {
             'each control is { type: slider|number|toggle|select|color|text, param, label, default, ...type config }. ' +
             'Bind params in your HTML via CSS custom properties var(--param), [data-bind="param"] text, and ' +
             '[data-show="param"] visibility; for computed updates define window.applyParams(values) in a <script>. ' +
-            'Pass canvas_id to update an existing canvas; omit it to create a new one.',
+            'Omit canvas_id to create. To EDIT an existing canvas, prefer canvas_edit (str_replace) — it avoids ' +
+            're-sending the whole document; only use canvas_write with canvas_id for a full intentional replace.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -139,11 +179,22 @@ export function createCanvasTools(config) {
     // ---------------------------------------------------------------------------
     const canvasGetTool = defineTool({
         name: 'canvas_get',
-        description: 'Get a canvas by id, including its content, controls manifest, and current values.',
+        description: 'Get a canvas by id. Content is returned with line numbers. For large canvases, ' +
+            'use outline=true to see the element skeleton, or startLine/maxLines to read a slice — ' +
+            'then edit with canvas_edit (str_replace) instead of re-sending the whole document.',
         inputSchema: {
             type: 'object',
             properties: {
                 canvas_id: { type: 'number', description: 'Canvas id.' },
+                outline: {
+                    type: 'boolean',
+                    description: 'If true, return only the structural skeleton (elements with id/class + line numbers).',
+                },
+                startLine: {
+                    type: 'number',
+                    description: 'First line to read (1-based). Use with maxLines.',
+                },
+                maxLines: { type: 'number', description: 'Max number of lines to read from startLine.' },
             },
             required: ['canvas_id'],
         },
@@ -152,13 +203,23 @@ export function createCanvasTools(config) {
                 const c = await canvases.getById(input.canvas_id);
                 if (!c)
                     return createErrorResult(`Canvas ${String(input.canvas_id)} not found.`);
+                const totalLines = c.content.split('\n').length;
+                const header = `Canvas "${c.title}" (${c.type})\n` +
+                    `ID: ${String(c.id)}  |  Controls: ${String(c.controls.controls.length)}  |  Lines: ${String(totalLines)}\n\n`;
+                if (input.outline) {
+                    return createSuccessResult(`${header}--- outline ---\n${htmlOutline(c.content)}`);
+                }
+                if (input.startLine !== undefined || input.maxLines !== undefined) {
+                    return createSuccessResult(`${header}--- content (lines ${String(input.startLine ?? 1)}+) ---\n` +
+                        numberedLines(c.content, input.startLine, input.maxLines));
+                }
+                // Full content, numbered. Truncate very large docs with an accurate hint.
                 const tc = truncateContent(c.content);
-                const output = `Canvas "${c.title}" (${c.type})\n` +
-                    `ID: ${String(c.id)}\n` +
-                    `Controls: ${String(c.controls.controls.length)}\n\n` +
-                    `--- content ---\n` +
-                    tc.content;
-                return createSuccessResult(output);
+                if (tc.truncated) {
+                    return createSuccessResult(`${header}--- content (truncated; use outline=true or startLine/maxLines) ---\n` +
+                        numberedLines(c.content, 1, 200));
+                }
+                return createSuccessResult(`${header}--- content ---\n${numberedLines(c.content)}`);
             }
             catch (error) {
                 return createErrorResult(`Failed to get canvas: ${error instanceof Error ? error.message : String(error)}`);
@@ -166,6 +227,85 @@ export function createCanvasTools(config) {
         },
     });
     // ---------------------------------------------------------------------------
+    // canvas_edit — server-side edit; only the change goes through context
+    // ---------------------------------------------------------------------------
+    const canvasEditTool = defineTool({
+        name: 'canvas_edit',
+        description: 'Edit an existing canvas WITHOUT re-sending its full HTML — prefer this over canvas_write for edits. ' +
+            'The stored content is read and modified server-side; only your small change goes through context. ' +
+            'operation=str_replace finds an exact snippet (old_str) and replaces it with new_str (old_str must be ' +
+            'unique unless replace_all=true); append/prepend add content at the end/start. Use canvas_get ' +
+            '(outline or a line slice) first to find the exact snippet to replace.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                canvas_id: { type: 'number', description: 'Canvas id to edit.' },
+                operation: {
+                    type: 'string',
+                    enum: ['str_replace', 'append', 'prepend'],
+                    description: 'str_replace: swap an exact snippet. append/prepend: add content at end/start.',
+                },
+                old_str: {
+                    type: 'string',
+                    description: 'For str_replace: the exact existing snippet to find (include enough surrounding text to be unique).',
+                },
+                new_str: {
+                    type: 'string',
+                    description: 'For str_replace: the replacement snippet.',
+                },
+                content: {
+                    type: 'string',
+                    description: 'For append/prepend: the content to add.',
+                },
+                replace_all: {
+                    type: 'boolean',
+                    description: 'For str_replace: replace every occurrence instead of requiring old_str to be unique.',
+                },
+            },
+            required: ['canvas_id', 'operation'],
+        },
+        execute: async (input) => {
+            try {
+                const c = await canvases.getById(input.canvas_id);
+                if (!c)
+                    return createErrorResult(`Canvas ${String(input.canvas_id)} not found.`);
+                let next;
+                let summary;
+                if (input.operation === 'str_replace') {
+                    if (input.old_str === undefined || input.new_str === undefined) {
+                        return createErrorResult('str_replace requires both old_str and new_str.');
+                    }
+                    const occurrences = countOccurrences(c.content, input.old_str);
+                    if (occurrences === 0) {
+                        return createErrorResult('old_str not found in the canvas content. Use canvas_get to see the exact text.');
+                    }
+                    if (occurrences > 1 && !input.replace_all) {
+                        return createErrorResult(`old_str is not unique (${String(occurrences)} matches). Add surrounding context, or set replace_all=true.`);
+                    }
+                    next = input.replace_all
+                        ? c.content.split(input.old_str).join(input.new_str)
+                        : c.content.replace(input.old_str, input.new_str);
+                    summary = `Replaced ${String(input.replace_all ? occurrences : 1)} occurrence(s).`;
+                }
+                else {
+                    if (input.content === undefined) {
+                        return createErrorResult(`${input.operation} requires content.`);
+                    }
+                    next =
+                        input.operation === 'append' ? c.content + input.content : input.content + c.content;
+                    summary = `${input.operation === 'append' ? 'Appended' : 'Prepended'} ${String(input.content.length)} chars.`;
+                }
+                const updated = await canvases.update(input.canvas_id, { content: next });
+                if (!updated)
+                    return createErrorResult(`Canvas ${String(input.canvas_id)} not found.`);
+                return createSuccessResult(`Edited canvas "${updated.title}" (${updated.type}). ${summary} Now ${String(next.split('\n').length)} lines.`);
+            }
+            catch (error) {
+                return createErrorResult(`Failed to edit canvas: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
     // canvas_delete
     // ---------------------------------------------------------------------------
     const canvasDeleteTool = defineTool({
@@ -190,5 +330,5 @@ export function createCanvasTools(config) {
             }
         },
     });
-    return [canvasWriteTool, canvasListTool, canvasGetTool, canvasDeleteTool];
+    return [canvasWriteTool, canvasEditTool, canvasListTool, canvasGetTool, canvasDeleteTool];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",