storeframe-mcp 0.1.0 → 0.2.0

package/dist/local.js

@@ -64,6 +64,67 @@ metadata, and never submits. Feel free to inspect it \u2014 it's five lines.
 
 ## Troubleshooting
 
+- **"Could not find app with bundle identifier"** \u2014 the Bundle ID above doesn't match an
+  app on the team you signed in with. Re-export from Storeframe with the right Bundle ID.
+- **Screenshots land under the wrong language** \u2014 re-export with the right locale; the
+  folder name under \`fastlane/screenshots/\` is the App Store locale code.
+- **Wrong order in the store** \u2014 the \`NN_\` prefix controls order; re-arrange the strip in
+  Storeframe and re-export rather than renaming files by hand.
+`;
+var MULTI_LOCALE_README_TEMPLATE = `# Upload these screenshots to App Store Connect
+
+This bundle was exported from Storeframe Studio for **{{BUNDLE_ID}}** \u2014
+{{LOCALE_COUNT}} locales ({{LOCALES}}) \xB7 {{PER_LOCALE_COUNT}} screenshots each \xB7 {{PANEL_LABEL}}.
+
+You upload it yourself with [Fastlane](https://fastlane.tools), signed in with **your own
+Apple account or API key**. Your credentials never touch Storeframe.
+
+## Upload
+
+\`\`\`
+cd <this folder>
+fastlane deliver
+\`\`\`
+
+Fastlane will:
+
+1. Ask you to sign in (Apple ID with 2FA, or an App Store Connect API key if you have
+   fastlane configured with one).
+2. Detect the device size automatically from the image dimensions.
+3. Upload screenshots for **every locale** below in one run \u2014 it reads the locale from each
+   \`fastlane/screenshots/<locale>/\` folder name.
+4. Show you an **HTML preview** of exactly what will be uploaded and ask
+   \`Does the Preview look okay for you? (y/n)\` \u2014 nothing is sent until you confirm.
+5. Upload the screenshots to your app's **editable (unreleased) version**, replacing the
+   existing set for each device size and locale.
+
+**Nothing is ever submitted for review.** This bundle only updates screenshots on a draft
+version; you review and submit in App Store Connect yourself, whenever you're ready.
+
+## First time?
+
+- Install fastlane: \`brew install fastlane\` (or \`gem install fastlane\`).
+- You need an **editable version** of your app in App Store Connect (any version that
+  isn't live yet). If every version is released, create a new version in App Store
+  Connect first \u2014 deliver can't attach screenshots to a released version.
+
+## What's in this bundle
+
+\`\`\`
+README.md                        this file
+fastlane/
+  Deliverfile                    pre-filled config \u2014 screenshots only, nothing else
+{{LOCALE_FOLDERS}}
+\`\`\`
+
+Each locale folder holds that language's screenshots; the \`NN_\` filename prefix is the
+display order in the App Store.
+
+The \`Deliverfile\` is deliberately minimal and read-safe: it skips binary upload, skips
+metadata, and never submits. Feel free to inspect it \u2014 it's a handful of lines.
+
+## Troubleshooting
+
 - **"Could not find app with bundle identifier"** \u2014 the Bundle ID above doesn't match an
   app on the team you signed in with. Re-export from Storeframe with the right Bundle ID.
 - **Screenshots land under the wrong language** \u2014 re-export with the right locale; the
@@ -75,7 +136,11 @@ function render(template, vars) {
   return template.replace(/\{\{(\w+)\}\}/g, (match, key) => vars[key] ?? match);
 }
 function generateDeliverfile(opts) {
-  return render(DELIVERFILE_TEMPLATE, { BUNDLE_ID: opts.bundleId });
+  const base = render(DELIVERFILE_TEMPLATE, { BUNDLE_ID: opts.bundleId });
+  const locales = opts.locales?.filter((l) => l.length > 0) ?? [];
+  if (locales.length === 0) return base;
+  return `# Locales in this bundle: ${locales.join(", ")} (one fastlane/screenshots/<locale>/ folder each).
+${base}`;
 }
 function generateBundleReadme(opts) {
   return render(README_TEMPLATE, {
@@ -85,6 +150,17 @@ function generateBundleReadme(opts) {
     COUNT: String(opts.count)
   });
 }
+function generateMultiLocaleBundleReadme(opts) {
+  const folderLines = opts.locales.map((l) => `  fastlane/screenshots/${l}/`.padEnd(33) + `your ${l} screenshots`).join("\n");
+  return render(MULTI_LOCALE_README_TEMPLATE, {
+    BUNDLE_ID: opts.bundleId,
+    LOCALES: opts.locales.join(", "),
+    LOCALE_COUNT: String(opts.locales.length),
+    PER_LOCALE_COUNT: String(opts.perLocaleCount),
+    PANEL_LABEL: opts.panelLabel,
+    LOCALE_FOLDERS: folderLines
+  });
+}
 function screenshotFilename(index) {
   return `${String(index).padStart(2, "0")}_storeframe.png`;
 }
@@ -113,6 +189,265 @@ function buildFastlaneBundleZip(slots, opts) {
   }
   return zipSync(files, { level: 0 });
 }
+function buildMultiLocaleFastlaneBundleZip(localeSlots, opts) {
+  const locales = localeSlots.map((ls) => ls.locale);
+  const files = {
+    "README.md": strToU8(
+      generateMultiLocaleBundleReadme({
+        bundleId: opts.bundleId,
+        locales,
+        panelLabel: opts.panelLabel,
+        // Structure is shared across locales (invariant 2), so every locale has the same slot
+        // count — take the first (0 for the degenerate empty-input case).
+        perLocaleCount: localeSlots[0]?.slots.length ?? 0
+      })
+    ),
+    "fastlane/Deliverfile": strToU8(generateDeliverfile({ bundleId: opts.bundleId, locales }))
+  };
+  for (const { locale: locale2, slots } of localeSlots) {
+    for (const slot2 of slots) {
+      files[`fastlane/screenshots/${locale2}/${screenshotFilename(slot2.displayPosition)}`] = slot2.bytes;
+    }
+  }
+  return zipSync(files, { level: 0 });
+}
+
+// ../mockup-engine/appstore.ts
+var DEFAULT_LOOK = {
+  angle: "front",
+  cameraPos: null,
+  roll: "0",
+  phoneHeight: "72",
+  hOffset: "0",
+  vOffset: "0",
+  material: "real",
+  colorway: "silver",
+  customColor: "F5F5F5",
+  finish: "0",
+  clearcoat: "0",
+  clayTone: "grey",
+  clayCustom: "B0B0B0",
+  flatScreen: false,
+  glare: false,
+  lighting: true,
+  reflections: false
+};
+function normalizePanelBackgrounds(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const out = {};
+  for (const [panelId, entry] of Object.entries(raw)) {
+    if (!entry || typeof entry !== "object") continue;
+    const e = entry;
+    if (e.kind === "solid" && typeof e.color === "string") {
+      out[panelId] = { kind: "solid", color: e.color };
+    } else if (e.kind === "gradient" && typeof e.from === "string" && typeof e.to === "string" && (e.dir === "horizontal" || e.dir === "vertical")) {
+      out[panelId] = { kind: "gradient", from: e.from, to: e.to, dir: e.dir };
+    }
+  }
+  return out;
+}
+var DEFAULT_CAPTION_ANCHOR = { x: 0.5, y: 0.06 };
+function isAutoAnchor(anchor) {
+  return !anchor || anchor.x === DEFAULT_CAPTION_ANCHOR.x && anchor.y === DEFAULT_CAPTION_ANCHOR.y;
+}
+function captionLayerStyle(layer) {
+  const { text: _text, anchor, ...rest } = layer;
+  return isAutoAnchor(anchor) ? { ...rest } : { ...rest, anchor };
+}
+var DEFAULT_CAPTION_STYLE = {
+  fontId: "inter",
+  sizePt: 44,
+  color: "FFFFFF",
+  align: "center",
+  anchor: DEFAULT_CAPTION_ANCHOR,
+  maxWidth: 0.86
+};
+var LEGACY_SUBTITLE_SCALE = 0.55;
+var DEFAULT_LOCALE = "en-US";
+function normalizeCaptionStyles(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const out = {};
+  for (const [panelId, entry] of Object.entries(raw)) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+    out[panelId] = normalizeCaptionLayerStyle(entry);
+  }
+  return out;
+}
+function normalizeAnchor(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const a = raw;
+  const x = typeof a.x === "number" ? a.x : DEFAULT_CAPTION_ANCHOR.x;
+  const y = typeof a.y === "number" ? a.y : DEFAULT_CAPTION_ANCHOR.y;
+  return isAutoAnchor({ x, y }) ? void 0 : { x, y };
+}
+function normalizeCaptionLayerStyle(raw) {
+  const e = raw && typeof raw === "object" ? raw : {};
+  const anchor = normalizeAnchor(e.anchor);
+  const merged = { ...DEFAULT_CAPTION_STYLE, ...e };
+  if (anchor) merged.anchor = anchor;
+  else delete merged.anchor;
+  return merged;
+}
+function normalizeCaptionLayer(raw) {
+  const e = raw && typeof raw === "object" ? raw : {};
+  return { ...normalizeCaptionLayerStyle(e), text: typeof e.text === "string" ? e.text : "" };
+}
+function normalizeCaptionLayerStyles(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const out = {};
+  for (const [panelId, entry] of Object.entries(raw)) {
+    if (Array.isArray(entry)) {
+      if (entry.length > 0) out[panelId] = entry.map(normalizeCaptionLayerStyle);
+    } else if (entry && typeof entry === "object") {
+      out[panelId] = [normalizeCaptionLayerStyle(entry)];
+    }
+  }
+  return out;
+}
+function layersFromCaptionText(text, style2) {
+  const layers = [{ ...normalizeCaptionLayerStyle(style2), text: text.headline }];
+  if (typeof text.subtitle === "string" && text.subtitle.trim()) {
+    layers.push({ ...normalizeCaptionLayerStyle({ ...style2, sizePt: style2.sizePt * LEGACY_SUBTITLE_SCALE }), text: text.subtitle });
+  }
+  return layers;
+}
+function normalizeCaptionText(raw, captionStyles) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const styles = normalizeCaptionStyles(captionStyles);
+  const styleFor = (panelId) => styles[panelId] ?? DEFAULT_CAPTION_STYLE;
+  const innerToLayers = (inner) => {
+    if (!inner || typeof inner !== "object" || Array.isArray(inner)) return {};
+    const out2 = {};
+    for (const [panelId, value] of Object.entries(inner)) {
+      if (Array.isArray(value)) {
+        if (value.length > 0) out2[panelId] = value.map(normalizeCaptionLayer);
+      } else if (value && typeof value === "object" && typeof value.headline === "string") {
+        out2[panelId] = layersFromCaptionText(value, styleFor(panelId));
+      }
+    }
+    return out2;
+  };
+  const entries = Object.entries(raw);
+  const looksFlat = entries.some(
+    ([, value]) => !!value && typeof value === "object" && typeof value.headline === "string"
+  );
+  if (looksFlat) return { [DEFAULT_LOCALE]: innerToLayers(raw) };
+  const out = {};
+  for (const [locale2, inner] of entries) out[locale2] = innerToLayers(inner);
+  return out;
+}
+function resolveCaptionText(captionText, locale2) {
+  return captionText[locale2 ?? DEFAULT_LOCALE] ?? captionText[DEFAULT_LOCALE] ?? {};
+}
+function deriveLocales(captionText, explicit) {
+  const dedupe = (list) => {
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    for (const l of list) if (typeof l === "string" && l && !seen.has(l)) {
+      seen.add(l);
+      out.push(l);
+    }
+    return out;
+  };
+  if (Array.isArray(explicit)) {
+    const cleaned = dedupe(explicit);
+    if (cleaned.length > 0) return cleaned;
+  }
+  return dedupe([DEFAULT_LOCALE, ...Object.keys(captionText)]);
+}
+function captionStylesFromLayers(captionText) {
+  const out = {};
+  const locales = Object.keys(captionText);
+  const ordered = locales.includes(DEFAULT_LOCALE) ? [DEFAULT_LOCALE, ...locales.filter((l) => l !== DEFAULT_LOCALE)] : locales;
+  for (const locale2 of ordered) {
+    const inner = captionText[locale2];
+    if (!inner) continue;
+    for (const [panelId, layers] of Object.entries(inner)) {
+      if (out[panelId] === void 0 && Array.isArray(layers) && layers.length > 0) out[panelId] = layers.map(captionLayerStyle);
+    }
+  }
+  return out;
+}
+function shotsInPanelOrder(shots, panels) {
+  return panels.flatMap((panel) => shots.filter((s) => s.panelId === panel.id));
+}
+function isLocaleVariants(entry) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false;
+  const locales = entry.locales;
+  return !!locales && typeof locales === "object" && !Array.isArray(locales);
+}
+function resolveLocaleVariant(entry, locale2) {
+  if (!isLocaleVariants(entry)) return entry;
+  const variants = entry.locales;
+  const declared = Object.keys(variants);
+  if (declared.length === 0) {
+    throw new Error(
+      'a per-locale screenshot entry has an empty "locales" map \u2014 provide at least one locale, e.g. { "locales": { "en-US": { "ref": "\u2026" } } }'
+    );
+  }
+  return variants[locale2 ?? DEFAULT_LOCALE] ?? variants[DEFAULT_LOCALE] ?? variants[declared[0]];
+}
+function resolveLocaleVariantSlots(slots, locale2) {
+  return slots.map((slot2) => slot2.map((entry) => resolveLocaleVariant(entry, locale2)));
+}
+function collectVariantLocales(entries) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const entry of entries) {
+    if (!isLocaleVariants(entry)) continue;
+    for (const locale2 of Object.keys(entry.locales)) {
+      if (!seen.has(locale2)) {
+        seen.add(locale2);
+        out.push(locale2);
+      }
+    }
+  }
+  return out;
+}
+var PROJECT_SCHEMA_VERSION = 2;
+function serializeProject(state) {
+  const ordered = shotsInPanelOrder(state.shots, state.panels);
+  const shots = ordered.map((s) => ({
+    id: s.id,
+    panelId: s.panelId,
+    frameNodeId: s.frameNodeId,
+    frameName: s.frameName,
+    look: s.look,
+    inputAnchor: s.inputAnchor,
+    // v2 provenance — persisted so drift survives reload
+    outputAnchor: s.outputAnchor
+  }));
+  const captionText = normalizeCaptionText(state.captionText, state.captionStyles);
+  return {
+    schema: PROJECT_SCHEMA_VERSION,
+    shots,
+    panels: state.panels,
+    selectedShotId: state.selectedShotId,
+    // Caption TEXT is content: emitted here on the project record, deliberately NOT via
+    // extractStripStyle — so words can never leak into serializeLook's styling blob (invariant 2).
+    captionText,
+    // The language list is content too — placed here (not the extractStripStyle spread) so languages
+    // never leak into a Look (invariant 3). Per-locale screenshot BYTES (state.localeScreens) are
+    // DROPPED, exactly as Shot.bytes are: bytes never enter the record (rule 1). They persist only in
+    // the byte-cache and re-join by frameName on load.
+    locales: deriveLocales(captionText, state.locales),
+    ...extractStripStyle(state, captionText)
+  };
+}
+function extractStripStyle(state, captionText) {
+  return {
+    panelPresetId: state.panelPresetId,
+    bgMode: state.bgMode,
+    gradientFrom: state.gradientFrom,
+    gradientTo: state.gradientTo,
+    gradientDir: state.gradientDir,
+    panelColors: state.panelColors,
+    shadow: state.shadow,
+    floorReflection: state.floorReflection ?? false,
+    panelBackgrounds: state.panelBackgrounds ?? {},
+    captionStyles: { ...normalizeCaptionLayerStyles(state.captionStyles), ...captionStylesFromLayers(captionText) }
+  };
+}
 
 // src/screenshotInput.ts
 import { readFile } from "node:fs/promises";
@@ -309,15 +644,18 @@ function panelDimensionsFor(presetId) {
 var nameField = z.string().max(200).optional().describe(
   `The screenshot's original filename (e.g. "03_statistics.png"). Pass it so that, if this render is saved as a project, the user's own screenshots folder re-loads exactly this file by name. Optional if the ref already carries a name (from request_screenshot_upload({ names })); omit entirely and the record falls back to a positional name (screen-N.png).`
 );
-var screenshotEntry = z.union([
-  z.string().min(1).describe('Inline base64-encoded PNG (no "data:" prefix). Small payloads only.'),
-  z.object({ ref: z.string().min(1), name: nameField }).strict().describe("A ref returned by request_screenshot_upload \u2014 resolved server-side, never re-sent inline."),
-  z.object({ url: z.string().min(1), name: nameField }).strict().describe("An https URL to a PNG \u2014 fetched server-side (image/png, no redirects, ~20MB cap)."),
-  z.object({ path: z.string().min(1), name: nameField }).strict().describe(
-    "A local filesystem path to a PNG, read straight off disk \u2014 ONLY available over the local stdio server (npx storeframe-mcp); the hosted server rejects this entry shape."
-  )
-]);
-var screenshotsDescription = 'An array of App Store slots in display order (1\u201310; the store allows up to 10 per size). Each slot is itself an array of screenshots: one entry = one phone in that slot, several entries = multiple phones composited into that one slot. Each screenshot entry is EITHER an inline base64 PNG string (small payloads only \u2014 large inline payloads are rejected with a clear error), OR { "ref": "..." } from request_screenshot_upload, OR { "url": "https://..." }, OR (local stdio mode only) { "path": "/abs/or/relative/path.png" } to read a file straight off disk. Prefer ref/url for real screenshots so the bytes never transit this conversation.';
+var inlineBase64Entry = z.string().min(1).describe('Inline base64-encoded PNG (no "data:" prefix). Small payloads only.');
+var refEntry = z.object({ ref: z.string().min(1), name: nameField }).strict().describe("A ref returned by request_screenshot_upload \u2014 resolved server-side, never re-sent inline.");
+var urlEntry = z.object({ url: z.string().min(1), name: nameField }).strict().describe("An https URL to a PNG \u2014 fetched server-side (image/png, no redirects, ~20MB cap).");
+var pathEntry = z.object({ path: z.string().min(1), name: nameField }).strict().describe(
+  "A local filesystem path to a PNG, read straight off disk \u2014 ONLY available over the local stdio server (npx storeframe-mcp); the hosted server rejects this entry shape."
+);
+var singleScreenshotEntry = z.union([inlineBase64Entry, refEntry, urlEntry, pathEntry]);
+var localeScreenshotEntry = z.object({ locales: z.record(z.string(), singleScreenshotEntry) }).strict().describe(
+  'Per-locale variants of ONE screenshot: { "locales": { "en-US": <entry>, "de-DE": <entry> } } (each variant is an inline base64 / ref / url / path entry). render_strip picks the top-level `locale`\'s variant; emit_bundle with `locales` renders/packages every listed locale. A locale with no variant of its own falls back to the en-US variant (else the first declared), so you can localize only some screenshots.'
+);
+var screenshotEntry = z.union([inlineBase64Entry, refEntry, urlEntry, pathEntry, localeScreenshotEntry]);
+var screenshotsDescription = 'An array of App Store slots in display order (1\u201310; the store allows up to 10 per size). Each slot is itself an array of screenshots: one entry = one phone in that slot, several entries = multiple phones composited into that one slot. Each screenshot entry is EITHER an inline base64 PNG string (small payloads only \u2014 large inline payloads are rejected with a clear error), OR { "ref": "..." } from request_screenshot_upload, OR { "url": "https://..." }, OR (local stdio mode only) { "path": "/abs/or/relative/path.png" } to read a file straight off disk, OR { "locales": { "<locale>": <any of those> } } to vary that screenshot per App Store locale (missing locales fall back to the en-US variant). Prefer ref/url for real screenshots so the bytes never transit this conversation.';
 var slot = z.array(screenshotEntry).min(1).max(6).describe(
   "One App Store slot: 1\u20136 screenshots. Several entries = several phones composited into that one slot."
 );
@@ -326,8 +664,12 @@ var screenshotsForSave = z.array(slot).min(1).max(10).describe(
   `${screenshotsDescription} NOTE: save_project does not render \u2014 it uses only each slot's SHAPE (phones per panel) and each entry's \`name\` (source filename, for re-load matching). The image bytes are never fetched or stored, so pass the same entries you rendered with (esp. their \`name\`s).`
 );
 var screenshotsOptional = z.array(slot).min(1).max(10).optional().describe(`${screenshotsDescription} Required unless \`panels\` (pre-rendered refs) is given instead.`);
-var panelRefs = z.array(z.object({ ref: z.string().min(1) }).strict()).min(1).max(10).optional().describe(
-  'Pre-rendered panel refs from a prior render_strip call made with `output: "urls"` \u2014 packages them directly into the bundle WITHOUT rendering again. Mutually exclusive with `screenshots`; one of the two is required.'
+var panelRef = z.object({ ref: z.string().min(1) }).strict();
+var localePanelRef = z.object({ locales: z.record(z.string(), panelRef) }).strict().describe(
+  'Per-locale variants of ONE pre-rendered panel: { "locales": { "en-US": { "ref": "\u2026" }, "de-DE": { "ref": "\u2026" } } }. Used with `locales` to compose a multi-locale bundle from per-locale render_strip results without re-rendering; a missing locale falls back to the en-US variant (else the first declared).'
+);
+var panelRefs = z.array(z.union([panelRef, localePanelRef])).min(1).max(10).optional().describe(
+  'Pre-rendered panel refs from a prior render_strip call made with `output: "urls"` \u2014 packages them directly into the bundle WITHOUT rendering again. Mutually exclusive with `screenshots`; one of the two is required. An entry may also be { "locales": { "<locale>": { "ref": "\u2026" } } } to vary that panel per locale (see `locales`).'
 );
 var output = z.enum(["inline", "urls"]).optional().describe(
   'How to return rendered bytes: "inline" (base64), "urls" (uploaded, short-lived signed download URLs \u2014 use for real/full-resolution renders so bytes never transit this conversation), or omit for auto (inline under ~200KB total, urls above).'
@@ -337,11 +679,14 @@ var preview = z.boolean().optional().describe(
 );
 var panelPresetId = z.enum(PANEL_PRESET_IDS).optional().describe("App Store screenshot size. Default r69 (6.9\u2033 iPhone, 1290\xD72796).");
 var look = z.record(z.string(), z.unknown()).optional().describe(
-  'A Storeframe "look" (styling only) JSON, exactly as returned by read_look, applied to the strip. Omit for default styling.'
+  'A Storeframe "look" (styling only) JSON, exactly as returned by read_look, applied to the strip. Omit for default styling. Unlike style.shotLook (one device for the whole strip), a look carries shots[] \u2014 one entry per panel in slot order, each with its own look \u2014 so you can style each panel differently (mixed-device / continuous-scene). See describe_look.'
 );
 var useSavedLook = z.boolean().optional().describe("If true, style the strip with the project's saved look (ignored when `look`/`style` is given).");
 var locale = z.string().optional().describe(
-  'App Store locale, e.g. "de-DE" (default en-US). Labels the render and, for emit_bundle, selects the fastlane screenshots folder. Does not select caption text \u2014 pass the copy for this locale yourself via `style.captions[].text` (see the README\'s `captions.<locale>.json` convention).'
+  'App Store locale, e.g. "de-DE" (default en-US). Labels the render, selects which { "locales": \u2026 } screenshot variants render, and, for emit_bundle, selects the fastlane screenshots folder. Does not select caption text \u2014 pass the copy for this locale yourself via `style.captions[].text` (see the README\'s `captions.<locale>.json` convention).'
+);
+var localesField = z.array(z.string().min(1)).min(1).max(40).optional().describe(
+  'Emit ONE multi-locale bundle: render (or, with `panels`, just package) each listed App Store locale and lay them out as fastlane/screenshots/<locale>/ folders in a single zip. Screenshot/panel entries may vary per locale via { "locales": \u2026 }; a plain entry \u2014 or a missing locale variant \u2014 falls back to the en-US variant, so a locale with no screens of its own ships the fallback pixels in its own folder (correct for fastlane). With `screenshots` this renders once PER locale (slow \u2014 prefer per-locale render_strip calls with output:"urls", then compose here with per-locale `panels`). A single-entry list behaves exactly like `locale`. Caption text is per-RENDER input: in this one-call form the same style.captions apply to every locale, so for localized captions use the render-per-locale-then-compose flow.'
 );
 var CAPTION_FONT_IDS = ["inter", "manrope", "poppins", "fraunces", "space-grotesk"];
 var DEFAULT_SHOT_LOOK = {
@@ -355,6 +700,7 @@ var DEFAULT_SHOT_LOOK = {
   colorway: "silver",
   customColor: "F5F5F5",
   finish: "0",
+  clearcoat: "0",
   clayTone: "grey",
   clayCustom: "B0B0B0",
   flatScreen: false,
@@ -362,7 +708,7 @@ var DEFAULT_SHOT_LOOK = {
   lighting: true,
   reflections: false
 };
-var DEFAULT_CAPTION_STYLE = {
+var DEFAULT_CAPTION_STYLE2 = {
   fontId: "inter",
   sizePt: 44,
   color: "FFFFFF",
@@ -382,6 +728,7 @@ var shotLook = z.object({
   colorway: z.enum(["orange", "blue", "silver", "custom"]).optional().describe('Body colour (material "real"). Default silver.'),
   customColor: z.string().optional().describe('Hex body colour when colorway is "custom".'),
   finish: numeric.optional().describe("0 = matte \u2026 1 = glossy. Default 0."),
+  clearcoat: numeric.optional().describe("0 = none \u2026 1 = glossy clear-coat lacquer over the body (a wet/ceramic sheen, on top of finish). Default 0."),
   clayTone: z.enum(["grey", "white", "charcoal", "custom"]).optional().describe('Clay tone (material "clay"). Default grey.'),
   clayCustom: z.string().optional().describe('Hex clay colour when clayTone is "custom".'),
   flatScreen: z.boolean().optional().describe("Render the screen flat (no curvature). Default false."),
@@ -395,7 +742,8 @@ var background = z.object({
   gradientTo: z.string().optional().describe("Gradient end (hex). Default #0a0a14."),
   gradientDir: z.enum(["vertical", "horizontal"]).optional().describe("Default vertical."),
   panelColors: z.array(z.string().nullable()).max(10).optional().describe('Per-panel flat colours (mode "perPanel"), one entry per slot in order; null = default.'),
-  shadow: z.boolean().optional().describe("Drop shadow under the phones. Default true.")
+  shadow: z.boolean().optional().describe("Drop shadow under the phones. Default true."),
+  floorReflection: z.boolean().optional().describe("Flipped, faded floor reflection under each phone. Default false.")
 }).strict();
 var captionEntry = z.object({
   fontId: z.enum(CAPTION_FONT_IDS).optional().describe("Bundled font. Default inter."),
@@ -410,7 +758,13 @@ var captionEntry = z.object({
 var style = z.object({
   shotLook: shotLook.optional().describe("Device/camera styling, applied to every phone in the strip."),
   background: background.optional(),
-  captions: z.array(captionEntry.nullable()).max(10).optional().describe("One entry PER PANEL in slot order; null = no caption on that panel.")
+  // plan-20 Phase 8 (D9): one entry PER PANEL, and each entry is EITHER a single caption object OR
+  // an ORDERED ARRAY of caption layers (a multi-line strip: headline + subline + …). Both are
+  // accepted forever — this is a public wire contract (published npm + hosted Fly server), so the
+  // union is additive, never a breaking swap. null = no caption on that panel.
+  captions: z.array(z.union([captionEntry, z.array(captionEntry).max(8)]).nullable()).max(10).optional().describe(
+    "One entry PER PANEL in slot order; null = no caption on that panel. An entry is EITHER a single caption object OR an array of caption layers (stacked, in order) on that panel."
+  )
 }).strict().optional().describe(
   "Structured styling \u2014 the discoverable alternative to the opaque `look` param (call describe_look for the full field catalog + defaults). Wins over `look`/`useSavedLook`."
 );
@@ -453,6 +807,7 @@ var emitBundleShape = {
     "Your app\u2019s reverse-DNS bundle identifier, e.g. com.acme.app. Pre-fills the fastlane Deliverfile ONLY \u2014 it is never sent to any store from here."
   ),
   locale,
+  locales: localesField,
   projectName: z.string().optional().describe('A name for the bundle (used for the zip filename + any share link). Default "storeframe".'),
   share: z.boolean().optional().describe(
     "Also create an unguessable, 14-day share link to a landing page (preview + bundle download + fastlane how-to), attributed to your account. Default false."
@@ -478,6 +833,17 @@ var saveProjectShape = {
   sourceDir
 };
 var readLookShape = { project };
+var readProjectShape = { project };
+var screenshotFileList = z.array(singleScreenshotEntry).min(1).max(60).describe(
+  `A FLAT list of the developer's raw app screenshots \u2014 each an inline base64 PNG, { "ref" }, { "url" }, or (local stdio only) { "path" }, and each with a \`name\` (its original filename). They are matched to the saved project's shots BY FILENAME (name === the shot's frameName), so the order you pass them does NOT matter and you never pre-sort. A shot with no matching file is reported as missing (it does not error the render). Prefer ref/url for real screenshots so the bytes never transit this conversation.`
+);
+var renderProjectShape = {
+  project,
+  screenshots: screenshotFileList,
+  locale,
+  preview,
+  output
+};
 var saveLookShape = {
   project,
   look: z.record(z.string(), z.unknown()).describe(
@@ -501,6 +867,7 @@ var DESCRIBE_LOOK_CATALOG = {
         material: "real | clay",
         colorway: "orange | blue | silver | custom (with customColor hex)",
         finish: "0 (matte) \u2026 1 (glossy)",
+        clearcoat: "0 (none) \u2026 1 (glossy clear-coat lacquer over the body, on top of finish)",
         clayTone: "grey | white | charcoal | custom (with clayCustom hex)",
         flatScreen: "boolean",
         glare: "boolean",
@@ -510,28 +877,30 @@ var DESCRIBE_LOOK_CATALOG = {
     },
     background: {
       description: "The strip background.",
-      defaults: { mode: "gradient", gradientFrom: "#1b1b2e", gradientTo: "#0a0a14", gradientDir: "vertical", shadow: true },
+      defaults: { mode: "gradient", gradientFrom: "#1b1b2e", gradientTo: "#0a0a14", gradientDir: "vertical", shadow: true, floorReflection: false },
       fields: {
         mode: "gradient | perPanel",
-        panelColors: 'per-panel hex colours (mode "perPanel"), one entry per slot in order'
+        panelColors: 'per-panel hex colours (mode "perPanel"), one entry per slot in order',
+        floorReflection: "boolean \u2014 a flipped, faded floor reflection under each phone"
       }
     },
     captions: {
-      description: "One entry PER PANEL in slot order (null = no caption). Styling is part of the look; `text`/`subtitle` are per-RENDER input and are never stored (zero-custody of content).",
-      defaults: DEFAULT_CAPTION_STYLE,
+      description: "One entry PER PANEL in slot order (null = no caption). An entry is EITHER a single caption object OR an array of caption LAYERS stacked in order on that panel (e.g. a headline layer + a subline layer). Styling is part of the look; `text` (and a single caption\u2019s `subtitle`) are per-RENDER input and are never stored (zero-custody of content). Captions AUTO-LAYOUT above the device by default so they never collide with the phone.",
+      defaults: DEFAULT_CAPTION_STYLE2,
       fonts: CAPTION_FONT_IDS,
       fields: {
         sizePt: "font size in iOS points \u2014 preset-independent",
-        anchor: "{ x, y } normalized 0\u20131 position on the panel",
+        anchor: "{ x, y } normalized 0\u20131 position on the panel \u2014 OMIT to auto-place above the device",
         maxWidth: "wrap width as a 0\u20131 fraction of the panel width",
-        text: "the headline (per-render input)",
-        subtitle: "optional subtitle (per-render input)"
+        text: "the headline / this layer\u2019s words (per-render input)",
+        subtitle: "single-caption shape only: an optional second line (per-render input). In the ARRAY shape, add another layer instead."
       }
     }
   },
   panelPresets: PANEL_PRESET_IDS.map((id) => ({ id, ...PANEL_DIMENSIONS[id], label: PANEL_LABELS[id] })),
   notes: [
     "Pass `style` to render_strip/emit_bundle for structured styling, or save a composed look with save_look and render with useSavedLook.",
+    'style.shotLook is ONE device for the whole strip. For a DIFFERENT device per panel (mixed-device or continuous-scene strips), pass a `look` instead \u2014 a look has shots[], one entry per panel in slot order, each with its own `look` (same fields as shotLook). e.g. look:{ shots:[ {panelId:"panel-1",look:{angle:"left"}}, {panelId:"panel-2",look:{colorway:"orange"}} ] }.',
     "save_look bumps the look version; pinning a version is done in Storeframe Studio (the Look bar), and pinned projects render their pinned version by default."
   ]
 };
@@ -542,6 +911,13 @@ var requestScreenshotUploadShape = {
   // `{ ref }` bare (no `name`). Optional; a shorter/absent array just leaves those slots nameless.
   names: z.array(z.string().max(200)).optional().describe(
     'Original filenames, one per slot in the same order (e.g. ["03_statistics.png", ...]). Each is encoded into that slot\'s ref, so the saved project re-loads by real filename even without re-passing `name` at render time. Optional.'
+  ),
+  // plan-21 Phase 5 (D6): an ORGANIZATIONAL tag only — which locale this batch of uploads is
+  // for. Echoed back in the response so an agent uploading per-locale batches can keep its
+  // refs sorted; it changes nothing about the refs themselves (any ref works in any locale
+  // slot of a { locales: … } entry).
+  locale: z.string().optional().describe(
+    'Optional tag: which App Store locale these screenshots are for (e.g. "de-DE") when uploading one batch per locale. Echoed back for your bookkeeping only \u2014 the refs are locale-agnostic; place each under the matching key of a { "locales": \u2026 } screenshot entry.'
   )
 };
 
@@ -558,6 +934,19 @@ function resolveOutputMode(requested, totalBytes) {
   if (requested === "inline" || requested === "urls") return requested;
   return totalBytes > AUTO_INLINE_THRESHOLD_BYTES ? "urls" : "inline";
 }
+function dedupeLocales(list) {
+  if (!Array.isArray(list)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const raw of list) {
+    const locale2 = typeof raw === "string" ? raw.trim() : "";
+    if (locale2 && !seen.has(locale2)) {
+      seen.add(locale2);
+      out.push(locale2);
+    }
+  }
+  return out;
+}
 async function resolveLook(deps2, args) {
   if (args.style != null) return { look: null, style: args.style };
   if (args.look != null) return { look: args.look };
@@ -629,9 +1018,16 @@ async function handleRenderStrip(deps2, args) {
   if (args.createProject && args.preview) {
     return errorResult("createProject cannot be combined with preview:true \u2014 drop preview to persist a full render (or iterate with preview, then render once without it).");
   }
+  const screenshotLocales = collectVariantLocales(args.screenshots.flat());
+  let entries;
+  try {
+    entries = resolveLocaleVariantSlots(args.screenshots, locale2);
+  } catch (err) {
+    return errorResult(err.message);
+  }
   let screenshots2;
   try {
-    screenshots2 = await resolveScreenshots(args.screenshots, deps2.userId, deps2.allowLocalScreenshots ?? false);
+    screenshots2 = await resolveScreenshots(entries, deps2.userId, deps2.allowLocalScreenshots ?? false);
   } catch (err) {
     return errorResult(err.message);
   }
@@ -644,7 +1040,9 @@ async function handleRenderStrip(deps2, args) {
     locale: locale2,
     buildRecord: args.createProject === true,
     // Phase 5A: only compute names when we're building a record (saving a project).
-    ...args.createProject ? { screenshotNames: resolveScreenshotNames(args.screenshots) } : {}
+    // Per-locale entries: names come from the locale-resolved entries — the record describes
+    // exactly the files this render used.
+    ...args.createProject ? { screenshotNames: resolveScreenshotNames(entries) } : {}
   });
   if (!result.ok || !result.panels) {
     return errorResult(`render failed: ${result.error ?? "unknown error"}`);
@@ -672,6 +1070,9 @@ async function handleRenderStrip(deps2, args) {
     renderMs: result.ms,
     output: outputMode,
     locale: locale2,
+    // Only when the payload actually carried per-locale entries — a legacy payload's
+    // response stays byte-identical (D6).
+    ...screenshotLocales.length > 0 ? { screenshotLocales } : {},
     ...note ? { note } : {},
     ...persisted ? { projectId: persisted.projectId, openUrl: persisted.openUrl } : {},
     ...persistNote ? { projectNote: persistNote } : {},
@@ -690,8 +1091,17 @@ async function handleEmitBundle(deps2, args) {
   if (!isValidBundleId(args.bundleId)) {
     return errorResult(`invalid bundleId "${args.bundleId}" \u2014 expected reverse-DNS, e.g. com.acme.app`);
   }
-  const locale2 = args.locale?.trim() || "en-US";
   const projectName2 = args.projectName?.trim() || "storeframe";
+  const requestedLocales = dedupeLocales(args.locales);
+  if (requestedLocales.length >= 2) {
+    if (args.createProject) {
+      return errorResult(
+        "createProject is not supported with the multi-locale `locales` form \u2014 save the editable project separately with save_project (a project record is structure + look, locale-independent), or emit a single-locale bundle with `locale`."
+      );
+    }
+    return emitMultiLocaleBundle(deps2, args, requestedLocales, projectName2);
+  }
+  const locale2 = requestedLocales[0] ?? (args.locale?.trim() || "en-US");
   if (args.createProject && args.panels && args.panels.length > 0) {
     return errorResult("createProject is not supported on the compose-only `panels` path (nothing is re-styled here) \u2014 use render_strip({ createProject: true }) or save_project on the render path instead.");
   }
@@ -703,9 +1113,15 @@ async function handleEmitBundle(deps2, args) {
   if (args.panels && args.panels.length > 0) {
     const dims = panelDimensionsFor(args.panelPresetId ?? "r69");
     panelLabel = panelLabelFor(args.panelPresetId ?? "r69", dims.width, dims.height);
+    let panelEntries;
+    try {
+      panelEntries = args.panels.map((p) => resolveLocaleVariant(p, locale2));
+    } catch (err) {
+      return errorResult(err.message);
+    }
     let bytesList;
     try {
-      bytesList = await Promise.all(args.panels.map((p) => fetchUploadedRef(p.ref, deps2.userId)));
+      bytesList = await Promise.all(panelEntries.map((p) => fetchUploadedRef(p.ref, deps2.userId)));
     } catch (err) {
       return errorResult(`failed to fetch panel ref: ${err.message}`);
     }
@@ -715,9 +1131,15 @@ async function handleEmitBundle(deps2, args) {
     if (!args.screenshots || args.screenshots.length === 0) {
       return errorResult("emit_bundle needs either `screenshots` or pre-rendered `panels` refs.");
     }
+    let entries;
+    try {
+      entries = resolveLocaleVariantSlots(args.screenshots, locale2);
+    } catch (err) {
+      return errorResult(err.message);
+    }
     let screenshots2;
     try {
-      screenshots2 = await resolveScreenshots(args.screenshots, deps2.userId, deps2.allowLocalScreenshots ?? false);
+      screenshots2 = await resolveScreenshots(entries, deps2.userId, deps2.allowLocalScreenshots ?? false);
     } catch (err) {
       return errorResult(err.message);
     }
@@ -730,7 +1152,7 @@ async function handleEmitBundle(deps2, args) {
       style: resolved.style,
       locale: locale2,
       buildRecord: args.createProject === true,
-      ...args.createProject && args.screenshots ? { screenshotNames: resolveScreenshotNames(args.screenshots) } : {}
+      ...args.createProject ? { screenshotNames: resolveScreenshotNames(entries) } : {}
     });
     if (!result.ok || !result.panels || !result.panelPresetId) {
       return errorResult(`render failed: ${result.error ?? "unknown error"}`);
@@ -740,6 +1162,11 @@ async function handleEmitBundle(deps2, args) {
     previewPng = result.stripBase64 ? Buffer.from(result.stripBase64, "base64") : null;
     projectRecord = result.projectRecord;
   }
+  const declaredLocales = collectVariantLocales([...(args.screenshots ?? []).flat(), ...args.panels ?? []]);
+  if (declaredLocales.length > 0) {
+    const hint = `per-locale screenshots detected (${declaredLocales.join(", ")}) \u2014 this call bundled only ${locale2}; pass locales: [...] to emit ONE multi-locale bundle.`;
+    note = note ? `${note} ${hint}` : hint;
+  }
   const zip = buildFastlaneBundleZip(slots, { bundleId: args.bundleId, locale: locale2, panelLabel });
   const filename = bundleZipFilename(projectName2);
   let shareLink;
@@ -790,6 +1217,116 @@ async function handleEmitBundle(deps2, args) {
     ...zipOut
   });
 }
+async function emitMultiLocaleBundle(deps2, args, locales, projectName2) {
+  let localeSlots;
+  let panelLabel;
+  let previewPng = null;
+  let note;
+  if (args.panels && args.panels.length > 0) {
+    const dims = panelDimensionsFor(args.panelPresetId ?? "r69");
+    panelLabel = panelLabelFor(args.panelPresetId ?? "r69", dims.width, dims.height);
+    const refCache = /* @__PURE__ */ new Map();
+    const fetchRef = (ref) => {
+      let pending = refCache.get(ref);
+      if (!pending) {
+        pending = fetchUploadedRef(ref, deps2.userId);
+        refCache.set(ref, pending);
+      }
+      return pending;
+    };
+    localeSlots = [];
+    try {
+      for (const loc of locales) {
+        const refs = args.panels.map((p) => resolveLocaleVariant(p, loc));
+        const bytesList = await Promise.all(refs.map((p) => fetchRef(p.ref)));
+        localeSlots.push({
+          locale: loc,
+          slots: bytesList.map((bytes, i) => ({ displayPosition: i + 1, bytes: Buffer.from(bytes) }))
+        });
+      }
+    } catch (err) {
+      return errorResult(`failed to fetch panel ref: ${err.message}`);
+    }
+    const firstPanel = localeSlots[0]?.slots[0];
+    previewPng = firstPanel ? Buffer.from(firstPanel.bytes) : null;
+  } else {
+    if (!args.screenshots || args.screenshots.length === 0) {
+      return errorResult("emit_bundle needs either `screenshots` or pre-rendered `panels` refs.");
+    }
+    const resolved = await resolveLook(deps2, args);
+    note = resolved.note;
+    localeSlots = [];
+    panelLabel = "";
+    for (const loc of locales) {
+      let entries;
+      try {
+        entries = resolveLocaleVariantSlots(args.screenshots, loc);
+      } catch (err) {
+        return errorResult(err.message);
+      }
+      let screenshots2;
+      try {
+        screenshots2 = await resolveScreenshots(entries, deps2.userId, deps2.allowLocalScreenshots ?? false);
+      } catch (err) {
+        return errorResult(err.message);
+      }
+      const result = await deps2.renderer.render({
+        screenshots: screenshots2,
+        panelPresetId: args.panelPresetId,
+        look: resolved.look,
+        style: resolved.style,
+        locale: loc
+      });
+      if (!result.ok || !result.panels || !result.panelPresetId) {
+        return errorResult(`render failed for locale ${loc}: ${result.error ?? "unknown error"}`);
+      }
+      localeSlots.push({
+        locale: loc,
+        slots: result.panels.map((b64, i) => ({ displayPosition: i + 1, bytes: Buffer.from(b64, "base64") }))
+      });
+      if (!panelLabel) panelLabel = panelLabelFor(result.panelPresetId, result.panelWidth ?? 0, result.panelHeight ?? 0);
+      if (!previewPng && result.stripBase64) previewPng = Buffer.from(result.stripBase64, "base64");
+    }
+  }
+  const zip = buildMultiLocaleFastlaneBundleZip(localeSlots, { bundleId: args.bundleId, panelLabel });
+  const filename = bundleZipFilename(projectName2);
+  let shareLink;
+  if (args.share) {
+    if (!previewPng) return errorResult("cannot create share link: no preview image available");
+    try {
+      shareLink = await deps2.createShareLink({
+        userId: deps2.userId,
+        zip,
+        previewPng,
+        projectName: projectName2,
+        panelCount: localeSlots[0]?.slots.length ?? 0,
+        bundleId: args.bundleId,
+        // The share row's locale is display metadata — name every locale in the bundle.
+        locale: locales.join(", "),
+        origin: deps2.studioOrigin
+      });
+    } catch (err) {
+      return errorResult(`could not create share link: ${err.message}`);
+    }
+  }
+  const outputMode = resolveOutputMode(deps2.forceOutput ?? args.output, zip.byteLength);
+  const zipOut = outputMode === "urls" ? await storeAsset(uploadDirFor(deps2.userId), filename, zip, "application/zip").then((a) => ({
+    zipUrl: a.url,
+    zipRef: a.ref
+  })) : { zipBase64: Buffer.from(zip).toString("base64") };
+  return textResult({
+    ok: true,
+    filename,
+    bundleId: args.bundleId,
+    locales,
+    panelCount: localeSlots[0]?.slots.length ?? 0,
+    // per locale — total files = panelCount × locales.length
+    output: outputMode,
+    ...note ? { note } : {},
+    ...shareLink ? { shareLink } : {},
+    ...zipOut
+  });
+}
 async function handleSaveProject(deps2, args) {
   const { look: look2, style: style2 } = await resolveLook(deps2, args);
   const locale2 = args.locale?.trim() || "en-US";
@@ -800,7 +1337,13 @@ async function handleSaveProject(deps2, args) {
   if (slotSizes.some((n) => n < 1)) {
     return errorResult("every `screenshots` slot must contain at least one screenshot entry.");
   }
-  const screenshotNames = resolveScreenshotNames(args.screenshots).flat();
+  let entries;
+  try {
+    entries = resolveLocaleVariantSlots(args.screenshots, locale2);
+  } catch (err) {
+    return errorResult(err.message);
+  }
+  const screenshotNames = resolveScreenshotNames(entries).flat();
   let record;
   try {
     record = await deps2.renderer.buildRecord({
@@ -856,6 +1399,145 @@ async function handleReadLook(deps2, args) {
     look: saved.look
   });
 }
+function projectFileFromRecord(record) {
+  const inner = record?.project;
+  return inner != null && typeof inner === "object" ? inner : record;
+}
+async function handleReadProject(deps2, args) {
+  const project2 = await deps2.resolveProject(deps2.userId, args.project);
+  if (!project2) {
+    return textResult({
+      saved: false,
+      message: args.project ? "No such project on this account." : "No Storeframe project on this account yet \u2014 open Storeframe Studio and load a strip first."
+    });
+  }
+  const rec = await deps2.readProjectRecord(project2.id);
+  if (!rec) {
+    return textResult({
+      saved: false,
+      project: { id: project2.id, name: project2.name },
+      message: `Project "${project2.name}" has no saved record yet \u2014 open it in Storeframe Studio and save a strip first.`
+    });
+  }
+  return textResult({
+    saved: true,
+    project: { id: project2.id, name: project2.name },
+    updatedAt: rec.updatedAt,
+    pinnedVersion: project2.pinnedVersion,
+    // null = renders follow the latest look version
+    project_file: projectFileFromRecord(rec.record),
+    message: `Full project for "${project2.name}". project_file is the designer's current strip (frame order in \`panels\`, per-locale words in \`captionText\`, \`locales\`, styling). To detect changes, remember updatedAt and compare on your next read_project \u2014 a newer value means the designer edited it.`
+  });
+}
+function frameNamesFromProjectFile(projectFile) {
+  const shots = projectFile?.shots;
+  if (!Array.isArray(shots)) return [];
+  return shots.map((s) => s?.frameName).filter((n) => typeof n === "string" && n.length > 0);
+}
+function handoffRefsFromRecord(record) {
+  const raw = record?.handoffRefs;
+  if (!raw || typeof raw !== "object") return {};
+  const out = {};
+  for (const [name, ref] of Object.entries(raw)) {
+    if (typeof ref === "string" && ref.length > 0) out[name] = ref;
+  }
+  return out;
+}
+async function handleRenderProject(deps2, args) {
+  const project2 = await deps2.resolveProject(deps2.userId, args.project);
+  if (!project2) {
+    return errorResult(
+      args.project ? "No such project on this account." : "No Storeframe project on this account yet \u2014 open Storeframe Studio and load a strip first."
+    );
+  }
+  const rec = await deps2.readProjectRecord(project2.id);
+  if (!rec) {
+    return errorResult(`Project "${project2.name}" has no saved record yet \u2014 open it in Storeframe Studio and save a strip first.`);
+  }
+  const projectFile = projectFileFromRecord(rec.record);
+  const nested = args.screenshots.map((e) => [e]);
+  let resolvedBytes;
+  try {
+    resolvedBytes = await resolveScreenshots(nested, deps2.userId, deps2.allowLocalScreenshots ?? false);
+  } catch (err) {
+    return errorResult(err.message);
+  }
+  const names = resolveScreenshotNames(nested);
+  const screensByName = {};
+  let unnamed = 0;
+  names.forEach((slot2, i) => {
+    const name = slot2[0];
+    if (name) screensByName[name] = resolvedBytes[i][0];
+    else unnamed++;
+  });
+  const expected = frameNamesFromProjectFile(projectFile);
+  const handoffRefs = handoffRefsFromRecord(rec.record);
+  const handoffUsed = [];
+  if (deps2.fetchHandoffBytes) {
+    for (const frameName of expected) {
+      if (screensByName[frameName]) continue;
+      const ref = handoffRefs[frameName];
+      if (!ref) continue;
+      try {
+        const bytes = await deps2.fetchHandoffBytes(ref);
+        screensByName[frameName] = Buffer.from(bytes).toString("base64");
+        handoffUsed.push(frameName);
+      } catch {
+      }
+    }
+  }
+  if (expected.length > 0 && !expected.some((n) => screensByName[n])) {
+    return errorResult(
+      `None of the supplied screenshots matched this project's frames by filename. This project expects: ${expected.join(", ")}. Pass each raw screenshot with its original \`name\` (its filename), in any order \u2014 render_project matches by name.`
+    );
+  }
+  const locale2 = args.locale?.trim() || void 0;
+  const result = await deps2.renderer.renderProject({ projectFile, screensByName, locale: locale2, preview: args.preview });
+  if (!result.ok || !result.panels) {
+    return errorResult(`render failed: ${result.error ?? "unknown error"}`);
+  }
+  const shots = result.shots ?? [];
+  const missing = shots.filter((s) => !s.matched).map((s) => s.frameName);
+  const totalBytes = result.panels.reduce((sum, p) => sum + estimateDecodedBytes(p), 0);
+  const outputMode = resolveOutputMode(deps2.forceOutput ?? args.output, totalBytes);
+  const panels = outputMode === "urls" ? await uploadPanels(deps2.userId, result.panels) : result.panels;
+  const notes = [];
+  if (handoffUsed.length > 0) {
+    notes.push(
+      `${handoffUsed.length} shot(s) were resolved from the designer's uploaded screenshots (auto-handoff): ${handoffUsed.join(", ")}.`
+    );
+  }
+  if (missing.length > 0) {
+    notes.push(
+      `${missing.length} shot(s) had no matching screenshot and rendered without a device: ${missing.join(", ")}. Supply those files (by filename) to complete the strip.`
+    );
+  }
+  if (unnamed > 0) {
+    notes.push(
+      `${unnamed} supplied screenshot(s) had no filename (name) and could not be matched \u2014 pass each screenshot's original filename via \`name\`.`
+    );
+  }
+  return textResult({
+    ok: true,
+    count: result.count,
+    panelPresetId: result.panelPresetId,
+    panelWidth: result.panelWidth,
+    panelHeight: result.panelHeight,
+    renderMs: result.ms,
+    output: outputMode,
+    locale: result.locale ?? locale2 ?? "en-US",
+    project: { id: project2.id, name: project2.name },
+    pinnedVersion: project2.pinnedVersion,
+    // echoed for transparency; the render uses the record's saved look
+    shots,
+    // [{ frameName, matched }] — which of the project's shots got developer bytes
+    ...handoffUsed.length > 0 ? { handoffUsed } : {},
+    // shots resolved from the designer's uploads
+    ...missing.length > 0 ? { missing } : {},
+    ...notes.length > 0 ? { note: notes.join(" ") } : {},
+    panels
+  });
+}
 async function handleSaveLook(deps2, args) {
   const project2 = await deps2.resolveProject(deps2.userId, args.project);
   if (!project2) {
@@ -888,10 +1570,12 @@ async function handleRequestScreenshotUpload(deps2, args) {
   } catch (err) {
     return errorResult(err.message);
   }
+  const locale2 = args.locale?.trim() || void 0;
   return textResult({
     ok: true,
     slots,
-    instructions: 'PUT each screenshot\'s raw PNG bytes to its uploadUrl, e.g.: curl -T screenshot.png "<uploadUrl>" \u2014 then pass { "ref": "<the matching ref>" } as that screenshot\'s entry in render_strip/emit_bundle\'s `screenshots` array. If you passed `names`, that ref already carries its filename \u2014 no need to also set `name` on the screenshot entry. Uploads are not auto-purged yet \u2014 treat refs as short-lived and single-use.'
+    ...locale2 ? { locale: locale2 } : {},
+    instructions: 'PUT each screenshot\'s raw PNG bytes to its uploadUrl, e.g.: curl -T screenshot.png "<uploadUrl>" \u2014 then pass { "ref": "<the matching ref>" } as that screenshot\'s entry in render_strip/emit_bundle\'s `screenshots` array. If you passed `names`, that ref already carries its filename \u2014 no need to also set `name` on the screenshot entry. Uploads are not auto-purged yet \u2014 treat refs as short-lived and single-use.' + (locale2 ? ` These slots are tagged for ${locale2}: place each ref under that key of a per-locale screenshot entry, e.g. { "locales": { "${locale2}": { "ref": "<ref>" } } }.` : "")
   });
 }
 var SERVER_INSTRUCTIONS = [
@@ -910,6 +1594,13 @@ var SERVER_INSTRUCTIONS = [
   "3. emit_bundle({ screenshots|panels, bundleId }) \u2014 a fastlane deliver-ready zip. Pass a prior",
   '   render_strip output:"urls" result as `panels` to package without re-rendering.',
   "",
+  "## Input hygiene \u2014 feed RAW app screenshots, never already-composed panels",
+  "render_strip expects RAW in-app screen captures (no device frame, no caption). Do NOT feed it a",
+  "previously-rendered Storeframe panel, an exported fastlane image, or any screenshot that already",
+  "has a phone frame or caption baked in \u2014 it double-frames (a phone inside a phone). If a folder",
+  "holds both raw captures and finished panels, use the raw ones. Rule of thumb: if it already",
+  "looks like an App Store screenshot, it is the WRONG input.",
+  "",
   "## Big jobs: render, THEN bundle (do NOT render+zip in one call for 4+ panels)",
   "A full-resolution render is seconds PER PANEL and runs one panel at a time, so a 5-panel",
   "full-res render can take a couple of minutes \u2014 long enough that a single render+zip call",
@@ -920,32 +1611,63 @@ var SERVER_INSTRUCTIONS = [
   "(near-instant, no re-render). Preview (preview:true) is always fast and safe for iteration \u2014",
   "only the FINAL full-res pass is the slow one, so split that one.",
   "",
+  "## Per-locale screenshots \u2192 ONE multi-locale bundle",
+  'A screenshot entry can carry per-locale variants: { "locales": { "en-US": { "ref": "\u2026" },',
+  '"de-DE": { "ref": "\u2026" } } }. render_strip picks the top-level `locale`\'s variant; a locale',
+  "with no variant of its own falls back to the en-US one (ship German captions over English",
+  'screens now, upgrade the pixels later). emit_bundle({ locales: ["en-US","de-DE"], \u2026 }) emits',
+  "ONE zip with a fastlane/screenshots/<locale>/ folder per locale \u2014 fastlane deliver uploads",
+  "every locale in a single run. request_screenshot_upload({ count, names, locale }) tags a",
+  "batch of upload slots with the locale it is for (echoed back; bookkeeping only).",
+  "RECOMMENDED multi-locale flow \u2014 render per locale, then compose ONCE (this is also the only",
+  "way to get per-locale CAPTION text into one bundle, since caption text is per-render input):",
+  `1. per locale L: render_strip({ locale: L, output: "urls", style: { captions: [<L's words>] },`,
+  `   screenshots: [<L's screens or { "locales": \u2026 } entries>] }) \u2192 per-panel refs for L.`,
+  '2. emit_bundle({ locales: [...], bundleId, panels: [ { "locales": { "en-US": { "ref": p1en },',
+  '   "de-DE": { "ref": p1de } } }, \u2026 ] }) \u2014 zips every locale with NO re-render, near-instant.',
+  "The one-call form (emit_bundle with `screenshots` + `locales`) works but renders once PER",
+  "locale with the SAME captions for every locale \u2014 and multiplies the slow full-res render by",
+  "the locale count (see Big jobs above), so prefer the compose flow for real jobs.",
+  "",
   "## Styling \u2014 you can fully art-direct the strip via the `style` object",
   "Call describe_look for the exact field catalog + defaults; this is the map of what to reach for.",
   "Three groups (all optional \u2014 omit for a sensible dark default):",
   "- style.shotLook (the device, same for every phone): angle (front|left|right), material",
   "  (real|clay), colorway (orange|blue|silver|custom+customColor), finish (0 matte\u20261 glossy),",
-  "  roll (-45\u202645\xB0 tilt), phoneHeight (20\u2026100 % of panel), hOffset/vOffset to nudge position,",
-  "  glare, reflections, lighting, flatScreen.",
+  "  clearcoat (0\u20261 glossy clear-coat lacquer, on top of finish), roll (-45\u202645\xB0 tilt),",
+  "  phoneHeight (20\u2026100 % of panel), hOffset/vOffset to nudge position, glare, reflections,",
+  "  lighting, flatScreen.",
   "- style.background (the strip): mode gradient|perPanel; gradientFrom/gradientTo (hex),",
-  "  gradientDir vertical|horizontal, shadow; or panelColors[] (one hex per slot) for perPanel.",
-  "- style.captions[] (ONE entry per panel, in slot order; null = no caption): text (headline),",
-  "  subtitle, fontId (inter|manrope|poppins|fraunces|space-grotesk), sizePt, color (hex),",
-  "  align, anchor {x,y} (0\u20131 position), maxWidth (0\u20131 fraction of panel width).",
+  "  gradientDir vertical|horizontal, shadow, floorReflection; or panelColors[] (one hex per slot) for perPanel.",
+  "- style.captions[] (ONE entry per panel, in slot order; null = no caption). An entry is EITHER a",
+  "  single caption object OR an array of layers stacked on that panel: [{text,\u2026},{text,\u2026}]. Fields:",
+  "  text (this layer\u2019s words), subtitle (single-caption shape only \u2014 in the array shape add another",
+  "  layer instead), fontId (inter|manrope|poppins|fraunces|space-grotesk), sizePt, color (hex),",
+  "  align, anchor {x,y} (0\u20131 position; OMIT to auto-place above the device), maxWidth (0\u20131 fraction).",
   "panelPresetId picks the App Store size: r69 (6.9\u2033, default, 1290\xD72796) | r65 | r55 | ipad13 |",
   "ipad129. Match it to the pixel size of your source screenshots (1320\xD72868 or 1290\xD72796 \u2192 r69).",
+  "Per-panel variety (a DIFFERENT device per panel \u2014 mixed-device or continuous-scene strips):",
+  "style.shotLook is ONE device for the WHOLE strip. To style each panel differently, pass a `look`",
+  "instead of style \u2014 a look carries `shots[]`, ONE entry per panel in slot order, each with its own",
+  '`look` (same fields as shotLook). e.g. look:{ shots:[ {panelId:"panel-1",look:{angle:"left"}},',
+  '{panelId:"panel-2",look:{angle:"front",colorway:"orange"}} ] } tilts panel 1 and recolours panel 2',
+  "in one render_strip call. This is the exact shape read_look/save_look use; describe_look details it.",
+  "Continuous scene: panels have no hard divider \u2014 a phone pushed past its panel edge with a large",
+  "hOffset overflows into the NEIGHBOURING panel, so one device (or a multi-phone fan) can span",
+  "several panels and the strip reads as one swipe-through image. Deliberate \u2014 preview to place it.",
   "",
-  "## Caption guardrails (do this or captions crowd \u2014 the #1 first-render mistake)",
-  'Defaults are fontId "inter", sizePt 44, anchor {x:0.5, y:0.06} (near the top), maxWidth 0.86.',
-  "At 44pt a headline longer than ~15\u201318 characters WRAPS to two lines, and with a subtitle the",
-  "two then collide at the top of the panel. To keep it clean:",
-  "- Keep headlines SHORT (aim \u2264 ~18 chars) so they stay one line; or drop sizePt to ~36\u201340 if",
-  "  they must be longer; or raise maxWidth toward 1.0 to reduce wrapping.",
-  "- If you use a subtitle, give the block room: lower the phone a little (shotLook.phoneHeight",
-  "  ~64\u201368) and/or set the caption anchor slightly higher (anchor.y ~0.04). Preview and LOOK at",
-  "  the result before finalizing \u2014 a crowded headline+subtitle is the most common bad first pass.",
-  '- Punchy, benefit-led headlines read best ("Track every throw", "See your stats"), one idea',
-  "  per panel. A consistent fontId + color across all panels makes the strip feel designed.",
+  "## Caption guardrails (do this or captions crowd)",
+  'Defaults are fontId "inter", sizePt 44, maxWidth 0.86, and NO anchor (auto). By default a caption',
+  "AUTO-LAYOUTS in a band above the device and the phone is pushed down so the two never collide \u2014",
+  "even a headline that wraps to two lines, or several stacked layers, clears the phone automatically.",
+  "So you rarely need to set anchor at all. To keep it reading well:",
+  '- Punchy, benefit-led headlines read best ("Track every throw", "See your stats"), one idea per',
+  "  panel. A consistent fontId + color across all panels makes the strip feel designed.",
+  "- Want a headline + a smaller subline? Pass an ARRAY of layers for that panel \u2014 the first larger,",
+  "  the second smaller (lower sizePt) \u2014 instead of one caption; they stack in order in the band.",
+  "- Keep headlines fairly short; or drop sizePt to ~36\u201340, or raise maxWidth toward 1.0, to reduce",
+  "  wrapping if a line looks too tight. Setting anchor {x,y} OVERRIDES auto-layout \u2014 the caption is",
+  "  then pinned exactly there (it will not dodge the phone), so only set it when you want that.",
   "",
   "## Two kinds of state, kept separate on purpose",
   "- STYLING (the look \u2014 device, background, caption styling) is reusable: save_look persists it",
@@ -988,6 +1710,27 @@ var SERVER_INSTRUCTIONS = [
   "Skip the names and the record falls back to positional filenames (screen-1.png, screen-2.png\u2026)",
   "the user's folder can't match \u2014 the single worst create-project failure mode. Pass the real filenames.",
   "",
+  '## "Any updates?" \u2014 read back what a designer changed (read_project)',
+  "read_look returns only STYLING. To see what a designer edited in the web app \u2014 frame ORDER, the",
+  "per-locale caption WORDS, the locale list, structural changes \u2014 call read_project. It returns the",
+  "full project as `project_file` (an opaque ProjectFile: `panels` in the designer's order,",
+  "`captionText` keyed by locale then panel, `locales`, plus the styling) together with `updatedAt`.",
+  'To answer a recurring "any updates?": remember the `updatedAt` you last saw and compare on the next',
+  "read_project \u2014 a newer value means the designer changed something; re-read project_file to see what.",
+  "read_project is read-only and never returns screenshots (zero-custody). To reproduce the designer's",
+  "exact strip, feed the project to render_project with YOUR OWN raw screenshots (matched by filename).",
+  "",
+  "## Reproduce a saved project (render_project)",
+  "render_project({ project?, screenshots }) re-renders a SAVED project with YOUR OWN raw screenshots \u2014",
+  "the headless twin of opening the project in the web app and re-loading the raws. The PROJECT owns the",
+  "structure (frame order, per-locale captions, styling); you just supply the pixels. Pass `screenshots`",
+  "as a FLAT list of entries (base64 / { ref } / { url }), EACH with its original filename as `name` \u2014",
+  "they are matched to the project's shots BY filename, so the ORDER you pass them in does not matter and",
+  "you must NOT pre-sort. Pass `locale` to render that locale's caption words (the project already holds",
+  "them). A shot with no matching file renders without its device and is listed in the result's `shots`",
+  "/`missing` report \u2014 supply that filename to complete the strip. Typical flow: read_project to see what",
+  "the designer changed, then render_project passing your raws by their real filenames.",
+  "",
   "## Refine visually, then re-render headlessly",
   "A human can refine the look in Storeframe Studio (https://storeframe-studio.vercel.app \u2014 sign",
   "in as the SAME account) and Save look; read_look then returns exactly that, so an agent",
@@ -999,7 +1742,7 @@ function registerTools(server2, deps2) {
     "render_strip",
     {
       title: "Render App Store strip",
-      description: "Turn app screenshots into styled 3D device mockups laid out as an App Store screenshot strip, and return the finished per-panel PNGs. Optionally style with a saved look, render a cheap low-res `preview`, and get results `inline` or as `urls` for large payloads. For real, full-resolution screenshots, call request_screenshot_upload first \u2014 inline base64 is for small payloads only. No store credential is involved \u2014 this only renders images.",
+      description: 'Turn app screenshots into styled 3D device mockups laid out as an App Store screenshot strip, and return the finished per-panel PNGs. Optionally style with a saved look, render a cheap low-res `preview`, and get results `inline` or as `urls` for large payloads. Screenshots can vary per App Store locale via { "locales": \u2026 } entries \u2014 `locale` picks which variant renders (missing variants fall back to en-US). For real, full-resolution screenshots, call request_screenshot_upload first \u2014 inline base64 is for small payloads only. No store credential is involved \u2014 this only renders images.',
       inputSchema: renderStripShape
     },
     (args) => handleRenderStrip(deps2, args)
@@ -1008,7 +1751,7 @@ function registerTools(server2, deps2) {
     "emit_bundle",
     {
       title: "Emit fastlane bundle",
-      description: 'Render the strip (or package pre-rendered `panels` refs from a prior render_strip `output: "urls"` call, without re-rendering), then package it as a `fastlane deliver`-ready zip (screenshots + a pre-filled, never-submitting Deliverfile + a README). Returns the zip `inline` or as a `url` for large payloads, and can also mint a 14-day share link to a landing page. YOU upload it with your own fastlane \u2014 this server never touches a store credential and never submits for review.',
+      description: 'Render the strip (or package pre-rendered `panels` refs from a prior render_strip `output: "urls"` call, without re-rendering), then package it as a `fastlane deliver`-ready zip (screenshots + a pre-filled, never-submitting Deliverfile + a README). Pass `locales: [...]` for ONE multi-locale bundle \u2014 a fastlane/screenshots/<locale>/ folder per locale, best combined with per-locale { "locales": \u2026 } screenshot/panel entries. Returns the zip `inline` or as a `url` for large payloads, and can also mint a 14-day share link to a landing page. YOU upload it with your own fastlane \u2014 this server never touches a store credential and never submits for review.',
       inputSchema: emitBundleShape
     },
     (args) => handleEmitBundle(deps2, args)
@@ -1031,6 +1774,24 @@ function registerTools(server2, deps2) {
     },
     (args) => handleReadLook(deps2, args)
   );
+  server2.registerTool(
+    "read_project",
+    {
+      title: "Read full project",
+      description: "Return a project's FULL current state \u2014 the designer's frame order (panels), per-locale caption words (captionText), locale list, and styling \u2014 as an opaque ProjectFile, NOT just the look. Use it to answer \"what did the designer change?\": remember the returned `updatedAt` and re-read later; a newer value means the strip was edited. Read-only, no store credential. To re-render this project with your own screenshots, pass it to render_project.",
+      inputSchema: readProjectShape
+    },
+    (args) => handleReadProject(deps2, args)
+  );
+  server2.registerTool(
+    "render_project",
+    {
+      title: "Render a saved project",
+      description: "Re-render a SAVED Storeframe project with your OWN raw screenshots \u2014 the headless twin of opening the project in the web app and re-loading the raws. Pass the developer's screenshots as a FLAT list (each with its original filename as `name`); they are matched to the project's shots BY filename, so ORDER does not matter and you never pre-sort. The project supplies the structure \u2014 frame order, per-locale caption words (pick one with `locale`), styling \u2014 so the result reproduces the designer's exact strip. Shots with no matching file are reported as missing (not an error). Returns per-panel PNGs (`inline` or `urls`). No store credential.",
+      inputSchema: renderProjectShape
+    },
+    (args) => handleRenderProject(deps2, args)
+  );
   server2.registerTool(
     "save_look",
     {
@@ -1053,7 +1814,7 @@ function registerTools(server2, deps2) {
     "request_screenshot_upload",
     {
       title: "Request screenshot upload slots",
-      description: "Mint signed upload URLs so real screenshots' bytes never transit this conversation's context \u2014 PUT bytes directly to the returned URLs, then pass the returned `ref`s into render_strip/emit_bundle. Use this instead of inline base64 for real (full-resolution) screenshots.",
+      description: "Mint signed upload URLs so real screenshots' bytes never transit this conversation's context \u2014 PUT bytes directly to the returned URLs, then pass the returned `ref`s into render_strip/emit_bundle. Use this instead of inline base64 for real (full-resolution) screenshots. Uploading one batch per App Store locale? Tag each batch with `locale` (echoed back for your bookkeeping).",
       inputSchema: requestScreenshotUploadShape
     },
     (args) => handleRequestScreenshotUpload(deps2, args)
@@ -1079,119 +1840,13 @@ import { chromium } from "playwright";
 import { createServer as createServer2 } from "vite";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
-// ../mockup-engine/appstore.ts
-var DEFAULT_LOOK = {
-  angle: "front",
-  cameraPos: null,
-  roll: "0",
-  phoneHeight: "72",
-  hOffset: "0",
-  vOffset: "0",
-  material: "real",
-  colorway: "silver",
-  customColor: "F5F5F5",
-  finish: "0",
-  clayTone: "grey",
-  clayCustom: "B0B0B0",
-  flatScreen: false,
-  glare: false,
-  lighting: true,
-  reflections: false
-};
-var DEFAULT_CAPTION_STYLE2 = {
-  fontId: "inter",
-  sizePt: 44,
-  color: "FFFFFF",
-  align: "center",
-  anchor: { x: 0.5, y: 0.06 },
-  maxWidth: 0.86
-};
-var DEFAULT_LOCALE = "en-US";
-function normalizeCaptionStyles(raw) {
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
-  const out = {};
-  for (const [panelId, entry] of Object.entries(raw)) {
-    if (!entry || typeof entry !== "object") continue;
-    const e = entry;
-    out[panelId] = {
-      ...DEFAULT_CAPTION_STYLE2,
-      ...e,
-      anchor: { ...DEFAULT_CAPTION_STYLE2.anchor, ...e.anchor && typeof e.anchor === "object" ? e.anchor : {} }
-    };
-  }
-  return out;
-}
-function normalizeFlatCaptionMap(raw) {
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
-  const out = {};
-  for (const [panelId, entry] of Object.entries(raw)) {
-    if (!entry || typeof entry !== "object") continue;
-    const e = entry;
-    if (typeof e.headline !== "string") continue;
-    out[panelId] = { headline: e.headline, ...typeof e.subtitle === "string" ? { subtitle: e.subtitle } : {} };
-  }
-  return out;
-}
-function normalizeCaptionText(raw) {
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
-  const entries = Object.entries(raw);
-  const looksFlat = entries.some(
-    ([, value]) => !!value && typeof value === "object" && typeof value.headline === "string"
-  );
-  if (looksFlat) return { [DEFAULT_LOCALE]: normalizeFlatCaptionMap(raw) };
-  const out = {};
-  for (const [locale2, inner] of entries) out[locale2] = normalizeFlatCaptionMap(inner);
-  return out;
-}
-function shotsInPanelOrder(shots, panels) {
-  return panels.flatMap((panel) => shots.filter((s) => s.panelId === panel.id));
-}
-var PROJECT_SCHEMA_VERSION = 2;
-function serializeProject(state) {
-  const ordered = shotsInPanelOrder(state.shots, state.panels);
-  const shots = ordered.map((s) => ({
-    id: s.id,
-    panelId: s.panelId,
-    frameNodeId: s.frameNodeId,
-    frameName: s.frameName,
-    look: s.look,
-    inputAnchor: s.inputAnchor,
-    // v2 provenance — persisted so drift survives reload
-    outputAnchor: s.outputAnchor
-  }));
-  return {
-    schema: PROJECT_SCHEMA_VERSION,
-    shots,
-    panels: state.panels,
-    selectedShotId: state.selectedShotId,
-    // Caption TEXT is content (C1): emitted here on the project record, deliberately NOT
-    // via extractStripStyle — so it can never leak into serializeLook's styling blob.
-    // normalizeCaptionText upgrades the flat v1 input to the locale-nested stored shape
-    // (flat → { [DEFAULT_LOCALE]: … }); a Phase-3 nested input passes through unchanged.
-    captionText: normalizeCaptionText(state.captionText),
-    ...extractStripStyle(state)
-  };
-}
-function extractStripStyle(state) {
-  return {
-    panelPresetId: state.panelPresetId,
-    bgMode: state.bgMode,
-    gradientFrom: state.gradientFrom,
-    gradientTo: state.gradientTo,
-    gradientDir: state.gradientDir,
-    panelColors: state.panelColors,
-    shadow: state.shadow,
-    captionStyles: state.captionStyles ?? {}
-  };
-}
-
 // ../mockup-engine/stripFromSlots.ts
 var FALLBACK_GRADIENT_FROM = "#1b1b2e";
 var FALLBACK_GRADIENT_TO = "#0a0a14";
 function staggeredHOffset(k) {
   return String(Math.max(-100, Math.min(100, k * 35)));
 }
-var NUMERIC_STRING_FIELDS = ["roll", "phoneHeight", "hOffset", "vOffset", "finish"];
+var NUMERIC_STRING_FIELDS = ["roll", "phoneHeight", "hOffset", "vOffset", "finish", "clearcoat"];
 function coerceShotLook(raw) {
   if (!raw || typeof raw !== "object") return {};
   const out = { ...raw };
@@ -1200,6 +1855,14 @@ function coerceShotLook(raw) {
   }
   return out;
 }
+function coerceCaptionLayer(el) {
+  const { subtitle: _subtitle, sizePt, maxWidth, ...rest } = el;
+  return {
+    ...rest,
+    ...sizePt !== void 0 ? { sizePt: Number(sizePt) } : {},
+    ...maxWidth !== void 0 ? { maxWidth: Number(maxWidth) } : {}
+  };
+}
 function remapByOrdinal(record, sourceOrder, targetIds) {
   const out = {};
   if (!record) return out;
@@ -1212,7 +1875,7 @@ function remapByOrdinal(record, sourceOrder, targetIds) {
 function stripFromSlots(input) {
   const slotSizes = input.slotSizes.filter((n) => Number.isInteger(n) && n > 0);
   const panelIds = slotSizes.map((_, i) => `panel-${i + 1}`);
-  const captionText = {};
+  let captionLayers = {};
   const opaque = !input.style && input.look && typeof input.look === "object" ? input.look : null;
   const style2 = input.style ?? null;
   const opaqueShots = opaque && Array.isArray(opaque.shots) ? opaque.shots : [];
@@ -1229,11 +1892,13 @@ function stripFromSlots(input) {
   });
   let panelColors = {};
   let captionStyles = {};
+  let panelBackgrounds = {};
   let bgMode = "gradient";
   let gradientFrom = FALLBACK_GRADIENT_FROM;
   let gradientTo = FALLBACK_GRADIENT_TO;
   let gradientDir = "vertical";
   let shadow = true;
+  let floorReflection = false;
   if (style2) {
     const bg = style2.background ?? {};
     bgMode = bg.mode === "perPanel" ? "perPanel" : "gradient";
@@ -1241,6 +1906,7 @@ function stripFromSlots(input) {
     if (typeof bg.gradientTo === "string") gradientTo = bg.gradientTo;
     if (bg.gradientDir === "horizontal") gradientDir = "horizontal";
     if (bg.shadow === false) shadow = false;
+    if (bg.floorReflection === true) floorReflection = true;
     if (Array.isArray(bg.panelColors)) {
       bg.panelColors.forEach((color, i) => {
         if (typeof color === "string" && color && panelIds[i] !== void 0) panelColors[panelIds[i]] = color;
@@ -1248,22 +1914,28 @@ function stripFromSlots(input) {
     }
     if (Array.isArray(style2.captions)) {
       const rawStyles = {};
+      const inner = {};
       style2.captions.forEach((entry, i) => {
-        if (!entry || typeof entry !== "object" || panelIds[i] === void 0) return;
-        const { text, subtitle, sizePt, maxWidth, ...rest } = entry;
-        rawStyles[panelIds[i]] = {
-          ...rest,
-          ...sizePt !== void 0 ? { sizePt: Number(sizePt) } : {},
-          ...maxWidth !== void 0 ? { maxWidth: Number(maxWidth) } : {}
-        };
-        if (typeof text === "string" && text.trim()) {
-          captionText[panelIds[i]] = {
-            headline: text,
-            ...typeof subtitle === "string" && subtitle ? { subtitle } : {}
+        const panelId = panelIds[i];
+        if (panelId === void 0 || entry === null || entry === void 0) return;
+        if (Array.isArray(entry)) {
+          const layers = entry.filter((el) => !!el && typeof el === "object" && typeof el.text === "string" && el.text.trim() !== "").map(coerceCaptionLayer);
+          if (layers.length > 0) inner[panelId] = layers;
+        } else if (typeof entry === "object") {
+          const { text, subtitle, sizePt, maxWidth, ...rest } = entry;
+          rawStyles[panelId] = {
+            ...rest,
+            ...sizePt !== void 0 ? { sizePt: Number(sizePt) } : {},
+            ...maxWidth !== void 0 ? { maxWidth: Number(maxWidth) } : {}
           };
+          if (typeof text === "string" && text.trim()) {
+            inner[panelId] = { headline: text, ...typeof subtitle === "string" && subtitle ? { subtitle } : {} };
+          }
         }
       });
-      captionStyles = normalizeCaptionStyles(rawStyles);
+      const localeLayers = normalizeCaptionText({ [DEFAULT_LOCALE]: inner }, normalizeCaptionStyles(rawStyles));
+      captionStyles = captionStylesFromLayers(localeLayers);
+      captionLayers = resolveCaptionText(localeLayers);
     }
   } else if (opaque) {
     bgMode = opaque.bgMode === "perPanel" ? "perPanel" : "gradient";
@@ -1271,19 +1943,33 @@ function stripFromSlots(input) {
     if (typeof opaque.gradientTo === "string") gradientTo = opaque.gradientTo;
     if (opaque.gradientDir === "horizontal") gradientDir = "horizontal";
     if (opaque.shadow === false) shadow = false;
+    if (opaque.floorReflection === true) floorReflection = true;
     const sourceOrder = [];
     for (const s of opaqueShots) {
       const id = typeof s?.panelId === "string" ? s.panelId : null;
       if (id && !sourceOrder.includes(id)) sourceOrder.push(id);
     }
     panelColors = remapByOrdinal(opaque.panelColors, sourceOrder, panelIds);
-    captionStyles = remapByOrdinal(normalizeCaptionStyles(opaque.captionStyles), sourceOrder, panelIds);
+    captionStyles = remapByOrdinal(normalizeCaptionLayerStyles(opaque.captionStyles), sourceOrder, panelIds);
+    panelBackgrounds = remapByOrdinal(normalizePanelBackgrounds(opaque.panelBackgrounds), sourceOrder, panelIds);
   }
   const panelPresetId2 = input.panelPresetId ?? (typeof opaque?.panelPresetId === "string" ? opaque.panelPresetId : void 0) ?? "r69";
   return {
-    look: { panelPresetId: panelPresetId2, bgMode, gradientFrom, gradientTo, gradientDir, panelColors, shadow, captionStyles, shots },
+    look: {
+      panelPresetId: panelPresetId2,
+      bgMode,
+      gradientFrom,
+      gradientTo,
+      gradientDir,
+      panelColors,
+      shadow,
+      floorReflection,
+      panelBackgrounds,
+      captionStyles,
+      shots
+    },
     panelIds,
-    captionText
+    captionText: captionLayers
   };
 }
 
@@ -1330,6 +2016,7 @@ function recordFromStrip(input) {
     gradientDir: look2.gradientDir,
     panelColors: look2.panelColors,
     shadow: look2.shadow,
+    panelBackgrounds: look2.panelBackgrounds,
     captionStyles: look2.captionStyles,
     // Nest this render's flat caption text under its locale (default en-US) so the stored blob
     // is locale-correct; serializeProject's normalizeCaptionText passes a nested map through.
@@ -1469,6 +2156,17 @@ var StripRenderer = class {
     }
     return result;
   }
+  // render_project: same page + boot handshake as render(); only the harness entry differs
+  // (window.renderProject restores the saved ProjectFile and joins bytes by frameName).
+  async renderProject(input) {
+    await this.boot();
+    if (!this.page) return { ok: false, error: "renderer failed to boot" };
+    const result = await this.page.evaluate((inp) => window.renderProject(inp), input);
+    if (this.sawContextLost) {
+      console.warn("[renderer] CONTEXT_LOST observed since boot");
+    }
+    return result;
+  }
   async close() {
     await this.page?.close().catch(() => {
     });
@@ -1490,6 +2188,57 @@ var StripRenderer = class {
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { dirname } from "node:path";
+
+// package.json
+var package_default = {
+  name: "storeframe-mcp",
+  version: "0.2.0",
+  private: false,
+  type: "module",
+  description: "The bundle-emitting MCP server over the @engine/@sync spine. Exposes render_strip, emit_bundle, read_look to agents (Claude Code / Cursor / CI) over Streamable HTTP, auth'd with personal Storeframe API tokens. Zero-custody: no code path accepts, stores, or forwards a store-signing credential \u2014 upload stays the user's own fastlane. Renders via headless Playwright Chromium, the engine's native non-browser habitat (same path as mockup-mcp). Also ships as a free LOCAL stdio server (`npx storeframe-mcp`) \u2014 same render, on your own machine, no account needed.",
+  license: "UNLICENSED",
+  bin: {
+    "storeframe-mcp": "./dist/local.js"
+  },
+  files: [
+    "dist",
+    "harness-dist",
+    "README.md"
+  ],
+  engines: {
+    node: ">=20.12"
+  },
+  scripts: {
+    dev: "tsx src/server.ts",
+    start: "tsx src/server.ts",
+    "build:harness": "vite build --config vite.harness.config.mjs",
+    "build:node": "node build.mjs",
+    build: "npm run build:harness && npm run build:node",
+    prepublishOnly: "npm run build",
+    typecheck: "tsc --noEmit"
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    express: "^5.2.1",
+    fflate: "^0.8.3",
+    playwright: "1.61.1",
+    vite: "^5.4.0",
+    zod: "^3.25.76"
+  },
+  devDependencies: {
+    "@types/express": "^5.0.6",
+    esbuild: "^0.28.1",
+    pixelmatch: "^7.2.0",
+    pngjs: "^7.0.0",
+    tsx: "^4.23.0",
+    typescript: "^5.6.0"
+  }
+};
+
+// src/version.ts
+var VERSION = package_default.version;
+
+// src/hostedBridge.ts
 var DEFAULT_HOSTED_MCP_URL = "https://storeframe-mcp.fly.dev/mcp";
 function hostedMcpUrl() {
   return (process.env.STOREFRAME_MCP_URL || DEFAULT_HOSTED_MCP_URL).replace(/\/+$/, "");
@@ -1527,7 +2276,7 @@ async function callSaveProject(client, ctx, extra) {
   return { id: res.projectId };
 }
 async function connectHostedBridge(token2) {
-  const client = new Client({ name: "storeframe-mcp-local-bridge", version: "0.1.0" }, { capabilities: {} });
+  const client = new Client({ name: "storeframe-mcp-local-bridge", version: VERSION }, { capabilities: {} });
   const transport = new StreamableHTTPClientTransport(new URL(hostedMcpUrl()), {
     requestInit: { headers: { Authorization: `Bearer ${token2}` } }
   });
@@ -1555,6 +2304,14 @@ async function connectHostedBridge(token2) {
         // known gap — see the module comment above.
       };
     },
+    async readProjectRecord(projectId) {
+      const res = await callRemoteTool(client, "read_project", { project: projectId });
+      if (!res.saved) return null;
+      return {
+        record: { project: res.project_file },
+        updatedAt: typeof res.updatedAt === "string" ? res.updatedAt : null
+      };
+    },
     async saveLook(projectId, look2, sourceName) {
       const res = await callRemoteTool(client, "save_look", {
         project: projectId,
@@ -1596,6 +2353,7 @@ function localToolDeps(token2) {
       ...base,
       resolveProject: async () => null,
       readLook: async () => null,
+      readProjectRecord: async () => null,
       saveLook: async () => {
         throw new Error(`Saving a look is ${SIGN_IN}`);
       },
@@ -1627,6 +2385,7 @@ function localToolDeps(token2) {
     ...base,
     resolveProject: async (userId, projectId) => (await bridge()).resolveProject(userId, projectId),
     readLook: async (projectId) => (await bridge()).readLook(projectId),
+    readProjectRecord: async (projectId) => (await bridge()).readProjectRecord(projectId),
     saveLook: async (projectId, look2, sourceName) => (await bridge()).saveLook(projectId, look2, sourceName),
     createProject: async (userId, name, record, ctx) => (await bridge()).createProject(userId, name, record, ctx),
     updateProjectRecord: async (projectId, record, ctx) => (await bridge()).updateProjectRecord(projectId, record, ctx),
@@ -1657,7 +2416,7 @@ Rendering runs on THIS machine \u2014 free, no timeout ceiling. A hosted token i
 ## Local mode (this connection)
 Rendering runs on THIS machine \u2014 free, no timeout ceiling. No hosted token is configured, so save_project / read_look / save_look / share links cleanly no-op ("sign in") \u2014 pass local files as { "path": "..." } screenshot entries and render_strip / emit_bundle work fully.`;
 var server = new McpServer(
-  { name: "storeframe-mcp-local", version: "0.1.0" },
+  { name: "storeframe-mcp-local", version: VERSION },
   { instructions: localInstructions }
 );
 registerTools(server, { userId: "local", ...deps });