figura-cli 0.19.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figura-cli",
-  "version": "0.19.0",
+  "version": "0.21.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

@@ -101,6 +101,9 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
      wrong tenant). Tell the user to run `figura link` in this repo, then
      re-verify. If the response has no `binding` field (older CLI/MCP), confirm
      the team slug matches this project with the user before proceeding.
+   - **Update notice?** If the whoami response carries a `notice` field, relay it
+     to the user verbatim (a one-line "figura-mcp is behind / below min — run …"),
+     then proceed. It's a passive nudge, shown once per session — never a blocker.
 
 2. **Default — build it yourself, with YOUR Claude.** Fetch the **canonical
    authoring scaffold** — **`figura_fig_scaffold`** (CLI:
@@ -171,7 +174,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 +234,10 @@ 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, wrap each in the
+  kit's **`.fig-mini`** wrapper (see "Scaling a framed device" below), never a
+  rule on `.fig-device` and never CSS `zoom` (zoom leaks an unzoomed
+  `scrollWidth` into horizontal overflow — the exact thing this view forbids).
 - **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 +252,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
@@ -320,10 +340,32 @@ 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 (and NOT authoring its CSS — Figura stamps the bezel,
-Dynamic Island, and safe-area insets), the `figura:context` / `figura:feature`
+`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-mini` wrapper, 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.
 
+**Scaling a framed device — use `.fig-mini`, never a rule on `.fig-device`.**
+An overview grid needs shrunken frames, and the obvious way to write that is a
+CSS rule on the injected class. Don't: your rule wins over the kit, so the frame
+stops matching real device geometry — and `zoom` is worse, it leaks the unzoomed
+width into scrollable overflow. The kit ships the wrapper instead:
+
+```html
+<div class="fig-mini" style="--fig-scale:.34">
+  <div class="fig-device portrait" data-device="iphone-16">
+    <div class="fig-screen">…</div><div class="fig-di"></div><div class="fig-homebar"></div>
+  </div>
+</div>
+```
+
+`.fig-mini` scales its device with `transform` and takes the **scaled** layout
+box, so a row of minis lays out at its visual size instead of reserving
+full-size phones. Add `landscape` to the device (or the wrapper) and the box
+flips with it. `--fig-scale` defaults to `.34`; set it per element.
+
 - **`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