figura-cli 0.18.1 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figura-cli",
-  "version": "0.18.1",
+  "version": "0.20.0",
   "description": "Command-line client for the Figura visualization SaaS",
   "license": "MIT",
   "type": "module",
@@ -36,6 +36,7 @@
     "@panofm/figura-core": "workspace:*",
     "@types/node": "^20.14.0",
     "axios": "^1.7.9",
+    "package-manager-detector": "^1.8.0",
     "postgres": "^3.4.9",
     "typescript": "^5.5.0"
   }

package/skills/fig/SKILL.md

@@ -2,7 +2,7 @@
 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_fig_scaffold, 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 *)'
+allowed-tools: 'mcp__figura__figura_whoami, mcp__figura__figura_fig_scaffold, mcp__figura__figura_fig_devices, 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
@@ -171,7 +171,11 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
    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
+4. **Verify, then open the HOSTED fig for approval — never a local file.** First
+   run **`figura fig verify <id>`**: the component CSS is stamped server-side, so
+   only the served bytes can tell a working fig from one that renders as empty
+   phones. It exits non-zero if a frame class shipped unsized — fix and re-land
+   before a human sees it. Then 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
@@ -227,7 +231,14 @@ truncation, and doesn't need a library):
   status chip and ONE condensed context line (`+ / –`). This view is for
   scanning and picking a direction, not for reading detail. The grid must
   wrap to one column before it can overflow — **a fig never scrolls
-  horizontally**, at any viewport.
+  horizontally**, at any viewport. To shrink the framed phones, set the kit's
+  **`--fig-scale`** custom property (e.g. `style="--fig-scale:.42"` on each
+  `.fig-device`, or on the grid container — it inherits) — Figura shrinks the
+  whole framed phone and reserves the scaled layout box so the minis tile
+  without overlapping. **Do NOT** write your own rule on `.fig-device`
+  (a `width`/`height` or `transform: scale()`): `--fig-scale` is the one
+  sanctioned scaling knob, and hand-sizing the frame fights the injected
+  geometry.
 - **Focus — full frame.** One state at a time behind state pills (Today / A /
   B / …), each state framed identically so flipping states in place reads as
   spot-the-difference. This is where the context lives, pinned on the frame
@@ -242,20 +253,30 @@ truncation, and doesn't need a library):
   arguing the pick against the others. Keep the chrome around the frames
   minimal — the frames are the content; no legends (chips label themselves),
   no repeated context, fluid `max-width` layout throughout.
-- **Verify before publishing.** Render the fig headless at a few viewport
-  widths: `document.scrollWidth` must equal the viewport in every view and
-  state (sideways scroll = broken — beware CSS `zoom`, which leaks unzoomed
-  width into scrollable overflow; scale minis with `transform` in
-  fixed-aspect wrappers instead), and screenshot each state to check no
-  annotation chip covers the content it annotates.
-  When you write the fig's HTML out to render/screenshot it, save it to a
-  **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 --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).
+- **Verify the SERVED fig, not your local draft.** The component kit (device
+  frame, status bar, control bar) is stamped **server-side at save** — it does
+  **not** exist in the HTML you authored locally, so a headless render of your
+  own file shows *unstyled, empty* frames whether or not the fig is actually
+  correct. A local screenshot is structurally blind to the most common way a
+  framed fig breaks. So verify the fig that actually ships:
+  1. **Land it first** (`figura_create_fig` / `figura_revise_fig`), then dump
+     the stamped bytes: `figura fig open <id> --local --print`. This is the
+     served document, kit and all.
+  2. **Assert the kit stamped — `figura fig verify <id>`.** One command, and it
+     **exits non-zero** if any frame class your markup uses shipped with no CSS
+     giving it dimensions. It checks every injected component (device frame,
+     status bar, control bar, browser chrome), cross-checks the manifest's
+     `components` array, and reports the fig's own `frameKit` / `complete` /
+     `doubleFramed` checks; `--json` for machine output. The engine won't
+     silently drop the kit anymore, and create/revise now warns loudly if it
+     ever did — this is the check that *proves* a frame renders.
+  3. **Screenshot THAT** (the printed served HTML, saved to a deterministic
+     project-scoped path — the repo's `.figura/figs/` (gitignored), or
+     `~/.figura/figs/` outside a bound repo, never `/tmp`/`mktemp`), at a few
+     viewport widths: `document.scrollWidth` must equal the viewport in every
+     view and state (sideways scroll = broken), and no annotation chip may
+     cover the content it annotates. `figura fig open <id> --local` writes the
+     same served bytes to `<repo>/.figura/figs/figura-fig-<id>.html`.
 
 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
@@ -316,62 +337,26 @@ with two things you do **not** hand-write:
   search and the self-improving loop. Artifact-descriptive only — no team/brand
   ids (the block is served on the public link).
 
-So when you **hand-build** a fig (the default path), do your part of the contract:
-
-- **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
-  feature it depicts.
-
-### The two mobile presentations — pick ONE, never both (#717)
-
-A mobile fig is EITHER a frameless single OR a canvas composition. Emitting both
-signals — a whole-fig `figura:artboard` meta AND an in-fig `.fig-device` frame —
-makes the viewer wrap the *whole* composition in one phone (the key, masthead,
-and second screen all crammed inside the bezel). That contradiction is flagged
-(`double-framed`), so choose deliberately:
-
-- **Frameless single** — the whole fig IS one screen. Whole-fig `figura:artboard`
-  meta, `<body>` sized to exactly W×H, body == the screen, no surrounding HTML.
-  The viewer draws the phone around the entire fig. Best fidelity for "just the
-  screen".
-- **Canvas composition** — a document that frames one or more devices **in-fig**,
-  with author HTML around them (a design-language key, annotations, multiple
-  screens, states with controls). **No whole-fig `figura:artboard` meta.** Frame
-  each target device as a bounded `.fig-device` element and Figura stamps the
-  bezel + Dynamic Island + safe-area insets for that device (do NOT author CSS
-  for `.fig-device` / `.fig-screen` / `.fig-di` / `.fig-homebar`):
-
-  ```html
-  <div class="fig-device portrait" data-device="iphone-16">
-    <div class="fig-screen fig-safe"> …screen content… </div>
-    <div class="fig-di"></div>       <!-- Dynamic Island / notch, drawn for you -->
-    <div class="fig-homebar"></div>  <!-- home indicator, drawn for you -->
-  </div>
-  ```
-
-  Use `class="fig-device landscape"` for a landscape device (the island moves to
-  the leading edge automatically). `data-device` is any catalog id
-  (`figura fig scaffold` / `brand --json` list them); **different `data-device`
-  values on one canvas frame different phones** — an `iphone-16` beside an
-  `iphone-se-3`, each with its own bezel radius and cutout. Put your key,
-  annotations, and any other screens as ordinary HTML AROUND the framed
-  device(s). A composition renders full-page (no whole-fig meta) so nothing is
-  phone-wrapped as a whole.
+So when you **hand-build** a fig (the default path), you do your part of the
+contract — but the exact rules are **fetched, not restated here**: the
+presentation model (frameless single vs canvas composition), when to emit or
+omit the whole-fig `<meta name="figura:artboard">`, the `.fig-device` /
+`data-device` frame markup (Figura stamps the bezel, Dynamic Island, and
+safe-area insets **before** your `<style>`, so you normally leave those classes
+alone — if you do style one, your rule wins by cascade and the frame still
+works; to shrink a frame use the `--fig-scale` custom property, never a
+hand-written `.fig-device` width/height/transform), the `figura:context` /
+`figura:feature` metas, and the valid devices all live in the canonical scaffold.
+
+- **`figura_fig_scaffold`** (CLI: `figura fig scaffold`) is authoritative for the
+  presentation model, the frame markup, and the output contract. Fetch it and
+  follow it verbatim (step 2 above) — do NOT restate design/format rules from
+  memory. A bundled skill can pin stale; the scaffold is always current.
+- **`figura_fig_devices`** (CLI: `figura fig devices`) is the full valid-
+  `data-device` catalog — every framed-device id + its geometry (logical dims,
+  safe-area insets, cutout, corner radius). Pick a real id from it for a canvas
+  composition's `<div class="fig-device" data-device="…">`; an unknown id
+  silently gets no frame.
 
 ## Notes