@oscharko-dev/keiko-server 0.2.0

package/dist/qualityIntelligence/figma/figmaScopeRef.js

@@ -0,0 +1,18 @@
+// Non-reversible scope reference for connector observability (Epic #750, Issue #760).
+//
+// An audit entry or consent record must NEVER carry a customer board id, link, file key, node id,
+// or any design content. But it must still be keyed to "the same connected scope" so the operator
+// can correlate connect → snapshot → re-snapshot → revoke for one board without ever recording which
+// board it is. The scope reference is the SHA-256 of `${fileKey}:${nodeId}`, hex-encoded: a stable,
+// collision-irrelevant, NON-REVERSIBLE digest. The same scope always yields the same ref; two
+// different scopes (in practice) yield different refs; and the raw ids cannot be recovered from it.
+//
+// The hex digest also satisfies `assertValidRunId`'s bounded `[A-Za-z0-9._-]` charset, so it is a
+// safe filename key for the reused contained JSON artifact store.
+import { sha256Hex } from "@oscharko-dev/keiko-security";
+/**
+ * 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 const deriveFigmaScopeRef = (fileKey, nodeId) => sha256Hex(`${fileKey}:${nodeId}`);

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

@@ -0,0 +1,86 @@
+/** A raw Figma node as returned by `GET /v1/files/:key/nodes` — provider-shaped, partially typed. */
+export interface RawFigmaNode {
+    id?: unknown;
+    name?: unknown;
+    type?: unknown;
+    children?: RawFigmaNode[];
+    [key: string]: unknown;
+}
+/** Fetches one node id's subtree at the configured `pageDepth`. Returns undefined on a hard failure
+ *  (the caller keeps the shallow content rather than aborting the whole build). */
+export type ScopedNodeFetcher = (nodeId: string) => Promise<RawFigmaNode | undefined>;
+/**
+ * Generic, board-agnostic budgets that bound the per-screen pagination. The global ceiling is the
+ * deterministic product `maxScreensDeep × maxNodesPerScreen` (and `× maxFetchesPerScreen`): there is
+ * NO shared, live, cross-screen counter, so screens are fully independent and the assembled tree is
+ * identical regardless of how the concurrent fetches interleave (load-bearing for the drift hash,
+ * #735). None of these is tuned to a sample board; all are overridable per deployment.
+ */
+export interface ScopedPaginationLimits {
+    /** Depth of each individual scoped fetch (the discovery fetch and every per-screen fetch). A larger
+     *  depth captures a whole shallow screen in one request and a deep screen in fewer rounds — the
+     *  dominant lever against per-request latency — at the cost of larger individual responses. */
+    readonly pageDepth: number;
+    /** Per-screen raw-node budget; breadth-first expansion stops once a screen reaches it. */
+    readonly maxNodesPerScreen: number;
+    /** Per-screen fetch cap; bounds requests (and thus wall-clock) for one dense screen. */
+    readonly maxFetchesPerScreen: number;
+    /** Cap on how many discovered screens are deep-fetched; a board with more reports `capped`. */
+    readonly maxScreensDeep: number;
+    /**
+     * Max in-flight scoped fetches across the WHOLE build (a shared gate over all screens + levels).
+     * Real boards have multi-second per-subtree latency, so this pool is the dominant wall-clock lever.
+     * It throttles concurrency only — the result is order-independent and deterministic. The 429
+     * backoff (#759) absorbs the burst. Clamp ≥ 1.
+     */
+    readonly fetchConcurrency: number;
+}
+/**
+ * Defaults balanced for Figma's cost-based rate limit on real, latency-bound boards (NOT tuned to any
+ * sample board's content). `pageDepth=8` captures typical screen bodies in one bounded request, while
+ * a small shared pool of 2 in-flight fetches avoids bursty high-cost 429s. The per-screen and
+ * per-board caps deliberately keep the worst-case live build below 100 deep scoped fetches by
+ * default, so a pasted whole-canvas Release section remains reviewable in the browser instead of
+ * turning into a minutes-long request storm. Operators can raise these budgets per deployment through
+ * KEIKO_FIGMA_* env vars when their Figma plan and proxy allow it.
+ */
+export declare const DEFAULT_SCOPED_PAGINATION_LIMITS: ScopedPaginationLimits;
+/** Hard safety ceilings: operators may tune pagination, but never past these finite bounds. */
+export declare const SCOPED_PAGINATION_LIMIT_CEILINGS: ScopedPaginationLimits;
+export declare const resolveScopedPaginationLimits: (partial?: Partial<ScopedPaginationLimits>) => ScopedPaginationLimits;
+/** Coverage telemetry for one deep snapshot fetch — surfaced in the snapshot summary (never a leak). */
+export interface FigmaScopeCoverage {
+    /** Screens discovered structurally under the scoped root. */
+    readonly screenCount: number;
+    /** Screens that received a per-screen deep fetch (≤ `maxScreensDeep`). */
+    readonly screensDeepFetched: number;
+    /** Screens whose deep content was cut short by a per-screen budget (a coverage signal). */
+    readonly screensTruncated: number;
+    /** Total raw nodes in the assembled deep document. */
+    readonly nodeCount: number;
+    /** Total per-screen scoped fetches performed (excludes the single discovery fetch). */
+    readonly fetchCount: number;
+    /** True when more screens were discovered than `maxScreensDeep`, so some stayed shallow. */
+    readonly capped: boolean;
+}
+export interface DeepFetchResult {
+    readonly document: RawFigmaNode;
+    readonly coverage: FigmaScopeCoverage;
+}
+/**
+ * The screen FRAME/INSTANCE nodes under a scoped root, descending only through container groupings
+ * (CANVAS/SECTION) — never into a screen's own body, so a nested frame stays part of its screen.
+ * Mirrors the pure-domain `detectScreens` rule (#752) at the connector (raw-node) layer. A directly
+ * scoped screen root is the sole screen.
+ */
+export declare const discoverScreenNodes: (root: RawFigmaNode) => readonly RawFigmaNode[];
+/**
+ * Deepen a shallow scoped document into a per-screen-paginated one, bounded by {@link limits}.
+ * `fetchNode` performs one bounded `depth=pageDepth` scoped fetch (with the connector's 429 backoff).
+ * Stays inside the snapshot-build boundary: it issues only scoped node fetches, returns the assembled
+ * raw document for the existing deterministic IR cleaner, and reports coverage. A board with no
+ * discoverable screen (a directly-scoped non-screen, non-container node) returns the shallow root
+ * unchanged with zero-screen coverage.
+ */
+export declare const paginateScopedDocument: (shallowRoot: RawFigmaNode, fetchNode: ScopedNodeFetcher, limits?: ScopedPaginationLimits) => Promise<DeepFetchResult>;
+//# sourceMappingURL=figmaScopedPagination.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"figmaScopedPagination.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaScopedPagination.ts"],"names":[],"mappings":"AAyBA,qGAAqG;AACrG,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;mFACmF;AACnF,MAAM,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;AAEtF;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC;;mGAE+F;IAC/F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0FAA0F;IAC1F,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,wFAAwF;IACxF,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,+FAA+F;IAC/F,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,gCAAgC,EAAE,sBAM9C,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,gCAAgC,EAAE,sBAM9C,CAAC;AAEF,eAAO,MAAM,6BAA6B,GACxC,UAAU,OAAO,CAAC,sBAAsB,CAAC,KACxC,sBAgBF,CAAC;AAEF,wGAAwG;AACxG,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,2FAA2F;IAC3F,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uFAAuF;IACvF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;CACvC;AA0CD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,YAAY,KAAG,SAAS,YAAY,EAY7E,CAAC;AA4KF;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GACjC,aAAa,YAAY,EACzB,WAAW,iBAAiB,EAC5B,SAAQ,sBAAyD,KAChE,OAAO,CAAC,eAAe,CAsCzB,CAAC"}

package/dist/qualityIntelligence/figma/figmaScopedPagination.js

@@ -0,0 +1,308 @@
+// Scoped, bounded depth pagination for the Figma snapshot-build (Epic #750, Issues #837, #759).
+//
+// PROBLEM (#837, found by live verification in #757): a single scoped `nodes?depth=4` fetch of the
+// canvas captures layout + structure + design tokens but almost NO in-screen text — on real,
+// component-instance-heavy enterprise boards the meaningful UI text lives DEEP inside instance
+// subtrees (verified content-free: text concentrated at screen-relative depths 7–18). A naive
+// deeper single fetch is not an option: one real screen alone is 17k–20k nodes, far past the
+// per-fetch oversize guard (#759), and the whole canvas is hundreds of thousands of nodes.
+//
+// SOLUTION: per-screen scoped pagination, still strictly WITHIN the snapshot-build communication
+// boundary (Figma is contacted only here, during the build; every downstream stage reads the stored
+// Snapshot). After the screens are discovered structurally from one shallow fetch, each screen
+// subtree is completed by a breadth-first sequence of bounded `depth=pageDepth` fetches: each fetch
+// is small (one subtree, ≤ a per-fetch budget), and the assembled per-screen tree is bounded by a
+// per-screen node + request budget. Breadth-first means the shallow, most-meaningful levels are
+// captured first; when a budget is hit the deep tail is dropped and the screen is reported truncated
+// (a coverage signal, never a crash). Figma truncates a depth-limited subtree by returning
+// `children: []` on the frontier container nodes — that empty array on a container at exactly
+// `pageDepth` is the re-fetch marker.
+//
+// Generic by construction: no screen name, layout, mask style, copy, or board-specific threshold is
+// read — only structural node type and the generic budgets below. Deterministic: screens and each
+// frontier are processed in Figma's stable child order, so the same board state yields the same
+// assembled tree (and a budget cut-off truncates the same deterministic tail every run).
+/**
+ * Defaults balanced for Figma's cost-based rate limit on real, latency-bound boards (NOT tuned to any
+ * sample board's content). `pageDepth=8` captures typical screen bodies in one bounded request, while
+ * a small shared pool of 2 in-flight fetches avoids bursty high-cost 429s. The per-screen and
+ * per-board caps deliberately keep the worst-case live build below 100 deep scoped fetches by
+ * default, so a pasted whole-canvas Release section remains reviewable in the browser instead of
+ * turning into a minutes-long request storm. Operators can raise these budgets per deployment through
+ * KEIKO_FIGMA_* env vars when their Figma plan and proxy allow it.
+ */
+export const DEFAULT_SCOPED_PAGINATION_LIMITS = {
+    pageDepth: 8,
+    maxNodesPerScreen: 8_000,
+    maxFetchesPerScreen: 6,
+    maxScreensDeep: 16,
+    fetchConcurrency: 2,
+};
+/** Hard safety ceilings: operators may tune pagination, but never past these finite bounds. */
+export const SCOPED_PAGINATION_LIMIT_CEILINGS = {
+    pageDepth: 16,
+    maxNodesPerScreen: 50_000,
+    maxFetchesPerScreen: 128,
+    maxScreensDeep: 250,
+    fetchConcurrency: 8,
+};
+export const resolveScopedPaginationLimits = (partial) => {
+    const pick = (key) => {
+        const supplied = partial?.[key];
+        const resolved = supplied !== undefined && Number.isInteger(supplied) && supplied >= 1
+            ? supplied
+            : DEFAULT_SCOPED_PAGINATION_LIMITS[key];
+        return Math.min(resolved, SCOPED_PAGINATION_LIMIT_CEILINGS[key]);
+    };
+    return {
+        pageDepth: pick("pageDepth"),
+        maxNodesPerScreen: pick("maxNodesPerScreen"),
+        maxFetchesPerScreen: pick("maxFetchesPerScreen"),
+        maxScreensDeep: pick("maxScreensDeep"),
+        fetchConcurrency: pick("fetchConcurrency"),
+    };
+};
+const SCREEN_TYPES = new Set(["FRAME", "INSTANCE"]);
+const CONTAINER_TYPES = new Set(["CANVAS", "SECTION"]);
+// Node types whose internals are worth a deeper fetch. Leaves (TEXT, VECTOR, RECTANGLE, …) never
+// carry children, so re-fetching them would waste a request; only these container types are expanded.
+const PAGINATE_CONTAINER = new Set([
+    "FRAME",
+    "GROUP",
+    "INSTANCE",
+    "COMPONENT",
+    "COMPONENT_SET",
+    "SECTION",
+]);
+const typeOf = (node) => (typeof node.type === "string" ? node.type : "");
+const idOf = (node) => (typeof node.id === "string" ? node.id : "");
+const childrenOf = (node) => Array.isArray(node.children) ? node.children : [];
+const countNodes = (node) => {
+    let total = 1;
+    for (const child of childrenOf(node))
+        total += countNodes(child);
+    return total;
+};
+const pruneToNodeBudget = (node, maxNodes) => {
+    let remaining = Math.max(1, maxNodes);
+    const clone = (current) => {
+        if (remaining <= 0)
+            return undefined;
+        remaining -= 1;
+        const children = [];
+        for (const child of childrenOf(current)) {
+            const kept = clone(child);
+            if (kept === undefined)
+                break;
+            children.push(kept);
+        }
+        return { ...current, children };
+    };
+    return clone(node) ?? { ...node, children: [] };
+};
+/**
+ * The screen FRAME/INSTANCE nodes under a scoped root, descending only through container groupings
+ * (CANVAS/SECTION) — never into a screen's own body, so a nested frame stays part of its screen.
+ * Mirrors the pure-domain `detectScreens` rule (#752) at the connector (raw-node) layer. A directly
+ * scoped screen root is the sole screen.
+ */
+export const discoverScreenNodes = (root) => {
+    if (SCREEN_TYPES.has(typeOf(root)))
+        return [root];
+    if (!CONTAINER_TYPES.has(typeOf(root)))
+        return [];
+    const screens = [];
+    const walk = (node) => {
+        for (const child of childrenOf(node)) {
+            if (SCREEN_TYPES.has(typeOf(child)))
+                screens.push(child);
+            else if (CONTAINER_TYPES.has(typeOf(child)))
+                walk(child);
+        }
+    };
+    walk(root);
+    return screens;
+};
+// Collect the container frontier nodes of a `pageDepth`-limited subtree: containers at exactly
+// `pageDepth` carrying an empty `children` array (Figma's truncation marker). These are the only
+// nodes worth re-fetching to descend further.
+const collectFrontier = (node, pageDepth) => {
+    const out = [];
+    const rec = (current, depth) => {
+        if (depth === pageDepth) {
+            if (PAGINATE_CONTAINER.has(typeOf(current)) && childrenOf(current).length === 0) {
+                out.push(current);
+            }
+            return;
+        }
+        for (const child of childrenOf(current))
+            rec(child, depth + 1);
+    };
+    rec(node, 0);
+    return out;
+};
+// A concurrency-limited fetch wrapper shared across all screens + levels: at most `limit` scoped
+// fetches are ever in flight, no matter how many screens deepen in parallel. It throttles only — it
+// never reorders results a caller awaits — so it does not affect the deterministic assembled tree.
+const createFetchGate = (fetchNode, limit) => {
+    const cap = Math.max(1, limit);
+    let active = 0;
+    const queue = [];
+    const acquire = () => {
+        if (active < cap) {
+            active += 1;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => queue.push(resolve));
+    };
+    const release = () => {
+        const next = queue.shift();
+        if (next !== undefined)
+            next(); // hand the slot straight to the next waiter (active unchanged)
+        else
+            active -= 1;
+    };
+    return async (nodeId) => {
+        await acquire();
+        try {
+            return await fetchNode(nodeId);
+        }
+        finally {
+            release();
+        }
+    };
+};
+// Expand one breadth-first level: fetch the (budget-capped) frontier nodes together through the gate,
+// splice their children back in stable order, and collect the next level. Pure of any cross-screen
+// state — its result depends only on the inputs, so concurrent interleaving cannot change it.
+const expandLevel = async (frontier, gatedFetch, pageDepth, fetchBudget, nodeBudgetRemaining) => {
+    const level = frontier.slice(0, Math.max(0, fetchBudget));
+    let cut = level.length < frontier.length;
+    const deeps = await Promise.all(level.map((fnode) => gatedFetch(idOf(fnode))));
+    const nextFrontier = [];
+    let nodesAdded = 0;
+    let remainingNodeBudget = Math.max(0, nodeBudgetRemaining);
+    for (let k = 0; k < level.length; k += 1) {
+        const frontierNode = level[k];
+        const deep = deeps[k];
+        if (frontierNode === undefined)
+            continue;
+        if (deep === undefined) {
+            cut = true;
+            continue;
+        }
+        const deepChildren = childrenOf(deep);
+        if (deepChildren.length > 0) {
+            const added = countNodes(deep) - 1;
+            if (added > remainingNodeBudget) {
+                cut = true;
+                continue;
+            }
+            frontierNode.children = deepChildren;
+            nodesAdded += added;
+            remainingNodeBudget -= added;
+            for (const f of collectFrontier(deep, pageDepth))
+                nextFrontier.push(f);
+        }
+    }
+    return { nextFrontier, fetchesUsed: level.length, nodesAdded, cut };
+};
+// Complete one screen subtree by breadth-first bounded pagination. Each level's frontier fetches are
+// dispatched together through the shared gate (so they run in parallel with other screens' fetches),
+// then applied in stable order. Bounded by the per-screen node + fetch budgets only — independent of
+// every other screen — so the result is deterministic regardless of concurrent interleaving.
+const completeScreen = async (shallow, gatedFetch, limits) => {
+    const base = await gatedFetch(idOf(shallow));
+    if (base === undefined) {
+        // Could not deepen this screen — keep the shallow content, but surface partial capture.
+        return { node: shallow, deepFetched: false, truncated: true, fetchCount: 1 };
+    }
+    let screenNodes = countNodes(base);
+    let fetches = 1;
+    let truncated = false;
+    if (screenNodes > limits.maxNodesPerScreen) {
+        return {
+            node: pruneToNodeBudget(base, limits.maxNodesPerScreen),
+            deepFetched: true,
+            truncated: true,
+            fetchCount: fetches,
+        };
+    }
+    let frontier = collectFrontier(base, limits.pageDepth);
+    while (frontier.length > 0) {
+        if (screenNodes >= limits.maxNodesPerScreen || fetches >= limits.maxFetchesPerScreen) {
+            truncated = true;
+            break;
+        }
+        const level = await expandLevel(frontier, gatedFetch, limits.pageDepth, limits.maxFetchesPerScreen - fetches, limits.maxNodesPerScreen - screenNodes);
+        fetches += level.fetchesUsed;
+        screenNodes += level.nodesAdded;
+        if (level.cut) {
+            truncated = true;
+            break;
+        }
+        frontier = level.nextFrontier;
+    }
+    if (frontier.length > 0)
+        truncated = true;
+    return { node: base, deepFetched: true, truncated, fetchCount: fetches };
+};
+// Rebuild the scoped document with each screen subtree replaced by its deep-fetched version, keeping
+// the surrounding container structure (CANVAS/SECTION) intact. Screen nodes are matched by id.
+const rebuildWithDeepScreens = (root, deepById) => {
+    const rewrite = (node) => {
+        const replacement = deepById.get(idOf(node));
+        if (replacement !== undefined)
+            return replacement;
+        const kids = childrenOf(node);
+        if (kids.length === 0)
+            return node;
+        return { ...node, children: kids.map(rewrite) };
+    };
+    return rewrite(root);
+};
+/**
+ * Deepen a shallow scoped document into a per-screen-paginated one, bounded by {@link limits}.
+ * `fetchNode` performs one bounded `depth=pageDepth` scoped fetch (with the connector's 429 backoff).
+ * Stays inside the snapshot-build boundary: it issues only scoped node fetches, returns the assembled
+ * raw document for the existing deterministic IR cleaner, and reports coverage. A board with no
+ * discoverable screen (a directly-scoped non-screen, non-container node) returns the shallow root
+ * unchanged with zero-screen coverage.
+ */
+export const paginateScopedDocument = async (shallowRoot, fetchNode, limits = DEFAULT_SCOPED_PAGINATION_LIMITS) => {
+    const resolvedLimits = resolveScopedPaginationLimits(limits);
+    const screens = discoverScreenNodes(shallowRoot);
+    const deepable = screens.slice(0, resolvedLimits.maxScreensDeep);
+    const gatedFetch = createFetchGate(fetchNode, resolvedLimits.fetchConcurrency);
+    // All deep-fetchable screens run concurrently; the shared gate bounds total in-flight fetches.
+    // Each screen's result depends only on its own budgets, so order-of-completion never changes it.
+    const outcomes = await Promise.all(deepable.map((screen) => completeScreen(screen, gatedFetch, resolvedLimits)));
+    const deepById = new Map();
+    let screensDeepFetched = 0;
+    let screensTruncated = 0;
+    let fetchCount = 0;
+    deepable.forEach((screen, index) => {
+        const outcome = outcomes[index];
+        if (outcome === undefined)
+            return;
+        deepById.set(idOf(screen), outcome.node);
+        if (outcome.deepFetched)
+            screensDeepFetched += 1;
+        if (outcome.truncated)
+            screensTruncated += 1;
+        fetchCount += outcome.fetchCount;
+    });
+    // When the root IS the single screen, the rebuild replaces the root itself with its deep version.
+    const document = rebuildWithDeepScreens(shallowRoot, deepById);
+    return {
+        document,
+        coverage: {
+            screenCount: screens.length,
+            screensDeepFetched,
+            screensTruncated,
+            nodeCount: countNodes(document),
+            fetchCount,
+            capped: deepable.length < screens.length,
+        },
+    };
+};

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

@@ -0,0 +1,31 @@
+import type { FigmaHttpPort } from "./figmaHttpPort.js";
+import type { FigmaRenderPort } from "./figmaRenderPort.js";
+import type { FigmaProvenance } from "./figmaConnector.js";
+import { type FigmaRetryPolicy, type FigmaRetrySleep } from "./figmaRetry.js";
+import type { FigmaSnapshot } from "./figmaSnapshotTypes.js";
+import type { QualityIntelligenceFigma } from "@oscharko-dev/keiko-quality-intelligence";
+export interface BuildFigmaSnapshotInput {
+    readonly ir: QualityIntelligenceFigma.ScreenIrResult;
+    readonly provenance: FigmaProvenance;
+    readonly token: string;
+    readonly imagesPort: FigmaHttpPort;
+    readonly renderPort: FigmaRenderPort;
+    /** `/v1/images` ids-per-call cap — bounds each render batch. */
+    readonly batchSize?: number;
+    readonly maxImageBytes?: number;
+    /** Max simultaneous byte-downloads — bounds burst on huge boards. */
+    readonly downloadConcurrency?: number;
+    /** Max screens rendered into image side-files; excess screens remain structural-only skips. */
+    readonly maxScreensRendered?: number;
+    /** Deterministic 429 backoff policy; defaults to {@link DEFAULT_FIGMA_RETRY_POLICY}. */
+    readonly retryPolicy?: FigmaRetryPolicy;
+    /** Injectable wait seam so tests assert the backoff schedule without real delays. */
+    readonly sleep?: FigmaRetrySleep;
+}
+/**
+ * Render the screens and assemble the immutable Figma Snapshot. Render failures degrade to a
+ * `skippedScreens` entry plus structural-only IR (partial render); a non-2xx `/v1/images` call is
+ * a hard coded error.
+ */
+export declare const buildFigmaSnapshot: (input: BuildFigmaSnapshotInput) => Promise<FigmaSnapshot>;
+//# sourceMappingURL=figmaSnapshotBuilder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"figmaSnapshotBuilder.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaSnapshotBuilder.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AAMzB,OAAO,KAAK,EAGV,aAAa,EAGd,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AAiBzF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,wBAAwB,CAAC,cAAc,CAAC;IACrD,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,gEAAgE;IAChE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,+FAA+F;IAC/F,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,wFAAwF;IACxF,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IACxC,qFAAqF;IACrF,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;CAClC;AAuSD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,uBAAuB,KAC7B,OAAO,CAAC,aAAa,CAyCvB,CAAC"}