@clearlysh/beehaven 0.8.34 → 0.8.36

package/skills/clearly-artifacts/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: clearly-artifacts
+description: >-
+  Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so: the connector cannot make a running page.
+  Put a self-contained interactive HTML page into a Clearly workspace, the way a
+  Claude artifact works: an explainer, an animation, a small tool, a calculator, a
+  chart that runs. Covers which of the three HTML homes runs scripts (a SITE does,
+  a canvas ARTIFACT card does but cannot be clicked, a NOTE never does), the exact
+  CLI calls, the sandbox limits, updating, filing in a project, how a person opens
+  it, and QA. Use when asked to publish, host or add an HTML page, demo or animation
+  to the workspace. Triggers: "make an artifact", "publish this HTML", "add this page /
+  animation / explainer to the workspace", "host this demo", "interactive page",
+  "put this HTML on the canvas", "why doesn't my page's script run".
+---
+
+# Clearly artifacts — a running HTML page in the workspace
+
+Sign in first (`clearly-agent`). `beehaven env` must name the environment you mean; staging and
+production hold different workspaces.
+
+## 1. Pick the home — only two of the three run code
+
+| Home | Make it with | Scripts and CSS animation | Clickable | Search, history | Opens at |
+|---|---|---|---|---|---|
+| **Site** | `compose-upload-init` → `file-teleport-inline` → `compose-upload-finalize` | run | yes | not in `document-search`; no version history; a re-upload overwrites | Recents or project card → `/compositions/detail?id=<id>` |
+| **Canvas artifact** | `canvas-act` `canvas.add-artifact` | run | **no**: the card never takes pointer events, so it pans like a picture | no; it is part of the canvas and is deleted with it | the canvas, `/c/<compositionId>` |
+| **Note** | `document-create {html}`; `page-write` (in-app chat only) | **never**: it opens in the document editor, which drops `<script>`, `<style>` and inline `<svg>` | n/a | yes, both | `/documents/<id>` |
+
+- An interactive page someone opens, clicks through or comes back to is a **site**. This is the
+  Claude-artifact equivalent and the default.
+- A page that only needs to be **seen** beside other cards (a looping animation, a live chart in a
+  review board) is a **canvas artifact**. Buttons inside it cannot be pressed.
+- Prose the team will read, search and edit is a **note**. Never put a script in a note: it
+  is stored, and then nothing ever runs it. Editing the note in the app rewrites its body.
+
+No home gives a public link that runs. Every share link (`/r/…`) is served with
+`script-src 'none'`, and a shared composition renders as a static picture. Say so when someone asks to
+publish an interactive page outside the workspace.
+
+## 2. Write it self-contained
+
+Both running homes inject the page with `srcdoc` into `<iframe sandbox="allow-scripts">`, with no
+`allow-same-origin`. The page gets an opaque origin (`window.origin === "null"`).
+
+- **One file.** `<!doctype html>`, `<meta name="viewport" content="width=device-width, initial-scale=1">`,
+  CSS in `<style>`, JS in `<script>`, art as inline SVG, images and fonts as `data:` URIs,
+  system font stacks. Make no network requests and load no CDN scripts.
+- **The sandbox blocks:** `localStorage`, `sessionStorage`, cookies and IndexedDB (accessing them
+  throws), `alert`/`confirm`/`prompt`, form submission, popups, `window.open` and top-level
+  navigation. Keep state in memory, and wrap any storage access in `try`.
+- **A site's other files are rarely reached.** The preview rewrites only `src="…"`/`href="…"`
+  in the entry HTML that name a build file exactly (up to 60 files). It does not rewrite `url()`
+  inside CSS, `import`, or `fetch` of a sibling file. Inline them.
+- **Size:** a canvas artifact is at most 512 KB. A site file is at most 6 MB inline. Over the CLI
+  WebSocket, keep a single `beehaven call` under about 900 KB, or use `beehaven compose push`,
+  which switches to a presigned upload.
+- **Motion:** honour `@media (prefers-reduced-motion: reduce)`. A canvas card lays the page out
+  at `designWidth` (default 1280) and grows to the document's full height. A `100vh` layout
+  makes it grow again on every fit, so size sections in px or by content.
+
+## 3. Make it (CLI)
+
+Build JSON payloads with a script and pass them as `@file`. Do not hand-escape HTML into a shell
+argument.
+
+**Site, from one file** (one `file-teleport-inline` per file; `entryPoint` and each path are
+relative to `build/`):
+
+```sh
+beehaven call compose-upload-init '{"name":"MCP tokens explained","sourceType":"static","entryPoint":"index.html","projectId":"<projectId>"}'
+# → { "id": "cmp_…", "created": true }
+node -e 'const fs=require("fs"),b=fs.readFileSync("page.html");fs.writeFileSync("up.json",JSON.stringify({key:"compositions/<id>/build/index.html",composition:true,name:"index.html",mimeType:"text/html",size:b.length,data:b.toString("base64")}))'
+beehaven call file-teleport-inline @up.json
+beehaven call compose-upload-finalize '{"compositionId":"<id>","totalBytes":<bytes>,"entryPoint":"index.html"}'
+beehaven call composition-fs '{"compositionId":"<id>","action":"list"}'   # one row per file, sizes match
+```
+
+Both parts of the upload are load-bearing. A `key` outside `compositions/<id>/build/`, or a
+missing `composition:true`, still answers ok, and the site then renders nothing.
+
+**Site, from a folder** that holds only the page and its assets:
+`cd <folder> && beehaven compose create --name "<title>" && beehaven compose push`. Every file in
+the folder is uploaded. A Vite, Next, Astro or SvelteKit `package.json` there runs its build first.
+To push to an existing site, run `beehaven compose push --composition <id>` from the folder; there
+is no `--dir` flag. `compose create` cannot file the site, so file it afterwards (§4). Ignore the
+URL that `push` prints, because it does not open the site.
+
+**Canvas artifact** (create or reuse the canvas with `composition-create {title, projectId}`):
+
+```sh
+# payload: {"compositionId":"<canvasId>","action":"canvas.add-artifact",
+#           "args":{"html":"<!doctype html>…","title":"…","name":"explainer","x":0,"y":0,"w":1000,"designWidth":1000}}
+beehaven call canvas-act @artifact.json
+```
+
+`w` is the card's width on the board; `designWidth` is the viewport the page lays out at. Use 390
+for a phone design. `canvas.place {kind:"site", id}` puts an existing site on a canvas as an
+artifact card. It copies the entry HTML at that moment: later re-uploads do not reach the card,
+and the site's other files do not load.
+
+**Connector only (MCP):** no tool makes a site or an artifact. `clearly_file_upload` cannot choose
+a site path, and `clearly_create` stores a document body as markdown. `clearly_canvas_place
+{target, kind:"site", id}` can place a site that already exists. Otherwise, tell the person the
+running page needs the CLI.
+
+## 4. Update, file, link
+
+- **Update a site:** upload to the same `key`, then `compose-upload-finalize` again. Only someone
+  who may manage the site (its creator) can overwrite it. A file you stop shipping stays in the
+  build. Agents are refused `composition-fs … "action":"delete"`, so ask the person to remove it,
+  or stop referencing it. There is no history, so keep the source in the repository or a note.
+- **Update a canvas artifact:** there is no edit verb. Add the new version at the old card's
+  `x`/`y`/`w`, then remove the old card with `canvas.delete {ids:[…]}`.
+- **File:** `projectId` on `compose-upload-init` (to file later, call it again with
+  `{"compositionId","projectId"}`). For a canvas, `composition-create {projectId}`. For a note,
+  `document-create {projectId}` or `document-update {id, projectId}`. Unfiled agent work is
+  private to its author.
+- **Link it to the ticket:** `beehaven call work-link '{"ticketId":"…","kind":"design","refKind":"composition","refId":"<id>"}'`.
+
+## 5. Hand it over
+
+Give the person the place to click, not just an id.
+
+- A site: "Recents (or the project) → the card", which opens `/compositions/detail?id=<id>`.
+  Do not hand over `/c/<siteId>`. That is what `beehaven open`, ticket links and workspace-ref
+  chips build for a site, and it opens an empty canvas instead of the page.
+- A canvas artifact: `/c/<canvasId>`. Double-clicking the card opens its stored file in a new tab,
+  which shows source text or an access error, never the running page.
+
+## 6. QA — open it, read the console, check mobile
+
+1. **Render it in the real frame model** before uploading. Use Playwright: an
+   `<iframe sandbox="allow-scripts" srcdoc>` at 1280 and 390 wide. Confirm there are no console
+   errors and no requests from the frame, that `scrollWidth === clientWidth`, that the animation
+   advances by itself, and that its controls respond.
+2. **Read the stored copy back:** check that `composition-fs list` shows the size you sent.
+3. **See the server render it.** For a canvas artifact, run
+   `canvas-act {"compositionId":"<canvasId>","action":"canvas.review","args":{"ids":["<artifactId>"]}}`.
+   It returns a filmstrip of four frames across about 5.4 s; inspect the PNG. For a site, place it on a scratch canvas
+   (`canvas.place {kind:"site", id}`), review that card the same way, and then archive the scratch
+   canvas (`composition-set-archived {id, archived:true}`).
+4. Report what you checked and what you could not check. Opening the signed-in page itself needs a
+   person's session.

package/skills/index.json

@@ -118,5 +118,12 @@
       "SKILL.md"
     ],
     "sha": "b9622f21173bab0d"
+  },
+  {
+    "name": "clearly-artifacts",
+    "files": [
+      "SKILL.md"
+    ],
+    "sha": "14434d4904da91a3"
   }
 ]