@oscharko-dev/keiko-server 0.2.0

package/dist/qualityIntelligence/figma/figmaHttpPort.js

@@ -0,0 +1,70 @@
+// Figma HTTP seam (Epic #750, Issue #751).
+//
+// The core connector NEVER calls `fetch`/undici directly. It depends only on this small
+// injectable port so unit tests can mock the transport and a future proxy-aware /
+// custom-CA client (#802) can be slotted in without touching connector logic.
+//
+// The request type intentionally carries the outbound headers (including the
+// `X-Figma-Token` auth header). The token is materialised into that header ONLY by the
+// default adapter below, immediately before the platform `fetch` call — it is never
+// logged here and never re-emitted by the port.
+//
+// redirect: "manual" is set so the PAT auth header can never silently follow a
+// cross-origin redirect. A 3xx response surfaces as a non-2xx status; the connector
+// layer treats any non-2xx as an upstream error.
+import { classifyFigmaTransportError, FigmaConnectorError } from "./figmaConnectorErrors.js";
+import { gatewayFetch, readJsonCapped, } from "@oscharko-dev/keiko-model-gateway/internal/http";
+/** Default request timeout in milliseconds for Figma HTTP API calls. */
+const DEFAULT_TIMEOUT_MS = 60_000;
+/** Default maximum JSON response body size (10 MiB). */
+const DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+// Collects the response headers into a plain lower-cased map. `Headers` already lower-cases
+// names, so this is a faithful, allocation-bounded copy with no token (request-only header).
+const collectHeaders = (response) => {
+    const out = {};
+    response.headers.forEach((value, name) => {
+        out[name] = value;
+    });
+    return out;
+};
+/**
+ * Thin default adapter over the platform `fetch`. This is the ONLY place `fetch` is named.
+ * It forwards the caller-built headers verbatim and reads the body as JSON with an explicit
+ * byte cap; it does not log, retry, or inspect the token. Resilience/backoff is out of scope
+ * here (#759); the proxy/custom-CA transport is the platform prerequisite (#802) that replaces
+ * this adapter.
+ *
+ * `redirect: "manual"` prevents the PAT auth header from following a cross-origin redirect.
+ * A 3xx response surfaces as a non-2xx port result; the connector treats non-2xx as upstream error.
+ */
+export const createDefaultFigmaHttpPort = (egress, fetchImpl, options) => {
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxResponseBytes = options?.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    return async (request) => {
+        const signal = AbortSignal.timeout(timeoutMs);
+        try {
+            const response = await gatewayFetch(request.url, {
+                method: "GET",
+                headers: { ...request.headers },
+                redirect: "manual",
+                signal,
+                ...(egress !== undefined ? { egress } : {}),
+                ...(fetchImpl !== undefined ? { fetchImpl } : {}),
+            });
+            const headers = collectHeaders(response);
+            let json;
+            try {
+                json = await readJsonCapped(response, maxResponseBytes);
+            }
+            catch {
+                throw new FigmaConnectorError("FIGMA_RESPONSE_TOO_LARGE");
+            }
+            return { status: response.status, json, headers };
+        }
+        catch (err) {
+            if (err instanceof FigmaConnectorError)
+                throw err;
+            throw new FigmaConnectorError(classifyFigmaTransportError(err));
+        }
+    };
+};

package/dist/qualityIntelligence/figma/figmaObservedActions.d.ts

@@ -0,0 +1,49 @@
+import { type FigmaAugmentationTally, type FigmaConnectorMetrics, type FigmaConnectorMetricsExtras } from "./figmaConnectorMetrics.js";
+import { type FigmaScopeRef } from "./figmaScopeRef.js";
+import type { FigmaProvenance } from "./figmaConnector.js";
+import type { FigmaSnapshot } from "./figmaSnapshotTypes.js";
+import type { QualityIntelligenceFigma } from "@oscharko-dev/keiko-quality-intelligence";
+export interface ObservedActionContext {
+    readonly evidenceDir: string;
+    readonly now: string;
+}
+export interface ObservedSnapshotInput {
+    readonly ctx: ObservedActionContext;
+    /** Token-free provenance from the connector fetch — the scopeRef source. */
+    readonly provenance: FigmaProvenance;
+    readonly ir: QualityIntelligenceFigma.ScreenIrResult;
+    readonly augmentation: FigmaAugmentationTally;
+    readonly extras?: FigmaConnectorMetricsExtras;
+    /** `true` for a re-snapshot action, `false`/omitted for an initial snapshot. */
+    readonly isResnapshot?: boolean;
+    /**
+     * Defaults to true. Route orchestration sets this false so success is audited only after the
+     * snapshot record has been durably written and reloaded from Evidence.
+     */
+    readonly auditSuccess?: boolean;
+    /** Performs the actual render + assembly (delegates to buildFigmaSnapshot / resnapshotFigma). */
+    readonly run: () => Promise<FigmaSnapshot>;
+}
+export interface ObservedSnapshotResult {
+    readonly snapshot: FigmaSnapshot;
+    readonly metrics: FigmaConnectorMetrics;
+    readonly scopeRef: FigmaScopeRef;
+}
+/**
+ * Observe a snapshot or re-snapshot: gate on consent, run the build, then audit (with counts) and
+ * compute metrics on success, or audit the coded failure and re-raise. The build itself is injected
+ * so no #753/#759 behaviour changes.
+ */
+export declare const observeFigmaSnapshot: (input: ObservedSnapshotInput) => Promise<ObservedSnapshotResult>;
+export interface ObservedRevokeInput {
+    readonly ctx: ObservedActionContext;
+    readonly scopeRef: FigmaScopeRef;
+    /** Performs the actual key removal (delegates to FigmaTokenStore.revoke). */
+    readonly run: () => void;
+}
+/**
+ * Observe a revoke (key removal): run it, then audit the action. Revoke needs no consent gate — it
+ * removes access — and produces no metrics. A failure is audited then re-raised.
+ */
+export declare const observeFigmaRevoke: (input: ObservedRevokeInput) => void;
+//# sourceMappingURL=figmaObservedActions.d.ts.map

package/dist/qualityIntelligence/figma/figmaObservedActions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figmaObservedActions.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaObservedActions.ts"],"names":[],"mappings":"AAoBA,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EACjC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AAEzF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAmCD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,GAAG,EAAE,qBAAqB,CAAC;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,EAAE,EAAE,wBAAwB,CAAC,cAAc,CAAC;IACrD,QAAQ,CAAC,YAAY,EAAE,sBAAsB,CAAC;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,2BAA2B,CAAC;IAC9C,gFAAgF;IAChF,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,iGAAiG;IACjG,QAAQ,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;CAClC;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAC/B,OAAO,qBAAqB,KAC3B,OAAO,CAAC,sBAAsB,CA+BhC,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE,qBAAqB,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,mBAAmB,KAAG,IAa/D,CAAC"}

package/dist/qualityIntelligence/figma/figmaObservedActions.js

@@ -0,0 +1,89 @@
+// Observed connector actions — the audit/consent/metrics hook points (Epic #750, Issue #760).
+//
+// PURELY ADDITIVE over #751/#753/#758/#759: this module does NOT change the connector, snapshot
+// builder, re-snapshot, or token-store behaviour. It composes them with the three governance
+// concerns so the future route tier (#756) calls ONE function per action and gets:
+//   - consent gating before the FIRST fetch (connect / snapshot / resnapshot),
+//   - an audit entry on success AND on a coded failure (re-raising the original error),
+//   - operational metrics on a successful snapshot / re-snapshot.
+//
+// The scopeRef is derived from the connector's token-free provenance, so no board id / link ever
+// reaches the audit or metrics. The actual board fetch is delegated to the injected action; this
+// wrapper only observes it.
+import { FigmaConnectorError } from "./figmaConnectorErrors.js";
+import { appendFigmaConnectorAudit, } from "./figmaConnectorAudit.js";
+import { assertReadOnlyConsent } from "./figmaConsent.js";
+import { computeFigmaConnectorMetrics, } from "./figmaConnectorMetrics.js";
+import { deriveFigmaScopeRef } from "./figmaScopeRef.js";
+const auditFailureAndRethrow = (ctx, scopeRef, action, error) => {
+    const errorCode = error instanceof FigmaConnectorError ? error.code : "FIGMA_INTERNAL";
+    appendFigmaConnectorAudit({
+        scopeRef,
+        evidenceDir: ctx.evidenceDir,
+        action,
+        outcome: "error",
+        errorCode,
+        now: ctx.now,
+    });
+    throw error;
+};
+const countsOf = (ir, snapshot) => ({
+    screens: ir.screens.length,
+    renders: snapshot.screens.length,
+    skipped: snapshot.skippedScreens.length,
+    designTokens: ir.tokens.colors.length +
+        ir.tokens.typography.length +
+        ir.tokens.spacing.length +
+        ir.tokens.radius.length,
+    ...(ir.links.length > 0 ? { navTransitions: ir.links.length } : {}),
+});
+/**
+ * Observe a snapshot or re-snapshot: gate on consent, run the build, then audit (with counts) and
+ * compute metrics on success, or audit the coded failure and re-raise. The build itself is injected
+ * so no #753/#759 behaviour changes.
+ */
+export const observeFigmaSnapshot = async (input) => {
+    const scopeRef = deriveFigmaScopeRef(input.provenance.fileKey, input.provenance.nodeId);
+    const action = input.isResnapshot === true ? "resnapshot" : "snapshot";
+    // Consent is a precondition checked BEFORE the action starts, so a consent-denied attempt throws
+    // here and produces no audit entry: it is a refused precondition, not a connector-action outcome.
+    assertReadOnlyConsent(scopeRef, input.ctx.evidenceDir);
+    let snapshot;
+    try {
+        snapshot = await input.run();
+    }
+    catch (error) {
+        return auditFailureAndRethrow(input.ctx, scopeRef, action, error);
+    }
+    const metrics = computeFigmaConnectorMetrics(input.ir, snapshot, input.augmentation, input.extras ?? {});
+    if (input.auditSuccess !== false) {
+        appendFigmaConnectorAudit({
+            scopeRef,
+            evidenceDir: input.ctx.evidenceDir,
+            action,
+            outcome: "ok",
+            counts: countsOf(input.ir, snapshot),
+            now: input.ctx.now,
+        });
+    }
+    return { snapshot, metrics, scopeRef };
+};
+/**
+ * Observe a revoke (key removal): run it, then audit the action. Revoke needs no consent gate — it
+ * removes access — and produces no metrics. A failure is audited then re-raised.
+ */
+export const observeFigmaRevoke = (input) => {
+    try {
+        input.run();
+    }
+    catch (error) {
+        auditFailureAndRethrow(input.ctx, input.scopeRef, "revoke", error);
+    }
+    appendFigmaConnectorAudit({
+        scopeRef: input.scopeRef,
+        evidenceDir: input.ctx.evidenceDir,
+        action: "revoke",
+        outcome: "ok",
+        now: input.ctx.now,
+    });
+};

package/dist/qualityIntelligence/figma/figmaReadiness.d.ts

@@ -0,0 +1,32 @@
+export interface FigmaDevStatus {
+    readonly type: string;
+}
+export interface FigmaNode {
+    readonly id: string;
+    readonly name: string;
+    readonly type: string;
+    readonly devStatus?: FigmaDevStatus;
+    readonly children?: readonly FigmaNode[];
+}
+export interface ReadinessOptions {
+    readonly version?: string | undefined;
+    readonly releaseMarker?: string | undefined;
+}
+export type ReadinessSignal = {
+    readonly source: "version";
+    readonly ready: true;
+    readonly version: string;
+} | {
+    readonly source: "section";
+    readonly ready: true;
+    readonly matchedNodeName: string;
+} | {
+    readonly source: "devStatus";
+    readonly ready: true;
+    readonly readyNodeCount: number;
+} | {
+    readonly source: "none";
+    readonly ready: false;
+};
+export declare const resolveReadiness: (root: FigmaNode, options: ReadinessOptions) => ReadinessSignal;
+//# sourceMappingURL=figmaReadiness.d.ts.map

package/dist/qualityIntelligence/figma/figmaReadiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figmaReadiness.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaReadiness.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC9E;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GACtF;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GACvF;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AA2CvD,eAAO,MAAM,gBAAgB,GAAI,MAAM,SAAS,EAAE,SAAS,gBAAgB,KAAG,eAiB7E,CAAC"}

package/dist/qualityIntelligence/figma/figmaReadiness.js

@@ -0,0 +1,67 @@
+// Figma readiness resolution (Epic #750, Issue #751).
+//
+// Pure, deterministic. Resolves whether a scoped node subtree is "release-ready" using a
+// fixed precedence with graceful fallback:
+//
+//   1. version  — a pinned version id was supplied (operator pinned a named version).
+//   2. section  — a node anywhere in the subtree is named with a configurable release
+//                 marker (default case-insensitive token `release`).
+//   3. devStatus — one or more nodes carry Dev-Mode `devStatus.type === "READY_FOR_DEV"`.
+//
+// `devStatus` is OPTIONAL in the Figma REST response and may be absent for an entire
+// account/plan. When it is absent (or no node is READY_FOR_DEV) and the higher signals
+// did not fire, the result degrades to `{ source: "none", ready: false }`.
+const DEFAULT_RELEASE_MARKER = "release";
+const READY_FOR_DEV = "READY_FOR_DEV";
+const TOKEN_SPLIT = /[^a-z0-9]+/u;
+const NEGATED_RELEASE_NAME = /\b(?:unreleased|not\s+(?:for\s+)?release|no\s+release|non[-\s]+release)\b/iu;
+const walk = (node, visit) => {
+    if (visit(node))
+        return true;
+    for (const child of node.children ?? []) {
+        if (walk(child, visit))
+            return true;
+    }
+    return false;
+};
+const findReleaseNamedNode = (root, marker) => {
+    const needle = marker.trim().toLowerCase();
+    if (needle.length === 0)
+        return undefined;
+    let match;
+    walk(root, (node) => {
+        const lowerName = node.name.toLowerCase();
+        const tokens = lowerName.split(TOKEN_SPLIT).filter((token) => token.length > 0);
+        const markerMatched = tokens.includes(needle) || (needle === DEFAULT_RELEASE_MARKER && tokens.includes("released"));
+        if (markerMatched && !NEGATED_RELEASE_NAME.test(lowerName)) {
+            match = node;
+            return true;
+        }
+        return false;
+    });
+    return match;
+};
+const countReadyForDevNodes = (root) => {
+    let count = 0;
+    walk(root, (node) => {
+        if (node.devStatus?.type === READY_FOR_DEV)
+            count += 1;
+        return false;
+    });
+    return count;
+};
+export const resolveReadiness = (root, options) => {
+    if (options.version !== undefined && options.version.length > 0) {
+        return { source: "version", ready: true, version: options.version };
+    }
+    const marker = options.releaseMarker ?? DEFAULT_RELEASE_MARKER;
+    const namedNode = findReleaseNamedNode(root, marker);
+    if (namedNode !== undefined) {
+        return { source: "section", ready: true, matchedNodeName: namedNode.name };
+    }
+    const readyNodeCount = countReadyForDevNodes(root);
+    if (readyNodeCount > 0) {
+        return { source: "devStatus", ready: true, readyNodeCount };
+    }
+    return { source: "none", ready: false };
+};

package/dist/qualityIntelligence/figma/figmaRenderPort.d.ts

@@ -0,0 +1,29 @@
+import { type OutboundHttpEgressConfig } from "@oscharko-dev/keiko-model-gateway/internal/http";
+export interface FigmaRenderRequest {
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+}
+export interface FigmaRenderResponse {
+    readonly status: number;
+    readonly bytes: Uint8Array;
+    readonly headers: Readonly<Record<string, string>>;
+}
+export type FigmaRenderPort = (request: FigmaRenderRequest) => Promise<FigmaRenderResponse>;
+/** Optional creation-time overrides for the default render port. */
+export interface FigmaRenderPortOptions {
+    readonly timeoutMs?: number;
+    readonly maxResponseBytes?: number;
+}
+/**
+ * Thin default adapter over the platform `fetch`. This is the ONLY place in the render path
+ * `fetch` is named. It forwards the caller-built headers verbatim and reads the body as raw
+ * bytes with an explicit byte cap; it does not log, retry, or inspect any token. Resilience/
+ * backoff is out of scope here (#759); the proxy/custom-CA transport is the platform
+ * prerequisite (#802) that replaces this.
+ *
+ * `redirect: "manual"` prevents any caller-supplied auth header from following a cross-origin
+ * redirect. A 3xx response surfaces as a non-2xx port result; the connector treats it as
+ * upstream error.
+ */
+export declare const createDefaultFigmaRenderPort: (egress?: OutboundHttpEgressConfig, fetchImpl?: typeof fetch, options?: FigmaRenderPortOptions) => FigmaRenderPort;
+//# sourceMappingURL=figmaRenderPort.d.ts.map

package/dist/qualityIntelligence/figma/figmaRenderPort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figmaRenderPort.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaRenderPort.ts"],"names":[],"mappings":"AAkBA,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,iDAAiD,CAAC;AAQzD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAG3B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAE5F,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAiCD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GACvC,SAAS,wBAAwB,EACjC,YAAY,OAAO,KAAK,EACxB,UAAU,sBAAsB,KAC/B,eA2BF,CAAC"}

package/dist/qualityIntelligence/figma/figmaRenderPort.js

@@ -0,0 +1,93 @@
+// Figma render-byte seam (Epic #750, Issue #753).
+//
+// The `/v1/images` API returns an EPHEMERAL https url per rendered frame; a SECOND fetch
+// downloads the PNG bytes from that url. The snapshot builder NEVER calls `fetch`/undici
+// directly for that download — it depends only on this small injectable port so unit tests
+// can mock the transport and a future proxy-aware / custom-CA client (#802) can be slotted in
+// without touching builder logic.
+//
+// The request type carries the outbound headers. The render-url download itself needs no
+// Figma auth header (the ephemeral url is pre-signed), but the seam still forwards whatever
+// headers the caller supplies so the proxy adapter can add transport headers. The token is
+// never materialised here and never logged.
+//
+// redirect: "manual" is set so any auth header supplied by the caller cannot follow a
+// cross-origin redirect. A 3xx response surfaces as a non-2xx status; the connector
+// layer treats non-2xx as upstream error.
+import { classifyFigmaTransportError, FigmaConnectorError } from "./figmaConnectorErrors.js";
+import { gatewayFetch, } from "@oscharko-dev/keiko-model-gateway/internal/http";
+/** Default request timeout in milliseconds for Figma render downloads. */
+const DEFAULT_TIMEOUT_MS = 60_000;
+/** Default maximum render response body size (32 MiB). */
+const DEFAULT_MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
+/**
+ * Read a streaming response body up to `maxBytes`, accumulating into a Uint8Array.
+ * Throws a {@link FigmaConnectorError} with `FIGMA_RESPONSE_TOO_LARGE` if the cap is exceeded.
+ */
+const readBytesCapped = async (response, maxBytes) => {
+    if (response.body === null) {
+        const buffer = await response.arrayBuffer();
+        return new Uint8Array(buffer);
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel();
+            throw new FigmaConnectorError("FIGMA_RESPONSE_TOO_LARGE");
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+};
+/**
+ * Thin default adapter over the platform `fetch`. This is the ONLY place in the render path
+ * `fetch` is named. It forwards the caller-built headers verbatim and reads the body as raw
+ * bytes with an explicit byte cap; it does not log, retry, or inspect any token. Resilience/
+ * backoff is out of scope here (#759); the proxy/custom-CA transport is the platform
+ * prerequisite (#802) that replaces this.
+ *
+ * `redirect: "manual"` prevents any caller-supplied auth header from following a cross-origin
+ * redirect. A 3xx response surfaces as a non-2xx port result; the connector treats it as
+ * upstream error.
+ */
+export const createDefaultFigmaRenderPort = (egress, fetchImpl, options) => {
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxResponseBytes = options?.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    return async (request) => {
+        const signal = AbortSignal.timeout(timeoutMs);
+        try {
+            const response = await gatewayFetch(request.url, {
+                method: "GET",
+                headers: { ...request.headers },
+                redirect: "manual",
+                signal,
+                maxResponseBytes,
+                ...(egress !== undefined ? { egress } : {}),
+                ...(fetchImpl !== undefined ? { fetchImpl } : {}),
+            });
+            const headers = {};
+            response.headers.forEach((value, name) => {
+                headers[name] = value;
+            });
+            const bytes = await readBytesCapped(response, maxResponseBytes);
+            return { status: response.status, bytes, headers };
+        }
+        catch (err) {
+            if (err instanceof FigmaConnectorError)
+                throw err;
+            throw new FigmaConnectorError(classifyFigmaTransportError(err));
+        }
+    };
+};

package/dist/qualityIntelligence/figma/figmaResnapshot.d.ts

@@ -0,0 +1,28 @@
+import type { FigmaConnector, FigmaFetchOptions } from "./figmaConnector.js";
+import type { FigmaHttpPort } from "./figmaHttpPort.js";
+import type { FigmaRenderPort } from "./figmaRenderPort.js";
+import type { FigmaSnapshot } from "./figmaSnapshotTypes.js";
+import type { FigmaRetryPolicy, FigmaRetrySleep } from "./figmaRetry.js";
+import type { FigmaScopedResult } from "./figmaConnector.js";
+import type { QualityIntelligenceFigma } from "@oscharko-dev/keiko-quality-intelligence";
+/** Deterministic clean of the raw scoped nodes into the per-screen IR (#752 lives behind this seam). */
+export type FigmaCleanToIr = (scoped: FigmaScopedResult) => QualityIntelligenceFigma.ScreenIrResult;
+export interface ResnapshotFigmaDeps {
+    readonly connector: FigmaConnector;
+    readonly cleanToIr: FigmaCleanToIr;
+    readonly token: string;
+    readonly imagesPort: FigmaHttpPort;
+    readonly renderPort: FigmaRenderPort;
+    readonly batchSize?: number;
+    readonly maxImageBytes?: number;
+    readonly downloadConcurrency?: number;
+    readonly retryPolicy?: FigmaRetryPolicy;
+    readonly sleep?: FigmaRetrySleep;
+}
+/**
+ * Perform an explicit full scoped re-snapshot of `url`. Re-fetches the whole scope and rebuilds
+ * the Snapshot — no delta, no incremental reuse. `options.version` pins the re-fetch to a named
+ * Figma version so the re-snapshot stays within the configured scope.
+ */
+export declare const resnapshotFigma: (url: string, deps: ResnapshotFigmaDeps, options?: FigmaFetchOptions) => Promise<FigmaSnapshot>;
+//# sourceMappingURL=figmaResnapshot.d.ts.map

package/dist/qualityIntelligence/figma/figmaResnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figmaResnapshot.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaResnapshot.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AAEzF,wGAAwG;AACxG,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,iBAAiB,KAAK,wBAAwB,CAAC,cAAc,CAAC;AAEpG,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;CAClC;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAC1B,KAAK,MAAM,EACX,MAAM,mBAAmB,EACzB,UAAS,iBAAsB,KAC9B,OAAO,CAAC,aAAa,CAuBvB,CAAC"}

package/dist/qualityIntelligence/figma/figmaResnapshot.js

@@ -0,0 +1,38 @@
+// Explicit, on-demand FULL re-snapshot of a Figma scope (Epic #750, Issue #759; drift #735).
+//
+// A re-snapshot is a DELIBERATE caller action — never a webhook, never a poll, never a designer
+// signal. It performs a fresh, scoped, FULL re-fetch of the same board scope and rebuilds the
+// immutable Snapshot from scratch: scoped nodes fetch → deterministic IR clean → render. There is
+// NO delta and NO incremental skip of "unchanged" screens — every screen in scope is re-fetched
+// and re-rendered. Because the Snapshot integrity hash is deterministic and excludes wall-clock
+// time, two re-snapshots of an unchanged design hash identically; a changed design changes the
+// hash. That hash compare IS the drift signal (#735) — this module performs the re-snapshot; the
+// comparison is the caller's, and Figma is contacted ONLY here, within the snapshot boundary.
+import { buildFigmaSnapshot } from "./figmaSnapshotBuilder.js";
+/**
+ * Perform an explicit full scoped re-snapshot of `url`. Re-fetches the whole scope and rebuilds
+ * the Snapshot — no delta, no incremental reuse. `options.version` pins the re-fetch to a named
+ * Figma version so the re-snapshot stays within the configured scope.
+ */
+export const resnapshotFigma = async (url, deps, options = {}) => {
+    // Deep scoped-pagination fetch (#837): a re-snapshot must capture the same in-screen text the
+    // initial build does, so the regenerated drift baseline (#735) is comparable. Still a FULL,
+    // explicit, on-demand re-fetch — no delta, no incremental skip — within the snapshot boundary.
+    const scoped = await deps.connector.fetchScopedNodesDeep(url, options);
+    const ir = deps.cleanToIr(scoped);
+    const buildInput = {
+        ir,
+        provenance: scoped.provenance,
+        token: deps.token,
+        imagesPort: deps.imagesPort,
+        renderPort: deps.renderPort,
+        ...(deps.batchSize !== undefined ? { batchSize: deps.batchSize } : {}),
+        ...(deps.maxImageBytes !== undefined ? { maxImageBytes: deps.maxImageBytes } : {}),
+        ...(deps.downloadConcurrency !== undefined
+            ? { downloadConcurrency: deps.downloadConcurrency }
+            : {}),
+        ...(deps.retryPolicy !== undefined ? { retryPolicy: deps.retryPolicy } : {}),
+        ...(deps.sleep !== undefined ? { sleep: deps.sleep } : {}),
+    };
+    return buildFigmaSnapshot(buildInput);
+};

package/dist/qualityIntelligence/figma/figmaRetry.d.ts

@@ -0,0 +1,31 @@
+/** Injectable wait seam — the default is real `setTimeout`; tests pass a synchronous recorder. */
+export type FigmaRetrySleep = (ms: number) => Promise<void>;
+export interface FigmaRetryPolicy {
+    /** Maximum extra attempts after the first; total attempts = maxRetries + 1. */
+    readonly maxRetries: number;
+    /** First backoff delay in ms; subsequent delays double until `maxDelayMs`. */
+    readonly baseDelayMs: number;
+    /** Hard ceiling for any single delay (computed or `Retry-After`) — prevents unbounded waits. */
+    readonly maxDelayMs: number;
+}
+/**
+ * Bounded, conservative default well inside Figma's documented limits. Patient enough (8 retries,
+ * 45s ceiling) that the multi-fetch deep scoped-pagination build (#837) absorbs the cost-based 429
+ * bursts a large board provokes instead of aborting, while staying finite so a genuinely down API
+ * still fails fast-ish.
+ */
+export declare const DEFAULT_FIGMA_RETRY_POLICY: FigmaRetryPolicy;
+/** The minimum a backoff-capable response must expose: a status and (lower-cased) headers. */
+export interface FigmaBackoffResponse {
+    readonly status: number;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** The real-timer sleep used by the default ports. */
+export declare const realFigmaRetrySleep: FigmaRetrySleep;
+/**
+ * Run `operation` (a single attempt), retrying ONLY on HTTP 429 with deterministic exponential
+ * backoff up to `policy.maxRetries`. Honours a numeric `Retry-After` over the computed delay.
+ * Throws FIGMA_RATE_LIMITED once the bounded retries are exhausted; never retries a non-429.
+ */
+export declare const fetchWithBackoff: <R extends FigmaBackoffResponse>(operation: () => Promise<R>, policy: FigmaRetryPolicy, sleep: FigmaRetrySleep) => Promise<R>;
+//# sourceMappingURL=figmaRetry.d.ts.map

package/dist/qualityIntelligence/figma/figmaRetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figmaRetry.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaRetry.ts"],"names":[],"mappings":"AAgBA,kGAAkG;AAClG,MAAM,MAAM,eAAe,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,gGAAgG;IAChG,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,gBAIxC,CAAC;AAEF,8FAA8F;AAC9F,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,EAAE,eAG9B,CAAC;AAsBL;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAU,CAAC,SAAS,oBAAoB,EACnE,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,QAAQ,gBAAgB,EACxB,OAAO,eAAe,KACrB,OAAO,CAAC,CAAC,CASX,CAAC"}

package/dist/qualityIntelligence/figma/figmaRetry.js

@@ -0,0 +1,62 @@
+// Deterministic 429 backoff for the bounded Figma snapshot-build (Epic #750, Issue #759).
+//
+// Figma rate-limits the scoped `/v1/files/:key/nodes` fetch and the `/v1/images` render with HTTP
+// 429. On a huge enterprise board these are expected, not exceptional, so the snapshot-build must
+// retry them on a deterministic exponential schedule rather than failing or hammering the API.
+//
+// Scope discipline: ONLY a 429 is retried here. A 4xx (auth/scope/not-found) or 5xx is surfaced
+// to the caller unchanged — those are not rate-limit conditions and must not be silently retried.
+// There is NO webhook, NO polling, and NO timer beyond the injectable `sleep` seam: the whole
+// schedule is driven by the caller's awaited promise chain, so a mocked sleep makes tests instant.
+//
+// The `sleep` seam is injectable so unit tests record the exact delay schedule without waiting.
+// `Retry-After` (whole seconds) is honoured when present and numeric, capped at `maxDelayMs`.
+import { FigmaConnectorError } from "./figmaConnectorErrors.js";
+/**
+ * Bounded, conservative default well inside Figma's documented limits. Patient enough (8 retries,
+ * 45s ceiling) that the multi-fetch deep scoped-pagination build (#837) absorbs the cost-based 429
+ * bursts a large board provokes instead of aborting, while staying finite so a genuinely down API
+ * still fails fast-ish.
+ */
+export const DEFAULT_FIGMA_RETRY_POLICY = {
+    maxRetries: 8,
+    baseDelayMs: 500,
+    maxDelayMs: 45_000,
+};
+/** The real-timer sleep used by the default ports. */
+export const realFigmaRetrySleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+const FIGMA_RATE_LIMIT_STATUS = 429;
+const computeBackoffMs = (attempt, policy) => {
+    const exponential = policy.baseDelayMs * 2 ** attempt;
+    return Math.min(exponential, policy.maxDelayMs);
+};
+// Parses a numeric `Retry-After` (whole seconds) into capped milliseconds. Returns undefined for a
+// missing/non-numeric/negative value so the caller falls back to the computed exponential delay.
+const retryAfterMs = (headers, policy) => {
+    const raw = headers?.["retry-after"];
+    if (raw === undefined)
+        return undefined;
+    const seconds = Number(raw);
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return undefined;
+    return Math.min(seconds * 1000, policy.maxDelayMs);
+};
+/**
+ * Run `operation` (a single attempt), retrying ONLY on HTTP 429 with deterministic exponential
+ * backoff up to `policy.maxRetries`. Honours a numeric `Retry-After` over the computed delay.
+ * Throws FIGMA_RATE_LIMITED once the bounded retries are exhausted; never retries a non-429.
+ */
+export const fetchWithBackoff = async (operation, policy, sleep) => {
+    for (let attempt = 0; attempt <= policy.maxRetries; attempt += 1) {
+        const response = await operation();
+        if (response.status !== FIGMA_RATE_LIMIT_STATUS)
+            return response;
+        if (attempt === policy.maxRetries)
+            break;
+        const delay = retryAfterMs(response.headers, policy) ?? computeBackoffMs(attempt, policy);
+        await sleep(delay);
+    }
+    throw new FigmaConnectorError("FIGMA_RATE_LIMITED");
+};

package/dist/qualityIntelligence/figma/figmaScopeRef.d.ts

@@ -0,0 +1,9 @@
+/** Opaque, non-reversible reference to a connected Figma scope. Hex SHA-256, safe as a store key. */
+export type FigmaScopeRef = string;
+/**
+ * Derive the opaque scope reference for a `(fileKey, nodeId)` pair. Pure and deterministic. The
+ * inputs are design identifiers and are consumed ONLY to produce the one-way digest — they are not
+ * retained anywhere by this function.
+ */
+export declare const deriveFigmaScopeRef: (fileKey: string, nodeId: string) => FigmaScopeRef;
+//# sourceMappingURL=figmaScopeRef.d.ts.map

package/dist/qualityIntelligence/figma/figmaScopeRef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figmaScopeRef.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaScopeRef.ts"],"names":[],"mappings":"AAcA,qGAAqG;AACrG,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAEnC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,MAAM,EAAE,QAAQ,MAAM,KAAG,aACnC,CAAC"}