framer-dalton 0.0.5 → 0.0.7

package/docs/{server-api.md → skills/framer.md}

@@ -1,3 +1,29 @@
+---
+name: framer
+description: "Single entry point for Framer tasks. Mandatory precondition: run `npx framer-dalton@latest setup` and let it complete BEFORE loading this skill."
+---
+
+If you didn't run this command before loading the skill, run it now:
+
+```bash
+npx framer-dalton@latest setup
+```
+
+## Capabilities
+
+What you can do with the Framer CLI:
+
+- **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.
+- **Assets**: Upload and manage images and files.
+- **Localization**: Manage translations programmatically.
+- **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
 
 ### Required Workflow
@@ -27,24 +53,46 @@ npx framer-dalton docs Collection.getItems  # What are the parameters and return
 Only after checking docs:
 
 ```bash
-npx framer-dalton -s 1 -e "state.items = await collection.getItems(); console.log(state.items.length)"
+npx framer-dalton -s 1 -e "state.collections = await framer.getCollections(); console.log(state.collections.length)"
 ```
 
 #### 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`.
 
-### Communication style
+## 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.
+- 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.
 
----
+## 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.
+
+```bash
+# First call: fetch and store
+npx framer-dalton -s 1 -e "state.collections = await framer.getCollections()"
+
+# Later calls: reuse from state
+npx framer-dalton -s 1 -e "const team = state.collections.find(c => c.name === 'Team')"
+npx framer-dalton -s 1 -e "state.teamItems = await state.collections.find(c => c.name === 'Team').getItems()"
+```
+
+Store anything you'll reference again.
 
-### Session Management
+## Session Management
 
 Each session maintains a persistent connection to a Framer project. Use sessions to:
 
@@ -67,13 +115,19 @@ List active sessions:
 npx framer-dalton session list
 ```
 
-### Execute Code
+## Canvas Editing
+
+For design tasks, do not try to build or restyle pages with low-level node APIs. Instead, load the dynamically created project-scoped canvas skill and follow its `readProjectForAgent` plus `applyAgentChanges` flow.
+
+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, the live agent system prompt, and the live project context for `pagePath: "/"`.
+
+## Execute Code
 
 ```bash
 npx framer-dalton -s <sessionId> -e "<code>"
 ```
 
-**Escaping:** For code with HTML, quotes, or special characters, use a heredoc (see below). For simple strings, use `$'...'` syntax.
+**Escaping:** For code containing `$` (e.g. `$control__` properties), HTML, or nested quotes, use a heredoc (see below). `-e "..."` works for everything else, including multiline.
 
 **Examples:**
 
@@ -108,22 +162,23 @@ The `<<'EOF'` syntax (with quotes around EOF) prevents shell interpolation.
 cat script.js | npx framer-dalton -s 1
 ```
 
-**Simple inline code:**
+**Multiline inline code:**
 
 ```bash
-npx framer-dalton -s 1 -e $'
+npx framer-dalton -s 1 -e "
 const collections = await framer.getCollections();
 for (const c of collections) {
   const items = await c.getItems();
   console.log(c.name, items.length);
 }
-'
+"
 ```
 
-### API Documentation
+## 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
@@ -131,46 +186,15 @@ npx framer-dalton docs ScreenshotOptions          # Show type + recursively expa
 
 `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.
 
----
-
-## 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.
-
-```bash
-# First call: fetch and store
-npx framer-dalton -s 1 -e "state.collections = await framer.getCollections()"
-
-# Later calls: reuse from state
-npx framer-dalton -s 1 -e "const team = state.collections.find(c => c.name === 'Team')"
-npx framer-dalton -s 1 -e "state.teamItems = await state.collections.find(c => c.name === 'Team').getItems()"
-```
-
-Store anything you'll reference again: collections, items, nodes, fields.
-
----
-
 ## 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)
+### Working with Collections (CMS)
 
 Collections are Framer's CMS. Each collection has fields (columns) and items (rows).
 
-### Reading Collections
+#### Reading Collections
 
 ```js
 // Get all collections
@@ -191,11 +215,11 @@ console.log(items);
 // [{ id: "XTM8FSHGs", slug: "post-1", draft: false, fieldData: {...} }, ...]
 ```
 
-### Field Types
+#### Field Types
 
 `boolean`, `color`, `number`, `string`, `formattedText` (HTML), `image`, `file`, `link`, `date`, `enum`, `collectionReference`, `multiCollectionReference`, `array` (galleries)
 
-### Updating Collection Items
+#### Updating Collection Items
 
 ```js
 // Add or update items (if id matches existing item, it updates)
@@ -215,7 +239,7 @@ const ids = items.map((i) => i.id).reverse();
 await collection.setItemOrder(ids);
 ```
 
-### Working with CollectionItem
+#### Working with CollectionItem
 
 ```js
 const items = await collection.getItems();
@@ -231,7 +255,7 @@ await item.navigateTo();
 await item.remove();
 ```
 
-### Managed Collections
+#### Managed Collections
 
 Managed collections are fully controlled by code - users can't edit them directly. Use for syncing external data sources.
 
@@ -260,13 +284,11 @@ await managed.setPluginData("lastSync", new Date().toISOString());
 const lastSync = await managed.getPluginData("lastSync");
 ```
 
----
-
-## Working with Nodes
+### Working with Nodes
 
 Nodes are layers on the canvas: frames, text, images, components, etc.
 
-### Getting Nodes
+#### Getting Nodes
 
 ```js
 // Get current selection
@@ -293,7 +315,7 @@ const nodesWithBg = await framer.getNodesWithAttributeSet("backgroundColor");
 const nodesWithImage = await framer.getNodesWithAttributeSet("backgroundImage");
 ```
 
-### Creating Nodes
+#### Creating Nodes
 
 ```js
 // Create a frame
@@ -312,7 +334,7 @@ await textNode.setText("Hello World");
 const child = await framer.createFrameNode({ name: "Child" }, parentNode.id);
 ```
 
-### Modifying Nodes
+#### Modifying Nodes
 
 ```js
 // Update attributes
@@ -335,7 +357,7 @@ const clone = await node.clone();
 await framer.removeNodes([node.id]);
 ```
 
-### Working with Text
+#### Working with Text
 
 ```js
 // Get text content
@@ -347,9 +369,7 @@ await framer.setText("New text"); // on selection
 await textNode.setText("Hello World");
 ```
 
----
-
-## Working with Images
+### Working with Images
 
 ```js
 // Add image to canvas
@@ -386,11 +406,9 @@ await framer.addSVG({
 });
 ```
 
----
-
-## Working with Styles
+### Working with Styles
 
-### Color Styles
+#### Color Styles
 
 ```js
 // List all color styles
@@ -413,7 +431,7 @@ await style.setAttributes({ light: "rgba(0, 100, 200, 1)" });
 await style.remove();
 ```
 
-### Text Styles
+#### Text Styles
 
 ```js
 // List all text styles
@@ -443,7 +461,7 @@ const responsive = await framer.createTextStyle({
 await heading.setAttributes({ fontSize: "52px" });
 ```
 
-### Fonts
+#### Fonts
 
 ```js
 // Get available fonts
@@ -461,9 +479,7 @@ await framer.createTextStyle({
 });
 ```
 
----
-
-## Code Components
+### 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:
 
@@ -475,7 +491,7 @@ Code components are custom React components that run inside Framer. Use them whe
 
 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
+#### Workflow
 
 1. **Create** a code file: `framer.createCodeFile("MyComponent.tsx", code)`
 2. **Edit** an existing code file: `codeFile.setFileContent(newCode)`
@@ -484,19 +500,11 @@ If the design can be built with Framer's built-in components, layout tools, and
 
 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, read the relevant skill docs:
-
-```bash
-npx framer-dalton skill code-components    # Structure, constraints, layout annotations
-npx framer-dalton skill property-controls  # All 20+ control types with examples
-npx framer-dalton skill component-examples # Complete reference components
-```
+#### Authoring guidance
 
----
+Before writing component code, load the `framer-code-components` skill.
 
-## Storing Data
+### Storing Data
 
 Store metadata on nodes or globally in the project.
 
@@ -517,9 +525,7 @@ const nodeKeys = await node.getPluginDataKeys();
 await framer.setPluginData("myKey", null);
 ```
 
----
-
-## Localization
+### Localization
 
 ```js
 // Get all locales
@@ -540,11 +546,9 @@ await framer.setLocalizationData({
 });
 ```
 
----
-
-## Common Patterns
+### Common Patterns
 
-### Iterate over all nodes in project
+#### Iterate over all nodes in project
 
 ```js
 const root = await framer.getCanvasRoot();
@@ -553,7 +557,7 @@ for await (const node of root.walk()) {
 }
 ```
 
-### Sync external data to collection
+#### Sync external data to collection
 
 ```js
 const collection = await framer.getManagedCollection();
@@ -579,7 +583,7 @@ if (toRemove.length) await collection.removeItems(toRemove);
 await collection.setPluginData("lastSync", new Date().toISOString());
 ```
 
-### Batch update all images' alt text
+#### Batch update all images' alt text
 
 ```js
 const nodes = await framer.getNodesWithAttributeSet("backgroundImage");
@@ -593,9 +597,7 @@ for (const node of nodes) {
 }
 ```
 
----
-
-## Screenshots and SVG Export
+### Screenshots and SVG Export
 
 Server API exclusive methods for capturing visual output from nodes.
 
@@ -622,9 +624,7 @@ const svgString = await framer.exportSVG(node.id);
 await require("fs").promises.writeFile(os.tmpdir() + "/export.svg", svgString);
 ```
 
----
-
-## Publishing and Deployments
+### Publishing and Deployments
 
 Server API exclusive methods for publishing and managing deployments.
 
@@ -649,9 +649,7 @@ console.log(info.production?.url); // Production URL
 console.log(info.staging?.url); // Staging URL
 ```
 
----
-
-## Change Tracking
+### Change Tracking
 
 Server API exclusive methods for tracking project changes.
 
@@ -666,89 +664,7 @@ console.log(changes.removed); // Removed paths
 const contributors = await framer.getChangeContributors();
 ```
 
----
-
-## Canvas Editing
-
-**Use this for all design tasks** — creating pages, building sections, recreating designs from screenshots, or any task that involves layout or visual styling on the canvas.
-
-**Hard rule:** For design/layout work, do **not** use low-level node APIs (`createNode`, `setAttributes`, `setRect`, etc.). Always use the canvas editing flow (`getAgentSystemPrompt` + `getAgentContext` + `readProjectForAgent` + `applyAgentChanges`). If you start writing low-level node code for design work, stop and switch to canvas editing methods.
-
-**Access note:** Canvas editing `agent` methods are employee-only. If these methods fail or are unavailable, the account likely does not have employee access.
-
-### Methods
-
-**`framer.getAgentSystemPrompt()`** — Returns the command reference, design rules, layout patterns, and examples. This is the sole documentation for the command syntax and query types. It is static (same for every project) — fetch once per session and persist to a file.
-
-**`framer.getAgentContext({ pagePath })`** — Returns the project's available fonts, components, color tokens, text style presets, and icon sets for the target page scope. Fetch before generating commands and use the same `pagePath` across context/read/apply calls.
-
-**`framer.readProjectForAgent(queries, { pagePath })`** — Reads project state. Query types are documented in the system prompt. Use liberally — query the page tree, icon sets, components, and examples before generating commands. Multiple queries can be batched in a single call. Never guess at names for examples, icon sets, or fonts — always look them up first.
-
-**`framer.applyAgentChanges(dsl, { pagePath })`** — Applies commands to the canvas. Node IDs you assign are temporary — re-read the page tree via `readProjectForAgent` if you need actual IDs after applying.
-
-### Workflow
-
-```js
-// 1. Save the system prompt to a file (once per session).
-const fs = require("fs");
-const prompt = await framer.getAgentSystemPrompt();
-fs.writeFileSync("/tmp/framer-canvas-reference.txt", prompt);
-console.log("Saved to /tmp/framer-canvas-reference.txt —", prompt.length, "chars");
-
-// 2. Get project context
-const projectCtx = await framer.getAgentContext({ pagePath: "/" });
-console.log(projectCtx);
-
-// 3. Read project state (query types are in the prompt)
-const { results } = await framer.readProjectForAgent(
-  [{ type: "page", path: "/" }],
-  { pagePath: "/" }
-);
-
-// 4. Apply changes
-await framer.applyAgentChanges(dsl, { pagePath: "/" });
-```
-
-**You must read the entire system prompt file before writing any commands.** It contains command syntax, design rules, layout patterns, examples, and query documentation. Skipping sections will cause incorrect output.
-
-After applying changes, take screenshots to inspect the result. Check padding, spacing, typography, icon choice, and alignment. Iterate with additional `readProjectForAgent` + `applyAgentChanges` passes until visually accurate.
-
-When setting text content, use raw Unicode characters directly (e.g. `→` not `\u2192`).
-
-Always fetch fresh context per session — the format may change between versions.
-
-### What canvas editing can do
-
-Beyond basic page layout, the command language supports:
-
-- **Colour tokens** — Create color tokens (`ColorStyleTokenNode`) with light/dark mode variants. Reference them across the project for consistent theming.
-- **Text style presets** — Create reusable typography presets (`TextStylePresetNode`) and apply them to text nodes. Build full typographic systems (headings, body, captions, etc.).
-- **Smart components** — Author reusable components (`ComponentNode`) with multiple visual variants, scoped variables, and property controls. Instantiate them anywhere with `ComponentInstanceNode`.
-- **Interactive effects** — Add hover effects (scale, opacity, color), tap effects, scroll-triggered appear animations, transitions between component variants, and event handlers.
-- **Icon sets** — Insert icons from named vector sets. Query available sets and icons via `readProjectForAgent`.
-- **Responsive breakpoints** — Create page breakpoints (Desktop, Tablet, Mobile) using the replica/variant system, with per-breakpoint overrides.
-- **Complex layouts** — Stack and grid layouts with auto-fill, fractional units, space-between distribution, and nested grids for asymmetric layouts.
-
----
-
-## Capabilities
-
-What you can do with the Framer CLI:
-
-- **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.
-- **Assets**: Upload and manage images and files.
-- **Localization**: Manage translations programmatically.
-- **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.
-
----
-
-## Known Limitations
+### Known Limitations
 
 - **Pages**: No list, delete, update, move, or settings APIs (create only)
 - **Code overrides**: Cannot assign overrides to nodes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-dalton",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "type": "module",
   "bin": {
     "framer-dalton": "./dist/cli.js"
@@ -35,8 +35,5 @@
     "tsx": "^4.19.0",
     "typescript": "^5.9.2",
     "vitest": "^4.0.18"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org"
   }
 }

package/docs/all-skills.md

@@ -1,6 +0,0 @@
-## All Skills
-
-- `npx framer-dalton skill` — Server API docs (sessions, collections, canvas, styles, publishing)
-- `npx framer-dalton skill code-components` — Code component authoring guide
-- `npx framer-dalton skill property-controls` — Property control reference (all 20+ types)
-- `npx framer-dalton skill component-examples` — Complete code component examples

package/docs/code-components.md

@@ -1,115 +0,0 @@
-# Framer Code Components
-
-## Best Practices
-
-### Component Structure
-
-```tsx
-import { addPropertyControls, ControlType } from "framer";
-import { motion } from "framer-motion"; // NOT from "framer"
-
-interface MyComponentProps {
-  /* typed props */
-}
-
-/**
- * @framerSupportedLayoutWidth any-prefer-fixed
- * @framerSupportedLayoutHeight any-prefer-fixed
- */
-export default function MyComponent(props: MyComponentProps) {
-  // component
-}
-
-addPropertyControls(MyComponent, {
-  /* controls */
-});
-```
-
-### Platform Constraints
-
-These will cause errors if violated:
-
-1. **Single file, default export** - Use named `function` syntax (not arrow functions), no named exports
-2. **Imports** - Only `react`, `react-dom`, `framer`, `framer-motion`. Import `motion` from `"framer-motion"`, not `"framer"`
-3. **Position** - Use `position: relative` on the root element, never `fixed`
-4. **SSR** - Guard `window`/`document` access: `if (typeof window !== "undefined")`
-5. **Annotations** - Include `@framerSupportedLayoutWidth/Height` in a `/** */` block comment immediately above the component function
-6. **Types** - Provide a typed props interface (e.g. `MyComponentProps`). Avoid NodeJS types like `Timeout` — use `number` instead
-
-### Layout Annotations
-
-| Content           | Width              | Height             |
-| ----------------- | ------------------ | ------------------ |
-| No intrinsic size | `fixed`            | `fixed`            |
-| Text/auto-sizing  | `auto`             | `auto`             |
-| Flexible          | `any-prefer-fixed` | `any-prefer-fixed` |
-
-Detect auto vs fixed sizing: check if `style.width` or `style.height` is `"100%"`.
-
-### Property Controls
-
-To make components configurable in Framer's properties panel, add property controls:
-
-- To make colors customizable, use `ControlType.Color`. Reuse the same prop for elements sharing a color.
-- To make text styling customizable, use `ControlType.Font` with `controls: "extended"` and `defaultFontType: "sans-serif"`.
-- For images, use `ControlType.ResponsiveImage`. Set defaults in the component body via destructuring (the control doesn't support `defaultValue`).
-- Provide a `defaultValue` for every prop so components render correctly in the Framer canvas. Include at least one item in `ControlType.Array` controls.
-- `ComponentName.defaultProps` is not supported in Framer — use `defaultValue` on the property control instead.
-- Use `hidden` for conditional visibility: `hidden: (props) => !props.showFeature`
-- Prefer sliders over steppers unless step values are large.
-- Keep controls focused — make key elements configurable, hardcode the rest.
-- See `npx framer-dalton skill property-controls` for the full property control reference.
-
-### Image Defaults (in component body)
-
-```tsx
-const {
-  image = {
-    src: "https://framerusercontent.com/images/GfGkADagM4KEibNcIiRUWlfrR0.jpg",
-    alt: "Default",
-  },
-} = props;
-```
-
-### Animation Performance
-
-```tsx
-import { useIsStaticRenderer } from "framer";
-import { useInView } from "framer-motion";
-
-const isStatic = useIsStaticRenderer();
-const ref = useRef(null);
-const isInView = useInView(ref);
-
-if (isStatic) return <StaticPreview />; // Show useful static state
-// Pause animations when out of viewport
-```
-
-- For very complex animations, consider WebGL instead of `framer-motion`.
-- Static preview should include visual effects, not just text.
-- Wrapping state updates in `startTransition()` prevents UI blocking and keeps interactions smooth.
-
-### Text
-
-- For auto-sized components with text, apply `width: max-content` or `minWidth: max-content` to prevent text from collapsing.
-
-### Common Errors
-
-- WebGL cross-origin: handle `SecurityError: Failed to execute 'texImage2D'` for cross-origin images.
-- Inverted Y-axis: check if WebGL images render upside down and accommodate.
-
-### Accessibility
-
-- `aria` roles on interactive elements
-- Semantic HTML (`<nav>`, `<article>`, `<section>`)
-- `alt=""` on decorative images
-- 4.5:1 color contrast
-
-## Term Interpretation
-
-- "responsive" → width/height 100%
-- "modern" → 8px radius, 16px spacing, subtle shadows
-- "minimal" → limited colors, whitespace
-- "interactive" → hover/active states
-- "accessible" → ARIA, semantic HTML
-- "props"/"properties" → Framer property controls