@daydreamui/paper 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,278 @@
-# Temporary Holding Version
+# Paper
 
-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 Paper desktop on the
+canvas. The design stays in Paper; Daydream takes an image of it, or
+converts it into a page of the project, and lets any agent connected to
+Daydream read Paper through eight tools. Paper's export is HTML and CSS in
+all but syntax, so Add as page is a converter and not a prompt: no agent
+is asked, and the page lands in seconds. There is no plugin inside Paper.
+Enable **Paper** in Daydream's Plugins page (⌥⌘P).
+
+From this repository, install the plugin with:
+
+```sh
+pnpm install
+pnpm ship plugins/daydream.paper --enable
+```
+
+The build produces `plugins/daydream.paper/dist/index.js`. The install command
+copies the plugin into the user's Daydream plugins folder and records its trust.
+
+## Requirements
+
+- Paper desktop, open on this machine, with the file you want to read open
+  in it. The plugin reads the file you are viewing.
+- Nothing to turn on in Paper, and no paid seat: Paper serves its MCP server
+  on this machine, and the plugin reads it at `http://127.0.0.1:29979/mcp`.
+
+What leaves the machine, and what does not. Paper is read locally, and the
+project is never sent anywhere. The image fills a page uses are downloaded
+from Paper's asset host (`app.paper.design` only; a fill served from
+anywhere else is not downloaded, stays a url in the page's sheet and is
+warned about). And a converted page links Google Fonts for the file's
+font families that are not system fonts, one `<link>` per family, so
+opening that page, on the canvas or anywhere, asks `fonts.googleapis.com`
+for them when it renders. The weights a link asks for (and the italic, when
+a node uses one) are the ones the page uses, read from its nodes' styles
+and the tokens they refer to, because Google refuses a range for a static
+family; a weight a static family lacks is the one case in which the link
+still fails, and the page shows that font's fallback.
+
+The panel's first line says what Paper answers, probed with one call of
+the host part (the selection's read, which carries the file's name) when
+the panel opens, when a project is opened and when the window comes to the
+front. It
+shows one of these, always in sentence case:
+
+- "Looking for Paper desktop…" until the first probe answers.
+- "Paper is not reachable: open Paper desktop with the file you want to
+  read" when Paper is closed or its server is off. Each gesture answers the
+  same sentence.
+- `Amazing jewel · 3 selected`, the file you are viewing and how many nodes
+  are selected in it.
+- `Amazing jewel · nothing selected`.
+
+## The two gestures
+
+Both take what is selected in Paper, and nothing else: one artboard, 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 Paper, press here.
+Each begins by reading the selection, and each kind of answer gets its own
+sentence: nothing selected ("Select an artboard in Paper first."), Paper
+not there (or refusing, in its own sentence), or Paper too slow to answer
+("Paper took too long to answer; try again.").
+
+1. **Add as image** takes each node's screenshot by its id, copies it into
+   the project's `assets/` (named by its bytes, so the same node twice is
+   one file), and lands it on the canvas as a `daydream.paper.reference`
+   item at free space, selected and brought into view, as one undo step.
+   Its title bar carries the node's name, as the selection listed it, and
+   renames it; nothing is drawn under the image. 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 node's, `nodeId` Paper's id. With several
+   nodes selected, one screenshot is taken per node 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 node whose screenshot
+   Paper refuses is left out and named in the error line while the others
+   land.
+2. **Add as page** converts each selected artboard into a page of the
+   project and lands it on the canvas, in the selection's order, with no
+   agent in between. For each artboard Daydream reads its tree, its
+   computed styles, each SVG's markup and the file's tokens from Paper,
+   writes the files under What lands, and lands the page as a viewport as
+   wide as the artboard. The status says `Added <name> as a page.` or `Added 3 pages:
+Garden, Archive, Notes.`; the error line carries what the conversion
+   warned of, the remote files that stayed links, and any artboard that
+   failed while the others landed.
+
+   What the page is: faithful and plain. Every text is a `p`; every box is
+   a `div` with a class named after its Paper layer (a layer with a
+   default name, such as `Frame`, gets `<type>-<n>`, and every Text node
+   gets `text-<n>` whatever its layer is called); an SVG is
+   its markup with the class on the root; flex and absolute layout are as
+   Paper has them, the width is fixed at the artboard's, and there are no
+   media queries; the sheet sets `box-sizing: border-box` on everything,
+   as Paper does (its computed styles leave it out). Tokens stay
+   `var(--color-ink)`. Every element carries
+   `data-paper="<id>"`, the Paper node it came from. Making it semantic
+   (headings, lists, landmarks, a layout that flows) is a rework of a page
+   already on the canvas, afterwards, which an agent or the Impeccable
+   verbs do; the converter does not guess it.
+
+### What lands
+
+Add as page, and the `paper_page` tool, write these files at the project's
+root:
+
+- `<stem>.css`: the page's sheet. The stem is the artboard's name made
+  file-safe (`CSS Zen Garden` becomes `css-zen-garden`), with `-2`, `-3` and on
+  while `<stem>.html` or `<stem>.css` is taken.
+- `<file>-tokens.css`: the Paper file's design tokens as a `:root {}`
+  sheet, named after the file (`amazing-jewel-tokens.css`), shared by every
+  page of that file. It is rebuilt from Paper's tokens, each passed through
+  the same guard as the page's styles (a value that would end its rule, or
+  load from somewhere a page may not, is left out and named). The
+  project's copy is never replaced. It is
+  **written** when absent; **kept** when it is there with Paper's text
+  already; **differs** when it is there with other text, in which case it
+  is kept as it is, the page links it as it is, and the error line says
+  "the project's tokens sheet differs from Paper's tokens and was kept";
+  and **none** when the file has no tokens, in which case the page links no
+  tokens sheet and nothing is written.
+- `assets/paper-<name>-<hash>.<ext>`: each image fill the page uses,
+  downloaded from Paper's asset host and named from the whole url (the
+  last part of its path, then the first eight hex digits of the url's
+  sha256, then the extension the download's content type gives: a fill
+  served at a `.html` url that is a PNG is saved as a `.png`), so two
+  images from different places never share a file; one
+  already there is the same url's and is kept, one that cannot be
+  downloaded stays a url and is named in the error line.
+- `<stem>.html`: the page itself, written by Daydream's `createPage` and
+  not by the host part, at the path the host chose (`<stem>.html`, `-2` and
+  on). Landing it and placing its viewport at the artboard's size is one
+  undo step; an undo takes the viewport off and leaves the files, as it
+  does for every page Daydream makes.
+
+Add as page and the `paper_page` tool are one call of the host part,
+`paper-page`: it reads Paper, writes the files, asks the browser part to
+land the html (`land-page`) and, when that fails, takes its own files back
+before it answers. A page is therefore either landed, with its path and
+viewport, or a rejection that says what became of its files. A landing
+that fails takes back what the call wrote, in three cases and no other.
+
+- The host part's own write fails or is late: the call takes back what it
+  had written before it answers, and the failure names the cause.
+- `createPage` rejects the page (its path was taken meanwhile, there is no
+  room): the host part removes the call's own files — the sheet, the
+  tokens sheet if this call wrote it, the assets this call wrote — each
+  only while it still holds the bytes the call wrote and no other page
+  uses it. The error line follows the failure with one of four sentences,
+  by what became of them:
+  - "It had written no files." when the call had written none;
+  - "The files it had written were removed: a.css, amazing-jewel-tokens.css."
+    when all went;
+  - "Of the files it had written, a.css was removed and
+    assets/paper-3f2a-1c9e04ab.jpg stayed, edited since or used by another page."
+    when some stayed, both lists named;
+  - "It could not take them back: a.css, assets/paper-3f2a-1c9e04ab.jpg." when
+    neither list says anything (files already gone), with no cause guessed at.
+
+  If the removal itself fails, the line says "Its files could not be
+  removed (<why>) and stayed: …".
+
+- The canvas answers neither way and the page's html exists as Daydream
+  was given it (Daydream wrote it, so the page may be there), or the
+  project changed meanwhile: nothing is taken back, and the sentence says
+  the files were kept.
+
+When the project changed after Paper was read, the files stay in the
+project they were written to, and nothing more is done.
+
+## The agent tools
+
+The host part registers eight MCP tools, so any agent connected to Daydream
+reads Paper through it with no Paper setup of its own. Each reads Paper
+only, and answers one sentence as an error result when Paper does not
+answer. A `fileId` left out is the file you are viewing. The reads are
+marked read-only; `paper_screenshot` and `paper_page` are not, since they
+write into the project.
+
+| Tool               | Takes                                                                                      | Answers                                                                                                                                                                                                    |
+| ------------------ | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `paper_info`       | optional `fileId`                                                                          | the file: its id and name, its pages, its artboards with their sizes, its font families, its tokens                                                                                                        |
+| `paper_selection`  | none                                                                                       | what is selected in Paper: each node's id, name, type and size, with the file they are in                                                                                                                  |
+| `paper_tree`       | `nodeId`, optional `fileId`, optional `depth` (3 by default, at most 10)                   | the node's subtree as Paper's indented summary: type, layer name, id, size, and a text node's text                                                                                                         |
+| `paper_styles`     | `nodeIds[]` (at most 500), optional `fileId`                                               | the computed CSS of the nodes, batched: camelCase properties with units, tokens kept as `var(--name)`                                                                                                      |
+| `paper_jsx`        | `nodeId`, optional `fileId`, optional `format` (`inline-styles` by default, or `tailwind`) | the node as JSX; how an SVG's markup is read                                                                                                                                                               |
+| `paper_tokens`     | optional `fileId`, optional `format` (`css` by default, or `json`)                         | the file's design tokens, as a `:root {}` stylesheet or structured                                                                                                                                         |
+| `paper_screenshot` | `nodeId`, optional `fileId`                                                                | the node's image as Paper sends it (JPEG today), written into the open project's `.daydream/paper/<node>.jpg` and answered as that path                                                                    |
+| `paper_page`       | `nodeId`, optional `fileId`                                                                | the conversion Add as page runs, for the node: the files above written and the page landed on the canvas; the answer names the page's path and its viewport, and any remote file the canvas could not copy |
+
+A tool's result cannot return an image, 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. `paper_page` has the page landed by
+the browser part, so it needs Daydream open on the project in a tab.
+
+## What is not done
+
+- No plugin inside Paper: Daydream reads Paper through Paper's own server
+  and adds nothing to Paper.
+- No write-back: nothing changes in Paper, ever. A page edited in Daydream
+  does not go back to its artboard.
+- No re-sync: a page converted once is the project's own file. Add as page
+  again makes a second page (`-2`) beside it; it does not update the first
+  from an artboard that changed.
+- No files on disk: only the file open in Paper desktop is read, through
+  its server.
+- No shared package with the Figma plugin yet. The transport and the probe
+  are copies of `packages/figma-devmode`'s and the unreachable sentence
+  follows its pattern; the client's session core, `land.ts` (the page half
+  is new) and `ReferenceItem.tsx` are adapted from the Figma package's and
+  plugin's. Each is marked as such at the top with the commit it was taken
+  at; the file-writing helpers (`bridge/files.ts`) follow the
+  Figma bridge's care and carry only the `mirrors-adapted` marker for its
+  `.daydream/` gitignore. One shared package is the follow-up.
+- No semantic markup and no responsive rules (above).
+
+## Limits
+
+- One file at a time: the one you are viewing in Paper desktop. Another
+  file's nodes are read by giving a tool its `fileId`; the panel always
+  takes the file in view.
+- Up to 12 nodes per gesture: a screenshot or a conversion each is a round
+  trip to Paper.
+- The selection's listing is read under 5 s of its own: past that the
+  gesture says Paper was too slow, and nothing is asked further.
+- A request to Paper is given 20 s and one call of the client — its
+  handshake, a session opened again and the retry included — 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. A large artboard's
+  conversion reads its styles 100 nodes at a time and may come near that.
+- The page call has one budget, 45 s, for the whole of it: the reads, the
+  downloads, the writes and the landing, the panel's call and the
+  `paper_page` tool's alike, so it ends under the 50 s the kernel allows a
+  host-part call. Past it before the writes, the sentence is "Converting
+  <name> took longer than 45 s; nothing was written". The landing is given
+  what is left of the budget; when the canvas has not answered by then the
+  call is rejected with "<name> was converted, but the canvas did not answer
+  in time; its files were kept: …" and nothing is taken back, since the page
+  may still land.
+- A call's writes are remembered for ten minutes, so the rollback of one
+  page never removes a file another page of that time uses; a host restart
+  forgets them.
+- An agent calling `paper_page` while the panel lands pages may find an
+  asset or the tokens sheet shared between two pages. A rollback never
+  removes a file another live call's page uses; it names it as one that
+  stayed.
+- A Text node whose text holds a line break cannot be read from Paper's
+  tree summary today (whether Paper escapes it is unverified), and fails
+  the conversion with a sentence naming the node.
+- Shader and effect nodes (a lens distortion, say) have no HTML: they land
+  as plain `div`s and the conversion warns, naming the node.
+- A node selected inside an SVG is refused with a sentence; select the SVG
+  itself, or its artboard.
+- An artboard on a page other than the one Paper shows takes the shown
+  page's font list, so a font used only there is not linked.
+- Images a page uses are downloaded once into `assets/`; a fill served
+  from anywhere but Paper's asset host, or one whose download fails, stays
+  a url, and that part of the page works only while that address does.
+- The width is the artboard's. A page converted from a 1440 px artboard
+  does not reflow below that.
+
+## Validation
+
+`pnpm test` runs the shared parts (the payload rules, the channel answers'
+shapes, the sentences), the gestures over a fake `dd` (the selection's
+kinds, several nodes, a node refused among several, the pages landed with
+their path and frame, the project changing under a gesture), and the host
+part and the package's converter over their fixtures. `pnpm test:kernel
+<daydream-checkout> plugins/daydream.paper` mounts the real shell with
+host-part replies in memory: the state line in its states, an image landed
+and selected with its file copied, three nodes in a row, nothing selected,
+the unreachable sentence, Add as page landing a page at the artboard's
+frame, one of three refused while two land, a landing the shell refuses
+having its files taken back by the host part, and the handler the host's `paper_page` tool
+lands its page through. The plugin requires a Daydream build reporting API 3.0. See the
+repository’s kernel pin and release gate before shipping.