@avocadostudio-ai/orchestrator-core 0.14.0 → 0.15.0

package/dist/chat/chat-pipeline-image.d.ts

@@ -1,6 +1,21 @@
 import type { Logger } from "../logger.ts";
-import { type EditPlan, type PageDoc } from "@avocadostudio-ai/shared";
+import { type EditPlan, type Operation, type PageDoc } from "@avocadostudio-ai/shared";
 import type { PendingImageGeneration } from "../state/session-state.ts";
+import { resolveUnsplashImage } from "../image/image-helpers.ts";
+export declare function setChatImageResolverForTests(fn?: typeof resolveUnsplashImage): void;
+/**
+ * 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 declare function primaryImageKeyFor(block: PageDoc["blocks"][number] | null | undefined): string | null;
 export declare function blockHasImageUrlProp(block: PageDoc["blocks"][number] | null | undefined): block is PageDoc["blocks"][number];
 export declare function parsePath(path: string): Array<string | number>;
 export declare function getValueAtPath(root: unknown, path: string): unknown;
@@ -13,11 +28,113 @@ export declare function extractReferencedItemIndices(message: string): {
     hasConstraint: boolean;
 };
 /**
- * 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 declare function blockSupportsImageAtPath(blockType: string, imagePath: string): boolean;
-export declare function detectImagePaths(value: unknown, basePath?: string, acc?: Set<string>): Set<string>;
+/**
+ * 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 declare function detectImagePaths(value: unknown, opts?: {
+    blockType?: string;
+}): Set<string>;
+/**
+ * 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 declare function isImageEditablePath(blockType: string | undefined, editablePath: string | undefined): boolean;
+/**
+ * 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 declare function imageAltPathFor(blockType: string | undefined, imagePath: string): string;
+/**
+ * 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 declare function buildImagePatchProps(blockProps: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
+/**
+ * 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 declare function setImageInPatch(patch: Record<string, unknown>, blockProps: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * Every place one op writes an image, and how to write a different image there.
+ *
+ * The deferred image passes used to ask a plan a single question — "is
+ * `patch.imageUrl` a placeholder?" — which is only ever true of an
+ * `update_props` op on a block whose image is a top-level prop. A card's image
+ * is neither of those things. The planner addresses one entry of a list with
+ * `update_item`, and the `update_props` form of the same edit nests the path
+ * (`cards[0].imageUrl`); both were invisible to those passes. So a turn that
+ * searched Unsplash twice, got two photos back and reported that it had swapped
+ * one in had nowhere to put either of them, and the placeholder the planner is
+ * told to write stayed on the page.
+ *
+ * `rewrite` is part of the site rather than left to the caller because the op
+ * that writes the image back is not the same shape as the op that asked for it
+ * — see `buildImagePatchProps` for the list-length trap it avoids.
+ */
+export type ImagePatchSite = {
+    blockId: string;
+    pageSlug: string;
+    /** The block being patched, when the page state knows it. */
+    blockType: string | undefined;
+    /** The image's path, relative to this op's patch. */
+    path: string;
+    /** Where this image's alt text belongs, relative to this op's patch. */
+    altPath: string;
+    /** What the op writes at `path` today. */
+    value: string;
+    /** What the op writes at `altPath` today, when it writes anything. */
+    alt: string | undefined;
+    /** An op writing `url` (and `alt`, when given) to the same place. */
+    rewrite: (url: string, alt?: string) => Operation;
+};
+export declare function findImagePatchSites(op: Operation, 
+/** The page as it stands now — a lookup, so the caller needs no op narrowing of its own. */
+pageAt: (slug: string) => PageDoc | null | undefined): ImagePatchSite[];
+/**
+ * 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 declare function opsAddressSameTarget(a: Operation, b: Operation): boolean;
 export declare function imageQueryFromItem(item: Record<string, unknown>, sectionContext?: string): string;
 export declare function shouldPopulateAllChildImages(message: string): boolean;
 export declare function findImageTargets(args: {
@@ -25,11 +142,29 @@ export declare function findImageTargets(args: {
     currentPage: PageDoc;
     targetBlock: PageDoc["blocks"][number];
     patchCandidate: Record<string, unknown>;
+    /**
+     * The op's `imageQuery` — what the planner said the picture should show.
+     * It becomes this block's default subject; a list item that names its own
+     * subject (a card's title, an indexed "third one: a dog") still wins, because
+     * that is more specific than one phrase for the whole block.
+     */
+    plannerQuery?: string;
 }): {
     path: string;
     altPath: string;
     query: string;
 }[];
+/**
+ * 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 declare function statedImageQuery(plan: EditPlan): string | undefined;
 export declare function rewriteAddBlockToChildImageUpdate(args: {
     plan: EditPlan;
     message: string;
@@ -76,6 +211,37 @@ export declare function resolveHeroImageForCreatePage(args: {
     alt: string;
     source: "ai-generated" | "gdrive" | "unsplash";
 } | 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 declare function isVacuousPatch(value: unknown): boolean;
+/**
+ * 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 declare function rewriteItemImageUpdateToProps(args: {
+    plan: EditPlan;
+    currentPage: PageDoc;
+    slug: string;
+}): EditPlan;
 export declare function detectImageOps(args: {
     plan: EditPlan;
     message: string;