shotops-mcp 0.9.6 → 0.9.8

package/README.md

@@ -56,9 +56,10 @@ The key is never copied, printed, or sent to ShotOps, and no release tool is ins
 |------|--------------|------------|
 | `render_strip` | Preferred focused render: turn raw screenshots into mocked-up per-panel PNGs without creating or updating a project | `screenshots`, `panelPresetId?`, `clip?`, `style?` **+** `look?` (they compose) / `useSavedLook?`, `project?`, `version?`, `locale?`, `preview?`, `output?` |
 | `emit_bundle` | `render_strip` (or pre-rendered `panels` — refs or local `{ path }`, or a saved `project`'s own screenshots) + a `fastlane deliver` zip (+ optional share link) | `screenshots` or `panels` or `project` (bundles what that project holds), `bundleId`, `clip?`, `outputs?` (target devices — one bundle for several sizes; omit and a `project`'s saved outputs are used), `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); always returns an `openUrl`. Authenticated saves also return `projectId`; unsigned local saves return a seven-day pending claim the user owns after opening the link and signing in | `screenshots`, `project?` (update in place only when explicitly targeted and authenticated; omit to create a new project or pending claim), `projectName?`, `outputs?`, `panelPresetId?`, `style?` / `look?` / `useSavedLook?`, `version?`, `locale?`, `sourceDir?` |
+| `save_project` | Save the strip as an editable Studio project (structure + look only — does NOT render, so it never hits the render timeout); always returns an `openUrl`. Authenticated saves also return `projectId`; unsigned local saves return a seven-day pending claim the user owns after opening the link and signing in | `screenshots`, `project?` (update in place only when explicitly targeted and authenticated; omit to create a new project or pending claim), `projectName?`, `appListing?` (an App Store URL, numeric app ID or bundle ID — the project takes the real app's name, bundle ID, languages and devices), `outputs?`, `panelPresetId?`, `style?` / `look?` / `useSavedLook?`, `version?`, `locale?`, `sourceDir?` |
 | `read_look` | Return a project's saved ShotOps look (styling only), with its latest version, the held version, the `versions` history, and the `layout` template it is composed on (derived from its values, never stored) | `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 — plus the derived `layout` and a `screenshots.cells` report for every shot × target-family × locale. Each cell says whether pixels resolve, where they resolved from, and which axes inherited | `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 — plus the derived `layout` and a `screenshots.cells` report for every shot × target-family × locale. Each cell says whether pixels resolve, where they resolved from, and which axes inherited. `linkedApp` names the App Store app the project is linked to, when it has one | `project?` (default: your most recently edited project) |
+| `search_app_listing` | Find the user's app on the App Store so a save can carry its real identity: each result carries the app's name, seller, icon, bundle ID and numeric app ID, plus the App Store Connect languages and iPhone devices ShotOps would apply. Free, renders nothing, writes nothing; needs an account. Finding a public listing proves nothing about who owns the app | `term`, `country?` (two-letter storefront, default `us`) |
 | `render_project` | Render a SAVED project. By default it renders the screenshots **the project already holds** — pass none at all, no upload needed — into **every supported device the project targets**. Pixels resolve independently for each device family + locale through the shared manifest; genuine fallback is reported in `shots[].inherited` and `note` | `project?`, `screenshots?` (**optional** — omit to use what the project holds; else a FLAT list matched by original `name`, with optional `variant: { family?, locale? }` per cell), `outputs?` (override the project's saved devices for this call), `locale?`, `preview?`, `output?` |
 | `refine_project` | Run one bounded Agent turn against a saved project. A supported request commits once and returns the actual diff; ambiguity, missing input, unsupported intent, conflict, and failure return a typed no-write outcome | `project?`, `instruction`, `focus?` |
 | `save_look` | Persist a composed look on a project (styling only — appends a new version) | `look`, `project?`, `sourceName?` |
@@ -71,7 +72,7 @@ The key is never copied, printed, or sent to ShotOps, and no release tool is ins
 | `production_operation` | Reconnect to one durable paid Hosted render or rendering bundle, report persisted progress, request cooperative cancellation, or mint fresh result download grants without rerendering or charging again | `action` (`get`, `cancel`, or `result`), `operationId` |
 | `delete_assets` | Permanently delete private uploaded screenshots, rendered panels, or generated bundles owned by the signed-in account | `refs` (1–50 ShotOps refs) |
 
-- **`panelPresetId`** — App Store size: `r69` (default, 6.9″ iPhone 1290×2796), `r65`, `r55`.
+- **`panelPresetId`** — App Store size: `r69` (default, 6.9″ iPhone 1320×2868), `r65`, `r55`.
   **iPhone sizes only** — the iPad presets are deliberately not offered, because no iPad device
   model exists yet and rendering one would put an iPhone body in an iPad-shaped canvas. The
   accepted set is `RENDERABLE_PANEL_PRESET_IDS` in `shotops-mcp/src/render/panelCatalog.ts`, a subset of
@@ -86,11 +87,14 @@ The key is never copied, printed, or sent to ShotOps, and no release tool is ins
   `text` (and a single caption's `subtitle`) is per-RENDER input (never stored — a look carries
   styling only). Captions auto-layout in a band at the top of the panel, and the device does NOT
   move to make room.
-- **`style.layout`** — the panel **composition** in one word: `"standard"`, `"bleed"`, or
-  `"top-bleed"`. It settles the headline's reserved region, device placement, camera pose, and
-  roll together. `standard` (the shipped default) puts the whole device
-  under a 2-line region — about 36 characters — and crops nothing; `bleed` reserves 4 lines (~72
-  characters) and runs the device 10% off the bottom edge. The region is **reserved, not fitted**:
+- **`style.layout`** — the panel **composition** in one word: `"standard"`, `"bleed"`, `"top-bleed"`,
+  `"lean-right"`, `"lean-left"`, `"swipe"` or `"corner-bleed"`. It settles the headline's reserved
+  region, device placement, camera pose, and roll together. `standard` (the shipped default) puts
+  the whole device under a 2-line region — about 36 characters — and crops nothing; `bleed` reserves
+  4 lines (~72 characters) and runs the device 10% off the bottom edge. The last four run it off a
+  SIDE edge instead, into the neighbouring screenshot, so the set reads as one continuous swipe —
+  pick one for **every** panel or none, and never mirror `lean-right` against `lean-left`, which
+  puts two devices into the same seam. The region is **reserved, not fitted**:
   it is held at full size whether or not the headline fills it, which is what makes every panel in
   a swiped set land on the same line. **Precedence** — the template expands *first*, then any
   explicit `shotLook` composition field or caption layout field you also pass **overrides** it
@@ -292,8 +296,8 @@ screenshot unavailable; public privacy disclosures must accurately state this re
    shown once — copy it then.
 2. **Supabase service env** (already in the repo's `.env.local` for local dev): `SUPABASE_URL`
    and `SUPABASE_SERVICE_ROLE_KEY`. The server loads `../.env.local` automatically.
-3. Playwright's Chromium (installed with the package; run `npx playwright install chromium`
-   once if it's missing).
+3. Playwright's Chromium. The first render downloads it automatically into Playwright's cache if
+   it's missing; run `npx playwright install chromium` first to skip that one-time wait.
 
 ## Run it
 
@@ -303,7 +307,8 @@ npm install
 npm run dev            # boots on http://localhost:8788/mcp  (override with MCP_PORT)
 ```
 
-Chromium boots lazily on the first `render_strip` / `emit_bundle` call, so startup is fast.
+Chromium boots lazily on the first `render_strip` / `emit_bundle` call, so startup is fast — and
+that first render also installs Chromium if it isn't cached yet, adding ~20-25s to that one call.
 `GET /health` is an unauthenticated liveness probe.
 
 ## Connect ChatGPT (Developer Mode)
@@ -419,13 +424,26 @@ the transport and a few account-shaped tools differ.
 claude mcp add shotops -- npx -y shotops-mcp
 ```
 
-One-time setup: Chromium isn't bundled in the npm package (it's ~150MB) — Playwright downloads
-it on first run, or install it explicitly:
+Chromium isn't bundled in the npm package (it's ~150MB). The first render on a machine without
+Playwright's Chromium installs it automatically into Playwright's cache, then renders. That first
+render takes ~20-25s longer, and its result `note` says so. Install it ahead of time to skip the wait:
 
 ```bash
 npx playwright install chromium
 ```
 
+Offline, that automatic download fails and the first render refuses with `upstream_unavailable`
+until you're back online.
+
+### Claude Desktop (macOS and Windows)
+
+The same local server ships as a Claude Desktop extension, no terminal needed. Download
+**<https://shotops.dev/download/shotops.mcpb>** (always the latest version; a specific one is
+`shotops-mcp-<version>.mcpb` beside it) and double-click it. Leave the **ShotOps API token**
+setting empty to preview free without an account, or paste a token from the Studio app → account
+menu → **API tokens** to save projects and looks. The extension bundles everything except
+Chromium, which the first render downloads once as described above.
+
 **Screenshots are read straight off your disk** — no upload dance. Pass a local file path
 instead of `{ ref }`/`{ url }`: