framer-dalton 0.0.9 → 0.0.11

package/dist/cli.js

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
-import path3 from 'path';
+import fs3 from 'fs';
+import path4 from 'path';
 import { Command } from 'commander';
 import crypto from 'crypto';
 import http from 'http';
 import { spawn, execFile } from 'child_process';
-import fs2 from 'fs';
 import os from 'os';
 import { z } from 'zod';
 import { fileURLToPath } from 'url';
 import { createTRPCClient, httpLink } from '@trpc/client';
 
-/* @framer/ai CLI v0.0.9 */
+/* @framer/ai CLI v0.0.11 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 function openUrl(url) {
@@ -36,20 +36,20 @@ function openUrl(url) {
 __name(openUrl, "openUrl");
 function getConfigDir() {
   if (process.env.XDG_CONFIG_HOME) {
-    return path3.join(process.env.XDG_CONFIG_HOME, "framer");
+    return path4.join(process.env.XDG_CONFIG_HOME, "framer");
   }
   if (process.platform === "win32") {
-    return path3.join(process.env.APPDATA || os.homedir(), "framer");
+    return path4.join(process.env.APPDATA || os.homedir(), "framer");
   }
-  return path3.join(os.homedir(), ".config", "framer");
+  return path4.join(os.homedir(), ".config", "framer");
 }
 __name(getConfigDir, "getConfigDir");
 function getProjectsConfigPath() {
-  return path3.join(getConfigDir(), "projects.json");
+  return path4.join(getConfigDir(), "projects.json");
 }
 __name(getProjectsConfigPath, "getProjectsConfigPath");
 function getLegacyCredentialsPath() {
-  return path3.join(getConfigDir(), "credentials.json");
+  return path4.join(getConfigDir(), "credentials.json");
 }
 __name(getLegacyCredentialsPath, "getLegacyCredentialsPath");
 var ProjectsConfigSchema = z.object({
@@ -65,11 +65,11 @@ var ProjectsConfigSchema = z.object({
 });
 var LegacyCredentialsSchema = z.record(z.string(), z.string());
 function readJsonFile(filePath) {
-  if (!fs2.existsSync(filePath)) {
+  if (!fs3.existsSync(filePath)) {
     return null;
   }
   try {
-    return JSON.parse(fs2.readFileSync(filePath, "utf-8"));
+    return JSON.parse(fs3.readFileSync(filePath, "utf-8"));
   } catch (_error) {
     return null;
   }
@@ -77,14 +77,14 @@ function readJsonFile(filePath) {
 __name(readJsonFile, "readJsonFile");
 function ensureConfigDir() {
   const configDir = getConfigDir();
-  if (!fs2.existsSync(configDir)) {
-    fs2.mkdirSync(configDir, { recursive: true, mode: 448 });
+  if (!fs3.existsSync(configDir)) {
+    fs3.mkdirSync(configDir, { recursive: true, mode: 448 });
   }
 }
 __name(ensureConfigDir, "ensureConfigDir");
 function writeProjectsConfig(config) {
   ensureConfigDir();
-  fs2.writeFileSync(
+  fs3.writeFileSync(
     getProjectsConfigPath(),
     JSON.stringify(config, null, "	"),
     {
@@ -111,7 +111,7 @@ function migrateLegacyCredentials() {
   }
   const config = { version: 2, projects };
   writeProjectsConfig(config);
-  fs2.rmSync(getLegacyCredentialsPath(), { force: true });
+  fs3.rmSync(getLegacyCredentialsPath(), { force: true });
   return config;
 }
 __name(migrateLegacyCredentials, "migrateLegacyCredentials");
@@ -124,7 +124,7 @@ function readProjectsConfig() {
       return result.data;
     }
   }
-  if (fs2.existsSync(getLegacyCredentialsPath())) {
+  if (fs3.existsSync(getLegacyCredentialsPath())) {
     return migrateLegacyCredentials();
   }
   return { version: 2, projects: {} };
@@ -14909,8 +14909,8 @@ ${typeDef}`);
 }
 __name(renderDocs, "renderDocs");
 var __filename$1 = fileURLToPath(import.meta.url);
-var __dirname$1 = path3.dirname(__filename$1);
-var VERSION = "0.0.9" ;
+var __dirname$1 = path4.dirname(__filename$1);
+var VERSION = "0.0.11" ;
 var RELAY_PORT = Number(process.env.FRAMER_CLI_PORT) || 19988;
 var client = createTRPCClient({
   links: [
@@ -14972,7 +14972,7 @@ async function ensureRelayServerRunning(options = {}) {
     logger?.log("Relay server not running, starting it...");
   }
   const isRunningFromSource = __filename$1.endsWith(".ts");
-  const scriptPath = isRunningFromSource ? path3.resolve(__dirname$1, "./start-relay-server.ts") : path3.resolve(__dirname$1, "./start-relay-server.js");
+  const scriptPath = isRunningFromSource ? path4.resolve(__dirname$1, "./start-relay-server.ts") : path4.resolve(__dirname$1, "./start-relay-server.js");
   const serverProcess = spawn(
     isRunningFromSource ? "tsx" : process.execPath,
     [scriptPath],
@@ -14994,16 +14994,37 @@ async function ensureRelayServerRunning(options = {}) {
   throw new Error("Failed to start relay server after 5 seconds");
 }
 __name(ensureRelayServerRunning, "ensureRelayServerRunning");
+var FRAMER_TEMPORARY_DIR = path4.join(os.tmpdir(), "framer");
+function ensureTemporaryDir() {
+  fs3.mkdirSync(FRAMER_TEMPORARY_DIR, { recursive: true });
+}
+__name(ensureTemporaryDir, "ensureTemporaryDir");
+function isTemporaryFile(filePath) {
+  const absolutePath = path4.resolve(filePath);
+  const isInTemporaryDir = absolutePath.startsWith(
+    FRAMER_TEMPORARY_DIR + path4.sep
+  );
+  const isFile = fs3.statSync(absolutePath, { throwIfNoEntry: false })?.isFile() ?? false;
+  return isInTemporaryDir && isFile;
+}
+__name(isTemporaryFile, "isTemporaryFile");
+function removeTemporaryFile(filePath) {
+  fs3.unlinkSync(filePath);
+}
+__name(removeTemporaryFile, "removeTemporaryFile");
+
+// src/skills.ts
 var META_SKILL_NAME = "framer";
 var CODE_COMPONENTS_SKILL_NAME = "framer-code-components";
-var __dirname2 = path3.dirname(fileURLToPath(import.meta.url));
-var skillsDocsDir = path3.join(__dirname2, "..", "docs", "skills");
+var __dirname2 = path4.dirname(fileURLToPath(import.meta.url));
+var skillsDocsDir = path4.join(__dirname2, "..", "docs", "skills");
 function readSkillDoc(name) {
-  return fs2.readFileSync(path3.join(skillsDocsDir, name), "utf-8").trimEnd();
+  return fs3.readFileSync(path4.join(skillsDocsDir, name), "utf-8").trimEnd();
 }
 __name(readSkillDoc, "readSkillDoc");
 function buildMetaSkill() {
-  return `${readSkillDoc("framer.md")}
+  const template = readSkillDoc("framer.md");
+  return `${renderTemplate(template, { FRAMER_TEMPORARY_DIR })}
 `;
 }
 __name(buildMetaSkill, "buildMetaSkill");
@@ -15033,36 +15054,37 @@ function buildProjectCanvasSkill(projectId, agentContext, canvasPrompt) {
     PROJECT_ID: projectId,
     GENERATED_AT: (/* @__PURE__ */ new Date()).toISOString(),
     CANVAS_PROMPT: canvasPrompt.trimEnd(),
-    AGENT_CONTEXT: agentContext.trimEnd()
+    AGENT_CONTEXT: agentContext.trimEnd(),
+    FRAMER_TEMPORARY_DIR
   })}
 `;
   return { skillName, content };
 }
 __name(buildProjectCanvasSkill, "buildProjectCanvasSkill");
 function writeSkill(root, skillName, content) {
-  fs2.mkdirSync(root, { recursive: true });
-  const rootStat = fs2.statSync(root);
+  fs3.mkdirSync(root, { recursive: true });
+  const rootStat = fs3.statSync(root);
   if (!rootStat.isDirectory()) {
     throw new Error(`Skill root is not a directory: ${root}`);
   }
-  const skillDir = path3.join(root, skillName);
-  const filePath = path3.join(skillDir, "SKILL.md");
-  if (fs2.existsSync(skillDir)) {
-    const current = fs2.lstatSync(skillDir);
+  const skillDir = path4.join(root, skillName);
+  const filePath = path4.join(skillDir, "SKILL.md");
+  if (fs3.existsSync(skillDir)) {
+    const current = fs3.lstatSync(skillDir);
     if (current.isSymbolicLink() || !current.isDirectory()) {
-      fs2.rmSync(skillDir, { recursive: true, force: true });
+      fs3.rmSync(skillDir, { recursive: true, force: true });
     }
   }
-  fs2.mkdirSync(skillDir, { recursive: true });
-  fs2.writeFileSync(filePath, content, "utf-8");
+  fs3.mkdirSync(skillDir, { recursive: true });
+  fs3.writeFileSync(filePath, content, "utf-8");
   return filePath;
 }
 __name(writeSkill, "writeSkill");
 function getDefaultSkillRoots() {
   const home = os.homedir();
   return [
-    path3.join(home, ".agents", "skills"),
-    path3.join(home, ".claude", "skills")
+    path4.join(home, ".agents", "skills"),
+    path4.join(home, ".claude", "skills")
   ];
 }
 __name(getDefaultSkillRoots, "getDefaultSkillRoots");
@@ -15111,8 +15133,8 @@ function printSetupSummary(results) {
   const installLocations = /* @__PURE__ */ new Set();
   for (const result of results) {
     for (const filePath of result.paths) {
-      const skillDir = path3.dirname(filePath);
-      const root = path3.dirname(skillDir);
+      const skillDir = path4.dirname(filePath);
+      const root = path4.dirname(skillDir);
       installLocations.add(root);
     }
   }
@@ -15214,9 +15236,21 @@ async function ensureRelayForCli() {
   }
 }
 __name(ensureRelayForCli, "ensureRelayForCli");
-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;
+program.option("-s, --session <id>", "Session ID (required for code execution)").option("-e, --eval <code>", "Code to execute (or pipe via stdin)").option("-f, --file <path>", "File containing code to execute").action(async (options) => {
+  const { session: sessionId, eval: evalCode, file: filePath } = options;
+  ensureTemporaryDir();
   let code = evalCode;
+  if (!code && filePath) {
+    try {
+      code = fs3.readFileSync(filePath, "utf-8");
+    } catch (err) {
+      printError(`Failed to read file: ${formatError(err)}`);
+      process.exit(1);
+    }
+    if (isTemporaryFile(filePath)) {
+      removeTemporaryFile(filePath);
+    }
+  }
   if (!code && !process.stdin.isTTY) {
     code = await readStdin();
   }

package/dist/start-relay-server.js

@@ -13,9 +13,50 @@ import { createRequire } from 'module';
 import * as vm from 'vm';
 import { connect } from 'framer-api';
 
-/* @framer/ai relay server v0.0.9 */
+/* @framer/ai relay server v0.0.11 */
 var __defProp = Object.defineProperty;
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __using = (stack, value, async) => {
+  if (value != null) {
+    if (typeof value !== "object" && typeof value !== "function") __typeError("Object expected");
+    var dispose, inner;
+    if (dispose === void 0) {
+      dispose = value[__knownSymbol("dispose")];
+    }
+    if (typeof dispose !== "function") __typeError("Object not disposable");
+    if (inner) dispose = function() {
+      try {
+        inner.call(this);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+    };
+    stack.push([async, dispose, value]);
+  }
+  return value;
+};
+var __callDispose = (stack, error, hasError) => {
+  var E = typeof SuppressedError === "function" ? SuppressedError : function(e, s, m, _) {
+    return _ = Error(m), _.name = "SuppressedError", _.error = e, _.suppressed = s, _;
+  };
+  var fail = (e) => error = hasError ? new E(e, error, "An error was suppressed during disposal") : (hasError = true, e);
+  var next = (it) => {
+    while (it = stack.pop()) {
+      try {
+        var result = it[1] && it[1].call(it[2]);
+        if (it[0]) return Promise.resolve(result).then(next, (e) => (fail(e), next()));
+      } catch (e) {
+        fail(e);
+      }
+    }
+    if (hasError) throw error;
+  };
+  return next();
+};
 function getLogPath() {
   if (process.env.XDG_STATE_HOME) {
     return path.join(process.env.XDG_STATE_HOME, "framer", "relay.log");
@@ -50,7 +91,7 @@ function log(message) {
 __name(log, "log");
 var __filename$1 = fileURLToPath(import.meta.url);
 path.dirname(__filename$1);
-var VERSION = "0.0.9" ;
+var VERSION = "0.0.11" ;
 var RELAY_PORT = Number(process.env.FRAMER_CLI_PORT) || 19988;
 createTRPCClient({
   links: [
@@ -415,25 +456,24 @@ async function execute(session, framer, code, options = {}) {
   }
 }
 __name(execute, "execute");
-async function executeWithReconnect(session, framer, code, options, reconnect) {
+async function executeWithReconnect(session, framer, code, options, reconnect, execId) {
   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 reqId = framer.requestId;
+  const tag = `exec=${execId} session=${session.id}${reqId ? ` req=${reqId}` : ""}`;
+  log(`reconnect ${tag} project=${session.projectId} reason="${result.error}"`);
   const newFramer = await reconnect();
   if (!newFramer) {
-    log(
-      `reconnect.failed session=${session.id} error="no connection returned"`
-    );
+    log(`reconnect.failed ${tag} error="no connection returned"`);
     return {
       output: [],
       error: "Connection lost and failed to reconnect"
     };
   }
-  log(`reconnect.success session=${session.id}`);
+  const newReqId = newFramer.requestId;
+  log(`reconnect.success ${tag}${newReqId ? ` new_req=${newReqId}` : ""}`);
   return tryExecute(session, newFramer, code, options);
 }
 __name(executeWithReconnect, "executeWithReconnect");
@@ -481,12 +521,17 @@ var ConnectionPool = class {
     const entry = this.pool.get(projectId);
     if (entry) {
       entry.sessions.add(session);
+      if (!entry.connected) {
+        await entry.connection.reconnect();
+        entry.connected = true;
+      }
       return entry.connection;
     }
     const connection = await connect(projectId, apiKey);
     this.pool.set(projectId, {
       connection,
-      sessions: /* @__PURE__ */ new Set([session])
+      sessions: /* @__PURE__ */ new Set([session]),
+      connected: true
     });
     return connection;
   }
@@ -515,11 +560,26 @@ var ConnectionPool = class {
     if (!entry) return null;
     try {
       await entry.connection.reconnect();
+      entry.connected = true;
       return entry.connection;
     } catch {
       return null;
     }
   }
+  /**
+   * Disconnect a project's connection without removing sessions.
+   * The next exec will trigger a reconnect via executeWithReconnect.
+   */
+  async disconnect(projectId) {
+    const entry = this.pool.get(projectId);
+    if (!entry || !entry.connected) return;
+    entry.connected = false;
+    await entry.connection.disconnect();
+  }
+  isConnected(projectId) {
+    const entry = this.pool.get(projectId);
+    return entry?.connected ?? false;
+  }
   /**
    * Release a session from a connection.
    * If no sessions remain, the connection is disconnected and removed.
@@ -548,11 +608,14 @@ var ConnectionPool = class {
 var connectionPool = new ConnectionPool();
 
 // src/session-manager.ts
+var SESSION_IDLE_TIMEOUT_MS = 60 * 1e3;
+var SESSION_IDLE_CHECK_INTERVAL_MS = 30 * 1e3;
 var SessionManager = class {
   static {
     __name(this, "SessionManager");
   }
   sessions = /* @__PURE__ */ new Map();
+  idleCheck = null;
   async create(projectId, apiKey) {
     let id = 1;
     while (this.sessions.has(String(id))) {
@@ -562,9 +625,13 @@ var SessionManager = class {
       id: String(id),
       projectId,
       apiKey,
-      state: {}
+      state: {},
+      lastActivityAt: 0,
+      inflight: 0
     };
+    this.startIdleCheck();
     await connectionPool.acquire(projectId, apiKey, session);
+    session.lastActivityAt = Date.now();
     this.sessions.set(String(id), session);
     return String(id);
   }
@@ -581,9 +648,27 @@ var SessionManager = class {
   getFramer(session) {
     return connectionPool.getConnection(session.projectId);
   }
+  isConnected(session) {
+    return connectionPool.isConnected(session.projectId);
+  }
   async reconnect(session) {
     return connectionPool.reconnect(session.projectId);
   }
+  /** Marks session as actively executing. Dispose to release. */
+  exec(id) {
+    const session = this.sessions.get(id);
+    if (session) {
+      session.inflight++;
+    }
+    return {
+      [Symbol.dispose]: () => {
+        if (session) {
+          session.inflight--;
+          session.lastActivityAt = Date.now();
+        }
+      }
+    };
+  }
   async destroy(id) {
     const session = this.sessions.get(id);
     if (!session) {
@@ -591,17 +676,66 @@ var SessionManager = class {
     }
     await connectionPool.release(session.projectId, session);
     this.sessions.delete(id);
+    if (this.sessions.size === 0) {
+      this.stopIdleCheck();
+    }
   }
   async destroyAll() {
     for (const id of this.sessions.keys()) {
       await this.destroy(id);
     }
   }
+  startIdleCheck() {
+    if (this.idleCheck) return;
+    this.idleCheck = setInterval(() => {
+      this.reapIdleSessions().catch((err) => {
+        log(`reap error: ${err instanceof Error ? err.message : err}`);
+      });
+    }, SESSION_IDLE_CHECK_INTERVAL_MS);
+    this.idleCheck.unref();
+  }
+  stopIdleCheck() {
+    if (this.idleCheck) {
+      clearInterval(this.idleCheck);
+      this.idleCheck = null;
+    }
+  }
+  async reapIdleSessions() {
+    const now = Date.now();
+    const projectSessions = /* @__PURE__ */ new Map();
+    for (const session of this.sessions.values()) {
+      const existing = projectSessions.get(session.projectId);
+      if (existing) existing.push(session);
+      else projectSessions.set(session.projectId, [session]);
+    }
+    const disconnects = [];
+    for (const [projectId, sessions] of projectSessions) {
+      if (!connectionPool.isConnected(projectId)) continue;
+      const allIdle = sessions.every(
+        (s) => s.inflight === 0 && now - s.lastActivityAt >= SESSION_IDLE_TIMEOUT_MS
+      );
+      if (!allIdle) continue;
+      const reqId = connectionPool.getConnection(projectId)?.requestId;
+      log(
+        `idle disconnect project=${projectId}${reqId ? ` req=${reqId}` : ""}`
+      );
+      disconnects.push(connectionPool.disconnect(projectId));
+    }
+    const results = await Promise.allSettled(disconnects);
+    for (const result of results) {
+      if (result.status === "rejected") {
+        log(
+          `disconnect error: ${result.reason instanceof Error ? result.reason.message : result.reason}`
+        );
+      }
+    }
+  }
 };
 var sessionManager = new SessionManager();
 
 // src/router.ts
 var t = initTRPC.create();
+var nextExecId = 0;
 var appRouter = t.router({
   version: t.procedure.query(() => {
     return { version: VERSION };
@@ -633,35 +767,52 @@ var appRouter = t.router({
       cwd: z.string().optional()
     })
   ).mutation(async ({ input }) => {
-    const { sessionId, code, cwd } = input;
-    const session = sessionManager.get(sessionId);
-    if (!session) {
-      throw new TRPCError({
-        code: "NOT_FOUND",
-        message: `Session ${sessionId} not found`
-      });
-    }
-    log(
-      `exec session=${sessionId} code=${JSON.stringify(code).slice(0, 100)}`
-    );
-    const framer = sessionManager.getFramer(session);
-    if (!framer) {
-      return {
-        output: [],
-        error: "Failed to get connection for session"
-      };
-    }
-    const result = await executeWithReconnect(
-      session,
-      framer,
-      code,
-      { cwd },
-      () => sessionManager.reconnect(session)
-    );
-    if (result.error) {
-      log(`exec.error session=${sessionId} error="${result.error}"`);
+    var _stack = [];
+    try {
+      const { sessionId, code, cwd } = input;
+      const session = sessionManager.get(sessionId);
+      if (!session) {
+        throw new TRPCError({
+          code: "NOT_FOUND",
+          message: `Session ${sessionId} not found`
+        });
+      }
+      const _guard = __using(_stack, sessionManager.exec(sessionId));
+      const execId = nextExecId++;
+      let framer = sessionManager.getFramer(session);
+      if (framer && !sessionManager.isConnected(session)) {
+        log(
+          `exec.reconnect exec=${execId} session=${sessionId} reason="idle disconnected"`
+        );
+        framer = await sessionManager.reconnect(session);
+      }
+      const reqId = framer?.requestId;
+      const tag = `exec=${execId} session=${sessionId}${reqId ? ` req=${reqId}` : ""}`;
+      log(`exec ${tag} code=${JSON.stringify(code).slice(0, 100)}`);
+      if (!framer) {
+        log(`exec.error ${tag} error="no connection"`);
+        return {
+          output: [],
+          error: "Failed to get connection for session"
+        };
+      }
+      const result = await executeWithReconnect(
+        session,
+        framer,
+        code,
+        { cwd },
+        () => sessionManager.reconnect(session),
+        execId
+      );
+      if (result.error) {
+        log(`exec.error ${tag} error="${result.error}"`);
+      }
+      return result;
+    } catch (_) {
+      var _error = _, _hasError = true;
+    } finally {
+      __callDispose(_stack, _error, _hasError);
     }
-    return result;
   }),
   shutdown: t.procedure.mutation(() => {
     log("shutdown requested");
@@ -672,11 +823,25 @@ var appRouter = t.router({
 });
 
 // src/relay-server.ts
+var IDLE_TIMEOUT_MS = 24 * 60 * 60 * 1e3;
+var IDLE_CHECK_INTERVAL_MS = 60 * 1e3;
 var trpcHandler = createHTTPHandler({ router: appRouter });
 async function startRelayServer(port = RELAY_PORT) {
+  let lastActivityAt = Date.now();
   const server = http.createServer((req, res) => {
+    lastActivityAt = Date.now();
     trpcHandler(req, res);
   });
+  const idleCheck = setInterval(() => {
+    const idleMs = Date.now() - lastActivityAt;
+    if (idleMs >= IDLE_TIMEOUT_MS) {
+      log(`idle for ${Math.round(idleMs / 1e3)}s, shutting down`);
+      clearInterval(idleCheck);
+      server.close();
+      process.exit(0);
+    }
+  }, IDLE_CHECK_INTERVAL_MS);
+  idleCheck.unref();
   return new Promise((resolve, reject) => {
     server.on("error", reject);
     server.listen(port, "127.0.0.1", () => {

package/docs/skills/framer-canvas-editing-project.md

@@ -1,7 +1,7 @@
 ---
 name: {{SKILL_NAME}}
 description: "Project-scoped Framer canvas editing skill for project {{PROJECT_ID}}. Very important: never load this skill without having already read the `framer` skill and without having already run `session new`, which will dynamically update this skill."
-allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)"]
+allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
 ---
 
 ## Project Scope
@@ -27,26 +27,26 @@ allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)"]
 ## Workflow Loop
 
 ```bash
-# 1) Read page structure first
-framer -s <sessionId> <<'EOF'
-const { results } = await framer.readProjectForAgent(
-  [{ type: "page", path: "/" }],
-  { pagePath: "/" }
-);
+# 1) Read page structure first — write code to a unique file, then execute with -f
+# {{FRAMER_TEMPORARY_DIR}}/<sessionId>-read-page.js:
+#   const { results } = await framer.readProjectForAgent(
+#     [{ type: "page", path: "/" }],
+#     { pagePath: "/" }
+#   );
+#   console.log(results);
 
-console.log(results);
-EOF
+framer -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-read-page.js
 
 # 2) Request additional targeted queries only if needed
 
 # 3) Apply changes in a later call, once `dsl` has been prepared
-framer -s <sessionId> <<'EOF'
-const dsl = `
-...your canvas DSL...
-`;
+# {{FRAMER_TEMPORARY_DIR}}/<sessionId>-apply-changes.js:
+#   const dsl = `
+#   ...your canvas DSL...
+#   `;
+#   await framer.applyAgentChanges(dsl, { pagePath: "/" });
 
-await framer.applyAgentChanges(dsl, { pagePath: "/" });
-EOF
+framer -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-apply-changes.js
 ```
 
 ## Live Agent System Prompt
@@ -61,6 +61,6 @@ This is the static canvas-editing prompt returned by `framer.getAgentSystemPromp
 
 ## Live Agent Context (/)
 
-This is the dynamic project context returned by `framer.getAgentContext({ pagePath: "/" })`. It contains project-specific data for the current page, including available fonts, components and their controls, design tokens, style presets, and icon sets.
+This is the dynamic project context returned by `framer.getAgentContext({ pagePath: "/" })`. It contains project-specific data for the current page, including available fonts, available components, design tokens, style presets, and icon sets.
 
 {{AGENT_CONTEXT}}

package/docs/skills/framer.md

@@ -3,7 +3,7 @@ name: framer
 description: >
   Use when the user wants to design, edit, or publish a website or web page — creating layouts, editing sections, updating text or images, managing CMS collections and content, syncing external data, creating or modifying code components, managing color and text styles, handling localization, or publishing deployments. Trigger when the user mentions Framer, references their website or web pages, asks to edit designs, update site content, or work with any Framer project — even if they don't explicitly say 'Framer'. 
   **Mandatory precondition**: run `npx framer-dalton@latest setup` and let it complete **BEFORE** loading this skill.
-allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)"]
+allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
 ---
 
 If you didn't run this command before loading the skill, run it now:
@@ -59,10 +59,10 @@ npx framer-dalton docs Collection.getItems  # What are the parameters and return
 
 #### 3. Execute code
 
-Only after checking docs:
+Only after checking docs, write your code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/` and execute with `-f`. Name each file `<sessionId>-<short-summary>.js` where `<short-summary>` is a brief kebab-case description (e.g., `1-read-collections.js`, `1-add-team-member.js`). Files are automatically deleted after execution.
 
 ```bash
-npx framer-dalton -s 1 -e "state.collections = await framer.getCollections(); console.log(state.collections.length)"
+npx framer-dalton -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-read-collections.js
 ```
 
 #### 4. Store results in `state`
@@ -90,13 +90,23 @@ Always save results you'll need again. Don't repeat API calls.
 
 **Always store results in `state` when you'll need them again.** API calls are slow - don't repeat them.
 
+```js
+// {{FRAMER_TEMPORARY_DIR}}/1-get-collections.js
+state.collections = await framer.getCollections();
+```
+
 ```bash
-# First call: fetch and store
-npx framer-dalton -s 1 -e "state.collections = await framer.getCollections()"
+npx framer-dalton -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-collections.js
+```
 
-# Later calls: reuse from state
-npx framer-dalton -s 1 -e "const team = state.collections.find(c => c.name === 'Team')"
-npx framer-dalton -s 1 -e "state.teamItems = await state.collections.find(c => c.name === 'Team').getItems()"
+```js
+// {{FRAMER_TEMPORARY_DIR}}/1-get-team-items.js — reuse from state
+state.teamItems = await state.collections.find(c => c.name === 'Team').getItems();
+console.log(state.teamItems.length);
+```
+
+```bash
+npx framer-dalton -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-team-items.js
 ```
 
 Store anything you'll reference again.
@@ -132,55 +142,10 @@ After session creation, load the dynamically created project-scoped skill `frame
 
 ## Execute Code
 
-```bash
-npx framer-dalton -s <sessionId> -e "<code>"
-```
-
-**Escaping:** For code containing `$` (e.g. `$control__` properties), HTML, or nested quotes, use a heredoc (see below). `-e "..."` works for everything else, including multiline.
-
-**Examples:**
+Write your code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/` and execute with `-f`:
 
 ```bash
-# Fetch collections and store in state (always store results you'll reuse)
-npx framer-dalton -s 1 -e "state.collections = await framer.getCollections(); console.log(state.collections.map(c => c.name))"
-
-# Use stored data in subsequent calls
-npx framer-dalton -s 1 -e "state.team = state.collections.find(c => c.name === 'Team')"
-npx framer-dalton -s 1 -e "state.teamItems = await state.team.getItems(); console.log(state.teamItems.length)"
-```
-
-**Multiline code with heredoc (recommended for complex strings):**
-
-For code containing HTML, quotes, or special characters, use a heredoc to avoid escaping issues:
-
-```bash
-npx framer-dalton -s 1 <<'EOF'
-const translations = {
-  "node-id": "<h2>Ship's Treasures</h2>",
-  "other-id": "<p>Text with "quotes" and <tags></p>"
-};
-await framer.setLocalizationData({ valuesBySource: translations });
-EOF
-```
-
-The `<<'EOF'` syntax (with quotes around EOF) prevents shell interpolation.
-
-**Alternative: pipe from file:**
-
-```bash
-cat script.js | npx framer-dalton -s 1
-```
-
-**Multiline inline code:**
-
-```bash
-npx framer-dalton -s 1 -e "
-const collections = await framer.getCollections();
-for (const c of collections) {
-  const items = await c.getItems();
-  console.log(c.name, items.length);
-}
-"
+npx framer-dalton -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-<short-summary>.js
 ```
 
 ## API Documentation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-dalton",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "type": "module",
   "bin": {
     "framer-dalton": "./dist/cli.js"