framer-dalton 0.0.24 → 0.0.26

package/docs/skills/framer.md

@@ -31,11 +31,7 @@ What you can do with the Framer CLI:
 
 The Framer CLI requires network access (to download packages and connect to Framer servers) and file-system access outside the project directory (to install skills into `~/.agents/skills/` and `~/.claude/skills/`). In sandboxed environments, you must execute `npx framer-dalton` commands with elevated permissions from the get-go. Do not try to execute them with the default sandboxed permissions; they will hang or fail.
 
-### Required Workflow
-
-Every task follows these steps:
-
-#### 1. Connect (once per session)
+### Session Management
 
 If the user refers to a project by name or description rather than giving a URL, first inspect the recent projects:
 
@@ -45,12 +41,16 @@ npx framer-dalton project list
 
 Use that list to infer the likely project from the names and recency. If the right project is already known, use its project ID with `session new`. If there are multiple possible matches, clarify with the user. Only ask the user for a Project URL if there is no clear match. Avoid talking about the technical contents of returned data like IDs.
 
+Each session maintains a persistent connection to a Framer project. Use sessions to keep state separate between different tasks, persist data across multiple execute calls, and reuse the `framer` API instance without reconnecting.
+
 Create a session against an existing project:
 
 ```bash
 npx framer-dalton session new "<url or id>"
 ```
 
+This prints the session ID. You must always use that session ID with `-s <id>` for all subsequent commands. Using the same session preserves your `state` between calls.
+
 To create a brand new empty project and connect to it:
 
 ```bash
@@ -67,91 +67,6 @@ npx framer-dalton session new "<returned project id>"
 
 Note that during beta, you cannot connect to non-beta projects. If creating a session errors with a message about this, you need to move your project to beta.
 
-#### 2. Look up the API (before EVERY code execution)
-
-**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?
-```
-
-#### 3. Execute code
-
-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`).
-
-```bash
-npx framer-dalton exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-read-collections.js
-```
-
-#### 4. Store results in `state`
-
-Always save results you'll need again. Don't repeat API calls.
-
-**Do not skip step 2.** The examples below are patterns only - always verify current signatures with `npx framer-dalton docs`.
-
-## 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.
-
-## 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.
-
-## Session Management
-
-Each session maintains a persistent connection to a Framer project. Use sessions to:
-
-- Keep state separate between different tasks
-- Persist data across multiple execute calls
-- Reuse the `framer` API instance without reconnecting
-
-Get a new session ID:
-
-```bash
-npx framer-dalton session new "https://framer.com/projects/Website--abc123"
-# outputs: 1
-```
-
-**Always use your own session** - pass `-s <id>` to all commands. Using the same session preserves your `state` between calls.
-
 List active sessions:
 
 ```bash
@@ -160,296 +75,4 @@ npx framer-dalton session list
 
 ## Project-scoped skill
 
-**Always load the project-scoped skill `framer-canvas-editing-project-<projectId>` immediately after `session new`, regardless of the task.** It is the source of truth for the connected project and is required for canvas editing, project-tree reads, change review, publishing, page management, sourcing stock images, and component operations. CMS plugin API, code components, localization, plugin data, and CLI mechanics remain in this framer-dalton skill — use both together.
-
-## 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 writing code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/` and executing it with `-f`:
-
-```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 a canvas concern. Build and edit those through canvas editing, not the plugin API. Use the plugin Collection API to read available collections and field schema first, then drive the list through the canvas-editing 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: {...} }, ...]
-```
-
-#### 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 canvas-editing 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 visual tools don'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.
-
-#### Workflow
-
-1. **Create** a code file: `framer.createCodeFile("MyComponent.tsx", code)`
-2. **Edit** an existing code file: `codeFile.setFileContent(newCode)`
-3. **Type check**: `codeFile.typecheck()` or `framer.typecheckCode("File.tsx", code)`
-4. **Add to canvas**: `framer.addComponentInstance({ url: codeFile.exports[0].insertURL })`
-
-Use `npx framer-dalton docs CodeFile` and `npx framer-dalton docs Framer.createCodeFile` to look up the full API.
-
-#### Authoring guidance
-
-Before writing component code, load the `framer-code-components` skill.
-
-### 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" },
-    },
-  },
-});
-```
-
-### Common Patterns
-
-#### Iterate over all nodes in project
-
-```js
-const root = await framer.getCanvasRoot();
-for await (const node of root.walk()) {
-  console.log(node.name);
-}
-```
-
-#### 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());
-```
-
-### 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
+**Always load the project-scoped skill `framer-project-<projectId>` immediately after `session new`, regardless of the task.** That skill is generated by `session new` and contains the documentation for everything you need to know about working with a Framer project.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-dalton",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "type": "module",
   "bin": "./dist/cli.js",
   "main": "./dist/cli.js",
@@ -16,6 +16,7 @@
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist",
     "check": "biome check .",
+    "check:fix": "biome check --write .",
     "format": "biome format --write .",
     "generate-types": "tsx scripts/generate-types.ts"
   },
@@ -23,17 +24,17 @@
     "@trpc/client": "^11.17.0",
     "@trpc/server": "^11.17.0",
     "commander": "^12.1.0",
-    "framer-api": "0.1.10",
-    "zod": "^4.3.6"
+    "framer-api": "^0.1.14-beta",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",
-    "@framerjs/framer-events": "0.0.175",
-    "@types/node": "24.10.9",
+    "@framerjs/framer-events": "0.0.183",
+    "@types/node": "24.12.4",
     "tsup": "^8.0.2",
-    "tsx": "^4.19.0",
+    "tsx": "^4.22.3",
     "typescript": "^5.9.2",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.7"
   },
   "packageManager": "yarn@4.13.0",
   "engines": {

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

@@ -1,49 +0,0 @@
----
-name: {{SKILL_NAME}}
-description: "Project-scoped Framer skill for project {{PROJECT_ID}}. Covers canvas editing, project reads, change review, publishing, image sourcing, and component operations. 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}}
-
-## Rules
-
-- For design/layout work, do not use low-level node APIs (`createNode`, `setAttributes`, `setRect`, etc.). Use the canvas editing flow (`read-project` + `apply-changes`) with the embedded prompt and project context in this skill.
-- During normal task execution, do not call `framer.getAgentSystemPrompt()` or `framer.getAgentContext()`. This skill already includes `getAgentContext({ pagePath: "/" })`.
-- `read-project` and `apply-changes` are one-liner CLI shortcuts for the high-frequency canvas-editing methods. Use them to read state and apply DSL inline without writing a file first:
-    - `npx framer-dalton read-project -s <sessionId> -q <queries> -p <pagePath>` — equivalent to `framer.readProjectForAgent(queries, { pagePath })`. Query types are documented in the embedded prompt below.
-    - `npx framer-dalton apply-changes -s <sessionId> -p <pagePath> -e <dsl>` — equivalent to `framer.applyAgentChanges(dsl, { pagePath })`.
-- The embedded prompt below also references other agent-surface methods (`reviewChangesForAgent`, `publishForAgent`, `queryImagesForAgent`, `flattenComponentInstanceForAgent`, `makeExternalComponentLocalForAgent`, `getNodeForAgent` / `getNodesForAgent` / `getNodesOfTypesForAgent` / `getScopeNodeForAgent` / `getGroundNodeForAgent` / `getParentNodeForAgent` / `getAncestorsForAgent`, and `serializeForAgent` / `serializeNodesForAgent` / `paginateForAgent`). These have no dedicated shortcut; invoke via `npx framer-dalton exec -s <sessionId> -e 'console.log(await framer.<method>(<args>))'`.
-
-## Workflow Loop
-
-```bash
-# 1) Read page structure first (fill in real query from Live Agent System Prompt)
-npx framer-dalton read-project -s <sessionId> -q '<query to get page structure>' -p "/"
-
-# 2) Request additional targeted queries only if needed
-
-# 3) Apply changes — pass DSL directly via apply-changes
-npx framer-dalton apply-changes -s <sessionId> -p "/" -e "$dsl"
-```
-
-## Critical for UX: Streaming
-
-When you generate DSL to apply, keep it short. Each `apply-changes` call must only cover ONE logical section (header, footer, hero, card, etc.). Once you apply ONE section, continue with the next.
-
-This ensures progress is streamed to the user in small, visible increments.
-
-## Live Agent System Prompt
-
-This is the static prompt returned by `framer.getAgentSystemPrompt()`. 
-
-{{CANVAS_PROMPT}}
-
-## 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, available components, design tokens, style presets, and icon sets.
-
-{{AGENT_CONTEXT}}