@elixpo/lixsketch 5.6.2 → 5.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elixpo/lixsketch",
-  "version": "5.6.2",
+  "version": "5.6.4",
   "description": "Open-source SVG whiteboard engine + React canvas component with hand-drawn aesthetics — the core of LixSketch",
   "type": "module",
   "main": "src/index.js",
@@ -48,6 +48,9 @@
     "url": "https://github.com/elixpo"
   },
   "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "homepage": "https://sketch.elixpo.com",
   "repository": {
     "type": "git",

package/src/mcp/index.js

@@ -1,5 +1,7 @@
 export { createLixSketchMcpServer, LixSketchMcpServer, LIXSKETCH_MCP_PROTOCOL_VERSION, LIXSKETCH_MCP_TOOLS } from './server.js';
 export { MemorySceneStore } from './store.js';
+export { RemoteSceneStore, decryptRemoteScene, encryptRemoteScene } from './remoteStore.js';
+export { compileLixScript } from './lixscript.js';
 export { MarketplaceTemplateProvider, decryptPublicTemplate } from './templates.js';
 export { applyScenePatch, createEmptyScene, getSceneBounds, getSceneSummary, mergeTemplateScene, normalizeShape, validateScene, MCP_LIMITS } from './scene.js';
 export { renderSceneSvg } from './preview.js';

package/src/mcp/lixscript.js

@@ -0,0 +1,93 @@
+import { parseLixScript, resolveShapeRefs } from '../core/LixScriptParser.js';
+
+const MAX_SOURCE_LENGTH = 100_000;
+
+function options(def) {
+  return {
+    stroke: def.props.stroke || def.props.color || '#8b76d6',
+    strokeWidth: Number(def.props.strokeWidth) || 2,
+    fill: def.props.fill || 'transparent',
+    fillStyle: def.props.fillStyle || 'solid',
+    roughness: def.props.roughness === undefined ? 1.2 : Number(def.props.roughness),
+    opacity: def.props.opacity === undefined ? 1 : Number(def.props.opacity),
+  };
+}
+
+function bounds(def) {
+  const width = Number(def.width) || (def.type === 'frame' ? 600 : def.type === 'rect' ? 160 : 80);
+  const height = Number(def.height) || (def.type === 'frame' ? 400 : def.type === 'rect' ? 60 : 80);
+  return { x: Number(def.x) || 0, y: Number(def.y) || 0, width, height };
+}
+
+function endpoint(point, definitions) {
+  if (Number.isFinite(point?.x) && Number.isFinite(point?.y)) return { x: point.x, y: point.y };
+  const target = definitions.get(point?.ref);
+  if (!target) throw new Error(`Cannot resolve LixScript connection target "${point?.ref || ''}"`);
+  const box = bounds(target);
+  const offset = Number(point.offset) || 0;
+  const side = point.side || 'center';
+  if (side === 'top') return { x: box.x + box.width / 2 + offset, y: box.y };
+  if (side === 'bottom') return { x: box.x + box.width / 2 + offset, y: box.y + box.height };
+  if (side === 'left') return { x: box.x, y: box.y + box.height / 2 + offset };
+  if (side === 'right') return { x: box.x + box.width, y: box.y + box.height / 2 + offset };
+  return { x: box.x + box.width / 2 + offset, y: box.y + box.height / 2 };
+}
+
+function labelShape(def, shapeID, parentFrame) {
+  if (!def.props.label) return null;
+  const box = bounds(def);
+  return {
+    type: 'text', shapeID: `${shapeID}-label`, x: box.x + box.width / 2, y: box.y + box.height / 2,
+    text: String(def.props.label), fontSize: Number(def.props.labelFontSize) || 14,
+    color: def.props.labelColor || '#e8e3f3', parentFrame,
+  };
+}
+
+export function compileLixScript(source, { x = 0, y = 0 } = {}) {
+  const input = String(source || '');
+  if (!input.trim()) throw new Error('LixScript source is required');
+  if (input.length > MAX_SOURCE_LENGTH) throw new Error('LixScript source exceeds 100 KB');
+  const parsed = parseLixScript(input);
+  if (parsed.errors.length) throw new Error(`LixScript parse failed: ${parsed.errors.map((entry) => `line ${entry.line}: ${entry.message}`).join('; ')}`);
+  resolveShapeRefs(parsed.shapes);
+  const prefix = `lix-${crypto.randomUUID().slice(0, 8)}`;
+  const shapeId = (id) => `${prefix}-${id}`;
+  const definitions = new Map(parsed.shapes.map((shape) => [shape.id, shape]));
+  const frame = parsed.shapes.find((shape) => shape.type === 'frame');
+  const frameId = frame ? shapeId(frame.id) : `${prefix}-frame`;
+  const frameMembers = frame?.props.contains ? new Set(String(frame.props.contains).split(',').map((value) => value.trim()).filter(Boolean)) : null;
+  const shapes = [];
+  for (const def of parsed.shapes) {
+    const box = bounds(def);
+    const parentFrame = def === frame || (frameMembers && !frameMembers.has(def.id)) ? null : frameId;
+    let shape;
+    const id = shapeId(def.id);
+    if (def.type === 'rect') shape = { type: 'rectangle', shapeID: id, x: box.x + x, y: box.y + y, width: box.width, height: box.height, rotation: Number(def.props.rotation) || 0, options: options(def), parentFrame };
+    else if (def.type === 'circle' || def.type === 'ellipse') shape = { type: 'circle', shapeID: id, x: box.x + box.width / 2 + x, y: box.y + box.height / 2 + y, rx: box.width / 2, ry: box.height / 2, rotation: Number(def.props.rotation) || 0, options: options(def), parentFrame };
+    else if (def.type === 'text') shape = { type: 'text', shapeID: id, x: box.x + x, y: box.y + y, text: String(def.props.content || def.props.text || 'Text'), fontSize: Number(def.props.fontSize) || 16, color: def.props.color || def.props.fill || '#e8e3f3', fontFamily: def.props.fontFamily || 'lixFont', parentFrame };
+    else if (def.type === 'frame') shape = { type: 'frame', shapeID: id, x: box.x + x, y: box.y + y, width: box.width, height: box.height, frameName: String(def.props.frameName || def.props.name || def.id), fillStyle: def.props.fillStyle || 'transparent', fillColor: def.props.fillColor || def.props.fill || '#1e1e28', options: options(def) };
+    else if (def.type === 'freehand') {
+      const points = String(def.props.points || '').split(';').map((value) => value.split(',').map(Number)).filter((point) => point.length >= 2 && point.every(Number.isFinite)).map(([px, py, pressure = 0.5]) => [px + x, py + y, pressure]);
+      shape = { type: 'freehandStroke', shapeID: id, points, options: options(def), parentFrame };
+    } else if (def.type === 'line' || def.type === 'arrow') {
+      const startPoint = endpoint(def.from, definitions), endPoint = endpoint(def.to, definitions);
+      startPoint.x += x; startPoint.y += y; endPoint.x += x; endPoint.y += y;
+      shape = def.type === 'line'
+        ? { type: 'line', shapeID: id, startPoint, endPoint, isCurved: def.props.curve === true || def.props.curve === 'true', options: options(def), parentFrame }
+        : { type: 'arrow', shapeID: id, startPoint, endPoint, arrowHeadStyle: def.props.head || 'triangle', arrowOutlineStyle: def.props.style || 'solid', arrowCurved: def.props.curve && def.props.curve !== 'straight', arrowCurveAmount: Number(def.props.curveAmount) || 0.2, options: options(def), parentFrame };
+    } else throw new Error(`LixScript ${def.type} is not writable through MCP`);
+    shapes.push(shape);
+    const label = labelShape(def, id, parentFrame);
+    if (label) { label.x += x; label.y += y; shapes.push(label); }
+  }
+  if (!frame && shapes.length) {
+    const boxes = parsed.shapes.filter((def) => !['arrow', 'line'].includes(def.type)).map(bounds);
+    const pointShapes = shapes.filter((shape) => shape.startPoint && shape.endPoint);
+    const minX = boxes.length ? Math.min(...boxes.map((box) => box.x)) + x : Math.min(...pointShapes.flatMap((shape) => [shape.startPoint.x, shape.endPoint.x]));
+    const minY = boxes.length ? Math.min(...boxes.map((box) => box.y)) + y : Math.min(...pointShapes.flatMap((shape) => [shape.startPoint.y, shape.endPoint.y]));
+    const maxX = boxes.length ? Math.max(...boxes.map((box) => box.x + box.width)) + x : Math.max(...pointShapes.flatMap((shape) => [shape.startPoint.x, shape.endPoint.x]));
+    const maxY = boxes.length ? Math.max(...boxes.map((box) => box.y + box.height)) + y : Math.max(...pointShapes.flatMap((shape) => [shape.startPoint.y, shape.endPoint.y]));
+    shapes.unshift({ type: 'frame', shapeID: frameId, x: minX - 40, y: minY - 40, width: Math.max(80, maxX - minX + 80), height: Math.max(80, maxY - minY + 80), frameName: 'LixScript', fillStyle: 'transparent', fillColor: '#1e1e28' });
+  }
+  return { shapes, operations: shapes.map((shape) => ({ op: 'add', shape })), sourceShapeCount: parsed.shapes.length };
+}

package/src/mcp/remoteStore.js

@@ -0,0 +1,99 @@
+import { validateScene } from './scene.js';
+
+function decodeBase64Url(value) {
+  const base64 = String(value).replaceAll('-', '+').replaceAll('_', '/');
+  const padded = base64 + '='.repeat((4 - base64.length % 4) % 4);
+  const binary = atob(padded);
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+
+function encodeBase64Url(bytes) {
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+}
+
+async function importWorkspaceKey(keyValue, usages) {
+  const bytes = decodeBase64Url(keyValue);
+  if (bytes.byteLength !== 32) throw new Error('The workspace encryption key is not AES-256');
+  return crypto.subtle.importKey('raw', bytes, { name: 'AES-GCM', length: 256 }, false, usages);
+}
+
+export async function decryptRemoteScene(ciphertext, keyValue) {
+  const combined = decodeBase64Url(ciphertext);
+  if (combined.byteLength < 28) throw new Error('The encrypted workspace payload is invalid');
+  const key = await importWorkspaceKey(keyValue, ['decrypt']);
+  const plaintext = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: combined.slice(0, 12) }, key, combined.slice(12));
+  return JSON.parse(new TextDecoder().decode(plaintext));
+}
+
+export async function encryptRemoteScene(scene, keyValue) {
+  const key = await importWorkspaceKey(keyValue, ['encrypt']);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const plaintext = new TextEncoder().encode(JSON.stringify(scene));
+  const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, plaintext));
+  const combined = new Uint8Array(iv.byteLength + ciphertext.byteLength);
+  combined.set(iv);
+  combined.set(ciphertext, iv.byteLength);
+  return encodeBase64Url(combined);
+}
+
+export class RemoteSceneStore {
+  constructor({ baseUrl = 'https://sketch.elixpo.com', workspaceId, token, encryptionKey, fetchImpl = globalThis.fetch } = {}) {
+    if (!workspaceId) throw new Error('RemoteSceneStore requires workspaceId');
+    if (!token) throw new Error('RemoteSceneStore requires an agent grant token');
+    if (!encryptionKey) throw new Error('RemoteSceneStore requires the workspace encryption key');
+    if (typeof fetchImpl !== 'function') throw new Error('RemoteSceneStore requires fetch');
+    this.url = new URL(`/api/mcp/workspaces/${encodeURIComponent(workspaceId)}`, String(baseUrl).replace(/\/$/, ''));
+    this.workspaceId = workspaceId;
+    this.token = token;
+    this.encryptionKey = encryptionKey;
+    this.fetch = fetchImpl;
+    this.remoteRevision = null;
+  }
+
+  async read() {
+    const response = await this.fetch(this.url, { headers: this.headers(), cache: 'no-store' });
+    const body = await readJson(response);
+    if (!response.ok) throw remoteError(response, body);
+    const scene = await decryptRemoteScene(body.encryptedData, this.encryptionKey);
+    const validation = validateScene(scene);
+    if (!validation.valid) throw new Error(`Remote workspace is invalid: ${validation.errors.join('; ')}`);
+    this.remoteRevision = Number(body.revision || 0);
+    scene.mcpRevision = this.remoteRevision;
+    return scene;
+  }
+
+  async write(scene) {
+    const validation = validateScene(scene);
+    if (!validation.valid) throw new Error(`Refusing to store invalid remote scene: ${validation.errors.join('; ')}`);
+    if (!Number.isInteger(this.remoteRevision)) throw new Error('Read the remote workspace before writing it');
+    const encryptedData = await encryptRemoteScene(scene, this.encryptionKey);
+    const response = await this.fetch(this.url, {
+      method: 'PUT',
+      headers: { ...this.headers(), 'Content-Type': 'application/json' },
+      body: JSON.stringify({ encryptedData, expectedRevision: this.remoteRevision, workspaceName: scene.name }),
+    });
+    const body = await readJson(response);
+    if (!response.ok) throw remoteError(response, body);
+    this.remoteRevision = Number(body.revision);
+    return structuredClone({ ...scene, mcpRevision: this.remoteRevision });
+  }
+
+  headers() {
+    return { Accept: 'application/json', Authorization: `Bearer ${this.token}` };
+  }
+}
+
+async function readJson(response) {
+  return response.json().catch(() => ({}));
+}
+
+function remoteError(response, body) {
+  const error = new Error(body.error === 'REVISION_CONFLICT'
+    ? `Revision conflict: expected ${body.expectedRevision}, current ${body.currentRevision}`
+    : body.error || `Remote workspace request failed (${response.status})`);
+  error.status = response.status;
+  error.details = body;
+  return error;
+}

package/src/mcp/scene.js

@@ -168,6 +168,7 @@ export function applyScenePatch(sceneInput, operations, { expectedRevision, dryR
       scene.name = String(operation.name || '').trim().slice(0, 72) || scene.name;
     } else throw new Error(`Unsupported operation "${operation.op}"`);
   }
+  reconcileFrameContainment(scene);
   scene.mcpRevision = revision + 1;
   scene.updatedAt = new Date().toISOString();
   const result = validateScene(scene);
@@ -175,6 +176,17 @@ export function applyScenePatch(sceneInput, operations, { expectedRevision, dryR
   return { scene, revision: scene.mcpRevision, dryRun: Boolean(dryRun), changedShapeIDs: [...changedIds] };
 }
 
+function reconcileFrameContainment(scene) {
+  const frames = new Map(scene.shapes.filter((shape) => shape.type === 'frame').map((shape) => [shape.shapeID, shape]));
+  for (const frame of frames.values()) frame.containedShapeIDs = [];
+  for (const shape of scene.shapes) {
+    if (!shape.parentFrame) continue;
+    const frame = frames.get(shape.parentFrame);
+    if (!frame) throw new Error(`Shape "${shape.shapeID}" references missing frame "${shape.parentFrame}"`);
+    frame.containedShapeIDs.push(shape.shapeID);
+  }
+}
+
 function applyShapeChanges(shape, changes) {
   if (!changes || typeof changes !== 'object' || Array.isArray(changes)) throw new Error('Shape changes must be an object');
   const allowed = {

package/src/mcp/server.js

@@ -1,9 +1,10 @@
 import { applyScenePatch, createEmptyScene, getSceneSummary, mergeTemplateScene, validateScene, MCP_LIMITS } from './scene.js';
 import { MarketplaceTemplateProvider } from './templates.js';
 import { renderSceneSvg } from './preview.js';
+import { compileLixScript } from './lixscript.js';
 
 const SERVER_NAME = 'lixsketch';
-const SERVER_VERSION = '1.0.0';
+const SERVER_VERSION = '1.1.0';
 const PROTOCOL_VERSION = '2025-11-25';
 const SUPPORTED_PROTOCOL_VERSIONS = new Set([PROTOCOL_VERSION, '2025-06-18', '2024-11-05']);
 
@@ -53,6 +54,13 @@ export const LIXSKETCH_MCP_TOOLS = Object.freeze([
     inputSchema: { type: 'object', required: ['confirm'], properties: { name: { type: 'string', maxLength: 72 }, confirm: { const: true } }, additionalProperties: false },
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
   },
+  {
+    name: 'lixscript_apply',
+    title: 'Apply LixScript diagram',
+    description: 'Compile LixScript into the same validated atomic scene patch used by structured canvas edits. Supports revisions and dry runs.',
+    inputSchema: { type: 'object', required: ['source'], properties: { source: { type: 'string', maxLength: 100000 }, x: { type: 'number' }, y: { type: 'number' }, expectedRevision: { type: 'integer', minimum: 0 }, dryRun: { type: 'boolean', default: false } }, additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+  },
   {
     name: 'templates_search',
     title: 'Search LixSketch templates',
@@ -130,10 +138,20 @@ export class LixSketchMcpServer {
         case 'canvas_new':
           if (args.confirm !== true) throw new Error('canvas_new requires confirm=true');
           return await this.enqueueMutation(async () => {
+            const current = await this.store.read();
             const scene = createEmptyScene(args.name);
+            scene.mcpRevision = Number(current.mcpRevision || 0) + 1;
             await this.store.write(scene);
             return toolResult({ summary: getSceneSummary(scene) }, 'Blank canvas created.');
           });
+        case 'lixscript_apply':
+          return await this.enqueueMutation(async () => {
+            const scene = await this.store.read();
+            const compiled = compileLixScript(args.source, args);
+            const result = applyScenePatch(scene, compiled.operations, args);
+            if (!args.dryRun) await this.store.write(result.scene);
+            return toolResult({ revision: result.revision, dryRun: result.dryRun, sourceShapeCount: compiled.sourceShapeCount, createdShapeIDs: result.changedShapeIDs, summary: getSceneSummary(result.scene) }, args.dryRun ? 'LixScript is valid. No changes were saved.' : `LixScript added ${result.changedShapeIDs.length} canvas elements.`);
+          });
         case 'template_insert':
           return await this.enqueueMutation(async () => {
             const scene = await this.store.read();
@@ -162,7 +180,7 @@ export class LixSketchMcpServer {
     if (method === 'initialize') {
       const requested = request.params?.protocolVersion;
       const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.has(requested) ? requested : PROTOCOL_VERSION;
-      return { protocolVersion, capabilities: { tools: { listChanged: false }, resources: { subscribe: false, listChanged: false } }, serverInfo: this.serverInfo, instructions: 'Read canvas_get before mutations. Use expectedRevision and dryRun for safe edits. Prefer template_insert for reusable component packs.' };
+      return { protocolVersion, capabilities: { tools: { listChanged: false }, resources: { subscribe: false, listChanged: false } }, serverInfo: this.serverInfo, instructions: 'Before any mutation, call canvas_get and retain its revision. Preserve unrelated shapes. Send expectedRevision and dryRun: true first, inspect canvas_preview for layout changes, then commit the same validated operation with dryRun: false. Never clear or replace a canvas unless the user explicitly requests it. Prefer lixscript_apply for diagrams and template_insert for reusable component packs.' };
     }
     if (method === 'ping') return {};
     if (method === 'tools/list') return { tools: this.listTools() };

package/src/mcp/stdio.js

@@ -4,34 +4,40 @@ import { createLixSketchMcpServer } from './server.js';
 import { FileSceneStore } from './fileStore.js';
 import { MarketplaceTemplateProvider } from './templates.js';
 import { serveLixSketchStdio } from './stdioTransport.js';
+import { RemoteSceneStore } from './remoteStore.js';
 
 function parseArguments(argv) {
-  const options = { scene: process.env.LIXSKETCH_SCENE_FILE || './lixsketch-mcp.lixjson', marketplaceUrl: process.env.LIXSKETCH_MARKETPLACE_URL || 'https://sketch.elixpo.com' };
+  const options = { scene: process.env.LIXSKETCH_SCENE_FILE || './lixsketch-mcp.lixjson', remote: process.env.LIXSKETCH_REMOTE_URL || '', workspace: process.env.LIXSKETCH_WORKSPACE_ID || '', marketplaceUrl: process.env.LIXSKETCH_MARKETPLACE_URL || 'https://sketch.elixpo.com' };
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
     if (argument === '--scene') options.scene = argv[++index];
+    else if (argument === '--remote') options.remote = argv[++index];
+    else if (argument === '--workspace') options.workspace = argv[++index];
     else if (argument === '--marketplace-url') options.marketplaceUrl = argv[++index];
     else if (argument === '--help' || argument === '-h') options.help = true;
     else throw new Error(`Unknown argument: ${argument}`);
   }
   if (!options.scene) throw new Error('--scene requires a file path');
+  if (options.remote && !options.workspace) throw new Error('--remote requires --workspace or LIXSKETCH_WORKSPACE_ID');
   return options;
 }
 
 function printHelp() {
-  process.stderr.write(`LixSketch MCP server\n\nUsage:\n  lixsketch-mcp --scene ./diagram.lixjson\n\nOptions:\n  --scene <path>             Atomic .lixjson scene file (default: ./lixsketch-mcp.lixjson)\n  --marketplace-url <url>    Template marketplace origin\n  -h, --help                 Show this help\n\nEnvironment:\n  LIXSKETCH_SCENE_FILE\n  LIXSKETCH_MARKETPLACE_URL\n`);
+  process.stderr.write(`LixSketch MCP server\n\nUsage:\n  lixsketch-mcp --scene ./diagram.lixjson\n  lixsketch-mcp --remote https://sketch.elixpo.com --workspace lx-...\n\nOptions:\n  --scene <path>             Atomic local .lixjson scene file\n  --remote <origin>          Remote LixSketch deployment origin\n  --workspace <id>           Remote workspace session ID\n  --marketplace-url <url>    Template marketplace origin\n  -h, --help                 Show this help\n\nRemote environment (never pass secrets as arguments):\n  LIXSKETCH_AGENT_TOKEN\n  LIXSKETCH_ENCRYPTION_KEY\n\nOther environment:\n  LIXSKETCH_SCENE_FILE\n  LIXSKETCH_REMOTE_URL\n  LIXSKETCH_WORKSPACE_ID\n  LIXSKETCH_MARKETPLACE_URL\n`);
 }
 
 async function main() {
   const options = parseArguments(process.argv.slice(2));
   if (options.help) { printHelp(); return; }
-  const store = new FileSceneStore(options.scene);
+  const store = options.remote
+    ? new RemoteSceneStore({ baseUrl: options.remote, workspaceId: options.workspace, token: process.env.LIXSKETCH_AGENT_TOKEN, encryptionKey: process.env.LIXSKETCH_ENCRYPTION_KEY })
+    : new FileSceneStore(options.scene);
   const server = createLixSketchMcpServer({ store, templateProvider: new MarketplaceTemplateProvider({ baseUrl: options.marketplaceUrl }) });
   const transport = serveLixSketchStdio(server);
   const close = () => { void transport.close().finally(() => process.exit(0)); };
   process.once('SIGINT', close);
   process.once('SIGTERM', close);
-  process.stderr.write(`LixSketch MCP ready: ${store.filePath}\n`);
+  process.stderr.write(`LixSketch MCP ready: ${store.filePath || `${options.remote}/c/${options.workspace}`}\n`);
   await transport.closed;
 }