@oscharko-dev/keiko 0.2.0-beta.5 → 0.2.0-beta.7

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

@@ -9,11 +9,13 @@
 //
 //   2. The capability-routed VISION hint provider — consults `resolveQiMultimodalSelection` (#810)
 //      to decide whether a multimodal model is available; when one is, it MAY call an injected
-//      `visionCall` to recover image-derived semantics, returning them as additive hints. There is
+//      server-owned vision call to recover image-derived semantics from the STORED render side-file,
+//      returning them as additive hints. There is
 //      NO hard-coded model id. On "unavailable", a thrown call, or a non-array/garbage result the
 //      provider returns `[]`, so the source degrades silently to the deterministic IR-only baseline.
-//      No model port is wired here yet, so the default provider is IR-only by construction — the
-//      seam is ready for the multimodal port without any further refactor of the ingestion path.
+//      The call goes through deps.modelPortFactory / Model Gateway only — no provider SDK and no
+//      Figma egress after snapshot build.
+import { Buffer } from "node:buffer";
 import { createNodeFigmaSnapshotStore, } from "@oscharko-dev/keiko-evidence";
 import { resolveQiMultimodalSelection } from "./modelSelection.js";
 /**
@@ -48,11 +50,143 @@ export function makeFigmaSnapshotLoader(deps, options) {
         }
     };
 }
+const MAX_VISION_IMAGE_BYTES = 4 * 1024 * 1024;
+const MAX_VISION_BASELINE_BYTES = 12_000;
+const MAX_VISION_HINTS = 24;
+const FIGMA_VISION_TIMEOUT_MS = 30_000;
+const encoder = new TextEncoder();
+function utf8ByteLength(value) {
+    return encoder.encode(value).length;
+}
+function truncateUtf8(value, maxBytes) {
+    if (utf8ByteLength(value) <= maxBytes)
+        return value;
+    let out = "";
+    let bytes = 0;
+    for (const cp of value) {
+        const cpBytes = utf8ByteLength(cp);
+        if (bytes + cpBytes > maxBytes)
+            break;
+        out += cp;
+        bytes += cpBytes;
+    }
+    return out;
+}
+function redactedString(deps, value) {
+    const redacted = deps.redactor(value);
+    return typeof redacted === "string" ? redacted : "";
+}
 function sanitiseCallResult(value) {
     if (!Array.isArray(value))
         return [];
     return value.filter((entry) => typeof entry === "string");
 }
+function parseHintResponse(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return [];
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed))
+            return sanitiseCallResult(parsed).slice(0, MAX_VISION_HINTS);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            Array.isArray(parsed.hints)) {
+            return sanitiseCallResult(parsed.hints).slice(0, MAX_VISION_HINTS);
+        }
+    }
+    catch {
+        return [];
+    }
+    return [];
+}
+function visionUserText(request, baselineText) {
+    return (`Screen id: ${request.screenId}\n` +
+        "Structural baseline, already authoritative:\n" +
+        `${baselineText}\n\n` +
+        "Return only visual/semantic hints that are absent from the baseline.");
+}
+function buildVisionRequest(request, modelId, dataUrl, baselineText, structuredOutput) {
+    const userText = visionUserText(request, baselineText);
+    return {
+        modelId,
+        messages: [
+            {
+                role: "system",
+                content: "You are an additive UI test-generation vision pass. Use the image only to recover " +
+                    "semantics missing from the structural baseline. Do not contradict, replace, or restate " +
+                    "the baseline. Return concise JSON: an array of strings.",
+            },
+            {
+                role: "user",
+                content: userText,
+                contentParts: [
+                    { type: "text", text: userText },
+                    { type: "image_url", image_url: { url: dataUrl } },
+                ],
+            },
+        ],
+        ...(structuredOutput
+            ? {
+                responseFormat: {
+                    type: "json_schema",
+                    schema: {
+                        type: "array",
+                        items: { type: "string" },
+                        maxItems: MAX_VISION_HINTS,
+                    },
+                },
+            }
+            : {}),
+    };
+}
+function createVisionAbortSignal() {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort();
+    }, FIGMA_VISION_TIMEOUT_MS);
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            clearTimeout(timeout);
+        },
+    };
+}
+function makeGatewayFigmaVisionCall(deps, options) {
+    const evidenceDir = deps.evidenceDir;
+    if (evidenceDir === undefined || evidenceDir.length === 0)
+        return undefined;
+    const store = createNodeFigmaSnapshotStore(evidenceDir);
+    // Capture the structured-output flag once at closure-creation, not per screen. The multimodal
+    // selection is stable for the lifetime of the provider (deps is immutable after server init),
+    // so re-calling resolveQiMultimodalSelection on every vision call is redundant work.
+    const closureSelection = resolveQiMultimodalSelection(deps);
+    const closureModelSelection = closureSelection.kind === "model" ? closureSelection : undefined;
+    return async (request, modelId) => {
+        if (request.image.byteLength > MAX_VISION_IMAGE_BYTES)
+            return [];
+        const model = deps.modelPortFactory(modelId);
+        if (model === undefined)
+            return [];
+        const image = store.loadImage(request.snapshotRunId, request.image);
+        if (image.byteLength > MAX_VISION_IMAGE_BYTES)
+            return [];
+        const dataUrl = `data:${image.mimeType};base64,${Buffer.from(image.bytes).toString("base64")}`;
+        const baselineText = truncateUtf8(redactedString(deps, request.baselineText), MAX_VISION_BASELINE_BYTES);
+        const structuredOutput = closureModelSelection?.modelId === modelId &&
+            closureModelSelection.capability.supportsResponseFormat === true;
+        const gatewayRequest = buildVisionRequest(request, modelId, dataUrl, baselineText, structuredOutput);
+        const abort = createVisionAbortSignal();
+        try {
+            options.onGatewayCallAttempt?.();
+            const response = await model.call(gatewayRequest, abort.signal);
+            return parseHintResponse(redactedString(deps, response.content));
+        }
+        finally {
+            abort.cleanup();
+        }
+    };
+}
 /**
  * Build a capability-routed vision hint provider. When no multimodal capability is configured (or no
  * `visionCall` is injected), every request returns `[]` — the deterministic IR-only baseline path.
@@ -60,15 +194,19 @@ function sanitiseCallResult(value) {
  * garbage result is swallowed to `[]` so a misbehaving model can never break the run or override the
  * structural baseline. No model id is hard-coded — selection is via `resolveQiMultimodalSelection`.
  */
-export function makeFigmaVisionHintProvider(deps, visionCall) {
+export function makeFigmaVisionHintProvider(deps, visionCall, options = {}) {
+    const resolvedVisionCall = visionCall ?? makeGatewayFigmaVisionCall(deps, options);
     const selection = resolveQiMultimodalSelection(deps);
-    if (selection.kind === "unavailable" || visionCall === undefined) {
+    if (selection.kind === "unavailable" || resolvedVisionCall === undefined) {
         return () => [];
     }
     const { modelId } = selection;
     return (request) => {
         try {
-            return sanitiseCallResult(visionCall(request, modelId));
+            const result = resolvedVisionCall(request, modelId);
+            return typeof result.then === "function"
+                ? Promise.resolve(result).then(sanitiseCallResult, () => [])
+                : sanitiseCallResult(result);
         }
         catch {
             return [];

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

@@ -10,8 +10,17 @@ export interface GovernedSnapshotDeps {
     readonly now: string;
     /** When true, record the read-only-scope acknowledgement before the fetch (operator consent). */
     readonly acknowledgeReadOnly?: boolean;
+    /**
+     * Route orchestration sets this true so `snapshot`/`resnapshot` success is audited only after the
+     * evidence record has been durably persisted and reloaded.
+     */
+    readonly deferSuccessAudit?: boolean;
     /** Deep scoped-pagination overrides (#837). */
     readonly pagination?: Partial<ScopedPaginationLimits>;
+    /** Optional pinned Figma file version. When present it is sent to the scoped REST fetch. */
+    readonly version?: string | undefined;
+    /** Optional Keiko config PAT alternate (#751). Vault remains higher precedence. */
+    readonly configToken?: string | undefined;
     /** Shared enterprise egress settings for Figma API + render downloads (#802). */
     readonly egress?: OutboundHttpEgressConfig | undefined;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"figmaSnapshotOrchestration.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/figmaSnapshotOrchestration.ts"],"names":[],"mappings":"AAeA,OAAO,EAOL,qBAAqB,EAQrB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACpF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iDAAiD,CAAC;AAKhG,KAAK,cAAc,GAAG,wBAAwB,CAAC,cAAc,CAAC;AAE9D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,uFAAuF;IACvF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iGAAiG;IACjG,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACtD,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,GAAG,SAAS,CAAC;IACvD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAEvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,mBAAmB,CAAC;CAC/C;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;CAClC;AAMD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,oBAAoB,KAAG,MAAM,GAAG,SAWzE,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,GAC7B,MAAM,IAAI,CAAC,oBAAoB,EAAE,KAAK,GAAG,aAAa,GAAG,gBAAgB,CAAC,KACzE,UAAU,CAAC,OAAO,qBAAqB,CAOzC,CAAC;AAqDF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAChC,WAAW,MAAM,EACjB,MAAM,oBAAoB,EAC1B,sBAAoB,KACnB,OAAO,CAAC,sBAAsB,CAmDhC,CAAC"}
+{"version":3,"file":"figmaSnapshotOrchestration.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/figmaSnapshotOrchestration.ts"],"names":[],"mappings":"AAeA,OAAO,EAOL,qBAAqB,EAUrB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAElB,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACpF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iDAAiD,CAAC;AAKhG,KAAK,cAAc,GAAG,wBAAwB,CAAC,cAAc,CAAC;AAE9D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,uFAAuF;IACvF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iGAAiG;IACjG,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACtD,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,mFAAmF;IACnF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,GAAG,SAAS,CAAC;IACvD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAEvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,mBAAmB,CAAC;CAC/C;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;CAClC;AAMD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,oBAAoB,KAAG,MAAM,GAAG,SAWzE,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,GAC7B,MAAM,IAAI,CAAC,oBAAoB,EAAE,KAAK,GAAG,aAAa,GAAG,gBAAgB,CAAC,KACzE,UAAU,CAAC,OAAO,qBAAqB,CAOzC,CAAC;AAsJF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAChC,WAAW,MAAM,EACjB,MAAM,oBAAoB,EAC1B,sBAAoB,KACnB,OAAO,CAAC,sBAAsB,CA+ChC,CAAC"}

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

@@ -12,7 +12,7 @@
 // The vault degrades gracefully — an unconfigured vault yields `undefined` and the build falls back to
 // the config/env token, so the existing env-auth path keeps working unchanged.
 import { join } from "node:path";
-import { appendFigmaConnectorAudit, assertReadOnlyConsent, buildFigmaSnapshot, createDefaultFigmaHttpPort, createDefaultFigmaRenderPort, createFigmaConnector, createFigmaTokenStore, deriveFigmaScopeRef, FigmaConnectorError, observeFigmaSnapshot, parseFigmaTarget, recordReadOnlyConsent, resolveFigmaToken, resolveFigmaVaultKey, } from "./figma/index.js";
+import { appendFigmaConnectorAudit, assertReadOnlyConsent, buildFigmaSnapshot, createDefaultFigmaHttpPort, createDefaultFigmaRenderPort, createFigmaConnector, createFigmaTokenStore, deriveFigmaScopeRef, FigmaConnectorError, loadFigmaConnectorAudit, observeFigmaSnapshot, parseFigmaTarget, recordReadOnlyConsent, resolveFigmaToken, resolveScopedPaginationLimits, resolveFigmaVaultKey, } from "./figma/index.js";
 import { QualityIntelligenceFigma } from "@oscharko-dev/keiko-quality-intelligence";
 const FIGMA_VAULT_SUBDIR = "figma";
 const FIGMA_TOKEN_VAULT_FILE = "figma-token.vault";
@@ -38,34 +38,92 @@ export const figmaTokenStoreFor = (deps) => {
     return createFigmaTokenStore({ key, storePath: tokenVaultPath(deps.evidenceDir) });
 };
 // Count deterministic a11y findings (#812) on the cleaned IR — the metric the #760 audit surfaces.
-// Coverage-notice items are excluded: they record what could NOT be checked, not a finding.
+// Passing checks, generic expectations, and coverage notices are excluded: they record test cases or
+// unverified coverage, not confirmed a11y findings.
 const a11yFindingsCount = (ir) => {
     let count = 0;
     for (const items of QualityIntelligenceFigma.deriveA11yTestItemsByScreen(ir.screens).values()) {
         for (const item of items)
-            if (item.category === "a11y")
+            if (item.category === "a11y" && item.outcome === "fail")
                 count += 1;
     }
     return count;
 };
+const hasSuccessfulConnectAudit = (scopeRef, evidenceDir) => loadFigmaConnectorAudit(scopeRef, evidenceDir)?.auditLog.some((entry) => entry.action === "connect" && entry.outcome === "ok") === true;
 // Record (when acknowledged) and assert read-only-scope consent BEFORE any token materialisation or
 // egress — an unconsented scope never reaches Figma (#760). Throws FIGMA_CONSENT_REQUIRED if missing.
 const gateConsent = (deps, scopeRef) => {
     if (deps.acknowledgeReadOnly === true) {
+        // The first acknowledgement IS the operator's "connect" gesture. Guard on the audit ledger, not
+        // only on consent existence: if consent was written but the audit append failed, an acknowledged
+        // retry must repair the missing connect marker rather than suppressing it forever.
+        const needsConnectAudit = !hasSuccessfulConnectAudit(scopeRef, deps.evidenceDir);
         recordReadOnlyConsent({
             scopeRef,
             evidenceDir: deps.evidenceDir,
             acknowledgedBy: "operator",
             now: deps.now,
         });
+        if (needsConnectAudit) {
+            appendFigmaConnectorAudit({
+                scopeRef,
+                evidenceDir: deps.evidenceDir,
+                action: "connect",
+                outcome: "ok",
+                now: deps.now,
+            });
+        }
     }
     assertReadOnlyConsent(scopeRef, deps.evidenceDir);
 };
+function snapshotPorts(deps) {
+    return {
+        httpPort: deps.httpPort ?? createDefaultFigmaHttpPort(deps.egress, undefined, deps.portOptions),
+        renderPort: deps.renderPort ?? createDefaultFigmaRenderPort(deps.egress, undefined, deps.portOptions),
+    };
+}
+function resolveBuildToken(deps, vaultToken) {
+    return resolveFigmaToken({
+        vaultToken,
+        configToken: deps.configToken,
+        envToken: deps.env.FIGMA_ACCESS_TOKEN,
+    });
+}
+function createGovernedConnector(deps, httpPort, vaultToken) {
+    return createFigmaConnector({
+        http: httpPort,
+        env: deps.env,
+        ...(vaultToken !== undefined ? { vaultToken } : {}),
+        config: {
+            ...(deps.configToken !== undefined ? { accessToken: deps.configToken } : {}),
+            pagination: deps.pagination ?? {},
+        },
+    });
+}
+function auditedResolveBuildToken(deps, vaultToken, scopeRef, action) {
+    try {
+        return resolveBuildToken(deps, vaultToken);
+    }
+    catch (error) {
+        appendFigmaConnectorAudit({
+            scopeRef,
+            evidenceDir: deps.evidenceDir,
+            action,
+            outcome: "error",
+            errorCode: error instanceof FigmaConnectorError ? error.code : "FIGMA_INTERNAL",
+            now: deps.now,
+        });
+        throw error;
+    }
+}
 // Deep scoped fetch with audit-on-failure: a fetch failure is recorded as a coded audit entry before
 // it propagates, so the audit ledger captures the action even when the egress never produced a build.
 const auditedDeepFetch = async (connector, boardLink, deps, scopeRef, action) => {
     try {
-        return await connector.fetchScopedNodesDeep(boardLink, { fetchedAt: deps.now });
+        return await connector.fetchScopedNodesDeep(boardLink, {
+            fetchedAt: deps.now,
+            ...(deps.version !== undefined ? { version: deps.version } : {}),
+        });
     }
     catch (error) {
         appendFigmaConnectorAudit({
@@ -79,6 +137,19 @@ const auditedDeepFetch = async (connector, boardLink, deps, scopeRef, action) =>
         throw error;
     }
 };
+const assertReadyForSnapshot = (scoped, deps, scopeRef, action) => {
+    if (scoped.readiness.ready)
+        return;
+    appendFigmaConnectorAudit({
+        scopeRef,
+        evidenceDir: deps.evidenceDir,
+        action,
+        outcome: "error",
+        errorCode: "FIGMA_NOT_READY",
+        now: deps.now,
+    });
+    throw new FigmaConnectorError("FIGMA_NOT_READY");
+};
 /**
  * Run the governed snapshot-build for `boardLink`: resolve the vault>config>env PAT, gate on recorded
  * read-only consent BEFORE any Figma egress, perform the deep scoped-pagination fetch + render, and
@@ -91,21 +162,17 @@ export const governedSnapshotBuild = async (boardLink, deps, isResnapshot = fals
     if (target === null)
         throw new FigmaConnectorError("FIGMA_MALFORMED_URL");
     const scopeRef = deriveFigmaScopeRef(target.fileKey, target.nodeId);
-    const httpPort = deps.httpPort ?? createDefaultFigmaHttpPort(deps.egress, undefined, deps.portOptions);
-    const renderPort = deps.renderPort ?? createDefaultFigmaRenderPort(deps.egress, undefined, deps.portOptions);
-    const vaultToken = readFigmaVaultToken(deps);
+    const { httpPort, renderPort } = snapshotPorts(deps);
+    const action = isResnapshot ? "resnapshot" : "snapshot";
     gateConsent(deps, scopeRef);
+    const vaultToken = readFigmaVaultToken(deps);
     // Render-token (vault > config > env). Throws FIGMA_TOKEN_MISSING when nothing is configured.
-    const token = resolveFigmaToken({ vaultToken, envToken: deps.env.FIGMA_ACCESS_TOKEN });
-    const connector = createFigmaConnector({
-        http: httpPort,
-        env: deps.env,
-        ...(vaultToken !== undefined ? { vaultToken } : {}),
-        config: { pagination: deps.pagination ?? {} },
-    });
-    const action = isResnapshot ? "resnapshot" : "snapshot";
+    const token = auditedResolveBuildToken(deps, vaultToken, scopeRef, action);
+    const connector = createGovernedConnector(deps, httpPort, vaultToken);
     const scoped = await auditedDeepFetch(connector, boardLink, deps, scopeRef, action);
+    assertReadyForSnapshot(scoped, deps, scopeRef, action);
     const ir = QualityIntelligenceFigma.cleanScopedNodesToScreenIr(scoped.nodes);
+    const renderLimits = resolveScopedPaginationLimits(deps.pagination);
     const observed = await observeFigmaSnapshot({
         ctx: { evidenceDir: deps.evidenceDir, now: deps.now },
         provenance: scoped.provenance,
@@ -115,12 +182,14 @@ export const governedSnapshotBuild = async (boardLink, deps, isResnapshot = fals
         augmentation: { deterministic: 0, modelAugmented: 0 },
         extras: { a11yFindings: a11yFindingsCount(ir) },
         isResnapshot,
+        auditSuccess: deps.deferSuccessAudit !== true,
         run: () => buildFigmaSnapshot({
             ir,
             provenance: scoped.provenance,
             token,
             imagesPort: httpPort,
             renderPort,
+            maxScreensRendered: renderLimits.maxScreensDeep,
         }),
     });
     return {

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

@@ -1,6 +1,7 @@
-import type { RouteContext, RouteResult } from "../routes.js";
+import { type HandlerOutcome, type RouteContext, type RouteResult } from "../routes.js";
 import { type UiHandlerDeps } from "../deps.js";
-import { type FigmaConnectorMetrics, type FigmaScopeCoverage } from "./figma/index.js";
+import type { EnvSource } from "@oscharko-dev/keiko-security";
+import { type FigmaConnectorMetrics, type FigmaScopeCoverage, type ScopedPaginationLimits } from "./figma/index.js";
 export interface FigmaSnapshotSummary {
     readonly runId: string;
     readonly fileKey: string;
@@ -25,16 +26,15 @@ export interface FigmaSnapshotSummary {
      */
     readonly coverage?: FigmaScopeCoverage;
     /**
-     * Operational metrics (#760) — present on a freshly-built snapshot (POST response): reduction
+     * Operational metrics (#760) — present on POST and reloaded GET summaries: reduction
      * ratio, screen/render counts, design-token count, navigation-graph size (screens + transitions),
      * a11y-finding count, and the deterministic-vs-model augmentation share. All NUMBERS — never any
-     * board content, screen name, token, or board id. Build-time only; not persisted in the snapshot.
+     * board content, screen name, token, or board id.
      */
     readonly metrics?: FigmaConnectorMetrics;
     /**
-     * Per-screen summary for the UI gallery. IR display names + image metadata only.
-     * PNG bytes are NOT returned — the client shows a placeholder pending a future
-     * screen-image route (/{runId}/screens/:index).
+     * Per-screen summary for the UI gallery. IR display names + image metadata only. The client loads
+     * the token-free PNG side-file through /api/figma/snapshots/:runId/screens/:screenIndex/image.
      */
     readonly screens: readonly FigmaScreenSummary[];
 }
@@ -51,6 +51,7 @@ export interface FigmaScreenSummary {
     /** Byte size of the rendered PNG. */
     readonly imageByteLength: number;
 }
+export declare function figmaPaginationFromEnv(env: EnvSource): ScopedPaginationLimits;
 interface CoalescedBuildEntry {
     readonly promise: Promise<RouteResult>;
 }
@@ -61,5 +62,6 @@ export declare function resetInFlightMap(): void;
 export declare function handleFigmaTriggerSnapshot(ctx: RouteContext, deps: UiHandlerDeps, inFlight?: Map<string, CoalescedBuildEntry>): Promise<RouteResult>;
 export declare function handleFigmaRevokeToken(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
 export declare function handleFigmaLoadSnapshot(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handleFigmaLoadSnapshotImage(ctx: RouteContext, deps: UiHandlerDeps): HandlerOutcome;
 export {};
 //# sourceMappingURL=figmaSnapshotRoutes.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"figmaSnapshotRoutes.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/figmaSnapshotRoutes.ts"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAA8B,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EAOL,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EAExB,MAAM,kBAAkB,CAAC;AAoI1B,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2FAA2F;IAC3F,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wFAAwF;IACxF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAgOD,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;CACxC;AAMD,sEAAsE;AACtE,wBAAgB,eAAe,IAAI,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAElE;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAmED,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,EACnB,QAAQ,GAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAsB,GAC9D,OAAO,CAAC,WAAW,CAAC,CAqCtB;AAID,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CA4B1F;AAID,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CAwB3F"}
+{"version":3,"file":"figmaSnapshotRoutes.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/figmaSnapshotRoutes.ts"],"names":[],"mappings":"AAgDA,OAAO,EAAa,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AACnG,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EASL,KAAK,qBAAqB,EAE1B,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AA2I1B,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2FAA2F;IAC3F,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wFAAwF;IACxF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AA+MD,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,SAAS,GAAG,sBAAsB,CAiB7E;AA8GD,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;CACxC;AAMD,sEAAsE;AACtE,wBAAgB,eAAe,IAAI,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAElE;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AA6FD,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,EACnB,QAAQ,GAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAsB,GAC9D,OAAO,CAAC,WAAW,CAAC,CAiDtB;AAID,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CA4B1F;AAID,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CAwB3F;AAiCD,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,cAAc,CAgChB"}