figura-cli 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figura-cli",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Command-line client for the Figura visualization SaaS",
   "license": "MIT",
   "type": "module",

package/skills/fig/SKILL.md

@@ -2,15 +2,16 @@
 name: fig
 description: "Mock up a screen as an on-brand, shareable HTML fig via your Figura team — render a UI state in seconds before writing the real code. Use when asked to visualize a screen, mock a UI, or 'make a fig'. iPhone-framed by default; browser frame for web/desktop."
 argument-hint: '<what to visualize>'
-allowed-tools: 'mcp__figura__figura_whoami, mcp__figura__figura_generate_fig, mcp__figura__figura_create_fig, Bash(figura *), Bash(bunx figura-cli *)'
+allowed-tools: 'mcp__figura__figura_whoami, mcp__figura__figura_generate_fig, mcp__figura__figura_create_fig, mcp__figura__figura_revise_fig, mcp__figura__figura_publish_fig, mcp__figura__figura_commit_fig, Bash(figura *), Bash(bunx figura-cli *)'
 ---
 
 # /fig — figure it out before you build it
 
 A **fig** is a self-contained HTML mock of one UI state, rendered against your
-Figura team's design system and saved (optionally published with a shareable
-link) to your team's timeline. Build a fig to pressure-test a layout or screen in
-seconds, before writing the real code.
+Figura team's design system and saved to Figura as a workspace draft —
+committed to the team library when it's the final pick, and optionally
+published with a shareable link. Build a fig to pressure-test a layout or
+screen in seconds, before writing the real code.
 
 This skill is a **thin wrapper over the Figura MCP**. It deliberately carries **no
 brand tokens, colors, fonts, or design rules** — the brand lives in exactly one
@@ -65,36 +66,100 @@ greenfield.
 
 2. **Default — build it yourself, with YOUR Claude.** Fetch the team's design
    system — `bunx figura-cli brand --json` — and hand-build the fig's HTML against
-   it, then land it with **`figura_create_fig`** (`publish: true`), setting
+   it, then land it with **`figura_create_fig`**, setting
    `area`, `orientation` (`portrait` / `landscape` / `both`), `mode` (`single` /
    `compare` / `variations` — default to `compare` when Existing-first turned up a
    baseline), `title`, and a real description. This uses the
    caller's own Claude (the model running this skill) — no extra cost, full control
    for precise broken-vs-proposed diptychs — and applies the team's brand from the
    fetched design system. **Follow that design system verbatim; never invent brand
-   values.** `figura_create_fig` returns a shareable `figura.so/f/<id>` link.
+   values.**
+
+   **Landing IS hosting — leave `publish` and `commit` unset.** Creating a fig
+   always persists it to Figura (there is no separate "save it for real" step);
+   the response's **`viewUrl`** is a link you can open right now, whether or not
+   anyone has decided to share it wider. It lands as a **workspace draft** —
+   hosted and shareable by URL, visible to its author, but NOT in the team
+   library and silent for teammates — so iterate freely without claiming the
+   team's attention. Don't pass `publish: true` just to get something viewable
+   (that makes a first-draft iteration PUBLIC), and don't pass `commit: true`
+   on an exploration — committing is reserved for the session's final
+   recommendation (step 7).
+
+   **Pass the fig markup INLINE as `html` — never a shell reference.** The `html`
+   argument to `figura_create_fig` / `figura_revise_fig` is the *full HTML
+   document itself*, passed directly as the value. An MCP tool argument is **not**
+   a shell: `$(cat "…/fig.html")`, a backtick `` `cat file` ``, any command
+   substitution, or a bare file path will **not** expand — the literal string is
+   stored as the fig, producing a tiny black/empty canvas (the engine now rejects
+   this with a 400). If you authored the HTML in a scratch file to render/verify
+   it (step "Verify before publishing"), **read that file's contents** and pass
+   the contents as `html` — do not reference the path.
 
 3. **Server render — the user's call, never yours.** Figura can also render the
    fig server-side against the team brand: **`figura_generate_fig`** with a
-   natural-language brief (same `area` / `orientation` / `mode` / `title` /
-   `publish: true`). Use it only when the **user explicitly asks** for a server
-   render ("let Figura render it", headless/CI flows with no local model) — or
-   when you've offered both paths and they picked this one. It runs as an
-   **async job the tool polls for you** — expect ~30–90s before the landed fig
-   returns; don't re-call while one is in flight. Unlike the default path, this
-   **spends the team's Figura credits** (a `403` means no active subscription).
-   Pass **`fidelity: 'high'`** to render on the better model (the default
-   `'fast'` is lighter — fine for rough states, weaker on brand). Never pick
-   this path on your own to save effort: it costs credits and hand-built figs
-   track the brand better.
-
-4. **Review** the returned link, share it, move on.
+   natural-language brief (same `area` / `orientation` / `mode` / `title`, and
+   again leave `publish` unset by default). Use it only when the **user
+   explicitly asks** for a server render ("let Figura render it", headless/CI
+   flows with no local model) — or when you've offered both paths and they
+   picked this one. It runs as an **async job the tool polls for you** — expect
+   ~30–90s before the landed fig returns; don't re-call while one is in flight.
+   Unlike the default path, this **spends the team's Figura credits** (a `403`
+   means no active subscription). Pass **`fidelity: 'high'`** to render on the
+   better model (the default `'fast'` is lighter — fine for rough states, weaker
+   on brand). Never pick this path on your own to save effort: it costs credits
+   and hand-built figs track the brand better.
+
+4. **Open the HOSTED fig for approval — never a local file.** Run
+   `figura fig open <id>` (the id `figura_create_fig`/`figura_generate_fig` just
+   returned). It opens **`viewUrl`** in the reviewer's browser — the actual
+   Figura render (brand chrome, CSP, favicon, responsive frame), team-scoped so
+   any signed-in teammate can open it even though nothing was published. That's
+   what gets approved, and it's the exact page that ships once published — not a
+   `file://` reconstruction that can drift from it. No display reachable (a
+   headless/CI session)? Paste the printed `viewUrl` into the conversation
+   instead, or fall back to `figura fig open <id> --local` for a local sandboxed
+   HTML preview.
+
+5. **Iterate against the SAME fig, not a fresh one.** Changes from review go
+   through **`figura_revise_fig`** (`id`, the updated `html`) — it joins the
+   existing chain as a new version and returns a fresh `viewUrl`. Publishing is
+   NOT inherited automatically: a revision of an already-published fig still
+   lands unpublished by default (`viewUrl` is a team-scoped view, and the
+   existing public link keeps serving the OLD version) — pass `publish: true`
+   on the revise call itself if the fig is already live and the public link
+   needs to move to this version. Re-open it (`figura fig open <id>`) and
+   repeat until approved.
+
+6. **Approve, then share.** Once the human signs off AND wants a link people
+   outside the team can open, publish it explicitly —
+   **`figura_publish_fig`** (or `figura fig publish <id>`) — Figura's
+   `figura.so/f/<id>` share link. Team-only review never needed this; treat
+   publishing as a deliberate call the human makes, not something create/revise
+   does on its own. Publishing is the share link ONLY — it does not put the
+   fig in the team library (that's committing, step 7); a shared draft's URL
+   resolves fine.
+
+7. **Commit exactly ONE fig — the session's recommendation.** Every fig this
+   session landed is a workspace draft: teammates never saw it. **Committing**
+   (`draft → published`) is what puts a fig in the team library and notifies
+   the team (digest-batched) — so at the end of the session, commit exactly
+   the fig the user asked for / the final agreed version, and nothing else.
+   Explorations, rejected variants, and intermediate iterations STAY drafts.
+   If the deliverable is the fig you're about to create/revise anyway, prefer
+   `commit: true` on that final `figura_create_fig` / `figura_revise_fig`
+   call (CLI: `--commit`) over a separate call; otherwise commit it afterwards
+   with **`figura_commit_fig`** (CLI: `figura fig commit <id>`). Committed the
+   wrong one? `figura_commit_fig` with `uncommit: true` (CLI:
+   `figura fig uncommit <id>`) returns it to a draft — the share link is
+   untouched either way.
 
 ## Presenting a redesign — overview ⇄ focus
 
 When a fig argues a change against a current state (a shipped baseline, or
 several candidate directions), build one fig with **two switchable views** —
-CSS-only radio tabs, since figs carry no `<script>`:
+plain CSS-only radio tabs for THIS specific toggle (it's binary, must survive
+truncation, and doesn't need a library):
 
 - **Overview — side by side.** Every state at once: the honest current state
   first, then each variation, as scaled-down frames in a grid. Under each: a
@@ -124,14 +189,55 @@ CSS-only radio tabs, since figs carry no `<script>`:
   **deterministic**, project-scoped path — the repo's `.figura/figs/` (already
   gitignored), or `~/.figura/figs/` outside a bound repo — never `/tmp` or
   `mktemp`. A stable path means a rerun overwrites the same file instead of
-  littering volatile temp locations, and matches where `figura fig open` writes
-  (`<repo>/.figura/figs/figura-fig-<id>.html`).
+  littering volatile temp locations, and matches where `figura fig open --local`
+  writes (`<repo>/.figura/figs/figura-fig-<id>.html`) — this is YOUR headless
+  self-check copy, separate from the hosted `viewUrl` a human reviewer opens
+  (step 4 above).
 
 A **wipe-slider** stays the narrow tool for exactly two states of the same
 layout with pixel-level tweaks. Never ship a squeezed side-by-side as the
 *only* view of desktop frames, and never a full-frame toggle as the only
 view of many variations — each is one half of the pair above.
 
+## JavaScript is ALLOWED — use it for high-fidelity animation
+
+Figs are **not** CSS-only. The served fig's CSP (`script-src 'unsafe-inline'
+https://cdn.jsdelivr.net https://cdnjs.cloudflare.com https://unpkg.com`) runs
+inline `<script>` **and** external libraries loaded from those three CDNs — so
+reach for real JS whenever it raises fidelity, especially for a mobile-app fig
+where the point is to sell a screen's motion (entrance transitions, spring/
+easing on interactive controls, scroll-driven or gesture-driven animation),
+not just its static layout. Don't self-censor to CSS keyframes when a library
+like GSAP does the job better.
+
+Rules, so the script actually runs on the published fig instead of getting
+CSP-blocked or failing validation:
+
+- **Only the 3 allowlisted CDNs** — `cdn.jsdelivr.net`, `cdnjs.cloudflare.com`,
+  `unpkg.com`. Any other host is CSP-blocked at serve time; the script silently
+  never runs.
+- **Pin an exact version** — `gsap@3.13.0`, never `gsap@latest` or an
+  unversioned path. The engine's `depsPinned` check fails an unpinned CDN
+  script.
+- Inline `<script>` (no `src`) has no CDN restriction — it's your own code, not
+  a third-party load.
+- **No network calls** — `connect-src 'none'` blocks fetch/XHR/WebSocket/
+  sendBeacon outright; a script that tries to phone home just fails silently.
+  Animate/interact with what's already in the DOM.
+- The fig still runs in a sandboxed, opaque-origin iframe (no cookies, no
+  parent-document access) — the security tradeoff Figura accepts to allow this
+  is documented in `packages/core/src/fig/fig-csp.ts` and `cdn-hosts.ts`.
+
+Example — a GSAP-driven entrance for a mobile screen, pinned + allowlisted:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.13.0/dist/gsap.min.js"></script>
+<script>
+  gsap.from('.card', { y: 24, opacity: 0, duration: 0.5, stagger: 0.08, ease: 'power2.out' });
+  gsap.from('.cta', { scale: 0.9, opacity: 0, duration: 0.4, delay: 0.3, ease: 'back.out(1.7)' });
+</script>
+```
+
 ## Metadata & geometry — stamped for you
 
 Every landed fig is **auto-stamped server-side** (on `create` and `generate`)
@@ -163,6 +269,15 @@ So when you **hand-build** a fig (the default path), do your part of the contrac
 
 - **MCP unavailable** (headless / cron, or no interactive auth): fall back to the
   CLI — `bunx figura-cli fig create` / `fig publish`, with `fig revise` /
-  `fig revisions` for versions, and `bunx figura-cli brand --json` for the brand.
+  `fig revisions` for versions, `fig commit` / `fig uncommit` (or `--commit` on
+  the final create/revise) for the team library, and
+  `bunx figura-cli brand --json` for the brand.
+- **`figura_create_fig`/`figura_revise_fig` itself fails** (no network, API down,
+  auth expired): the fig never entered Figura, so there is no `id`/`viewUrl` to
+  open. Only THEN write the HTML to a local scratch file (project-scoped —
+  `.figura/figs/`, never `/tmp`) and tell the user it's a local-only draft that
+  still needs landing once connectivity is back — this is the degraded fallback,
+  not the default path. Don't reach for it just because publishing felt like
+  an extra step; `figura_create_fig` hosts on the first call, every time.
 - **One job, one place.** Brand = the Figura brand profile. Generation = the Figura
   engine. This skill only decides *when* to fig and *which MCP call* to make.