shotops-mcp 0.5.0

package/dist/local.js

@@ -0,0 +1,3261 @@
+#!/usr/bin/env node
+
+// src/local.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// ../mockup-engine/appstore/devices.ts
+var IPHONE_MODEL_ID = "iphone-17-pro";
+var PIXEL_MODEL_ID = "pixel-10-pro";
+var DEVICES = [
+  { id: "iphone-6-9", label: "iPhone 6.9\u2033", panelPresetId: "r69", ascDeviceSet: "APP_IPHONE_67", modelId: IPHONE_MODEL_ID, screenFamily: "iphone" },
+  { id: "iphone-6-5", label: "iPhone 6.5\u2033", panelPresetId: "r65", ascDeviceSet: "APP_IPHONE_65", modelId: IPHONE_MODEL_ID, screenFamily: "iphone" },
+  { id: "pixel-10-pro", label: "Pixel 10 Pro", panelPresetId: "pixel69", ascDeviceSet: "ANDROID_PHONE", modelId: PIXEL_MODEL_ID, screenFamily: "android" },
+  { id: "ipad-13", label: "iPad 13\u2033", panelPresetId: "ipad13", ascDeviceSet: "APP_IPAD_PRO_129", modelId: "ipad-pro", screenFamily: "ipad", comingSoon: true },
+  { id: "ipad-12-9", label: "iPad 12.9\u2033", panelPresetId: "ipad129", ascDeviceSet: "APP_IPAD_PRO_3GEN_129", modelId: "ipad-pro", screenFamily: "ipad", comingSoon: true }
+];
+var DEFAULT_OUTPUT_DEVICE_ID = "iphone-6-9";
+function deviceById(id) {
+  return DEVICES.find((d) => d.id === id);
+}
+function selectableDevices() {
+  return DEVICES.filter((d) => !d.comingSoon);
+}
+function deriveOutputs(explicit, panelPresetId2) {
+  if (Array.isArray(explicit)) {
+    const seen = /* @__PURE__ */ new Set();
+    const cleaned = [];
+    for (const id of explicit) {
+      const d = deviceById(id);
+      if (d && !d.comingSoon && !seen.has(id)) {
+        seen.add(id);
+        cleaned.push(id);
+      }
+    }
+    if (cleaned.length > 0) return cleaned;
+  }
+  if (panelPresetId2) {
+    const byPreset = selectableDevices().find((d) => d.panelPresetId === panelPresetId2);
+    if (byPreset) return [byPreset.id];
+  }
+  return [DEFAULT_OUTPUT_DEVICE_ID];
+}
+var BASE_SCREEN_FAMILY = deviceById(DEFAULT_OUTPUT_DEVICE_ID)?.screenFamily ?? "iphone";
+
+// ../mockup-engine/appstore/shotLook.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
+};
+
+// ../mockup-engine/appstore/panel.ts
+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;
+}
+
+// ../mockup-engine/appstore/captionModel.ts
+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, baseLocale = DEFAULT_LOCALE) {
+  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 { [baseLocale]: innerToLayers(raw) };
+  const out = {};
+  for (const [locale2, inner] of entries) out[locale2] = innerToLayers(inner);
+  return out;
+}
+function resolveCaptionText(captionText, locale2, baseLocale = DEFAULT_LOCALE) {
+  return captionText[locale2 ?? baseLocale] ?? captionText[baseLocale] ?? {};
+}
+function captionStylesFromLayers(captionText, baseLocale = DEFAULT_LOCALE) {
+  const out = {};
+  const locales = Object.keys(captionText);
+  const ordered = locales.includes(baseLocale) ? [baseLocale, ...locales.filter((l) => l !== baseLocale)] : 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;
+}
+
+// ../mockup-engine/appstore/localeAxis.ts
+function deriveLocales(captionText, explicit, baseLocale = DEFAULT_LOCALE) {
+  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.includes(baseLocale) ? cleaned : [...cleaned, baseLocale];
+  }
+  return dedupe([baseLocale, ...Object.keys(captionText)]);
+}
+function normalizeBaseLocale(raw, fallback = DEFAULT_LOCALE) {
+  return typeof raw === "string" && raw.length > 0 ? raw : fallback;
+}
+
+// ../mockup-engine/appstore/outputCaptions.ts
+function normalizeOutputCaptionText(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const out = {};
+  for (const [family, perLocaleRaw] of Object.entries(raw)) {
+    if (family === BASE_SCREEN_FAMILY) continue;
+    if (!perLocaleRaw || typeof perLocaleRaw !== "object" || Array.isArray(perLocaleRaw)) continue;
+    const perLocale = {};
+    for (const [locale2, byPanelRaw] of Object.entries(perLocaleRaw)) {
+      if (!byPanelRaw || typeof byPanelRaw !== "object" || Array.isArray(byPanelRaw)) continue;
+      const byPanel = {};
+      for (const [panelId, words] of Object.entries(byPanelRaw)) {
+        if (Array.isArray(words) && words.every((w) => typeof w === "string")) {
+          byPanel[panelId] = words;
+        }
+      }
+      if (Object.keys(byPanel).length > 0) perLocale[locale2] = byPanel;
+    }
+    if (Object.keys(perLocale).length > 0) out[family] = perLocale;
+  }
+  return out;
+}
+
+// ../mockup-engine/appstore/localeVariants.ts
+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, baseLocale = DEFAULT_LOCALE) {
+  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 ?? baseLocale] ?? variants[baseLocale] ?? variants[declared[0]];
+}
+function resolveLocaleVariantSlots(slots, locale2, baseLocale = DEFAULT_LOCALE) {
+  return slots.map((slot2) => slot2.map((entry) => resolveLocaleVariant(entry, locale2, baseLocale)));
+}
+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;
+}
+
+// ../mockup-engine/appstore/shot.ts
+function shotsInPanelOrder(shots, panels) {
+  return panels.flatMap((panel) => shots.filter((s) => s.panelId === panel.id));
+}
+
+// ../mockup-engine/appstore/serialize.ts
+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) }
+  };
+}
+
+// ../mockup-engine/appstore/project.ts
+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 baseLocale = normalizeBaseLocale(state.baseLocale);
+  const captionText = normalizeCaptionText(state.captionText, state.captionStyles, baseLocale);
+  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, baseLocale),
+    // #94 — the caption inheritance base. Content side (structure), never via extractStripStyle.
+    baseLocale,
+    // The OUTPUT device list is structure too — placed here (not the extractStripStyle spread) so a
+    // device selection never leaks into a Look (invariant 3). Always non-empty; migrates from
+    // panelPresetId when the editor state predates the axis.
+    outputs: deriveOutputs(state.outputs, state.panelPresetId),
+    // #88 — per-Output caption WORDS. Content, like captionText: emitted here on the record, NEVER via
+    // extractStripStyle (invariant 2/3). Normalized so a malformed/base-family key can't ride through.
+    // {} drops to an empty object (a pre-#88 project stays effectively unchanged).
+    outputCaptions: normalizeOutputCaptionText(state.outputCaptions),
+    ...extractStripStyle(state, captionText)
+  };
+}
+
+// ../mockup-engine/appstore/lookDivergence.ts
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null || typeof a !== "object") return false;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((v, i) => deepEqual(v, b[i]));
+  }
+  const ao = a;
+  const bo = b;
+  const ak = Object.keys(ao);
+  const bk = Object.keys(bo);
+  if (ak.length !== bk.length) return false;
+  return ak.every((k) => Object.prototype.hasOwnProperty.call(bo, k) && deepEqual(ao[k], bo[k]));
+}
+function byPanelOrdinal(look2, record) {
+  const ordinalOf = /* @__PURE__ */ new Map();
+  for (const s of look2.shots) {
+    if (!ordinalOf.has(s.panelId)) ordinalOf.set(s.panelId, ordinalOf.size);
+  }
+  const out = {};
+  for (const [panelId, value] of Object.entries(record ?? {})) {
+    const ord = ordinalOf.get(panelId);
+    if (ord !== void 0) out[ord] = value;
+  }
+  return out;
+}
+function panelColorsByOrdinal(look2) {
+  return byPanelOrdinal(look2, look2.panelColors);
+}
+function captionStylesByOrdinal(look2) {
+  return byPanelOrdinal(look2, look2.captionStyles);
+}
+function panelBackgroundsByOrdinal(look2) {
+  return byPanelOrdinal(look2, look2.panelBackgrounds);
+}
+function looksMatch(a, b) {
+  if (a.bgMode !== b.bgMode) return false;
+  if (a.panelPresetId !== b.panelPresetId) return false;
+  if (a.gradientFrom !== b.gradientFrom) return false;
+  if (a.gradientTo !== b.gradientTo) return false;
+  if (a.gradientDir !== b.gradientDir) return false;
+  if (a.shadow !== b.shadow) return false;
+  if (!!a.floorReflection !== !!b.floorReflection) return false;
+  if (a.shots.length !== b.shots.length) return false;
+  if (!a.shots.every((s, i) => deepEqual({ ...DEFAULT_LOOK, ...s.look }, { ...DEFAULT_LOOK, ...b.shots[i].look })))
+    return false;
+  if (!deepEqual(captionStylesByOrdinal(a), captionStylesByOrdinal(b))) return false;
+  if (!deepEqual(panelBackgroundsByOrdinal(a), panelBackgroundsByOrdinal(b))) return false;
+  return deepEqual(panelColorsByOrdinal(a), panelColorsByOrdinal(b));
+}
+
+// src/screenshotInput.ts
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+
+// src/uploads.ts
+import { randomBytes } from "node:crypto";
+
+// ../api/_lib/shareStorage.ts
+var BUCKET = "share-bundles";
+function storageBase() {
+  const base = (process.env.SUPABASE_URL ?? "").replace(/\/+$/, "");
+  if (!base) throw new Error("SUPABASE_URL not set");
+  return `${base}/storage/v1`;
+}
+function serviceHeaders(extra = {}) {
+  const key = process.env.SUPABASE_SERVICE_ROLE_KEY;
+  if (!key) throw new Error("SUPABASE_SERVICE_ROLE_KEY not set");
+  return { apikey: key, Authorization: `Bearer ${key}`, ...extra };
+}
+async function createSignedUploadUrl(path) {
+  const res = await fetch(`${storageBase()}/object/upload/sign/${BUCKET}/${path}`, {
+    method: "POST",
+    headers: serviceHeaders({ "Content-Type": "application/json" }),
+    body: JSON.stringify({})
+  });
+  if (!res.ok) {
+    throw new Error(`storage sign-upload ${res.status}: ${(await res.text().catch(() => "")).slice(0, 200)}`);
+  }
+  const data = await res.json();
+  if (!data.url) throw new Error("storage sign-upload: no url in response");
+  return { uploadUrl: `${storageBase()}${data.url}` };
+}
+async function createSignedDownloadUrl(path, expiresInSeconds) {
+  const res = await fetch(`${storageBase()}/object/sign/${BUCKET}/${path}`, {
+    method: "POST",
+    headers: serviceHeaders({ "Content-Type": "application/json" }),
+    body: JSON.stringify({ expiresIn: expiresInSeconds })
+  });
+  if (!res.ok) {
+    throw new Error(`storage sign-download ${res.status}: ${(await res.text().catch(() => "")).slice(0, 200)}`);
+  }
+  const data = await res.json();
+  if (!data.signedURL) throw new Error("storage sign-download: no signedURL in response");
+  return `${storageBase()}${data.signedURL}`;
+}
+async function putBytes(uploadUrl, bytes, contentType) {
+  const res = await fetch(uploadUrl, {
+    method: "PUT",
+    headers: { "content-type": contentType },
+    // A fresh ArrayBuffer copy — undici rejects a Uint8Array view whose buffer it can't own.
+    body: bytes.slice()
+  });
+  if (!res.ok) {
+    throw new Error(`storage PUT ${res.status}: ${(await res.text().catch(() => "")).slice(0, 200)}`);
+  }
+}
+async function downloadObject(path) {
+  const res = await fetch(`${storageBase()}/object/${BUCKET}/${path}`, { headers: serviceHeaders() });
+  if (!res.ok) {
+    throw new Error(`storage download ${res.status}: ${(await res.text().catch(() => "")).slice(0, 200)}`);
+  }
+  return new Uint8Array(await res.arrayBuffer());
+}
+
+// src/uploads.ts
+var DOWNLOAD_URL_TTL_SECONDS = 60 * 60;
+function uploadDirFor(userId) {
+  return `uploads/${userId}/${randomBytes(12).toString("base64url")}`;
+}
+var NAME_SEGMENT_RE = /^\d+__([A-Za-z0-9_-]+)\.png$/;
+function decodeNameFromRef(ref) {
+  const last = ref.slice(ref.lastIndexOf("/") + 1);
+  const match = NAME_SEGMENT_RE.exec(last);
+  if (!match) return null;
+  try {
+    return Buffer.from(match[1], "base64url").toString("utf-8");
+  } catch {
+    return null;
+  }
+}
+function refBelongsToUser(ref, userId) {
+  return ref.startsWith(`uploads/${userId}/`) && !ref.includes("..");
+}
+async function fetchUploadedRef(ref, userId) {
+  if (!refBelongsToUser(ref, userId)) {
+    throw new Error(`ref does not belong to this account: ${ref}`);
+  }
+  return downloadObject(ref);
+}
+async function storeAsset(dir, filename, bytes, contentType) {
+  const ref = `${dir}/${filename}`;
+  const { uploadUrl } = await createSignedUploadUrl(ref);
+  await putBytes(uploadUrl, bytes, contentType);
+  const url = await createSignedDownloadUrl(ref, DOWNLOAD_URL_TTL_SECONDS);
+  return { ref, url };
+}
+var MAX_CHATGPT_FILE_BYTES = 20 * 1024 * 1024;
+var PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+
+// src/screenshotInput.ts
+function entryName(entry) {
+  if (typeof entry === "string") return null;
+  if (typeof entry.name === "string" && entry.name.trim()) return entry.name.trim();
+  if ("ref" in entry) return decodeNameFromRef(entry.ref);
+  if ("path" in entry) return basename(entry.path) || null;
+  return null;
+}
+function resolveScreenshotNames(slots) {
+  return slots.map((slot2) => slot2.map(entryName));
+}
+var MAX_URL_FETCH_BYTES = 20 * 1024 * 1024;
+var MAX_INLINE_TOTAL_BYTES = 8 * 1024 * 1024;
+function estimateDecodedBytes(base64) {
+  return Math.floor(base64.length * 3 / 4);
+}
+function assertInlinePayloadSize(entries) {
+  const totalInline = entries.filter((e) => typeof e === "string").reduce((sum, s) => sum + estimateDecodedBytes(s), 0);
+  if (totalInline > MAX_INLINE_TOTAL_BYTES) {
+    const mb = (totalInline / 1024 / 1024).toFixed(1);
+    const capMb = MAX_INLINE_TOTAL_BYTES / 1024 / 1024;
+    throw new Error(
+      `payload too large (${mb}MB inline, cap ${capMb}MB) \u2014 call request_screenshot_upload and pass { "ref": "..." } entries instead of inline base64.`
+    );
+  }
+}
+function assertInlinePayloadSizeNested(slots) {
+  assertInlinePayloadSize(slots.flat());
+}
+async function fetchUrlAsBase64(url) {
+  if (!/^https:\/\//i.test(url)) throw new Error(`screenshot url must be https: ${url}`);
+  const res = await fetch(url, { redirect: "manual" });
+  if (res.status >= 300 && res.status < 400) {
+    throw new Error(`screenshot url redirected \u2014 redirects are not followed (https-only, one hop): ${url}`);
+  }
+  if (!res.ok) throw new Error(`screenshot url fetch failed (${res.status}): ${url}`);
+  const contentType = res.headers.get("content-type") ?? "";
+  if (!/^image\/png/i.test(contentType)) {
+    throw new Error(`screenshot url did not return image/png (got "${contentType || "no content-type"}"): ${url}`);
+  }
+  const buf = new Uint8Array(await res.arrayBuffer());
+  if (buf.byteLength > MAX_URL_FETCH_BYTES) {
+    throw new Error(`screenshot url exceeds the ${MAX_URL_FETCH_BYTES / 1024 / 1024}MB cap: ${url}`);
+  }
+  return Buffer.from(buf).toString("base64");
+}
+async function readLocalPathAsBase64(path) {
+  try {
+    return (await readFile(path)).toString("base64");
+  } catch (err) {
+    throw new Error(`could not read local screenshot at "${path}": ${err.message}`);
+  }
+}
+async function resolvePanelBytes(entry, userId, allowLocalPath) {
+  if ("path" in entry) {
+    if (!allowLocalPath) {
+      throw new Error(
+        `{ "path": "${entry.path}" } panel entries are only available over the local stdio server (npx shotops-mcp) \u2014 the hosted server rejects them. Pass { "ref": "..." } from a prior render_strip output:"urls" result instead.`
+      );
+    }
+    try {
+      return await readFile(entry.path);
+    } catch (err) {
+      throw new Error(`could not read local panel at "${entry.path}": ${err.message}`);
+    }
+  }
+  return fetchUploadedRef(entry.ref, userId);
+}
+async function resolveEntry(entry, userId, allowLocalPath) {
+  if (typeof entry === "string") return entry;
+  if ("ref" in entry) return Buffer.from(await fetchUploadedRef(entry.ref, userId)).toString("base64");
+  if ("path" in entry) {
+    if (!allowLocalPath) {
+      throw new Error(
+        `{ "path": "${entry.path}" } screenshot entries are only available over the local stdio server (npx shotops-mcp) \u2014 the hosted server rejects them. Use { "ref": "..." } (request_screenshot_upload) or { "url": "..." } instead.`
+      );
+    }
+    return readLocalPathAsBase64(entry.path);
+  }
+  return fetchUrlAsBase64(entry.url);
+}
+async function resolveScreenshots(slots, userId, allowLocalPath = false) {
+  assertInlinePayloadSizeNested(slots);
+  return Promise.all(slots.map((slot2) => Promise.all(slot2.map((entry) => resolveEntry(entry, userId, allowLocalPath)))));
+}
+
+// src/schemas.ts
+import { z } from "zod";
+var PANEL_PRESET_IDS = ["r69", "r65", "r55", "ipad13", "ipad129"];
+var OUTPUT_DEVICE_IDS = ["iphone-6-9", "iphone-6-5"];
+var OUTPUT_DEVICES = [
+  { id: "iphone-6-9", label: "iPhone 6.9\u2033", panelPresetId: "r69", ascDeviceSet: "APP_IPHONE_67" },
+  { id: "iphone-6-5", label: "iPhone 6.5\u2033", panelPresetId: "r65", ascDeviceSet: "APP_IPHONE_65" }
+];
+function outputDeviceFor(id) {
+  return OUTPUT_DEVICES.find((device) => device.id === id);
+}
+var PANEL_LABELS = {
+  r69: "6.9\u2033 iPhone",
+  r65: "6.5\u2033 iPhone",
+  r55: "5.5\u2033 iPhone",
+  ipad13: "13\u2033 iPad",
+  ipad129: "12.9\u2033 iPad"
+};
+function panelLabelFor(presetId, width, height) {
+  const name = PANEL_LABELS[presetId];
+  return name ? `${name} \xB7 ${width}\xD7${height}` : `${width}\xD7${height}`;
+}
+var PANEL_DIMENSIONS = {
+  r69: { width: 1290, height: 2796 },
+  r65: { width: 1242, height: 2688 },
+  r55: { width: 1242, height: 2208 },
+  ipad13: { width: 2064, height: 2752 },
+  ipad129: { width: 2048, height: 2732 }
+};
+function panelDimensionsFor(presetId) {
+  return PANEL_DIMENSIONS[presetId] ?? PANEL_DIMENSIONS.r69;
+}
+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 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 shotops-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."
+);
+var screenshots = z.array(slot).min(1).max(10).describe(screenshotsDescription);
+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 panelRef = z.object({ ref: z.string().min(1) }).strict();
+var pathPanel = z.object({ path: z.string().min(1) }).strict().describe(
+  '(local stdio mode only) a pre-rendered panel PNG read straight off disk: { "path": "/abs/or/relative/panel-01.png" }. Mirrors a screenshot { path } \u2014 rejected on the hosted server. Lets the free local tier PACKAGE a render with no account / no upload refs.'
+);
+var panelEntry = z.union([panelRef, pathPanel]);
+var localePanelRef = z.object({ locales: z.record(z.string(), panelEntry) }).strict().describe(
+  'Per-locale variants of ONE pre-rendered panel: { "locales": { "en-US": { "ref": "\u2026" }, "de-DE": { "ref": "\u2026" } } }. Each variant is a { "ref" } or (local) { "path" }. 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, pathPanel, localePanelRef])).min(1).max(10).optional().describe(
+  'Pre-rendered panels, packaged into the bundle WITHOUT rendering again \u2014 either { "ref": "\u2026" } from a prior render_strip `output: "urls"` call (hosted), or (local stdio mode) { "path": "/abs/panel.png" } straight off disk so the free local tier can package a two-pass render. Mutually exclusive with `screenshots`; one of the two is required. An entry may also be { "locales": { "<locale>": { "ref" | "path" } } } 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).'
+);
+var outputsField = z.array(z.enum(OUTPUT_DEVICE_IDS)).min(1).max(OUTPUT_DEVICE_IDS.length).optional().describe(
+  "Target device outputs to render into one fastlane bundle. Supported now: iphone-6-9 (1290\xD72796 / APP_IPHONE_67) and iphone-6-5 (1242\xD72688 / APP_IPHONE_65). Each is rendered from the same Look and inputs; omit this field to keep the legacy single panelPresetId form unchanged. Not supported with pre-rendered `panels` refs."
+);
+var clip = z.enum(["strip", "panel"]).optional().describe(
+  "How the strip handles a device that overflows its panel. 'strip' (default) = one continuous canvas \u2014 a phone can straddle the seam into the next panel (swipe-through scenes; also what hOffset \xB11 opts into). 'panel' = clip each phone to its OWN panel so it can't bleed a foreign edge into the neighbouring App Store screenshot (independent images). A render option, not part of the saved look."
+);
+var preview = z.boolean().optional().describe(
+  "Render at ~25% resolution for a fast, cheap styling preview \u2014 small enough to always come back inline. Not for final delivery: re-render without `preview` (or use emit_bundle directly) once the look is right."
+);
+var panelPresetId = z.enum(PANEL_PRESET_IDS).optional().describe("App Store screenshot size. Default r69 (6.9\u2033 iPhone, 1290\xD72796).");
+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, 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 = {
+  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
+};
+var DEFAULT_CAPTION_STYLE2 = {
+  fontId: "inter",
+  sizePt: 44,
+  color: "FFFFFF",
+  align: "center",
+  anchor: { x: 0.5, y: 0.06 },
+  maxWidth: 0.86
+};
+var numeric = z.union([z.string(), z.number()]);
+var shotLook = z.object({
+  angle: z.enum(["front", "left", "right"]).optional().describe("Camera preset. Default front."),
+  cameraPos: z.object({ x: z.number(), y: z.number(), z: z.number() }).nullable().optional().describe("Manual camera position override; null/omit = use the angle preset."),
+  roll: numeric.optional().describe("\u221245\u202645\xB0 clock-hand tilt. Default 0."),
+  phoneHeight: numeric.optional().describe("Phone height, 20\u2013100 (% of panel height). Default 72."),
+  hOffset: numeric.optional().describe("Horizontal position \u2212100\u2026100; 0 = centre. Default 0 (multi-phone slots auto-stagger)."),
+  vOffset: numeric.optional().describe("Vertical position \u2212200\u2026200; 0 = centre. Default 0."),
+  material: z.enum(["real", "clay"]).optional().describe("Device body. Default real."),
+  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."),
+  glare: z.boolean().optional().describe("Screen glare. Default false."),
+  lighting: z.boolean().optional().describe("Scene lighting. Default true."),
+  reflections: z.boolean().optional().describe("Body reflections. Default false.")
+}).strict();
+var background = z.object({
+  mode: z.enum(["gradient", "perPanel"]).optional().describe("One gradient across the strip, or a flat colour per panel."),
+  gradientFrom: z.string().optional().describe("Gradient start (hex). Default #1b1b2e."),
+  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."),
+  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."),
+  sizePt: z.number().positive().max(200).optional().describe("Font size in iOS points (preset-independent). Default 44."),
+  color: z.string().optional().describe("Text colour (hex). Default FFFFFF."),
+  align: z.enum(["left", "center", "right"]).optional().describe("Default center."),
+  anchor: z.object({ x: z.number().min(0).max(1).optional(), y: z.number().min(0).max(1).optional() }).optional().describe("Normalized 0\u20131 position of the caption on the panel. Default {x:0.5, y:0.06}."),
+  maxWidth: z.number().min(0.05).max(1).optional().describe("Wrap width as a 0\u20131 fraction of the panel. Default 0.86."),
+  text: z.string().max(200).optional().describe("The headline \u2014 per-RENDER input, never stored in a look."),
+  subtitle: z.string().max(300).optional().describe("Optional subtitle under the headline \u2014 also per-render input.")
+}).strict();
+var style = z.object({
+  shotLook: shotLook.optional().describe("Device/camera styling, applied to every phone in the strip."),
+  background: background.optional(),
+  // 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 path (call describe_look for the full field catalog + defaults). COMPOSES with `look`: pass BOTH to get per-panel devices from the `look` AND captions from `style.captions` in ONE render (every real App Store strip). When a `look` is also given it supplies the devices + background, so `style.shotLook`/`style.background` are ignored (a note says so) \u2014 use `style` for `captions` then. Alone, `style` styles every phone identically + captions. Also composes with `useSavedLook`/`version`."
+);
+var lookShot = z.object({
+  panelId: z.string().optional().describe("Panel this shot styles. Panels are panel-1\u2026panel-N in slot order; a saved look\u2019s own ids are remapped by ordinal."),
+  look: shotLook.optional().describe("This panel\u2019s device/camera styling \u2014 the SAME fields as style.shotLook.")
+}).strict();
+var lookObject = z.object({
+  schema: z.number().optional().describe("Look schema version (read_look stamps it; ignored on input)."),
+  panelPresetId: z.string().optional().describe("Canvas size preset, e.g. r69 = 1290\xD72796. Default r69."),
+  bgMode: z.enum(["gradient", "perPanel"]).optional().describe("One gradient across the strip, or a flat colour per panel. Default gradient."),
+  gradientFrom: z.string().optional().describe("Gradient start (hex). Default #1b1b2e."),
+  gradientTo: z.string().optional().describe("Gradient end (hex). Default #0a0a14."),
+  gradientDir: z.enum(["horizontal", "vertical"]).optional().describe("Default vertical."),
+  panelColors: z.record(z.string(), z.string()).optional().describe("Per-panel flat colours (mode perPanel), keyed by panel id."),
+  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."),
+  panelBackgrounds: z.record(z.string(), z.unknown()).optional().describe("Per-frame background overrides keyed by panel id (web-authored; agents rarely set these)."),
+  captionStyles: z.record(z.string(), z.unknown()).optional().describe("Per-panel caption STYLE arrays keyed by panel id (styling only, no words \u2014 for caption text pass style.captions)."),
+  shots: z.array(lookShot).max(60).optional().describe("One entry per panel in slot order, each with its OWN device `look` \u2014 this is how a look styles each panel DIFFERENTLY (mixed-device / continuous-scene strips), which style.shotLook cannot.")
+}).strict();
+var look = lookObject.optional().describe(
+  'A ShotOps "look" \u2014 per-panel DEVICE styling + background, exactly as read_look returns it. Its shots[] give each panel its own device (tint/tilt/size); style.shotLook is one device for all. COMPOSES with `style`: pass a look for the devices + `style.captions` for the words in ONE render. Validated \u2014 unknown keys are rejected (call describe_look for the full field catalog).'
+);
+var project = z.string().min(1).optional().describe("The ShotOps project id to target (as returned by read_look). Omit = your most recently edited project.");
+var version = z.number().int().min(1).optional().describe(
+  "Render a specific saved look version of the project (implies the saved look). Omit = the project's HELD version if one is held (hold_look), else the latest saved look."
+);
+var createProjectFlag = z.boolean().optional().describe(
+  "Also save this render as an editable ShotOps project the signed-in user can open + refine (returns projectId + an openUrl). Pass an existing `project` id to update it instead of creating a new one. Full-res only \u2014 not allowed with preview:true. No image bytes are stored (structure + look only)."
+);
+var projectName = z.string().optional().describe('Name for the created project (when createProject makes a new one). Default "ShotOps render".');
+var sourceDir = z.string().optional().describe(
+  'Advanced: the on-disk folder these screenshots were read from (only meaningful when they came from local { path } entries on the SAME machine). When set, the saved project remembers this folder as its screen source (kind: "local-path") instead of just filenames. Used by the local stdio bridge \u2014 most callers should omit it.'
+);
+var renderStripShape = {
+  screenshots,
+  panelPresetId,
+  clip,
+  look,
+  style,
+  useSavedLook,
+  project,
+  version,
+  locale,
+  preview,
+  output,
+  createProject: createProjectFlag,
+  projectName,
+  sourceDir
+};
+var emitBundleShape = {
+  screenshots: screenshotsOptional,
+  panels: panelRefs,
+  panelPresetId,
+  clip,
+  outputs: outputsField,
+  look,
+  style,
+  useSavedLook,
+  project,
+  version,
+  bundleId: z.string().describe(
+    "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 "shotops".'),
+  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."
+  ),
+  // create-project: save the rendered strip as an editable Studio project too (returns
+  // projectId + openUrl). Only on the RENDER path (screenshots) — the compose-only `panels`
+  // path never re-styles, so there's nothing to persist; it's rejected with a pointer to
+  // render_strip/save_project.
+  createProject: createProjectFlag,
+  output,
+  sourceDir
+};
+var saveProjectShape = {
+  screenshots: screenshotsForSave,
+  panelPresetId,
+  look,
+  style,
+  useSavedLook,
+  project,
+  version,
+  locale,
+  projectName,
+  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,
+  // C (#50): the SAME validated shape as the render `look` (required here). A typo'd device key
+  // is rejected at save time now, not silently persisted — the handler's structural `shots` gate
+  // and the looksMatch dedupe still run on top.
+  look: lookObject.describe(
+    "The look JSON to save (styling only \u2014 the shape read_look returns / describe_look documents). Caption text is NOT part of a look; pass it per render instead."
+  ),
+  sourceName: z.string().max(120).optional().describe("Where this styling came from (shown in the studio UI).")
+};
+var heldVersion = z.number().int().min(1).describe("The saved look version to HOLD as the one agents render by default (see read_look `versions`).");
+var holdLookShape = { project, version: heldVersion };
+var releaseLookShape = { project };
+var describeLookShape = {};
+var DESCRIBE_LOOK_CATALOG = {
+  style: {
+    shotLook: {
+      description: "Device/camera styling, applied to every phone in the strip.",
+      defaults: DEFAULT_SHOT_LOOK,
+      fields: {
+        angle: "front | left | right (preset only \u2014 there is no free yaw)",
+        cameraPos: "{ x, y, z } rotates the camera around the device to refine the angle beyond the presets, or null to use the preset. It does NOT zoom or resize \u2014 device SIZE is set ONLY by phoneHeight (the export alpha-crops the device tight, so camera distance is discarded).",
+        roll: "-45\u202645 (degrees, clock-hand tilt; continuous, unlike angle)",
+        phoneHeight: "20\u2026100 (% of panel height) \u2014 the ONLY device-size control. Larger = more near-bleed. Default 72.",
+        hOffset: "-100\u2026100 (0 = centre; multi-phone slots auto-stagger when unset)",
+        vOffset: "-200\u2026200 (0 = centre)",
+        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",
+        lighting: "boolean",
+        reflections: "boolean"
+      }
+    },
+    background: {
+      description: "The strip background.",
+      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',
+        floorReflection: "boolean \u2014 a flipped, faded floor reflection under each phone"
+      }
+    },
+    captions: {
+      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 \u2014 OMIT to auto-place above the device",
+        maxWidth: "wrap width as a 0\u20131 fraction of the panel width",
+        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."
+      }
+    }
+  },
+  // B (#49): the opaque `look` shape, dumped in full with an example — no more reverse-engineering
+  // it from the source. A look is per-panel DEVICE styling + background; style.shotLook is one device
+  // for all. All fields optional; validated (unknown keys rejected).
+  look: {
+    description: "The per-panel styling path: give each panel its OWN device (tint/tilt/size) via shots[], which style.shotLook cannot. The exact shape read_look returns \u2014 hand-author it or round-trip it. COMPOSES with style (see notes): a look for the devices + style.captions for the words, one render.",
+    fields: {
+      shots: "The per-panel devices: an array, one entry { panelId, look } per panel in slot order, each `look` taking the SAME fields as style.shotLook above. This is the only way to vary the device per panel.",
+      panelPresetId: "canvas size preset id (see panelPresets); the top-level panelPresetId param overrides it",
+      bgMode: "gradient | perPanel",
+      gradientFrom: "gradient start (hex). Default #1b1b2e",
+      gradientTo: "gradient end (hex). Default #0a0a14",
+      gradientDir: "vertical | horizontal. Default vertical",
+      panelColors: 'per-panel flat colours keyed by panel id (mode perPanel), e.g. { "panel-1": "#123456" }',
+      shadow: "boolean \u2014 drop shadow under the phones. Default true",
+      floorReflection: "boolean \u2014 flipped, faded floor reflection. Default false",
+      panelBackgrounds: "per-frame background overrides keyed by panel id \u2014 web-authored; usually only present on a round-tripped look",
+      captionStyles: "per-panel caption STYLE arrays keyed by panel id (styling only, no words) \u2014 web-authored; for caption text pass style.captions"
+    },
+    example: {
+      bgMode: "gradient",
+      gradientFrom: "#3E3D42",
+      gradientTo: "#1E1D22",
+      shots: [
+        { panelId: "panel-1", look: { material: "clay", clayTone: "custom", clayCustom: "175030", angle: "left", roll: "-19", phoneHeight: "74" } },
+        { panelId: "panel-2", look: { material: "clay", clayTone: "custom", clayCustom: "194860", angle: "right", roll: "8", phoneHeight: "86" } }
+      ]
+    }
+  },
+  panelPresets: PANEL_PRESET_IDS.map((id) => ({ id, ...PANEL_DIMENSIONS[id], label: PANEL_LABELS[id] })),
+  // E (#54): a top-level render option (not styling) — named here so it's discoverable.
+  clip: {
+    description: "How the strip handles a device that overflows its panel (top-level render_strip/emit_bundle param, not part of the look). 'strip' (default) = one continuous canvas; a phone can straddle the seam into the next panel (swipe-through scenes). 'panel' = clip each phone to its own panel so it can't bleed a foreign-coloured edge into the neighbouring App Store screenshot.",
+    values: ["strip", "panel"],
+    default: "strip"
+  },
+  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). See the `look` section for the full shape + an example.",
+    "COMPOSE (every real App Store strip): to style each panel with its OWN device AND caption it, pass BOTH `look` (per-panel devices via shots[] + background) and `style` (captions via style.captions) in ONE render_strip/emit_bundle call \u2014 they combine. The look supplies the styling; if you also pass style.shotLook/style.background alongside a look they are ignored (the look wins) and a note tells you.",
+    "Fidelity ceilings: `angle` is preset-only (front|left|right) and `roll` is continuous (\xB145\xB0), but there is NO free yaw \u2014 an arbitrary 3-axis source rotation can only be approximated. Device SIZE is set only by `phoneHeight` (there is no separate scale, and cameraPos does not resize). Fonts are the 5 in `style.captions.fonts` \u2014 pick the closest; an exact non-bundled typeface match is not possible.",
+    "save_look appends a look version; hold_look sets which saved version agents render by default (or Hold one in ShotOps\u2019s Version history), and render_strip `version` renders a specific one."
+  ]
+};
+var requestScreenshotUploadShape = {
+  count: z.number().int().min(1).max(10).describe("How many upload slots to mint (1\u201310, one per screenshot)."),
+  // Phase 2 (item 2, PINNED): each name is encoded into its slot's ref, so it reaches the
+  // saved project's frameName even if a later render_strip/emit_bundle call passes that slot's
+  // `{ 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.'
+  )
+};
+var deleteAssetsShape = {
+  refs: z.array(z.string().min(1)).min(1).max(50).describe(
+    "One or more account-scoped refs previously returned by import_screenshot, request_screenshot_upload, render_strip, render_project, or emit_bundle. Deletion is irreversible."
+  )
+};
+var chatGptFile = z.object({
+  download_url: z.string().url().describe("Short-lived HTTPS download URL supplied by ChatGPT."),
+  file_id: z.string().min(1).describe("ChatGPT file identifier."),
+  mime_type: z.string().optional().describe("File MIME type supplied by ChatGPT."),
+  file_name: z.string().max(200).optional().describe("Original attachment filename, when available.")
+}).strict();
+var importScreenshotShape = {
+  file: chatGptFile.describe("A PNG attached by the user in ChatGPT."),
+  name: z.string().max(200).optional().describe("Override the filename stored in the returned ref. Defaults to file.file_name."),
+  locale: z.string().optional().describe("Optional bookkeeping tag for the App Store locale this screenshot belongs to.")
+};
+var projectSummary = z.object({ id: z.string(), name: z.string() }).passthrough();
+var storedAssetOutput = z.object({ ref: z.string(), url: z.string().url() }).passthrough();
+var panelOutput = z.union([z.string(), storedAssetOutput]);
+var renderStripOutputSchema = z.object({
+  ok: z.boolean(),
+  count: z.number(),
+  panelPresetId: z.string(),
+  panelWidth: z.number(),
+  panelHeight: z.number(),
+  renderMs: z.number(),
+  output: z.enum(["inline", "urls"]),
+  locale: z.string(),
+  panels: z.array(panelOutput)
+}).passthrough();
+var emitBundleOutputSchema = z.object({
+  ok: z.boolean(),
+  filename: z.string(),
+  bundleId: z.string(),
+  panelCount: z.number(),
+  output: z.enum(["inline", "urls"])
+}).passthrough();
+var saveProjectOutputSchema = z.object({
+  ok: z.boolean(),
+  projectId: z.string(),
+  openUrl: z.string().url(),
+  count: z.number(),
+  panelPresetId: z.string(),
+  locale: z.string(),
+  message: z.string()
+}).passthrough();
+var readLookOutputSchema = z.object({
+  saved: z.boolean(),
+  project: projectSummary.optional(),
+  message: z.string().optional()
+}).passthrough();
+var readProjectOutputSchema = z.object({
+  saved: z.boolean(),
+  project: projectSummary.optional(),
+  message: z.string().optional()
+}).passthrough();
+var renderProjectOutputSchema = renderStripOutputSchema.extend({
+  project: projectSummary,
+  shots: z.array(z.object({ frameName: z.string(), matched: z.boolean() }).passthrough())
+});
+var saveLookOutputSchema = z.object({ ok: z.boolean(), project: projectSummary, version: z.number(), message: z.string() }).passthrough();
+var holdLookOutputSchema = z.object({ ok: z.boolean(), project: projectSummary, heldVersion: z.number(), message: z.string() }).passthrough();
+var releaseLookOutputSchema = z.object({ ok: z.boolean(), project: projectSummary, heldVersion: z.null(), message: z.string() }).passthrough();
+var describeLookOutputSchema = z.object({
+  style: z.unknown(),
+  look: z.unknown(),
+  panelPresets: z.array(z.unknown()),
+  clip: z.unknown(),
+  notes: z.array(z.string())
+}).passthrough();
+var requestScreenshotUploadOutputSchema = z.object({
+  ok: z.boolean(),
+  slots: z.array(
+    z.object({ ref: z.string(), uploadUrl: z.string().url(), name: z.string().optional() }).passthrough()
+  ),
+  instructions: z.string()
+}).passthrough();
+var importScreenshotOutputSchema = z.object({
+  ok: z.boolean(),
+  ref: z.string(),
+  url: z.string().url(),
+  name: z.string(),
+  size: z.number().int().nonnegative(),
+  instructions: z.string()
+}).passthrough();
+var deleteAssetsOutputSchema = z.object({
+  ok: z.boolean(),
+  deletedCount: z.number().int().nonnegative(),
+  deletedRefs: z.array(z.string()),
+  message: z.string()
+}).passthrough();
+
+// src/toolContract.ts
+var SERVER_INSTRUCTIONS = [
+  "ShotOps turns raw app screenshots into styled 3D device mockups laid out as an App Store",
+  "screenshot strip, and packages them into a fastlane deliver bundle. It renders images only \u2014",
+  "no App Store / Apple credential is ever involved, and nothing is submitted for review.",
+  "",
+  "## Workflow",
+  "1. In ChatGPT, call import_screenshot once per attached PNG; it returns a ShotOps { ref }",
+  "   without putting image bytes in model context. In other hosted MCP clients, use",
+  "   request_screenshot_upload({ count, names }) \u2014 get signed slots, then PUT each raw PNG to its",
+  '   uploadUrl (curl -T screenshot.png "<uploadUrl>"). NEVER inline full-resolution screenshots;',
+  "   pass the returned { ref } instead. Only small images may be inlined as base64. Pass `names`",
+  "   (original filenames, same order as count) and each ref already carries its name \u2014 see below.",
+  "2. render_strip({ screenshots, panelPresetId, style }) \u2014 composite onto a device, return",
+  "   per-panel PNGs. Iterate with preview:true (fast ~25% render); drop it for final delivery.",
+  '   Large results come back as output:"urls" (download them; bytes never transit the chat).',
+  "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. On the LOCAL',
+  "   stdio tier (no account, so no upload refs) pass panels straight off disk instead:",
+  '   panels: [{ "path": "/abs/panel-01.png" }, \u2026] \u2014 the same { path } local-only door as screenshots.',
+  "4. Hosted refs are private but retained until deleted. After downloading the final results, call",
+  "   delete_assets({ refs: [...] }) for screenshots, panels, and bundles the user no longer needs.",
+  "",
+  "## 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 ShotOps 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",
+  "(emit_bundle with `screenshots`) can exceed the MCP client idle window and the client gives up",
+  'even though the server finished. For 4+ panels, SPLIT it: first render_strip({ output:"urls" })',
+  "(you get panel URLs back as soon as it completes \u2014 watchable, and re-running is cheap since the",
+  "panels are already uploaded), THEN emit_bundle({ panels: [...those refs] }) which only ZIPS",
+  "(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),",
+  "  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, 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`",
+  "\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.',
+  "COMPOSE \u2014 every real App Store strip needs BOTH varied devices AND headlines, and you get them in",
+  "ONE call: pass the `look` AND a `style` together \u2014 the look gives the per-panel devices +",
+  "background, style.captions gives the words. (A style.shotLook/style.background passed alongside a",
+  "look is redundant \u2014 the look wins and the result carries a note saying so.) This is the exact shape",
+  "read_look/save_look use; describe_look details it and dumps the full look schema + an example.",
+  "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.",
+  'To opt OUT of that bleed (App Store panels as independent images), pass top-level clip:"panel" \u2014',
+  "it confines each phone to its own panel so an oversized/offset device never leaks a foreign edge",
+  'into the neighbour. Default clip:"strip" keeps the continuous scene. It is a render option, not styling.',
+  "",
+  "## 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",
+  "  per project (bumps a version), read_look returns it, and render_strip can re-apply it via",
+  "  useSavedLook. describe_look is the authoritative field list.",
+  "- CAPTION TEXT (the words) is per-render input and comes from the CALLER (your repo), never the",
+  "  server. No tool returns Studio-typed caption text \u2014 pass the copy yourself in",
+  "  style.captions[].text. Use the optional top-level `locale` to label a render and route an",
+  "  emit_bundle into fastlane/screenshots/<locale>/ (see the captions.<locale>.json convention).",
+  "",
+  "## Look version history + Hold",
+  "Every save_look (or a web Save look) appends a retained VERSION. read_look returns the full",
+  "`versions` history (newest-first) plus the current `heldVersion`. Render any specific one with",
+  "render_strip/emit_bundle `version: N`. To make one version the DEFAULT agents render (without",
+  "the designer having to re-save it as the newest), hold_look({ version: N }); release_look returns",
+  "to Follow latest (render the newest saved). With no version held, useSavedLook / omitting `version`",
+  "renders the latest.",
+  "",
+  "## Save a render as an editable project (offer this)",
+  "When the user might want to KEEP or later edit the strip (not just receive images), save it as",
+  "a real ShotOps project they can open + refine: call save_project, or pass",
+  "`createProject: true` on render_strip / emit_bundle. Either returns a projectId + an openUrl \u2014",
+  "hand the openUrl back so they can open it (signed in as the SAME account). To iterate, thread",
+  "that projectId back as `project` on the next call and it UPDATES the same project in place",
+  "(instead of creating a new one each time).",
+  "save_project is FAST and never renders \u2014 it saves structure + look only, so prefer it (over the",
+  "createProject flag) when the user just wants the editable project and you do not also need the",
+  "rendered images in the same call; it is the reliable way to save many/large strips. The",
+  "`createProject: true` flag renders too, so it cannot be combined with preview:true \u2014 for the",
+  "flag path, save the full-res pass, not a preview.",
+  "",
+  "## IMPORTANT \u2014 the raw screenshots are the ONE thing the account cannot give back",
+  "The saved record is structure + look only: NO screenshot bytes are stored (zero-custody), so",
+  "when the user opens the project the web app prompts them to RE-LOAD the raw app screenshots.",
+  "ShotOps cannot supply those \u2014 only the user's original files can. So whenever you save a",
+  "project (createProject / save_project), you MUST make the strip re-loadable:",
+  "- PASS EACH SCREENSHOT'S ORIGINAL FILENAME \u2014 easiest via request_screenshot_upload({ names }),",
+  `  which encodes it into that slot's ref so a later bare { "ref": "\u2026" } already carries it; or`,
+  '  set it explicitly per entry, e.g. { "ref": "\u2026", "name": "03_statistics.png" }. That filename',
+  "  becomes the saved shot's identity, so the user just re-opens their OWN screenshots folder and",
+  "  ShotOps matches exactly the files you used BY NAME \u2014 even a folder of many screenshots",
+  '  where only some were used. This is the clean path: no copying, no "which ones did you use?".',
+  "  The web banner names the files it expects, drawn from these names.",
+  "- Use the RAW app screenshots (the images you were given), NOT the rendered mockup panels or the",
+  "  exported fastlane zip \u2014 re-loading the export instead double-mockups the strip (a painful trap).",
+  "- If you generated/fetched the screenshots yourself, save them to disk and tell the user the",
+  "  folder path (with the same filenames you passed as `name`/`names`).",
+  "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 ShotOps (https://storeframe-studio.vercel.app \u2014 sign",
+  "in as the SAME account) and Save look; read_look then returns exactly that, so an agent",
+  "reproduces the human-tuned design with zero manual step. Zero-custody: source screenshots are",
+  "ephemeral (one render, then discarded); only the styling look is persisted, never the pixels."
+].join("\n");
+
+// ../mockup-engine/fastlaneBundle.ts
+import { strToU8, zipSync } from "fflate";
+var DELIVERFILE_TEMPLATE = `# Generated by ShotOps \u2014 screenshots-only upload, nothing else.
+# Uploads to your app's editable (unreleased) version. Never submits for review.
+app_identifier "{{BUNDLE_ID}}"
+skip_binary_upload true
+skip_metadata true
+skip_app_version_update true
+overwrite_screenshots true
+`;
+var README_TEMPLATE = `# Upload these screenshots to App Store Connect
+
+This bundle was exported from ShotOps for **{{BUNDLE_ID}}** \u2014
+{{COUNT}} screenshots \xB7 {{PANEL_LABEL}} \xB7 locale \`{{LOCALE}}\`.
+
+You upload it yourself with [Fastlane](https://fastlane.tools), signed in with **your own
+Apple account or API key**. Your credentials never touch ShotOps.
+
+## 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. 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.
+4. Upload the screenshots to your app's **editable (unreleased) version**, replacing the
+   existing set for this 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
+  fastlane/screenshots/{{LOCALE}}/   your 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 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 ShotOps 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
+  ShotOps 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 ShotOps 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 ShotOps.
+
+## 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 ShotOps 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
+  ShotOps and re-export rather than renaming files by hand.
+`;
+function render(template, vars) {
+  return template.replace(/\{\{(\w+)\}\}/g, (match, key) => vars[key] ?? match);
+}
+function generateDeliverfile(opts) {
+  const base = render(DELIVERFILE_TEMPLATE, { BUNDLE_ID: opts.bundleId });
+  const locales = opts.locales?.filter((l) => l.length > 0) ?? [];
+  const outputs = opts.outputs?.filter((o) => o.length > 0) ?? [];
+  if (locales.length === 0 && outputs.length === 0) return base;
+  const comments = [
+    ...locales.length > 0 ? [`# Locales in this bundle: ${locales.join(", ")} (one fastlane/screenshots/<locale>/ folder each).`] : [],
+    ...outputs.length > 0 ? [`# Device outputs in this bundle: ${outputs.join(", ")} (fastlane detects each from PNG dimensions).`] : []
+  ];
+  return `${comments.join("\n")}
+${base}`;
+}
+function generateBundleReadme(opts) {
+  return render(README_TEMPLATE, {
+    BUNDLE_ID: opts.bundleId,
+    LOCALE: opts.locale,
+    PANEL_LABEL: opts.panelLabel,
+    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")}_shotops.png`;
+}
+function outputScreenshotFilename(ascDeviceSet, index) {
+  return `${ascDeviceSet}_${String(index).padStart(2, "0")}_shotops.png`;
+}
+function bundleZipFilename(projectName2) {
+  const slug = projectName2.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return `${slug || "shotops"}-appstore-upload.zip`;
+}
+var BUNDLE_ID_RE = /^[A-Za-z][A-Za-z0-9-]*(\.[A-Za-z][A-Za-z0-9-]*)+$/;
+function isValidBundleId(s) {
+  return BUNDLE_ID_RE.test(s);
+}
+function buildFastlaneBundleZip(slots, opts) {
+  const files = {
+    "README.md": strToU8(
+      generateBundleReadme({
+        bundleId: opts.bundleId,
+        locale: opts.locale,
+        panelLabel: opts.panelLabel,
+        count: slots.length
+      })
+    ),
+    "fastlane/Deliverfile": strToU8(generateDeliverfile({ bundleId: opts.bundleId }))
+  };
+  for (const slot2 of slots) {
+    files[`fastlane/screenshots/${opts.locale}/${screenshotFilename(slot2.displayPosition)}`] = slot2.bytes;
+  }
+  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 });
+}
+var MULTI_OUTPUT_README_TEMPLATE = `# Upload these screenshots to App Store Connect
+
+This bundle was exported from ShotOps for **{{BUNDLE_ID}}** \u2014
+{{OUTPUT_COUNT}} device outputs ({{OUTPUTS}}) \xD7 {{LOCALE_COUNT}} locales ({{LOCALES}}).
+
+You upload it yourself with [Fastlane](https://fastlane.tools), signed in with **your own
+Apple account or API key**. Your credentials never touch ShotOps.
+
+## Upload
+
+\`\`\`
+cd <this folder>
+fastlane deliver
+\`\`\`
+
+Fastlane reads each \`fastlane/screenshots/<locale>/\` folder and detects the target device
+from each PNG's dimensions. The \`APP_IPHONE_*\` filename prefix makes the intended device
+set explicit; device-set subfolders are deliberately not used because deliver does not scan
+them. It shows an HTML preview and asks for confirmation before uploading.
+
+**Nothing is ever submitted for review.** The generated Deliverfile skips binaries and
+metadata and only replaces screenshots on an editable version.
+
+## Included outputs
+
+{{OUTPUT_LINES}}
+
+## Included locale folders
+
+{{LOCALE_LINES}}
+`;
+function generateMultiOutputBundleReadme(targets, opts) {
+  const locales = Array.from(new Set(targets.flatMap((target) => target.localeSlots.map((entry) => entry.locale))));
+  return render(MULTI_OUTPUT_README_TEMPLATE, {
+    BUNDLE_ID: opts.bundleId,
+    OUTPUT_COUNT: String(targets.length),
+    OUTPUTS: targets.map((target) => target.output.label).join(", "),
+    LOCALE_COUNT: String(locales.length),
+    LOCALES: locales.join(", "),
+    OUTPUT_LINES: targets.map(
+      ({ output: output2 }) => `- ${output2.label}: ${output2.ascDeviceSet} \xB7 preset ${output2.panelPresetId}`
+    ).join("\n"),
+    LOCALE_LINES: locales.map((locale2) => `- fastlane/screenshots/${locale2}/`).join("\n")
+  });
+}
+function buildMultiOutputFastlaneBundleZip(targets, opts) {
+  const locales = Array.from(new Set(targets.flatMap((target) => target.localeSlots.map((entry) => entry.locale))));
+  const files = {
+    "README.md": strToU8(generateMultiOutputBundleReadme(targets, opts)),
+    "fastlane/Deliverfile": strToU8(
+      generateDeliverfile({
+        bundleId: opts.bundleId,
+        locales,
+        outputs: targets.map(({ output: output2 }) => `${output2.label} (${output2.ascDeviceSet})`)
+      })
+    )
+  };
+  for (const { output: output2, localeSlots } of targets) {
+    for (const { locale: locale2, slots } of localeSlots) {
+      for (const slot2 of slots) {
+        const path = `fastlane/screenshots/${locale2}/${outputScreenshotFilename(
+          output2.ascDeviceSet,
+          slot2.displayPosition
+        )}`;
+        if (files[path]) throw new Error(`duplicate fastlane screenshot path: ${path}`);
+        files[path] = slot2.bytes;
+      }
+    }
+  }
+  return zipSync(files, { level: 0 });
+}
+
+// src/toolsBundle.ts
+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;
+}
+function dedupeOutputDevices(list) {
+  if (!Array.isArray(list)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const devices = [];
+  for (const id of list) {
+    if (seen.has(id)) continue;
+    const device = outputDeviceFor(id);
+    if (!device) continue;
+    seen.add(id);
+    devices.push(device);
+  }
+  return devices;
+}
+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 projectName2 = args.projectName?.trim() || "shotops";
+  const requestedLocales = dedupeLocales(args.locales);
+  const requestedOutputs = dedupeOutputDevices(args.outputs);
+  if (requestedOutputs.length > 0) {
+    if (args.panels && args.panels.length > 0) {
+      return errorResult(
+        "outputs cannot be combined with pre-rendered `panels` refs \u2014 those PNGs already have one fixed size. Pass `screenshots` so emit_bundle can re-render each target device."
+      );
+    }
+    if (args.createProject) {
+      return errorResult(
+        "createProject is not supported with the multi-output `outputs` form \u2014 save the editable project separately with save_project, then emit the device bundle."
+      );
+    }
+    const locales = requestedLocales.length > 0 ? requestedLocales : [args.locale?.trim() || "en-US"];
+    return emitMultiOutputBundle(deps2, args, requestedOutputs, locales, projectName2);
+  }
+  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.");
+  }
+  let slots;
+  let panelLabel;
+  let previewPng;
+  let note;
+  let projectRecord;
+  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(panelEntries.map((p) => resolvePanelBytes(p, deps2.userId, deps2.allowLocalScreenshots ?? false)));
+    } catch (err) {
+      return errorResult(`failed to read panel: ${err.message}`);
+    }
+    slots = bytesList.map((bytes, i) => ({ displayPosition: i + 1, bytes: Buffer.from(bytes) }));
+    previewPng = bytesList[0] ? Buffer.from(bytesList[0]) : null;
+  } else {
+    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(entries, deps2.userId, deps2.allowLocalScreenshots ?? false);
+    } catch (err) {
+      return errorResult(err.message);
+    }
+    const resolved = await resolveLook(deps2, args);
+    note = [resolved.note, composeConflictNote(resolved.look, resolved.style)].filter(Boolean).join(" ") || void 0;
+    const result = await deps2.renderer.render({
+      screenshots: screenshots2,
+      panelPresetId: args.panelPresetId,
+      look: resolved.look,
+      style: resolved.style,
+      clip: args.clip,
+      locale: locale2,
+      buildRecord: args.createProject === true,
+      ...args.createProject ? { screenshotNames: resolveScreenshotNames(entries) } : {}
+    });
+    if (!result.ok || !result.panels || !result.panelPresetId) {
+      return errorResult(`render failed: ${result.error ?? "unknown error"}`);
+    }
+    slots = result.panels.map((b64, i) => ({ displayPosition: i + 1, bytes: Buffer.from(b64, "base64") }));
+    panelLabel = panelLabelFor(result.panelPresetId, result.panelWidth ?? 0, result.panelHeight ?? 0);
+    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;
+  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: slots.length,
+        bundleId: args.bundleId,
+        locale: locale2,
+        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") };
+  let persisted;
+  let persistNote;
+  if (args.createProject) {
+    if (projectRecord == null) {
+      persistNote = "bundle succeeded but no project record was produced \u2014 not saved.";
+    } else {
+      const p = await persistProject(deps2, args, projectRecord);
+      if ("error" in p) persistNote = `not saved: ${p.error}`;
+      else persisted = p;
+    }
+  }
+  return textResult({
+    ok: true,
+    filename,
+    bundleId: args.bundleId,
+    locale: locale2,
+    panelCount: slots.length,
+    output: outputMode,
+    ...note ? { note } : {},
+    ...shareLink ? { shareLink } : {},
+    ...persisted ? { projectId: persisted.projectId, openUrl: persisted.openUrl } : {},
+    ...persistNote ? { projectNote: persistNote } : {},
+    ...zipOut
+  });
+}
+async function emitMultiOutputBundle(deps2, args, outputs, locales, projectName2) {
+  if (!args.screenshots || args.screenshots.length === 0) {
+    return errorResult("emit_bundle with outputs needs a non-empty `screenshots` array.");
+  }
+  const resolved = await resolveLook(deps2, args);
+  const targets = [];
+  let previewPng = null;
+  for (const output2 of outputs) {
+    const localeSlots = [];
+    for (const locale2 of locales) {
+      let entries;
+      try {
+        entries = resolveLocaleVariantSlots(args.screenshots, locale2);
+      } 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: output2.panelPresetId,
+        look: resolved.look,
+        style: resolved.style,
+        clip: args.clip,
+        locale: locale2
+      });
+      if (!result.ok || !result.panels || !result.panelPresetId) {
+        return errorResult(
+          `render failed for ${output2.label} / ${locale2}: ${result.error ?? "unknown error"}`
+        );
+      }
+      if (result.panelPresetId !== output2.panelPresetId) {
+        return errorResult(
+          `renderer returned ${result.panelPresetId} for ${output2.label}; expected ${output2.panelPresetId}`
+        );
+      }
+      localeSlots.push({
+        locale: locale2,
+        slots: result.panels.map((b64, index) => ({
+          displayPosition: index + 1,
+          bytes: Buffer.from(b64, "base64")
+        }))
+      });
+      if (!previewPng && result.stripBase64) previewPng = Buffer.from(result.stripBase64, "base64");
+    }
+    targets.push({ output: output2, localeSlots });
+  }
+  const zip = buildMultiOutputFastlaneBundleZip(targets, { bundleId: args.bundleId });
+  const filename = bundleZipFilename(projectName2);
+  const panelCount = targets[0]?.localeSlots[0]?.slots.length ?? 0;
+  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: panelCount * outputs.length,
+        bundleId: args.bundleId,
+        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((asset) => ({
+    zipUrl: asset.url,
+    zipRef: asset.ref
+  })) : { zipBase64: Buffer.from(zip).toString("base64") };
+  return textResult({
+    ok: true,
+    filename,
+    bundleId: args.bundleId,
+    outputs: outputs.map((output2) => output2.id),
+    locales,
+    panelCount,
+    totalPanelCount: panelCount * outputs.length * locales.length,
+    output: outputMode,
+    ...resolved.note ? { note: resolved.note } : {},
+    ...shareLink ? { shareLink } : {},
+    ...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 bytesCache = /* @__PURE__ */ new Map();
+    const readPanel = (p) => {
+      const key = "path" in p ? `path:${p.path}` : `ref:${p.ref}`;
+      let pending = bytesCache.get(key);
+      if (!pending) {
+        pending = resolvePanelBytes(p, deps2.userId, deps2.allowLocalScreenshots ?? false);
+        bytesCache.set(key, pending);
+      }
+      return pending;
+    };
+    localeSlots = [];
+    try {
+      for (const loc of locales) {
+        const panelEntries = args.panels.map((p) => resolveLocaleVariant(p, loc));
+        const bytesList = await Promise.all(panelEntries.map((p) => readPanel(p)));
+        localeSlots.push({
+          locale: loc,
+          slots: bytesList.map((bytes, i) => ({ displayPosition: i + 1, bytes: Buffer.from(bytes) }))
+        });
+      }
+    } catch (err) {
+      return errorResult(`failed to read panel: ${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,
+        clip: args.clip,
+        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
+  });
+}
+
+// src/toolsRender.ts
+async function handleRenderStrip(deps2, args) {
+  const { look: look2, style: style2, note: resolveNote } = await resolveLook(deps2, args);
+  const note = [resolveNote, composeConflictNote(look2, style2)].filter(Boolean).join(" ") || void 0;
+  const locale2 = args.locale?.trim() || "en-US";
+  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(entries, deps2.userId, deps2.allowLocalScreenshots ?? false);
+  } catch (err) {
+    return errorResult(err.message);
+  }
+  const result = await deps2.renderer.render({
+    screenshots: screenshots2,
+    panelPresetId: args.panelPresetId,
+    look: look2,
+    style: style2,
+    clip: args.clip,
+    preview: args.preview,
+    locale: locale2,
+    buildRecord: args.createProject === true,
+    // Phase 5A: only compute names when we're building a record (saving a project).
+    // 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"}`);
+  }
+  let persisted;
+  let persistNote;
+  if (args.createProject) {
+    if (result.projectRecord == null) {
+      persistNote = "render succeeded but no project record was produced \u2014 not saved.";
+    } else {
+      const p = await persistProject(deps2, args, result.projectRecord);
+      if ("error" in p) persistNote = `not saved: ${p.error}`;
+      else persisted = p;
+    }
+  }
+  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;
+  return textResult({
+    ok: true,
+    count: result.count,
+    panelPresetId: result.panelPresetId,
+    panelWidth: result.panelWidth,
+    panelHeight: result.panelHeight,
+    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 } : {},
+    panels
+  });
+}
+async function uploadPanels(userId, panelsBase64) {
+  const dir = uploadDirFor(userId);
+  return Promise.all(
+    panelsBase64.map(
+      (b64, i) => storeAsset(dir, `panel-${String(i + 1).padStart(2, "0")}.png`, Buffer.from(b64, "base64"), "image/png")
+    )
+  );
+}
+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 ShotOps project on this account yet \u2014 open ShotOps 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 ShotOps 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 },
+    heldVersion: project2.heldVersion,
+    // 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
+  });
+}
+
+// src/tools.ts
+var SAVED_RECORD_VERSION = 2;
+function textResult(payload, extraContent = []) {
+  return {
+    structuredContent: payload,
+    // Keep the existing JSON text for clients that do not consume structuredContent yet.
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }, ...extraContent]
+  };
+}
+function errorResult(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+var AUTO_INLINE_THRESHOLD_BYTES = 200 * 1024;
+function resolveOutputMode(requested, totalBytes) {
+  if (requested === "inline" || requested === "urls") return requested;
+  return totalBytes > AUTO_INLINE_THRESHOLD_BYTES ? "urls" : "inline";
+}
+async function resolveLook(deps2, args) {
+  const style2 = args.style ?? null;
+  if (args.look != null) return { look: args.look, style: style2 };
+  if (args.useSavedLook || args.version != null) {
+    const project2 = await deps2.resolveProject(deps2.userId, args.project);
+    if (!project2) {
+      return { look: null, style: style2, note: "no matching ShotOps project found for this account \u2014 used default styling." };
+    }
+    const saved = await deps2.readLook(project2.id);
+    if (!saved) {
+      return { look: null, style: style2, note: `no saved look on project "${project2.name}" \u2014 used default styling.` };
+    }
+    if (args.version != null) {
+      if (args.version === saved.version) return { look: saved.look, style: style2 };
+      const v = await deps2.readVersion(project2.id, args.version);
+      if (v) return { look: v.look, style: style2 };
+      return {
+        look: saved.look,
+        style: style2,
+        note: `version ${args.version} not found on project "${project2.name}" (latest is v${saved.version}) \u2014 rendered the latest.`
+      };
+    }
+    if (project2.heldVersion != null && project2.heldVersion !== saved.version) {
+      const held = await deps2.readVersion(project2.id, project2.heldVersion);
+      if (held) return { look: held.look, style: style2, note: `rendered the held look v${project2.heldVersion} (Follow latest to change).` };
+      return {
+        look: saved.look,
+        style: style2,
+        note: `held version v${project2.heldVersion} not found on project "${project2.name}" \u2014 rendered the latest (v${saved.version}).`
+      };
+    }
+    return { look: saved.look, style: style2 };
+  }
+  return { look: null, style: style2 };
+}
+function composeConflictNote(look2, style2) {
+  if (look2 == null || style2 == null || typeof style2 !== "object") return void 0;
+  const s = style2;
+  const ignored = [];
+  if (s.shotLook != null) ignored.push("style.shotLook");
+  if (s.background != null) ignored.push("style.background");
+  if (ignored.length === 0) return void 0;
+  return `a look is supplying the styling, so ${ignored.join(" + ")} ${ignored.length > 1 ? "were" : "was"} ignored \u2014 pass per-panel devices/background via the look, and captions via style.captions.`;
+}
+function screenNamesFromRecord(record) {
+  const shots = record?.shots;
+  if (!Array.isArray(shots)) return [];
+  return shots.map((s) => s?.frameName).filter((n) => typeof n === "string" && n.length > 0);
+}
+async function persistProject(deps2, args, record) {
+  const names = screenNamesFromRecord(record);
+  const source = names.length === 0 ? void 0 : args.sourceDir ? { kind: "local-path", ref: { dir: args.sourceDir, names } } : { kind: "agent", ref: { names } };
+  const wrapped = {
+    record: SAVED_RECORD_VERSION,
+    project: record,
+    ...source ? { source } : {}
+  };
+  const ctx = {
+    screenshots: args.screenshots,
+    look: args.look,
+    style: args.style,
+    panelPresetId: args.panelPresetId,
+    locale: args.locale,
+    sourceDir: args.sourceDir
+  };
+  try {
+    let projectId;
+    if (args.project) {
+      const project2 = await deps2.resolveProject(deps2.userId, args.project);
+      if (!project2) return { error: "no matching ShotOps project for this account." };
+      await deps2.updateProjectRecord(project2.id, wrapped, ctx);
+      projectId = project2.id;
+    } else {
+      const name = args.projectName?.trim() || "ShotOps render";
+      const created = await deps2.createProject(deps2.userId, name, wrapped, ctx);
+      projectId = created.id;
+    }
+    return { projectId, openUrl: `${deps2.studioOrigin}/?project=${projectId}` };
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+async function handleSaveProject(deps2, args) {
+  const { look: look2, style: style2 } = await resolveLook(deps2, args);
+  const locale2 = args.locale?.trim() || "en-US";
+  if (!Array.isArray(args.screenshots) || args.screenshots.length === 0) {
+    return errorResult("save_project needs a non-empty `screenshots` array (its slot shape + names define the project structure).");
+  }
+  const slotSizes = args.screenshots.map((s) => Array.isArray(s) ? s.length : 1);
+  if (slotSizes.some((n) => n < 1)) {
+    return errorResult("every `screenshots` slot must contain at least one screenshot entry.");
+  }
+  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({
+      slotSizes,
+      panelPresetId: args.panelPresetId,
+      look: look2,
+      style: style2,
+      locale: locale2,
+      screenshotNames
+    });
+  } catch (err) {
+    return errorResult(`could not build the project record: ${err.message}`);
+  }
+  if (record == null) {
+    return errorResult("no project record was produced \u2014 not saved.");
+  }
+  const p = await persistProject(deps2, args, record);
+  if ("error" in p) return errorResult(p.error);
+  return textResult({
+    ok: true,
+    projectId: p.projectId,
+    openUrl: p.openUrl,
+    count: slotSizes.length,
+    panelPresetId: args.panelPresetId ?? "r69",
+    locale: locale2,
+    message: `Saved as an editable ShotOps project \u2014 open it at ${p.openUrl} (sign in as the same account). Thread this projectId back on later renders to update it in place.`
+  });
+}
+async function handleReadLook(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 ShotOps project on this account yet \u2014 open ShotOps and load a strip first."
+    });
+  }
+  const saved = await deps2.readLook(project2.id);
+  if (!saved) {
+    return textResult({
+      saved: false,
+      project: { id: project2.id, name: project2.name },
+      message: `No saved look on project "${project2.name}". Style a strip in ShotOps and use the Look bar \u2192 Save look, or compose one here with describe_look + save_look.`
+    });
+  }
+  return textResult({
+    saved: true,
+    project: { id: project2.id, name: project2.name },
+    sourceName: saved.sourceName,
+    updatedAt: saved.updatedAt,
+    version: saved.version,
+    heldVersion: project2.heldVersion,
+    // null = renders Follow latest
+    // The full saved-look history (newest-first). Render a specific one with render_strip `version`,
+    // or hold it as the default with hold_look. Metadata only — fetch a version's styling by rendering.
+    versions: await deps2.listVersions(project2.id),
+    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 ShotOps project on this account yet \u2014 open ShotOps 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 ShotOps and save a strip first.`
+    });
+  }
+  return textResult({
+    saved: true,
+    project: { id: project2.id, name: project2.name },
+    updatedAt: rec.updatedAt,
+    heldVersion: project2.heldVersion,
+    // null = renders Follow latest
+    versions: await deps2.listVersions(project2.id),
+    // the saved-look history (newest-first metadata)
+    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\`, the language list in \`locales\`, the caption base the untranslated locales inherit in \`baseLocale\`, styling). To detect changes, remember updatedAt and compare on your next read_project \u2014 a newer value means the designer edited it.`
+  });
+}
+async function handleSaveLook(deps2, args) {
+  const project2 = await deps2.resolveProject(deps2.userId, args.project);
+  if (!project2) {
+    return errorResult(
+      args.project ? "No such project on this account." : "No ShotOps project on this account yet \u2014 open ShotOps and load a strip first."
+    );
+  }
+  const look2 = args.look;
+  if (!look2 || typeof look2 !== "object" || !Array.isArray(look2.shots)) {
+    return errorResult("`look` must be a look JSON with a `shots` array \u2014 see describe_look / read_look for the shape.");
+  }
+  if (JSON.stringify(args.look).length > 256 * 1024) {
+    return errorResult("`look` is too large \u2014 a look is styling only (no screenshots, no image bytes).");
+  }
+  const latest = await deps2.readLook(project2.id);
+  if (latest && looksMatch(args.look, latest.look)) {
+    return textResult({
+      ok: true,
+      project: { id: project2.id, name: project2.name },
+      version: latest.version,
+      message: `No styling change \u2014 still version ${latest.version} on "${project2.name}".`
+    });
+  }
+  const { version: version2 } = await deps2.saveLook(project2.id, args.look, args.sourceName?.trim() || void 0);
+  return textResult({
+    ok: true,
+    project: { id: project2.id, name: project2.name },
+    version: version2,
+    message: `Saved as version ${version2} on "${project2.name}" \u2014 render it with useSavedLook, or hold it as the default in ShotOps.`
+  });
+}
+async function handleHoldLook(deps2, args) {
+  const project2 = await deps2.resolveProject(deps2.userId, args.project);
+  if (!project2) {
+    return errorResult(
+      args.project ? "No such project on this account." : "No ShotOps project on this account yet."
+    );
+  }
+  const versions = await deps2.listVersions(project2.id);
+  if (!versions.some((v) => v.version === args.version)) {
+    const available = versions.length ? versions.map((v) => `v${v.version}`).join(", ") : "none saved yet";
+    return errorResult(`Version ${args.version} not found on project "${project2.name}" (saved: ${available}).`);
+  }
+  try {
+    await deps2.setHeldVersion(project2.id, args.version);
+  } catch (err) {
+    return errorResult(err.message);
+  }
+  return textResult({
+    ok: true,
+    project: { id: project2.id, name: project2.name },
+    heldVersion: args.version,
+    message: `Holding v${args.version} on "${project2.name}" \u2014 agents render it by default until release_look (Follow latest).`
+  });
+}
+async function handleReleaseLook(deps2, args) {
+  const project2 = await deps2.resolveProject(deps2.userId, args.project);
+  if (!project2) {
+    return errorResult(
+      args.project ? "No such project on this account." : "No ShotOps project on this account yet."
+    );
+  }
+  try {
+    await deps2.setHeldVersion(project2.id, null);
+  } catch (err) {
+    return errorResult(err.message);
+  }
+  return textResult({
+    ok: true,
+    project: { id: project2.id, name: project2.name },
+    heldVersion: null,
+    message: `Released the hold on "${project2.name}" \u2014 agents now Follow latest (render the newest saved version).`
+  });
+}
+function handleDescribeLook() {
+  return textResult(DESCRIBE_LOOK_CATALOG);
+}
+async function handleRequestScreenshotUpload(deps2, args) {
+  let slots;
+  try {
+    slots = await deps2.requestScreenshotUpload(deps2.userId, args.count, args.names);
+  } catch (err) {
+    return errorResult(err.message);
+  }
+  const locale2 = args.locale?.trim() || void 0;
+  return textResult({
+    ok: true,
+    slots,
+    ...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>" } } }.` : "")
+  });
+}
+async function handleImportScreenshot(deps2, args) {
+  if (!deps2.importScreenshot) {
+    return errorResult(
+      'import_screenshot is only available on the hosted ChatGPT/HTTP connection. In local stdio mode, pass a { "path": "..." } screenshot entry directly.'
+    );
+  }
+  let imported;
+  try {
+    imported = await deps2.importScreenshot(deps2.userId, args.file, args.name);
+  } catch (err) {
+    return errorResult(err.message);
+  }
+  const locale2 = args.locale?.trim() || void 0;
+  const payload = {
+    ok: true,
+    ...imported,
+    ...locale2 ? { locale: locale2 } : {},
+    instructions: 'Pass { "ref": "<ref>" } as this screenshot in render_strip or emit_bundle. For render_project, also pass { "name": "<name>" } so it matches the saved frame by filename.'
+  };
+  return textResult(payload, [
+    {
+      type: "resource_link",
+      name: imported.name,
+      uri: imported.url,
+      description: "Imported ShotOps screenshot (short-lived signed download URL).",
+      mimeType: "image/png",
+      size: imported.size
+    }
+  ]);
+}
+async function handleDeleteAssets(deps2, args) {
+  if (!deps2.deleteAssets) {
+    return errorResult(
+      "delete_assets is only available on the hosted ShotOps connection. Local mode does not upload or retain screenshot files."
+    );
+  }
+  try {
+    const deletedRefs = await deps2.deleteAssets(deps2.userId, args.refs);
+    return textResult({
+      ok: true,
+      deletedCount: deletedRefs.length,
+      deletedRefs,
+      message: "Deleted the selected ShotOps uploads. Saved projects that referenced these files may now report missing screenshots."
+    });
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+var READ_ONLY = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var ADDITIVE_WRITE = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: false
+};
+var IDEMPOTENT_WRITE = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var DESTRUCTIVE_WRITE = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: false
+};
+var OPEN_WORLD_DESTRUCTIVE_WRITE = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: true
+};
+var IDEMPOTENT_DESTRUCTIVE_WRITE = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: true,
+  openWorldHint: false
+};
+function toolMeta(deps2, invoking, invoked, extra = {}) {
+  return {
+    // Current MCP SDK exposes Apps authentication policy through `_meta`; `noauth` keeps the
+    // same registrar accurate for the local stdio server.
+    securitySchemes: deps2.allowLocalScreenshots ? [{ type: "noauth" }] : [{ type: "oauth2", scopes: [] }],
+    "openai/toolInvocation/invoking": invoking,
+    "openai/toolInvocation/invoked": invoked,
+    ...extra
+  };
+}
+function registerTools(server2, deps2) {
+  server2.registerTool(
+    "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. 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,
+      outputSchema: renderStripOutputSchema,
+      annotations: DESTRUCTIVE_WRITE,
+      _meta: toolMeta(deps2, "Rendering ShotOps strip\u2026", "ShotOps strip rendered")
+    },
+    (args) => handleRenderStrip(deps2, args)
+  );
+  server2.registerTool(
+    "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). 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,
+      outputSchema: emitBundleOutputSchema,
+      annotations: OPEN_WORLD_DESTRUCTIVE_WRITE,
+      _meta: toolMeta(deps2, "Building fastlane bundle\u2026", "Fastlane bundle built")
+    },
+    (args) => handleEmitBundle(deps2, args)
+  );
+  server2.registerTool(
+    "save_project",
+    {
+      title: "Save as editable project",
+      description: "SAVE the strip as an editable ShotOps project the signed-in user can open + refine (returns projectId + an openUrl \u2014 no panel PNGs). Fast: it persists structure + look only, so it does NOT render \u2014 no image bytes are stored or returned, and it never hits the render timeout. Pass an existing `project` id to update that project in place; omit it to create a new one. Prefer this (or render_strip/emit_bundle with `createProject: true` when you also need the images) when the user wants to keep + edit the strip later, not just receive the images.",
+      inputSchema: saveProjectShape,
+      outputSchema: saveProjectOutputSchema,
+      annotations: DESTRUCTIVE_WRITE,
+      _meta: toolMeta(deps2, "Saving ShotOps project\u2026", "ShotOps project saved")
+    },
+    (args) => handleSaveProject(deps2, args)
+  );
+  server2.registerTool(
+    "read_look",
+    {
+      title: "Read saved look",
+      description: "Return a project's saved ShotOps look (styling only \u2014 no screenshots, no credentials), with its latest version, the held version (if any), and the `versions` history. Feed the returned look back into render_strip/emit_bundle via the `look` field, or just pass `useSavedLook: true`; render a specific `versions` entry with `version`, or hold_look it.",
+      inputSchema: readLookShape,
+      outputSchema: readLookOutputSchema,
+      annotations: READ_ONLY,
+      _meta: toolMeta(deps2, "Reading saved look\u2026", "Saved look read")
+    },
+    (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,
+      outputSchema: readProjectOutputSchema,
+      annotations: READ_ONLY,
+      _meta: toolMeta(deps2, "Reading ShotOps project\u2026", "ShotOps project read")
+    },
+    (args) => handleReadProject(deps2, args)
+  );
+  server2.registerTool(
+    "render_project",
+    {
+      title: "Render a saved project",
+      description: "Re-render a SAVED ShotOps 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,
+      outputSchema: renderProjectOutputSchema,
+      annotations: ADDITIVE_WRITE,
+      _meta: toolMeta(deps2, "Rendering saved project\u2026", "Saved project rendered")
+    },
+    (args) => handleRenderProject(deps2, args)
+  );
+  server2.registerTool(
+    "save_look",
+    {
+      title: "Save look",
+      description: "Persist a composed ShotOps look (styling only) on a project, bumping its version. Use describe_look for the field catalog; caption text is never stored \u2014 pass it per render. No store credential is involved.",
+      inputSchema: saveLookShape,
+      outputSchema: saveLookOutputSchema,
+      annotations: ADDITIVE_WRITE,
+      _meta: toolMeta(deps2, "Saving ShotOps look\u2026", "ShotOps look saved")
+    },
+    (args) => handleSaveLook(deps2, args)
+  );
+  server2.registerTool(
+    "hold_look",
+    {
+      title: "Hold a look version",
+      description: "HOLD which saved look version the hosted MCP / agents render by DEFAULT \u2014 the coherent way to fix a render target. The version must exist (see read_look `versions`). A held version stays put while the designer keeps saving newer ones; render_strip/emit_bundle with `useSavedLook: true` then render it. Use release_look to Follow latest again. No credential.",
+      inputSchema: holdLookShape,
+      outputSchema: holdLookOutputSchema,
+      annotations: IDEMPOTENT_WRITE,
+      _meta: toolMeta(deps2, "Holding look version\u2026", "Look version held")
+    },
+    (args) => handleHoldLook(deps2, args)
+  );
+  server2.registerTool(
+    "release_look",
+    {
+      title: "Release the held look",
+      description: "Clear a project\u2019s held version (undo hold_look): agents go back to rendering the LATEST saved look (Follow latest). No-op if nothing was held. No store credential.",
+      inputSchema: releaseLookShape,
+      outputSchema: releaseLookOutputSchema,
+      annotations: IDEMPOTENT_WRITE,
+      _meta: toolMeta(deps2, "Releasing look version\u2026", "Look version released")
+    },
+    (args) => handleReleaseLook(deps2, args)
+  );
+  server2.registerTool(
+    "describe_look",
+    {
+      title: "Describe look fields",
+      description: "The styling field catalog + defaults (device/camera, background, captions, panel presets) for authoring a `style` or a full look from scratch.",
+      inputSchema: describeLookShape,
+      outputSchema: describeLookOutputSchema,
+      annotations: READ_ONLY,
+      _meta: toolMeta(deps2, "Reading look field catalog\u2026", "Look field catalog read")
+    },
+    () => handleDescribeLook()
+  );
+  server2.registerTool(
+    "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. Uploading one batch per App Store locale? Tag each batch with `locale` (echoed back for your bookkeeping).",
+      inputSchema: requestScreenshotUploadShape,
+      outputSchema: requestScreenshotUploadOutputSchema,
+      annotations: ADDITIVE_WRITE,
+      _meta: toolMeta(deps2, "Preparing screenshot uploads\u2026", "Screenshot uploads ready")
+    },
+    (args) => handleRequestScreenshotUpload(deps2, args)
+  );
+  server2.registerTool(
+    "import_screenshot",
+    {
+      title: "Import attached screenshot",
+      description: "Import one PNG the user attached in ChatGPT and return an account-scoped ShotOps `ref`. Use the ref in render_strip/emit_bundle, or use it with its filename in render_project. The attachment bytes move server-to-server and never enter model context.",
+      inputSchema: importScreenshotShape,
+      outputSchema: importScreenshotOutputSchema,
+      annotations: ADDITIVE_WRITE,
+      _meta: toolMeta(deps2, "Importing attached screenshot\u2026", "Attached screenshot imported", {
+        "openai/fileParams": ["file"]
+      })
+    },
+    (args) => handleImportScreenshot(deps2, args)
+  );
+  server2.registerTool(
+    "delete_assets",
+    {
+      title: "Delete uploaded assets",
+      description: "Permanently delete private, account-scoped screenshot, rendered-panel, or generated-bundle refs previously returned by ShotOps. This cannot delete another account\u2019s files or public share-link objects. Saved projects that reference a deleted screenshot may render it as missing. This action is irreversible.",
+      inputSchema: deleteAssetsShape,
+      outputSchema: deleteAssetsOutputSchema,
+      annotations: IDEMPOTENT_DESTRUCTIVE_WRITE,
+      _meta: toolMeta(deps2, "Deleting ShotOps assets\u2026", "ShotOps assets deleted")
+    },
+    (args) => handleDeleteAssets(deps2, args)
+  );
+}
+
+// src/env.ts
+import { existsSync } from "node:fs";
+import { URL as NodeUrl, fileURLToPath } from "node:url";
+var rootEnvLocal = fileURLToPath(new NodeUrl("../../.env.local", import.meta.url));
+if (existsSync(rootEnvLocal)) {
+  try {
+    process.loadEnvFile(rootEnvLocal);
+  } catch {
+  }
+}
+function studioOrigin() {
+  return (process.env.STUDIO_ORIGIN || "https://storeframe-studio.vercel.app").replace(/\/+$/, "");
+}
+
+// src/renderer.ts
+import { chromium } from "playwright";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// ../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", "clearcoat"];
+function coerceShotLook(raw) {
+  if (!raw || typeof raw !== "object") return {};
+  const out = { ...raw };
+  for (const f of NUMERIC_STRING_FIELDS) {
+    if (typeof out[f] === "number") out[f] = String(out[f]);
+  }
+  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;
+  sourceOrder.forEach((sourceId, i) => {
+    const target = targetIds[i];
+    if (target !== void 0 && record[sourceId] !== void 0) out[target] = record[sourceId];
+  });
+  return out;
+}
+function stripFromSlots(input) {
+  const slotSizes = input.slotSizes.filter((n) => Number.isInteger(n) && n > 0);
+  const panelIds = slotSizes.map((_, i) => `panel-${i + 1}`);
+  let captionLayers = {};
+  const opaque = input.look && typeof input.look === "object" ? input.look : null;
+  const style2 = input.style ?? null;
+  const opaqueShots = opaque && Array.isArray(opaque.shots) ? opaque.shots : [];
+  const hasOpaqueShots = opaqueShots.length > 0;
+  const styleShotLook = style2 ? coerceShotLook(style2.shotLook) : null;
+  const shots = [];
+  let globalIdx = 0;
+  slotSizes.forEach((phoneCount, slotIdx) => {
+    for (let k = 0; k < phoneCount; k++) {
+      const base = hasOpaqueShots ? coerceShotLook(opaqueShots[globalIdx]?.look ?? opaqueShots[0]?.look ?? {}) : styleShotLook ?? {};
+      const hOffset = base.hOffset !== void 0 && base.hOffset !== null ? String(base.hOffset) : staggeredHOffset(k);
+      shots.push({ panelId: panelIds[slotIdx], look: { ...DEFAULT_LOOK, ...base, hOffset } });
+      globalIdx++;
+    }
+  });
+  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 (opaque) {
+    bgMode = opaque.bgMode === "perPanel" ? "perPanel" : "gradient";
+    if (typeof opaque.gradientFrom === "string") gradientFrom = opaque.gradientFrom;
+    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(normalizeCaptionLayerStyles(opaque.captionStyles), sourceOrder, panelIds);
+    panelBackgrounds = remapByOrdinal(normalizePanelBackgrounds(opaque.panelBackgrounds), sourceOrder, panelIds);
+  } else if (style2) {
+    const bg = style2.background ?? {};
+    bgMode = bg.mode === "perPanel" ? "perPanel" : "gradient";
+    if (typeof bg.gradientFrom === "string") gradientFrom = bg.gradientFrom;
+    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;
+      });
+    }
+  }
+  if (style2 && Array.isArray(style2.captions)) {
+    const rawStyles = {};
+    const inner = {};
+    style2.captions.forEach((entry, i) => {
+      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 } : {} };
+        }
+      }
+    });
+    const localeLayers = normalizeCaptionText({ [DEFAULT_LOCALE]: inner }, normalizeCaptionStyles(rawStyles));
+    captionStyles = captionStylesFromLayers(localeLayers);
+    captionLayers = resolveCaptionText(localeLayers);
+  }
+  const panelPresetId2 = input.panelPresetId ?? (typeof opaque?.panelPresetId === "string" ? opaque.panelPresetId : void 0) ?? "r69";
+  return {
+    look: {
+      panelPresetId: panelPresetId2,
+      bgMode,
+      gradientFrom,
+      gradientTo,
+      gradientDir,
+      panelColors,
+      shadow,
+      floorReflection,
+      panelBackgrounds,
+      captionStyles,
+      shots
+    },
+    panelIds,
+    captionText: captionLayers
+  };
+}
+
+// ../mockup-engine/recordFromStrip.ts
+function normalizeSourceName(raw) {
+  const name = raw?.trim();
+  if (!name) return null;
+  return /\.(png|jpe?g|webp)$/i.test(name) ? name : `${name}.png`;
+}
+function frameNamesFor(shots, shotNames) {
+  const seen = /* @__PURE__ */ new Map();
+  return shots.map((_, i) => {
+    const real = normalizeSourceName(shotNames?.[i]);
+    if (!real) return `screen-${i + 1}.png`;
+    const count = seen.get(real) ?? 0;
+    seen.set(real, count + 1);
+    if (count === 0) return real;
+    const dot = real.lastIndexOf(".");
+    return `${real.slice(0, dot)}-${count + 1}${real.slice(dot)}`;
+  });
+}
+function recordFromStrip(input) {
+  const { look: look2, panelIds, captionText, locale: locale2, shotNames } = input;
+  const panels = panelIds.map((id) => ({ id }));
+  const frameNames = frameNamesFor(look2.shots, shotNames);
+  const shots = look2.shots.map((s, i) => ({
+    id: `shot-${i + 1}`,
+    panelId: s.panelId,
+    frameNodeId: frameNames[i],
+    frameName: frameNames[i],
+    bytes: null,
+    look: s.look,
+    thumb: null,
+    thumbStale: true
+  }));
+  return serializeProject({
+    shots,
+    panels,
+    selectedShotId: shots[0]?.id ?? null,
+    panelPresetId: look2.panelPresetId,
+    bgMode: look2.bgMode,
+    gradientFrom: look2.gradientFrom,
+    gradientTo: look2.gradientTo,
+    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.
+    captionText: captionText && Object.keys(captionText).length > 0 ? { [locale2 || DEFAULT_LOCALE]: captionText } : {}
+  });
+}
+
+// src/staticServer.ts
+import { createServer } from "node:http";
+import { readFile as readFile2 } from "node:fs/promises";
+import { extname, join, relative, isAbsolute } from "node:path";
+var MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".glb": "model/gltf-binary",
+  ".woff2": "font/woff2",
+  ".woff": "font/woff",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".wasm": "application/wasm"
+};
+async function startStaticServer(rootDir) {
+  const server2 = createServer((req, res) => {
+    const reqPath = decodeURIComponent((req.url ?? "/").split("?")[0]);
+    const rel = reqPath === "/" ? "index.html" : reqPath.replace(/^\/+/, "");
+    const filePath = join(rootDir, rel);
+    const within = relative(rootDir, filePath);
+    if (within.startsWith("..") || isAbsolute(within)) {
+      res.statusCode = 403;
+      res.end("forbidden");
+      return;
+    }
+    readFile2(filePath).then(
+      (body) => {
+        res.statusCode = 200;
+        res.setHeader("Content-Type", MIME[extname(filePath).toLowerCase()] ?? "application/octet-stream");
+        res.end(body);
+      },
+      () => {
+        res.statusCode = 404;
+        res.end("not found");
+      }
+    );
+  });
+  await new Promise((resolve, reject) => {
+    server2.once("error", reject);
+    server2.listen(0, "127.0.0.1", resolve);
+  });
+  const addr = server2.address();
+  return {
+    url: `http://127.0.0.1:${addr.port}/`,
+    close: () => new Promise((resolve) => {
+      server2.close(() => resolve());
+    })
+  };
+}
+
+// src/renderer.ts
+var StripRenderer = class {
+  serveMode;
+  vite = null;
+  staticServer = null;
+  browser = null;
+  page = null;
+  booting = null;
+  sawContextLost = false;
+  // Default 'vite' so `new StripRenderer()` (server.ts) keeps the hosted path byte-for-byte.
+  constructor(options = {}) {
+    this.serveMode = options.serve ?? "vite";
+  }
+  boot() {
+    if (!this.booting) {
+      this.booting = this.doBoot().catch((err) => {
+        this.booting = null;
+        throw err;
+      });
+    }
+    return this.booting;
+  }
+  async doBoot() {
+    const url = await this.startHarnessServer();
+    this.browser = await chromium.launch({ headless: true });
+    const page = await this.browser.newPage();
+    page.on("console", (m) => {
+      if (/CONTEXT_LOST|Context Lost/i.test(m.text())) this.sawContextLost = true;
+    });
+    await page.goto(url, { waitUntil: "load" });
+    await page.waitForFunction(() => window.__RENDER_READY === true, { timeout: 9e4 });
+    this.page = page;
+  }
+  // The one line that forks between hosted and local. Everything downstream (browser launch,
+  // the __RENDER_READY handshake, window.renderStrip, boot-retry, CONTEXT_LOST) is identical
+  // — the page is the same harness, only its bytes come from a different server.
+  async startHarnessServer() {
+    if (this.serveMode === "static") {
+      const rootDir = fileURLToPath2(new URL("../harness-dist", import.meta.url));
+      this.staticServer = await startStaticServer(rootDir);
+      return this.staticServer.url;
+    }
+    const configFile = fileURLToPath2(new URL("../vite.config.mjs", import.meta.url));
+    const { createServer: createServer2 } = await import("vite");
+    this.vite = await createServer2({ configFile });
+    await this.vite.listen();
+    const addr = this.vite.httpServer?.address();
+    const port = this.vite.config.server.port || (addr && typeof addr === "object" ? addr.port : 0);
+    return `http://localhost:${port}/`;
+  }
+  // buildRecord: the SAME styling seam the render uses (stripFromSlots → recordFromStrip), run
+  // in Node with NO browser. Both are pure, browser-free @engine functions and a record carries
+  // no bytes, so save_project persists an editable project without a multi-second Chromium render
+  // — the fix for the Fly proxy timeout on that path. Kept byte-for-byte aligned with the
+  // harness's buildRecord branch (render.js): same stripFromSlots call, same recordFromStrip
+  // args — so a save_project record matches a render({buildRecord:true}) record exactly.
+  async buildRecord(input) {
+    const { look: look2, panelIds, captionText } = stripFromSlots({
+      slotSizes: input.slotSizes,
+      panelPresetId: input.panelPresetId,
+      look: input.look ?? void 0,
+      style: input.style ?? void 0
+    });
+    return recordFromStrip({
+      look: look2,
+      panelIds,
+      captionText,
+      locale: input.locale,
+      shotNames: input.screenshotNames
+    });
+  }
+  async render(input) {
+    await this.boot();
+    if (!this.page) return { ok: false, error: "renderer failed to boot" };
+    const result = await this.page.evaluate((inp) => window.renderStrip(inp), input);
+    if (this.sawContextLost) {
+      console.warn("[renderer] CONTEXT_LOST observed since boot");
+    }
+    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(() => {
+    });
+    await this.browser?.close().catch(() => {
+    });
+    await this.vite?.close().catch(() => {
+    });
+    await this.staticServer?.close().catch(() => {
+    });
+    this.page = null;
+    this.browser = null;
+    this.vite = null;
+    this.staticServer = null;
+    this.booting = null;
+  }
+};
+
+// src/hostedBridge.ts
+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: "shotops-mcp",
+  version: "0.5.0",
+  private: false,
+  type: "module",
+  description: "The bundle-emitting MCP server over the @engine/@sync spine. Exposes ShotOps tools to ChatGPT, Claude Code, Cursor, and CI over Streamable HTTP with OAuth or personal 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 shotops-mcp`) \u2014 same render, on your own machine, no account needed.",
+  license: "UNLICENSED",
+  bin: {
+    "shotops-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",
+    tsx: "^4.23.0",
+    zod: "^3.25.76"
+  },
+  devDependencies: {
+    "@types/express": "^5.0.6",
+    esbuild: "^0.28.1",
+    pixelmatch: "^7.2.0",
+    pngjs: "^7.0.0",
+    typescript: "^5.6.0",
+    vite: "^5.4.0"
+  }
+};
+
+// src/version.ts
+var VERSION = package_default.version;
+
+// src/hostedBridge.ts
+var DEFAULT_HOSTED_MCP_URL = "https://shotops-mcp.fly.dev/mcp";
+function hostedMcpUrl() {
+  return (process.env.SHOTOPS_MCP_URL || DEFAULT_HOSTED_MCP_URL).replace(/\/+$/, "");
+}
+async function callRemoteTool(client, name, args) {
+  const result = await client.callTool({ name, arguments: args });
+  const text = result.content?.find((c) => c.type === "text")?.text;
+  if (result.isError) throw new Error(text || `${name} failed`);
+  if (!text) throw new Error(`${name} returned no content`);
+  return JSON.parse(text);
+}
+function localSourceDir(screenshots2) {
+  if (!Array.isArray(screenshots2)) return void 0;
+  const dirs = /* @__PURE__ */ new Set();
+  for (const slot2 of screenshots2) {
+    if (!Array.isArray(slot2)) continue;
+    for (const entry of slot2) {
+      if (entry && typeof entry === "object" && "path" in entry && typeof entry.path === "string") {
+        dirs.add(dirname(entry.path));
+      }
+    }
+  }
+  return dirs.size === 1 ? [...dirs][0] : void 0;
+}
+async function callSaveProject(client, ctx, extra) {
+  const res = await callRemoteTool(client, "save_project", {
+    screenshots: ctx?.screenshots,
+    panelPresetId: ctx?.panelPresetId,
+    look: ctx?.look,
+    style: ctx?.style,
+    locale: ctx?.locale,
+    sourceDir: ctx?.sourceDir ?? localSourceDir(ctx?.screenshots),
+    ...extra
+  });
+  return { id: res.projectId };
+}
+async function connectHostedBridge(token2) {
+  const client = new Client({ name: "shotops-mcp-local-bridge", version: VERSION }, { capabilities: {} });
+  const transport = new StreamableHTTPClientTransport(new URL(hostedMcpUrl()), {
+    requestInit: { headers: { Authorization: `Bearer ${token2}` } }
+  });
+  await client.connect(transport);
+  return {
+    async resolveProject(_userId, projectId) {
+      const res = await callRemoteTool(client, "read_look", projectId ? { project: projectId } : {});
+      const project2 = res.project;
+      if (!project2?.id) return null;
+      return {
+        id: project2.id,
+        name: typeof project2.name === "string" ? project2.name : "My project",
+        heldVersion: typeof res.heldVersion === "number" ? res.heldVersion : null
+      };
+    },
+    async readLook(projectId) {
+      const res = await callRemoteTool(client, "read_look", { project: projectId });
+      if (!res.saved) return null;
+      return {
+        look: res.look,
+        sourceName: typeof res.sourceName === "string" ? res.sourceName : null,
+        updatedAt: typeof res.updatedAt === "string" ? res.updatedAt : null,
+        version: typeof res.version === "number" ? res.version : 0
+      };
+    },
+    async readVersion() {
+      return null;
+    },
+    async listVersions(projectId) {
+      const res = await callRemoteTool(client, "read_look", { project: projectId });
+      return Array.isArray(res.versions) ? res.versions : [];
+    },
+    async setHeldVersion(projectId, version2) {
+      if (version2 === null) await callRemoteTool(client, "release_look", { project: projectId });
+      else await callRemoteTool(client, "hold_look", { project: projectId, version: version2 });
+    },
+    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,
+        look: look2,
+        ...sourceName ? { sourceName } : {}
+      });
+      return { version: res.version };
+    },
+    async createProject(_userId, projectName2, _record, ctx) {
+      return callSaveProject(client, ctx, { projectName: projectName2 });
+    },
+    async updateProjectRecord(projectId, _record, ctx) {
+      await callSaveProject(client, ctx, { project: projectId });
+    },
+    async close() {
+      await client.close();
+    }
+  };
+}
+
+// src/localDeps.ts
+var SIGN_IN = "not available in local (free) mode \u2014 connect the hosted ShotOps MCP and sign in for saved looks, editable projects, and share links.";
+var SHARE_LINK_NOT_BRIDGED = `Creating a share link is ${SIGN_IN} (bridging this needs a hosted rendering step, which local mode deliberately avoids \u2014 connect directly to the hosted MCP for share links.)`;
+function localToolDeps(token2) {
+  const base = {
+    renderer: new StripRenderer({ serve: "static" }),
+    requestScreenshotUpload: async () => {
+      throw new Error(
+        'request_screenshot_upload is not available in local mode \u2014 local mode reads screenshots straight off disk: pass { "path": "/abs/or/relative/path.png" } screenshot entries instead.'
+      );
+    },
+    allowLocalScreenshots: true,
+    forceOutput: "inline",
+    // no Supabase storage locally to upload an `output: "urls"` result to
+    studioOrigin: studioOrigin()
+  };
+  if (!token2) {
+    return {
+      ...base,
+      resolveProject: async () => null,
+      readLook: async () => null,
+      readVersion: async () => null,
+      listVersions: async () => [],
+      setHeldVersion: async () => {
+        throw new Error(`Holding a look version is ${SIGN_IN}`);
+      },
+      readProjectRecord: async () => null,
+      saveLook: async () => {
+        throw new Error(`Saving a look is ${SIGN_IN}`);
+      },
+      createProject: async () => {
+        throw new Error(`Saving an editable project is ${SIGN_IN}`);
+      },
+      updateProjectRecord: async () => {
+        throw new Error(`Updating a saved project is ${SIGN_IN}`);
+      },
+      createShareLink: async () => {
+        throw new Error(`Creating a share link is ${SIGN_IN}`);
+      }
+    };
+  }
+  const hostedToken = token2;
+  let bridgePromise = null;
+  function bridge() {
+    if (!bridgePromise) {
+      bridgePromise = connectHostedBridge(hostedToken).catch((err) => {
+        bridgePromise = null;
+        throw new Error(
+          `could not reach the hosted ShotOps MCP (${err.message}) \u2014 check SHOTOPS_TOKEN / network, or drop the token to use local-only mode.`
+        );
+      });
+    }
+    return bridgePromise;
+  }
+  return {
+    ...base,
+    resolveProject: async (userId, projectId) => (await bridge()).resolveProject(userId, projectId),
+    readLook: async (projectId) => (await bridge()).readLook(projectId),
+    readVersion: async (projectId, version2) => (await bridge()).readVersion(projectId, version2),
+    listVersions: async (projectId) => (await bridge()).listVersions(projectId),
+    setHeldVersion: async (projectId, version2) => (await bridge()).setHeldVersion(projectId, version2),
+    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),
+    createShareLink: async () => {
+      throw new Error(SHARE_LINK_NOT_BRIDGED);
+    },
+    closeBridge: async () => {
+      if (bridgePromise) await (await bridgePromise).close().catch(() => {
+      });
+    }
+  };
+}
+
+// src/local.ts
+function tokenFromArgv(argv) {
+  const eq = argv.find((a) => a.startsWith("--token="));
+  if (eq) return eq.slice("--token=".length);
+  const idx = argv.indexOf("--token");
+  return idx !== -1 ? argv[idx + 1] : void 0;
+}
+var token = tokenFromArgv(process.argv.slice(2)) || process.env.SHOTOPS_TOKEN || void 0;
+var deps = localToolDeps(token);
+var localInstructions = token ? `${SERVER_INSTRUCTIONS}
+
+## Local mode (this connection)
+Rendering runs on THIS machine \u2014 free, no timeout ceiling. A hosted token is configured, so save_project / read_look / save_look also work (they read/write your hosted ShotOps account); request_screenshot_upload and import_screenshot still no-op \u2014 pass local files as { "path": "..." } screenshot entries instead.` : `${SERVER_INSTRUCTIONS}
+
+## 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"); request_screenshot_upload and import_screenshot are hosted-only \u2014 pass local files as { "path": "..." } screenshot entries and render_strip / emit_bundle work fully.`;
+var server = new McpServer(
+  { name: "shotops-mcp-local", version: VERSION },
+  { instructions: localInstructions }
+);
+registerTools(server, { userId: "local", ...deps });
+async function shutdown() {
+  await deps.renderer.close();
+  await deps.closeBridge?.();
+  process.exit(0);
+}
+process.on("SIGINT", () => void shutdown());
+process.on("SIGTERM", () => void shutdown());
+await server.connect(new StdioServerTransport());
+console.error(
+  `[shotops-mcp-local] connected over stdio \u2014 renders run on this machine.${token ? " (hosted bridge configured)" : ""}`
+);