framer-dalton 0.0.27 → 0.0.28

package/dist/cli.js

@@ -4,15 +4,15 @@ import path7 from 'path';
 import { Command } from 'commander';
 import crypto, { randomUUID } from 'crypto';
 import http from 'http';
-import { spawn, execFile } from 'child_process';
+import { spawn, execFile, execFileSync } from 'child_process';
 import { z } from 'zod';
-import os from 'os';
+import os2 from 'os';
 import { ErrorCode, FramerAPIError } from 'framer-api';
 import net from 'net';
 import { fileURLToPath } from 'url';
 import { createTRPCClient, httpLink } from '@trpc/client';
 
-/* @framer/ai CLI v0.0.27 */
+/* @framer/ai CLI v0.0.28 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
@@ -100,9 +100,9 @@ function getConfigDir() {
     return path7.join(process.env.XDG_CONFIG_HOME, "framer");
   }
   if (process.platform === "win32") {
-    return path7.join(process.env.APPDATA || os.homedir(), "framer");
+    return path7.join(process.env.APPDATA || os2.homedir(), "framer");
   }
-  return path7.join(os.homedir(), ".config", "framer");
+  return path7.join(os2.homedir(), ".config", "framer");
 }
 __name(getConfigDir, "getConfigDir");
 function ensureConfigDir() {
@@ -375,15 +375,59 @@ __name(markTelemetryNoticeShown, "markTelemetryNoticeShown");
 // src/version.ts
 var VERSION = (
   // typeof is used to ensure this can be used just via tsx or node etc. without build
-  "0.0.27" 
+  "0.0.28" 
 );
 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 = os2.release().trim();
+  return version || "unknown";
+}
+__name(getOsVersion, "getOsVersion");
+function getOsMetadata() {
+  const platform = os2.platform();
+  const arch = os2.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) {
@@ -396,16 +440,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 */
@@ -434,35 +481,43 @@ function waitForTrackingToFinish() {
 }
 __name(waitForTrackingToFinish, "waitForTrackingToFinish");
 function trackAuthStart(payload) {
-  postEvent({
-    event: "local_agents_auth_start",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_auth_start",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackAuthStart, "trackAuthStart");
 function trackAuthSuccess(payload) {
-  postEvent({
-    event: "local_agents_auth_success",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_auth_success",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackAuthSuccess, "trackAuthSuccess");
 function trackSkillsInstall(payload) {
-  postEvent({
-    event: "local_agents_skills_install",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_skills_install",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackSkillsInstall, "trackSkillsInstall");
 function trackError(payload) {
-  postEvent({
-    event: "local_agents_error",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_error",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackError, "trackError");
 
@@ -16430,7 +16485,7 @@ async function waitForClaudeCodeSkillDiscovery() {
   );
 }
 __name(waitForClaudeCodeSkillDiscovery, "waitForClaudeCodeSkillDiscovery");
-var FRAMER_TEMPORARY_DIR = path7.join(os.tmpdir(), "framer");
+var FRAMER_TEMPORARY_DIR = path7.join(os2.tmpdir(), "framer");
 function ensureTemporaryDir() {
   fs7.mkdirSync(FRAMER_TEMPORARY_DIR, { recursive: true });
 }
@@ -16525,7 +16580,7 @@ function cleanupLegacyCanvasEditingSkills(skillRoots = getDefaultSkillRoots()) {
 }
 __name(cleanupLegacyCanvasEditingSkills, "cleanupLegacyCanvasEditingSkills");
 function getDefaultSkillRoots() {
-  const home = os.homedir();
+  const home = os2.homedir();
   return [
     path7.join(home, ".agents", "skills"),
     path7.join(home, ".claude", "skills")

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.27 */
+/* @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.27" 
+  "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

@@ -46,6 +46,8 @@ Choose the highest-priority interface available for the task:
 - 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.
 
 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.
 
@@ -173,109 +175,143 @@ 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.
+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.
 
-**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 `framer.agent.readProject` and `framer.agent.applyChanges`, not the plugin API. Use the plugin Collection API to read available collections and field schema first, then use `framer.agent.applyChanges` to add the list.
-
-#### 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-dalton",
-  "version": "0.0.27",
+  "version": "0.0.28",
   "type": "module",
   "bin": "./dist/cli.js",
   "main": "./dist/cli.js",
@@ -29,7 +29,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",
-    "@framerjs/framer-events": "0.0.183",
+    "@framerjs/framer-events": "0.0.185",
     "@types/node": "24.12.4",
     "tsup": "^8.0.2",
     "tsx": "^4.22.3",