@sun-asterisk/sungen 2.5.0 → 2.5.2

package/dist/tools/figma/figma-client-types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Shared types for Figma integration.
+ * Used by figma-auth.ts, figma-url-parser.ts, and REST client modules.
+ */
+/** Authentication configuration for Figma API. */
+export interface FigmaAuthConfig {
+    /** Personal Access Token — never log this value. */
+    pat: string;
+}
+/** Parsed reference to a specific Figma node. */
+export interface FigmaNodeRef {
+    /** Figma file key extracted from URL (alphanumeric, 20+ chars). */
+    fileKey: string;
+    /** Node ID in API form: "1:23" (colon-separated). Absent when URL has no node-id param. */
+    nodeId?: string;
+}
+/** Minimal /v1/me response shape used for PAT validation. */
+export interface FigmaMeResponse {
+    id: string;
+    email: string;
+    handle: string;
+}
+/** Result of a PAT validation call. */
+export interface FigmaAuthCheckResult {
+    valid: boolean;
+    handle?: string;
+    email?: string;
+    error?: string;
+}
+/** Raw Figma node as returned by the API (loose — unknown fields allowed). */
+export interface FigmaRawNode {
+    id: string;
+    name: string;
+    type: string;
+    /** Text content for TEXT nodes. */
+    characters?: string;
+    /** Component set variant properties. */
+    componentPropertyDefinitions?: Record<string, unknown>;
+    /** Variant property values for COMPONENT nodes. */
+    componentProperties?: Record<string, {
+        value: string;
+        type: string;
+    }>;
+    /** Bounding box from absoluteBoundingBox. */
+    absoluteBoundingBox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Child nodes. */
+    children?: FigmaRawNode[];
+    /** Allow any additional Figma fields. */
+    [key: string]: unknown;
+}
+/** Response from GET /v1/files/:key/nodes */
+export interface FigmaFileNodesResponse {
+    nodes: Record<string, {
+        document: FigmaRawNode;
+    } | null>;
+    /** Current file version ID. */
+    version: string;
+}
+/** Response from GET /v1/images/:key */
+export interface FigmaImageUrlsResponse {
+    /** Map of nodeId → signed S3 URL (transient — do not persist). */
+    images: Record<string, string | null>;
+    err: string | null;
+}
+/** Role inferred from component name suffix. */
+export type FigmaNodeRole = 'button' | 'textbox' | 'link' | 'image' | null;
+/** Pruned, minimal Figma node for downstream LLM / test generation. */
+export interface FilteredFigmaNode {
+    id: string;
+    name: string;
+    type: string;
+    /** Text content (TEXT nodes only). */
+    text?: string;
+    /** Component set name (COMPONENT / COMPONENT_SET nodes). */
+    componentName?: string;
+    /** Variant property map from componentProperties. */
+    variantProps?: Record<string, string>;
+    /** Inferred accessibility / interaction role. */
+    role?: FigmaNodeRole;
+    /** Bounding rectangle in file coordinates. */
+    boundingBox?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    children: FilteredFigmaNode[];
+}
+/** A single text label extracted from the node tree. */
+export interface FigmaTextLabel {
+    text: string;
+    nodePath: string;
+}
+/** A single variant definition extracted from a COMPONENT_SET. */
+export interface FigmaVariantDefinition {
+    nodeId: string;
+    name: string;
+    variantProps: Record<string, string>;
+}
+export interface FigmaImageOptions {
+    /** Render scale. Default 2. */
+    scale?: number;
+    /** Image format. Default 'png'. */
+    format?: 'png' | 'jpg' | 'svg' | 'pdf';
+}
+export type FigmaCacheKind = 'json' | 'raw' | `${number}x`;
+//# sourceMappingURL=figma-client-types.d.ts.map

package/dist/tools/figma/figma-client-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-client-types.d.ts","sourceRoot":"","sources":["../../../src/tools/figma/figma-client-types.ts"],"names":[],"mappings":"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"}

package/dist/tools/figma/figma-client-types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Shared types for Figma integration.
+ * Used by figma-auth.ts, figma-url-parser.ts, and REST client modules.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=figma-client-types.js.map

package/dist/tools/figma/figma-client-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-client-types.js","sourceRoot":"","sources":["../../../src/tools/figma/figma-client-types.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/dist/tools/figma/figma-errors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Typed error classes for Figma API failures.
+ * Each error carries an actionable remediation message for CLI output.
+ *
+ * Never include PAT values in error messages or remediation text.
+ */
+/** Common base for all Figma errors. */
+declare abstract class FigmaBaseError extends Error {
+    /** Human-readable instruction shown to the user on failure. */
+    readonly remediation: string;
+    constructor(message: string, remediation: string);
+}
+/**
+ * HTTP 401 — PAT is missing, expired, or invalid.
+ */
+export declare class FigmaAuthError extends FigmaBaseError {
+    constructor(message?: string);
+}
+/**
+ * HTTP 403 / 404 — PAT valid but insufficient access, or resource not found.
+ */
+export declare class FigmaAccessError extends FigmaBaseError {
+    readonly statusCode: 403 | 404;
+    constructor(statusCode: 403 | 404, message?: string);
+}
+/**
+ * HTTP 429 — Rate limited by Figma API.
+ */
+export declare class FigmaRateLimitError extends FigmaBaseError {
+    /** Seconds to wait before retrying, parsed from Retry-After header. */
+    readonly retryAfter: number;
+    readonly planTier?: string;
+    readonly bucket?: string;
+    readonly upgradeLink?: string;
+    constructor(retryAfter: number, message?: string, opts?: {
+        planTier?: string;
+        bucket?: string;
+        upgradeLink?: string;
+    });
+}
+/**
+ * Network / transport failure (timeout, DNS, stream error, etc.).
+ */
+export declare class FigmaNetworkError extends FigmaBaseError {
+    readonly cause: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export {};
+//# sourceMappingURL=figma-errors.d.ts.map

package/dist/tools/figma/figma-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-errors.d.ts","sourceRoot":"","sources":["../../../src/tools/figma/figma-errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,wCAAwC;AACxC,uBAAe,cAAe,SAAQ,KAAK;IACzC,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAKjD;AAMD;;GAEG;AACH,qBAAa,cAAe,SAAQ,cAAc;gBACpC,OAAO,SAAuC;CAM3D;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,cAAc;IAClD,QAAQ,CAAC,UAAU,EAAE,GAAG,GAAG,GAAG,CAAC;gBAEnB,UAAU,EAAE,GAAG,GAAG,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM;CAYpD;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,cAAc;IACrD,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;gBAG5B,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,EAChB,IAAI,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO;CAyB1E;AAgBD;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,cAAc;IACnD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAO7C"}

package/dist/tools/figma/figma-errors.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Typed error classes for Figma API failures.
+ * Each error carries an actionable remediation message for CLI output.
+ *
+ * Never include PAT values in error messages or remediation text.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FigmaNetworkError = exports.FigmaRateLimitError = exports.FigmaAccessError = exports.FigmaAuthError = void 0;
+// ---------------------------------------------------------------------------
+// Base
+// ---------------------------------------------------------------------------
+/** Common base for all Figma errors. */
+class FigmaBaseError extends Error {
+    constructor(message, remediation) {
+        super(message);
+        this.name = this.constructor.name;
+        this.remediation = remediation;
+    }
+}
+// ---------------------------------------------------------------------------
+// Concrete error types
+// ---------------------------------------------------------------------------
+/**
+ * HTTP 401 — PAT is missing, expired, or invalid.
+ */
+class FigmaAuthError extends FigmaBaseError {
+    constructor(message = 'Figma authentication failed (401).') {
+        super(message, 'Your Figma PAT is invalid or expired. Re-authenticate by running: sungen figma auth set');
+    }
+}
+exports.FigmaAuthError = FigmaAuthError;
+/**
+ * HTTP 403 / 404 — PAT valid but insufficient access, or resource not found.
+ */
+class FigmaAccessError extends FigmaBaseError {
+    constructor(statusCode, message) {
+        const defaultMsg = statusCode === 403
+            ? 'Figma access denied (403).'
+            : 'Figma resource not found (404).';
+        const remediation = statusCode === 403
+            ? 'Request view access to the Figma file, or ensure your PAT has the file:read scope.'
+            : 'Check the Figma URL — the file key or node ID may be incorrect.';
+        super(message ?? defaultMsg, remediation);
+        this.statusCode = statusCode;
+    }
+}
+exports.FigmaAccessError = FigmaAccessError;
+/**
+ * HTTP 429 — Rate limited by Figma API.
+ */
+class FigmaRateLimitError extends FigmaBaseError {
+    constructor(retryAfter, message, opts = {}) {
+        const human = formatRetryAfter(retryAfter);
+        const tierSuffix = opts.planTier ? ` (plan: ${opts.planTier}${opts.bucket ? `, bucket: ${opts.bucket}` : ''})` : '';
+        const msg = message ?? `Figma API rate limit hit (429)${tierSuffix}. Retry after ${human}.`;
+        // Multi-day Retry-After → almost certainly the Starter-tier daily quota.
+        const multiDay = retryAfter > 24 * 60 * 60;
+        const remediation = multiDay
+            ? [
+                `This is a Figma ${opts.planTier ?? 'Starter'}-tier daily/multi-day REST quota (not a transient burst).`,
+                'To continue today you must either:',
+                '  1) Re-run with a cached version: sungen add --screen <name> --figma <url>  (no --refresh)',
+                '     → reuses .sungen/figma-cache raw JSON; skips the /nodes API call entirely.',
+                opts.upgradeLink ? `  2) Upgrade the Figma account: ${opts.upgradeLink}` : '  2) Upgrade the Figma account to a paid tier.',
+                '  3) Wait for the quota window to reset.',
+            ].join('\n')
+            : 'Wait and retry, or reduce request frequency. In the meantime you can re-run without --refresh to reuse cached node JSON.';
+        super(msg, remediation);
+        this.retryAfter = retryAfter;
+        this.planTier = opts.planTier;
+        this.bucket = opts.bucket;
+        this.upgradeLink = opts.upgradeLink;
+    }
+}
+exports.FigmaRateLimitError = FigmaRateLimitError;
+/** Turn `369943` → `4d 6h 45m`. */
+function formatRetryAfter(secs) {
+    if (!Number.isFinite(secs) || secs <= 0)
+        return `${secs}s`;
+    const d = Math.floor(secs / 86400);
+    const h = Math.floor((secs % 86400) / 3600);
+    const m = Math.floor((secs % 3600) / 60);
+    const parts = [];
+    if (d)
+        parts.push(`${d}d`);
+    if (h)
+        parts.push(`${h}h`);
+    if (m && !d)
+        parts.push(`${m}m`);
+    if (!parts.length)
+        parts.push(`${secs}s`);
+    return `${parts.join(' ')} (${secs}s)`;
+}
+/**
+ * Network / transport failure (timeout, DNS, stream error, etc.).
+ */
+class FigmaNetworkError extends FigmaBaseError {
+    constructor(message, cause) {
+        super(message, 'Check your internet connection and verify api.figma.com is reachable. If the issue persists, retry.');
+        this.cause = cause;
+    }
+}
+exports.FigmaNetworkError = FigmaNetworkError;
+//# sourceMappingURL=figma-errors.js.map

package/dist/tools/figma/figma-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-errors.js","sourceRoot":"","sources":["../../../src/tools/figma/figma-errors.ts"],"names":[],"mappings":"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"}

package/dist/tools/figma/figma-image-downloader.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Download a Figma-signed image URL to disk.
+ *
+ * - Streams response body to a .tmp file then atomically renames to destPath.
+ * - Verifies the final file is non-zero bytes before committing.
+ * - Enforces a configurable timeout (default 30 s).
+ * - Surfaces all failures as FigmaNetworkError.
+ *
+ * Security: signed S3 URLs are consumed transiently — never logged.
+ */
+export interface DownloadOptions {
+    /** Request timeout in milliseconds. Default: 30 000. */
+    timeoutMs?: number;
+}
+/**
+ * Download the image at `url` and write it to `destPath`.
+ *
+ * Uses atomic write: streams to `<destPath>.tmp`, verifies size > 0,
+ * then renames to `destPath`. Cleans up .tmp on failure.
+ *
+ * @throws FigmaNetworkError on any network, timeout, or I/O failure.
+ * @throws FigmaNetworkError when the downloaded file has zero bytes.
+ */
+export declare function downloadToPath(url: string, destPath: string, options?: DownloadOptions): Promise<void>;
+//# sourceMappingURL=figma-image-downloader.d.ts.map

package/dist/tools/figma/figma-image-downloader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-image-downloader.d.ts","sourceRoot":"","sources":["../../../src/tools/figma/figma-image-downloader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAgEf"}

package/dist/tools/figma/figma-image-downloader.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Download a Figma-signed image URL to disk.
+ *
+ * - Streams response body to a .tmp file then atomically renames to destPath.
+ * - Verifies the final file is non-zero bytes before committing.
+ * - Enforces a configurable timeout (default 30 s).
+ * - Surfaces all failures as FigmaNetworkError.
+ *
+ * Security: signed S3 URLs are consumed transiently — never logged.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.downloadToPath = downloadToPath;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const promises_1 = require("node:stream/promises");
+const node_stream_1 = require("node:stream");
+const figma_errors_1 = require("./figma-errors");
+/**
+ * Download the image at `url` and write it to `destPath`.
+ *
+ * Uses atomic write: streams to `<destPath>.tmp`, verifies size > 0,
+ * then renames to `destPath`. Cleans up .tmp on failure.
+ *
+ * @throws FigmaNetworkError on any network, timeout, or I/O failure.
+ * @throws FigmaNetworkError when the downloaded file has zero bytes.
+ */
+async function downloadToPath(url, destPath, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 30000;
+    const tmpPath = `${destPath}.tmp`;
+    // Ensure destination directory exists
+    const dir = path.dirname(destPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetch(url, { signal: controller.signal });
+    }
+    catch (cause) {
+        clearTimeout(timer);
+        cleanupTmp(tmpPath);
+        const isTimeout = cause instanceof Error && cause.name === 'AbortError';
+        throw new figma_errors_1.FigmaNetworkError(isTimeout
+            ? `Image download timed out after ${timeoutMs}ms.`
+            : 'Image download failed due to a network error.', cause);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        cleanupTmp(tmpPath);
+        throw new figma_errors_1.FigmaNetworkError(`Image download received HTTP ${response.status}.`);
+    }
+    if (!response.body) {
+        cleanupTmp(tmpPath);
+        throw new figma_errors_1.FigmaNetworkError('Image download response has no body.');
+    }
+    // Stream to .tmp file
+    const writeStream = fs.createWriteStream(tmpPath);
+    try {
+        await (0, promises_1.pipeline)(node_stream_1.Readable.fromWeb(response.body), writeStream);
+    }
+    catch (cause) {
+        cleanupTmp(tmpPath);
+        throw new figma_errors_1.FigmaNetworkError('Failed to write image to disk.', cause);
+    }
+    // Verify non-zero file size
+    const stat = fs.statSync(tmpPath);
+    if (stat.size === 0) {
+        cleanupTmp(tmpPath);
+        throw new figma_errors_1.FigmaNetworkError('Downloaded image file is empty (0 bytes).');
+    }
+    // Atomic rename
+    try {
+        fs.renameSync(tmpPath, destPath);
+    }
+    catch (cause) {
+        cleanupTmp(tmpPath);
+        throw new figma_errors_1.FigmaNetworkError('Failed to finalize image file on disk.', cause);
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function cleanupTmp(tmpPath) {
+    try {
+        if (fs.existsSync(tmpPath))
+            fs.unlinkSync(tmpPath);
+    }
+    catch {
+        // Best-effort cleanup — ignore errors
+    }
+}
+//# sourceMappingURL=figma-image-downloader.js.map

package/dist/tools/figma/figma-image-downloader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-image-downloader.js","sourceRoot":"","sources":["../../../src/tools/figma/figma-image-downloader.ts"],"names":[],"mappings":"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"}

package/dist/tools/figma/figma-node-filter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Prune raw Figma node trees to a minimal shape for LLM / test-generation use.
+ *
+ * Drops: vectors, fills, effects, strokes, constraints, style references.
+ * Keeps: id, name, type, text content, component/variant metadata, bounding box, children.
+ *
+ * Role inference: component name suffix → button | textbox | link | image | null.
+ */
+import type { FilteredFigmaNode, FigmaTextLabel, FigmaVariantDefinition } from './figma-client-types';
+/**
+ * Validate and filter a raw Figma node tree.
+ *
+ * @throws ZodError when the input fails basic structural validation.
+ */
+export declare function filterFigmaNode(rawNode: unknown): FilteredFigmaNode;
+/**
+ * Recursively collect all text labels from a filtered node tree.
+ * Returns a flat list of { text, nodePath } pairs.
+ */
+export declare function extractTextLabels(node: FilteredFigmaNode, _path?: string): FigmaTextLabel[];
+/**
+ * Extract variant definitions from a COMPONENT_SET node.
+ * Each direct child COMPONENT represents one variant combination.
+ */
+export declare function extractVariants(componentSetNode: FilteredFigmaNode): FigmaVariantDefinition[];
+//# sourceMappingURL=figma-node-filter.d.ts.map

package/dist/tools/figma/figma-node-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-node-filter.d.ts","sourceRoot":"","sources":["../../../src/tools/figma/figma-node-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,iBAAiB,EAEjB,cAAc,EACd,sBAAsB,EACvB,MAAM,sBAAsB,CAAC;AAgI9B;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,CASnE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,iBAAiB,EACvB,KAAK,SAAK,GACT,cAAc,EAAE,CAalB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,gBAAgB,EAAE,iBAAiB,GAClC,sBAAsB,EAAE,CAU1B"}

package/dist/tools/figma/figma-node-filter.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * Prune raw Figma node trees to a minimal shape for LLM / test-generation use.
+ *
+ * Drops: vectors, fills, effects, strokes, constraints, style references.
+ * Keeps: id, name, type, text content, component/variant metadata, bounding box, children.
+ *
+ * Role inference: component name suffix → button | textbox | link | image | null.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterFigmaNode = filterFigmaNode;
+exports.extractTextLabels = extractTextLabels;
+exports.extractVariants = extractVariants;
+const zod_1 = require("zod");
+// ---------------------------------------------------------------------------
+// Zod schema — loose, unknown fields allowed via passthrough
+// ---------------------------------------------------------------------------
+// Zod v4: z.record() requires explicit key schema (z.string())
+const RawNodeSchema = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string(),
+    type: zod_1.z.string(),
+    characters: zod_1.z.string().optional(),
+    componentPropertyDefinitions: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    componentProperties: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.object({ value: zod_1.z.string(), type: zod_1.z.string() }))
+        .optional(),
+    absoluteBoundingBox: zod_1.z
+        .object({ x: zod_1.z.number(), y: zod_1.z.number(), width: zod_1.z.number(), height: zod_1.z.number() })
+        .optional(),
+    children: zod_1.z.array(zod_1.z.lazy(() => RawNodeSchema)).optional(),
+})
+    .passthrough();
+// ---------------------------------------------------------------------------
+// Role inference
+// ---------------------------------------------------------------------------
+const ROLE_SUFFIX_MAP = [
+    [/button$/i, 'button'],
+    [/input|textbox|text.?field|text.?input/i, 'textbox'],
+    [/link$/i, 'link'],
+    [/icon|image|img|illustration/i, 'image'],
+];
+function inferRole(name) {
+    for (const [pattern, role] of ROLE_SUFFIX_MAP) {
+        if (pattern.test(name))
+            return role;
+    }
+    return null;
+}
+// Node types to skip entirely (leaf-only visual noise)
+const SKIP_TYPES = new Set([
+    'VECTOR',
+    'STAR',
+    'POLYGON',
+    'BOOLEAN_OPERATION',
+    'ELLIPSE',
+    'LINE',
+]);
+// ---------------------------------------------------------------------------
+// Core filter
+// ---------------------------------------------------------------------------
+/**
+ * Recursively prune a raw Figma node to the minimal FilteredFigmaNode shape.
+ * Returns null when the node type should be dropped entirely.
+ *
+ * @param raw     Validated (but loosely typed) raw Figma node object.
+ * @param maxDepth  Maximum recursion depth (default 30 — safety guard).
+ */
+function filterNode(raw, depth = 0, maxDepth = 30) {
+    const id = raw['id'];
+    const name = raw['name'];
+    const type = raw['type'];
+    if (SKIP_TYPES.has(type))
+        return null;
+    if (depth > maxDepth)
+        return null;
+    // Bounding box
+    let boundingBox;
+    const bb = raw['absoluteBoundingBox'];
+    if (bb) {
+        boundingBox = { x: bb.x, y: bb.y, w: bb.width, h: bb.height };
+    }
+    // Text content
+    const text = type === 'TEXT' ? raw['characters'] : undefined;
+    // Component / variant metadata
+    let componentName;
+    let variantProps;
+    if (type === 'COMPONENT' || type === 'COMPONENT_SET' || type === 'INSTANCE') {
+        componentName = name;
+        const props = raw['componentProperties'];
+        if (props) {
+            variantProps = Object.fromEntries(Object.entries(props).map(([k, v]) => [k, v.value]));
+        }
+    }
+    // Role (only meaningful for component-like nodes)
+    const role = componentName != null ? inferRole(name) : null;
+    // Recurse into children
+    const rawChildren = raw['children'] ?? [];
+    const children = rawChildren
+        .map((child) => filterNode(child, depth + 1, maxDepth))
+        .filter((n) => n !== null);
+    const node = { id, name, type, children };
+    if (text !== undefined)
+        node.text = text;
+    if (componentName !== undefined)
+        node.componentName = componentName;
+    if (variantProps !== undefined)
+        node.variantProps = variantProps;
+    if (role)
+        node.role = role;
+    if (boundingBox !== undefined)
+        node.boundingBox = boundingBox;
+    return node;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Validate and filter a raw Figma node tree.
+ *
+ * @throws ZodError when the input fails basic structural validation.
+ */
+function filterFigmaNode(rawNode) {
+    const validated = RawNodeSchema.parse(rawNode);
+    const result = filterNode(validated);
+    // Root node should never be null (root type is never in SKIP_TYPES)
+    if (!result) {
+        const id = rawNode['id'] ?? 'unknown';
+        throw new Error(`Root node (id=${id}) was filtered out — unexpected type.`);
+    }
+    return result;
+}
+/**
+ * Recursively collect all text labels from a filtered node tree.
+ * Returns a flat list of { text, nodePath } pairs.
+ */
+function extractTextLabels(node, _path = '') {
+    const currentPath = _path ? `${_path} > ${node.name}` : node.name;
+    const labels = [];
+    if (node.text) {
+        labels.push({ text: node.text, nodePath: currentPath });
+    }
+    for (const child of node.children) {
+        labels.push(...extractTextLabels(child, currentPath));
+    }
+    return labels;
+}
+/**
+ * Extract variant definitions from a COMPONENT_SET node.
+ * Each direct child COMPONENT represents one variant combination.
+ */
+function extractVariants(componentSetNode) {
+    if (componentSetNode.type !== 'COMPONENT_SET')
+        return [];
+    return componentSetNode.children
+        .filter((child) => child.type === 'COMPONENT')
+        .map((child) => ({
+        nodeId: child.id,
+        name: child.name,
+        variantProps: child.variantProps ?? {},
+    }));
+}
+//# sourceMappingURL=figma-node-filter.js.map