storeframe-mcp 0.1.0

package/dist/local.js

@@ -0,0 +1,1674 @@
+#!/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/fastlaneBundle.ts
+import { strToU8, zipSync } from "fflate";
+var DELIVERFILE_TEMPLATE = `# Generated by Storeframe Studio \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 Storeframe Studio 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 Storeframe.
+
+## Upload
+
+\`\`\`
+cd <this folder>
+fastlane deliver
+\`\`\`
+
+Fastlane will:
+
+1. Ask you to sign in (Apple ID with 2FA, or an App Store Connect API key if you have
+   fastlane configured with one).
+2. Detect the device size automatically from the image dimensions.
+3. 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 Storeframe with the right Bundle ID.
+- **Screenshots land under the wrong language** \u2014 re-export with the right locale; the
+  folder name under \`fastlane/screenshots/\` is the App Store locale code.
+- **Wrong order in the store** \u2014 the \`NN_\` prefix controls order; re-arrange the strip in
+  Storeframe and re-export rather than renaming files by hand.
+`;
+function render(template, vars) {
+  return template.replace(/\{\{(\w+)\}\}/g, (match, key) => vars[key] ?? match);
+}
+function generateDeliverfile(opts) {
+  return render(DELIVERFILE_TEMPLATE, { BUNDLE_ID: opts.bundleId });
+}
+function generateBundleReadme(opts) {
+  return render(README_TEMPLATE, {
+    BUNDLE_ID: opts.bundleId,
+    LOCALE: opts.locale,
+    PANEL_LABEL: opts.panelLabel,
+    COUNT: String(opts.count)
+  });
+}
+function screenshotFilename(index) {
+  return `${String(index).padStart(2, "0")}_storeframe.png`;
+}
+function bundleZipFilename(projectName2) {
+  const slug = projectName2.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return `${slug || "storeframe"}-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 });
+}
+
+// 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 };
+}
+
+// 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 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 storeframe-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 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 screenshotEntry = z.union([
+  z.string().min(1).describe('Inline base64-encoded PNG (no "data:" prefix). Small payloads only.'),
+  z.object({ ref: z.string().min(1), name: nameField }).strict().describe("A ref returned by request_screenshot_upload \u2014 resolved server-side, never re-sent inline."),
+  z.object({ url: z.string().min(1), name: nameField }).strict().describe("An https URL to a PNG \u2014 fetched server-side (image/png, no redirects, ~20MB cap)."),
+  z.object({ path: z.string().min(1), name: nameField }).strict().describe(
+    "A local filesystem path to a PNG, read straight off disk \u2014 ONLY available over the local stdio server (npx storeframe-mcp); the hosted server rejects this entry shape."
+  )
+]);
+var screenshotsDescription = 'An array of App Store slots in display order (1\u201310; the store allows up to 10 per size). Each slot is itself an array of screenshots: one entry = one phone in that slot, several entries = multiple phones composited into that one slot. Each screenshot entry is EITHER an inline base64 PNG string (small payloads only \u2014 large inline payloads are rejected with a clear error), OR { "ref": "..." } from request_screenshot_upload, OR { "url": "https://..." }, OR (local stdio mode only) { "path": "/abs/or/relative/path.png" } to read a file straight off disk. Prefer ref/url for real screenshots so the bytes never transit this conversation.';
+var 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 panelRefs = z.array(z.object({ ref: z.string().min(1) }).strict()).min(1).max(10).optional().describe(
+  'Pre-rendered panel refs from a prior render_strip call made with `output: "urls"` \u2014 packages them directly into the bundle WITHOUT rendering again. Mutually exclusive with `screenshots`; one of the two is required.'
+);
+var 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 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 look = z.record(z.string(), z.unknown()).optional().describe(
+  'A Storeframe "look" (styling only) JSON, exactly as returned by read_look, applied to the strip. Omit for default styling.'
+);
+var useSavedLook = z.boolean().optional().describe("If true, style the strip with the project's saved look (ignored when `look`/`style` is given).");
+var locale = z.string().optional().describe(
+  'App Store locale, e.g. "de-DE" (default en-US). Labels the render and, for emit_bundle, selects the fastlane screenshots folder. Does not select caption text \u2014 pass the copy for this locale yourself via `style.captions[].text` (see the README\'s `captions.<locale>.json` convention).'
+);
+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",
+  clayTone: "grey",
+  clayCustom: "B0B0B0",
+  flatScreen: false,
+  glare: false,
+  lighting: true,
+  reflections: false
+};
+var DEFAULT_CAPTION_STYLE = {
+  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."),
+  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.")
+}).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(),
+  captions: z.array(captionEntry.nullable()).max(10).optional().describe("One entry PER PANEL in slot order; null = no caption on that panel.")
+}).strict().optional().describe(
+  "Structured styling \u2014 the discoverable alternative to the opaque `look` param (call describe_look for the full field catalog + defaults). Wins over `look`/`useSavedLook`."
+);
+var project = z.string().min(1).optional().describe("The Storeframe 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 pinned version if one is pinned, else the latest saved look."
+);
+var createProjectFlag = z.boolean().optional().describe(
+  "Also save this render as an editable Storeframe Studio 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 "Storeframe 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,
+  look,
+  style,
+  useSavedLook,
+  project,
+  version,
+  locale,
+  preview,
+  output,
+  createProject: createProjectFlag,
+  projectName,
+  sourceDir
+};
+var emitBundleShape = {
+  screenshots: screenshotsOptional,
+  panels: panelRefs,
+  panelPresetId,
+  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,
+  projectName: z.string().optional().describe('A name for the bundle (used for the zip filename + any share link). Default "storeframe".'),
+  share: z.boolean().optional().describe(
+    "Also create an unguessable, 14-day share link to a landing page (preview + bundle download + fastlane how-to), attributed to your account. Default false."
+  ),
+  // 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 saveLookShape = {
+  project,
+  look: z.record(z.string(), z.unknown()).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 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",
+        cameraPos: "{ x, y, z } manual override, or null for the angle preset",
+        roll: "-45\u202645 (degrees, clock-hand tilt)",
+        phoneHeight: "20\u2026100 (% of panel height)",
+        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)",
+        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 },
+      fields: {
+        mode: "gradient | perPanel",
+        panelColors: 'per-panel hex colours (mode "perPanel"), one entry per slot in order'
+      }
+    },
+    captions: {
+      description: "One entry PER PANEL in slot order (null = no caption). Styling is part of the look; `text`/`subtitle` are per-RENDER input and are never stored (zero-custody of content).",
+      defaults: DEFAULT_CAPTION_STYLE,
+      fonts: CAPTION_FONT_IDS,
+      fields: {
+        sizePt: "font size in iOS points \u2014 preset-independent",
+        anchor: "{ x, y } normalized 0\u20131 position on the panel",
+        maxWidth: "wrap width as a 0\u20131 fraction of the panel width",
+        text: "the headline (per-render input)",
+        subtitle: "optional subtitle (per-render input)"
+      }
+    }
+  },
+  panelPresets: PANEL_PRESET_IDS.map((id) => ({ id, ...PANEL_DIMENSIONS[id], label: PANEL_LABELS[id] })),
+  notes: [
+    "Pass `style` to render_strip/emit_bundle for structured styling, or save a composed look with save_look and render with useSavedLook.",
+    "save_look bumps the look version; pinning a version is done in Storeframe Studio (the Look bar), and pinned projects render their pinned version by default."
+  ]
+};
+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.'
+  )
+};
+
+// src/tools.ts
+var SAVED_RECORD_VERSION = 2;
+function textResult(payload) {
+  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+}
+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) {
+  if (args.style != null) return { look: null, style: args.style };
+  if (args.look != null) return { look: args.look };
+  if (args.useSavedLook || args.version != null) {
+    const project2 = await deps2.resolveProject(deps2.userId, args.project);
+    if (!project2) {
+      return { look: null, note: "no matching Storeframe project found for this account \u2014 used default styling." };
+    }
+    const saved = await deps2.readLook(project2.id);
+    if (!saved) {
+      return { look: null, note: `no saved look on project "${project2.name}" \u2014 used default styling.` };
+    }
+    if (args.version != null) {
+      if (saved.pinned?.version === args.version) return { look: saved.pinned.look };
+      if (saved.version === args.version) return { look: saved.look };
+      return {
+        look: saved.look,
+        note: `version ${args.version} not found on project "${project2.name}" (latest is v${saved.version}${saved.pinned ? `, pinned is v${saved.pinned.version}` : ""}) \u2014 rendered the latest.`
+      };
+    }
+    if (project2.pinnedVersion != null && saved.pinned) {
+      return { look: saved.pinned.look, note: `rendered the pinned look v${saved.pinned.version} (M4).` };
+    }
+    return { look: saved.look };
+  }
+  return { look: null };
+}
+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 Storeframe project for this account." };
+      await deps2.updateProjectRecord(project2.id, wrapped, ctx);
+      projectId = project2.id;
+    } else {
+      const name = args.projectName?.trim() || "Storeframe 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 handleRenderStrip(deps2, args) {
+  const { look: look2, style: style2, note } = await resolveLook(deps2, args);
+  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).");
+  }
+  let screenshots2;
+  try {
+    screenshots2 = await resolveScreenshots(args.screenshots, 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,
+    preview: args.preview,
+    locale: locale2,
+    buildRecord: args.createProject === true,
+    // Phase 5A: only compute names when we're building a record (saving a project).
+    ...args.createProject ? { screenshotNames: resolveScreenshotNames(args.screenshots) } : {}
+  });
+  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,
+    ...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")
+    )
+  );
+}
+async function handleEmitBundle(deps2, args) {
+  if (!isValidBundleId(args.bundleId)) {
+    return errorResult(`invalid bundleId "${args.bundleId}" \u2014 expected reverse-DNS, e.g. com.acme.app`);
+  }
+  const locale2 = args.locale?.trim() || "en-US";
+  const projectName2 = args.projectName?.trim() || "storeframe";
+  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 bytesList;
+    try {
+      bytesList = await Promise.all(args.panels.map((p) => fetchUploadedRef(p.ref, deps2.userId)));
+    } catch (err) {
+      return errorResult(`failed to fetch panel ref: ${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 screenshots2;
+    try {
+      screenshots2 = await resolveScreenshots(args.screenshots, deps2.userId, deps2.allowLocalScreenshots ?? false);
+    } catch (err) {
+      return errorResult(err.message);
+    }
+    const resolved = await resolveLook(deps2, args);
+    note = resolved.note;
+    const result = await deps2.renderer.render({
+      screenshots: screenshots2,
+      panelPresetId: args.panelPresetId,
+      look: resolved.look,
+      style: resolved.style,
+      locale: locale2,
+      buildRecord: args.createProject === true,
+      ...args.createProject && args.screenshots ? { screenshotNames: resolveScreenshotNames(args.screenshots) } : {}
+    });
+    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 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 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.");
+  }
+  const screenshotNames = resolveScreenshotNames(args.screenshots).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 Storeframe 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 Storeframe project on this account yet \u2014 open Storeframe Studio 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 Storeframe Studio 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,
+    pinnedVersion: project2.pinnedVersion,
+    // null = renders follow the latest version
+    look: saved.look
+  });
+}
+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 Storeframe project on this account yet \u2014 open Storeframe Studio 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 { 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 pin it in Storeframe Studio.`
+  });
+}
+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);
+  }
+  return textResult({
+    ok: true,
+    slots,
+    instructions: 'PUT each screenshot\'s raw PNG bytes to its uploadUrl, e.g.: curl -T screenshot.png "<uploadUrl>" \u2014 then pass { "ref": "<the matching ref>" } as that screenshot\'s entry in render_strip/emit_bundle\'s `screenshots` array. If you passed `names`, that ref already carries its filename \u2014 no need to also set `name` on the screenshot entry. Uploads are not auto-purged yet \u2014 treat refs as short-lived and single-use.'
+  });
+}
+var SERVER_INSTRUCTIONS = [
+  "Storeframe 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. 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.',
+  "",
+  "## 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.",
+  "",
+  "## Styling \u2014 you can fully art-direct the strip via the `style` object",
+  "Call describe_look for the exact field catalog + defaults; this is the map of what to reach for.",
+  "Three groups (all optional \u2014 omit for a sensible dark default):",
+  "- style.shotLook (the device, same for every phone): angle (front|left|right), material",
+  "  (real|clay), colorway (orange|blue|silver|custom+customColor), finish (0 matte\u20261 glossy),",
+  "  roll (-45\u202645\xB0 tilt), phoneHeight (20\u2026100 % of panel), hOffset/vOffset to nudge position,",
+  "  glare, reflections, lighting, flatScreen.",
+  "- style.background (the strip): mode gradient|perPanel; gradientFrom/gradientTo (hex),",
+  "  gradientDir vertical|horizontal, shadow; or panelColors[] (one hex per slot) for perPanel.",
+  "- style.captions[] (ONE entry per panel, in slot order; null = no caption): text (headline),",
+  "  subtitle, fontId (inter|manrope|poppins|fraunces|space-grotesk), sizePt, color (hex),",
+  "  align, anchor {x,y} (0\u20131 position), maxWidth (0\u20131 fraction of panel width).",
+  "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).",
+  "",
+  "## Caption guardrails (do this or captions crowd \u2014 the #1 first-render mistake)",
+  'Defaults are fontId "inter", sizePt 44, anchor {x:0.5, y:0.06} (near the top), maxWidth 0.86.',
+  "At 44pt a headline longer than ~15\u201318 characters WRAPS to two lines, and with a subtitle the",
+  "two then collide at the top of the panel. To keep it clean:",
+  "- Keep headlines SHORT (aim \u2264 ~18 chars) so they stay one line; or drop sizePt to ~36\u201340 if",
+  "  they must be longer; or raise maxWidth toward 1.0 to reduce wrapping.",
+  "- If you use a subtitle, give the block room: lower the phone a little (shotLook.phoneHeight",
+  "  ~64\u201368) and/or set the caption anchor slightly higher (anchor.y ~0.04). Preview and LOOK at",
+  "  the result before finalizing \u2014 a crowded headline+subtitle is the most common bad first pass.",
+  '- Punchy, benefit-led headlines read best ("Track every throw", "See your stats"), one idea',
+  "  per panel. A consistent fontId + color across all panels makes the strip feel designed.",
+  "",
+  "## 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).",
+  "",
+  "## 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 Storeframe Studio 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.",
+  "Storeframe 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",
+  "  Storeframe 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.",
+  "",
+  "## Refine visually, then re-render headlessly",
+  "A human can refine the look in Storeframe Studio (https://storeframe-studio.vercel.app \u2014 sign",
+  "in as the SAME account) and Save look; read_look then returns exactly that, so an agent",
+  "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");
+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. For real, full-resolution screenshots, call request_screenshot_upload first \u2014 inline base64 is for small payloads only. No store credential is involved \u2014 this only renders images.",
+      inputSchema: renderStripShape
+    },
+    (args) => handleRenderStrip(deps2, args)
+  );
+  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). Returns the zip `inline` or as a `url` for large payloads, and can also mint a 14-day share link to a landing page. YOU upload it with your own fastlane \u2014 this server never touches a store credential and never submits for review.',
+      inputSchema: emitBundleShape
+    },
+    (args) => handleEmitBundle(deps2, args)
+  );
+  server2.registerTool(
+    "save_project",
+    {
+      title: "Save as editable project",
+      description: "SAVE the strip as an editable Storeframe Studio 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
+    },
+    (args) => handleSaveProject(deps2, args)
+  );
+  server2.registerTool(
+    "read_look",
+    {
+      title: "Read saved look",
+      description: "Return a project's saved Storeframe look (styling only \u2014 no screenshots, no credentials), with its version and pin state. Feed the returned look back into render_strip/emit_bundle via the `look` field, or just pass `useSavedLook: true`.",
+      inputSchema: readLookShape
+    },
+    (args) => handleReadLook(deps2, args)
+  );
+  server2.registerTool(
+    "save_look",
+    {
+      title: "Save look",
+      description: "Persist a composed Storeframe 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
+    },
+    (args) => handleSaveLook(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
+    },
+    () => 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.",
+      inputSchema: requestScreenshotUploadShape
+    },
+    (args) => handleRequestScreenshotUpload(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 { createServer as createServer2 } from "vite";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// ../mockup-engine/appstore.ts
+var DEFAULT_LOOK = {
+  angle: "front",
+  cameraPos: null,
+  roll: "0",
+  phoneHeight: "72",
+  hOffset: "0",
+  vOffset: "0",
+  material: "real",
+  colorway: "silver",
+  customColor: "F5F5F5",
+  finish: "0",
+  clayTone: "grey",
+  clayCustom: "B0B0B0",
+  flatScreen: false,
+  glare: false,
+  lighting: true,
+  reflections: false
+};
+var DEFAULT_CAPTION_STYLE2 = {
+  fontId: "inter",
+  sizePt: 44,
+  color: "FFFFFF",
+  align: "center",
+  anchor: { x: 0.5, y: 0.06 },
+  maxWidth: 0.86
+};
+var DEFAULT_LOCALE = "en-US";
+function normalizeCaptionStyles(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const out = {};
+  for (const [panelId, entry] of Object.entries(raw)) {
+    if (!entry || typeof entry !== "object") continue;
+    const e = entry;
+    out[panelId] = {
+      ...DEFAULT_CAPTION_STYLE2,
+      ...e,
+      anchor: { ...DEFAULT_CAPTION_STYLE2.anchor, ...e.anchor && typeof e.anchor === "object" ? e.anchor : {} }
+    };
+  }
+  return out;
+}
+function normalizeFlatCaptionMap(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const out = {};
+  for (const [panelId, entry] of Object.entries(raw)) {
+    if (!entry || typeof entry !== "object") continue;
+    const e = entry;
+    if (typeof e.headline !== "string") continue;
+    out[panelId] = { headline: e.headline, ...typeof e.subtitle === "string" ? { subtitle: e.subtitle } : {} };
+  }
+  return out;
+}
+function normalizeCaptionText(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const entries = Object.entries(raw);
+  const looksFlat = entries.some(
+    ([, value]) => !!value && typeof value === "object" && typeof value.headline === "string"
+  );
+  if (looksFlat) return { [DEFAULT_LOCALE]: normalizeFlatCaptionMap(raw) };
+  const out = {};
+  for (const [locale2, inner] of entries) out[locale2] = normalizeFlatCaptionMap(inner);
+  return out;
+}
+function shotsInPanelOrder(shots, panels) {
+  return panels.flatMap((panel) => shots.filter((s) => s.panelId === panel.id));
+}
+var PROJECT_SCHEMA_VERSION = 2;
+function serializeProject(state) {
+  const ordered = shotsInPanelOrder(state.shots, state.panels);
+  const shots = ordered.map((s) => ({
+    id: s.id,
+    panelId: s.panelId,
+    frameNodeId: s.frameNodeId,
+    frameName: s.frameName,
+    look: s.look,
+    inputAnchor: s.inputAnchor,
+    // v2 provenance — persisted so drift survives reload
+    outputAnchor: s.outputAnchor
+  }));
+  return {
+    schema: PROJECT_SCHEMA_VERSION,
+    shots,
+    panels: state.panels,
+    selectedShotId: state.selectedShotId,
+    // Caption TEXT is content (C1): emitted here on the project record, deliberately NOT
+    // via extractStripStyle — so it can never leak into serializeLook's styling blob.
+    // normalizeCaptionText upgrades the flat v1 input to the locale-nested stored shape
+    // (flat → { [DEFAULT_LOCALE]: … }); a Phase-3 nested input passes through unchanged.
+    captionText: normalizeCaptionText(state.captionText),
+    ...extractStripStyle(state)
+  };
+}
+function extractStripStyle(state) {
+  return {
+    panelPresetId: state.panelPresetId,
+    bgMode: state.bgMode,
+    gradientFrom: state.gradientFrom,
+    gradientTo: state.gradientTo,
+    gradientDir: state.gradientDir,
+    panelColors: state.panelColors,
+    shadow: state.shadow,
+    captionStyles: state.captionStyles ?? {}
+  };
+}
+
+// ../mockup-engine/stripFromSlots.ts
+var FALLBACK_GRADIENT_FROM = "#1b1b2e";
+var FALLBACK_GRADIENT_TO = "#0a0a14";
+function staggeredHOffset(k) {
+  return String(Math.max(-100, Math.min(100, k * 35)));
+}
+var NUMERIC_STRING_FIELDS = ["roll", "phoneHeight", "hOffset", "vOffset", "finish"];
+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 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}`);
+  const captionText = {};
+  const opaque = !input.style && input.look && typeof input.look === "object" ? input.look : null;
+  const style2 = input.style ?? null;
+  const opaqueShots = opaque && Array.isArray(opaque.shots) ? opaque.shots : [];
+  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 = styleShotLook ?? coerceShotLook(opaqueShots[globalIdx]?.look ?? opaqueShots[0]?.look ?? {});
+      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 bgMode = "gradient";
+  let gradientFrom = FALLBACK_GRADIENT_FROM;
+  let gradientTo = FALLBACK_GRADIENT_TO;
+  let gradientDir = "vertical";
+  let shadow = true;
+  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 (Array.isArray(bg.panelColors)) {
+      bg.panelColors.forEach((color, i) => {
+        if (typeof color === "string" && color && panelIds[i] !== void 0) panelColors[panelIds[i]] = color;
+      });
+    }
+    if (Array.isArray(style2.captions)) {
+      const rawStyles = {};
+      style2.captions.forEach((entry, i) => {
+        if (!entry || typeof entry !== "object" || panelIds[i] === void 0) return;
+        const { text, subtitle, sizePt, maxWidth, ...rest } = entry;
+        rawStyles[panelIds[i]] = {
+          ...rest,
+          ...sizePt !== void 0 ? { sizePt: Number(sizePt) } : {},
+          ...maxWidth !== void 0 ? { maxWidth: Number(maxWidth) } : {}
+        };
+        if (typeof text === "string" && text.trim()) {
+          captionText[panelIds[i]] = {
+            headline: text,
+            ...typeof subtitle === "string" && subtitle ? { subtitle } : {}
+          };
+        }
+      });
+      captionStyles = normalizeCaptionStyles(rawStyles);
+    }
+  } else 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;
+    const sourceOrder = [];
+    for (const s of opaqueShots) {
+      const id = typeof s?.panelId === "string" ? s.panelId : null;
+      if (id && !sourceOrder.includes(id)) sourceOrder.push(id);
+    }
+    panelColors = remapByOrdinal(opaque.panelColors, sourceOrder, panelIds);
+    captionStyles = remapByOrdinal(normalizeCaptionStyles(opaque.captionStyles), sourceOrder, panelIds);
+  }
+  const panelPresetId2 = input.panelPresetId ?? (typeof opaque?.panelPresetId === "string" ? opaque.panelPresetId : void 0) ?? "r69";
+  return {
+    look: { panelPresetId: panelPresetId2, bgMode, gradientFrom, gradientTo, gradientDir, panelColors, shadow, captionStyles, shots },
+    panelIds,
+    captionText
+  };
+}
+
+// ../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,
+    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));
+    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;
+  }
+  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";
+var DEFAULT_HOSTED_MCP_URL = "https://storeframe-mcp.fly.dev/mcp";
+function hostedMcpUrl() {
+  return (process.env.STOREFRAME_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: "storeframe-mcp-local-bridge", version: "0.1.0" }, { 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",
+        pinnedVersion: typeof res.pinnedVersion === "number" ? res.pinnedVersion : 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,
+        pinned: null
+        // known gap — see the module comment above.
+      };
+    },
+    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 Storeframe 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,
+      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 Storeframe MCP (${err.message}) \u2014 check STOREFRAME_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),
+    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.STOREFRAME_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 Storeframe account); request_screenshot_upload still no-ops \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") \u2014 pass local files as { "path": "..." } screenshot entries and render_strip / emit_bundle work fully.`;
+var server = new McpServer(
+  { name: "storeframe-mcp-local", version: "0.1.0" },
+  { 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(
+  `[storeframe-mcp-local] connected over stdio \u2014 renders run on this machine.${token ? " (hosted bridge configured)" : ""}`
+);