figura-cli 0.15.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figura-cli",
-  "version": "0.15.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, 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
@@ -74,12 +75,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
@@ -121,13 +136,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
@@ -167,6 +199,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`)
@@ -198,7 +269,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 —