framer-dalton 0.0.24 → 0.0.26

package/docs/skills/framer-project.md

@@ -0,0 +1,439 @@
+---
+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 `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.
+
+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 use `applyAgentChanges` to add the list.
+
+#### 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)
+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: {...} }, ...]
+```
+
+#### 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);
+```
+
+#### 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:
+
+```js
+const caseId = field.cases.find((c) => c.name === "New").id;
+await collection.addItems([
+  { slug: "hello-world", fieldData: { [field.id]: { type: "enum", value: caseId } } },
+]);
+```
+
+#### 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 use it directly with `applyAgentChanges`.
+
+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}}