storeframe-mcp 0.1.0 → 0.2.0

package/README.md

@@ -25,11 +25,14 @@ share links) — nothing that could reach a store on your behalf.
 | Tool | What it does | Key inputs |
 |------|--------------|------------|
 | `render_strip` | Render screenshots into mocked-up per-panel PNGs | `screenshots`, `panelPresetId?`, `style?` / `look?` / `useSavedLook?`, `project?`, `version?`, `locale?`, `preview?`, `output?` |
-| `emit_bundle` | `render_strip` (or pre-rendered `panels`) + a `fastlane deliver` zip (+ optional share link) | `screenshots` or `panels`, `bundleId`, `locale?`, `projectName?`, `share?`, `output?` (+ the same styling params) |
+| `emit_bundle` | `render_strip` (or pre-rendered `panels`) + a `fastlane deliver` zip (+ optional share link) | `screenshots` or `panels`, `bundleId`, `locale?`, `locales?` (multi-locale bundle), `projectName?`, `share?`, `output?` (+ the same styling params) |
+| `save_project` | Save the strip as an editable Studio project (structure + look only — does NOT render, so it never hits the render timeout); returns `projectId` + an `openUrl` | `screenshots`, `project?` (update in place; omit to create), `projectName?`, `panelPresetId?`, `style?` / `look?` / `useSavedLook?`, `version?`, `locale?`, `sourceDir?` |
 | `read_look` | Return a project's saved Storeframe look (styling only), with its version + pin state | `project?` (default: your most recently edited project) |
+| `read_project` | Return a project's FULL current state as an opaque `ProjectFile` — frame order, per-locale caption words, locale list, styling. Answers *"what did the designer change?"* (remember `updatedAt`, re-read later) | `project?` (default: your most recently edited project) |
+| `render_project` | Re-render a SAVED project with your OWN raw screenshots, matched to its shots **by filename** — the project supplies frame order, captions + styling, so the result reproduces the designer's strip | `project?`, `screenshots` (a FLAT list, each with its original filename as `name`), `locale?`, `preview?`, `output?` |
 | `save_look` | Persist a composed look on a project (styling only — bumps its content version) | `look`, `project?`, `sourceName?` |
 | `describe_look` | The styling field catalog + defaults, for authoring from scratch | *(none)* |
-| `request_screenshot_upload` | Mint signed upload slots for real screenshots | `count` (1–10) |
+| `request_screenshot_upload` | Mint signed upload slots for real screenshots | `count` (1–10), `names?`, `locale?` (a per-locale batch tag) |
 
 - **`panelPresetId`** — App Store size: `r69` (default, 6.9″ iPhone 1290×2796), `r65`, `r55`,
   `ipad13`, `ipad129`. This enum is a hand-kept copy of `mockup-engine/appstore.ts`'s
@@ -38,8 +41,10 @@ share links) — nothing that could reach a store on your behalf.
   here.
 - **`style`** — the structured styling input (call `describe_look` for the full catalog):
   `{ shotLook?, background?, captions? }`. `captions` is one entry PER PANEL in slot order;
-  each entry's `text`/`subtitle` is per-RENDER input (never stored — a look carries styling
-  only). Wins over `look`/`useSavedLook`.
+  each entry is EITHER a single caption object OR an **array of caption layers** stacked on that
+  panel (headline + subline + …). Each layer's `text` (and a single caption's `subtitle`) is
+  per-RENDER input (never stored — a look carries styling only). Captions auto-layout above the
+  device so they never collide with the phone. Wins over `look`/`useSavedLook`.
 - **`look`** — a Storeframe look JSON exactly as `read_look` returns it; feed it back in to
   restyle. Omit for default styling.
 - **`version`** — render a specific saved look version (implies the saved look). Without it,
@@ -47,34 +52,78 @@ share links) — nothing that could reach a store on your behalf.
 - **`emit_bundle` output** — a zip (`README.md`, `fastlane/Deliverfile`,
   `fastlane/screenshots/<locale>/NN_storeframe.png`) as `zipBase64` or `zipUrl`/`zipRef` (see
   Output below), plus `shareLink` when `share: true`.
-- **`locale`** — an App Store locale code, e.g. `de-DE` (default `en-US`). Labels the render
-  and, for `emit_bundle`, picks the `fastlane/screenshots/<locale>/` folder. **It does not
+- **`locale`** — an App Store locale code, e.g. `de-DE` (default `en-US`). Labels the render,
+  picks which `{ "locales": … }` screenshot variants render (see
+  [Per-locale screenshots](#per-locale-screenshots--multi-locale-bundles)), and, for
+  `emit_bundle`, picks the `fastlane/screenshots/<locale>/` folder. **It does not
   select caption text** — this server never stores or looks up Studio-typed copy (repo owns
   the words). Pass the right words for that locale yourself in `style.captions[].text` /
   `subtitle`.
 
+### Per-locale screenshots & multi-locale bundles
+
+Any `screenshots` entry (and any `emit_bundle` `panels` entry) can carry **per-locale
+variants** instead of one image:
+
+```json
+{ "locales": { "en-US": { "ref": "…en…" }, "de-DE": { "ref": "…de…" } } }
+```
+
+- `render_strip({ locale: "de-DE", … })` renders the `de-DE` variant of each such entry. A
+  locale with **no variant of its own falls back** to the `en-US` variant (else the first
+  declared) — so you can ship German captions over English screenshots today and upgrade the
+  pixels later. Plain (non-`locales`) entries serve every locale. The response echoes the
+  declared locales as `screenshotLocales`.
+- `emit_bundle({ locales: ["en-US", "de-DE"], … })` emits **ONE zip** with a
+  `fastlane/screenshots/<locale>/` folder per listed locale — `fastlane deliver` uploads every
+  locale in a single run. A single-entry list behaves exactly like `locale`; omitting `locales`
+  is the unchanged single-locale bundle.
+- `request_screenshot_upload({ count, names, locale })` tags a batch of upload slots with the
+  locale it's for (echoed back — bookkeeping only; refs are locale-agnostic).
+
+**Recommended multi-locale flow — render per locale, then compose once.** Caption text is
+per-render input, so this is also the only way to get per-locale *captions* into one bundle,
+and it keeps each call fast (see "Cheap preview, then compose" below):
+
+1. Per locale `L`: `render_strip({ locale: L, output: "urls", style: { captions: [<L's words>] },
+   screenshots: […] })` → per-panel refs for `L`.
+2. One `emit_bundle({ locales: […], bundleId, panels: [ { "locales": { "en-US": { "ref": "p1-en" },
+   "de-DE": { "ref": "p1-de" } } }, … ] })` — zips every locale **without re-rendering**.
+
+The one-call form (`emit_bundle` with `screenshots` + `locales`) works too, but renders once
+per locale with the *same* captions for every locale, and multiplies the slow full-res render
+by the locale count.
+
 ### The `captions.<locale>.json` convention
 
 The canonical source of shipping caption copy is a file **in your own repo**, one per locale,
 keyed by **panel ordinal** (0-based, in strip order — not panel id, so the file stays stable
 across re-renders):
 
+A panel's entry is EITHER a single caption (`{ headline, subtitle? }`) OR an **array of layers**
+(each `{ text, … }`, stacked in order) — use the array when you want more than a headline + one
+subtitle, e.g. an eyebrow over a headline over a caption:
+
 ```json
 // captions.de-DE.json
 {
   "0": { "headline": "Alles im Blick", "subtitle": "Deine Tage, übersichtlich." },
-  "1": { "headline": "Schneller planen" }
+  "1": [ { "text": "NEU" }, { "text": "Schneller planen" } ]
 }
 ```
 
 To render a locale: read that file, map it onto `style.captions[]` in the same order (index
 `i` → panel `i`, `null` for a panel with no caption), and pass `locale` alongside so the
-render/bundle is labeled and routed consistently:
+render/bundle is labeled and routed consistently. A single caption maps to one object; a layer
+array maps straight through as an array:
 
 ```json
 {
   "locale": "de-DE",
-  "style": { "captions": [{ "text": "Alles im Blick", "subtitle": "Deine Tage, übersichtlich." }, { "text": "Schneller planen" }] }
+  "style": { "captions": [
+    { "text": "Alles im Blick", "subtitle": "Deine Tage, übersichtlich." },
+    [ { "text": "NEU", "sizePt": 28 }, { "text": "Schneller planen" } ]
+  ] }
 }
 ```
 
@@ -97,10 +146,12 @@ context budget (or get silently truncated by a file-read tool) long before rende
 3. Pass `{ "ref": "<ref>" }` — not inline base64 — as that screenshot's entry in
    `render_strip`/`emit_bundle`'s `screenshots` array.
 
-`screenshots` entries accept three shapes: an inline base64 string (small payloads only —
+`screenshots` entries accept these shapes: an inline base64 string (small payloads only —
 inline is capped and returns a clear "payload too large" error above ~8MB decoded, pointing
-you back at this flow), `{ ref }` from step 1, or `{ url }` (an https URL this server fetches
-itself: image/png, no redirects, ~20MB cap).
+you back at this flow), `{ ref }` from step 1, `{ url }` (an https URL this server fetches
+itself: image/png, no redirects, ~20MB cap), `{ path }` (local stdio server only — see below),
+or `{ "locales": { "<locale>": <any of those> } }` for per-locale variants (see
+[Per-locale screenshots](#per-locale-screenshots--multi-locale-bundles) above).
 
 **Output** works the same way in reverse: `render_strip`/`emit_bundle` take an `output` field
 — `"inline"` (base64), `"urls"` (uploaded under your own prefix, short-lived signed download
@@ -248,24 +299,26 @@ instead of `{ ref }`/`{ url }`:
 (`{ "path": ... }` only works over this LOCAL server — the hosted server rejects it, since
 reading an arbitrary server-side path there would be a local-file-inclusion hole.)
 
-**What's different locally, and why:** `read_look` / `save_look` / `save_project` / share links
-need an ACCOUNT to persist to, which local mode doesn't have by default — they cleanly no-op
-with a "sign in" message. `render_strip` / `emit_bundle` are otherwise **fully functional** —
-you lose nothing on rendering itself, only on persistence, which is exactly the free/paid line:
+**What's different locally, and why:** every tool that needs an ACCOUNT to read or persist to —
+`read_look` / `save_look` / `save_project` / `read_project` / `render_project` / share links —
+has nothing to talk to in local mode by default, so they cleanly no-op with a "sign in" message.
+`render_strip` / `emit_bundle` are otherwise **fully functional** — you lose nothing on rendering
+itself, only on persistence, which is exactly the free/paid line:
 
 | | Local (free, `npx storeframe-mcp`) | Hosted (Fly, `sfs_…` token) |
 |---|---|---|
 | Render compute | **your machine** ($0, no timeout) | our Fly machine |
 | Auth | none (the process runs as you) | account + API token |
-| Saved looks / editable projects / share links | opt-in via a token (below) — share links still need a direct hosted connection | ✅ |
+| Saved looks / editable projects / project read+re-render / share links | opt-in via a token (below) — share links still need a direct hosted connection | ✅ |
 | Screenshot input | local `{ path }` off disk | `request_screenshot_upload` → `{ ref }` |
 
 ### Optional: bridge a local render into your hosted account
 
 Pass a personal Storeframe API token (Studio → account menu → **API tokens** — the same
 `sfs_…` token the hosted server takes as a bearer) and `save_project` / `read_look` /
-`save_look` start working too — **rendering still happens locally and for free; only the small
-saved-project JSON (structure + look, never screenshot bytes) goes to your account:**
+`save_look` / `read_project` / `render_project` start working too — **rendering still happens
+locally and for free; only the small saved-project JSON (structure + look, never screenshot
+bytes) goes to your account:**
 
 ```bash
 STOREFRAME_TOKEN=sfs_… claude mcp add storeframe -- npx -y storeframe-mcp