framer-dalton 0.0.4 → 0.0.5

package/README.md

@@ -14,12 +14,22 @@ Then, simply open your preferred agent, ask to interact with your Framer project
 
 See [skills/framer/SKILL.md](skills/framer/SKILL.md) for full CLI usage and API documentation.
 
-## Development
+## Local Development
+
+Build and symlink to PATH + install skill locally:
+
+```bash
+make install-dev
+```
+
+If you want to hit a local FramerHeadlessAPI instance, when interacting with your agent, tell it something like this:
+
+```
+Use the framer skill, but use `FRAMER_HEADLESS_SERVER_URL=ws://localhost:8080/channel/headless-plugin framer` (never with @latest) for all commands instead of `npx framer-dalton`
+```
+
+Remove local install:
 
 ```bash
-make install-dev    # Build and symlink to PATH + install skill locally
-make build          # Build (installs deps automatically)
-make check          # Type check + lint
-make format         # Auto-format
-make clean          # Clean build artifacts
+make uninstall-dev
 ```

package/dist/cli.js

@@ -7,7 +7,7 @@ import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { createTRPCClient, httpLink } from '@trpc/client';
 
-/* @framer/ai CLI v0.0.4 */
+/* @framer/ai CLI v0.0.5 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 function getConfigDir() {
@@ -1412,7 +1412,7 @@ var types = {
     name: "Control",
     description: "",
     kind: "alias",
-    alias: "EnumControl | BooleanControl | BorderControl | ShadowControl | DateControl | NumberControl | TransitionControl | StringControl | ColorControl | FormattedTextControl | LinkControl | LinkRelControl | FontControl | PageScopeControl | ScrollSectionControl | CustomCursorControl | CursorControl | FileControl | GapControl | PaddingControl | BorderRadiusControl | CollectionReferenceControl | MultiCollectionReferenceControl | VectorSetItemControl | TrackingIdControl | ImageControl | FusedNumberControl | ObjectControl | ArrayControl | EventHandlerControl | SlotControl",
+    alias: "EnumControl | BooleanControl | BorderControl | ShadowControl | DateControl | NumberControl | TransitionControl | StringControl | ColorControl | FormattedTextControl | LinkControl | LinkRelControl | FontControl | PageScopeControl | ScrollSectionControl | CustomCursorControl | CursorControl | FileControl | GapControl | PaddingControl | BorderRadiusControl | CollectionReferenceControl | MultiCollectionReferenceControl | VectorSetItemControl | TrackingIdControl | ImageControl | FusedNumberControl | ObjectControl | ArrayControl | EventHandlerControl | SlotControl | LocationControl",
     references: [
       "EnumControl",
       "BooleanControl",
@@ -1444,7 +1444,8 @@ var types = {
       "ObjectControl",
       "ArrayControl",
       "EventHandlerControl",
-      "SlotControl"
+      "SlotControl",
+      "LocationControl"
     ]
   },
   controlattributes: {
@@ -1461,6 +1462,26 @@ var types = {
     references: ["WithKey"],
     extends: ["WithKey", "Partial", "Partial"]
   },
+  coordinate: {
+    name: "Coordinate",
+    description: "",
+    kind: "interface",
+    references: [],
+    members: [
+      {
+        name: "latitude",
+        type: "number",
+        description: "",
+        optional: false
+      },
+      {
+        name: "longitude",
+        type: "number",
+        description: "",
+        optional: false
+      }
+    ]
+  },
   createarrayfield: {
     name: "CreateArrayField",
     description: "",
@@ -1803,6 +1824,50 @@ var types = {
     references: ["WithLinkVariableType", "CreateVariableBase"],
     extends: ["WithLinkVariableType", "CreateVariableBase"]
   },
+  createlocaleinput: {
+    name: "CreateLocaleInput",
+    description: "Input for creating a new locale.\n@alpha",
+    kind: "interface",
+    references: ["LocaleId"],
+    members: [
+      {
+        name: "language",
+        type: "string",
+        description: 'The language code (e.g., "en", "fr", "zh-Hans"). Use `getLocaleLanguages()` to get the list of valid codes.',
+        optional: false
+      },
+      {
+        name: "region",
+        type: "string",
+        description: 'The optional region code (e.g., "US", "CA"). Use `getLocaleRegions(language)` to get the list of valid codes.',
+        optional: true
+      },
+      {
+        name: "fallbackLocaleId",
+        type: "LocaleId",
+        description: "ID of the fallback locale. Must reference an existing locale.",
+        optional: true
+      },
+      {
+        name: "slug",
+        type: "string",
+        description: 'URL slug for the locale (e.g., "en"). If not provided, one is derived from the code.',
+        optional: true
+      },
+      {
+        name: "name",
+        type: "string",
+        description: 'Display Name for the locale (e.g., "English (US)"). If not provided, one is derived from the code.',
+        optional: true
+      },
+      {
+        name: "draft",
+        type: "boolean",
+        description: "Flag to mark the locale as a draft. Defaults to `false`.",
+        optional: true
+      }
+    ]
+  },
   createmulticollectionreferencefield: {
     name: "CreateMultiCollectionReferenceField",
     description: "",
@@ -4319,6 +4384,53 @@ var types = {
     alias: '{\n    action: "set";\n    value: string;\n    needsReview?: boolean;\n} | {\n    action: "clear";\n} | {\n    action: "ignore";\n    needsReview?: boolean;\n}',
     references: []
   },
+  location: {
+    name: "Location",
+    description: "",
+    kind: "interface",
+    references: ["Coordinate"],
+    members: [
+      {
+        name: "coordinate",
+        type: "Coordinate",
+        description: "",
+        optional: false
+      },
+      {
+        name: "title",
+        type: "string",
+        description: 'Place name, e.g. "Eiffel Tower" or "Framer".',
+        optional: true
+      },
+      {
+        name: "address",
+        type: "string",
+        description: 'Formatted address string, e.g. "Rozengracht 207, 1016 LZ Amsterdam, Netherlands".',
+        optional: true
+      }
+    ]
+  },
+  locationcontrol: {
+    name: "LocationControl",
+    description: "",
+    kind: "interface",
+    references: ["ControlBase", "Location"],
+    members: [
+      {
+        name: "type",
+        type: '"location"',
+        description: "",
+        optional: false
+      },
+      {
+        name: "value",
+        type: "Location | undefined",
+        description: "",
+        optional: true
+      }
+    ],
+    extends: ["ControlBase"]
+  },
   managedarrayfieldinput: {
     name: "ManagedArrayFieldInput",
     description: "",
@@ -5254,6 +5366,24 @@ var types = {
         description: "",
         optional: false
       },
+      {
+        name: "createLocale",
+        type: "(input: CreateLocaleInput) => Promise<Locale>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "getLocaleLanguages",
+        type: "() => Promise<{\n        code: string;\n        name: string;\n    }[]>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "getLocaleRegions",
+        type: "(language: string) => Promise<{\n        code: string;\n        name: string;\n        isCommon: boolean;\n    }[]>",
+        description: "@alpha",
+        optional: false
+      },
       {
         name: "unstable_ensureMinimumDependencyVersion",
         type: 'FramerPluginAPI["unstable_ensureMinimumDependencyVersion"]',
@@ -6058,6 +6188,30 @@ var types = {
         description: "@alpha",
         optional: false
       },
+      {
+        name: "getAgentSystemPrompt",
+        type: "() => Promise<string>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "getAgentContext",
+        type: "(options?: {\n        pagePath?: string;\n    }) => Promise<string>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "readProjectForAgent",
+        type: "(queries: Record<string, unknown>[], options?: {\n        pagePath?: string;\n    }) => Promise<{\n        results: unknown[];\n    }>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "applyAgentChanges",
+        type: "(dsl: string, options?: {\n        pagePath?: string;\n    }) => Promise<void>",
+        description: "@alpha",
+        optional: false
+      },
       {
         name: "[getAiServiceInfoMessageType]",
         type: "() => Promise<AiServiceInfo>",
@@ -11648,6 +11802,34 @@ var methodsByCategory = {
     }
   ],
   framer: [
+    {
+      name: "[$framerApiOnly.applyAgentChanges]",
+      category: "framer",
+      signature: "[$framerApiOnly.applyAgentChanges](dsl: string, options?: { pagePath?: string; }): Promise<void>",
+      description: 'Applies commands to the canvas to create, update, remove, move, or duplicate nodes.\n\nThe command syntax is documented in the string returned by {@link getAgentSystemPrompt}.\nEach call is scoped to a single page.\n\n@param dsl - A string of commands separated by `;`. See {@link getAgentSystemPrompt} for syntax.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.',
+      references: []
+    },
+    {
+      name: "[$framerApiOnly.getAgentContext]",
+      category: "framer",
+      signature: "[$framerApiOnly.getAgentContext](options?: { pagePath?: string; }): Promise<string>",
+      description: 'Returns the dynamic project context as a string.\n\nThe context includes project-specific data:\n- **Available fonts** \u2014 font families loaded in the project.\n- **Components** \u2014 component names and their controls.\n- **Design tokens** \u2014 color tokens defined in the project.\n- **Style presets** \u2014 text style presets defined in the project.\n- **Icon sets** \u2014 available icon sets and their definitions.\n\nThis data changes per project and page. Pair with the static prompt\nfrom {@link getAgentSystemPrompt} for complete agent context.\n\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns A string containing the project context.',
+      references: []
+    },
+    {
+      name: "[$framerApiOnly.getAgentSystemPrompt]",
+      category: "framer",
+      signature: "[$framerApiOnly.getAgentSystemPrompt](): Promise<string>",
+      description: "Returns the static agent system prompt as a string.\n\nThe prompt includes:\n- **Command reference** \u2014 syntax for adding, updating, removing, moving, and duplicating nodes.\n- **Design rules** \u2014 spacing, layout, typography, and responsive design guidance.\n- **Examples** \u2014 common UI patterns expressed as commands.\n- **`readProjectForAgent` query reference** \u2014 available query types and their parameters.\n\nThis is the sole documentation for the command syntax used by {@link applyAgentChanges}\nand the query types used by {@link readProjectForAgent}.\n\nThe prompt is static and does not depend on any specific project.\nCall {@link getAgentContext} to get the project-specific context.\n\n@returns A string containing the agent system prompt.",
+      references: []
+    },
+    {
+      name: "[$framerApiOnly.readProjectForAgent]",
+      category: "framer",
+      signature: "[$framerApiOnly.readProjectForAgent](queries: Record<string, unknown>[], options?: { pagePath?: string; }): Promise<{ results: unknown[]; }>",
+      description: 'Reads project state by executing an array of queries against the project.\n\nReturns one result per query. Available query types and their parameters\nare documented in the string returned by {@link getAgentSystemPrompt}.\n\n@param queries - Array of query objects. See {@link getAgentSystemPrompt} for available types.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns An object with a `results` array, one entry per query.',
+      references: []
+    },
     {
       name: "[$framerInternal.initialState]",
       category: "framer",
@@ -11728,6 +11910,13 @@ var methodsByCategory = {
       description: "Add a new text node to the canvas.",
       references: ["AddTextOptions"]
     },
+    {
+      name: "applyAgentChanges",
+      category: "framer",
+      signature: "applyAgentChanges(dsl: string, options?: { pagePath?: string; }): Promise<void>",
+      description: 'Applies commands to the canvas to create, update, remove, move, or duplicate nodes.\n\nThe command syntax is documented in the string returned by {@link getAgentSystemPrompt}.\nEach call is scoped to a single page.\n\n@param dsl - A string of commands separated by `;`. See {@link getAgentSystemPrompt} for syntax.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.',
+      references: []
+    },
     {
       name: "cloneNode",
       category: "framer",
@@ -11777,6 +11966,13 @@ var methodsByCategory = {
       description: "Create a new node on the canvas.",
       references: ["EditableFrameNodeAttributes", "FrameNode"]
     },
+    {
+      name: "createLocale",
+      category: "framer",
+      signature: "createLocale(input: CreateLocaleInput): Promise<Locale>",
+      description: "Create a new locale in the project.\n\n@alpha\n@param input - The locale configuration, use `getLocaleLanguages` and `getLocaleRegions` to get valid language and region codes.\n@returns The created locale.",
+      references: ["CreateLocaleInput", "Locale"]
+    },
     {
       name: "createManagedCollection",
       category: "framer",
@@ -11826,6 +12022,20 @@ var methodsByCategory = {
       description: "",
       references: []
     },
+    {
+      name: "getAgentContext",
+      category: "framer",
+      signature: "getAgentContext(options?: { pagePath?: string; }): Promise<string>",
+      description: 'Returns the dynamic project context as a string.\n\nThe context includes project-specific data:\n- **Available fonts** \u2014 font families loaded in the project.\n- **Components** \u2014 component names and their controls.\n- **Design tokens** \u2014 color tokens defined in the project.\n- **Style presets** \u2014 text style presets defined in the project.\n- **Icon sets** \u2014 available icon sets and their definitions.\n\nThis data changes per project and page. Pair with the static prompt\nfrom {@link getAgentSystemPrompt} for complete agent context.\n\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns A string containing the project context.',
+      references: []
+    },
+    {
+      name: "getAgentSystemPrompt",
+      category: "framer",
+      signature: "getAgentSystemPrompt(): Promise<string>",
+      description: "Returns the static agent system prompt as a string.\n\nThe prompt includes:\n- **Command reference** \u2014 syntax for adding, updating, removing, moving, and duplicating nodes.\n- **Design rules** \u2014 spacing, layout, typography, and responsive design guidance.\n- **Examples** \u2014 common UI patterns expressed as commands.\n- **`readProjectForAgent` query reference** \u2014 available query types and their parameters.\n\nThis is the sole documentation for the command syntax used by {@link applyAgentChanges}\nand the query types used by {@link readProjectForAgent}.\n\nThe prompt is static and does not depend on any specific project.\nCall {@link getAgentContext} to get the project-specific context.\n\n@returns A string containing the agent system prompt.",
+      references: []
+    },
     {
       name: "getCanvasRoot",
       category: "framer",
@@ -11945,6 +12155,20 @@ var methodsByCategory = {
       description: "Get the image of the current selection or `null` if there is no image.\n\nIn `editImage` mode, this returns the image the user already has set,\nwhich your plugin can then modify.",
       references: ["ImageAsset"]
     },
+    {
+      name: "getLocaleLanguages",
+      category: "framer",
+      signature: "getLocaleLanguages(): Promise<{ code: string; name: string; }[]>",
+      description: "Get all available locale languages.\n\n@alpha\n@returns A list of language codes and their display names, sorted by name.",
+      references: []
+    },
+    {
+      name: "getLocaleRegions",
+      category: "framer",
+      signature: "getLocaleRegions(languageCode: string): Promise<{ code: string; name: string; isCommon: boolean; }[]>",
+      description: "Get all available locale regions for a given language.\n\n@alpha\n@param languageCode - The language code to get regions for. Use `getLocaleLanguages` to get valid language codes.\n@returns A list of region codes, their display names, and whether they are commonly paired with the given language.",
+      references: []
+    },
     {
       name: "getLocales",
       category: "framer",
@@ -12071,6 +12295,13 @@ var methodsByCategory = {
       description: "",
       references: ["PublishResult"]
     },
+    {
+      name: "readProjectForAgent",
+      category: "framer",
+      signature: "readProjectForAgent(queries: Record<string, unknown>[], options?: { pagePath?: string; }): Promise<{ results: unknown[]; }>",
+      description: 'Reads project state by executing an array of queries against the project.\n\nReturns one result per query. Available query types and their parameters\nare documented in the string returned by {@link getAgentSystemPrompt}.\n\n@param queries - Array of query objects. See {@link getAgentSystemPrompt} for available types.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns An object with a `results` array, one entry per query.',
+      references: []
+    },
     {
       name: "rejectAllPending",
       category: "framer",
@@ -14281,7 +14512,7 @@ ${typeDef}`);
 __name(renderDocs, "renderDocs");
 var __filename$1 = fileURLToPath(import.meta.url);
 var __dirname$1 = path.dirname(__filename$1);
-var VERSION = "0.0.4" ;
+var VERSION = "0.0.5" ;
 var RELAY_PORT = Number(process.env.FRAMER_CLI_PORT) || 19988;
 var client = createTRPCClient({
   links: [
@@ -14413,8 +14644,8 @@ async function readStdin() {
   return Buffer.concat(chunks).toString("utf-8");
 }
 __name(readStdin, "readStdin");
-program.option("-s, --session <id>", "Session ID (required for code execution)").option("-e, --eval <code>", "Code to execute (or pipe via stdin)").option("--timeout <ms>", "Execution timeout in milliseconds", "30000").action(async (options) => {
-  const { session: sessionId, eval: evalCode, timeout } = options;
+program.option("-s, --session <id>", "Session ID (required for code execution)").option("-e, --eval <code>", "Code to execute (or pipe via stdin)").action(async (options) => {
+  const { session: sessionId, eval: evalCode } = options;
   let code = evalCode;
   if (!code && !process.stdin.isTTY) {
     code = await readStdin();
@@ -14435,7 +14666,6 @@ program.option("-s, --session <id>", "Session ID (required for code execution)")
     const result = await client.exec.mutate({
       sessionId: String(sessionId),
       code,
-      timeout: parseInt(timeout, 10),
       cwd: process.cwd()
     });
     for (const line of result.output) {

package/dist/start-relay-server.js

@@ -13,7 +13,7 @@ import { createRequire } from 'module';
 import * as vm from 'vm';
 import { connect } from 'framer-api';
 
-/* @framer/ai relay server v0.0.4 */
+/* @framer/ai relay server v0.0.5 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 function getLogPath() {
@@ -50,7 +50,7 @@ function log(message) {
 __name(log, "log");
 var __filename$1 = fileURLToPath(import.meta.url);
 path.dirname(__filename$1);
-var VERSION = "0.0.4" ;
+var VERSION = "0.0.5" ;
 var RELAY_PORT = Number(process.env.FRAMER_CLI_PORT) || 19988;
 createTRPCClient({
   links: [
@@ -266,8 +266,8 @@ var ScopedFS = class {
   constants = fs2.constants;
 };
 
-// src/executor.ts
-var DEFAULT_TIMEOUT = 3e4;
+// src/execute.ts
+var EXECUTION_TIMEOUT = 10 * 60 * 1e3;
 var baseRequire = createRequire(import.meta.url);
 var ALLOWED_MODULES = /* @__PURE__ */ new Set([
   "path",
@@ -329,7 +329,7 @@ async function sandboxedImport(scopedFs, specifier) {
 }
 __name(sandboxedImport, "sandboxedImport");
 async function execute(session, framer, code, options = {}) {
-  const { timeout = DEFAULT_TIMEOUT, cwd } = options;
+  const { cwd } = options;
   const output = [];
   const customConsole = {
     log: /* @__PURE__ */ __name((...args) => {
@@ -376,22 +376,24 @@ async function execute(session, framer, code, options = {}) {
   };
   const vmContext = vm.createContext(vmContextObj);
   const wrappedCode = `(async () => { ${code} })()`;
+  let timeoutId;
   try {
     const script = new vm.Script(wrappedCode, {
       filename: "framer-exec.js"
     });
     const resultPromise = script.runInContext(vmContext, {
       timeout: 5e3
-      // Short timeout for sync part
     });
     const result = await Promise.race([
       resultPromise,
-      new Promise(
-        (_, reject) => setTimeout(
-          () => reject(new Error(`Execution timed out after ${timeout}ms`)),
-          timeout
-        )
-      )
+      new Promise((_, reject) => {
+        timeoutId = setTimeout(
+          () => reject(
+            new Error(`Execution timed out after ${EXECUTION_TIMEOUT}ms`)
+          ),
+          EXECUTION_TIMEOUT
+        );
+      })
     ]);
     if (result !== void 0) {
       output.push(formatValue(result));
@@ -403,9 +405,42 @@ async function execute(session, framer, code, options = {}) {
       output,
       error: errorMessage
     };
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
   }
 }
 __name(execute, "execute");
+async function executeWithReconnect(session, framer, code, options, reconnect) {
+  const result = await tryExecute(session, framer, code, options);
+  if (!result.error || !isConnectionError(result.error)) {
+    return result;
+  }
+  log(
+    `reconnect session=${session.id} project=${session.projectId} reason="${result.error}"`
+  );
+  const newFramer = await reconnect();
+  if (!newFramer) {
+    log(
+      `reconnect.failed session=${session.id} error="no connection returned"`
+    );
+    return {
+      output: [],
+      error: "Connection lost and failed to reconnect"
+    };
+  }
+  log(`reconnect.success session=${session.id}`);
+  return tryExecute(session, newFramer, code, options);
+}
+__name(executeWithReconnect, "executeWithReconnect");
+async function tryExecute(session, framer, code, options) {
+  try {
+    return await execute(session, framer, code, options);
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    return { output: [], error };
+  }
+}
+__name(tryExecute, "tryExecute");
 function formatValue(value) {
   if (value === null) return "null";
   if (value === void 0) return "undefined";
@@ -431,6 +466,7 @@ var ConnectionPool = class {
     __name(this, "ConnectionPool");
   }
   pool = /* @__PURE__ */ new Map();
+  reconnectPromises = /* @__PURE__ */ new Map();
   /**
    * Acquire a connection for a session.
    * If a connection already exists for the project, the session is added to it.
@@ -458,15 +494,26 @@ var ConnectionPool = class {
   }
   /**
    * Reconnect a project's connection (call after catching a connection error).
-   * Uses the same connection object but swaps the underlying WebSocket.
+   * Concurrent callers for the same project share a single reconnect attempt.
    */
   async reconnect(projectId) {
+    const existingPromise = this.reconnectPromises.get(projectId);
+    if (existingPromise) return existingPromise;
+    const promise = this.doReconnect(projectId).finally(() => {
+      this.reconnectPromises.delete(projectId);
+    });
+    this.reconnectPromises.set(projectId, promise);
+    return promise;
+  }
+  async doReconnect(projectId) {
     const entry = this.pool.get(projectId);
-    if (!entry) {
+    if (!entry) return null;
+    try {
+      await entry.connection.reconnect();
+      return entry.connection;
+    } catch {
       return null;
     }
-    await entry.connection.reconnect();
-    return entry.connection;
   }
   /**
    * Release a session from a connection.
@@ -570,11 +617,10 @@ var appRouter = t.router({
     z.object({
       sessionId: z.string(),
       code: z.string(),
-      timeout: z.number().default(3e4),
       cwd: z.string().optional()
     })
   ).mutation(async ({ input }) => {
-    const { sessionId, code, timeout, cwd } = input;
+    const { sessionId, code, cwd } = input;
     const session = sessionManager.get(sessionId);
     if (!session) {
       throw new TRPCError({
@@ -585,43 +631,20 @@ var appRouter = t.router({
     log(
       `exec session=${sessionId} code=${JSON.stringify(code).slice(0, 100)}`
     );
-    let framer = sessionManager.getFramer(session);
+    const framer = sessionManager.getFramer(session);
     if (!framer) {
       return {
         output: [],
         error: "Failed to get connection for session"
       };
     }
-    let result;
-    try {
-      result = await execute(session, framer, code, { timeout, cwd });
-    } catch (execErr) {
-      const errMsg = execErr instanceof Error ? execErr.message : String(execErr);
-      result = { output: [], error: errMsg };
-    }
-    if (result.error && isConnectionError(result.error)) {
-      log(
-        `reconnect session=${sessionId} project=${session.projectId} reason="${result.error}"`
-      );
-      framer = await sessionManager.reconnect(session);
-      if (framer) {
-        try {
-          result = await execute(session, framer, code, {
-            timeout,
-            cwd
-          });
-          log(`reconnect.success session=${sessionId}`);
-        } catch (retryErr) {
-          const errMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
-          log(`reconnect.failed session=${sessionId} error="${errMsg}"`);
-          result = { output: [], error: errMsg };
-        }
-      } else {
-        log(
-          `reconnect.failed session=${sessionId} error="no connection returned"`
-        );
-      }
-    }
+    const result = await executeWithReconnect(
+      session,
+      framer,
+      code,
+      { cwd },
+      () => sessionManager.reconnect(session)
+    );
     if (result.error) {
       log(`exec.error session=${sessionId} error="${result.error}"`);
     }

package/docs/server-api.md

@@ -73,8 +73,6 @@ npx framer-dalton session list
 npx framer-dalton -s <sessionId> -e "<code>"
 ```
 
-Default timeout is 30 seconds. Increase with `--timeout <ms>`.
-
 **Escaping:** For code with HTML, quotes, or special characters, use a heredoc (see below). For simple strings, use `$'...'` syntax.
 
 **Examples:**
@@ -606,7 +604,10 @@ Server API exclusive methods for capturing visual output from nodes.
 const result = await framer.screenshot(node.id);
 console.log(result.mimeType); // "image/png"
 const os = require("os");
-await require("fs").promises.writeFile(os.tmpdir() + "/screenshot.png", result.data);
+await require("fs").promises.writeFile(
+  os.tmpdir() + "/screenshot.png",
+  result.data,
+);
 
 // With options
 const jpg = await framer.screenshot(node.id, {
@@ -667,12 +668,75 @@ const contributors = await framer.getChangeContributors();
 
 ---
 
+## Canvas Editing
+
+**Use this for all design tasks** — creating pages, building sections, recreating designs from screenshots, or any task that involves layout or visual styling on the canvas.
+
+**Hard rule:** For design/layout work, do **not** use low-level node APIs (`createNode`, `setAttributes`, `setRect`, etc.). Always use the canvas editing flow (`getAgentSystemPrompt` + `getAgentContext` + `readProjectForAgent` + `applyAgentChanges`). If you start writing low-level node code for design work, stop and switch to canvas editing methods.
+
+**Access note:** Canvas editing `agent` methods are employee-only. If these methods fail or are unavailable, the account likely does not have employee access.
+
+### Methods
+
+**`framer.getAgentSystemPrompt()`** — Returns the command reference, design rules, layout patterns, and examples. This is the sole documentation for the command syntax and query types. It is static (same for every project) — fetch once per session and persist to a file.
+
+**`framer.getAgentContext({ pagePath })`** — Returns the project's available fonts, components, color tokens, text style presets, and icon sets for the target page scope. Fetch before generating commands and use the same `pagePath` across context/read/apply calls.
+
+**`framer.readProjectForAgent(queries, { pagePath })`** — Reads project state. Query types are documented in the system prompt. Use liberally — query the page tree, icon sets, components, and examples before generating commands. Multiple queries can be batched in a single call. Never guess at names for examples, icon sets, or fonts — always look them up first.
+
+**`framer.applyAgentChanges(dsl, { pagePath })`** — Applies commands to the canvas. Node IDs you assign are temporary — re-read the page tree via `readProjectForAgent` if you need actual IDs after applying.
+
+### Workflow
+
+```js
+// 1. Save the system prompt to a file (once per session).
+const fs = require("fs");
+const prompt = await framer.getAgentSystemPrompt();
+fs.writeFileSync("/tmp/framer-canvas-reference.txt", prompt);
+console.log("Saved to /tmp/framer-canvas-reference.txt —", prompt.length, "chars");
+
+// 2. Get project context
+const projectCtx = await framer.getAgentContext({ pagePath: "/" });
+console.log(projectCtx);
+
+// 3. Read project state (query types are in the prompt)
+const { results } = await framer.readProjectForAgent(
+  [{ type: "page", path: "/" }],
+  { pagePath: "/" }
+);
+
+// 4. Apply changes
+await framer.applyAgentChanges(dsl, { pagePath: "/" });
+```
+
+**You must read the entire system prompt file before writing any commands.** It contains command syntax, design rules, layout patterns, examples, and query documentation. Skipping sections will cause incorrect output.
+
+After applying changes, take screenshots to inspect the result. Check padding, spacing, typography, icon choice, and alignment. Iterate with additional `readProjectForAgent` + `applyAgentChanges` passes until visually accurate.
+
+When setting text content, use raw Unicode characters directly (e.g. `→` not `\u2192`).
+
+Always fetch fresh context per session — the format may change between versions.
+
+### What canvas editing can do
+
+Beyond basic page layout, the command language supports:
+
+- **Colour tokens** — Create color tokens (`ColorStyleTokenNode`) with light/dark mode variants. Reference them across the project for consistent theming.
+- **Text style presets** — Create reusable typography presets (`TextStylePresetNode`) and apply them to text nodes. Build full typographic systems (headings, body, captions, etc.).
+- **Smart components** — Author reusable components (`ComponentNode`) with multiple visual variants, scoped variables, and property controls. Instantiate them anywhere with `ComponentInstanceNode`.
+- **Interactive effects** — Add hover effects (scale, opacity, color), tap effects, scroll-triggered appear animations, transitions between component variants, and event handlers.
+- **Icon sets** — Insert icons from named vector sets. Query available sets and icons via `readProjectForAgent`.
+- **Responsive breakpoints** — Create page breakpoints (Desktop, Tablet, Mobile) using the replica/variant system, with per-breakpoint overrides.
+- **Complex layouts** — Stack and grid layouts with auto-fill, fractional units, space-between distribution, and nested grids for asymmetric layouts.
+
+---
+
 ## Capabilities
 
 What you can do with the Framer CLI:
 
+- **Canvas Editing** For design tasks — creating or editing pages, sections, layouts, recreating designs from screenshots, etc.
 - **CMS**: Create, read, update, delete collections and items. Sync external databases.
-- **Canvas**: Create and modify frames, text, images, SVGs. Build layouts programmatically.
 - **Styles**: Manage color and text styles. Sync design systems.
 - **Code Components**: Create, edit, type-check, and add custom React components to the canvas.
 - **Assets**: Upload and manage images and files.
@@ -680,12 +744,12 @@ What you can do with the Framer CLI:
 - **Data**: Store metadata on nodes and projects for plugin state.
 - **Screenshots**: Capture node screenshots as PNG/JPEG. Export nodes as SVG.
 - **Publishing**: Publish projects, manage deployments, track changes.
+- **Low-level Node APIs**: Create and modify individual nodes. Only use these for targeted, surgical edits to specific nodes — not for building pages or layouts.
 
 ---
 
 ## Known Limitations
 
 - **Pages**: No list, delete, update, move, or settings APIs (create only)
-- **Canvas/design work**: Not viable via API. Can create/read nodes but limited modification support (transforms, constraints, layout)
 - **Code overrides**: Cannot assign overrides to nodes
-
+- **Analytics**: No APIs exist for accessing analytics data

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-dalton",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "type": "module",
   "bin": {
     "framer-dalton": "./dist/cli.js"
@@ -25,7 +25,7 @@
     "@trpc/client": "^11.9.0",
     "@trpc/server": "^11.9.0",
     "commander": "^12.1.0",
-    "framer-api": "^0.1.2-alpha.0",
+    "framer-api": "https://pkg.pr.new/framer/FramerStudio/framer-api@5804b52.tgz",
     "zod": "^4.3.6"
   },
   "devDependencies": {