@avocadostudio-ai/orchestrator-core 0.14.0 → 0.16.0

package/dist/chat/chat-pipeline-image.js

@@ -1,18 +1,56 @@
-import { getAllBlockMeta } from "@avocadostudio-ai/shared";
+import { getAllBlockMeta, getImageFields, getImageFieldMap, getListImageFields, isChrome } from "@avocadostudio-ai/shared";
 import { inferTranslationScopeFromMessage } from "./chat-pipeline-translation.js";
 import { heroImageQueryFromContext, imageKeywordsFromQuery, generateVariationImageWithOpenAI, resolveUnsplashImage, resolveGdriveImage, isExplicitImageGenRequest, extractImagePromptFromMessage, estimatedImageGenMs, recordImageGenDuration } from "../image/image-helpers.js";
 import { isGdriveConfigured } from "../image/gdrive-client.js";
 import { firstUrlFromText, looksLikeUserInstruction, preferredImageAltText } from "./chat-pipeline-ui.js";
 import { isDemoModeEnabled, isDemoImageGenDisabled } from "../demo-mode.js";
+/**
+ * The Unsplash lookup, behind a seam.
+ *
+ * Every hermetic test runs without `UNSPLASH_ACCESS_KEY`, so this always
+ * answered null and the only image behaviour the suite could observe was the
+ * one that fires when there is no image to be had. Injecting a resolver lets a
+ * test assert what happens when there *is* one — which is where the pipeline
+ * actually decides which prop to write and where its alt text goes.
+ */
+let resolveUnsplashImageImpl = resolveUnsplashImage;
+export function setChatImageResolverForTests(fn) {
+    resolveUnsplashImageImpl = fn ?? resolveUnsplashImage;
+}
 /** Is demo mode active AND image gen disabled for demo? Memoized per call. */
 function isDemoImageGenActive() {
     return isDemoModeEnabled() && isDemoImageGenDisabled();
 }
-export function blockHasImageUrlProp(block) {
+/**
+ * Which prop on this block an image belongs in, or null if none does.
+ *
+ * Used by the last-resort path: the message asked for a photo, the planner
+ * produced no image op, so find somewhere on the page to put one. It looked
+ * for a literal `imageUrl` prop, which meant that on a site whose hero image
+ * field is `backgroundImage` the fallback found nothing and the request
+ * quietly did nothing at all.
+ *
+ * Chrome blocks are excluded: the header and the footer own the logo, and
+ * "add a photo" has never meant "replace the logo".
+ */
+export function primaryImageKeyFor(block) {
     if (!block)
-        return false;
+        return null;
     const props = block.props;
-    return typeof props === "object" && props !== null && Object.prototype.hasOwnProperty.call(props, "imageUrl");
+    if (typeof props !== "object" || props === null)
+        return null;
+    if (isChrome(block.type))
+        return null;
+    if (Object.prototype.hasOwnProperty.call(props, "imageUrl"))
+        return "imageUrl";
+    for (const key of getImageFields(block.type)) {
+        if (Object.prototype.hasOwnProperty.call(props, key))
+            return key;
+    }
+    return null;
+}
+export function blockHasImageUrlProp(block) {
+    return primaryImageKeyFor(block) !== null;
 }
 export function parsePath(path) {
     const parts = [];
@@ -151,50 +189,239 @@ export function extractReferencedItemIndices(message) {
     return { numeric, includesLast, hasConstraint: numeric.size > 0 || includesLast };
 }
 /**
- * Check whether a block type's schema supports imageUrl at a given path.
+ * Check whether a block type's schema declares an image at a given path.
  * E.g. "imageUrl" → true for Hero, "features[0].imageUrl" → false for FeatureGrid.
+ *
+ * The final key is read against the block's own field metadata rather than
+ * compared to the literal `imageUrl`, so a block whose image field is called
+ * `backgroundImage` or `photo` answers for it too.
  */
 export function blockSupportsImageAtPath(blockType, imagePath) {
     const meta = getAllBlockMeta()[blockType];
     if (!meta)
         return true; // unknown block type → optimistic
-    // Top-level imageUrl (e.g. Hero)
-    if (imagePath === "imageUrl") {
-        return "imageUrl" in meta.fields;
+    // Top-level (e.g. Hero's imageUrl)
+    const topLevel = imagePath.match(/^([a-zA-Z_][a-zA-Z0-9_]*)$/);
+    if (topLevel) {
+        const key = topLevel[1];
+        return key in meta.fields;
     }
-    // Nested: e.g. "features[0].imageUrl" or "items[2].imageUrl"
-    const listMatch = imagePath.match(/^([a-zA-Z_]+)\[\d+\]\.imageUrl$/);
+    // Nested: e.g. "features[0].imageUrl" or "items[2].photo"
+    const listMatch = imagePath.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\[\d+\]\.([a-zA-Z_][a-zA-Z0-9_]*)$/);
     if (listMatch) {
-        const listName = listMatch[1];
+        const [, listName, key] = listMatch;
         const listMeta = meta.listFields?.[listName];
         if (!listMeta)
             return false;
-        return "imageUrl" in listMeta.itemFields;
+        if (key in listMeta.itemFields)
+            return true;
+        return Object.values(listMeta.itemFieldsByType ?? {}).some((branch) => key in branch);
     }
     // Deeper nesting we can't check — be optimistic
     return true;
 }
-export function detectImagePaths(value, basePath = "", acc = new Set()) {
-    if (Array.isArray(value)) {
-        value.forEach((entry, idx) => detectImagePaths(entry, `${basePath}[${idx}]`, acc));
-        return acc;
-    }
-    if (!value || typeof value !== "object")
-        return acc;
-    const obj = value;
-    for (const [key, child] of Object.entries(obj)) {
-        const nextPath = basePath ? `${basePath}.${key}` : key;
-        if (key === "imageUrl")
-            acc.add(nextPath);
-        detectImagePaths(child, nextPath, acc);
-    }
+/**
+ * Every path inside `value` that holds an image URL.
+ *
+ * Pass `blockType` and the block's declared `kind: "image"` fields are what
+ * counts; without it — a patch whose target is unknown, or a block that ships
+ * no field metadata — only the built-in `imageUrl` name is recognised, which
+ * is what this did for every caller before the block type was threaded in.
+ */
+export function detectImagePaths(value, opts) {
+    const declared = opts?.blockType ? getImageFieldMap(opts.blockType).image : undefined;
+    const isImageKey = (key) => key === "imageUrl" || Boolean(declared?.has(key));
+    const acc = new Set();
+    const walk = (node, basePath) => {
+        if (Array.isArray(node)) {
+            node.forEach((entry, idx) => walk(entry, `${basePath}[${idx}]`));
+            return;
+        }
+        if (!node || typeof node !== "object")
+            return;
+        for (const [key, child] of Object.entries(node)) {
+            const nextPath = basePath ? `${basePath}.${key}` : key;
+            if (isImageKey(key))
+                acc.add(nextPath);
+            walk(child, nextPath);
+        }
+    };
+    walk(value, "");
     return acc;
 }
+/**
+ * Is the field the user has selected in the preview an image field?
+ *
+ * The overlay reports the path it marked — `imageUrl`, `cards[2].photo` — and
+ * the pipeline used to compare it to the string "imageUrl", so selecting the
+ * image on any block that names the field differently read as "the user is not
+ * looking at an image".
+ */
+export function isImageEditablePath(blockType, editablePath) {
+    if (!editablePath)
+        return false;
+    const lastKey = editablePath.split(".").pop() ?? editablePath;
+    if (lastKey === "imageUrl")
+        return true;
+    if (!blockType)
+        return false;
+    return getImageFieldMap(blockType).image.has(lastKey);
+}
+/**
+ * Where the alt text for the image at `imagePath` belongs.
+ *
+ * Built-in blocks pair `imageUrl` with `imageAlt`, which is why the pairing
+ * used to be a string replace — but a Gallery item pairs `imageUrl` with
+ * `alt`, so that replace produced a key the Gallery does not have. The
+ * registry knows the pairing; ask it, and keep the old replace for blocks that
+ * declare nothing.
+ */
+export function imageAltPathFor(blockType, imagePath) {
+    const lastKey = imagePath.split(".").pop() ?? imagePath;
+    const declaredAlt = blockType ? getImageFieldMap(blockType).altFor.get(lastKey) : undefined;
+    if (!declaredAlt)
+        return imagePath.replace(/imageUrl$/, "imageAlt");
+    return imagePath.slice(0, imagePath.length - lastKey.length) + declaredAlt;
+}
 function isRemoteHttpUrl(value) {
     return typeof value === "string" && /^https?:\/\//i.test(value.trim());
 }
-function patchContainsResolvedImageUrl(patch) {
-    const imagePaths = detectImagePaths(patch);
+/** The patch an op carries, whether it is wrapped in `props` or not. */
+function unwrapPatchProps(patch) {
+    if (!patch || typeof patch !== "object" || Array.isArray(patch))
+        return {};
+    const raw = patch;
+    const inner = raw.props;
+    return inner && typeof inner === "object" && !Array.isArray(inner) ? inner : raw;
+}
+/**
+ * A props patch that writes `value` at `path` without collapsing the list the
+ * path runs through.
+ *
+ * `update_props` merges a list entry by entry and keeps the *patch's* length,
+ * so the obvious construction — `setValueAtPath({}, "cards[0].imageUrl", url)`
+ * → `{ cards: [{ imageUrl: url }] }` — takes a three-card grid down to one
+ * card. The list has to be rebuilt at the length it currently has, with every
+ * entry but the addressed one left empty for the merge to fill back in.
+ */
+export function buildImagePatchProps(blockProps, path, value) {
+    const listMatch = path.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\[(\d+)\]\.(.+)$/);
+    const patch = {};
+    if (!listMatch) {
+        setValueAtPath(patch, path, value);
+        return patch;
+    }
+    const [, listKey, rawIndex, itemPath] = listMatch;
+    const index = Number(rawIndex);
+    const currentList = blockProps[listKey];
+    const length = Math.max(Array.isArray(currentList) ? currentList.length : 0, index + 1);
+    patch[listKey] = Array.from({ length }, (_, i) => {
+        if (i !== index)
+            return {};
+        const entry = {};
+        setValueAtPath(entry, itemPath, value);
+        return entry;
+    });
+    return patch;
+}
+/**
+ * Write `value` at `path` in a patch that is being edited in place, without
+ * shortening the list the path runs through.
+ *
+ * `setValueAtPath` alone creates the list it needs and no more, so writing
+ * `cards[0].imageUrl` into a patch that says nothing about `cards` produces a
+ * one-element array — and update_props keeps the patch's length, so applying it
+ * deletes every other card. That is not hypothetical: a turn asking for the
+ * first card's image planned an unrelated `{ title }` patch, the image pass
+ * added `cards[0].imageUrl` to it, and a three-card grid came back with one
+ * card in it.
+ *
+ * A patch that already carries the list is left at the length it states — a
+ * plan replacing three cards with two means it.
+ */
+export function setImageInPatch(patch, blockProps, path, value) {
+    const listMatch = path.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\[(\d+)\]\./);
+    if (listMatch) {
+        const [, listKey, rawIndex] = listMatch;
+        if (!Array.isArray(patch[listKey])) {
+            const currentList = blockProps[listKey];
+            const length = Math.max(Array.isArray(currentList) ? currentList.length : 0, Number(rawIndex) + 1);
+            patch[listKey] = Array.from({ length }, () => ({}));
+        }
+    }
+    setValueAtPath(patch, path, value);
+}
+export function findImagePatchSites(op, 
+/** The page as it stands now — a lookup, so the caller needs no op narrowing of its own. */
+pageAt) {
+    if (op.op !== "update_props" && op.op !== "update_item")
+        return [];
+    const block = pageAt(op.pageSlug)?.blocks.find((b) => b.id === op.blockId);
+    const blockType = block?.type;
+    const blockProps = block?.props ?? {};
+    const isItemOp = op.op === "update_item";
+    const patch = isItemOp ? op.patch : unwrapPatchProps(op.patch);
+    const sites = [];
+    for (const path of detectImagePaths(patch, { blockType })) {
+        const value = getValueAtPath(patch, path);
+        if (typeof value !== "string")
+            continue;
+        const altPath = imageAltPathFor(blockType, path);
+        const altValue = getValueAtPath(patch, altPath);
+        sites.push({
+            blockId: op.blockId,
+            pageSlug: op.pageSlug,
+            blockType,
+            path,
+            altPath,
+            value,
+            alt: typeof altValue === "string" ? altValue : undefined,
+            rewrite: (url, alt) => {
+                if (isItemOp && op.op === "update_item") {
+                    const itemPatch = {};
+                    setValueAtPath(itemPatch, path, url);
+                    if (alt)
+                        setValueAtPath(itemPatch, altPath, alt);
+                    return {
+                        op: "update_item",
+                        pageSlug: op.pageSlug,
+                        blockId: op.blockId,
+                        listKey: op.listKey,
+                        ...(op.itemId ? { itemId: op.itemId } : {}),
+                        ...(typeof op.index === "number" ? { index: op.index } : {}),
+                        patch: itemPatch
+                    };
+                }
+                const props = buildImagePatchProps(blockProps, path, url);
+                if (alt)
+                    setValueAtPath(props, altPath, alt);
+                return { op: "update_props", pageSlug: op.pageSlug, blockId: op.blockId, patch: { props } };
+            }
+        });
+    }
+    return sites;
+}
+/**
+ * Do two ops address the same image? Block identity is enough for
+ * `update_props`; an item op also has to agree on which entry of which list,
+ * or a plan touching two cards would patch the wrong one.
+ */
+export function opsAddressSameTarget(a, b) {
+    if (a.op !== b.op)
+        return false;
+    if (a.op !== "update_props" && a.op !== "update_item")
+        return false;
+    if (a.blockId !== b.blockId)
+        return false;
+    if (a.pageSlug !== b.pageSlug)
+        return false;
+    if (a.op === "update_item" && b.op === "update_item") {
+        return a.listKey === b.listKey && a.itemId === b.itemId && a.index === b.index;
+    }
+    return true;
+}
+function patchContainsResolvedImageUrl(patch, blockType) {
+    const imagePaths = detectImagePaths(patch, { blockType });
     for (const path of imagePaths) {
         if (isRemoteHttpUrl(getValueAtPath(patch, path)))
             return true;
@@ -247,17 +474,27 @@ export function findImageTargets(args) {
         message: args.message,
         currentPage: args.currentPage,
         targetBlock: args.targetBlock,
-        patchCandidate: args.patchCandidate
+        patchCandidate: args.patchCandidate,
+        plannerQuery: args.plannerQuery
     });
-    const imagePaths = detectImagePaths(mergedProps);
+    const blockType = args.targetBlock.type;
+    const imagePaths = detectImagePaths(mergedProps, { blockType });
     if (shouldPopulateAllChildImages(args.message)) {
+        // "add photos to all the cards" reaches items that have no image key yet,
+        // so there is nothing in the props to detect — the key has to come from
+        // what the list declares. A list that declares none keeps `imageUrl`,
+        // which is the only name this could invent before.
+        const declaredListImages = getListImageFields(blockType);
         for (const [key, value] of Object.entries(mergedProps)) {
             if (!Array.isArray(value))
                 continue;
+            const itemKeys = declaredListImages.get(key);
+            const keysToFill = itemKeys && itemKeys.size > 0 ? [...itemKeys] : ["imageUrl"];
             value.forEach((entry, idx) => {
                 if (!entry || typeof entry !== "object" || Array.isArray(entry))
                     return;
-                imagePaths.add(`${key}[${idx}].imageUrl`);
+                for (const itemKey of keysToFill)
+                    imagePaths.add(`${key}[${idx}].${itemKey}`);
             });
         }
     }
@@ -268,7 +505,7 @@ export function findImageTargets(args) {
         .join(" ");
     const targets = [];
     for (const path of imagePaths) {
-        const itemMatch = path.match(/^(.*\[(\d+)\])\.imageUrl$/);
+        const itemMatch = path.match(/^(.*\[(\d+)\])\.[a-zA-Z_][a-zA-Z0-9_]*$/);
         const index = itemMatch?.[2] ? Number(itemMatch[2]) : undefined;
         const itemPath = itemMatch?.[1];
         if (constrainedIndices.hasConstraint && itemPath && index !== undefined) {
@@ -291,10 +528,30 @@ export function findImageTargets(args) {
         }
         if (!query)
             query = defaultQuery;
-        targets.push({ path, altPath: path.replace(/imageUrl$/, "imageAlt"), query });
+        targets.push({ path, altPath: imageAltPathFor(blockType, path), query });
     }
     return targets;
 }
+/**
+ * The image subject the planner stated anywhere in this plan.
+ *
+ * The two hero fallbacks below fire when no op yielded an image target — the
+ * plan named a block this page does not have, or patched nothing an image
+ * could hang on. The request was still about an image and the planner still
+ * said what it should show, so that answer beats re-deriving one from the
+ * sentence. Ops are checked in order and the first stated subject wins; a plan
+ * that resolves several images by this route is not a case worth guessing at.
+ */
+export function statedImageQuery(plan) {
+    for (const op of plan.ops) {
+        if (op.op !== "update_props")
+            continue;
+        const stated = op.imageQuery?.trim();
+        if (stated)
+            return stated;
+    }
+    return undefined;
+}
 export function rewriteAddBlockToChildImageUpdate(args) {
     if (args.plan.intent !== "edit_plan")
         return args.plan;
@@ -491,21 +748,22 @@ export async function withUnsplashHeroImage(args) {
         const patchCandidate = rawPatch && typeof rawPatch.props === "object" && rawPatch.props !== null && !Array.isArray(rawPatch.props)
             ? rawPatch.props
             : rawPatch;
-        const touchesImage = detectImagePaths(patchCandidate).size > 0 ||
-            args.activeEditablePath === "imageUrl" ||
+        const touchesImage = detectImagePaths(patchCandidate, { blockType: target.type }).size > 0 ||
+            isImageEditablePath(target.type, args.activeEditablePath) ||
             /\b(images?|photos?|pictures?)\b/.test(lowerMessage);
         const userProvidedExplicitUrl = Boolean(firstUrlFromText(args.message));
         const targets = findImageTargets({
             message: args.message,
             currentPage: args.currentPage,
             targetBlock: target,
-            patchCandidate
+            patchCandidate,
+            plannerQuery: op.imageQuery
         });
-        // Filter out targets whose block schema doesn't support imageUrl at that path
+        // Filter out targets whose block schema doesn't declare an image at that path
         const supportedTargets = targets.filter((t) => blockSupportsImageAtPath(target.type, t.path));
         const unresolvedTargets = supportedTargets.filter((t) => !isRemoteHttpUrl(getValueAtPath(patchCandidate, t.path)));
         const hasAnyImageTarget = supportedTargets.length > 0;
-        const hasImageUrlInPatch = detectImagePaths(patchCandidate).size > 0;
+        const hasImageUrlInPatch = detectImagePaths(patchCandidate, { blockType: target.type }).size > 0;
         const shouldReplace = !userProvidedExplicitUrl && touchesImage && hasAnyImageTarget && unresolvedTargets.length > 0 && (explicitUnsplashRequest || hasImageUrlInPatch || explicitImageGen);
         if (!touchesImage || !shouldReplace || unresolvedTargets.length === 0)
             continue;
@@ -568,7 +826,7 @@ export async function withUnsplashHeroImage(args) {
                 if (currentImageUrl)
                     globalUsedImageUrls.add(currentImageUrl);
                 const usedImageUrls = globalUsedImageUrls.size > 0 ? globalUsedImageUrls : undefined;
-                resolved = await resolveUnsplashImage(imageQuery, { subjectKeywords: imageKeywordsFromQuery(imageQuery, 4), usedImageUrls }, { chatRequestId: args.chatRequestId, logger: args.log });
+                resolved = await resolveUnsplashImageImpl(imageQuery, { subjectKeywords: imageKeywordsFromQuery(imageQuery, 4), usedImageUrls }, { chatRequestId: args.chatRequestId, logger: args.log });
                 if (resolved)
                     imageSource = resolved.url.includes("unsplash") ? "unsplash" : "placeholder";
             }
@@ -580,7 +838,7 @@ export async function withUnsplashHeroImage(args) {
                 skippedImageCount++;
                 continue;
             }
-            setValueAtPath(patchCandidate, targetImage.path, resolved.url);
+            setImageInPatch(patchCandidate, targetProps, targetImage.path, resolved.url);
             const existingAlt = getValueAtPath(patchCandidate, targetImage.altPath);
             const nextAlt = preferredImageAltText({
                 query: imageQuery,
@@ -588,7 +846,7 @@ export async function withUnsplashHeroImage(args) {
                 existingAlt: typeof existingAlt === "string" ? existingAlt : undefined
             });
             if (nextAlt.trim().length > 0)
-                setValueAtPath(patchCandidate, targetImage.altPath, nextAlt);
+                setImageInPatch(patchCandidate, targetProps, targetImage.altPath, nextAlt);
             sourceQuery = resolved.query;
             args.log.info({
                 event: "image_rewrite_applied",
@@ -596,6 +854,12 @@ export async function withUnsplashHeroImage(args) {
                 slug: args.slug,
                 blockId: op.blockId,
                 query: imageQuery,
+                // What the planner said the picture should show, logged next to what
+                // was actually searched for. A trace where these differ, or where
+                // this is absent on an image request, is the whole failure mode:
+                // otherwise the only way to tell a stated subject from one
+                // reconstructed off the block's heading is to re-derive it by hand.
+                plannerQuery: op.imageQuery,
                 explicitUnsplashRequest,
                 path: targetImage.path,
                 nextImageUrl: resolved.url,
@@ -617,7 +881,7 @@ export async function withUnsplashHeroImage(args) {
         const patchCandidate = patch && typeof patch.props === "object" && patch.props !== null && !Array.isArray(patch.props)
             ? patch.props
             : patch;
-        return patchContainsResolvedImageUrl(patchCandidate);
+        return patchContainsResolvedImageUrl(patchCandidate, args.currentPage.blocks.find((block) => block.id === op.blockId)?.type);
     });
     if (!changed && !planAlreadyHasResolvedImage && (explicitUnsplashRequest || explicitImageGen) && /\b(images?|photos?|pictures?|hero)\b/.test(lowerMessage)) {
         const selectedBlock = args.activeBlockId && args.currentPage.blocks.find((block) => block.id === args.activeBlockId)
@@ -630,7 +894,8 @@ export async function withUnsplashHeroImage(args) {
             const query = heroImageQueryFromContext({
                 message: args.message,
                 currentPage: args.currentPage,
-                targetBlock: fallbackHero
+                targetBlock: fallbackHero,
+                plannerQuery: statedImageQuery(plan)
             });
             let resolved = null;
             if (!explicitUnsplashRequest && process.env.OPENAI_API_KEY && (explicitImageGen || userImagePrompt)) {
@@ -681,9 +946,10 @@ export async function withUnsplashHeroImage(args) {
             if (!resolved) {
                 args.onStatusUpdate?.("Finding a suitable image...");
                 const fbProps = fallbackHero.props;
-                const fbCurrentUrl = typeof fbProps.imageUrl === "string" ? fbProps.imageUrl : "";
+                const fbImageKey = primaryImageKeyFor(fallbackHero) ?? "imageUrl";
+                const fbCurrentUrl = typeof fbProps[fbImageKey] === "string" ? fbProps[fbImageKey] : "";
                 const fbUsedUrls = fbCurrentUrl ? new Set([fbCurrentUrl]) : undefined;
-                resolved = await resolveUnsplashImage(query, { subjectKeywords: imageKeywordsFromQuery(query, 4), usedImageUrls: fbUsedUrls }, { chatRequestId: args.chatRequestId, logger: args.log });
+                resolved = await resolveUnsplashImageImpl(query, { subjectKeywords: imageKeywordsFromQuery(query, 4), usedImageUrls: fbUsedUrls }, { chatRequestId: args.chatRequestId, logger: args.log });
                 if (resolved)
                     imageSource = resolved.url.includes("unsplash") ? "unsplash" : "placeholder";
             }
@@ -692,11 +958,15 @@ export async function withUnsplashHeroImage(args) {
                 placeholderSkipped = true;
             }
             else {
+                const imageKey = primaryImageKeyFor(fallbackHero) ?? "imageUrl";
                 plan.ops.push({
                     op: "update_props",
                     pageSlug: args.slug,
                     blockId: fallbackHero.id,
-                    patch: { imageUrl: resolved.url, imageAlt: preferredImageAltText({ query, resolvedAlt: resolved.alt }) }
+                    patch: {
+                        [imageKey]: resolved.url,
+                        [imageAltPathFor(fallbackHero.type, imageKey)]: preferredImageAltText({ query, resolvedAlt: resolved.alt })
+                    }
                 });
                 sourceQuery = resolved.query;
                 changed = true;
@@ -792,12 +1062,75 @@ export async function resolveHeroImageForCreatePage(args) {
         }
     }
     args.onStatusUpdate?.("Finding image for new page...");
-    const resolved = await resolveUnsplashImage(args.query, { subjectKeywords: imageKeywordsFromQuery(args.query, 4) }, { chatRequestId: args.chatRequestId, logger: args.log });
+    const resolved = await resolveUnsplashImageImpl(args.query, { subjectKeywords: imageKeywordsFromQuery(args.query, 4) }, { chatRequestId: args.chatRequestId, logger: args.log });
     if (resolved && resolved.url.includes("unsplash")) {
         return { url: resolved.url, alt: resolved.alt, source: "unsplash" };
     }
     return null;
 }
+/**
+ * Is this patch all structure and no content — nothing but empty objects and
+ * empty lists of them?
+ *
+ * `{}` is obviously nothing. `{ cards: [{}, {}, {}] }` is the same nothing
+ * wearing the shape a list patch has to wear to keep its length, and the ops
+ * engine skips it as an unchanged value. Callers that need to know whether
+ * stripping a patch left anything behind have to ask the second question too.
+ */
+export function isVacuousPatch(value) {
+    if (Array.isArray(value))
+        return value.every(isVacuousPatch);
+    if (value && typeof value === "object")
+        return Object.values(value).every(isVacuousPatch);
+    return false;
+}
+/**
+ * Rewrite an `update_item` that sets an image into the nested `update_props`
+ * form, so the image passes can see it at all.
+ *
+ * `detectImageOps` and `withUnsplashHeroImage` both walk `update_props` ops and
+ * read image paths out of the block's merged props — `cards[0].imageUrl`. An
+ * item op carries exactly that edit in a shape neither reads. For a planner
+ * with image tools to call that only costs a detour; for one without them —
+ * OpenAI defers no image tools, and it is the default planner — those two
+ * passes are the *only* route to a real photo, so the stand-in the prompt tells
+ * the model to write was the final answer. A card kept `/hero-generated.svg`
+ * under a summary saying a photo had been found.
+ *
+ * Only item ops that actually set an image are rewritten. An item op changing
+ * text keeps its shape, which addresses the entry far more precisely.
+ */
+export function rewriteItemImageUpdateToProps(args) {
+    if (args.plan.intent !== "edit_plan")
+        return args.plan;
+    let changed = false;
+    const ops = args.plan.ops.map((op) => {
+        if (op.op !== "update_item" || op.pageSlug !== args.slug)
+            return op;
+        const block = args.currentPage.blocks.find((b) => b.id === op.blockId);
+        if (!block)
+            return op;
+        const patch = op.patch;
+        if (detectImagePaths(patch, { blockType: block.type }).size === 0)
+            return op;
+        const list = block.props[op.listKey];
+        if (!Array.isArray(list))
+            return op;
+        const index = op.itemId
+            ? list.findIndex((entry) => entry && typeof entry === "object" && entry.id === op.itemId)
+            : typeof op.index === "number" ? op.index : -1;
+        if (index < 0 || index >= list.length)
+            return op;
+        changed = true;
+        return {
+            op: "update_props",
+            pageSlug: op.pageSlug,
+            blockId: op.blockId,
+            patch: { props: { [op.listKey]: list.map((_, i) => (i === index ? { ...patch } : {})) } }
+        };
+    });
+    return changed ? { ...args.plan, ops } : args.plan;
+}
 // ---------------------------------------------------------------------------
 // Synchronous image-op detection (no API calls)
 // ---------------------------------------------------------------------------
@@ -827,17 +1160,18 @@ export function detectImageOps(args) {
         const patchCandidate = rawPatch && typeof rawPatch.props === "object" && rawPatch.props !== null && !Array.isArray(rawPatch.props)
             ? rawPatch.props
             : rawPatch;
-        const touchesImage = detectImagePaths(patchCandidate).size > 0 ||
-            args.activeEditablePath === "imageUrl" ||
+        const touchesImage = detectImagePaths(patchCandidate, { blockType: target.type }).size > 0 ||
+            isImageEditablePath(target.type, args.activeEditablePath) ||
             /\b(images?|photos?|pictures?)\b/.test(lowerMessage);
         const userProvidedExplicitUrl = Boolean(firstUrlFromText(args.message));
         const targets = findImageTargets({
             message: args.message,
             currentPage: args.currentPage,
             targetBlock: target,
-            patchCandidate
+            patchCandidate,
+            plannerQuery: op.imageQuery
         });
-        const hasImageUrlInPatch = detectImagePaths(patchCandidate).size > 0;
+        const hasImageUrlInPatch = detectImagePaths(patchCandidate, { blockType: target.type }).size > 0;
         const shouldReplace = !userProvidedExplicitUrl &&
             touchesImage &&
             targets.length > 0 &&
@@ -871,7 +1205,7 @@ export function detectImageOps(args) {
         const patchCandidate = patch && typeof patch.props === "object" && patch.props !== null && !Array.isArray(patch.props)
             ? patch.props
             : patch;
-        return patchContainsResolvedImageUrl(patchCandidate);
+        return patchContainsResolvedImageUrl(patchCandidate, args.currentPage.blocks.find((block) => block.id === op.blockId)?.type);
     });
     if (results.length === 0 && !planAlreadyHasResolvedImage && (explicitUnsplashRequest || explicitImageGen) && /\b(images?|photos?|pictures?|hero)\b/.test(lowerMessage)) {
         const selectedBlock = args.activeBlockId && args.currentPage.blocks.find((block) => block.id === args.activeBlockId)
@@ -884,13 +1218,22 @@ export function detectImageOps(args) {
             const query = heroImageQueryFromContext({
                 message: args.message,
                 currentPage: args.currentPage,
-                targetBlock: fallbackHero
+                targetBlock: fallbackHero,
+                plannerQuery: statedImageQuery(args.plan)
             });
             const provider = explicitGdriveRequest && isGdriveConfigured() ? "gdrive"
                 : explicitUnsplashRequest ? "unsplash"
                     : process.env.OPENAI_API_KEY ? "auto"
                         : "unsplash";
-            results.push({ blockId: fallbackHero.id, pageSlug: args.slug, query, provider });
+            const path = primaryImageKeyFor(fallbackHero) ?? "imageUrl";
+            results.push({
+                blockId: fallbackHero.id,
+                pageSlug: args.slug,
+                query,
+                provider,
+                path,
+                altPath: imageAltPathFor(fallbackHero.type, path)
+            });
         }
     }
     return results;