shotops-mcp 0.9.8 → 0.9.9

package/dist/local.js

@@ -24,7 +24,7 @@
   }
   await visit('')
   return hash.digest('hex')
-})(sourceDirectory) !== "7345df8a318a3c0989195e1b9c4ce91f2eaf136e27afd8ee123620da60c23410") {
+})(sourceDirectory) !== "726565c5a58fb0cf9d366865195f22440699f6a55c8789edcd92577fc682ebbf") {
           console.error('shotops-mcp: dist/local.js is stale; run npm run build in shotops-mcp.');
         }
       } catch { /* An unreadable checkout must not break an otherwise working CLI. */ }
@@ -140,10 +140,15 @@ var init_devices = __esm({
 });
 
 // ../mockup-engine/appstore/catalog/caption.ts
-var CAPTION_STYLE_BOUNDS;
+var CAPTION_STYLE_DEFAULTS, CAPTION_STYLE_BOUNDS;
 var init_caption = __esm({
   "../mockup-engine/appstore/catalog/caption.ts"() {
     "use strict";
+    CAPTION_STYLE_DEFAULTS = {
+      lineHeight: 1.2,
+      bandInset: 0.06,
+      bandCenter: 0.5
+    };
     CAPTION_STYLE_BOUNDS = {
       sizePt: { min: 20, max: 120 },
       maxWidth: { min: 0.1, max: 1 },
@@ -1908,7 +1913,7 @@ var init_resultContract = __esm({
       { code: "render_failed", test: /^render failed|^renderer returned / },
       { code: "payload_too_large", test: /inline-response ceiling|is too large/ },
       { code: "storage_failed", test: /could not store the rendered panels|could not create share link/ },
-      { code: "asset_not_found", test: /failed to read panel|no preview image available|does not belong to this account/ },
+      { code: "asset_not_found", test: /failed to read panel|no preview image available|does not belong to this account|no screenshot was ever uploaded for ref/ },
       { code: "persistence_failed", test: /could not build the project record|no project record was produced/ },
       { code: "quota_exhausted", test: /not enough credits|credit balance|wallet is empty/ },
       // Input-shape complaints raised by a HANDLER rather than by the schema. Last, and each anchored
@@ -3179,7 +3184,7 @@ function clampCaptionBounds(input) {
 }
 function captionClampNote(clamps) {
   if (clamps.length === 0) return void 0;
-  const said = clamps.map((clamp) => `${clamp.field} ${clamp.submitted} \u2192 ${clamp.stored}`).join("; ");
+  const said = clamps.map((clamp2) => `${clamp2.field} ${clamp2.submitted} \u2192 ${clamp2.stored}`).join("; ");
   return `Caption values outside the supported range were stored at the bound (${said}) \u2014 sizePt is ${captionBoundText("sizePt")} and maxWidth ${captionBoundText("maxWidth")}, the same range the ShotOps caption controls offer, so nothing here is unreachable in the app.`;
 }
 function rangeIssueMessage(field, raw) {
@@ -4229,7 +4234,7 @@ var init_schemas = __esm({
     flatScreenshots = z5.array(screenshotEntry).min(1).max(10).describe("Preferred: one screenshot entry per App Store panel, in display order.");
     groupedScreenshots = z5.array(slot).min(1).max(10).describe("Advanced: one nested slot per panel; put several screenshot entries in a slot for a multi-phone panel.");
     screenshots = z5.union([flatScreenshots, groupedScreenshots]).describe(screenshotsDescription);
-    screenshotsForSaveDescription = `${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).`;
+    screenshotsForSaveDescription = `${screenshotsDescription} NOTE: save_project does not render and never fetches image bytes. It uses each slot's SHAPE (phones per panel), each entry's \`name\` (source filename, for re-load matching) and each { "ref" }, per-locale ones included, which it records on that entry's own frame so the project reopens with that screenshot. A ref that is not an upload under this account refuses the whole save, naming it, and nothing is written. Pass the same entries you rendered with (esp. their \`name\`s).`;
     screenshotsForSave = screenshots.describe(screenshotsForSaveDescription);
     screenshotsOptionalDescription = `${screenshotsDescription} Required unless \`panels\` (pre-rendered refs) is given instead.`;
     screenshotsOptional = screenshots.optional().describe(screenshotsOptionalDescription);
@@ -5465,11 +5470,11 @@ function previewUsage(deps, snapshot) {
     ...credits ? publicCreditBalance(credits) : {}
   };
 }
-function statusMessage(deps, snapshot, step) {
-  if (step === "none") {
+function statusMessage(deps, snapshot, step2) {
+  if (step2 === "none") {
     return "This connection can produce store-ready output: full-resolution render_strip and render_project, and every emit_bundle form." + (isLocal(deps) ? " Local rendering spends no cloud credits." : "");
   }
-  if (step === "sign_in" && !snapshot.authenticated && deps.anonymous) {
+  if (step2 === "sign_in" && !snapshot.authenticated && deps.anonymous) {
     return `This connection is not signed in. It can import screenshots and render up to ${ANONYMOUS.attempts} preview strips of up to ${ANONYMOUS.maxPanels} panels each per ${Math.round(ANONYMOUS.windowSeconds / 86400)} days. ` + productionDenialMessage(snapshot.productionExport, deps);
   }
   return productionDenialMessage(snapshot.productionExport, deps);
@@ -5620,7 +5625,7 @@ function operationSupported(deps, tool, account) {
 async function handleAccountStatus(deps) {
   const snapshot = await readSnapshot(deps);
   const decision = snapshot.productionExport;
-  const step = accountNextStep(decision);
+  const step2 = accountNextStep(decision);
   return textResult({
     ok: true,
     connection: isLocal(deps) ? "local" : "hosted",
@@ -5646,8 +5651,8 @@ async function handleAccountStatus(deps) {
       ...decision.allowed ? {} : { reason: decision.reason },
       ...decision.allowed || !decision.requiredPlan ? {} : { requiredPlan: decision.requiredPlan }
     },
-    nextStep: step,
-    message: statusMessage(deps, snapshot, step),
+    nextStep: step2,
+    message: statusMessage(deps, snapshot, step2),
     // #662 — the capability half: accepted inputs, delivery modes, retention classes, operation
     // support, the cost model and the closed failure catalog. Additive; every field above is
     // exactly what it was.
@@ -6167,6 +6172,20 @@ var init_panel = __esm({
   }
 });
 
+// ../mockup-engine/storagePath.ts
+function isSafeStoragePath(path) {
+  if (path.length === 0 || path.startsWith("/") || UNSAFE_CHARACTER.test(path)) return false;
+  const body = path.endsWith("/") ? path.slice(0, -1) : path;
+  return body.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}
+var UNSAFE_CHARACTER;
+var init_storagePath = __esm({
+  "../mockup-engine/storagePath.ts"() {
+    "use strict";
+    UNSAFE_CHARACTER = /[%\\?#\u0000-\u001f\u007f]/;
+  }
+});
+
 // ../mockup-engine/appstore/fingerprint.ts
 function isScreenshotFingerprint(value) {
   return typeof value === "string" && SCREENSHOT_FINGERPRINT.test(value);
@@ -6324,7 +6343,7 @@ function isShotManifestEntry(entry) {
   return typeof entry.shotId === "string";
 }
 function manifestRefUploader(ref) {
-  if (ref.includes("..")) return null;
+  if (!isSafeStoragePath(ref)) return null;
   const match = UPLOAD_REF_RE.exec(ref);
   if (!match || !UUID_RE.test(match[1])) return null;
   return match[1];
@@ -6570,23 +6589,11 @@ function rebindManifestToShots(cells, shots) {
   }
   return { manifest, findings };
 }
-function manifestFromNamedRefs(refs, shots, hashes = {}) {
-  const idsByFrameName = shotIdsByFrameName(shots);
-  const out = [];
-  for (const [name, ref] of Object.entries(refs)) {
-    const canonical = canonicalizeManifestRef(ref);
-    const hash = hashes[name];
-    const withHash = (entry) => hash === void 0 ? entry : { ...entry, hash };
-    const ids = idsByFrameName[name];
-    if (ids === void 0) out.push(withHash({ slot: name, variant: {}, ref: canonical }));
-    else for (const id of ids) out.push(withHash({ shotId: id, variant: {}, ref: canonical }));
-  }
-  return out;
-}
 var UPLOAD_REF_RE, UUID_RE, TRUNCATED_NAMED_UPLOAD_REF, EMPTY;
 var init_screenManifest = __esm({
   "../mockup-engine/appstore/screenManifest.ts"() {
     "use strict";
+    init_storagePath();
     init_variant();
     init_fingerprint();
     UPLOAD_REF_RE = /^uploads\/([^/]+)\/([^/]+(?:\/[^/]+)*)$/;
@@ -9832,7 +9839,360 @@ var init_agentTurnRepetition = __esm({
   }
 });
 
+// ../mockup-engine/appstore/agentTurnAdjustments.ts
+function step(field, from, to) {
+  if (field !== "orbit") return to - from;
+  return ((to - from) % 360 + 540) % 360 - 180;
+}
+function pushesFurther(field, start, now, proposed) {
+  if (typeof start !== "number" || typeof now !== "number" || typeof proposed !== "number") return false;
+  const moved = step(field, start, now);
+  const next = step(field, now, proposed);
+  return moved !== 0 && next !== 0 && Math.sign(moved) === Math.sign(next);
+}
+function deviceLooks(state) {
+  const looks = {};
+  for (const shot of state.shots) looks[shot.id] = aiShotPatchFromLook(shot.look);
+  return looks;
+}
+function deviceRepeats(entry, deviceId, start, now) {
+  const from = start[deviceId];
+  const at = now[deviceId];
+  if (!from || !at) return [];
+  return ADJUSTABLE_DEVICE_FIELDS.filter((field) => pushesFurther(field, from[field], at[field], entry[field]));
+}
+function withoutFields(entry, fields2) {
+  const kept = { ...entry };
+  for (const field of fields2) delete kept[field];
+  return kept;
+}
+function baseLayers(state, panelId) {
+  return state.captionText[state.baseLocale]?.[panelId];
+}
+function effectiveCaptionValue(layer, field) {
+  const value = layer[field];
+  if (typeof value === "number") return value;
+  switch (field) {
+    case "lineHeight":
+    case "bandInset":
+    case "bandCenter":
+      return CAPTION_STYLE_DEFAULTS[field];
+    case "reserveLines":
+      return layer.text.split("\n").length;
+    default:
+      return void 0;
+  }
+}
+function captionRepeats(style2, start, now) {
+  if (!start || !now || start.length !== now.length || now.length === 0) return [];
+  return ADJUSTABLE_CAPTION_FIELDS.filter((field) => style2[field] !== void 0 && now.some((layer, index) => {
+    const applied = captionLayerFromAiPatch(layer, { [field]: style2[field] });
+    if (applied === layer) return false;
+    return pushesFurther(
+      field,
+      effectiveCaptionValue(start[index], field),
+      effectiveCaptionValue(layer, field),
+      effectiveCaptionValue(applied, field)
+    );
+  }));
+}
+function dropRepeatedAdjustments(patch, context) {
+  const dropped = [];
+  const start = deviceLooks(context.start);
+  const now = deviceLooks(context.now);
+  const repairing = (panelId) => panelId !== void 0 && (context.repairing?.has(panelId) ?? false);
+  const panelOfDevice = (deviceId) => context.now.shots.find((shot) => shot.id === deviceId)?.panelId;
+  let next = patch;
+  if (patch.devices) {
+    const devices = [];
+    let changed = false;
+    for (const entry of patch.devices) {
+      const repeats = repairing(panelOfDevice(entry.deviceId)) ? [] : deviceRepeats(entry.patch, entry.deviceId, start, now);
+      if (repeats.length === 0) {
+        devices.push(entry);
+        continue;
+      }
+      changed = true;
+      for (const field of repeats) dropped.push({ target: entry.deviceId, field });
+      const kept = withoutFields(entry.patch, repeats);
+      if (Object.keys(kept).length > 0) devices.push({ ...entry, patch: kept });
+    }
+    if (changed) {
+      const { devices: _replaced, ...rest } = next;
+      void _replaced;
+      next = devices.length > 0 ? { ...rest, devices } : rest;
+    }
+  }
+  if (patch.shots && patch.shots.length === context.panelIds.length) {
+    let changed = false;
+    const shots = patch.shots.map((entry, index) => {
+      const panelId = context.panelIds[index];
+      if (repairing(panelId)) return entry;
+      const repeats = [];
+      for (const shot of context.now.shots) {
+        if (shot.panelId !== panelId) continue;
+        for (const field of deviceRepeats(entry, shot.id, start, now)) {
+          if (repeats.indexOf(field) < 0) repeats.push(field);
+        }
+      }
+      if (repeats.length === 0) return entry;
+      changed = true;
+      for (const field of repeats) dropped.push({ target: `${panelId}#devices`, field });
+      return withoutFields(entry, repeats);
+    });
+    if (changed) next = { ...next, shots };
+  }
+  const frames = patch.frames && patch.frames.length === context.panelIds.length ? patch.frames : void 0;
+  if (frames) {
+    let changed = false;
+    const kept = frames.map((entry, index) => {
+      const style2 = entry.captionStyle;
+      const panelId = context.panelIds[index];
+      if (!style2 || repairing(panelId)) return entry;
+      const repeats = captionRepeats(style2, baseLayers(context.start, panelId), baseLayers(context.now, panelId));
+      if (repeats.length === 0) return entry;
+      changed = true;
+      for (const field of repeats) dropped.push({ target: `${panelId}#captions`, field });
+      const captionStyle = withoutFields(style2, repeats);
+      const { captionStyle: _replaced, ...rest } = entry;
+      void _replaced;
+      return Object.keys(captionStyle).length > 0 ? { ...rest, captionStyle } : rest;
+    });
+    if (changed) next = { ...next, frames: kept };
+  }
+  if (patch.captionStyle && !context.panelIds.some(repairing)) {
+    const stripWide = patch.captionStyle;
+    const repeats = [];
+    context.panelIds.forEach((panelId, index) => {
+      const own = frames?.[index]?.captionStyle ?? {};
+      const reaching = withoutFields(stripWide, Object.keys(own));
+      const found = captionRepeats(reaching, baseLayers(context.start, panelId), baseLayers(context.now, panelId));
+      for (const field of found) {
+        if (repeats.indexOf(field) < 0) repeats.push(field);
+      }
+    });
+    if (repeats.length > 0) {
+      for (const field of repeats) dropped.push({ target: "strip#captions", field });
+      const captionStyle = withoutFields(stripWide, repeats);
+      const { captionStyle: _replaced, ...rest } = next;
+      void _replaced;
+      next = Object.keys(captionStyle).length > 0 ? { ...rest, captionStyle } : rest;
+    }
+  }
+  return { patch: dropped.length > 0 ? next : patch, dropped };
+}
+function carriesSomething(value) {
+  if (value === void 0 || value === null) return false;
+  if (Array.isArray(value)) return value.some(carriesSomething);
+  if (typeof value === "object") return Object.keys(value).some((key) => carriesSomething(value[key]));
+  return true;
+}
+function patchChangesSomething(patch) {
+  return Object.keys(patch).some((key) => key !== "summary" && carriesSomething(patch[key]));
+}
+var ADJUSTABLE_DEVICE_FIELDS, ADJUSTABLE_CAPTION_FIELDS;
+var init_agentTurnAdjustments = __esm({
+  "../mockup-engine/appstore/agentTurnAdjustments.ts"() {
+    "use strict";
+    init_refinementValues();
+    init_caption();
+    ADJUSTABLE_DEVICE_FIELDS = [
+      "orbit",
+      "roll",
+      "deviceSize",
+      "hOffset",
+      "vOffset",
+      "finish",
+      "clearcoat",
+      "screenCornerRadius"
+    ];
+    ADJUSTABLE_CAPTION_FIELDS = ["sizePt", "maxWidth", "lineHeight", "bandInset", "bandCenter", "reserveLines"];
+  }
+});
+
+// ../mockup-engine/appstore/agentTurnLanded.ts
+function sameDeviceValue(field, proposed, applied) {
+  if (field !== "orbit") return near(proposed, applied);
+  const wrapped = ((proposed + 180) % 360 + 360) % 360 - 180;
+  return near(wrapped, applied, 0.5) || near(Math.abs(wrapped), 180, 0.5) && near(Math.abs(applied), 180, 0.5);
+}
+function deviceDifference(field, proposed, applied, sharedOffset) {
+  if (sameDeviceValue(field, proposed, applied)) return null;
+  if (field === "hOffset" && sharedOffset) return "shared_offset";
+  const range = field === "orbit" ? void 0 : SHOT_LOOK_RANGES[field];
+  if (range && (proposed < range.min || proposed > range.max) && near(clamp(proposed, range), applied)) return "held_at_limit";
+  return "set_differently";
+}
+function deviceDifferences(entry, applied, sharedOffset, out) {
+  for (const field of DEVICE_NUMBERS) {
+    const proposed = entry[field];
+    const landed = applied[field];
+    if (typeof proposed !== "number" || typeof landed !== "number") continue;
+    const difference = deviceDifference(field, proposed, landed, sharedOffset);
+    if (difference) out.add(difference);
+  }
+}
+function expectedCaptionValue(field, proposed, current) {
+  const raw = typeof proposed === "number" ? proposed : current === void 0 ? void 0 : current * clamp(proposed.scale, AI_SCALE_RANGE);
+  return raw !== void 0 && field === "reserveLines" ? Math.round(raw) : raw;
+}
+function captionDifferences(style2, before, after, alignedByPosition, out) {
+  const stated = CAPTION_NUMBERS.filter((field) => style2[field] !== void 0);
+  if (stated.length === 0) return;
+  if (!after || after.length === 0) {
+    out.add("set_differently");
+    return;
+  }
+  for (const field of stated) {
+    const proposed = style2[field];
+    if (typeof proposed !== "number" && !alignedByPosition) continue;
+    after.forEach((layer, index) => {
+      const expected = expectedCaptionValue(field, proposed, typeof proposed === "number" ? void 0 : before?.[index]?.[field]);
+      const landed = layer[field];
+      if (expected === void 0) {
+        out.add("set_differently");
+        return;
+      }
+      if (typeof landed === "number" && near(landed, expected)) return;
+      const range = CAPTION_STYLE_BOUNDS[field];
+      const limited = field === "reserveLines" ? Math.round(clamp(expected, range)) : clamp(expected, range);
+      out.add(typeof landed === "number" && !near(limited, expected) && near(landed, limited) ? "held_at_limit" : "set_differently");
+    });
+  }
+}
+function landedDifferences(before, after, patch, panelIds) {
+  const out = /* @__PURE__ */ new Set();
+  const lookOf = (shotId) => {
+    const shot = after.shots.find((candidate) => candidate.id === shotId);
+    return shot ? aiShotPatchFromLook(shot.look) : null;
+  };
+  for (const entry of patch.devices ?? []) {
+    const applied = lookOf(entry.deviceId);
+    if (applied) deviceDifferences(entry.patch, applied, false, out);
+  }
+  if (patch.shots && patch.shots.length === panelIds.length) {
+    patch.shots.forEach((entry, index) => {
+      const shots = after.shots.filter((shot) => shot.panelId === panelIds[index]);
+      for (const shot of shots) deviceDifferences(entry, aiShotPatchFromLook(shot.look), shots.length > 1, out);
+    });
+  }
+  const frames = patch.frames && patch.frames.length === panelIds.length ? patch.frames : void 0;
+  if (patch.captionStyle || frames) {
+    const beforeSlots = normalizeCaptionSlotIds(before.captionSlotIds, before.captionText, before.panels.map((panel) => panel.id));
+    const afterSlots = normalizeCaptionSlotIds(after.captionSlotIds, after.captionText, after.panels.map((panel) => panel.id));
+    panelIds.forEach((panelId, index) => {
+      const style2 = { ...patch.captionStyle, ...frames?.[index]?.captionStyle };
+      const aligned = (beforeSlots[panelId] ?? []).join("\0") === (afterSlots[panelId] ?? []).join("\0");
+      captionDifferences(
+        style2,
+        before.captionText[before.baseLocale]?.[panelId],
+        after.captionText[after.baseLocale]?.[panelId],
+        aligned,
+        out
+      );
+    });
+  }
+  return out;
+}
+var DEVICE_NUMBERS, CAPTION_NUMBERS, clamp, near;
+var init_agentTurnLanded = __esm({
+  "../mockup-engine/appstore/agentTurnLanded.ts"() {
+    "use strict";
+    init_caption();
+    init_defaults();
+    init_frameTemplates();
+    init_refineIntent();
+    init_refinementValues();
+    DEVICE_NUMBERS = ["orbit", "roll", "deviceSize", "hOffset", "vOffset", "finish", "clearcoat", "screenCornerRadius"];
+    CAPTION_NUMBERS = ["sizePt", "maxWidth", "lineHeight", "bandInset", "bandCenter", "reserveLines"];
+    clamp = (value, range) => Math.min(Math.max(value, range.min), range.max);
+    near = (a, b, tolerance = 1e-9) => Math.abs(a - b) <= tolerance;
+  }
+});
+
 // ../mockup-engine/appstore/agentTurnCoordinator.ts
+function passEffect(working, application, patch, panelIds, notApplied, focus) {
+  const landed = landedDifferences(working, application.state, patch, panelIds);
+  if (notApplied.size === 0 && landed.size === 0) return null;
+  const applied = [...describeRefinementEffect(working, application.state), ...describeAssetBindings(application.assetBindings)];
+  const lines = [applied.length > 0 ? `${applied.join(" \xB7 ")}.` : "Nothing changed in this pass."];
+  if (notApplied.size > 0) lines.push(`Not applied: ${Array.from(notApplied).map((reason) => NOT_APPLIED[reason]).join("; ")}.`);
+  if (landed.size > 0) lines.push(`Not applied as proposed: ${Array.from(landed).map((reason) => LANDED_DIFFERENTLY[reason]).join("; ")}.`);
+  return {
+    summary: lines.join(" "),
+    reachesOutsideFocus: changedOutsideFocus(working, application.state, focus)
+  };
+}
+function emptiedPassEffect(notApplied) {
+  return {
+    summary: `Nothing changed in this pass. Not applied: ${Array.from(notApplied).map((reason) => NOT_APPLIED[reason]).join("; ")}.`,
+    reachesOutsideFocus: false
+  };
+}
+function changedOutsideFocus(before, after, focus) {
+  if (focus.kind === "project") return false;
+  const frameId = focus.frameId;
+  const ownsFrame = focus.kind === "frame";
+  const slotsOf = (state) => normalizeCaptionSlotIds(state.captionSlotIds, state.captionText, state.panels.map((panel) => panel.id));
+  const beforeSlots = slotsOf(before);
+  const focusedSlot = focus.kind === "caption" ? beforeSlots[frameId]?.[focus.captionIndex] : void 0;
+  const shotsOutside = (state) => state.shots.filter((shot) => !(ownsFrame && shot.panelId === frameId)).map((shot) => focus.kind === "device" && shot.id === focus.deviceId ? { id: shot.id, panelId: shot.panelId } : { id: shot.id, panelId: shot.panelId, frameName: shot.frameName, frameNodeId: shot.frameNodeId, look: shot.look });
+  const bytesOutside = (state) => state.shots.filter((shot) => !(ownsFrame && shot.panelId === frameId) && !(focus.kind === "device" && shot.id === focus.deviceId)).map((shot) => shot.bytes);
+  const perFrame = (map) => {
+    if (!map || !ownsFrame) return map;
+    const { [frameId]: _owned, ...rest } = map;
+    void _owned;
+    return rest;
+  };
+  const outside = (state) => {
+    const {
+      selection: _selection,
+      activeLocale: _activeLocale,
+      previewPresetId: _preview,
+      outputScreens: _outputScreens,
+      localeScreens: _localeScreens,
+      selectedShotId: _selectedShotId,
+      shots: _shots,
+      captionSlotIds: _rawSlots,
+      captionText,
+      outputCaptions,
+      panelColors,
+      panelBackgrounds,
+      staleCaptionTranslations,
+      frameTemplates,
+      ...rest
+    } = state;
+    void [_selection, _activeLocale, _preview, _outputScreens, _localeScreens, _selectedShotId, _shots, _rawSlots];
+    const slots = slotsOf(state);
+    const slotAt = (panelId, index) => slots[panelId]?.[index] ?? `${panelId}#${index}`;
+    const owned = (panelId, index) => ownsFrame ? panelId === frameId : focusedSlot !== void 0 && slotAt(panelId, index) === focusedSlot;
+    const keyed = (panelId, layers) => layers.flatMap((layer, index) => owned(panelId, index) ? [] : [[slotAt(panelId, index), layer]]);
+    const byFrame = (frames) => frames && Object.keys(frames).map((panelId) => [panelId, keyed(panelId, frames[panelId])]).filter(([, entries]) => entries.length > 0);
+    const byLocale = (locales) => locales && Object.keys(locales).map((locale2) => [locale2, byFrame(locales[locale2])]);
+    return JSON.stringify({
+      rest,
+      shots: shotsOutside(state),
+      captionText: byLocale(captionText),
+      outputCaptions: outputCaptions && Object.keys(outputCaptions).map((family) => [family, byLocale(outputCaptions[family])]),
+      captionSlots: Object.keys(slots).map((panelId) => [panelId, slots[panelId].filter((_, index) => !owned(panelId, index))]).filter(([, ids]) => ids.length > 0),
+      staleCaptionTranslations: staleCaptionTranslations && Object.keys(staleCaptionTranslations).map((locale2) => [
+        locale2,
+        staleCaptionTranslations[locale2].flatMap((key) => {
+          const cut = key.lastIndexOf(":");
+          const panelId = key.slice(0, cut);
+          const index = Number(key.slice(cut + 1));
+          return owned(panelId, index) ? [] : [`${panelId}:${slotAt(panelId, index)}`];
+        }).sort()
+      ]),
+      panelColors: perFrame(panelColors),
+      panelBackgrounds: perFrame(panelBackgrounds),
+      frameTemplates: perFrame(frameTemplates)
+    });
+  };
+  const beforeBytes = bytesOutside(before);
+  const afterBytes = bytesOutside(after);
+  return outside(before) !== outside(after) || beforeBytes.length !== afterBytes.length || beforeBytes.some((bytes, index) => bytes !== afterBytes[index]);
+}
 function phaseFor(cycle) {
   return cycle === 1 ? "applying" : cycle === 2 ? "inspecting" : "adjusting";
 }
@@ -9901,6 +10261,7 @@ async function runAgentTurn(input, ports) {
   const appliedOperations = [];
   const touchedCapabilities = /* @__PURE__ */ new Set();
   const templatedPanels = /* @__PURE__ */ new Set();
+  let instructionSatisfied = false;
   let terminalOutcome = null;
   let invalid2 = false;
   let cancelled = false;
@@ -9953,10 +10314,55 @@ async function runAgentTurn(input, ports) {
     }
     interpretation ||= authorization.interpretation?.trim() || instruction;
     inspection = authorization.inspection?.trim() || "Inspected the current composed result.";
+    const notApplied = /* @__PURE__ */ new Set();
+    if (!authorization.failed && !authorization.terminalOutcome) {
+      if (authorization.patch && cycle > 1) {
+        const guarded = dropRepeatedOperations(authorization.patch, appliedOperations);
+        if (guarded.dropped.length > 0) {
+          authorization = { ...authorization, patch: guarded.patch };
+          notApplied.add("repeated_step");
+        }
+      }
+      if (authorization.patch && instructionSatisfied) {
+        const context = { start: before, now: working, panelIds: authorization.panelIds };
+        let guarded = dropRepeatedAdjustments(authorization.patch, context);
+        if (guarded.dropped.length > 0 && layoutRepairable && renderedState) {
+          const repairing = /* @__PURE__ */ new Set();
+          for (const index of ports.layoutCollisionFrames?.(rendered) ?? []) {
+            const panelId = renderedState.panels[index]?.id;
+            if (panelId) repairing.add(panelId);
+          }
+          if (repairing.size > 0) guarded = dropRepeatedAdjustments(authorization.patch, { ...context, repairing });
+        }
+        if (guarded.dropped.length > 0) {
+          authorization = {
+            ...authorization,
+            patch: patchChangesSomething(guarded.patch) ? guarded.patch : void 0
+          };
+          notApplied.add("repeated_adjustment");
+        }
+      }
+      if (authorization.patch && templatedPanels.size > 0) {
+        const shots = working.shots;
+        const guarded = dropTemplatePoses(
+          authorization.patch,
+          templatedPanels,
+          authorization.panelIds,
+          (deviceId) => shots.find((shot) => shot.id === deviceId)?.panelId
+        );
+        if (guarded.dropped) {
+          authorization = { ...authorization, patch: guarded.patch };
+          notApplied.add("template_pose");
+        }
+      }
+    }
+    const planned = !authorization.failed && !authorization.terminalOutcome;
+    const application = planned && authorization.patch ? applyProjectRefinementWithAssets(working, authorization.patch, authorization.panelIds, input.assets ?? []) : null;
+    const effect = !planned ? null : application && authorization.patch ? passEffect(working, application, authorization.patch, authorization.panelIds, notApplied, input.focus) : notApplied.size > 0 && !authorization.patch ? emptiedPassEffect(notApplied) : null;
     const pass = {
       phase,
       generationId: authorization.generationId,
-      summary: authorization.failed ? FAILED_PASS_SUMMARY[phase] : inspection,
+      summary: authorization.failed ? FAILED_PASS_SUMMARY[phase] : effect?.summary ?? inspection,
       usage: authorization.usage,
       createdAt: now()
     };
@@ -9977,29 +10383,11 @@ async function runAgentTurn(input, ports) {
       break;
     }
     remainingMismatch = authorization.remainingMismatch?.trim() || authorization.followUp?.trim() || null;
-    for (const change of authorization.broaderChanges ?? []) broaderChanges.add(change);
-    if (authorization.patch && cycle > 1) {
-      const guarded = dropRepeatedOperations(authorization.patch, appliedOperations);
-      if (guarded.dropped.length > 0) authorization = { ...authorization, patch: guarded.patch };
-    }
-    if (authorization.patch && templatedPanels.size > 0) {
-      const shots = working.shots;
-      const guarded = dropTemplatePoses(
-        authorization.patch,
-        templatedPanels,
-        authorization.panelIds,
-        (deviceId) => shots.find((shot) => shot.id === deviceId)?.panelId
-      );
-      if (guarded.dropped) authorization = { ...authorization, patch: guarded.patch };
+    if (authorization.patch && (!effect || effect.reachesOutsideFocus)) {
+      for (const change of authorization.broaderChanges ?? []) broaderChanges.add(change);
     }
     if (authorization.patch) {
       for (const id of capabilitiesForPatch(authorization.patch)) touchedCapabilities.add(id);
-      const application = applyProjectRefinementWithAssets(
-        working,
-        authorization.patch,
-        authorization.panelIds,
-        input.assets ?? []
-      );
       if (!application) {
         invalid2 = true;
         break;
@@ -10025,6 +10413,7 @@ async function runAgentTurn(input, ports) {
         assetBindings: workingAssetBindings
       };
       selected = checkpoint;
+      if (authorization.complete === true) instructionSatisfied = true;
       if (checkpoint.changed.length > 0 && (!best || checkpoint.quality >= best.quality)) best = checkpoint;
       await emit({
         type: "draft_applied",
@@ -10151,7 +10540,7 @@ async function runAgentTurn(input, ports) {
   void input.requestedCycle;
   return result;
 }
-var AGENT_TURN_PASS_CAP, AgentTurnAuthorizationError, EMPTY_USAGE, NO_CHANGE_SUMMARY, NEEDS_INPUT_SUMMARY, FAILED_PASS_SUMMARY;
+var AGENT_TURN_PASS_CAP, AgentTurnAuthorizationError, EMPTY_USAGE, NO_CHANGE_SUMMARY, NEEDS_INPUT_SUMMARY, FAILED_PASS_SUMMARY, NOT_APPLIED, LANDED_DIFFERENTLY;
 var init_agentTurnCoordinator = __esm({
   "../mockup-engine/appstore/agentTurnCoordinator.ts"() {
     "use strict";
@@ -10163,8 +10552,11 @@ var init_agentTurnCoordinator = __esm({
     init_appStoreLocales();
     init_agentAssetCustody();
     init_agentTurnRepetition();
+    init_agentTurnAdjustments();
     init_templatePoseGuard();
     init_layoutTemplates();
+    init_frameTemplates();
+    init_agentTurnLanded();
     AGENT_TURN_PASS_CAP = 3;
     AgentTurnAuthorizationError = class extends Error {
       constructor(outcome) {
@@ -10188,6 +10580,16 @@ var init_agentTurnCoordinator = __esm({
       inspecting: "The inspection pass did not complete.",
       adjusting: "The correction pass did not complete."
     };
+    NOT_APPLIED = {
+      repeated_step: "a step this turn had already taken",
+      repeated_adjustment: "a further change to what this turn had already adjusted",
+      template_pose: "a new pose for a device its layout template had placed"
+    };
+    LANDED_DIFFERENTLY = {
+      held_at_limit: "a value past its limit, which was held at the limit",
+      shared_offset: "a sideways offset for each phone of a frame that holds several, which stays shared",
+      set_differently: "a value the project took differently"
+    };
   }
 });
 
@@ -10955,10 +11357,14 @@ var init_supabaseRest = __esm({
 });
 
 // ../api/_lib/shareStorage.ts
+function safePath(path) {
+  if (!isSafeStoragePath(path)) throw new Error(`storage: refusing unsafe object path ${JSON.stringify(path)}`);
+  return path;
+}
 async function createSignedUploadUrl(path, options = {}) {
   const headers = serviceHeaders({ "Content-Type": "application/json" });
   if (options.upsert) headers["x-upsert"] = "true";
-  const res = await fetch(`${storageBase()}/object/upload/sign/${BUCKET}/${path}`, {
+  const res = await fetch(`${storageBase()}/object/upload/sign/${BUCKET}/${safePath(path)}`, {
     method: "POST",
     headers,
     body: JSON.stringify({})
@@ -10971,7 +11377,7 @@ async function createSignedUploadUrl(path, options = {}) {
   return { uploadUrl: `${storageBase()}${data.url}` };
 }
 async function createSignedDownloadUrl(path, expiresInSeconds, downloadFilename) {
-  const res = await fetch(`${storageBase()}/object/sign/${BUCKET}/${path}`, {
+  const res = await fetch(`${storageBase()}/object/sign/${BUCKET}/${safePath(path)}`, {
     method: "POST",
     headers: serviceHeaders({ "Content-Type": "application/json" }),
     body: JSON.stringify({ expiresIn: expiresInSeconds })
@@ -10996,7 +11402,7 @@ async function putBytes(uploadUrl, bytes, contentType) {
   }
 }
 async function downloadObject(path) {
-  const res = await fetch(`${storageBase()}/object/${BUCKET}/${path}`, { headers: serviceHeaders() });
+  const res = await fetch(`${storageBase()}/object/${BUCKET}/${safePath(path)}`, { headers: serviceHeaders() });
   if (!res.ok) {
     const body = (await res.text().catch(() => "")).slice(0, 200);
     if (res.status === 404 || /"statusCode"\s*:\s*"?404"?/.test(body) || /not_found/.test(body)) {
@@ -11007,7 +11413,7 @@ async function downloadObject(path) {
   return new Uint8Array(await res.arrayBuffer());
 }
 async function getObjectInfo(path) {
-  const res = await fetch(`${storageBase()}/object/info/${BUCKET}/${path}`, { headers: serviceHeaders() });
+  const res = await fetch(`${storageBase()}/object/info/${BUCKET}/${safePath(path)}`, { headers: serviceHeaders() });
   if (!res.ok) {
     const body = (await res.text().catch(() => "")).slice(0, 200);
     if (res.status === 404 || /"statusCode"\s*:\s*"?404"?/.test(body) || /not_found/.test(body)) {
@@ -11026,6 +11432,7 @@ var BUCKET, StorageObjectNotFoundError;
 var init_shareStorage = __esm({
   "../api/_lib/shareStorage.ts"() {
     "use strict";
+    init_storagePath();
     init_supabaseRest();
     BUCKET = "share-bundles";
     StorageObjectNotFoundError = class extends Error {
@@ -11380,7 +11787,7 @@ function uploadCustody(userId) {
 }
 function refBelongsToUser(ref, userId, now = Date.now()) {
   const prefix = `uploads/${userId}/`;
-  if (!ref.startsWith(prefix) || ref.includes("..")) return false;
+  if (!ref.startsWith(prefix) || !isSafeStoragePath(ref)) return false;
   if (!userId.startsWith(ANONYMOUS_USER_PREFIX)) return true;
   const dir = ref.slice(prefix.length).split("/")[0];
   const expiry = ANONYMOUS_DIR_EXPIRY_RE.exec(dir);
@@ -11394,17 +11801,16 @@ async function fetchUploadedRef(ref, userId) {
     await adoptLegacyAssetOnAuthorizedRead(ref, userId).catch(() => void 0);
     return await downloadObject(ref);
   } catch (err) {
-    if (err instanceof StorageObjectNotFoundError) {
-      throw new Error(
-        `no screenshot was ever uploaded for ref "${ref}". request_screenshot_upload only MINTS an upload slot \u2014 the raw PNG bytes must still be PUT to its uploadUrl before rendering (curl -T screenshot.png "$UPLOAD_URL"). If that PUT failed or was skipped, mint a fresh slot and retry it; slots are single-use and short-lived. Alternatively pass the screenshot as { "url": "https://\u2026" } and this server will fetch it for you. ` + // #180: on ChatGPT mobile the PUT can NEVER succeed (the sandbox cannot resolve the
-        // storage host), so "retry it" is not always advice an agent can take. Name the door
-        // that has no upload step at all.
-        BROWSER_FIRST_ROUTE
-      );
-    }
+    if (err instanceof StorageObjectNotFoundError) throw new Error(missingUploadMessage(ref));
     throw err;
   }
 }
+function missingUploadMessage(ref) {
+  return `no screenshot was ever uploaded for ref "${ref}". request_screenshot_upload only MINTS an upload slot \u2014 the raw PNG bytes must still be PUT to its uploadUrl before rendering (curl -T screenshot.png "$UPLOAD_URL"). If that PUT failed or was skipped, mint a fresh slot and retry it; slots are single-use and short-lived. Alternatively pass the screenshot as { "url": "https://\u2026" } and this server will fetch it for you. ` + // #180: on ChatGPT mobile the PUT can NEVER succeed (the sandbox cannot resolve the
+  // storage host), so "retry it" is not always advice an agent can take. Name the door
+  // that has no upload step at all.
+  BROWSER_FIRST_ROUTE;
+}
 async function fetchPanelRef(ref, userId) {
   if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(ref)) {
     return fetchUploadedRef(ref, userId);
@@ -11578,6 +11984,7 @@ var init_uploads = __esm({
     init_shareStorage();
     init_assetRegistry();
     init_supabaseRest();
+    init_storagePath();
     init_retentionPolicy();
     init_toolContract();
     init_pngOptimizer();
@@ -11660,7 +12067,12 @@ async function readLocalPathAsBase64(path) {
   const { bytes } = await readLocalScreenshotFile(path);
   return (await optimizeScreenshotPng(bytes, `The file at "${path}"`)).toString("base64");
 }
-async function resolvePanelBytes(entry, userId, allowLocalPath) {
+async function readOneUpload(readUploads, ref) {
+  const bytes = (await readUploads([ref])).get(ref);
+  if (!bytes) throw new Error(`the screenshot for ref "${ref}" could not be read.`);
+  return bytes;
+}
+async function resolvePanelBytes(entry, userId, allowLocalPath, readUploads) {
   if ("path" in entry) {
     if (!allowLocalPath) {
       throw new Error(
@@ -11673,14 +12085,20 @@ async function resolvePanelBytes(entry, userId, allowLocalPath) {
       throw new Error(`could not read local panel at "${entry.path}": ${err.message}`);
     }
   }
+  if (readUploads) {
+    if (PANEL_ID_RE.test(entry.ref)) throw new HostedOnlyPanelError(entry.ref);
+    return readOneUpload(readUploads, entry.ref);
+  }
   return entry.ref.includes("/") ? fetchUploadedRef(entry.ref, userId) : fetchPanelRef(entry.ref, userId);
 }
-async function resolveEntry(entry, userId, allowLocalPath) {
+async function resolveEntry(entry, userId, allowLocalPath, uploaded) {
   if (typeof entry === "string") {
     return (await optimizeScreenshotPng(Buffer.from(entry, "base64"), "Inline screenshot")).toString("base64");
   }
   if ("ref" in entry) {
-    const bytes = await fetchUploadedRef(entry.ref, userId);
+    const read = uploaded?.get(entry.ref);
+    if (uploaded && !read) throw new Error(`the screenshot for ref "${entry.ref}" could not be read.`);
+    const bytes = read ?? await fetchUploadedRef(entry.ref, userId);
     return (await optimizeScreenshotPng(bytes, `Screenshot ref "${entry.ref}"`)).toString("base64");
   }
   if ("path" in entry) {
@@ -11696,10 +12114,13 @@ async function resolveEntry(entry, userId, allowLocalPath) {
   }
   return fetchUrlAsBase64(entry.url);
 }
-async function resolveScreenshots(slots, userId, allowLocalPath = false) {
+async function resolveScreenshots(slots, userId, allowLocalPath = false, readUploads) {
   assertInlinePayloadSizeNested(slots);
-  return Promise.all(slots.map((slot2) => Promise.all(slot2.map((entry) => resolveEntry(entry, userId, allowLocalPath)))));
+  const refs = Array.from(new Set(slots.flat().flatMap((entry) => entry && typeof entry === "object" && "ref" in entry && typeof entry.ref === "string" ? [entry.ref] : [])));
+  const uploaded = readUploads && refs.length > 0 ? await readUploads(refs) : null;
+  return Promise.all(slots.map((slot2) => Promise.all(slot2.map((entry) => resolveEntry(entry, userId, allowLocalPath, uploaded)))));
 }
+var PANEL_ID_RE, HostedOnlyPanelError;
 var init_screenshotInput = __esm({
   "src/render/screenshotInput.ts"() {
     "use strict";
@@ -11707,6 +12128,15 @@ var init_screenshotInput = __esm({
     init_uploads();
     init_pngOptimizer();
     init_toolContract();
+    PANEL_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    HostedOnlyPanelError = class extends Error {
+      constructor(ref) {
+        super(
+          `Rendered panel ids are hosted-only \u2014 this local server cannot read panel "${ref}". Pass the rendered PNG as { "path": "\u2026" } instead.`
+        );
+        this.name = "HostedOnlyPanelError";
+      }
+    };
   }
 });
 
@@ -11716,22 +12146,96 @@ function screenNamesFromRecord(record8) {
   if (!Array.isArray(shots)) return [];
   return shots.map((s) => s?.frameName).filter((n) => typeof n === "string" && n.length > 0);
 }
-function handoffRefsFromScreenshots(screenshots2, frameNames, userId) {
-  if (!Array.isArray(screenshots2) || screenshots2.length === 0) return {};
-  const wanted = new Set(frameNames);
-  const out = {};
-  for (const slot2 of normalizeScreenshotSlots(screenshots2)) {
-    for (const entry of slot2) {
-      if (!entry || typeof entry !== "object" || !("ref" in entry) || typeof entry.ref !== "string") continue;
-      const ref = canonicalizeUploadRef(entry.ref);
-      if (!refBelongsToUser(ref, userId)) continue;
-      const name = entryName(entry);
-      if (!name || !wanted.has(name)) continue;
-      out[name] = ref;
+function refOf(entry) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return null;
+  const ref = entry.ref;
+  return typeof ref === "string" && ref.length > 0 ? canonicalizeUploadRef(ref) : null;
+}
+function introducedScreenCells(screenshots2, projectFile) {
+  const out = { manifest: [], refs: [], unaddressed: [] };
+  if (!Array.isArray(screenshots2) || screenshots2.length === 0) return out;
+  const entries = normalizeScreenshotSlots(screenshots2).flat();
+  const shots = shotRefsFromProjectFile(projectFile);
+  const { baseLocale } = projectLocaleAxis(projectFile);
+  entries.forEach((entry, i) => {
+    const shot = entries.length === shots.length ? shots[i] : void 0;
+    const cells = [];
+    if (isLocaleVariants(entry)) {
+      const base = refOf(resolveLocaleVariant(entry, baseLocale, baseLocale));
+      if (base) cells.push({ ref: base, variant: {} });
+      for (const [locale2, variant] of Object.entries(entry.locales)) {
+        const ref = locale2 === baseLocale ? null : refOf(variant);
+        if (ref) cells.push({ ref, variant: canonicalVariant({ locale: locale2 }, baseLocale), locale: locale2 });
+      }
+    } else {
+      const ref = refOf(entry);
+      if (ref) cells.push({ ref, variant: {} });
     }
-  }
+    for (const cell of cells) {
+      const named = {
+        ref: cell.ref,
+        frame: i + 1,
+        frameName: shot?.frameName ?? null,
+        ...cell.locale ? { locale: cell.locale } : {}
+      };
+      out.refs.push(named);
+      if (!shot) out.unaddressed.push(named);
+      else out.manifest.push({ shotId: shot.id, variant: cell.variant, ref: cell.ref });
+    }
+  });
   return out;
 }
+function describeUnsavedRefs(refs) {
+  return refs.map((entry) => {
+    const where = [
+      `frame ${entry.frame}`,
+      entry.frameName ? `"${entry.frameName}"` : null,
+      entry.locale ? `locale ${entry.locale}` : null
+    ].filter(Boolean).join(", ");
+    return `${entry.ref} (${where})`;
+  }).join("; ");
+}
+function refusedRefs(kind, refs) {
+  const list = describeUnsavedRefs(refs);
+  const details = { frames: refs.map(({ ref: _ref, ...where }) => where) };
+  switch (kind) {
+    case "no_account":
+      return {
+        code: "authentication_required",
+        details,
+        error: `This local server has no ShotOps account, so it cannot save { "ref" } screenshots \u2014 a ref points at an upload inside an account: ${list}. Pass each screenshot as a local { "path": "\u2026" } PNG, or sign in (npx shotops-mcp login) and save again. Nothing was saved.`
+      };
+    case "account_unknown":
+      return {
+        code: "upstream_unavailable",
+        details,
+        error: `Could not confirm which ShotOps account this server\u2019s token signs in as, so these { "ref" } screenshots could not be checked: ${list}. Nothing was saved \u2014 try again in a moment.`
+      };
+    case "foreign":
+      return {
+        code: "asset_not_found",
+        details,
+        error: `These { "ref" } screenshots do not belong to this account: ${list}. A ref has to be an upload under the account this save writes to. Pass those screenshots again from a source this account owns \u2014 a ref from import_screenshot or request_screenshot_upload, or a local { "path": "\u2026" } on the local server. Nothing was saved.`
+      };
+    case "unaddressed":
+      return {
+        code: "internal_error",
+        details,
+        error: `These { "ref" } screenshots could not be matched to a frame of the project being saved: ${list}. Nothing was saved.`
+      };
+  }
+}
+async function unsavableRefRefusal(deps, introduced) {
+  if (introduced.refs.length === 0) return null;
+  if (introduced.unaddressed.length > 0) return refusedRefs("unaddressed", introduced.unaddressed);
+  if (deps.createPendingProjectClaim) return refusedRefs("no_account", introduced.refs);
+  let owner = deps.userId;
+  if (deps.accountUserId) owner = await deps.accountUserId().catch(() => null);
+  if (!owner) return refusedRefs("account_unknown", introduced.refs);
+  const account = owner;
+  const foreign = introduced.refs.filter((entry) => !refBelongsToUser(entry.ref, account));
+  return foreign.length > 0 ? refusedRefs("foreign", foreign) : null;
+}
 function projectShotRefsFromRecord(record8) {
   return shotRefsFromProjectFile(record8?.project);
 }
@@ -11779,17 +12283,16 @@ function projectSaveEnvelope(stored, projectFile, manifest, source, listing2) {
 async function persistProject(deps, args, record8, claimPolicy = "none", listing2) {
   const names = screenNamesFromRecord(record8);
   const source = names.length === 0 ? void 0 : args.sourceDir ? { kind: "local-path", ref: { dir: args.sourceDir, names } } : { kind: "agent", ref: { names } };
-  const introducedRefs = handoffRefsFromScreenshots(args.screenshots, names, deps.userId);
+  const introduced = introducedScreenCells(args.screenshots, record8);
+  const refusal = await unsavableRefRefusal(deps, introduced);
+  if (refusal) return refusal;
   let screenNote;
-  const wrapWith = (handoffRefs, existingRecord) => {
+  const wrapWith = (existingRecord) => {
     const preserved = preservedCells(existingRecord, record8);
     if (preserved.findings.length > 0) {
       screenNote = preserved.findings.map((finding) => `The stored screenshot filed under "${finding.frameName}" was not carried over: that filename names ${finding.shotIds.length} devices (${finding.shotIds.join(", ")}), so no single device owns it. Its object is retained; give those devices distinct filenames, or pass their screenshots explicitly.`).join(" ");
     }
-    const manifest = mergeManifest(
-      preserved.manifest,
-      manifestFromNamedRefs(handoffRefs, shotRefsFromProjectFile(record8))
-    );
+    const manifest = mergeManifest(preserved.manifest, introduced.manifest);
     return projectSaveEnvelope(existingRecord, record8, manifest, source, listing2);
   };
   const ctx = {
@@ -11815,7 +12318,7 @@ async function persistProject(deps, args, record8, claimPolicy = "none", listing
         };
       }
       const name = args.projectName?.trim() || "ShotOps render";
-      return await deps.createPendingProjectClaim(name, wrapWith(introducedRefs), ctx);
+      return await deps.createPendingProjectClaim(name, wrapWith(), ctx);
     }
     let projectId;
     if (args.project) {
@@ -11831,7 +12334,7 @@ async function persistProject(deps, args, record8, claimPolicy = "none", listing
       if (denial) return { error: denial };
       const existing = await deps.readProjectRecord(project2.id);
       if (!existing) return { error: `Project "${project2.name}" has no readable saved record.` };
-      await deps.updateProjectRecord(project2.id, wrapWith(introducedRefs, existing.record), existing.recordVersion ?? 1, ctx);
+      await deps.updateProjectRecord(project2.id, wrapWith(existing.record), existing.recordVersion ?? 1, ctx);
       projectId = project2.id;
     } else {
       const name = args.projectName?.trim() || "ShotOps render";
@@ -11844,7 +12347,7 @@ async function persistProject(deps, args, record8, claimPolicy = "none", listing
         const denial = authorizationMessage(decision);
         if (denial) return { error: denial };
       }
-      const created = await deps.createProject(deps.userId, name, wrapWith(introducedRefs), ctx);
+      const created = await deps.createProject(deps.userId, name, wrapWith(), ctx);
       projectId = created.id;
     }
     return { projectId, openUrl: `${deps.studioOrigin}/?project=${projectId}`, ...screenNote ? { screenNote } : {} };
@@ -11865,6 +12368,9 @@ var init_projectPersistence = __esm({
     init_screenManifest();
     init_recordEnvelope();
     init_appListing();
+    init_localeAxis();
+    init_localeVariants();
+    init_variant();
     init_authorization();
     init_projectResolution();
     init_schemas();
@@ -12912,7 +13418,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "shotops-mcp",
-      version: "0.9.8",
+      version: "0.9.9",
       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. Hosted and MCP tool paths never accept, store, or forward a store-signing credential; the explicit local release CLI validates the user's existing key directly with Apple and records only its path. 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.",
@@ -13382,7 +13888,7 @@ async function renderStrip(deps, args, scope, signal) {
   if (durableHostedProductionAvailable(deps) && args.preview !== true) {
     let durableScreenshots;
     try {
-      durableScreenshots = await resolveScreenshots(entries, deps.userId, false);
+      durableScreenshots = await resolveScreenshots(entries, deps.userId, false, deps.readUploadedRefs);
     } catch (err) {
       return errorResult(err.message);
     }
@@ -13435,7 +13941,7 @@ async function renderStrip(deps, args, scope, signal) {
   if (refused) return errorResult(refused.error);
   let screenshots2;
   try {
-    screenshots2 = await resolveScreenshots(entries, deps.userId, deps.allowLocalScreenshots ?? false);
+    screenshots2 = await resolveScreenshots(entries, deps.userId, deps.allowLocalScreenshots ?? false, deps.readUploadedRefs);
   } catch (err) {
     return errorResult(err.message);
   }
@@ -13714,7 +14220,7 @@ async function resolveProjectScreens(deps, loaded, supplied) {
   const nested = supplied.map((e) => [e]);
   let resolvedBytes;
   try {
-    resolvedBytes = await resolveScreenshots(nested, deps.userId, deps.allowLocalScreenshots ?? false);
+    resolvedBytes = await resolveScreenshots(nested, deps.userId, deps.allowLocalScreenshots ?? false, deps.readUploadedRefs);
   } catch (err) {
     return { error: err.message };
   }
@@ -15164,6 +15670,10 @@ function parseControlPlaneResponse(op, value) {
     case "read_attachment_screens":
       if (!Array.isArray(body.screens)) throw new Error("control plane response is missing screens");
       break;
+    case "read_upload_screens":
+      if (!Array.isArray(body.screens)) throw new Error("control plane response is missing screens");
+      if (body.missing !== void 0 && !Array.isArray(body.missing)) throw new Error("control plane response has malformed missing");
+      break;
     case "refine_project":
       if (typeof body.ok !== "boolean") throw new Error("control plane response is missing refine_project result");
       if (body.ok) {
@@ -15370,8 +15880,25 @@ async function readAccountSnapshot(token2) {
   if (!body) return unavailable2("billing_unavailable");
   return snapshotFromEntitlementBody(body);
 }
+async function readAccountUserId(token2) {
+  try {
+    const res = await fetch(`${studioOrigin()}/api/billing-entitlement`, {
+      headers: { Authorization: `Bearer ${token2}`, [SHOTOPS_CLIENT_HEADER]: `shotops-mcp/${VERSION}` }
+    });
+    if (!res.ok) return null;
+    const body = await res.json().catch(() => null);
+    return typeof body?.userId === "string" && body.userId.length > 0 ? body.userId : null;
+  } catch {
+    return null;
+  }
+}
 function connectHostedBridge(token2) {
+  let accountId = null;
   return {
+    async accountUserId() {
+      accountId ??= await readAccountUserId(token2);
+      return accountId;
+    },
     async productionOperation(action, operationId) {
       const response = await callOp(token2, "production_operation", { action, operationId });
       return response.operation;
@@ -15415,6 +15942,18 @@ function connectHostedBridge(token2) {
       const res = await callOp(token2, "read_attachment_screens", { project: projectId, refs: [...refs] });
       return res.screens;
     },
+    async readUploadScreens(refs) {
+      try {
+        const res = await callOp(token2, "read_upload_screens", { refs: [...refs] });
+        return { screens: res.screens, missing: res.missing ?? [] };
+      } catch (err) {
+        if (err instanceof ControlPlaneOperationError && err.code === "foreign_refs") {
+          const named = err.refs.length > 0 ? err.refs : [...refs];
+          throw new Error(`ref does not belong to this account: ${named.join(", ")}`);
+        }
+        throw err;
+      }
+    },
     async refineProject(input) {
       return callOp(token2, "refine_project", input);
     },
@@ -15490,6 +16029,8 @@ var init_hostedBridge = __esm({
       code;
       capability;
       requiredPlan;
+      /** The refs a `read_upload_screens` refusal named (#1014); empty on every other refusal. */
+      refs;
       constructor(op, status, body) {
         const code = typeof body?.error === "string" ? body.error : null;
         super(`${op} failed (${status}${code ? ` ${code}` : ""})`);
@@ -15498,6 +16039,7 @@ var init_hostedBridge = __esm({
         this.code = code;
         this.capability = typeof body?.capability === "string" ? body.capability : null;
         this.requiredPlan = typeof body?.requiredPlan === "string" ? body.requiredPlan : null;
+        this.refs = Array.isArray(body?.refs) ? body.refs.filter((ref) => typeof ref === "string") : [];
       }
     };
     RATE_LIMIT_RETRIES = 3;
@@ -15533,6 +16075,7 @@ function createAgentTurnOp(sources) {
       authorize: ports.authorize,
       emit: ports.emit,
       unresolvedLayout: (rendered) => describeUnresolvedLayout(ports.layoutFindings(rendered)),
+      layoutCollisionFrames: (rendered) => ports.layoutFindings(rendered)?.flatMap((finding) => finding.frames) ?? null,
       commit: async ({ after, assetBindings, expectedVersion }) => {
         const current = ports.readCustody();
         const custody = assetBindings.length > 0 ? bindAgentAssets(
@@ -16882,8 +17425,8 @@ async function postClaim(body) {
   const parsed = await res.json().catch(() => null);
   return { status: res.status, body: parsed ?? {} };
 }
-function claimFailure(step, status, code) {
-  const detail = status == null ? step : `${step} (${status}${typeof code === "string" && code ? ` ${code}` : ""})`;
+function claimFailure(step2, status, code) {
+  const detail = status == null ? step2 : `${step2} (${status}${typeof code === "string" && code ? ` ${code}` : ""})`;
   return new Error(
     `Images delivered, but the editable project was not created: pending-claim ${detail}. The local render/export is still usable; retry save_project to create a fresh private claim link.`
   );
@@ -16978,6 +17521,16 @@ var init_projectClaimClient = __esm({
 
 // src/runtime/localDeps.ts
 import { readFile as readFile4 } from "node:fs/promises";
+function refsNeedAccount(refs) {
+  throw new Error(
+    `A { "ref" } screenshot needs a signed-in ShotOps account, and this local server has none (${refs.join(", ")}). Pass each screenshot as a local { "path": "\u2026" } PNG, or sign in (npx shotops-mcp login) and try again.`
+  );
+}
+async function readUploadsThroughBridge(bridge, refs) {
+  const { screens, missing } = await bridge.readUploadScreens(refs);
+  if (missing.length > 0) throw new Error(missingUploadMessage(missing[0]));
+  return new Map(await Promise.all(screens.map(async ({ ref, url }) => [ref, new Uint8Array(await downloadPng(url, `Screenshot ref "${ref}"`))])));
+}
 function localToolDeps(token2, options = {}) {
   const base = {
     // #889 — the first render on a machine with no Playwright Chromium downloads it once, here only.
@@ -17036,6 +17589,7 @@ function localToolDeps(token2, options = {}) {
         throw new Error(`Saving an editable project is ${SIGN_IN}`);
       },
       createPendingProjectClaim: (name, record8, ctx) => createAnonymousProjectClaim(name, record8, ctx?.screenshots),
+      readUploadedRefs: async (refs) => refsNeedAccount(refs),
       updateProjectRecord: async () => {
         throw new Error(`Updating a saved project is ${SIGN_IN}`);
       },
@@ -17057,6 +17611,13 @@ function localToolDeps(token2, options = {}) {
     // Read FRESH on every production request and never cached: that is what makes a revoked,
     // expired or downgraded token take effect on the next call rather than at the next restart.
     readAccountSnapshot: () => bridge.readAccountSnapshot(),
+    // #1014 — `userId` is 'local' on this tier, so the account a `{ ref }` must belong to comes
+    // from the token. Without this every ref a save was handed failed the ownership test and was
+    // dropped from the project it reported saving.
+    accountUserId: () => bridge.accountUserId(),
+    // #1014 — the same placeholder `userId` made every render path refuse the caller's own refs as
+    // "not this account's". The control plane checks them against the token's account instead.
+    readUploadedRefs: (refs) => readUploadsThroughBridge(bridge, refs),
     productionOperation: {
       execute: (_userId, action, operationId) => bridge.productionOperation(action, operationId)
     },
@@ -17186,6 +17747,7 @@ var init_localDeps = __esm({
     init_screenManifest();
     init_fingerprint();
     init_persistenceOps();
+    init_uploads();
     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.";
     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.)`;
   }
@@ -28305,6 +28867,10 @@ init_renderCredits();
 init_browserInstall();
 init_appstore();
 init_productionOperationStart();
+function panelReadFailure(err) {
+  if (err instanceof HostedOnlyPanelError) return errorResult(`failed to read panel: ${err.message}`, "unsupported_input");
+  return errorResult(`failed to read panel: ${err.message}`);
+}
 function dedupeLocales(list) {
   if (!Array.isArray(list)) return [];
   const seen = /* @__PURE__ */ new Set();
@@ -28345,7 +28911,7 @@ async function directDurableBundlePanels(input) {
       input.slots,
       locale2
     );
-    const screenshots2 = await resolveScreenshots(entries, input.deps.userId, false);
+    const screenshots2 = await resolveScreenshots(entries, input.deps.userId, false, input.deps.readUploadedRefs);
     const preset = output2?.panelPresetId ?? input.panelPresetId ?? "r69";
     const dimensions = panelDimensionsFor(preset);
     const slotSizes = screenshots2.map((slot2) => slot2.length);
@@ -28684,7 +29250,7 @@ async function emitBundle(deps, args, scope, attempt, signal) {
         }
         let screenshots2;
         try {
-          screenshots2 = await resolveScreenshots(entries, deps.userId, deps.allowLocalScreenshots ?? false);
+          screenshots2 = await resolveScreenshots(entries, deps.userId, deps.allowLocalScreenshots ?? false, deps.readUploadedRefs);
         } catch (err) {
           return { ok: false, error: err.message };
         }
@@ -28899,9 +29465,9 @@ async function emitBundle(deps, args, scope, attempt, signal) {
     readinessReport = resolvedInput.report;
     let bytesList;
     try {
-      bytesList = await Promise.all(panelEntries.map((p) => resolvePanelBytes(p, deps.userId, deps.allowLocalScreenshots ?? false)));
+      bytesList = await Promise.all(panelEntries.map((p) => resolvePanelBytes(p, deps.userId, deps.allowLocalScreenshots ?? false, deps.readUploadedRefs)));
     } catch (err) {
-      return errorResult(`failed to read panel: ${err.message}`);
+      return panelReadFailure(err);
     }
     slots = bytesList.map((bytes, i) => ({ displayPosition: i + 1, bytes: Buffer.from(bytes) }));
     previewPng = bytesList[0] ? Buffer.from(bytesList[0]) : null;
@@ -29041,7 +29607,7 @@ async function emitBundle(deps, args, scope, attempt, signal) {
     if (refused) return errorResult(refused.error);
     let screenshots2;
     try {
-      screenshots2 = await resolveScreenshots(entries, deps.userId, deps.allowLocalScreenshots ?? false);
+      screenshots2 = await resolveScreenshots(entries, deps.userId, deps.allowLocalScreenshots ?? false, deps.readUploadedRefs);
     } catch (err) {
       return errorResult(err.message);
     }
@@ -29381,7 +29947,7 @@ async function emitMultiLocaleBundle(deps, args, locales, projectName2, scope, p
       const key = "path" in p ? `path:${p.path}` : `ref:${p.ref}`;
       let pending = bytesCache.get(key);
       if (!pending) {
-        pending = resolvePanelBytes(p, deps.userId, deps.allowLocalScreenshots ?? false);
+        pending = resolvePanelBytes(p, deps.userId, deps.allowLocalScreenshots ?? false, deps.readUploadedRefs);
         bytesCache.set(key, pending);
       }
       return pending;
@@ -29397,7 +29963,7 @@ async function emitMultiLocaleBundle(deps, args, locales, projectName2, scope, p
         });
       }
     } catch (err) {
-      return errorResult(`failed to read panel: ${err.message}`);
+      return panelReadFailure(err);
     }
     const firstPanel = localeSlots[0]?.slots[0];
     previewPng = firstPanel ? Buffer.from(firstPanel.bytes) : null;
@@ -29419,7 +29985,7 @@ async function emitMultiLocaleBundle(deps, args, locales, projectName2, scope, p
       }
       let screenshots2;
       try {
-        screenshots2 = await resolveScreenshots(entries, deps.userId, deps.allowLocalScreenshots ?? false);
+        screenshots2 = await resolveScreenshots(entries, deps.userId, deps.allowLocalScreenshots ?? false, deps.readUploadedRefs);
       } catch (err) {
         return errorResult(err.message);
       }
@@ -30060,7 +30626,7 @@ async function handleSaveProject(deps, args) {
     "unsigned-new",
     listing2
   );
-  if ("error" in p) return errorResult(p.error);
+  if ("error" in p) return errorResult(p.error, p.code, p.details);
   const note = ["screenNote" in p && p.screenNote ? p.screenNote : void 0, baseNote].filter(Boolean).join(" ") || void 0;
   if ("status" in p) {
     return textResult({