framer-dalton 0.0.21 → 0.0.22

package/docs/skills/framer.md

@@ -15,7 +15,7 @@ npx framer-dalton@latest setup
 
 What you can do with the Framer CLI:
 
-- **Canvas Editing** For design tasks - creating or editing pages, sections, layouts, recreating designs from screenshots, etc.
+- **Canvas Editing**: For design tasks — creating or editing pages, sections, layouts, recreating designs from screenshots, etc.
 - **CMS**: Create, read, update, delete collections and items. Sync external databases.
 - **Styles**: Manage color and text styles. Sync design systems.
 - **Code Components**: Create, edit, type-check, and add custom React components to the canvas.
@@ -24,7 +24,6 @@ What you can do with the Framer CLI:
 - **Data**: Store metadata on nodes and projects for plugin state.
 - **Screenshots**: Capture node screenshots as PNG/JPEG. Export nodes as SVG.
 - **Publishing**: Publish projects, manage deployments, track changes.
-- **Low-level Node APIs**: Create and modify individual nodes. Only use these for targeted, surgical edits to specific nodes - not for building pages or layouts.
 
 ## CLI Usage
 
@@ -159,9 +158,9 @@ List active sessions:
 npx framer-dalton session list
 ```
 
-## Canvas Editing
+## Project-scoped skill
 
-For design tasks, do not try to build or restyle pages with low-level node APIs. Instead, after session creation, load the dynamically created project-scoped skill `framer-canvas-editing-project-<projectId>` for canvas editing on the connected project. It contains the canvas editing guidance and all related documentation for how to use the relevant methods.
+**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”)
 
@@ -199,7 +198,7 @@ Prompting may take a while to complete, so set the command timeout to 10 minutes
 
 ## Execute Code
 
-Write your code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/` and execute with `-f`:
+Use your write tool to write your code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/` and execute with `-f`:
 
 ```bash
 npx framer-dalton exec -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-<short-summary>.js
@@ -223,10 +222,9 @@ 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). There are two types:
+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.
 
-- **Unmanaged** (`framer.createCollection()`): Users can freely edit these in the Framer UI. Always use this by default.
-- **Managed** (`framer.createManagedCollection()`): Can ONLY be edited via the API. They appear read-only in the Framer UI. Only use managed collections when explicitly asked or when creating a script for data synchronisation.
+**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
 
@@ -289,228 +287,49 @@ await item.navigateTo();
 await item.remove();
 ```
 
-#### Managed Collections
-
-```js
-// Create a managed collection
-const managed = await framer.createManagedCollection({ name: "My Sync" });
-
-// Set fields
-await managed.setFields([
-  { id: "title", name: "Title", type: "string" },
-  { id: "content", name: "Content", type: "formattedText" },
-  { id: "published", name: "Published", type: "date" },
-]);
-
-// Add items
-await managed.addItems([
-  {
-    id: "1",
-    slug: "first-post",
-    fieldData: { title: "Hello", content: "<p>World</p>" },
-  },
-]);
-
-// Store sync metadata
-await managed.setPluginData("lastSync", new Date().toISOString());
-const lastSync = await managed.getPluginData("lastSync");
-```
-
-### Working with Nodes
-
-Nodes are layers on the canvas: frames, text, images, components, etc.
-
-#### Getting Nodes
-
-```js
-// Get current selection
-const selection = await framer.getSelection();
-
-// Get canvas root
-const root = await framer.getCanvasRoot();
-
-// Get node by ID
-const node = await framer.getNode("node-id");
-
-// Get children of a node
-const children = await framer.getChildren(node.id);
+### Working with Images
 
-// Get parent
-const parent = await framer.getParent(node.id);
+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.
 
-// Find nodes by type
-const frameNodes = await framer.getNodesWithType("FrameNode");
-const textNodes = await framer.getNodesWithType("TextNode");
+There are three sources you'll typically pull URLs from:
 
-// Find nodes with specific attribute set
-const nodesWithBg = await framer.getNodesWithAttributeSet("backgroundColor");
-const nodesWithImage = await framer.getNodesWithAttributeSet("backgroundImage");
-```
-
-#### Creating Nodes
+**Stock photography.** Use `framer.queryImagesForAgent` to source candidates and stash the URL you want:
 
 ```js
-// Create a frame
-const frame = await framer.createFrameNode({
-  name: "My Frame",
-  width: 200,
-  height: 100,
-  backgroundColor: "rgba(255, 0, 0, 1)",
+const { results } = await framer.queryImagesForAgent({
+  source: "unsplash",
+  query: "snow-capped mountains",
+  count: 4,
+  orientation: "landscape",
 });
-
-// Create text (creates TextNode, then use setText)
-const textNode = await framer.createTextNode({ name: "My Text" });
-await textNode.setText("Hello World");
-
-// Add to specific parent
-const child = await framer.createFrameNode({ name: "Child" }, parentNode.id);
+state.heroUrl = results[0].url;
 ```
 
-#### Modifying Nodes
+**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
-// Update attributes
-await node.setAttributes({
-  name: "New Name",
-  width: 300,
-  height: 200,
-  backgroundColor: "rgba(0, 0, 255, 0.5)",
-  visible: true,
-  locked: false,
-});
-
-// Move to different parent
-await framer.setParent(node.id, newParentId);
-
-// Clone a node
-const clone = await node.clone();
-
-// Remove nodes
-await framer.removeNodes([node.id]);
+state.heroUrl = (await framer.uploadImage({
+  image: "https://example.com/hero.png",
+  altText: "Mountain range at sunset",
+})).url;
 ```
 
-#### Working with Text
+**An image already on the canvas.** Read the node and reuse its existing image URL:
 
 ```js
-// Get text content
-const text = await framer.getText(); // from selection
-const nodeText = await textNode.getText();
-
-// Set text
-await framer.setText("New text"); // on selection
-await textNode.setText("Hello World");
+const node = await framer.getNodeForAgent({ id: "<image-node-id>" });
+state.heroUrl = node.attributes.fill;
 ```
 
-### Working with Images
+For inline SVGs, use the plugin method directly:
 
 ```js
-// Add image to canvas
-await framer.addImage({
-  image: "https://example.com/image.png",
-  name: "My Image",
-  altText: "Description",
-});
-
-// Set image on selected node
-await framer.setImage({
-  image: "https://example.com/image.png",
-  altText: "Description",
-});
-
-// Upload image without adding to canvas (for later use)
-const imageAsset = await framer.uploadImage({
-  image: "https://example.com/image.png",
-  name: "My Image",
-  altText: "Alt text",
-});
-
-// Use uploaded image when creating a frame
-await framer.createFrameNode({ backgroundImage: imageAsset });
-
-// Get image from selection
-const image = await framer.getImage();
-console.log(image?.url);
-
-// Add SVG (must be < 10kb)
 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",
 });
 ```
 
-### Working with Styles
-
-#### Color Styles
-
-```js
-// List all color styles
-const colorStyles = await framer.getColorStyles();
-
-// Get specific style
-const style = await framer.getColorStyle("style-id");
-
-// Create color style (supports light/dark themes)
-const newStyle = await framer.createColorStyle({
-  name: "Brand/Primary", // Use / for folders
-  light: "rgba(242, 59, 57, 1)",
-  dark: "rgba(180, 40, 40, 1)",
-});
-
-// Update style
-await style.setAttributes({ light: "rgba(0, 100, 200, 1)" });
-
-// Remove style
-await style.remove();
-```
-
-#### Text Styles
-
-```js
-// List all text styles
-const textStyles = await framer.getTextStyles();
-
-// Create text style
-const heading = await framer.createTextStyle({
-  name: "Typography/Heading 1",
-  tag: "h1",
-  fontSize: "48px",
-  lineHeight: "1.2em",
-  fontWeight: 700,
-});
-
-// With breakpoints for responsive typography
-const responsive = await framer.createTextStyle({
-  fontSize: "24px",
-  minWidth: 1280,
-  breakpoints: [
-    { minWidth: 1024, fontSize: "20px" },
-    { minWidth: 768, fontSize: "18px" },
-    { minWidth: 320, fontSize: "16px" },
-  ],
-});
-
-// Update text style
-await heading.setAttributes({ fontSize: "52px" });
-```
-
-#### Fonts
-
-```js
-// Get available fonts
-const fonts = await framer.getFonts();
-
-// Get specific font
-const font = await framer.getFont("Inter", { weight: 400 });
-const boldFont = await framer.getFont("Inter", { weight: 700 });
-
-// Use font in text style
-await framer.createTextStyle({
-  name: "Body",
-  font,
-  boldFont,
-});
-```
-
 ### 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:
@@ -592,8 +411,9 @@ for await (const node of root.walk()) {
 #### Sync external data to collection
 
 ```js
-const collection = await framer.getManagedCollection();
-const existingIds = new Set(await collection.getItemIds());
+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(),
@@ -615,87 +435,6 @@ if (toRemove.length) await collection.removeItems(toRemove);
 await collection.setPluginData("lastSync", new Date().toISOString());
 ```
 
-#### Batch update all images' alt text
-
-```js
-const nodes = await framer.getNodesWithAttributeSet("backgroundImage");
-for (const node of nodes) {
-  if (!node.backgroundImage) continue;
-  await node.setAttributes({
-    backgroundImage: node.backgroundImage.cloneWithAttributes({
-      altText: "Updated description",
-    }),
-  });
-}
-```
-
-### Screenshots and SVG Export
-
-Server API exclusive methods for capturing visual output from nodes.
-
-```js
-// Take a screenshot of a node (returns Buffer + mimeType)
-const result = await framer.screenshot(node.id);
-console.log(result.mimeType); // "image/png"
-const os = require("os");
-await require("fs").promises.writeFile(
-  os.tmpdir() + "/screenshot.png",
-  result.data,
-);
-
-// With options
-const jpg = await framer.screenshot(node.id, {
-  format: "jpeg", // "png" (default) or "jpeg"
-  quality: 90, // JPEG quality 0-100 (default 100)
-  scale: 2, // Pixel density: 0.5, 1, 1.5, 2, 3, or 4 (default 1)
-  clip: { x: 0, y: 0, width: 100, height: 100 }, // Clip region in CSS pixels
-});
-
-// Export as SVG string
-const svgString = await framer.exportSVG(node.id);
-await require("fs").promises.writeFile(os.tmpdir() + "/export.svg", svgString);
-```
-
-### Publishing and Deployments
-
-Server API exclusive methods for publishing and managing deployments.
-
-```js
-// Publish the project (creates a new deployment)
-const result = await framer.publish();
-console.log(result.deployment.id); // Deployment ID
-console.log(result.hostnames); // Array of hostnames
-
-// Get all deployments
-const deployments = await framer.getDeployments();
-for (const d of deployments) {
-  console.log(d.id, d.createdAt);
-}
-
-// Deploy a specific deployment to domains
-const hostnames = await framer.deploy(deploymentId, ["example.com"]);
-
-// Get current publish info (production and staging URLs)
-const info = await framer.getPublishInfo();
-console.log(info.production?.url); // Production URL
-console.log(info.staging?.url); // Staging URL
-```
-
-### Change Tracking
-
-Server API exclusive methods for tracking project changes.
-
-```js
-// Get changed paths since last publish
-const changes = await framer.getChangedPaths();
-console.log(changes.added); // New paths
-console.log(changes.modified); // Modified paths
-console.log(changes.removed); // Removed paths
-
-// Get contributors to changes (returns user IDs)
-const contributors = await framer.getChangeContributors();
-```
-
 ### Known Limitations
 
 - **Pages**: Cannot change the path of a page

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-dalton",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "type": "module",
   "bin": "./dist/cli.js",
   "main": "./dist/cli.js",
@@ -23,7 +23,7 @@
     "@trpc/client": "^11.9.0",
     "@trpc/server": "^11.9.0",
     "commander": "^12.1.0",
-    "framer-api": "0.1.7",
+    "framer-api": "^0.1.8",
     "zod": "^4.3.6"
   },
   "devDependencies": {