@daydreamui/figma 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,207 @@
-# Temporary Holding Version
+# Figma
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local Daydream plugin that puts what is open in Figma desktop beside the
+real page. The design stays in Figma; Daydream takes an image of it, or
+asks your agent to transcribe it as a page, and lets any agent connected to
+Daydream read Figma through four tools. There is no plugin inside Figma.
+Enable **Figma** in Daydream's Plugins page (⌥⌘P).
+
+From this repository, install the plugin with:
+
+```sh
+pnpm install
+pnpm ship plugins/daydream.figma --enable
+```
+
+The build produces `plugins/daydream.figma/dist/index.js`. The install command
+copies the plugin into the user's Daydream plugins folder and records its trust.
+
+## Requirements
+
+- Figma desktop, open on this machine, with the file you want to read open
+  in it.
+- Figma's Dev Mode MCP server turned on in Figma's preferences. The plugin
+  reads it at `http://127.0.0.1:3845/mcp`, on this machine only; nothing
+  leaves it.
+- A Figma seat that Figma gives the Dev Mode MCP server to (a paid plan, as
+  Figma requires).
+
+The panel's first line says whether Figma answers, probed when the panel
+opens, when a project is opened and when the window comes to the front.
+Figma closed, or the server off, is a normal state: the line says what to
+do, and each gesture answers the same sentence.
+
+## The two gestures
+
+Both take what is selected in Figma, and nothing else: one frame, or
+several, up to 12 at once (past that, each gesture refuses in one sentence
+naming the cap). There is nothing to type; select in Figma, press here.
+Each begins by reading the selection, and says what it found in its own
+words: nothing selected, Figma not there (or refusing, in the server's own
+sentence), or Figma too slow to answer ("Figma took too long to answer;
+try again"). A frame's id and name are the selection's listing's, so a
+frame whose own metadata is slow to come is still that frame. A layer
+inside a component instance — which Figma lists with an id of its own
+shape and refuses to read by it — is left out before anything is asked,
+and the error line says so: "2 layers inside instances were left out;
+select their frames."
+
+1. **Add as image** takes the frame's screenshot by its id, copies it into
+   the project's `assets/` (named by its bytes, so the same frame twice is
+   one file), and lands it on the canvas as a `daydream.figma.reference`
+   item at free space, selected and brought into view, as one undo step.
+   Its title bar carries the frame's name, as the selection listed it, and
+   renames it; nothing is drawn under the image. With nothing selected, the
+   page's screenshot lands, unnamed. A screenshot wider than 1200 px lands at that width; a resize
+   keeps the image's proportions, and a double-click on a handle resets it.
+   The payload is `{src, name, nodeId}`: `src` a file of the project's own
+   (`assets/<file>`), `name` the frame's, `nodeId` Figma's id or null. With
+   several frames selected, one screenshot is taken per frame by id and
+   every image lands in one row from free space, each 40 px right of the
+   last, side by side to compare, all selected, as one undo step; a frame
+   whose screenshot Figma refuses is left out and named in the error line
+   while the others land. (An earlier build kept a `link` the user had
+   typed on the payload; a canvas saved by it still renders, the `link`
+   let through and never read.)
+2. **Add as page** asks the project's agent to transcribe the frame as a page
+   of the project (Daydream's decision #96: the button is the prompt, and
+   nothing starts without it). The prompt names the frame — its id, its
+   name and its width — and asks for a
+   transcription through the tools below and the dream-author workflow: a
+   draft whose HTML and CSS are the project's own, finalized as a new page
+   titled after the frame. The plugin holds the project's conversation for
+   its own rounds (`contributes.conversation`), so the agent starts whether
+   the Agent plugin is on or not, and the panel shows the round it asked
+   for under the buttons: a status line — asking the agent, the agent
+   working, done with the page it wrote when a tool call named one, or the
+   agent's own note of why it stopped — each tool call as one line with a
+   mark for its state, the last paragraph of what the agent said, the
+   permissions the agent asks during the round with its own options as
+   buttons (a minimized panel carries a dot while one waits), and Cancel
+   while the turn runs. Every ask is yours, those about the plugin's own
+   four tools included: the plugin answers none. Nothing shows before the
+   first round; the last round stays when its turn ends. The prompt is a
+   turn of the project's one conversation, so the Agent panel shows the
+   same turn when it is on, and a turn asked there is not shown here. It
+   needs a frame — with nothing selected in Figma, the error line says to
+   select one first, and the agent is not started — and an agent
+   installed; the error line says which is missing. With several frames
+   selected, one prompt names every frame by name and id and asks for one
+   page per frame, titled after each, each compared against its own
+   screenshot; the panel shows that one round. The one-frame prompt
+   carries the frame's width when its metadata answers within 3 s, and
+   goes without it otherwise.
+
+   Under the two buttons sits a settings row, the same the Impeccable box
+   shows, hidden on a host that runs no agents. **Agent** is a select of
+   the agents Daydream knows, the one the Agent panel would show chosen
+   first — the project's conversation's, else the one used last, else the
+   first installed — with its state after it in a word or two ("starts on
+   Add as page" until a conversation with it is open; starting, ready,
+   working, needs a sign-in, stopped). Choosing another starts nothing by
+   itself: the next Add as page starts it, as a new conversation when it
+   is not the one the project's conversation is with (Daydream's
+   `intent: "new"`, the user's one switch). Once a conversation with the
+   chosen agent is open, the row adds the agent's **Mode** (unless the
+   agent offers its mode among its settings, which then stands for it) and
+   each of its settings — a select, or a checkbox — set through Daydream
+   as the Agent panel sets them, so the two never disagree. The agent's
+   permission behaviour lives there (Claude Code's is its mode), and is
+   your choice: pick a mode that asks for each tool, or one that does
+   not, before pressing Add as page a second time, or in the row as the
+   round runs. Before the first Add as page the row shows the agent alone,
+   since modes and settings are a live conversation's.
+
+Why the agent and not a converter: Figma's Dev Mode server emits React and
+Tailwind for `get_design_context`, in every configuration it was asked in
+(`clientLanguages` of `html,css`, `clientFrameworks` of `unknown`, `none`,
+`vanilla` and `html`, and `forceCode`), and its own notes say the code must
+be converted. A mechanical rewrite of Tailwind classes into CSS would ship a
+page that looks like the frame only by accident; the transcription is the
+agent's work, with the frame's tree, code and screenshot in front of it.
+
+## The agent tools
+
+The host part registers four MCP tools, so any agent connected to Daydream
+reads Figma through it with no Figma setup of its own. Each takes an
+optional `node` (an id, or a Figma link with a `node-id`; none for Figma's
+selection — the panel never names one, an agent does), reads Figma only,
+and answers one sentence as an error result when Figma does not answer. `figma_metadata` and `figma_variables` are marked read-only;
+`figma_screenshot` and `figma_design_context` are not, since they write
+the screenshot into the project.
+
+| Tool                   | Answers                                                                                                                                                                   |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `figma_metadata`       | the node's tree as `get_metadata` gives it: XML of ids, layer types, names, positions and sizes, the server's notes after it; with nothing selected, the document's pages |
+| `figma_design_context` | the node as code (`get_design_context`: React and Tailwind, with `data-node-id` attributes) and the notes; with `screenshot: true`, its PNG is written too                |
+| `figma_screenshot`     | the node's PNG (`get_screenshot`), written into the open project's `.daydream/figma/<node>.png` (`selection.png` for the selection) and answered as that path             |
+| `figma_variables`      | the variables the node uses (`get_variable_defs`), as the server spells them                                                                                              |
+
+A tool's result carries text alone on this plugin API, so a screenshot is a
+file in the project's `.daydream/` scratch, never through a link, for the
+agent to read with its own file tools. The images a design context names
+are served at `http://localhost:3845/assets/…` only while Figma runs; a
+page that uses one copies it into the project's `assets/`.
+
+## What is not done
+
+- No plugin inside Figma: Daydream reads Figma through Figma's own server
+  and adds nothing to Figma.
+- No write-back: nothing changes in Figma, ever.
+- No `.fig` files: only the file open in Figma desktop is read, through its
+  server, never a file on disk or Figma's web API.
+- No converter of Figma's code into HTML and CSS (above).
+
+## Limits
+
+- One file at a time: the one open in Figma desktop. The server reads the
+  current page's nodes and the selection, and never takes or tells a file
+  key, so a `node` an agent gives a tool as a link is read against the
+  open file whichever file the link names: a Share link from another file
+  reads that id in the open file, or is refused when the id is not there,
+  and nothing on this side can tell. Open the linked file in Figma first.
+- A node that is not on the open page, or an id of a shape the server does
+  not take, is Figma's refusal, said in the error line.
+- The image's name and id come from the selection's listing; the
+  `figma_screenshot` tool, which takes a node from an agent, names it from
+  the frame's metadata, asked under 3 s of its own (a name is a courtesy),
+  and names the node the agent gave when that does not answer in time, its
+  file named after it. A screenshot of the page itself (nothing selected)
+  lands as "Figma image", unnamed, to rename in its title bar.
+- The selection's listing is read under 5 s of its own: past that the
+  gesture says Figma was too slow, and nothing is asked further.
+- A streamed answer is buffered to 32 MB at most; a server that streams
+  past that without answering is dropped with one sentence.
+- `get_variable_defs` answers a JSON object of the variables the node
+  uses, name to value, every value a string
+  (`{"Size":"42","White":"#ffffff","Name":"John"}`, seen live; `{}` for
+  none; an alias resolved to the value it points at), passed through as
+  text, unread.
+- The server's own bounds apply: a very large frame may be answered as
+  metadata alone, and one call of the client — its handshake, a session
+  opened again and the retry included — is given 45 s in all, under the
+  50 s the kernel allows a host-part call, so what the panel hears is the
+  client's sentence and never the kernel's.
+
+## Validation
+
+`pnpm test` runs the host part over a fake client and a fake host (the
+channels, the four tools — the one list the manifest declares — the
+screenshot file under the project, Figma not answering as a sentence), the
+gestures over a fake `dd` (the selection's kinds, a slow metadata read, the
+layers inside instances left out, several frames) and the pure parts (the
+payload rules, a saved `link` let through, the frame read from the metadata
+XML, the prompt). The round reader's three folds carry `mirrors-adapted`
+markers naming the agent panel's thread state in the kernel, so
+`test:kernel` reports when the kernel's changes.
+`pnpm test:kernel <daydream-checkout> plugins/daydream.figma` mounts the
+real shell with host-part replies in memory: the state line, an image
+landed and selected with its file copied, three frames in a row, a saved
+item with its `link` still drawn, nothing selected, the unreachable
+sentence, Add as page with no agent, and — over a scripted `dd.agent` — the round block as the
+agent takes the prompt, calls tools, asks a permission and ends, Cancel,
+a turn asked from the agent panel left alone, and the settings row: the
+project's agent chosen, the mode and settings of the open conversation
+set through the host, and another agent chosen started as a new
+conversation on the next Add as page. The plugin requires a Daydream build reporting API 3.0. See the
+repository’s kernel pin and release gate before shipping.