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

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

@@ -7,7 +7,8 @@
 //   2. downloads the PNG bytes from that ephemeral url via the injectable render port (no auth
 //      header — the url is pre-signed);
 //   3. assembles the immutable Snapshot value: per-screen IR + image + deterministic integrity
-//      hashes + provenance, with a `skippedScreens` list for any screen that failed to render.
+//      hashes + provenance, with a `skippedScreens` list plus structural-only IR rows for any
+//      screen that failed to render.
 //
 // Once this returns, the Snapshot is the communication boundary: nothing downstream contacts
 // Figma. The token flows ONLY into the images-call header; it never reaches the snapshot value,
@@ -16,7 +17,7 @@ import { FigmaConnectorError } from "./figmaConnectorErrors.js";
 import { mapWithConcurrency } from "./figmaConcurrency.js";
 import { classifyTokenFailure } from "./figmaTokenSource.js";
 import { DEFAULT_FIGMA_RETRY_POLICY, fetchWithBackoff, realFigmaRetrySleep, } from "./figmaRetry.js";
-import { hashBytes, hashScreen, hashSnapshot } from "./figmaSnapshotHash.js";
+import { hashBytes, hashScreen, hashSnapshot, hashStructuralScreen } from "./figmaSnapshotHash.js";
 import { DEFAULT_SCOPED_PAGINATION_LIMITS, SCOPED_PAGINATION_LIMIT_CEILINGS, } from "./figmaScopedPagination.js";
 const FIGMA_API_ORIGIN = "https://api.figma.com";
 const SNAPSHOT_SCHEMA_VERSION = 1;
@@ -130,15 +131,24 @@ const extractImageUrls = (json) => {
     }
     return out;
 };
+// Figma's render endpoint can reject a subset of otherwise readable screen node ids with a client
+// status (observed on large boards where some detected screen frames cannot be rendered). That is a
+// renderability problem, not an auth/egress/build integrity problem: keep the snapshot usable by
+// returning an empty render-url map for that batch so the affected screens become structural-only.
+// Auth/scope/proxy/rate-limit/upstream failures remain hard coded errors below.
+const isRenderEndpointSoftFailure = (status) => status === 400 || status === 404 || status === 422;
 // Resolve one `/v1/images` batch to its ephemeral-url map. The fetch is wrapped in the deterministic
-// 429 backoff; a non-2xx is a hard coded error (auth/scope/upstream); a 2xx with a malformed body is a
-// transient render-overload signal that is retried up to MAX_RENDER_BODY_RETRIES, then degrades to an
-// empty map so the affected screens skip (render-url-missing) instead of aborting the build (F8).
+// 429 backoff; auth/scope/upstream non-2xx responses are hard coded errors, while renderability
+// client failures degrade this batch to structural-only. A 2xx with a malformed body is a transient
+// render-overload signal that is retried up to MAX_RENDER_BODY_RETRIES, then degrades to an empty map
+// so the affected screens skip (render-url-missing) instead of aborting the build (F8).
 const resolveRenderBatch = async (input, batch, policy, sleep) => {
     const requestUrl = buildImagesUrl(input.provenance.fileKey, batch, input.provenance.version);
     for (let attempt = 0;; attempt += 1) {
         const response = await fetchWithBackoff(() => input.imagesPort({ url: requestUrl, headers: { "X-Figma-Token": input.token } }), policy, sleep);
         if (response.status < 200 || response.status >= 300) {
+            if (isRenderEndpointSoftFailure(response.status))
+                return {};
             throw statusToError(response.status, response.json);
         }
         const map = extractImageUrls(response.json);
@@ -164,8 +174,14 @@ const requestRenderUrls = async (input, screenIds) => {
     }
     return urls;
 };
-const skip = (screenId, reason) => ({
-    skipped: { screenId, reason },
+const structuralOnly = (ir, reason) => ({
+    skipped: { screenId: ir.id, reason },
+    structuralScreen: {
+        screenId: ir.id,
+        ir,
+        reason,
+        integrityHash: hashStructuralScreen(ir.id, ir),
+    },
 });
 // Classifies a finished render download into a skip reason, or null when the bytes are usable.
 const renderSkipReason = (response, maxBytes) => {
@@ -201,18 +217,18 @@ const classifyRenderError = (screenId, err) => {
     if (err instanceof FigmaConnectorError) {
         if (RENDER_EGRESS_ABORT_CODES.has(err.code))
             throw err;
-        return skip(screenId, `render-fetch-failed:${err.code}`);
+        return { skipped: { screenId, reason: `render-fetch-failed:${err.code}` } };
     }
-    return skip(screenId, "render-fetch-failed");
+    return { skipped: { screenId, reason: "render-fetch-failed" } };
 };
 // Downloads one screen's render bytes and classifies the result into a kept screen or a skip.
 // A single screen failing after retries degrades to a skip (partial render), never aborting.
 // Exception: hard egress errors (TLS/proxy misconfiguration) abort via classifyRenderError.
 const resolveScreen = async (input, ir, renderUrl) => {
     if (renderUrl === null)
-        return skip(ir.id, "render-url-missing");
+        return structuralOnly(ir, "render-url-missing");
     if (!isRenderUrlSafe(renderUrl))
-        return skip(ir.id, "render-url-blocked");
+        return structuralOnly(ir, "render-url-blocked");
     const maxBytes = input.maxImageBytes ?? DEFAULT_MAX_IMAGE_BYTES;
     const policy = input.retryPolicy ?? DEFAULT_FIGMA_RETRY_POLICY;
     const sleep = input.sleep ?? realFigmaRetrySleep;
@@ -221,11 +237,15 @@ const resolveScreen = async (input, ir, renderUrl) => {
         response = await fetchWithBackoff(() => input.renderPort({ url: renderUrl, headers: {} }), policy, sleep);
     }
     catch (err) {
-        return classifyRenderError(ir.id, err);
+        const classified = classifyRenderError(ir.id, err);
+        if (classified.skipped !== undefined) {
+            return structuralOnly(ir, classified.skipped.reason);
+        }
+        return classified;
     }
     const reason = renderSkipReason(response, maxBytes);
     if (reason !== null)
-        return skip(ir.id, reason);
+        return structuralOnly(ir, reason);
     const sha256 = hashBytes(response.bytes);
     const screen = {
         screenId: ir.id,
@@ -240,9 +260,31 @@ const resolveScreen = async (input, ir, renderUrl) => {
     };
     return { screen };
 };
+function collectSnapshotRows(outcomes, cappedScreens) {
+    const screens = [];
+    const skippedScreens = [];
+    const structuralScreens = [];
+    for (const outcome of outcomes) {
+        if (outcome.screen !== undefined)
+            screens.push(outcome.screen);
+        if (outcome.skipped !== undefined)
+            skippedScreens.push(outcome.skipped);
+        if (outcome.structuralScreen !== undefined)
+            structuralScreens.push(outcome.structuralScreen);
+    }
+    for (const ir of cappedScreens) {
+        const outcome = structuralOnly(ir, "render-screen-cap-exceeded");
+        if (outcome.skipped !== undefined)
+            skippedScreens.push(outcome.skipped);
+        if (outcome.structuralScreen !== undefined)
+            structuralScreens.push(outcome.structuralScreen);
+    }
+    return { screens, skippedScreens, structuralScreens };
+}
 /**
  * Render the screens and assemble the immutable Figma Snapshot. Render failures degrade to a
- * `skippedScreens` entry (partial render); a non-2xx `/v1/images` call is a hard coded error.
+ * `skippedScreens` entry plus structural-only IR (partial render); a non-2xx `/v1/images` call is
+ * a hard coded error.
  */
 export const buildFigmaSnapshot = async (input) => {
     const maxScreensRendered = boundedPositiveInt(input.maxScreensRendered, DEFAULT_SCOPED_PAGINATION_LIMITS.maxScreensDeep, SCOPED_PAGINATION_LIMIT_CEILINGS.maxScreensDeep);
@@ -254,25 +296,19 @@ export const buildFigmaSnapshot = async (input) => {
         : await requestRenderUrls(input, screenIds);
     const concurrency = boundedPositiveInt(input.downloadConcurrency, DEFAULT_DOWNLOAD_CONCURRENCY, Number.MAX_SAFE_INTEGER);
     const outcomes = await mapWithConcurrency(renderableScreens, concurrency, (ir) => resolveScreen(input, ir, renderUrls.get(ir.id) ?? null));
-    const screens = [];
-    const skippedScreens = [];
-    for (const outcome of outcomes) {
-        if (outcome.screen !== undefined)
-            screens.push(outcome.screen);
-        if (outcome.skipped !== undefined)
-            skippedScreens.push(outcome.skipped);
-    }
-    for (const ir of cappedScreens) {
-        skippedScreens.push({ screenId: ir.id, reason: "render-screen-cap-exceeded" });
-    }
+    const { screens, skippedScreens, structuralScreens } = collectSnapshotRows(outcomes, cappedScreens);
     return {
         snapshotSchemaVersion: SNAPSHOT_SCHEMA_VERSION,
         provenance: input.provenance,
         screens,
         skippedScreens,
+        structuralScreens,
         // Carried verbatim from the Screen-IR (#752) for the navigation/flow graph (#811). NOT folded
         // into the integrity hash below — `links` is non-identity metadata, so drift (#735) is stable.
         links: input.ir.links,
-        integrityHash: hashSnapshot(SNAPSHOT_SCHEMA_VERSION, input.provenance.version, screens),
+        integrityHash: hashSnapshot(SNAPSHOT_SCHEMA_VERSION, input.provenance.version, [
+            ...screens,
+            ...structuralScreens,
+        ]),
     };
 };

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

@@ -2,6 +2,8 @@ import type { QualityIntelligenceFigma } from "@oscharko-dev/keiko-quality-intel
 type ScreenIr = QualityIntelligenceFigma.ScreenIr;
 /** sha256 over the canonical per-screen identity: {screenId, ir, imageSha256}. */
 export declare const hashScreen: (screenId: string, ir: ScreenIr, imageSha256: string) => string;
+/** sha256 over a structural-only screen identity: {screenId, ir, structuralOnly:true}. */
+export declare const hashStructuralScreen: (screenId: string, ir: ScreenIr) => string;
 /**
  * sha256 over the canonical snapshot identity: schema version + pinned Figma version + the
  * per-screen hashes sorted by screenId. EXCLUDES `fetchedAt` so the hash is drift-stable across

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

@@ -1 +1 @@
-{"version":3,"file":"figmaSnapshotHash.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaSnapshotHash.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AAEzF,KAAK,QAAQ,GAAG,wBAAwB,CAAC,QAAQ,CAAC;AAwDlD,kFAAkF;AAClF,eAAO,MAAM,UAAU,GAAI,UAAU,MAAM,EAAE,IAAI,QAAQ,EAAE,aAAa,MAAM,KAAG,MACV,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACvB,uBAAuB,MAAM,EAC7B,SAAS,MAAM,GAAG,SAAS,EAC3B,WAAW,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EAAE,KAClF,MAKF,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,OAAO,UAAU,KAAG,MACI,CAAC"}
+{"version":3,"file":"figmaSnapshotHash.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaSnapshotHash.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AAEzF,KAAK,QAAQ,GAAG,wBAAwB,CAAC,QAAQ,CAAC;AAwDlD,kFAAkF;AAClF,eAAO,MAAM,UAAU,GAAI,UAAU,MAAM,EAAE,IAAI,QAAQ,EAAE,aAAa,MAAM,KAAG,MACV,CAAC;AAExE,0FAA0F;AAC1F,eAAO,MAAM,oBAAoB,GAAI,UAAU,MAAM,EAAE,IAAI,QAAQ,KAAG,MACU,CAAC;AAEjF;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACvB,uBAAuB,MAAM,EAC7B,SAAS,MAAM,GAAG,SAAS,EAC3B,WAAW,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EAAE,KAClF,MAKF,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,OAAO,UAAU,KAAG,MACI,CAAC"}

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

@@ -3,9 +3,10 @@
 // The hash is the drift identity: same unchanged design ⇒ byte-identical hash, regardless of when
 // it was fetched. We therefore canonicalise to a stable key order and EXCLUDE the wall-clock
 // `fetchedAt`. The snapshot identity is the pinned Figma `version` + the sorted per-screen
-// identities (each = screenId + structural IR + image content sha256). `version` and the IR are
-// deterministic outputs of #751/#752; the image sha is included so an unexpected render-byte change
-// surfaces as drift too.
+// identities (each = screenId + structural IR + image content sha256, or a structural-only marker
+// for screens whose PNG render was deliberately skipped/could not be fetched). `version` and the IR
+// are deterministic outputs of #751/#752; the image sha is included so an unexpected render-byte
+// change surfaces as drift too, while structural-only screens still participate in drift detection.
 import { createHash } from "node:crypto";
 const sha256Hex = (input) => createHash("sha256").update(input, "utf8").digest("hex");
 // Stable stringify: object keys are emitted in sorted order at every depth so the serialisation is
@@ -46,6 +47,8 @@ const hashStableIr = (ir) => ({
 });
 /** sha256 over the canonical per-screen identity: {screenId, ir, imageSha256}. */
 export const hashScreen = (screenId, ir, imageSha256) => sha256Hex(canonical({ imageSha256, ir: hashStableIr(ir), screenId }));
+/** sha256 over a structural-only screen identity: {screenId, ir, structuralOnly:true}. */
+export const hashStructuralScreen = (screenId, ir) => sha256Hex(canonical({ ir: hashStableIr(ir), screenId, structuralOnly: true }));
 /**
  * sha256 over the canonical snapshot identity: schema version + pinned Figma version + the
  * per-screen hashes sorted by screenId. EXCLUDES `fetchedAt` so the hash is drift-stable across

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

@@ -16,6 +16,14 @@ export interface FigmaSnapshotScreen {
     /** sha256 over the canonical {screenId, ir, imageSha256} body — the per-screen drift identity. */
     readonly integrityHash: string;
 }
+/** One screen whose structural IR is captured but no PNG side-file exists. */
+export interface FigmaSnapshotStructuralScreen {
+    readonly screenId: string;
+    readonly ir: ScreenIr;
+    readonly reason: FigmaSkippedScreenReason;
+    /** sha256 over the canonical {screenId, ir, structuralOnly:true} body. */
+    readonly integrityHash: string;
+}
 /** Why a detected screen produced no render and was excluded from `screens` (partial-render).
  * The `render-fetch-failed` member also appears as `render-fetch-failed:<CODE>` when the fetch
  * threw a FigmaConnectorError — the code suffix lets metrics distinguish an egress
@@ -37,6 +45,12 @@ export interface FigmaSnapshot {
     readonly provenance: FigmaProvenance;
     readonly screens: readonly FigmaSnapshotScreen[];
     readonly skippedScreens: readonly FigmaSkippedScreen[];
+    /**
+     * Structural IR for screens that did not produce a PNG render. This keeps QI/code consumers from
+     * losing JSON evidence when render fan-out is capped or a single render fetch degrades. Optional
+     * for older snapshots/builders; new builds emit it for every skipped screen that has IR.
+     */
+    readonly structuralScreens?: readonly FigmaSnapshotStructuralScreen[];
     /**
      * Raw inter-screen transitions carried from the Screen-IR (#752) for the navigation/flow graph
      * (#811). OPTIONAL and additive — a constructor that omits it (e.g. an older builder or a test

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

@@ -1 +1 @@
-{"version":3,"file":"figmaSnapshotTypes.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaSnapshotTypes.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,KAAK,QAAQ,GAAG,wBAAwB,CAAC,QAAQ,CAAC;AAElD,+FAA+F;AAC/F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,kGAAkG;IAClG,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAChC,oBAAoB,GACpB,oBAAoB,GACpB,4BAA4B,GAC5B,qBAAqB,GACrB,uBAAuB,MAAM,EAAE,GAC/B,cAAc,GACd,kBAAkB,CAAC;AAEvB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;CAC3C;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,QAAQ,CAAC,cAAc,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACvD;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,wBAAwB,CAAC,eAAe,EAAE,CAAC;IACrE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC"}
+{"version":3,"file":"figmaSnapshotTypes.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaSnapshotTypes.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,KAAK,QAAQ,GAAG,wBAAwB,CAAC,QAAQ,CAAC;AAElD,+FAA+F;AAC/F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,kGAAkG;IAClG,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,8EAA8E;AAC9E,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAChC,oBAAoB,GACpB,oBAAoB,GACpB,4BAA4B,GAC5B,qBAAqB,GACrB,uBAAuB,MAAM,EAAE,GAC/B,cAAc,GACd,kBAAkB,CAAC;AAEvB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;CAC3C;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,QAAQ,CAAC,cAAc,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACvD;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,6BAA6B,EAAE,CAAC;IACtE;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,wBAAwB,CAAC,eAAe,EAAE,CAAC;IACrE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC"}

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

@@ -17,6 +17,8 @@ export interface FigmaSnapshotSummary {
      * "3 screens from 1 section (2 skipped)".
      */
     readonly reductionHint: string;
+    /** Skipped/non-rendered screens that still carry persisted structural Screen-IR JSON. */
+    readonly structuralOnlyCount: number;
     /** Integrity hash over the snapshot content — deterministic for drift detection (#735). */
     readonly integrityHash: string;
     /**
@@ -37,6 +39,11 @@ export interface FigmaSnapshotSummary {
      * the token-free PNG side-file through /api/figma/snapshots/:runId/screens/:screenIndex/image.
      */
     readonly screens: readonly FigmaScreenSummary[];
+    /**
+     * Screen-IR summaries for detected screens that have JSON evidence but no rendered PNG side-file.
+     * These are selectable as QI sources, but the browser cannot request an image for them.
+     */
+    readonly structuralScreens: readonly FigmaStructuralScreenSummary[];
 }
 export interface FigmaScreenSummary {
     readonly screenId: string;
@@ -51,6 +58,30 @@ export interface FigmaScreenSummary {
     /** Byte size of the rendered PNG. */
     readonly imageByteLength: number;
 }
+export interface FigmaStructuralScreenSummary {
+    readonly screenId: string;
+    /** Display name derived from the IR (ir.name). */
+    readonly name: string;
+    /** A brief structural description (field count, control count) for the gallery card. */
+    readonly irSummary: string;
+    /** Why no rendered PNG side-file exists for this screen. */
+    readonly reason: string;
+}
+export interface FigmaSnapshotListEntry {
+    readonly runId: string;
+    readonly fileKey: string;
+    readonly nodeId: string;
+    readonly version: string | undefined;
+    readonly fetchedAt: string;
+    readonly screenCount: number;
+    readonly skippedCount: number;
+    readonly structuralOnlyCount: number;
+    readonly reductionHint: string;
+    readonly integrityHash: string;
+}
+export interface FigmaSnapshotListResponse {
+    readonly snapshots: readonly FigmaSnapshotListEntry[];
+}
 export declare function figmaPaginationFromEnv(env: EnvSource): ScopedPaginationLimits;
 interface CoalescedBuildEntry {
     readonly promise: Promise<RouteResult>;
@@ -61,7 +92,9 @@ export declare function makeInFlightMap(): Map<string, CoalescedBuildEntry>;
 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 handleFigmaListSnapshots(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
 export declare function handleFigmaLoadSnapshot(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handleFigmaInspectSnapshotScreenJson(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":"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"}
+{"version":3,"file":"figmaSnapshotRoutes.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/figmaSnapshotRoutes.ts"],"names":[],"mappings":"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"}

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

@@ -44,6 +44,8 @@
 //   The coalesced build continues — other waiters (if any) are unaffected and will
 //   receive the result when the build settles.
 import { randomUUID } from "node:crypto";
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { STREAMING } from "../routes.js";
 import { currentGatewayConfig, currentGatewayEgressConfig, currentRedactionSecrets, } from "../deps.js";
 import { redact } from "@oscharko-dev/keiko-security";
@@ -155,12 +157,19 @@ function readBody(req) {
         req.on("error", reject);
     });
 }
-function buildReductionHint(screenCount, skippedCount) {
+function buildReductionHint(screenCount, skippedCount, structuralOnlyCount = 0) {
     const total = screenCount + skippedCount;
-    const skippedClause = skippedCount > 0
-        ? ` (${skippedCount.toString()} render${skippedCount !== 1 ? "s" : ""} skipped)`
+    if (skippedCount === 0) {
+        return `${screenCount.toString()} screen${screenCount !== 1 ? "s" : ""} from ${total.toString()} detected`;
+    }
+    const structuralClause = structuralOnlyCount > 0
+        ? `${structuralOnlyCount.toString()} structural-only`
+        : `${skippedCount.toString()} render${skippedCount !== 1 ? "s" : ""} skipped`;
+    const missingIrCount = Math.max(0, skippedCount - structuralOnlyCount);
+    const missingClause = structuralOnlyCount > 0 && missingIrCount > 0
+        ? `; ${missingIrCount.toString()} without structural IR`
         : "";
-    return `${screenCount.toString()} screen${screenCount !== 1 ? "s" : ""} from ${total.toString()} detected${skippedClause}`;
+    return `${screenCount.toString()} rendered screen${screenCount !== 1 ? "s" : ""} from ${total.toString()} detected (${structuralClause}${missingClause})`;
 }
 // Counts interaction-hint roles over a stored ScreenIr node tree (`{ root: { interactionHint,
 // children } }`). Duck-typed: it does NOT import the IR domain, only walks the serialised shape the
@@ -212,6 +221,7 @@ function screenNameFromIrJson(irJson) {
 function recordToSummary(record, coverage, metrics) {
     const screenCount = record.screens.length;
     const skippedCount = record.skippedScreens.length;
+    const structuralOnlyCount = record.structuralScreens?.length ?? 0;
     const truncatedClause = coverage !== undefined && (coverage.screensTruncated > 0 || coverage.capped)
         ? `; ${coverage.screensTruncated.toString()} partially captured (deep content bounded)`
         : "";
@@ -223,7 +233,8 @@ function recordToSummary(record, coverage, metrics) {
         fetchedAt: record.provenance.fetchedAt,
         screenCount,
         skippedCount,
-        reductionHint: `${buildReductionHint(screenCount, skippedCount)}${truncatedClause}`,
+        structuralOnlyCount,
+        reductionHint: `${buildReductionHint(screenCount, skippedCount, structuralOnlyCount)}${truncatedClause}`,
         integrityHash: record.integrityHash,
         ...(coverage !== undefined ? { coverage } : {}),
         ...(metrics !== undefined ? { metrics } : {}),
@@ -235,6 +246,126 @@ function recordToSummary(record, coverage, metrics) {
             imageSha256: s.image.sha256,
             imageByteLength: s.image.byteLength,
         })),
+        structuralScreens: (record.structuralScreens ?? []).map((s) => ({
+            screenId: s.screenId,
+            name: screenNameFromIrJson(s.irJson),
+            irSummary: irSummaryFromJson(s.irJson),
+            reason: s.reason,
+        })),
+    };
+}
+function decodeRouteParam(raw) {
+    if (raw === undefined || raw.length === 0)
+        return "";
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        return "";
+    }
+}
+function collectIrIds(value, out = new Set()) {
+    if (typeof value !== "object" || value === null)
+        return out;
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            collectIrIds(entry, out);
+        return out;
+    }
+    const record = value;
+    if (typeof record.id === "string" && record.id.length > 0)
+        out.add(record.id);
+    for (const entry of Object.values(record))
+        collectIrIds(entry, out);
+    return out;
+}
+function relatedLinksForScreen(irJson, links) {
+    if (links === undefined || links.length === 0)
+        return [];
+    const ids = collectIrIds(irJson);
+    return links.filter((link) => ids.has(link.sourceNodeId) || ids.has(link.targetNodeId));
+}
+function screenJsonSnapshot(record) {
+    return {
+        screenCount: record.screens.length,
+        skippedCount: record.skippedScreens.length,
+        structuralOnlyCount: record.structuralScreens?.length ?? 0,
+        integrityHash: record.integrityHash,
+        redactionSummary: record.redactionSummary,
+        ...(record.metrics !== undefined ? { metrics: record.metrics } : {}),
+        ...(record.tokens !== undefined ? { tokens: record.tokens } : {}),
+    };
+}
+function renderedScreenJsonResponse(record, rendered) {
+    return {
+        runId: record.runId,
+        fileKey: record.provenance.fileKey,
+        nodeId: record.provenance.nodeId,
+        version: record.provenance.version,
+        fetchedAt: record.provenance.fetchedAt,
+        source: {
+            kind: "figma-snapshot",
+            snapshotRunId: record.runId,
+            screenIds: [rendered.screenId],
+        },
+        snapshot: screenJsonSnapshot(record),
+        screen: {
+            kind: "rendered",
+            screenId: rendered.screenId,
+            name: screenNameFromIrJson(rendered.irJson),
+            irSummary: irSummaryFromJson(rendered.irJson),
+            integrityHash: rendered.integrityHash,
+            irJson: rendered.irJson,
+            image: rendered.image,
+        },
+        relatedLinks: relatedLinksForScreen(rendered.irJson, record.links),
+    };
+}
+function structuralScreenJsonResponse(record, structural) {
+    return {
+        runId: record.runId,
+        fileKey: record.provenance.fileKey,
+        nodeId: record.provenance.nodeId,
+        version: record.provenance.version,
+        fetchedAt: record.provenance.fetchedAt,
+        source: {
+            kind: "figma-snapshot",
+            snapshotRunId: record.runId,
+            screenIds: [structural.screenId],
+        },
+        snapshot: screenJsonSnapshot(record),
+        screen: {
+            kind: "structural",
+            screenId: structural.screenId,
+            name: screenNameFromIrJson(structural.irJson),
+            irSummary: irSummaryFromJson(structural.irJson),
+            integrityHash: structural.integrityHash,
+            irJson: structural.irJson,
+            structuralReason: structural.reason,
+        },
+        relatedLinks: relatedLinksForScreen(structural.irJson, record.links),
+    };
+}
+function screenJsonResponse(record, screenId) {
+    const rendered = record.screens.find((screen) => screen.screenId === screenId);
+    if (rendered !== undefined)
+        return renderedScreenJsonResponse(record, rendered);
+    const structural = record.structuralScreens?.find((screen) => screen.screenId === screenId);
+    return structural === undefined ? undefined : structuralScreenJsonResponse(record, structural);
+}
+function recordToListEntry(record) {
+    const structuralOnlyCount = record.structuralScreens?.length ?? 0;
+    return {
+        runId: record.runId,
+        fileKey: record.provenance.fileKey,
+        nodeId: record.provenance.nodeId,
+        version: record.provenance.version,
+        fetchedAt: record.provenance.fetchedAt,
+        screenCount: record.screens.length,
+        skippedCount: record.skippedScreens.length,
+        structuralOnlyCount,
+        reductionHint: buildReductionHint(record.screens.length, record.skippedScreens.length, structuralOnlyCount),
+        integrityHash: record.integrityHash,
     };
 }
 function persistedAuditCounts(record, metrics) {
@@ -410,6 +541,16 @@ function persistSnapshot(evidenceDir, runId, result, deps) {
                 integrityHash: s.integrityHash,
                 image: { mimeType: "image/png", bytes: s.image.bytes },
             })),
+            ...(result.snapshot.structuralScreens !== undefined
+                ? {
+                    structuralScreens: result.snapshot.structuralScreens.map((s) => ({
+                        screenId: s.screenId,
+                        reason: s.reason,
+                        irJson: s.ir,
+                        integrityHash: s.integrityHash,
+                    })),
+                }
+                : {}),
             skippedScreens: result.snapshot.skippedScreens.map((ss) => ({
                 screenId: ss.screenId,
                 reason: ss.reason,
@@ -583,6 +724,96 @@ export function handleFigmaRevokeToken(ctx, deps) {
         },
     };
 }
+// ─── GET /api/figma/snapshots — list stored snapshots for dashboard/history ────────────────
+const DEFAULT_FIGMA_SNAPSHOT_LIST_LIMIT = 12;
+const MAX_FIGMA_SNAPSHOT_LIST_LIMIT = 50;
+const FIGMA_SNAPSHOT_RECORD_SUFFIX = ".figma-snapshot.json";
+const FIGMA_EVIDENCE_SUBDIR = "qi";
+function parseSnapshotListLimit(url) {
+    const raw = url.searchParams.get("limit");
+    if (raw === null || raw.length === 0)
+        return DEFAULT_FIGMA_SNAPSHOT_LIST_LIMIT;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0)
+        return DEFAULT_FIGMA_SNAPSHOT_LIST_LIMIT;
+    return Math.min(parsed, MAX_FIGMA_SNAPSHOT_LIST_LIMIT);
+}
+function parseSnapshotListScope(url) {
+    const fileKey = (url.searchParams.get("fileKey") ?? "").trim();
+    const nodeId = (url.searchParams.get("nodeId") ?? "").trim();
+    return fileKey.length > 0 && nodeId.length > 0 ? { fileKey, nodeId } : undefined;
+}
+function loadSnapshotListEntries(store, runIds) {
+    const entries = [];
+    for (const runId of runIds) {
+        let record;
+        try {
+            record = store.loadMetadata(runId);
+        }
+        catch {
+            continue;
+        }
+        if (record !== undefined)
+            entries.push(recordToListEntry(record));
+    }
+    return entries;
+}
+function readSnapshotFetchedAt(qiDir, fileName) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(qiDir, fileName), "utf8"));
+        const provenance = typeof parsed.provenance === "object" && parsed.provenance !== null
+            ? parsed.provenance
+            : undefined;
+        const fetchedAt = provenance?.fetchedAt;
+        return typeof fetchedAt === "string" && fetchedAt.length > 0 ? fetchedAt : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function listRecentSnapshotRunIds(evidenceDir, limit) {
+    const qiDir = join(evidenceDir, FIGMA_EVIDENCE_SUBDIR);
+    const stat = lstatSync(qiDir, { throwIfNoEntry: false });
+    if (stat?.isDirectory() !== true)
+        return [];
+    const records = [];
+    for (const entry of readdirSync(qiDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith(FIGMA_SNAPSHOT_RECORD_SUFFIX))
+            continue;
+        const runId = entry.name.slice(0, -FIGMA_SNAPSHOT_RECORD_SUFFIX.length);
+        const fetchedAt = readSnapshotFetchedAt(qiDir, entry.name);
+        if (fetchedAt !== undefined)
+            records.push({ runId, fetchedAt });
+    }
+    records.sort((a, b) => (a.fetchedAt > b.fetchedAt ? -1 : a.fetchedAt < b.fetchedAt ? 1 : 0));
+    return records.slice(0, limit).map((record) => record.runId);
+}
+export function handleFigmaListSnapshots(ctx, deps) {
+    const evidenceDir = deps.evidenceDir;
+    if (evidenceDir === undefined || evidenceDir.length === 0) {
+        return { status: 503, body: figmaErrorBody("FIGMA_NO_EVIDENCE_DIR") };
+    }
+    const limit = parseSnapshotListLimit(ctx.url);
+    const scope = parseSnapshotListScope(ctx.url);
+    const store = createNodeFigmaSnapshotStore(evidenceDir);
+    try {
+        if (scope !== undefined) {
+            const snapshots = store
+                .listByScope(scope.fileKey, scope.nodeId)
+                .slice(0, limit)
+                .flatMap((entry) => {
+                const record = store.loadMetadata(entry.runId);
+                return record === undefined ? [] : [recordToListEntry(record)];
+            });
+            return { status: 200, body: { snapshots } };
+        }
+        const snapshots = loadSnapshotListEntries(store, listRecentSnapshotRunIds(evidenceDir, limit));
+        return { status: 200, body: { snapshots } };
+    }
+    catch {
+        return { status: 500, body: figmaErrorBody("FIGMA_INTERNAL") };
+    }
+}
 // ─── GET /api/figma/snapshots/:runId ──────────────────────────────────────────
 export function handleFigmaLoadSnapshot(ctx, deps) {
     const evidenceDir = deps.evidenceDir;
@@ -606,6 +837,33 @@ export function handleFigmaLoadSnapshot(ctx, deps) {
     }
     return { status: 200, body: recordToSummary(record, undefined, record.metrics) };
 }
+// ─── GET /api/figma/snapshots/:runId/screens/:screenId/json ───────────────────
+export function handleFigmaInspectSnapshotScreenJson(ctx, deps) {
+    const evidenceDir = deps.evidenceDir;
+    if (evidenceDir === undefined || evidenceDir.length === 0) {
+        return { status: 503, body: figmaErrorBody("FIGMA_NO_EVIDENCE_DIR") };
+    }
+    const runId = decodeRouteParam(ctx.params.runId);
+    const screenId = decodeRouteParam(ctx.params.screenId);
+    if (runId.length === 0 || screenId.length === 0) {
+        return { status: 404, body: figmaErrorBody("FIGMA_SCREEN_NOT_FOUND") };
+    }
+    const store = createNodeFigmaSnapshotStore(evidenceDir);
+    let record;
+    try {
+        record = store.loadMetadata(runId);
+    }
+    catch {
+        return { status: 500, body: figmaErrorBody("FIGMA_INTERNAL") };
+    }
+    if (record === undefined) {
+        return { status: 404, body: figmaErrorBody("FIGMA_SNAPSHOT_NOT_FOUND") };
+    }
+    const body = screenJsonResponse(record, screenId);
+    return body === undefined
+        ? { status: 404, body: figmaErrorBody("FIGMA_SCREEN_NOT_FOUND") }
+        : { status: 200, body };
+}
 // ─── GET /api/figma/snapshots/:runId/screens/:screenIndex/image ──────────────
 function parseScreenIndex(raw) {
     if (raw === undefined || raw.length === 0)