framer-dalton 0.0.23 → 0.0.25

package/dist/start-relay-server.js

@@ -2,18 +2,19 @@ import fs4 from 'fs';
 import os from 'os';
 import path from 'path';
 import 'child_process';
+import 'net';
 import { fileURLToPath } from 'url';
 import { createTRPCClient, httpLink } from '@trpc/client';
 import crypto, { randomUUID, timingSafeEqual } from 'crypto';
 import http from 'http';
 import { createHTTPHandler } from '@trpc/server/adapters/standalone';
 import { initTRPC, TRPCError } from '@trpc/server';
+import { connect, FramerAPIError } from 'framer-api';
 import { z } from 'zod';
-import { connect } from 'framer-api';
 import { createRequire } from 'module';
 import * as vm from 'vm';
 
-/* @framer/ai relay server v0.0.23 */
+/* @framer/ai relay server v0.0.25 */
 var __defProp = Object.defineProperty;
 var __knownSymbol = (name2, symbol) => (symbol = Symbol[name2]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name2);
 var __typeError = (msg) => {
@@ -159,7 +160,7 @@ __name(debug, "debug");
 // src/version.ts
 var VERSION = (
   // typeof is used to ensure this can be used just via tsx or node etc. without build
-  "0.0.23" 
+  "0.0.25" 
 );
 
 // src/relay-client.ts
@@ -391,6 +392,19 @@ var ScopedFS = class {
   }
   constants = fs4.constants;
 };
+function getErrorRef(error) {
+  if (!(error instanceof Error)) return void 0;
+  const ref = error.ref;
+  return typeof ref === "string" && ref.length > 0 ? ref : void 0;
+}
+__name(getErrorRef, "getErrorRef");
+function formatError(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+__name(formatError, "formatError");
 
 // src/execute.ts
 var EXECUTION_TIMEOUT = 10 * 60 * 1e3;
@@ -530,9 +544,11 @@ async function execute(session, code, options = {}) {
     if (isConnectionError(errorMessage)) {
       session.connection.markDisconnected();
     }
+    const errorRef = getErrorRef(err);
     return {
       output,
-      error: errorMessage
+      error: errorMessage,
+      ...errorRef ? { errorRef } : {}
     };
   } finally {
     if (timeoutId) clearTimeout(timeoutId);
@@ -546,10 +562,13 @@ async function executeWithReconnect(session, code, options, execId) {
     );
     try {
       await session.connection.reconnect();
-    } catch {
+    } catch (err) {
+      const inner = err instanceof Error ? err.message : String(err);
+      const errorRef = getErrorRef(err);
       return {
         output: [],
-        error: "Failed to get connection for session"
+        error: `Failed to get connection for session: ${inner}`,
+        ...errorRef ? { errorRef } : {}
       };
     }
   }
@@ -562,13 +581,16 @@ async function executeWithReconnect(session, code, options, execId) {
   );
   try {
     await session.connection.reconnect();
-  } catch {
+  } catch (err) {
+    const inner = err instanceof Error ? err.message : String(err);
+    const errorRef = getErrorRef(err);
     log(
-      `reconnect.failed exec=${execId} session=${session.id} req=${session.connection.framer.requestId} error="reconnect failed"`
+      `reconnect.failed exec=${execId} session=${session.id} req=${session.connection.framer.requestId} error="${inner}"`
     );
     return {
       output: [],
-      error: "Connection lost and failed to reconnect"
+      error: `Connection lost and failed to reconnect: ${inner}`,
+      ...errorRef ? { errorRef } : {}
     };
   }
   log(
@@ -1156,7 +1178,17 @@ var SessionManager = class {
 var sessionManager = new SessionManager();
 
 // src/router.ts
-var t = initTRPC.create();
+var t = initTRPC.create({
+  errorFormatter({ shape, error }) {
+    const cause = error.cause;
+    if (cause instanceof FramerAPIError) {
+      const framerApi = { code: cause.code };
+      if (cause.ref !== void 0) framerApi.ref = cause.ref;
+      return { ...shape, data: { ...shape.data, framerApi } };
+    }
+    return shape;
+  }
+});
 var nextExecId = 0;
 var appRouter = t.router({
   version: t.procedure.query(() => {
@@ -1192,7 +1224,7 @@ var appRouter = t.router({
       });
       return { id: session.id };
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
+      const message = formatError(err);
       trackError({
         errorType: "session_create_error",
         projectId: input.projectId,
@@ -1201,7 +1233,8 @@ var appRouter = t.router({
       });
       throw new TRPCError({
         code: isAuthError(message) ? "UNAUTHORIZED" : "INTERNAL_SERVER_ERROR",
-        message
+        message,
+        cause: err
       });
     }
   }),

package/docs/skills/framer-code-components.md

@@ -1,6 +1,6 @@
 ---
 name: framer-code-components
-description: "Framer code component implementation guidance, platform constraints, layout annotations, property controls, and authoring best practices. Use only after loading the framer skill first in the same task; never load this skill directly as the entry point."
+description: "Framer code component implementation guidance, platform constraints, layout annotations, property controls, and authoring best practices. Use only after loading the framer skill and the generated framer-project-<projectId> skill first in the same task; never load this skill directly as the entry point."
 ---
 
 # Framer Code Components

package/docs/skills/framer-project.md

@@ -0,0 +1,426 @@
+---
+name: {{SKILL_NAME}}
+description: "Project-scoped Framer skill for project {{PROJECT_ID}}. Covers project reads, edits, change review, publishing, image sourcing, component operations, and canvas editing. 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:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
+---
+
+## Project Scope
+
+- Project ID: {{PROJECT_ID}}
+- Generated At: {{GENERATED_AT}}
+
+## Required Workflow
+
+Every connected-project task follows these steps:
+
+### 1. Look up the API (before EVERY new use of an API method)
+
+**You MUST run `npx framer-dalton docs` before writing any code.** Do not guess method names or signatures.
+
+```bash
+npx framer-dalton docs Collection           # What methods exist?
+npx framer-dalton docs Collection.getItems  # What are the parameters and return type?
+```
+
+### 2. Execute code
+
+Only after checking docs, use your write tool to write your code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/`, then execute it with `-f`. Do not create code files with shell heredocs or `cat`. 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`).
+
+```bash
+npx framer-dalton exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-read-collections.js
+```
+
+### 3. Store results in `state`
+
+Always save results you'll need again. Don't repeat API calls.
+
+## Method Selection
+
+Use agent-specific methods whenever a plugin API method and an agent method overlap:
+
+- Use `readProjectForAgent`, `getNodeForAgent`, `getNodesForAgent`, `getNodesOfTypesForAgent`, `getScopeNodeForAgent`, `getGroundNodeForAgent`, `getParentNodeForAgent`, `getAncestorsForAgent`, `serializeForAgent`, `serializeNodesForAgent`, and `paginateForAgent` for project tree reads.
+- Use `applyAgentChanges` for page and layout edits. Do not use low-level node APIs like `createNode`, `setAttributes`, or `setRect` for design/layout work.
+- Use `publishForAgent` for publishing. Do not use `publish`, `getDeployments`, or `deploy` for normal agent publishing flows.
+
+Use the plugin API for capabilities that do not have an agent-specific counterpart, such as code file management, localization, and redirects.
+
+During normal task execution, do not call `framer.getAgentSystemPrompt()` or `framer.getAgentContext()`. This skill already includes their output.
+
+## Core Usage Principles
+
+- Be concise. Don't narrate implementation details like field IDs, escaping, or internal steps. Just do the work and report what was accomplished in user-facing terms.
+- Use `framer.*` for plugin API calls. Top-level methods are not globals.
+- Before making changes that add/update/delete content that the user has not clearly and explicitly requested in this conversation, inform the user of what you plan to do and why, and ask them to confirm.
+    - You do not need to ask for confirmation when carrying out a specific add/update/delete change that the user has already clearly requested (this counts as explicit consent).
+    - You do not need to explain or ask for confirmation for non-destructive calls like reading project state.
+    - If the exact action was not agreed upon, or you are inferring a broader change or choosing between multiple reasonable options using your own judgment, ask for confirmation.
+    - Always ask for confirmation before destructive actions that the user did not explicitly request - especially deletes, cleanup, resets, or broad removals inferred by the agent.
+
+## Compaction
+
+**Critical**: if an agent conversation is compacted, you MUST read the entirety of this skill back into context. This is non-negotiable and this instruction itself must not be lost during compaction.
+
+## Context Variables
+
+- `framer` - Connected Framer Server API instance
+- `state` - Object persisted between calls within your session
+- `console` - For output (`console.log`, `console.error`)
+- `require` - Sandboxed Node.js modules: fs, path, url, crypto, buffer, util, os
+- Standard globals: `fetch`, `Buffer`, `URL`, `crypto`, `setTimeout`
+
+**Note:** `fs` operations are sandboxed to cwd, /tmp, and os.tmpdir().
+
+## Use `state` to Avoid Repeated 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
+npx framer-dalton exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-collections.js
+```
+
+```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 exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-team-items.js
+```
+
+Store anything you'll reference again.
+
+## Canvas Editing: Alternative Approach (“Prompt the Framer agent”)
+
+Use this approach only if the user asks for it. Do not mention this approach to the user otherwise.
+
+This approach is called “Prompt the Framer agent”. With this approach, use `framer.startAgentConversation()` to start a stateful design subagent. Keep the `conversationId` it returns in `state`, and call `framer.continueAgentConversation()` with it to continue the same design task.
+
+Do not call `framer.getAgentSystemPrompt()` or `framer.getAgentContext()` or `framer.applyAgentChanges()` with this approach.
+
+Example:
+
+```js
+state.agent ??= {};
+const first = await framer.startAgentConversation(
+  "Build me a landing page based on the attached screenshot",
+  {
+    pagePath: "/",
+    imageUrls: ["https://example.com/image.png"],
+    // selectionNodeIds: [...]
+  },
+);
+state.agent.conversationId = first.conversationId;
+console.log(first.responseMessages);
+
+const second = await framer.continueAgentConversation("Now make it pink", {
+  conversationId: state.agent.conversationId,
+  selectionNodeIds: ["someNodeId"],
+  // imageUrls: [...],
+  // changing pagePath or model is not supported
+});
+console.log(second.responseMessages);
+```
+
+Prompting may take a while to complete, so set the command timeout to 10 minutes.
+
+## Execute Code
+
+Prefer using your write tool to write code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/` and executing it with `-f`. Do not create code files with shell heredocs or `cat`:
+
+```bash
+npx framer-dalton exec -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-<short-summary>.js
+```
+
+For short snippets, `exec` also accepts `-e <code>` or code piped on stdin.
+
+## Shell Quoting
+
+In Windows PowerShell, if an argument contains nested quotes, use a single-quoted here-string and pass the variable. Do not backslash-escape quotes.
+
+```powershell
+$value = @'
+[{"key":"value","filter":["text","$rect"]}]
+'@
+npx framer-dalton <command> --option $value
+```
+
+## API Documentation
+
+```bash
+npx framer-dalton docs                            # List all available methods
+npx framer-dalton docs framer.getCollections      # Show top level method
+npx framer-dalton docs Collection                 # Show class with all method signatures
+npx framer-dalton docs Collection.addItems        # Show method + recursively expand all referenced types
+npx framer-dalton docs ScreenshotOptions          # Show type + recursively expand all referenced types
+```
+
+`docs` with no arguments lists available methods. Looking up a class shows its full definition without expanding referenced types. Looking up a specific method or type automatically expands all referenced types recursively.
+
+## API Examples
+
+**STOP: These are patterns only. Before using any method below, run `npx framer-dalton docs <ClassName>` to verify the current signature.**
+
+### Working with Collections (CMS)
+
+Collections are Framer's CMS. Each collection has fields (columns) and items (rows). Use the plugin Collection API (the methods below) for collection schema and item CRUD.
+
+**Exception — CMS Collection Lists.** The in-canvas construct that *renders* a collection as a repeating list of cards (the "Collection List" / repeater) is an agent/page concern. Build and edit those through `readProjectForAgent` and `applyAgentChanges`, not the plugin API. Use the plugin Collection API to read available collections and field schema first, then drive the list through the project-scoped skill.
+
+#### Reading Collections
+
+```js
+// Get all collections
+const collections = await framer.getCollections();
+console.log(collections.map((c) => ({ name: c.name, id: c.id })));
+
+// Get a specific collection by ID
+const collection = await framer.getCollection("collection-id");
+
+// Get fields (columns) - returns array of { id, type, name }
+const fields = await collection.getFields();
+console.log(fields);
+// [{ id: "BnNuS2i3o", type: "string", name: "Title" }, ...]
+
+// Get items (rows)
+const items = await collection.getItems();
+console.log(items);
+// [{ id: "XTM8FSHGs", slug: "post-1", draft: false, fieldData: {...} }, ...]
+```
+
+#### Sync external data to collection
+
+```js
+const collection = await framer.getCollection("collection-id");
+const existing = await collection.getItems();
+const existingIds = new Set(existing.map((i) => i.id));
+
+const externalData = await fetch("https://api.example.com/posts").then((r) =>
+  r.json(),
+);
+
+const items = externalData.map((post) => ({
+  id: post.id,
+  slug: post.slug,
+  fieldData: { title: post.title, content: post.body },
+}));
+
+await collection.addItems(items);
+
+// Remove items no longer in external source
+const newIds = new Set(items.map((i) => i.id));
+const toRemove = [...existingIds].filter((id) => !newIds.has(id));
+if (toRemove.length) await collection.removeItems(toRemove);
+
+await collection.setPluginData("lastSync", new Date().toISOString());
+```
+
+#### Field Types
+
+`boolean`, `color`, `number`, `string`, `formattedText` (HTML), `image`, `file`, `link`, `date`, `enum`, `collectionReference`, `multiCollectionReference`, `array` (galleries)
+
+#### Updating Collection Items
+
+```js
+// Add or update items (if id matches existing item, it updates)
+await collection.addItems([
+  {
+    id: "new-item-1",
+    slug: "hello-world",
+    fieldData: { titleFieldId: "Hello World" },
+  },
+]);
+
+// Remove items
+await collection.removeItems(["item-id-1", "item-id-2"]);
+
+// Reorder items
+const ids = items.map((i) => i.id).reverse();
+await collection.setItemOrder(ids);
+```
+
+#### Working with CollectionItem
+
+```js
+const items = await collection.getItems();
+const item = items[0];
+
+// Update item attributes
+await item.setAttributes({ slug: "new-slug" });
+
+// Navigate to item in Framer UI
+await item.navigateTo();
+
+// Remove item
+await item.remove();
+```
+
+### Working with Images
+
+Canvas editing accepts image URLs directly when setting an image fill, so the typical task is to obtain a URL and pass it through to the project-scoped skill.
+
+There are three sources you'll typically pull URLs from:
+
+**Stock photography.** Use `framer.queryImagesForAgent` to source candidates and stash the URL you want:
+
+```js
+const { results } = await framer.queryImagesForAgent({
+  source: "unsplash",
+  query: "snow-capped mountains",
+  count: 4,
+  orientation: "landscape",
+});
+state.heroUrl = results[0].url;
+```
+
+**An external URL the user provided.** Pass it through directly. If you'll reuse the same image across many edits, upload it once and stash the resulting asset URL to avoid re-resolving the source on every change:
+
+```js
+state.heroUrl = (await framer.uploadImage({
+  image: "https://example.com/hero.png",
+  altText: "Mountain range at sunset",
+})).url;
+```
+
+**An image already on the canvas.** Read the node and reuse its existing image URL:
+
+```js
+const node = await framer.getNodeForAgent({ id: "<image-node-id>" });
+state.heroUrl = node.attributes.fill;
+```
+
+For inline SVGs, use the plugin method directly:
+
+```js
+await framer.addSVG({
+  svg: '<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20"><circle cx="10" cy="10" r="8"/></svg>',
+  name: "circle.svg",
+});
+```
+
+### Code Components
+
+Code components are custom React components that run inside Framer. Use them when you need behavior that Framer's canvas doesn't support:
+
+- **Custom interactivity** — drag-to-reorder, gesture-driven animations, games, form validation
+- **External data** — fetching from APIs, rendering dynamic content, real-time updates
+- **Complex logic** — state machines, calculations, conditional rendering beyond simple variants
+- **Third-party libraries** — maps, charts, video players, rich text editors
+- **Canvas/WebGL** — custom drawing, 3D rendering, generative art
+
+
+If the design can be built with Framer's built-in components, layout tools, and interactions — don't use a code component. Code components are harder to maintain and can't be visually edited.
+
+Before writing code components, load the `framer-code-components` skill.
+
+#### Creation
+
+```js
+state.codeFile = await framer.createCodeFile("Badge.tsx", code);
+state.diagnostics = await state.codeFile.typecheck();
+console.log(state.diagnostics);
+```
+
+```js
+state.component = state.codeFile.exports.find(
+  (exportItem) => exportItem.type === "component" && exportItem.isDefaultExport,
+);
+await framer.applyAgentChanges(
+  `+ComponentInstanceNode badge parent="wrapper" component="${state.component.componentId}"; SET badge width=120 height=48;`,
+  { pagePath: "/" },
+);
+```
+
+#### Editing
+
+```js
+const codeFile = await framer.getCodeFile("Badge.tsx");
+state.updatedCodeFile = await codeFile.setFileContent(code);
+state.diagnostics = await state.updatedCodeFile.typecheck();
+console.log(state.diagnostics);
+```
+
+For large files, write `codeFile.content` to disk:
+
+```js
+const fs = require("fs");
+
+state.codeFile = await framer.getCodeFile("Badge.tsx");
+state.localCodePath = "{{FRAMER_TEMPORARY_DIR}}/Badge.tsx";
+fs.writeFileSync(state.localCodePath, state.codeFile.content);
+```
+
+Update the file with your patch tools, then load it back into Framer:
+
+```js
+const fs = require("fs");
+const code = fs.readFileSync(state.localCodePath, "utf8");
+state.updatedCodeFile = await state.codeFile.setFileContent(code);
+state.diagnostics = await state.updatedCodeFile.typecheck();
+console.log(state.diagnostics);
+```
+
+### Storing Data
+
+Store metadata on nodes or globally in the project.
+
+```js
+// Store global project data
+await framer.setPluginData("myKey", "myValue");
+const value = await framer.getPluginData("myKey");
+
+// Store data on a node
+await node.setPluginData("processed", "true");
+const nodeData = await node.getPluginData("processed");
+
+// List all keys
+const keys = await framer.getPluginDataKeys();
+const nodeKeys = await node.getPluginDataKeys();
+
+// Delete data (set to null)
+await framer.setPluginData("myKey", null);
+```
+
+### Localization
+
+```js
+// Get all locales
+const locales = await framer.getLocales();
+const defaultLocale = await framer.getDefaultLocale();
+
+// Get localization groups (pages, CMS items with translations)
+const groups = await framer.getLocalizationGroups();
+
+// Update translations
+const french = locales.find((l) => l.code === "fr");
+await framer.setLocalizationData({
+  valuesBySource: {
+    [sourceId]: {
+      [french.id]: { action: "set", value: "Bonjour" },
+    },
+  },
+});
+```
+
+### Known Limitations
+
+- **Pages**: Cannot change the path of a page
+- **Code overrides**: Cannot assign overrides to nodes
+- **Analytics**: No APIs exist for accessing analytics data
+
+---
+
+Below is documentation for agent-specific methods and guidelines on how to work on projects.
+
+{{AGENT_PROMPT}}
+
+---
+
+Below is the current project context:
+
+{{AGENT_CONTEXT}}