framer-dalton 0.0.26 → 0.0.28

package/dist/start-relay-server.js

@@ -1,7 +1,7 @@
 import fs4 from 'fs';
-import os from 'os';
+import os5 from 'os';
 import path from 'path';
-import 'child_process';
+import { execFileSync } from 'child_process';
 import 'net';
 import { fileURLToPath } from 'url';
 import { createTRPCClient, httpLink } from '@trpc/client';
@@ -14,7 +14,7 @@ import { z } from 'zod';
 import { createRequire } from 'module';
 import * as vm from 'vm';
 
-/* @framer/ai relay server v0.0.26 */
+/* @framer/ai relay server v0.0.28 */
 var __defProp = Object.defineProperty;
 var __knownSymbol = (name2, symbol) => (symbol = Symbol[name2]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name2);
 var __typeError = (msg) => {
@@ -72,22 +72,28 @@ Please upgrade: https://nodejs.org/`
   );
   process.exit(1);
 }
+var DEFAULT_MAX_LOG_FILE_BYTES = 1024 * 1024;
+var DEFAULT_RETAINED_LOG_FILE_BYTES = 512 * 1024;
+var LOG_TRIM_CHECK_INTERVAL = 10;
+var maxLogFileBytes = DEFAULT_MAX_LOG_FILE_BYTES;
+var retainedLogFileBytes = DEFAULT_RETAINED_LOG_FILE_BYTES;
 function getLogPath() {
   if (process.env.XDG_STATE_HOME) {
     return path.join(process.env.XDG_STATE_HOME, "framer", "relay.log");
   }
   if (process.platform === "win32") {
     return path.join(
-      process.env.APPDATA || os.homedir(),
+      process.env.APPDATA || os5.homedir(),
       "framer",
       "relay.log"
     );
   }
-  return path.join(os.homedir(), ".local", "state", "framer", "relay.log");
+  return path.join(os5.homedir(), ".local", "state", "framer", "relay.log");
 }
 __name(getLogPath, "getLogPath");
 var logPath = getLogPath();
 var initialized = false;
+var logEntriesSinceTrimCheck = LOG_TRIM_CHECK_INTERVAL - 1;
 function ensureLogDir() {
   if (initialized) return;
   const dir = path.dirname(logPath);
@@ -95,11 +101,44 @@ function ensureLogDir() {
   initialized = true;
 }
 __name(ensureLogDir, "ensureLogDir");
+function trimLogFileIfNeeded() {
+  logEntriesSinceTrimCheck += 1;
+  if (logEntriesSinceTrimCheck < LOG_TRIM_CHECK_INTERVAL) return;
+  logEntriesSinceTrimCheck = 0;
+  let size;
+  try {
+    size = fs4.statSync(logPath).size;
+  } catch (err) {
+    if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+      return;
+    }
+    throw err;
+  }
+  if (size <= maxLogFileBytes) return;
+  const retainedBytes = Math.min(retainedLogFileBytes, size);
+  const buffer = Buffer.alloc(retainedBytes);
+  const file = fs4.openSync(logPath, "r");
+  let bytesRead = 0;
+  try {
+    bytesRead = fs4.readSync(
+      file,
+      buffer,
+      0,
+      retainedBytes,
+      size - retainedBytes
+    );
+  } finally {
+    fs4.closeSync(file);
+  }
+  fs4.writeFileSync(logPath, buffer.subarray(0, bytesRead));
+}
+__name(trimLogFileIfNeeded, "trimLogFileIfNeeded");
 function log(message) {
   ensureLogDir();
   const timestamp = (/* @__PURE__ */ new Date()).toISOString();
   fs4.appendFileSync(logPath, `${timestamp} ${message}
 `);
+  trimLogFileIfNeeded();
 }
 __name(log, "log");
 function getConfigDir() {
@@ -107,9 +146,9 @@ function getConfigDir() {
     return path.join(process.env.XDG_CONFIG_HOME, "framer");
   }
   if (process.platform === "win32") {
-    return path.join(process.env.APPDATA || os.homedir(), "framer");
+    return path.join(process.env.APPDATA || os5.homedir(), "framer");
   }
-  return path.join(os.homedir(), ".config", "framer");
+  return path.join(os5.homedir(), ".config", "framer");
 }
 __name(getConfigDir, "getConfigDir");
 function ensureConfigDir() {
@@ -160,7 +199,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.26" 
+  "0.0.28" 
 );
 
 // src/relay-client.ts
@@ -266,7 +305,7 @@ var ScopedFS = class {
   }
   allowedDirs;
   constructor(allowedDirs) {
-    const defaultDirs = [process.cwd(), "/tmp", os.tmpdir()];
+    const defaultDirs = [process.cwd(), "/tmp", os5.tmpdir()];
     const dirs = allowedDirs ?? defaultDirs;
     this.allowedDirs = [...new Set(dirs.map((d) => path.resolve(d)))];
   }
@@ -533,7 +572,7 @@ async function execute(session, code, options = {}) {
       output.push(args.map((arg) => formatValue(arg)).join(" "));
     }, "info")
   };
-  const scopedFs = cwd ? new ScopedFS([cwd, "/tmp", os.tmpdir()]) : new ScopedFS();
+  const scopedFs = cwd ? new ScopedFS([cwd, "/tmp", os5.tmpdir()]) : new ScopedFS();
   const sandboxedRequire = createSandboxedRequire(scopedFs);
   const vmContextObj = {
     // Framer API
@@ -795,11 +834,55 @@ function isTelemetryEnabled() {
 __name(isTelemetryEnabled, "isTelemetryEnabled");
 var trackingEndpoint = "https://events.framer.com/track";
 var inProgressTrackings = /* @__PURE__ */ new Set();
-function sharedFields() {
+var cachedSharedFields;
+function getOsName(platform) {
+  switch (platform) {
+    case "darwin":
+      return "macos";
+    case "win32":
+      return "windows";
+    case "linux":
+      return "linux";
+    default:
+      return "unknown";
+  }
+}
+__name(getOsName, "getOsName");
+function getMacOsVersion() {
+  try {
+    const version = execFileSync("/usr/bin/sw_vers", ["-productVersion"], {
+      encoding: "utf8",
+      timeout: 1e3
+    }).trim();
+    return version || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+__name(getMacOsVersion, "getMacOsVersion");
+function getOsVersion(platform) {
+  if (platform === "darwin") return getMacOsVersion();
+  const version = os5.release().trim();
+  return version || "unknown";
+}
+__name(getOsVersion, "getOsVersion");
+function getOsMetadata() {
+  const platform = os5.platform();
+  const arch = os5.arch();
   return {
+    arch: arch || "unknown",
+    osName: getOsName(platform),
+    osVersion: getOsVersion(platform)
+  };
+}
+__name(getOsMetadata, "getOsMetadata");
+function sharedFields() {
+  cachedSharedFields ??= {
     machineId: getMachineId(),
-    cliVersion: VERSION
+    cliVersion: VERSION,
+    ...getOsMetadata()
   };
+  return cachedSharedFields;
 }
 __name(sharedFields, "sharedFields");
 function wrapEvent(event) {
@@ -812,16 +895,19 @@ function wrapEvent(event) {
   };
 }
 __name(wrapEvent, "wrapEvent");
-function postEvent(event) {
+function postEvent(createEvent) {
   if (!isTelemetryEnabled()) return false;
   if (process.env.NODE_ENV === "test" && true) return false;
+  const event = createEvent();
+  const body = JSON.stringify([wrapEvent(event)]);
+  debug("tracking", `sending ${event.event} to ${trackingEndpoint}: ${body}`);
   const promise = fetch(trackingEndpoint, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       "User-Agent": `framer-dalton/${VERSION}`
     },
-    body: JSON.stringify([wrapEvent(event)]),
+    body,
     signal: AbortSignal.timeout(
       5e3
       /* 5 seconds */
@@ -850,75 +936,93 @@ function waitForTrackingToFinish() {
 }
 __name(waitForTrackingToFinish, "waitForTrackingToFinish");
 function trackRelayStart() {
-  postEvent({
-    event: "local_agents_relay_start",
-    ...sharedFields()
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_relay_start",
+      ...sharedFields()
+    })
+  );
 }
 __name(trackRelayStart, "trackRelayStart");
 var relayShutdownTracked = false;
 function trackRelayShutdown() {
   if (relayShutdownTracked) return;
-  relayShutdownTracked = postEvent({
-    event: "local_agents_relay_shutdown",
-    ...sharedFields()
-  });
+  relayShutdownTracked = postEvent(
+    () => ({
+      event: "local_agents_relay_shutdown",
+      ...sharedFields()
+    })
+  );
 }
 __name(trackRelayShutdown, "trackRelayShutdown");
 function trackSessionCreate(payload) {
-  postEvent({
-    event: "local_agents_session_create",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_session_create",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackSessionCreate, "trackSessionCreate");
 function trackSessionDestroy(payload) {
-  postEvent({
-    event: "local_agents_session_destroy",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_session_destroy",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackSessionDestroy, "trackSessionDestroy");
 function trackExec(payload) {
-  postEvent({
-    event: "local_agents_exec",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_exec",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackExec, "trackExec");
 function trackConnectionAcquire(payload) {
-  postEvent({
-    event: "local_agents_connection_acquire",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_connection_acquire",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackConnectionAcquire, "trackConnectionAcquire");
 function trackConnectionReconnect(payload) {
-  postEvent({
-    event: "local_agents_connection_reconnect",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_connection_reconnect",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackConnectionReconnect, "trackConnectionReconnect");
 function trackConnectionIdleDisconnect(payload) {
-  postEvent({
-    event: "local_agents_connection_idle_disconnect",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_connection_idle_disconnect",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackConnectionIdleDisconnect, "trackConnectionIdleDisconnect");
 function trackError(payload) {
-  postEvent({
-    event: "local_agents_error",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_error",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackError, "trackError");
 

package/docs/skills/framer-project.md

@@ -36,16 +36,22 @@ 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:
+Choose the highest-priority interface available for the task:
 
-- Use `readProjectForAgent`, `getNodeForAgent`, `getNodesForAgent`, `getNodesOfTypesForAgent`, `getScopeNodeForAgent`, `getGroundNodeForAgent`, `getParentNodeForAgent`, `getAncestorsForAgent`, `serializeForAgent`, `serializeNodesForAgent`, and `paginateForAgent` for project tree reads.
-- Use `readComponentControlsForAgent`, `readIconSetControlsForAgent`, `readIconsForAgent`, `readLayoutTemplateControlsForAgent`, and `readShaderControlsForAgent` for reading the controls of components, icon sets, icons, layout templates, and shaders.
-- 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.
+1. Subcommands, such as `framer-dalton read-project` and `framer-dalton apply-changes`
+2. Agent-specific methods, such as `framer.agent.readProject`, `framer.agent.applyChanges`, and `framer.agent.publish`
+3. Generic plugin API methods, such as top-level `framer.*` methods
 
-Use the plugin API for capabilities that do not have an agent-specific counterpart, such as code file management, localization, and redirects.
+- Use `framer.agent.readProject`, `framer.agent.getNode`, `framer.agent.getNodes`, `framer.agent.getNodesOfTypes`, `framer.agent.getScopeNode`, `framer.agent.getGroundNode`, `framer.agent.getParentNode`, `framer.agent.getAncestors`, `framer.agent.serialize`, `framer.agent.serializeNodes`, and `framer.agent.paginate` for project tree reads.
+- Use `framer.agent.readComponentControls`, `framer.agent.readIconSetControls`, `framer.agent.readIcons`, `framer.agent.readLayoutTemplateControls`, and `framer.agent.readShaderControls` for reading the controls of components, icon sets, icons, layout templates, and shaders.
+- Use `framer.agent.applyChanges` for page and layout edits. Do not use low-level node APIs like `createNode`, `setAttributes`, or `setRect` for design/layout work.
+- Use `framer.agent.publish` for publishing. Do not use `publish`, `getDeployments`, or `deploy` for normal agent publishing flows.
+- Prefer `framer.agent.applyChanges` and project tree read methods for CMS work where possible. Fall back to the collection APIs only for functionality otherwise not supported. Note that if you add collections or fields via collection APIs, some things may not work as expected when then using those collections or fields on the canvas via `framer.agent.applyChanges`.
+- Create styles, design tokens, components, and variables via `framer.agent.applyChanges`. Using plugin API methods can cause issues when trying to use newly created values later in `framer.agent.applyChanges` calls.
 
-During normal task execution, do not call `framer.getAgentSystemPrompt()` or `framer.getAgentContext()`. This skill already includes their output.
+Use generic plugin API methods only for capabilities that do not have a subcommand or agent-specific counterpart, such as code file management, localization, and redirects.
+
+During normal task execution, do not call `framer.agent.getSystemPrompt()` or `framer.agent.getContext()`. This skill already includes their output.
 
 ## Core Usage Principles
 
@@ -100,15 +106,15 @@ Store anything you'll reference again.
 
 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.
+This approach is called “Prompt the Framer agent”. With this approach, use `framer.agent.startConversation()` to start a stateful design subagent. Keep the `conversationId` it returns in `state`, and call `framer.agent.continueConversation()` with it to continue the same design task.
 
-Do not call `framer.getAgentSystemPrompt()` or `framer.getAgentContext()` or `framer.applyAgentChanges()` with this approach.
+Do not call `framer.agent.getSystemPrompt()` or `framer.agent.getContext()` or `framer.agent.applyChanges()` with this approach.
 
 Example:
 
 ```js
 state.agent ??= {};
-const first = await framer.startAgentConversation(
+const first = await framer.agent.startConversation(
   "Build me a landing page based on the attached screenshot",
   {
     pagePath: "/",
@@ -119,7 +125,7 @@ const first = await framer.startAgentConversation(
 state.agent.conversationId = first.conversationId;
 console.log(first.responseMessages);
 
-const second = await framer.continueAgentConversation("Now make it pink", {
+const second = await framer.agent.continueConversation("Now make it pink", {
   conversationId: state.agent.conversationId,
   selectionNodeIds: ["someNodeId"],
   // imageUrls: [...],
@@ -169,120 +175,154 @@ npx framer-dalton docs ScreenshotOptions          # Show type + recursively expa
 
 ### 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 use `applyAgentChanges` to add the list.
+Collections and items are nodes: read them with the agent read methods, create and edit them with `framer.agent.applyChanges`. A collection's fields are its `variables`; an item's cells are `$control__<fieldId>` attributes.
 
-#### Reading Collections
+#### List collections and fields
 
 ```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)
-const fields = await collection.getFields();
-// Note that a plain console.log will miss getter-backed properties
-console.log(fields.map((f) => ({ id: f.id, name: f.name, type: f.type })));
-// [{ id: "BnNuS2i3o", name: "Title", type: "string" }, ...]
-
-// Get items (rows)
-const items = await collection.getItems();
-console.log(items);
-// [{ id: "XTM8FSHGs", slug: "post-1", draft: false, fieldData: {...} }, ...]
+const collections = await framer.agent.getNodesOfTypes({ types: ["CollectionNode"] });
+console.log(collections.map((c) => ({
+  id: c.id,
+  name: c.name,
+  itemCount: c.$itemCount,
+  fields: c.variables.map((v) => ({ id: v.id, name: v.name, type: v.type })),
+})));
 ```
 
-#### Sync external data to collection
+#### Read items
+
+If you know the collection id, serialize the collection with `depth: 1` to read its direct item children.
 
 ```js
-const collection = await framer.getCollection("collection-id");
-const existing = await collection.getItems();
-const existingIds = new Set(existing.map((i) => i.id));
+const collectionId = "collection-id";
+const collection = await framer.agent.serialize({ id: collectionId, depth: 1 });
+const items = collection.children ?? [];
+console.log({
+  itemCount: collection.$itemCount,
+  items: items.map((item) => ({ id: item.id, ...item.attributes })),
+});
+```
 
-const externalData = await fetch("https://api.example.com/posts").then((r) =>
-  r.json(),
-);
+For huge collections, paginate the serialized children and process one page per call. Store the page in `state` only when you need to continue in a later exec call. Stop when the logged `nextCursor` is missing.
 
-const items = externalData.map((post) => ({
-  id: post.id,
-  slug: post.slug,
-  fieldData: { title: post.title, content: post.body },
-}));
+First page:
 
-await collection.addItems(items);
+```js
+const collectionId = "collection-id";
+const collection = await framer.agent.serialize({ id: collectionId, depth: 1 });
+state.page = await framer.agent.paginate({ items: collection.children ?? [] });
+console.log({
+  totalResults: state.page.totalResults,
+  nextCursor: state.page.nextCursor,
+  items: state.page.results.map((item) => ({ id: item.id, ...item.attributes })),
+});
+```
 
-// 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);
+Next page, if nextCursor is set:
 
-await collection.setPluginData("lastSync", new Date().toISOString());
+```js
+state.page = await framer.agent.paginate({
+  keyName: state.page.keyName,
+  cursor: state.page.nextCursor,
+});
+console.log({
+  totalResults: state.page.totalResults,
+  nextCursor: state.page.nextCursor,
+  items: state.page.results.map((item) => ({ id: item.id, ...item.attributes })),
+});
 ```
 
-#### Field Types
+To search across all collections, read item nodes directly and filter by `$parentId`:
 
-`boolean`, `color`, `number`, `string`, `formattedText` (HTML), `image`, `file`, `link`, `date`, `enum`, `collectionReference`, `multiCollectionReference`, `array` (galleries)
+```js
+const collectionId = "collection-id";
+const items = await framer.agent.getNodesOfTypes({ types: ["CollectionItemNode"] });
+const collectionItems = items
+  .filter((item) => item.$parentId === collectionId)
+  .map((item) => ({ id: item.id, ...item.attributes }));
+console.log(collectionItems);
+```
 
-#### Updating Collection Items
+#### Create and edit 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" },
-  },
-]);
+`+CollectionItemNode` adds a row; `SET … $control__<fieldId>` sets cells (a `SET` on an existing item id updates it; `DEL <itemId>` removes it).
 
-// Remove items
-await collection.removeItems(["item-id-1", "item-id-2"]);
+```js
+const { readFileSync } = require("fs");
+
+const collectionId = "collection-id";
+const columnToFieldId = { title: "title-field-id", body: "body-field-id" };
+const rows = JSON.parse(readFileSync("/abs/path/to/import.json", "utf8"));
+
+const commands = rows.flatMap((row, i) => {
+  const itemId = `item-${i}`;
+  const sets = Object.entries(columnToFieldId)
+    .filter(([col]) => row[col] != null)
+    .map(([col, fieldId]) => `$control__${fieldId}="${String(row[col]).replace(/"/g, '\\"')}"`);
+  return [`+CollectionItemNode ${itemId} parent="${collectionId}";`, `SET ${itemId} ${sets.join(" ")};`];
+});
 
-// Reorder items
-const ids = items.map((i) => i.id).reverse();
-await collection.setItemOrder(ids);
+await framer.agent.applyChanges(commands.join(" "));
 ```
 
 #### Writing enum fields
 
-Enum fields are **write-by-case-id, read-by-name**: a write must pass the case's `id`, but `getItems()` reads the value back as the case name. Writing `{ type: "enum", value: "New" }` (the name) is rejected — look up the id from the field definition first:
+With agent methods, enum fields are read and written by case name. Look up the field on the collection's `variables`, verify the case exists, then set the field's `$control__...` key:
 
 ```js
-const caseId = field.cases.find((c) => c.name === "New").id;
-await collection.addItems([
-  { slug: "hello-world", fieldData: { [field.id]: { type: "enum", value: caseId } } },
-]);
+const collection = (await framer.agent.getNodesOfTypes({ types: ["CollectionNode"] }))
+  .find((c) => c.name === "Posts");
+const statusField = collection.variables.find((v) => v.name === "Status");
+const status = statusField.cases.find((name) => name === "New");
+
+await framer.agent.applyChanges(
+  `+CollectionItemNode newPost parent="${collection.id}";
+   SET newPost $control__slug="hello-world" ${statusField.key}="${status}";`,
+);
 ```
 
-#### Working with CollectionItem
+#### Sync external data
+
+Upsert by a stable key (e.g. slug): `SET` existing rows, add new ones, `DEL` rows no longer in the source.
 
 ```js
-const items = await collection.getItems();
-const item = items[0];
+const collectionId = "collection-id";
+const fieldBySource = { title: "title-field-id", body: "body-field-id" };
+const source = await fetch("https://api.example.com/posts").then((r) => r.json());
+
+const existing = (await framer.agent.getNodesOfTypes({ types: ["CollectionItemNode"] }))
+  .filter((item) => item.$parentId === collectionId);
+const idBySlug = new Map(existing.map((item) => [item.attributes.$control__slug, item.id]));
+
+const seen = new Set();
+const commands = source.flatMap((row, i) => {
+  const itemId = idBySlug.get(row.slug) ?? `new-${i}`;
+  seen.add(itemId);
+  const sets = Object.entries(fieldBySource)
+    .filter(([k]) => row[k] != null)
+    .map(([k, fieldId]) => `$control__${fieldId}="${String(row[k]).replace(/"/g, '\\"')}"`);
+  const add = idBySlug.has(row.slug) ? [] : [`+CollectionItemNode ${itemId} parent="${collectionId}";`];
+  return [...add, `SET ${itemId} ${sets.join(" ")};`];
+});
+existing.filter((item) => !seen.has(item.id)).forEach((item) => commands.push(`DEL ${item.id};`));
 
-// Update item attributes
-await item.setAttributes({ slug: "new-slug" });
+await framer.agent.applyChanges(commands.join(" "));
+```
 
-// Navigate to item in Framer UI
-await item.navigateTo();
+#### Field Types
 
-// Remove item
-await item.remove();
-```
+`boolean`, `color`, `number`, `string`, `formattedText` (HTML), `image`, `file`, `link`, `date`, `enum`, `collectionReference`, `multiCollectionReference`, `array` (galleries)
 
 ### Working with Images
 
-Canvas editing accepts image URLs directly when setting an image fill, so the typical task is to obtain a URL and use it directly with `applyAgentChanges`.
+Canvas editing accepts image URLs directly when setting an image fill, so the typical task is to obtain a URL and use it directly with `framer.agent.applyChanges`.
 
 There are three sources you'll typically pull URLs from:
 
-**Stock photography.** Use `framer.queryImagesForAgent` to source candidates and stash the URL you want:
+**Stock photography.** Use `framer.agent.queryImages` to source candidates and stash the URL you want:
 
 ```js
-const { results } = await framer.queryImagesForAgent({
+const { results } = await framer.agent.queryImages({
   source: "unsplash",
   query: "snow-capped mountains",
   count: 4,
@@ -303,7 +343,7 @@ state.heroUrl = (await framer.uploadImage({
 **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>" });
+const node = await framer.agent.getNode({ id: "<image-node-id>" });
 state.heroUrl = node.attributes.fill;
 ```
 
@@ -343,7 +383,7 @@ console.log(state.diagnostics);
 state.component = state.codeFile.exports.find(
   (exportItem) => exportItem.type === "component" && exportItem.isDefaultExport,
 );
-await framer.applyAgentChanges(
+await framer.agent.applyChanges(
   `+ComponentInstanceNode badge parent="wrapper" component="${state.component.componentId}"; SET badge width=120 height=48;`,
   { pagePath: "/" },
 );

package/docs/skills/framer.md

@@ -1,7 +1,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'. 
+  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:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
 ---