@avocadostudio-ai/orchestrator-core 0.3.2 → 0.4.0

package/dist/chat/translation-chunking.js

@@ -0,0 +1,371 @@
+import { buildFullPageTranslationChecklist } from "./chat-pipeline-translation.js";
+import { ZERO_USAGE } from "../telemetry/usage.js";
+/**
+ * Full-page translation, split into independent per-block-group requests.
+ *
+ * One request for the whole page is the wrong shape for this job. A translation
+ * re-emits every string on the page, so its *output* length scales with the page
+ * while a single request's output is strictly serial: an 8 KB page cost 9,139
+ * output tokens and 75 seconds of streaming, and a page twice that size costs
+ * twice as long. Worse, the whole thing is one all-or-nothing unit — overshoot
+ * the token ceiling on the last block and the other six are discarded too.
+ *
+ * The blocks are independent, though. Nothing in translating the FAQ depends on
+ * how the hero was translated, so the work fans out: N smaller requests in
+ * parallel, each carrying only its own blocks, merged back into one plan. Wall
+ * clock becomes the slowest chunk rather than the sum, each chunk is far from
+ * any token ceiling, and a chunk that does fail costs only its own blocks.
+ *
+ * The tradeoff is input tokens — the schema contract and site context repeat per
+ * chunk — so each chunk carries only its own slice of the page outline, and the
+ * whole path is gated on the page being big enough to be worth it.
+ */
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+function envFlagOff(raw) {
+    return /^(0|false|no|off)$/i.test((raw ?? "").trim());
+}
+function envInt(raw, fallback) {
+    const parsed = Number((raw ?? "").trim());
+    return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+export function translationChunkingConfig() {
+    return {
+        enabled: !envFlagOff(process.env.CHAT_TRANSLATION_CHUNKING),
+        /**
+         * Translatable bytes to aim for per chunk.
+         *
+         * Chunk wall clock is roughly a fixed time-to-first-token plus streaming time
+         * proportional to this. Measured on Sonnet 5: ~5s to first token, then ~130
+         * output tokens/second, and a chunk's output runs a little over one token per
+         * source byte. ~900 bytes puts streaming (~8s) in the same range as the fixed
+         * cost, which is where splitting further stops buying much and starts paying
+         * another chunk's input tokens for nothing.
+         */
+        targetBytes: envInt(process.env.CHAT_TRANSLATION_CHUNK_BYTES, 900),
+        /** Upper bound on parallel planner calls — one wave, not a stampede. */
+        maxChunks: envInt(process.env.CHAT_TRANSLATION_MAX_CHUNKS, 6),
+        /** Below these, a single request is already fast and chunking only adds input cost. */
+        minBlocks: envInt(process.env.CHAT_TRANSLATION_CHUNK_MIN_BLOCKS, 3),
+        minBytes: envInt(process.env.CHAT_TRANSLATION_CHUNK_MIN_BYTES, 1800)
+    };
+}
+/**
+ * Weigh each block by the `update_props` patch a translation has to emit for it.
+ *
+ * Two wrong answers were tried first. Block JSON size over-weights a Gallery of
+ * twenty image URLs that has nothing to translate. Translatable string length —
+ * the obvious fix — under-weights list blocks badly: a live run gave one 769-byte
+ * CardGrid the same weight as a 1030-byte prose block and then watched it take
+ * twice as long, because a list patch re-sends *every row* (a shorter array
+ * truncates the list) and pays JSON structure for each one.
+ *
+ * So the weight is the thing being predicted: build the minimal patch we ask the
+ * model for and measure it.
+ */
+function weighBlocks(page) {
+    const checklist = buildFullPageTranslationChecklist(page);
+    return checklist.map((entry) => {
+        const block = page.blocks.find((b) => b.id === entry.blockId);
+        const props = (block?.props ?? {});
+        const patch = {};
+        for (const field of entry.fields) {
+            const listMatch = field.match(/^([^[]+)\[(\d+)\]\.(.+)$/);
+            if (!listMatch) {
+                if (typeof props[field] === "string")
+                    patch[field] = props[field];
+                continue;
+            }
+            const [, listKey, rawIndex, itemField] = listMatch;
+            const source = props[listKey];
+            if (!Array.isArray(source))
+                continue;
+            const rows = patch[listKey]
+                ?? source.map(() => ({}));
+            patch[listKey] = rows;
+            const value = source[Number(rawIndex)]?.[itemField];
+            if (typeof value === "string")
+                rows[Number(rawIndex)][itemField] = value;
+        }
+        return { blockId: entry.blockId, bytes: JSON.stringify(patch).length };
+    });
+}
+/**
+ * Partition the page's translatable blocks into balanced chunks.
+ *
+ * Wall clock is the *heaviest* chunk, not the average one, so balance is the
+ * whole game: a first live run split a page into 1604 / 1010 / 172 / 769 bytes
+ * and spent 17 of its 23 seconds waiting on the first bin while a 172-byte bin
+ * sat finished. Packing blocks in page order is what produces that — it has to
+ * close a chunk before it can see what comes next.
+ *
+ * So blocks are packed heaviest-first into whichever chunk is currently lightest
+ * (longest-processing-time-first), which bounds the heaviest chunk far better,
+ * and page order is restored afterwards so the change log still reads top to
+ * bottom. Blocks are never split: an `update_props` op carries a whole block.
+ *
+ * Returns a single chunk when the page is too small to be worth splitting; the
+ * caller treats that as "don't chunk".
+ */
+export function planTranslationChunks(args) {
+    const config = translationChunkingConfig();
+    const targetBytes = args.targetBytes ?? config.targetBytes;
+    const maxChunks = args.maxChunks ?? config.maxChunks;
+    const weighted = weighBlocks(args.page);
+    if (weighted.length === 0)
+        return [];
+    const totalBytes = weighted.reduce((sum, entry) => sum + entry.bytes, 0);
+    const chunkCount = Math.min(weighted.length, maxChunks, Math.max(1, Math.ceil(totalBytes / targetBytes)));
+    if (chunkCount <= 1) {
+        return [{ blockIds: weighted.map((entry) => entry.blockId), bytes: totalBytes }];
+    }
+    const pageOrder = new Map(weighted.map((entry, index) => [entry.blockId, index]));
+    const bins = Array.from({ length: chunkCount }, () => ({ blockIds: [], bytes: 0 }));
+    // Heaviest first into the lightest bin. The first `chunkCount` blocks land in
+    // distinct empty bins, so no bin is ever left empty.
+    for (const entry of [...weighted].sort((a, b) => b.bytes - a.bytes)) {
+        const lightest = bins.reduce((min, bin) => (bin.bytes < min.bytes ? bin : min));
+        lightest.blockIds.push(entry.blockId);
+        lightest.bytes += entry.bytes;
+    }
+    for (const bin of bins)
+        bin.blockIds.sort((a, b) => pageOrder.get(a) - pageOrder.get(b));
+    bins.sort((a, b) => pageOrder.get(a.blockIds[0]) - pageOrder.get(b.blockIds[0]));
+    return bins;
+}
+/** Whether this page is worth fanning out, per the configured thresholds. */
+export function shouldChunkTranslation(page, chunks) {
+    const config = translationChunkingConfig();
+    if (!config.enabled)
+        return false;
+    if (chunks.length < 2)
+        return false;
+    const translatableBlocks = chunks.reduce((sum, chunk) => sum + chunk.blockIds.length, 0);
+    const translatableBytes = chunks.reduce((sum, chunk) => sum + chunk.bytes, 0);
+    return translatableBlocks >= config.minBlocks && translatableBytes >= config.minBytes;
+}
+// ---------------------------------------------------------------------------
+// Per-chunk request shaping
+// ---------------------------------------------------------------------------
+/**
+ * The page as this chunk should see it: same id/slug/meta, only its own blocks.
+ *
+ * Everything downstream in the planner derives from `currentPage` — the output
+ * token budget, and the enumerated translation checklist handed to the model —
+ * so narrowing the page is what makes a chunk a chunk. No extra plumbing.
+ */
+export function subsetPageForChunk(page, blockIds) {
+    return { ...page, blocks: page.blocks.filter((block) => blockIds.has(block.id)) };
+}
+/** The context pack narrowed to the chunk's blocks, so input cost doesn't repeat the whole page N times. */
+export function subsetContextPackForChunk(pack, blockIds) {
+    const outline = pack.pageOutline.filter((entry) => blockIds.has(entry.id));
+    return {
+        ...pack,
+        blockCount: outline.length,
+        pageOutline: outline,
+        // The selection and its neighbours belong to the whole-page view; a chunk is
+        // scoped by its checklist, and a stale "selected block" would pull the model
+        // toward a block this chunk may not even carry.
+        selected: { ...pack.selected, blockId: null, blockType: null, editablePath: null, block: null, imageUrlForVision: null },
+        neighbors: { previous: null, next: null }
+    };
+}
+/**
+ * Page-level ops a translation may legitimately emit, but only once. Handing the
+ * same site config to six chunks invites six conflicting `update_site_config`
+ * ops, so only the first chunk is allowed to produce them.
+ */
+const PAGE_LEVEL_OPS = new Set(["update_page_meta", "update_site_config"]);
+/** Ops that address a block, and so must address one of *this* chunk's blocks. */
+const BLOCK_SCOPED_OPS = new Set(["update_props", "update_item", "add_item", "remove_item", "move_item", "reorder_items"]);
+/**
+ * Keep only what this chunk was asked for.
+ *
+ * A chunk sees a slice of the page, but nothing stops a model from volunteering
+ * an op for a block it half-remembers from the site context, or from restructuring
+ * a page it was asked to translate. Ops outside the chunk's blocks are dropped
+ * rather than merged: a translation that also deletes a section is not a
+ * translation, and two chunks editing the same block would silently race.
+ */
+export function filterChunkOps(args) {
+    const kept = args.ops.filter((op) => {
+        if (BLOCK_SCOPED_OPS.has(op.op)) {
+            return "blockId" in op && typeof op.blockId === "string" && args.blockIds.has(op.blockId);
+        }
+        if (PAGE_LEVEL_OPS.has(op.op))
+            return args.isFirstChunk;
+        return false;
+    });
+    return { kept, droppedCount: args.ops.length - kept.length };
+}
+/**
+ * Run every chunk in parallel and merge the results into one plan.
+ *
+ * A chunk that dies on a token ceiling is retried once on its own, with double
+ * the budget — retrying one chunk is cheap where retrying the page is not. A
+ * chunk that still fails is left out: the merged plan is short those blocks, and
+ * the pipeline's translation coverage gate is what notices and repairs that. The
+ * whole call only fails when every chunk failed, so the caller's own retry loop
+ * sees a normal planner failure.
+ */
+export async function generateChunkedTranslationPlan(args) {
+    const { plannerArgs, chunks, generate } = args;
+    // Ops stream to the UI (and to the streamed-per-op apply) as they arrive from
+    // whichever chunk produced them. Order across chunks is not meaningful — each
+    // op patches a different block — but the index has to stay unique and rising,
+    // so it is handed out centrally rather than per chunk.
+    let streamedOpIndex = 0;
+    const runChunk = async (chunk, index) => {
+        const blockIds = new Set(chunk.blockIds);
+        const isFirstChunk = index === 0;
+        const startedAt = Date.now();
+        let attempts = 0;
+        let lastError;
+        for (let attempt = 1; attempt <= 2; attempt += 1) {
+            attempts = attempt;
+            try {
+                const chunkPage = subsetPageForChunk(plannerArgs.currentPage, blockIds);
+                const result = await generate({
+                    ...plannerArgs,
+                    currentPage: chunkPage,
+                    contextPack: subsetContextPackForChunk(plannerArgs.contextPack, blockIds),
+                    outputTokenScale: (plannerArgs.outputTokenScale ?? 1) * attempt,
+                    // A page-wide translation normally ships every block's schema contract,
+                    // because it edits every block. A chunk edits two — and repeating ~9 KB
+                    // of contracts per chunk would hand back in input tokens most of what
+                    // the fan-out buys.
+                    contractBlockTypeAllowlist: [...new Set(chunkPage.blocks.map((block) => String(block.type)))],
+                    // Chunks are self-contained: no tools to call, no prior turns to
+                    // resolve against. Dropping both keeps the repeated input small.
+                    history: [],
+                    toolRuntime: undefined,
+                    toolCallContext: undefined,
+                    onToolExecution: undefined,
+                    // Prose callbacks are single-sourced. Six chunks streaming their own
+                    // summary into one message box would interleave into nonsense; ops and
+                    // change-log lines are independent and stream from every chunk.
+                    onToken: isFirstChunk ? plannerArgs.onToken : undefined,
+                    onSummaryChunk: isFirstChunk ? plannerArgs.onSummaryChunk : undefined,
+                    onThinking: isFirstChunk ? plannerArgs.onThinking : undefined,
+                    onStatusUpdate: isFirstChunk ? plannerArgs.onStatusUpdate : undefined,
+                    onPlannedOp: plannerArgs.onPlannedOp
+                        ? (op) => {
+                            streamedOpIndex += 1;
+                            plannerArgs.onPlannedOp(op, streamedOpIndex);
+                        }
+                        : undefined
+                });
+                const { kept, droppedCount } = filterChunkOps({ ops: result.plan.ops, blockIds, isFirstChunk });
+                if (droppedCount > 0) {
+                    args.log?.warn({ event: "translation_chunk_ops_dropped", chunkIndex: index, droppedCount, blockIds: chunk.blockIds }, "Translation chunk returned ops outside its own blocks — dropped");
+                }
+                return {
+                    outcome: {
+                        index,
+                        blockIds: chunk.blockIds,
+                        ok: true,
+                        opCount: kept.length,
+                        droppedOpCount: droppedCount,
+                        attempts,
+                        durationMs: Date.now() - startedAt,
+                        bytes: chunk.bytes,
+                        outputTokens: result.usage?.outputTokens ?? 0
+                    },
+                    result: { ...result, plan: { ...result.plan, ops: kept } }
+                };
+            }
+            catch (error) {
+                lastError = error;
+                const message = error instanceof Error ? error.message : String(error);
+                // Only a budget failure is worth an immediate identical retry; anything
+                // else (cancellation, an API error) should surface to the caller now.
+                if (attempt === 2 || !/truncated \(max_tokens/i.test(message))
+                    break;
+                args.log?.warn({ event: "translation_chunk_retry", chunkIndex: index, blockIds: chunk.blockIds, reason: message.slice(0, 200) }, "Translation chunk truncated — retrying with a larger budget");
+            }
+        }
+        return {
+            outcome: {
+                index,
+                blockIds: chunk.blockIds,
+                ok: false,
+                opCount: 0,
+                droppedOpCount: 0,
+                attempts,
+                durationMs: Date.now() - startedAt,
+                bytes: chunk.bytes,
+                outputTokens: 0,
+                reason: lastError instanceof Error ? lastError.message : String(lastError)
+            }
+        };
+    };
+    const settled = await Promise.all(chunks.map((chunk, index) => runChunk(chunk, index)));
+    const outcomes = settled.map((entry) => entry.outcome);
+    args.onChunksSettled?.(outcomes);
+    const succeeded = settled.filter((entry) => entry.result !== undefined);
+    if (succeeded.length === 0) {
+        const firstReason = outcomes.find((outcome) => outcome.reason)?.reason ?? "translation chunks produced no plan";
+        throw new Error(firstReason);
+    }
+    return mergeChunkResults(succeeded.map((entry) => entry.result), plannerArgs.currentPage.blocks.map((block) => block.id));
+}
+/** Chunk usage is real spend on the same request — the totals have to include all of it. */
+function addUsage(a, b) {
+    const cacheCreation = (a.cacheCreationInputTokens ?? 0) + (b.cacheCreationInputTokens ?? 0);
+    const cacheRead = (a.cacheReadInputTokens ?? 0) + (b.cacheReadInputTokens ?? 0);
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        totalTokens: a.totalTokens + b.totalTokens,
+        ...(cacheCreation > 0 ? { cacheCreationInputTokens: cacheCreation } : {}),
+        ...(cacheRead > 0 ? { cacheReadInputTokens: cacheRead } : {})
+    };
+}
+/**
+ * Fold the chunk plans back into one.
+ *
+ * Chunks are balanced by weight rather than page position, so their ops come
+ * back shuffled; `blockOrder` puts them back the way the page reads, which is
+ * the order the change log and the plan preview are reviewed in.
+ *
+ * The user-facing summary is not concatenated: every chunk was given the user's
+ * original message, so every chunk wrote a summary of the same request
+ * ("Translated the page into Russian"), and stacking six of those reads like a
+ * stutter. The first one stands for all.
+ */
+export function mergeChunkResults(results, blockOrder) {
+    const ops = [];
+    const changeLog = [];
+    const seenBlockOps = new Set();
+    for (const result of results) {
+        for (const op of result.plan.ops) {
+            // Chunks are disjoint by construction, but a duplicate here would mean two
+            // ops racing to patch one block, and the loser's translation vanishing.
+            const key = "blockId" in op && typeof op.blockId === "string" ? `${op.op}:${op.blockId}` : null;
+            if (key) {
+                if (seenBlockOps.has(key))
+                    continue;
+                seenBlockOps.add(key);
+            }
+            ops.push(op);
+        }
+        for (const entry of result.plan.change_log ?? [])
+            changeLog.push(entry);
+    }
+    if (blockOrder) {
+        const rank = new Map(blockOrder.map((id, index) => [id, index]));
+        // Page-level ops carry no block, and belong at the top where the model put them.
+        const rankOf = (op) => "blockId" in op && typeof op.blockId === "string" ? rank.get(op.blockId) ?? Number.MAX_SAFE_INTEGER : -1;
+        ops.sort((a, b) => rankOf(a) - rankOf(b));
+    }
+    const summary = results.map((result) => result.plan.summary_for_user).find((text) => typeof text === "string" && text.trim().length > 0)
+        ?? "Translated the page.";
+    return {
+        plan: { intent: "edit_plan", summary_for_user: summary, change_log: changeLog, ops },
+        usage: results.reduce((total, result) => addUsage(total, result.usage), { ...ZERO_USAGE }),
+        schemaContext: results[0].schemaContext,
+        deferredNativeImageCalls: results.flatMap((result) => result.deferredNativeImageCalls ?? [])
+    };
+}

package/dist/checks/field-walk.d.ts

@@ -0,0 +1,42 @@
+import type { BlockManifest, PageDoc } from "@avocadostudio-ai/shared";
+import type { FieldEntry, LinkEntry } from "./types.ts";
+export declare function walkPageFields(page: PageDoc, manifest: BlockManifest): FieldEntry[];
+/**
+ * Readable text inside a field value.
+ *
+ * A `text` field is a string. A `richtext` field is a ProseMirror document, or
+ * markdown, or — for a custom block registered with a loose schema — something
+ * else entirely. Collecting every `text` string in the tree handles all three
+ * without the caller having to know which it got, and returns "" for a shape
+ * this does not recognise rather than guessing.
+ */
+export declare function fieldText(value: unknown): string;
+/**
+ * The page's fields, split per block, in block order.
+ *
+ * Paths and containers are *block-relative* — every block with an image has a
+ * field at `imageUrl`, every block with a list has a `cards[0]` — so any rule
+ * that indexes fields by path or container has to do it one block at a time. A
+ * page-wide index of either silently pairs one block's image with another
+ * block's alt text, which is a false negative on the page that has two heroes
+ * and a false positive with the wrong block in its evidence on the page that
+ * has two of anything else.
+ */
+export declare function groupByBlock(fields: FieldEntry[]): Map<string, FieldEntry[]>;
+/**
+ * Every link on the page, from the two places links live.
+ *
+ * The first is a `link`- or `url`-kind prop, which is what every link-aware
+ * rule already walked. The second is prose — a markdown or ProseMirror link
+ * inside a richtext body — which none of them did, and which on a content page
+ * is where most of the links are. A live site's Bistro section carries four
+ * menu-PDF links written exactly that way; not one was ever inspected, and the
+ * one pointing at a misspelled filename had been wrong for months with nothing
+ * able to see it.
+ *
+ * A prose link is attributed to the field that contains it. That is honest
+ * about what we can offer — the panel can open the body, but there is no
+ * editable path for a span inside it — and `inProse` lets a rule word its
+ * finding accordingly instead of pretending otherwise.
+ */
+export declare function walkPageLinks(page: PageDoc, manifest: BlockManifest): LinkEntry[];

package/dist/checks/field-walk.js

@@ -0,0 +1,198 @@
+import { linksInRichText } from "@avocadostudio-ai/shared";
+/*
+ * Flatten a page's block props into located, kind-tagged fields.
+ *
+ * Every rule in this directory reads the manifest to find what it cares about
+ * — an image, its alt text, a heading level — rather than naming a block type.
+ * That is not tidiness. A rule containing `Hero` is a rule that silently exempts
+ * every custom block an integrator registered, which is most of the blocks on
+ * the sites where this checker would earn its keep.
+ *
+ * Paths use the editable-target grammar (`cards[0].imageAlt`) so a finding can
+ * point at a field the property panel and the preview overlay already address,
+ * and so `proposedOps` can be written against the same string.
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function definitionFor(manifest, type) {
+    return manifest.blocks.find((b) => b.type === type);
+}
+/**
+ * Which field set applies to one item of a polymorphic list.
+ *
+ * A discriminated list renders different fields per branch; using the merged
+ * union for every item would invent fields an item does not have, and a rule
+ * would then report a missing alt text on an item that has no image.
+ */
+function itemFieldsFor(list, item) {
+    const merged = (list.itemFields ?? {});
+    if (!list.discriminator || !list.itemFieldsByType || !isRecord(item))
+        return merged;
+    const branch = item[list.discriminator];
+    if (typeof branch !== "string")
+        return merged;
+    return list.itemFieldsByType[branch] ?? merged;
+}
+/** Longer than this and the panel would be showing a paragraph, not a name. */
+const BLOCK_LABEL_MAX = 48;
+/**
+ * What a reader would call this block: its first non-empty plain-text prop.
+ *
+ * Manifest-driven like everything else here — the first `text` field in
+ * declaration order is a block's heading on every built-in block and on every
+ * custom one we have seen, and asking for `props.title` by name would find
+ * nothing on a block that calls it `headline`.
+ *
+ * `richtext` is deliberately excluded: a body is not a name, and the first 48
+ * characters of one reads as a truncated sentence rather than a label.
+ */
+function labelForBlock(definition, props) {
+    for (const [key, meta] of Object.entries(definition.fields ?? {})) {
+        if (meta.kind !== "text")
+            continue;
+        const value = props[key];
+        if (typeof value !== "string")
+            continue;
+        const trimmed = value.trim();
+        if (!trimmed)
+            continue;
+        return trimmed.length > BLOCK_LABEL_MAX ? `${trimmed.slice(0, BLOCK_LABEL_MAX - 1)}…` : trimmed;
+    }
+    return undefined;
+}
+function entriesForBlock(block, definition) {
+    if (!definition)
+        return [];
+    const props = isRecord(block.props) ? block.props : {};
+    const out = [];
+    const blockLabel = labelForBlock(definition, props);
+    const located = blockLabel ? { blockLabel } : {};
+    for (const [key, meta] of Object.entries(definition.fields ?? {})) {
+        out.push({
+            blockId: block.id,
+            blockType: block.type,
+            ...located,
+            path: key,
+            kind: meta.kind,
+            ...(meta.label ? { label: meta.label } : {}),
+            value: props[key],
+            container: ""
+        });
+    }
+    for (const [key, list] of Object.entries(definition.listFields ?? {})) {
+        const items = props[key];
+        if (!Array.isArray(items))
+            continue;
+        items.forEach((item, index) => {
+            const container = `${key}[${index}]`;
+            for (const [itemKey, meta] of Object.entries(itemFieldsFor(list, item))) {
+                out.push({
+                    blockId: block.id,
+                    blockType: block.type,
+                    ...located,
+                    path: `${container}.${itemKey}`,
+                    kind: meta.kind,
+                    ...(meta.label ? { label: meta.label } : {}),
+                    value: isRecord(item) ? item[itemKey] : undefined,
+                    container
+                });
+            }
+        });
+    }
+    return out;
+}
+export function walkPageFields(page, manifest) {
+    return page.blocks.flatMap((block) => entriesForBlock(block, definitionFor(manifest, block.type)));
+}
+/**
+ * Readable text inside a field value.
+ *
+ * A `text` field is a string. A `richtext` field is a ProseMirror document, or
+ * markdown, or — for a custom block registered with a loose schema — something
+ * else entirely. Collecting every `text` string in the tree handles all three
+ * without the caller having to know which it got, and returns "" for a shape
+ * this does not recognise rather than guessing.
+ */
+export function fieldText(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return value.map(fieldText).filter(Boolean).join(" ");
+    if (isRecord(value)) {
+        const parts = [];
+        if (typeof value.text === "string")
+            parts.push(value.text);
+        if (Array.isArray(value.content))
+            parts.push(fieldText(value.content));
+        return parts.join(" ");
+    }
+    return "";
+}
+/**
+ * The page's fields, split per block, in block order.
+ *
+ * Paths and containers are *block-relative* — every block with an image has a
+ * field at `imageUrl`, every block with a list has a `cards[0]` — so any rule
+ * that indexes fields by path or container has to do it one block at a time. A
+ * page-wide index of either silently pairs one block's image with another
+ * block's alt text, which is a false negative on the page that has two heroes
+ * and a false positive with the wrong block in its evidence on the page that
+ * has two of anything else.
+ */
+export function groupByBlock(fields) {
+    const byBlock = new Map();
+    for (const field of fields) {
+        const list = byBlock.get(field.blockId);
+        if (list)
+            list.push(field);
+        else
+            byBlock.set(field.blockId, [field]);
+    }
+    return byBlock;
+}
+/**
+ * Every link on the page, from the two places links live.
+ *
+ * The first is a `link`- or `url`-kind prop, which is what every link-aware
+ * rule already walked. The second is prose — a markdown or ProseMirror link
+ * inside a richtext body — which none of them did, and which on a content page
+ * is where most of the links are. A live site's Bistro section carries four
+ * menu-PDF links written exactly that way; not one was ever inspected, and the
+ * one pointing at a misspelled filename had been wrong for months with nothing
+ * able to see it.
+ *
+ * A prose link is attributed to the field that contains it. That is honest
+ * about what we can offer — the panel can open the body, but there is no
+ * editable path for a span inside it — and `inProse` lets a rule word its
+ * finding accordingly instead of pretending otherwise.
+ */
+export function walkPageLinks(page, manifest) {
+    const out = [];
+    for (const field of walkPageFields(page, manifest)) {
+        const located = {
+            blockId: field.blockId,
+            blockType: field.blockType,
+            ...(field.blockLabel ? { blockLabel: field.blockLabel } : {}),
+            path: field.path,
+            ...(field.label ? { label: field.label } : {})
+        };
+        if (field.kind === "link" || field.kind === "url" || field.kind === "file") {
+            if (typeof field.value === "string" && field.value.trim() !== "") {
+                out.push({ ...located, value: field.value, inProse: false });
+            }
+            continue;
+        }
+        /*
+         * Only richtext. A `text` prop holding something that looks like markdown
+         * is a string that happens to contain brackets, and treating it as prose
+         * would invent links out of product copy.
+         */
+        if (field.kind !== "richtext")
+            continue;
+        for (const href of linksInRichText(field.value)) {
+            out.push({ ...located, value: href, inProse: true });
+        }
+    }
+    return out;
+}

package/dist/checks/index.d.ts

@@ -0,0 +1,5 @@
+export { runChecksForSession, scheduleChecksAfterApply, scheduleChecksAfterPublish, cancelScheduledChecks } from "./session-runner.ts";
+export { runDraftChecks, fingerprintFor, type RunChecksArgs } from "./run-checks.ts";
+export { DRAFT_RULES } from "./rules-draft.ts";
+export { walkPageFields, fieldText, groupByBlock } from "./field-walk.ts";
+export type { CheckRule, CheckContext, RuleFinding, FieldEntry, SiteView } from "./types.ts";

package/dist/checks/index.js

@@ -0,0 +1,4 @@
+export { runChecksForSession, scheduleChecksAfterApply, scheduleChecksAfterPublish, cancelScheduledChecks } from "./session-runner.js";
+export { runDraftChecks, fingerprintFor } from "./run-checks.js";
+export { DRAFT_RULES } from "./rules-draft.js";
+export { walkPageFields, fieldText, groupByBlock } from "./field-walk.js";

package/dist/checks/page-weight.d.ts

@@ -0,0 +1,22 @@
+import { type SiteConfig } from "@avocadostudio-ai/shared";
+import type { FieldEntry, SiteView } from "./types.ts";
+export type PageWeight = {
+    slug: string;
+    /** 0–1. Only meaningful as an ordering; the absolute value is not a quantity. */
+    weight: number;
+    /** Editorial inbound links, excluding site chrome and self-links. */
+    inbound: number;
+    /** Clicks from `/` over editorial links and named nav. Null when unreached. */
+    depth: number | null;
+    /** Named in `navLabels`/`navGroups`, or linked from nearly every page. */
+    named: boolean;
+    isHome: boolean;
+    /** Nothing on the site links here and nobody named it. See `named` below. */
+    isUnlinked: boolean;
+};
+export declare function computePageWeights(args: {
+    /** Every page on the site, not only the ones being scanned. */
+    pages: SiteView["pages"];
+    fieldsBySlug: Map<string, FieldEntry[]>;
+    config: SiteConfig;
+}): Map<string, PageWeight>;