@oscharko-dev/keiko 0.2.0-beta.8 → 0.2.0-beta.9

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/runIngestion.js

@@ -623,7 +623,9 @@ function mergeFigmaVisionHints(baselineText, hints) {
 /** Vision-augment one screen's baseline text without ever overriding it (additive only). */
 function visionAugmentedScreenText(baseline, ir, record, screen, vision) {
     const baselineText = QualityIntelligenceFigma.renderBaselineText(baseline);
-    if (vision === undefined || !screenNeedsVisionAugmentation(ir, baseline)) {
+    if (vision === undefined ||
+        !isRenderedScreenRow(screen) ||
+        !screenNeedsVisionAugmentation(ir, baseline)) {
         return { text: baselineText, fingerprintText: baselineText };
     }
     const hints = vision(figmaVisionRequest(record, screen, baselineText));
@@ -633,22 +635,128 @@ function visionAugmentedScreenText(baseline, ir, record, screen, vision) {
 }
 async function visionAugmentedScreenTextAsync(baseline, ir, record, screen, vision) {
     const baselineText = QualityIntelligenceFigma.renderBaselineText(baseline);
-    if (vision === undefined || !screenNeedsVisionAugmentation(ir, baseline)) {
+    if (vision === undefined ||
+        !isRenderedScreenRow(screen) ||
+        !screenNeedsVisionAugmentation(ir, baseline)) {
         return { text: baselineText, fingerprintText: baselineText };
     }
     const hints = await vision(figmaVisionRequest(record, screen, baselineText));
     return mergeFigmaVisionHints(baselineText, hints);
 }
+function isRenderedScreenRow(row) {
+    return "image" in row;
+}
 // Parse every screen's opaque irJson once; an unparseable screen is dropped (never crashes the run).
+// Rendered screens win if a corrupt record ever duplicates an id; structural-only rows then fill
+// the non-rendered/capped coverage gap for QI.
 function parseScreens(record) {
     const parsed = [];
+    const seen = new Set();
     for (const row of record.screens) {
         const ir = QualityIntelligenceFigma.parseScreenIr(row.irJson);
-        if (ir !== undefined)
+        if (ir !== undefined) {
             parsed.push({ row, ir });
+            seen.add(row.screenId);
+        }
+    }
+    for (const row of record.structuralScreens ?? []) {
+        if (seen.has(row.screenId))
+            continue;
+        const ir = QualityIntelligenceFigma.parseScreenIr(row.irJson);
+        if (ir !== undefined) {
+            parsed.push({ row, ir });
+            seen.add(row.screenId);
+        }
     }
     return parsed;
 }
+function scopedParsedScreens(record, screenIds) {
+    const parsed = parseScreens(record);
+    // Absent screenIds → whole snapshot (the contract's "absent = whole"). An explicitly EMPTY scope
+    // matches NOTHING — it must NEVER widen to the whole board. The route layer already rejects an empty
+    // array; this is the defense-in-depth invariant guaranteeing a scoped request can never silently fall
+    // back to every screen even if an internal caller passes an empty list.
+    if (screenIds === undefined)
+        return parsed;
+    if (screenIds.length === 0)
+        return [];
+    const wanted = new Set(screenIds);
+    return parsed.filter((screen) => wanted.has(screen.row.screenId));
+}
+// Canonicalise a scoped screen-id list (trim → drop empties → dedupe → sort) so the derived envelope
+// id / provenance ref is stable regardless of the order or duplicates a caller passed. The route layer
+// already canonicalises incoming requests; this keeps direct/internal callers consistent too.
+function canonicalFigmaScreenIds(screenIds) {
+    return [...new Set(screenIds.map((id) => id.trim()).filter((id) => id.length > 0))].sort();
+}
+function figmaSnapshotSourceRef(source) {
+    if (source.screenIds === undefined)
+        return source.snapshotRunId;
+    const canonical = canonicalFigmaScreenIds(source.screenIds);
+    return canonical.length === 0
+        ? source.snapshotRunId
+        : `${source.snapshotRunId}#${canonical.join(",")}`;
+}
+function imageSourceRef(source) {
+    return `${source.sourceKind}:${source.snapshotRunId}#${source.screenId}`;
+}
+function imageDescriptionBaseline(screenId, screenName) {
+    return ("No structural JSON is attached to this source. Describe the visible UI screenshot for " +
+        "test generation. Focus on user-visible purpose, controls, form fields, labels, states, " +
+        `layout groups, and likely validation affordances.\nScreen id: ${screenId}\nScreen name: ${screenName}`);
+}
+function imageDescriptionText(screenId, screenName, hints) {
+    const cleaned = hints
+        .map((hint) => redactFigmaAtomText(hint).trim())
+        .filter((hint) => hint.length > 0);
+    if (cleaned.length === 0)
+        return undefined;
+    return [
+        `Image description for ${screenName} (${screenId})`,
+        "",
+        ...cleaned.map((hint) => `- ${hint}`),
+    ].join("\n");
+}
+function parsedRenderedScreenForImageSource(record, source, label) {
+    const parsed = parseScreens(record).find((screen) => screen.row.screenId === source.screenId);
+    if (parsed === undefined || !isRenderedScreenRow(parsed.row)) {
+        throw new QiIngestionError("QI_IMAGE_UNAVAILABLE", `Image "${label}" could not be found in the stored Figma snapshot.`);
+    }
+    return { row: parsed.row, ir: parsed.ir };
+}
+function imageDescriptionUnavailable(label) {
+    return new QiIngestionError("QI_IMAGE_DESCRIPTION_UNAVAILABLE", `Image "${label}" could not be described. Configure an image-input capable model for Quality Intelligence image sources.`);
+}
+function imageDescriptionDocFromHints(screenId, screenName, hints, byteBudget) {
+    const text = imageDescriptionText(screenId, screenName, hints);
+    if (text === undefined)
+        return undefined;
+    const perDocBudget = Math.min(CAPSULE_MAX_BYTES_PER_DOCUMENT, byteBudget);
+    const capped = truncateToUtf8Bytes(redactFigmaAtomText(text), perDocBudget);
+    if (capped.trim().length === 0)
+        return undefined;
+    return {
+        documentId: `Image description: ${figmaDocumentId(screenId, screenName)}`,
+        text: capped,
+        fingerprintText: capped,
+    };
+}
+// Distinguish "the selected screens are not present in this snapshot" from "the snapshot produced no
+// usable baseline" so a scoped run surfaces a precise, user-actionable reason (audit: clear
+// screen-not-found error) in the streamed skippedSources notice. The code stays QI_SOURCE_EMPTY so the
+// N+1-resilience skip and the drift "all orphaned" allowance keep their existing control flow — only
+// the message is sharpened.
+function figmaSnapshotEmptyError(record, source, label) {
+    if (source.screenIds !== undefined) {
+        const requested = canonicalFigmaScreenIds(source.screenIds);
+        const present = new Set(parseScreens(record).map((screen) => screen.row.screenId));
+        const missing = requested.filter((id) => !present.has(id));
+        if (requested.length > 0 && missing.length === requested.length) {
+            return new QiIngestionError("QI_SOURCE_EMPTY", `Figma snapshot "${label}": none of the selected screens (${missing.join(", ")}) exist in this snapshot.`);
+        }
+    }
+    return new QiIngestionError("QI_SOURCE_EMPTY", `Figma snapshot "${label}" produced no usable screen baseline.`);
+}
 // Derive the deterministic navigation/flow/coverage test items per screen from the parsed screens +
 // the snapshot's raw inter-screen links (#811). Composes into the baseline below through #754's
 // `extraItems` seam. When the snapshot carries no `links` (an older record), every screen maps to no
@@ -719,13 +827,13 @@ function figmaDocFitsBudget(docs, totalBytes, nextBytes, perRunBudget) {
 // the cumulative corpus so an oversized board never hard-fails on QI_PROMPT_TOO_LARGE.
 // The byteBudget is the caller's fair share of the global evidence pool (Epic #729 N+1 split)
 // so a figma-snapshot source never consumes more than its fair slice alongside other sources.
-function figmaScreenDocs(record, vision, byteBudget) {
+function figmaScreenDocs(record, vision, byteBudget, screenIds) {
     // Mirror processCapsuleDocs (:558-563): the per-run corpus budget is the smaller of the capsule's
     // own ceiling and this source's fair share of the global evidence byte budget (Epic #729 N+1
     // split). The per-document cap is likewise never larger than the per-run budget.
     const perRunBudget = Math.min(CAPSULE_BUDGET_BYTES, byteBudget);
     const perDocBudget = Math.min(CAPSULE_MAX_BYTES_PER_DOCUMENT, perRunBudget);
-    const parsed = parseScreens(record);
+    const parsed = scopedParsedScreens(record, screenIds);
     const navItems = navItemsByScreen(parsed, record.links ?? []);
     const a11yItems = a11yItemsByScreen(parsed);
     const docs = [];
@@ -734,7 +842,9 @@ function figmaScreenDocs(record, vision, byteBudget) {
     for (const { row, ir } of parsed) {
         const extraItems = [...(navItems.get(ir.id) ?? []), ...(a11yItems.get(ir.id) ?? [])];
         const baseline = QualityIntelligenceFigma.deriveScreenTestBaseline(ir, extraItems);
-        const visionSlot = consumeVisionProviderForScreen(vision, remainingVisionScreens, ir, baseline);
+        const visionSlot = isRenderedScreenRow(row)
+            ? consumeVisionProviderForScreen(vision, remainingVisionScreens, ir, baseline)
+            : { provider: undefined, remaining: remainingVisionScreens };
         remainingVisionScreens = visionSlot.remaining;
         const augmented = visionAugmentedScreenText(baseline, ir, record, row, visionSlot.provider);
         const nextDoc = corpusDocFromFigmaScreen(row, ir, augmented, perDocBudget);
@@ -747,10 +857,10 @@ function figmaScreenDocs(record, vision, byteBudget) {
     }
     return docs;
 }
-async function figmaScreenDocsAsync(record, vision, byteBudget) {
+async function figmaScreenDocsAsync(record, vision, byteBudget, screenIds) {
     const perRunBudget = Math.min(CAPSULE_BUDGET_BYTES, byteBudget);
     const perDocBudget = Math.min(CAPSULE_MAX_BYTES_PER_DOCUMENT, perRunBudget);
-    const parsed = parseScreens(record);
+    const parsed = scopedParsedScreens(record, screenIds);
     const navItems = navItemsByScreen(parsed, record.links ?? []);
     const a11yItems = a11yItemsByScreen(parsed);
     const docs = [];
@@ -759,7 +869,9 @@ async function figmaScreenDocsAsync(record, vision, byteBudget) {
     for (const { row, ir } of parsed) {
         const extraItems = [...(navItems.get(ir.id) ?? []), ...(a11yItems.get(ir.id) ?? [])];
         const baseline = QualityIntelligenceFigma.deriveScreenTestBaseline(ir, extraItems);
-        const visionSlot = consumeVisionProviderForScreen(vision, remainingVisionScreens, ir, baseline);
+        const visionSlot = isRenderedScreenRow(row)
+            ? consumeVisionProviderForScreen(vision, remainingVisionScreens, ir, baseline)
+            : { provider: undefined, remaining: remainingVisionScreens };
         remainingVisionScreens = visionSlot.remaining;
         const augmented = await visionAugmentedScreenTextAsync(baseline, ir, record, row, visionSlot.provider);
         const nextDoc = corpusDocFromFigmaScreen(row, ir, augmented, perDocBudget);
@@ -778,15 +890,16 @@ function ingestFigmaSnapshot(source, index, registeredAt, loader, vision, byteBu
     if (record === undefined) {
         throw new QiIngestionError("QI_FIGMA_SNAPSHOT_UNAVAILABLE", `Figma snapshot "${label}" could not be found or read. Build the snapshot first.`);
     }
-    if (record.screens.length === 0) {
+    if (record.screens.length === 0 && (record.structuralScreens?.length ?? 0) === 0) {
         throw new QiIngestionError("QI_SOURCE_EMPTY", `Figma snapshot "${label}" has no screens.`);
     }
-    const docs = figmaScreenDocs(record, vision, byteBudget);
+    const docs = figmaScreenDocs(record, vision, byteBudget, source.screenIds);
     if (docs.length === 0) {
-        throw new QiIngestionError("QI_SOURCE_EMPTY", `Figma snapshot "${label}" produced no usable screen baseline.`);
+        throw figmaSnapshotEmptyError(record, source, label);
     }
     const joinedFingerprintText = docs.map((d) => d.fingerprintText ?? d.text).join("\n");
-    const envelopeId = envelopeIdFor(index, label, source.snapshotRunId);
+    const sourceRef = figmaSnapshotSourceRef(source);
+    const envelopeId = envelopeIdFor(index, label, sourceRef);
     // A stored Figma Snapshot is figma evidence, not repository context. Use the dedicated
     // `figma-evidence` envelope kind (#278 AC2 "represented as an explicit connector-backed source"
     // + AC4 citation/audit attribution) so the persisted envelope, source-mix priority, and any
@@ -796,11 +909,11 @@ function ingestFigmaSnapshot(source, index, registeredAt, loader, vision, byteBu
         kind: "figma-evidence",
         displayLabel: label,
         provenance: {
-            origin: `figma-snapshot:${source.snapshotRunId}`,
+            origin: `figma-snapshot:${sourceRef}`,
             registeredAt,
             integrityHashSha256Hex: sha256Hex(joinedFingerprintText),
         },
-        localRef: stableLocalRef("figma-snapshot", source.snapshotRunId),
+        localRef: stableLocalRef("figma-snapshot", sourceRef),
     };
     const atoms = docs.map((d) => capsuleDocAtom(d.documentId, d.text, envelopeId, d.fingerprintText ?? d.text));
     return { envelope, atoms };
@@ -811,29 +924,107 @@ async function ingestFigmaSnapshotAsync(source, index, registeredAt, loader, vis
     if (record === undefined) {
         throw new QiIngestionError("QI_FIGMA_SNAPSHOT_UNAVAILABLE", `Figma snapshot "${label}" could not be found or read. Build the snapshot first.`);
     }
-    if (record.screens.length === 0) {
+    if (record.screens.length === 0 && (record.structuralScreens?.length ?? 0) === 0) {
         throw new QiIngestionError("QI_SOURCE_EMPTY", `Figma snapshot "${label}" has no screens.`);
     }
-    const docs = await figmaScreenDocsAsync(record, vision, byteBudget);
+    const docs = await figmaScreenDocsAsync(record, vision, byteBudget, source.screenIds);
     if (docs.length === 0) {
-        throw new QiIngestionError("QI_SOURCE_EMPTY", `Figma snapshot "${label}" produced no usable screen baseline.`);
+        throw figmaSnapshotEmptyError(record, source, label);
     }
     const joinedFingerprintText = docs.map((d) => d.fingerprintText ?? d.text).join("\n");
-    const envelopeId = envelopeIdFor(index, label, source.snapshotRunId);
+    const sourceRef = figmaSnapshotSourceRef(source);
+    const envelopeId = envelopeIdFor(index, label, sourceRef);
     const envelope = {
         id: envelopeId,
         kind: "figma-evidence",
         displayLabel: label,
         provenance: {
-            origin: `figma-snapshot:${source.snapshotRunId}`,
+            origin: `figma-snapshot:${sourceRef}`,
             registeredAt,
             integrityHashSha256Hex: sha256Hex(joinedFingerprintText),
         },
-        localRef: stableLocalRef("figma-snapshot", source.snapshotRunId),
+        localRef: stableLocalRef("figma-snapshot", sourceRef),
     };
     const atoms = docs.map((d) => capsuleDocAtom(d.documentId, d.text, envelopeId, d.fingerprintText ?? d.text));
     return { envelope, atoms };
 }
+function buildImageSourceEnvelope(source, label, index, registeredAt, doc) {
+    const sourceRef = imageSourceRef(source);
+    const envelopeId = envelopeIdFor(index, label, sourceRef);
+    const envelope = {
+        id: envelopeId,
+        kind: "figma-evidence",
+        displayLabel: label,
+        provenance: {
+            origin: `image:${sourceRef}`,
+            registeredAt,
+            integrityHashSha256Hex: sha256Hex(doc.fingerprintText ?? doc.text),
+        },
+        localRef: stableLocalRef("image", sourceRef),
+    };
+    return {
+        envelope,
+        atoms: [capsuleDocAtom(doc.documentId, doc.text, envelopeId, doc.fingerprintText ?? doc.text)],
+    };
+}
+function imageDescriptionDoc(record, source, label, vision, byteBudget) {
+    if (vision === undefined)
+        return undefined;
+    const { row, ir } = parsedRenderedScreenForImageSource(record, source, label);
+    const hints = vision(figmaVisionRequest(record, row, imageDescriptionBaseline(row.screenId, ir.name)));
+    if (isPromiseLike(hints))
+        return undefined;
+    return imageDescriptionDocFromHints(row.screenId, ir.name, hints, byteBudget);
+}
+async function imageDescriptionDocAsync(record, source, label, vision, byteBudget) {
+    if (vision === undefined)
+        return undefined;
+    const { row, ir } = parsedRenderedScreenForImageSource(record, source, label);
+    const hints = await vision(figmaVisionRequest(record, row, imageDescriptionBaseline(row.screenId, ir.name)));
+    return imageDescriptionDocFromHints(row.screenId, ir.name, hints, byteBudget);
+}
+function ingestImageSource(source, index, registeredAt, loader, vision, byteBudget) {
+    const label = sanitiseLabel(source.label);
+    const record = loader(source.snapshotRunId);
+    if (record === undefined) {
+        throw new QiIngestionError("QI_IMAGE_UNAVAILABLE", `Image "${label}" could not be found or read. Build the Figma snapshot first.`);
+    }
+    const doc = imageDescriptionDoc(record, source, label, vision, byteBudget);
+    if (doc === undefined)
+        throw imageDescriptionUnavailable(label);
+    return buildImageSourceEnvelope(source, label, index, registeredAt, doc);
+}
+async function ingestImageSourceAsync(source, index, registeredAt, loader, vision, byteBudget) {
+    const label = sanitiseLabel(source.label);
+    const record = loader(source.snapshotRunId);
+    if (record === undefined) {
+        throw new QiIngestionError("QI_IMAGE_UNAVAILABLE", `Image "${label}" could not be found or read. Build the Figma snapshot first.`);
+    }
+    const doc = await imageDescriptionDocAsync(record, source, label, vision, byteBudget);
+    if (doc === undefined)
+        throw imageDescriptionUnavailable(label);
+    return buildImageSourceEnvelope(source, label, index, registeredAt, doc);
+}
+function ingestCapsuleSource(source, index, registeredAt, capsuleResolver, byteBudget) {
+    if (capsuleResolver === undefined) {
+        throw new QiIngestionError("QI_CAPSULE_UNAVAILABLE", source.kind === "capsule"
+            ? "Capsule sources are unavailable: the Local Knowledge store is not configured."
+            : "Capsule-set sources are unavailable: the Local Knowledge store is not configured.");
+    }
+    return source.kind === "capsule"
+        ? ingestCapsule(source, index, registeredAt, capsuleResolver, byteBudget)
+        : ingestCapsuleSet(source, index, registeredAt, capsuleResolver, byteBudget);
+}
+function ingestStoredFigmaSource(source, index, registeredAt, figmaSnapshotLoader, figmaVision, byteBudget) {
+    if (figmaSnapshotLoader === undefined) {
+        throw new QiIngestionError(source.kind === "image" ? "QI_IMAGE_UNAVAILABLE" : "QI_FIGMA_SNAPSHOT_UNAVAILABLE", source.kind === "image"
+            ? "Image sources are unavailable: the evidence directory is not configured."
+            : "Figma-snapshot sources are unavailable: the evidence directory is not configured.");
+    }
+    return source.kind === "image"
+        ? ingestImageSource(source, index, registeredAt, figmaSnapshotLoader, figmaVision, byteBudget)
+        : ingestFigmaSnapshot(source, index, registeredAt, figmaSnapshotLoader, figmaVision, byteBudget);
+}
 function ingestOne(source, index, registeredAt, capsuleResolver, figmaSnapshotLoader, figmaVision, byteBudget) {
     switch (source.kind) {
         case "requirements":
@@ -843,28 +1034,24 @@ function ingestOne(source, index, registeredAt, capsuleResolver, figmaSnapshotLo
         case "file":
             return ingestFile(source, index, registeredAt, byteBudget);
         case "capsule":
-            if (capsuleResolver === undefined) {
-                throw new QiIngestionError("QI_CAPSULE_UNAVAILABLE", "Capsule sources are unavailable: the Local Knowledge store is not configured.");
-            }
-            return ingestCapsule(source, index, registeredAt, capsuleResolver, byteBudget);
         case "capsule-set":
-            if (capsuleResolver === undefined) {
-                throw new QiIngestionError("QI_CAPSULE_UNAVAILABLE", "Capsule-set sources are unavailable: the Local Knowledge store is not configured.");
-            }
-            return ingestCapsuleSet(source, index, registeredAt, capsuleResolver, byteBudget);
+            return ingestCapsuleSource(source, index, registeredAt, capsuleResolver, byteBudget);
         case "figma-snapshot":
-            if (figmaSnapshotLoader === undefined) {
-                throw new QiIngestionError("QI_FIGMA_SNAPSHOT_UNAVAILABLE", "Figma-snapshot sources are unavailable: the evidence directory is not configured.");
-            }
-            return ingestFigmaSnapshot(source, index, registeredAt, figmaSnapshotLoader, figmaVision, byteBudget);
+        case "image":
+            return ingestStoredFigmaSource(source, index, registeredAt, figmaSnapshotLoader, figmaVision, byteBudget);
     }
 }
 async function ingestOneAsync(source, index, registeredAt, capsuleResolver, figmaSnapshotLoader, figmaVision, byteBudget) {
-    if (source.kind !== "figma-snapshot") {
+    if (source.kind !== "figma-snapshot" && source.kind !== "image") {
         return ingestOne(source, index, registeredAt, capsuleResolver, figmaSnapshotLoader, figmaVision, byteBudget);
     }
     if (figmaSnapshotLoader === undefined) {
-        throw new QiIngestionError("QI_FIGMA_SNAPSHOT_UNAVAILABLE", "Figma-snapshot sources are unavailable: the evidence directory is not configured.");
+        throw new QiIngestionError(source.kind === "image" ? "QI_IMAGE_UNAVAILABLE" : "QI_FIGMA_SNAPSHOT_UNAVAILABLE", source.kind === "image"
+            ? "Image sources are unavailable: the evidence directory is not configured."
+            : "Figma-snapshot sources are unavailable: the evidence directory is not configured.");
+    }
+    if (source.kind === "image") {
+        return ingestImageSourceAsync(source, index, registeredAt, figmaSnapshotLoader, figmaVision, byteBudget);
     }
     return ingestFigmaSnapshotAsync(source, index, registeredAt, figmaSnapshotLoader, figmaVision, byteBudget);
 }

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/runRoutes.d.ts

@@ -2,8 +2,15 @@ import type { QualityIntelligenceRunStreamMessage } from "@oscharko-dev/keiko-co
 import type { QualityIntelligence as QI } from "@oscharko-dev/keiko-contracts";
 import { type HandlerOutcome, type RouteContext, type RouteResult, type RouteDefinition } from "../routes.js";
 import type { Redactor, UiHandlerDeps } from "../deps.js";
+import { executeQiRun } from "./runExecution.js";
 export declare function toStreamEvent(event: QI.QualityIntelligenceRunEvent, redact: Redactor): QualityIntelligenceRunStreamMessage;
+type QiExecutionSummary = Awaited<ReturnType<typeof executeQiRun>>;
+type StreamTotals = Extract<QualityIntelligenceRunStreamMessage, {
+    type: "done";
+}>["totals"];
+export declare function doneFrameForSummary(deps: UiHandlerDeps, runId: string, summary: QiExecutionSummary, totals: StreamTotals): QualityIntelligenceRunStreamMessage;
 export declare function handleStartQiRun(ctx: RouteContext, deps: UiHandlerDeps): Promise<HandlerOutcome>;
 export declare function handleCancelQiRun(ctx: RouteContext, _deps: UiHandlerDeps): RouteResult;
 export declare const QI_RUN_EXECUTION_ROUTE_GROUP: readonly RouteDefinition[];
+export {};
 //# sourceMappingURL=runRoutes.d.ts.map

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/runRoutes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runRoutes.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/runRoutes.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAKV,mCAAmC,EAGpC,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,IAAI,EAAE,EAAE,MAAM,+BAA+B,CAAC;AAG/E,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA+N1D,wBAAgB,aAAa,CAC3B,KAAK,EAAE,EAAE,CAAC,2BAA2B,EACrC,MAAM,EAAE,QAAQ,GACf,mCAAmC,CAgBrC;AA8ED,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,cAAc,CAAC,CAoBzB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,aAAa,GAAG,WAAW,CAStF;AAED,eAAO,MAAM,4BAA4B,EAAE,SAAS,eAAe,EAOlE,CAAC"}
+{"version":3,"file":"runRoutes.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/runRoutes.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAMV,mCAAmC,EAGpC,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,IAAI,EAAE,EAAE,MAAM,+BAA+B,CAAC;AAG/E,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EACL,YAAY,EAIb,MAAM,mBAAmB,CAAC;AA4Q3B,wBAAgB,aAAa,CAC3B,KAAK,EAAE,EAAE,CAAC,2BAA2B,EACrC,MAAM,EAAE,QAAQ,GACf,mCAAmC,CAgBrC;AAkBD,KAAK,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC;AACnE,KAAK,YAAY,GAAG,OAAO,CAAC,mCAAmC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;AA0B7F,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,YAAY,GACnB,mCAAmC,CAiBrC;AAuCD,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,cAAc,CAAC,CAoBzB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,aAAa,GAAG,WAAW,CAStF;AAED,eAAO,MAAM,4BAA4B,EAAE,SAAS,eAAe,EAOlE,CAAC"}

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/runRoutes.js

@@ -12,7 +12,8 @@ import { isAbsolute } from "node:path";
 import { SSE_HEADERS } from "../sse.js";
 import { writeOrDestroy } from "../sse-write.js";
 import { STREAMING, } from "../routes.js";
-import { executeQiRun, QiGenerationError, QiIngestionError } from "./runExecution.js";
+import { executeQiRun, QiGenerationError, QiIngestionError, } from "./runExecution.js";
+import { parseFigmaSnapshotScreenIds } from "./figmaSnapshotScreenIds.js";
 import { qiRunRegistry } from "./runRegistry.js";
 const MAX_BODY_BYTES = 2 * 1024 * 1024;
 class BodyTooLargeError extends Error {
@@ -61,7 +62,37 @@ function validateFigmaSnapshotSource(label, raw) {
     if (typeof raw.snapshotRunId !== "string" || raw.snapshotRunId.trim().length === 0) {
         return errorResult(400, "QI_BAD_REQUEST", "A figma-snapshot source requires a non-empty snapshotRunId.");
     }
-    return { kind: "figma-snapshot", label, snapshotRunId: raw.snapshotRunId };
+    // Single source of truth shared with the re-check route so run/recheck never diverge. An absent
+    // field stays a whole-snapshot source; a present field must be a non-empty, bounded, canonicalised
+    // scope — an explicit empty array is rejected here so it can never silently widen to the whole board.
+    const parsed = parseFigmaSnapshotScreenIds(raw.screenIds);
+    if (!parsed.ok) {
+        return errorResult(400, "QI_BAD_REQUEST", parsed.reason);
+    }
+    return {
+        kind: "figma-snapshot",
+        label,
+        snapshotRunId: raw.snapshotRunId,
+        ...(parsed.screenIds !== undefined ? { screenIds: parsed.screenIds } : {}),
+    };
+}
+function validateImageSource(label, raw) {
+    if (raw.sourceKind !== "figma-snapshot-screen") {
+        return errorResult(400, "QI_BAD_REQUEST", "An image source requires sourceKind figma-snapshot-screen.");
+    }
+    if (typeof raw.snapshotRunId !== "string" || raw.snapshotRunId.trim().length === 0) {
+        return errorResult(400, "QI_BAD_REQUEST", "An image source requires a non-empty snapshotRunId.");
+    }
+    if (typeof raw.screenId !== "string" || raw.screenId.trim().length === 0) {
+        return errorResult(400, "QI_BAD_REQUEST", "An image source requires a non-empty screenId.");
+    }
+    return {
+        kind: "image",
+        label,
+        sourceKind: "figma-snapshot-screen",
+        snapshotRunId: raw.snapshotRunId,
+        screenId: raw.screenId,
+    };
 }
 // Connector sources (Local Knowledge capsule / capsule-set, Figma snapshot). Split out so
 // validateSource stays under the complexity budget as the source-kind union grows (Epic #710/#750).
@@ -75,6 +106,9 @@ function validateConnectorSource(label, raw) {
     if (raw.kind === "figma-snapshot") {
         return validateFigmaSnapshotSource(label, raw);
     }
+    if (raw.kind === "image") {
+        return validateImageSource(label, raw);
+    }
     return undefined;
 }
 function validateSource(raw) {
@@ -220,6 +254,36 @@ function classifyStartError(error) {
 function toWireSkippedSources(skipped) {
     return skipped.map((s) => ({ label: s.label, kind: s.kind, code: s.code }));
 }
+function writeAcceptedFrame(write, accepted) {
+    write({
+        type: "accepted",
+        runId: accepted.runId,
+        requestedAt: accepted.requestedAt,
+        sourceCount: accepted.sourceCount,
+        atomCount: accepted.atomCount,
+        ...(accepted.droppedSourceCount > 0 ? { droppedSourceCount: accepted.droppedSourceCount } : {}),
+        ...(accepted.skippedSources.length > 0
+            ? { skippedSources: toWireSkippedSources(accepted.skippedSources) }
+            : {}),
+    });
+}
+export function doneFrameForSummary(deps, runId, summary, totals) {
+    // Surface the bounded reasonSummary for BOTH a terminal failed run and a succeeded-but-degraded run
+    // (model/parser fell back to the deterministic baseline). The reason is already safeReasonSummary-
+    // bounded server-side; re-redact defensively before it reaches the wire.
+    const reasonSummary = summary.reasonSummary !== undefined
+        ? applyRedactor(deps.redactor, summary.reasonSummary)
+        : undefined;
+    const degraded = summary.status === "succeeded" && reasonSummary !== undefined ? true : undefined;
+    return {
+        type: "done",
+        runId,
+        status: summary.status,
+        totals,
+        ...(reasonSummary !== undefined ? { reasonSummary } : {}),
+        ...(degraded !== undefined ? { degraded } : {}),
+    };
+}
 async function streamRunExecution(deps, request, runId, registeredAt, signal, write) {
     const totals = { candidates: 0, findings: 0, exports: 0 };
     let terminal = "failed";
@@ -231,19 +295,7 @@ async function streamRunExecution(deps, request, runId, registeredAt, signal, wr
             registeredAt,
             signal,
             onAccepted: (accepted) => {
-                write({
-                    type: "accepted",
-                    runId: accepted.runId,
-                    requestedAt: accepted.requestedAt,
-                    sourceCount: accepted.sourceCount,
-                    atomCount: accepted.atomCount,
-                    ...(accepted.droppedSourceCount > 0
-                        ? { droppedSourceCount: accepted.droppedSourceCount }
-                        : {}),
-                    ...(accepted.skippedSources.length > 0
-                        ? { skippedSources: toWireSkippedSources(accepted.skippedSources) }
-                        : {}),
-                });
+                writeAcceptedFrame(write, accepted);
             },
             onEvent: (event) => {
                 if (event.payload.kind === "candidate:proposed")
@@ -255,7 +307,7 @@ async function streamRunExecution(deps, request, runId, registeredAt, signal, wr
             },
         });
         terminal = summary.status;
-        write({ type: "done", runId, status: summary.status, totals });
+        write(doneFrameForSummary(deps, runId, summary, totals));
     }
     catch (error) {
         const { code, message } = classifyStartError(error);

package/node_modules/@oscharko-dev/keiko-server/dist/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAyI/C,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACrE;AAID,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,eAAO,MAAM,SAAS,eAAsB,CAAC;AAC7C,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,OAAO,SAAS,CAAC;AAE5D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAElD,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,GAAG,CACzB,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,KAChB,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;CAChC;AAUD,eAAO,MAAM,UAAU,EAAE,SAAS,eAAe,EAuShD,CAAC;AA6BF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACnD;AAKD,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,UAAU,GAAG,oBAAoB,GAAG,SAAS,CA2B/C;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,CAEjE;AAED,wBAAgB,YAAY,IAAI,QAAQ,CAEvC;AAED,wBAAgB,oBAAoB,IAAI,QAAQ,CAE/C"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AA0I/C,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACrE;AAID,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,eAAO,MAAM,SAAS,eAAsB,CAAC;AAC7C,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,OAAO,SAAS,CAAC;AAE5D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAElD,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,GAAG,CACzB,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,KAChB,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;CAChC;AAUD,eAAO,MAAM,UAAU,EAAE,SAAS,eAAe,EA4ShD,CAAC;AA6BF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACnD;AAKD,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,UAAU,GAAG,oBAAoB,GAAG,SAAS,CA2B/C;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,CAEjE;AAED,wBAAgB,YAAY,IAAI,QAAQ,CAEvC;AAED,wBAAgB,oBAAoB,IAAI,QAAQ,CAE/C"}

package/node_modules/@oscharko-dev/keiko-server/dist/routes.js

@@ -23,7 +23,7 @@ import { handleBrowserApplyScreenshot, handleBrowserContent, handleBrowserEvents
 import { handleCancelLocalKnowledgeCapsuleIndexing, handleConnectLocalKnowledgeCapsule, handleCreateLocalKnowledgeCapsule, handleCreateLocalKnowledgeCapsuleSet, handleDeleteLocalKnowledgeCapsule, handleDisconnectLocalKnowledgeCapsule, handleGetLocalKnowledgeCapsule, handleListLocalKnowledgeCapsules, handleListLocalKnowledgeCapsuleSets, handleReindexLocalKnowledgeCapsule, handleStartLocalKnowledgeCapsuleIndexing, handleUpdateLocalKnowledgeCapsule, } from "./local-knowledge-handlers.js";
 import { handleRelationshipCreate, handleRelationshipDelete, handleRelationshipDependencies, handleRelationshipEvents, handleRelationshipExplain, handleRelationshipGet, handleRelationshipHealth, handleRelationshipImpact, handleRelationshipList, handleRelationshipPatch, handleRelationshipValidate, } from "./relationship-handlers.js";
 import { handleQiCapabilities, handleQiDryRunFigma, handleQiDryRunJira, handleQiSourceSelect, handleListQiRuns, handleGetQiRun, QI_HANDOFF_ROUTE_GROUP, QI_RUN_EXECUTION_ROUTE_GROUP, QI_REVIEW_ROUTE_GROUP, QI_EXPORT_ROUTE_GROUP, QI_EDIT_ROUTE_GROUP, QI_RETENTION_ROUTE_GROUP, QI_TRACEABILITY_ROUTE_GROUP, QI_RECHECK_ROUTE_GROUP, } from "./qualityIntelligence/index.js";
-import { handleFigmaListSnapshots, handleFigmaTriggerSnapshot, handleFigmaLoadSnapshot, handleFigmaLoadSnapshotImage, handleFigmaRevokeToken, } from "./qualityIntelligence/figmaSnapshotRoutes.js";
+import { handleFigmaListSnapshots, handleFigmaInspectSnapshotScreenJson, handleFigmaTriggerSnapshot, handleFigmaLoadSnapshot, handleFigmaLoadSnapshotImage, handleFigmaRevokeToken, } from "./qualityIntelligence/figmaSnapshotRoutes.js";
 import { handleFigmaGenerateCode } from "./qualityIntelligence/figmaCodegenRoutes.js";
 export const STREAMING = Symbol("streaming");
 function health() {
@@ -314,6 +314,11 @@ export const API_ROUTES = [
     { method: "POST", pattern: "/api/figma/snapshots", handler: handleFigmaTriggerSnapshot },
     { method: "GET", pattern: "/api/figma/snapshots", handler: handleFigmaListSnapshots },
     { method: "GET", pattern: "/api/figma/snapshots/:runId", handler: handleFigmaLoadSnapshot },
+    {
+        method: "GET",
+        pattern: "/api/figma/snapshots/:runId/screens/:screenId/json",
+        handler: handleFigmaInspectSnapshotScreenJson,
+    },
     {
         method: "GET",
         pattern: "/api/figma/snapshots/:runId/screens/:screenIndex/image",

package/node_modules/@oscharko-dev/keiko-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oscharko-dev/keiko-server",
-  "version": "0.2.0-beta.8",
+  "version": "0.2.0-beta.9",
   "private": true,
   "type": "module",
   "license": "Apache-2.0",