figura-cli 0.15.0 → 0.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figura-cli",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "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, mcp__figura__figura_revise_fig, mcp__figura__figura_publish_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
@@ -46,6 +47,44 @@ point. Only build a standalone `single` fig when the screen is genuinely net-new
 Unsure whether a version already exists? **Ask the user** rather than assume
 greenfield.
 
+### Reconstruct the baseline from SOURCE — required, no screenshot
+
+The existing/current/broken frame of a `compare` fig must be a **faithful
+recreation of what actually ships**, not a hand-approximation — an approximated
+"before" quietly rebuilds a strawman and the diptych argues against a screen that
+doesn't exist. So when you build the baseline state and **no screenshot is
+provided**, studying the source and rebuilding its layout is a **REQUIRED step**,
+not optional reading:
+
+1. **Locate the screen** — Grep/Glob for the route dir, the `page`/`route`
+   file, and the component(s) it renders (e.g. `apps/*/src/app/<route>/page.tsx`
+   plus imported views).
+2. **Read the component file(s)** and extract the real structure:
+   - the **JSX/TSX element hierarchy and order** (containers → sections →
+     controls, top to bottom);
+   - the **class names / style modules / design tokens** on each element
+     (`flex`/`grid`, spacing, radii, colors) — these are the layout;
+   - the **imported UI primitives** (`Button`, `Input`, `Card`, …) and *their*
+     rendered shape (a `variant="cta"` white pill vs an `outline` button is a
+     visible difference — open the primitive if unsure);
+   - **conditional branches** — auth-provider variants, stages, empty/error/
+     loading states — and decide which branch the baseline depicts (state it);
+   - the **real copy and labels** (headings, placeholders, button text, error
+     banners) verbatim, not paraphrased.
+3. **Rebuild that layout as the baseline** — real element hierarchy, real
+   controls, real copy, real spacing — so the "before" frame matches the shipped
+   screen line-for-line, then drift only the *proposed* frame.
+4. **Fallback (only if the source genuinely can't be located/read):**
+   approximate, and **caption the baseline as an approximation** (a chip / note on
+   the frame: "approximated — source not found") so no one mistakes a guess for
+   the shipped UI.
+
+This is what "grounded in the real current state" above means: the baseline is
+**source-faithful by reconstruction**, or it is explicitly labelled a guess —
+never a silent approximation. It applies to **both** the hand-build path and the
+server render below — on a server render you can't read the repo *for* the engine,
+so you hand it the studied structure in the brief (see step 3, "Server render").
+
 ## How to fig
 
 1. **Verify the destination team** — call **`figura_whoami`** (or
@@ -74,12 +113,26 @@ greenfield.
    fetched design system. **Follow that design system verbatim; never invent brand
    values.**
 
-   **Landing IS hosting — leave `publish` 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. Don't pass `publish: true` just to get something
-   viewable — that makes a first-draft iteration PUBLIC. Publishing is a
-   deliberate, later step (see step 5).
+   **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
@@ -95,6 +148,19 @@ greenfield.
    on brand). Never pick this path on your own to save effort: it costs credits
    and hand-built figs track the brand better.
 
+   **The engine CANNOT read your repo — carry the studied baseline in the brief.**
+   `figura_generate_fig` runs server-side against the team brand; it has no access
+   to the caller's filesystem, so for a `compare`/existing state it would otherwise
+   *guess* the "before" too. Close the seam yourself: do the source study from
+   "Reconstruct the baseline from SOURCE" above **first**, then pass the
+   reconstructed structure into the `prompt` brief as an explicit "before" spec —
+   the file you grounded it in, the element order top-to-bottom, the real controls
+   and primitive shapes, the branch depicted, and the verbatim copy/labels. The
+   `prompt` is free NL text, so this needs no extra parameter — the studied layout
+   just becomes the baseline half of the brief (the proposed half describes the
+   change). If you truly couldn't locate the source, say so in the brief and label
+   the baseline an approximation, same as the hand-build fallback.
+
 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
@@ -121,13 +187,30 @@ greenfield.
    **`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.
+   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
@@ -141,7 +224,9 @@ CSS-only radio tabs, since figs carry no `<script>`:
   as annotation chips: what's broken today, what each variation improves,
   what it trades away.
 - **In both views:** render the current state honestly from the shipped
-  implementation; color-code chips by function (broken / improved /
+  implementation — **reconstructed from source** per "Reconstruct the baseline
+  from SOURCE" (no screenshot ⇒ study the component file(s) and rebuild the real
+  layout, don't approximate); color-code chips by function (broken / improved /
   trade-off / detail) using the team's status colors from the fetched design
   system; mark the recommended variation and close with a short "my read"
   arguing the pick against the others. Keep the chrome around the frames
@@ -167,6 +252,45 @@ 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`)
@@ -184,11 +308,20 @@ with two things you do **not** hand-write:
 
 So when you **hand-build** a fig (the default path), do your part of the contract:
 
-- **Mobile:** size the body to the exact logical screen and emit
-  `<meta name="figura:artboard" content="WxH">` matching it (iPhone portrait
-  `393x852` / landscape `852x393`). For OS-chrome insets prefer
-  `var(--fig-safe-top, 59px)` / `.fig-safe-top` over hardcoded pixels — the stamp
-  fills the value, the fallback keeps you correct if the kit is absent.
+- **Bare mobile screen — and ONLY then:** when the fig's HTML *is* one raw app
+  screen (no masthead, no state pills, no hand-drawn `.fig-device` frames — the
+  Figura viewer draws the iPhone shell around it), size the body to the exact
+  logical screen and emit `<meta name="figura:artboard" content="WxH">` matching
+  it (iPhone portrait `393x852` / landscape `852x393`). For OS-chrome insets
+  prefer `var(--fig-safe-top, 59px)` / `.fig-safe-top` over hardcoded pixels —
+  the stamp fills the value, the fallback keeps you correct if the kit is absent.
+- **A document-style fig NEVER gets an artboard.** The artboard meta is the
+  viewer's opt-in signal for "size me to exactly WxH and wrap me in a device
+  shell" — stamped on an overview ⇄ focus redesign page (or any compare /
+  variations document with its own masthead, pills, or hand-drawn device
+  frames), it crams the whole document into a phone frame. A document fig
+  renders full-page precisely because it carries NO artboard meta, even when
+  every screen it depicts is a mobile app.
 - **Always:** emit `<meta name="figura:context" content="...">` (design intent).
 - **Optional but valued:** if the fig grounds a specific feature or flag, emit
   `<meta name="figura:feature" content="<flag-or-slug>">` so it links back to the
@@ -198,7 +331,9 @@ 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 —