@rnsk/toolkits 0.0.6 → 0.0.8

package/dist/toolkits/figma/tools/detect-background.js

@@ -0,0 +1,124 @@
+// @ts-nocheck
+import { tool } from 'ai';
+import { z } from 'zod';
+import { figmaRequest, figmaTokenField } from './client.js';
+function contains(outer, inner) {
+    return (outer.x <= inner.x &&
+        outer.y <= inner.y &&
+        outer.x + outer.width >= inner.x + inner.width &&
+        outer.y + outer.height >= inner.y + inner.height);
+}
+function overlaps(a, b) {
+    return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+}
+function flatten(node, depth, parentId, out, counter) {
+    const entry = {
+        id: String(node.id ?? ''),
+        name: String(node.name ?? ''),
+        type: String(node.type ?? ''),
+        index: counter.n++,
+        depth,
+        parentId,
+    };
+    const box = node.absoluteBoundingBox;
+    if (box && typeof box.x === 'number')
+        entry.bounds = box;
+    if (Array.isArray(node.fills))
+        entry.fills = node.fills;
+    out.push(entry);
+    for (const child of (node.children ?? [])) {
+        flatten(child, depth + 1, entry.id, out, counter);
+    }
+}
+export const detectBackground = tool({
+    description: 'Finds background candidates behind target nodes using geometry (containment/overlap), z-order, fills, and naming. Returns candidates with 0-1 confidence and reasons.',
+    inputSchema: z.object({
+        figmaToken: figmaTokenField,
+        fileKey: z.string().describe('Design file key (FigJam/Slides not supported)'),
+        targetNodeIds: z.array(z.string()).min(1).describe("Node IDs to find backgrounds for, e.g. ['1:2']"),
+        searchDepth: z.number().min(1).max(10).optional().describe('Ancestor levels to search (default 3)'),
+    }),
+    execute: async ({ figmaToken, fileKey, targetNodeIds, searchDepth }) => {
+        try {
+            const depth = searchDepth ?? 3;
+            const result = await figmaRequest(figmaToken, `/v1/files/${fileKey}`, { query: { depth: depth + 2 } });
+            if (!result.ok)
+                return { error: 'Failed to fetch file for background detection', details: result.error };
+            const doc = result.data.document;
+            if (!doc)
+                return { error: 'No document in file response' };
+            const flat = [];
+            flatten(doc, 0, undefined, flat, { n: 0 });
+            const byId = new Map(flat.map((n) => [n.id, n]));
+            const backgrounds = {};
+            for (const targetId of targetNodeIds) {
+                const target = byId.get(targetId);
+                if (!target?.bounds) {
+                    backgrounds[targetId] = [];
+                    continue;
+                }
+                const ancestors = new Set();
+                let current = target;
+                for (let i = 0; i < depth && current?.parentId; i++) {
+                    const parent = byId.get(current.parentId);
+                    if (!parent)
+                        break;
+                    ancestors.add(parent.id);
+                    current = parent;
+                }
+                const candidates = [];
+                for (const node of flat) {
+                    if (node.id === targetId || !node.bounds)
+                        continue;
+                    if (!ancestors.has(node.id) && node.parentId !== target.parentId)
+                        continue;
+                    if (node.index > target.index)
+                        continue; // painted after target → in front
+                    let confidence = 0;
+                    const reasons = [];
+                    if (contains(node.bounds, target.bounds)) {
+                        confidence += 0.45;
+                        reasons.push('contains target bounds');
+                    }
+                    else if (overlaps(node.bounds, target.bounds)) {
+                        confidence += 0.2;
+                        reasons.push('overlaps target bounds');
+                    }
+                    else {
+                        continue;
+                    }
+                    if (node.fills && node.fills.length > 0) {
+                        confidence += 0.2;
+                        reasons.push('has fills');
+                    }
+                    if (/background|^bg\b/i.test(node.name)) {
+                        confidence += 0.25;
+                        reasons.push('background-like name');
+                    }
+                    if (['RECTANGLE', 'FRAME'].includes(node.type)) {
+                        confidence += 0.1;
+                        reasons.push(`type ${node.type}`);
+                    }
+                    candidates.push({
+                        node_id: node.id,
+                        name: node.name,
+                        type: node.type,
+                        confidence: Math.min(1, Math.round(confidence * 100) / 100),
+                        reason: reasons.join('; '),
+                        bounds: node.bounds,
+                    });
+                }
+                candidates.sort((a, b) => b.confidence - a.confidence);
+                backgrounds[targetId] = candidates;
+            }
+            return { backgrounds };
+        }
+        catch (error) {
+            return {
+                error: 'Error detecting backgrounds',
+                message: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    },
+});
+//# sourceMappingURL=detect-background.js.map

package/dist/toolkits/figma/tools/discover-figma-resources.d.ts

@@ -0,0 +1,38 @@
+export interface NodeInfo {
+    id: string;
+    name: string;
+    type: string;
+    path: string;
+}
+export declare const discoverFigmaResources: import("ai").Tool<{
+    figmaToken: string;
+    teamId?: string | undefined;
+    projectId?: string | undefined;
+    fileKey?: string | undefined;
+    figmaUrl?: string | undefined;
+    maxDepth?: number | undefined;
+}, {
+    extracted_ids: {
+        fileKey?: string;
+        nodeId?: string;
+        teamId?: string;
+        projectId?: string;
+    };
+    projects: Record<string, unknown>[];
+    files: Record<string, unknown>[];
+    nodes: NodeInfo[];
+    errors: string[];
+    instructions: string[];
+    error?: undefined;
+    message?: undefined;
+} | {
+    error: string;
+    message: string;
+    extracted_ids?: undefined;
+    projects?: undefined;
+    files?: undefined;
+    nodes?: undefined;
+    errors?: undefined;
+    instructions?: undefined;
+}>;
+//# sourceMappingURL=discover-figma-resources.d.ts.map

package/dist/toolkits/figma/tools/discover-figma-resources.js

@@ -0,0 +1,99 @@
+// @ts-nocheck
+import { tool } from 'ai';
+import { z } from 'zod';
+import { figmaRequest, figmaTokenField } from './client.js';
+function parseFigmaUrl(url) {
+    const out = {};
+    const fileMatch = url.match(/figma\.com\/(?:file|design|board|proto|slides)\/([A-Za-z0-9]+)/);
+    if (fileMatch)
+        out.fileKey = fileMatch[1];
+    const nodeMatch = url.match(/[?&]node-id=([\d-]+)/);
+    if (nodeMatch)
+        out.nodeId = nodeMatch[1].replace(/-/g, ':');
+    const teamMatch = url.match(/figma\.com\/files\/team\/(\d+)/);
+    if (teamMatch)
+        out.teamId = teamMatch[1];
+    const projectMatch = url.match(/[?&]project(?:_|-)id=(\d+)/);
+    if (projectMatch)
+        out.projectId = projectMatch[1];
+    return out;
+}
+function collectNodes(node, path, depth, maxDepth, out) {
+    const name = String(node.name ?? '');
+    const current = path ? `${path}/${name}` : name;
+    if (node.id)
+        out.push({ id: String(node.id), name, type: String(node.type ?? ''), path: current });
+    if (depth >= maxDepth)
+        return;
+    for (const child of (node.children ?? [])) {
+        collectNodes(child, current, depth + 1, maxDepth, out);
+    }
+}
+export const discoverFigmaResources = tool({
+    description: 'Extracts file/node/team IDs from any Figma URL and traverses team → projects → files → nodes. Shallow by default (maxDepth 2-3); target FRAME/CANVAS IDs for big files.',
+    inputSchema: z.object({
+        figmaToken: figmaTokenField,
+        figmaUrl: z.string().optional().describe('Any Figma URL (/file/, /design/, /board/, /proto/, /slides/, team)'),
+        teamId: z.string().optional().describe('Team ID to list projects for'),
+        projectId: z.string().optional().describe('Project ID to list files for'),
+        fileKey: z.string().optional().describe('File key to list nodes for'),
+        maxDepth: z.number().optional().describe('Node traversal depth (default 2)'),
+    }),
+    execute: async ({ figmaToken, figmaUrl, teamId, projectId, fileKey, maxDepth }) => {
+        try {
+            const errors = [];
+            const instructions = [];
+            const extracted = figmaUrl ? parseFigmaUrl(figmaUrl) : {};
+            const effTeamId = teamId ?? extracted.teamId;
+            const effProjectId = projectId ?? extracted.projectId;
+            const effFileKey = fileKey ?? extracted.fileKey;
+            const projects = [];
+            const files = [];
+            const nodes = [];
+            if (effTeamId && !effProjectId && !effFileKey) {
+                const res = await figmaRequest(figmaToken, `/v1/teams/${effTeamId}/projects`);
+                if (!res.ok)
+                    errors.push(`Failed to list team projects: ${JSON.stringify(res.error)}`);
+                else {
+                    const data = res.data;
+                    for (const p of data.projects ?? [])
+                        projects.push({ id: p.id, name: p.name });
+                    instructions.push('Pass a project_id to list its files.');
+                }
+            }
+            if (effProjectId) {
+                const res = await figmaRequest(figmaToken, `/v1/projects/${effProjectId}/files`);
+                if (!res.ok)
+                    errors.push(`Failed to list project files: ${JSON.stringify(res.error)}`);
+                else {
+                    const data = res.data;
+                    for (const f of data.files ?? [])
+                        files.push(f);
+                    instructions.push('Pass a file_key to list its nodes.');
+                }
+            }
+            if (effFileKey) {
+                const res = await figmaRequest(figmaToken, `/v1/files/${effFileKey}`, { query: { depth: maxDepth ?? 2 } });
+                if (!res.ok)
+                    errors.push(`Failed to fetch file nodes: ${JSON.stringify(res.error)}`);
+                else {
+                    const doc = res.data.document;
+                    if (doc)
+                        collectNodes(doc, '', 0, maxDepth ?? 2, nodes);
+                    instructions.push('Use node IDs with getFileNodes, detectBackground, or image rendering.');
+                }
+            }
+            if (!figmaUrl && !teamId && !projectId && !fileKey) {
+                instructions.push('Provide figmaUrl, teamId, projectId, or fileKey to start discovery.');
+            }
+            return { extracted_ids: extracted, projects, files, nodes, errors, instructions };
+        }
+        catch (error) {
+            return {
+                error: 'Error discovering Figma resources',
+                message: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    },
+});
+//# sourceMappingURL=discover-figma-resources.js.map

package/dist/toolkits/figma/tools/download-figma-images.d.ts

@@ -0,0 +1,26 @@
+export declare const downloadFigmaImages: import("ai").Tool<{
+    images: {
+        fileName: string;
+        nodeId: string;
+        format?: string | undefined;
+    }[];
+    figmaToken: string;
+    fileKey: string;
+    scale?: number | undefined;
+    svgIncludeId?: boolean | undefined;
+    svgOutlineText?: boolean | undefined;
+    svgSimplifyStroke?: boolean | undefined;
+}, {
+    downloaded_images: Record<string, unknown>[];
+    successful_count: number;
+    failed_count: number;
+    error?: undefined;
+    message?: undefined;
+} | {
+    error: string;
+    message: string;
+    downloaded_images?: undefined;
+    successful_count?: undefined;
+    failed_count?: undefined;
+}>;
+//# sourceMappingURL=download-figma-images.d.ts.map

package/dist/toolkits/figma/tools/download-figma-images.js

@@ -0,0 +1,86 @@
+// @ts-nocheck
+import { tool } from 'ai';
+import { z } from 'zod';
+import { figmaRequest, figmaTokenField } from './client.js';
+const MIME_BY_FORMAT = { png: 'image/png', jpg: 'image/jpeg', svg: 'image/svg+xml', pdf: 'application/pdf' };
+export const downloadFigmaImages = tool({
+    description: 'Renders nodes and downloads the bytes (base64) in PNG/SVG/JPG/PDF. Find node IDs via getFileJson or node-id in URLs. Render URLs expire fast — bytes are fetched immediately.',
+    inputSchema: z.object({
+        figmaToken: figmaTokenField,
+        fileKey: z.string().describe('File key from the file URL'),
+        images: z.array(z.object({
+            nodeId: z.string().describe("Node ID, e.g. '1:2'"),
+            fileName: z.string().describe("Output filename, e.g. 'logo.png'"),
+            format: z.string().optional().describe("png (default), svg, jpg, or pdf"),
+        })).min(1),
+        scale: z.number().optional().describe('PNG/JPG scale 0.01-4 (default 2)'),
+        svgIncludeId: z.boolean().optional(),
+        svgOutlineText: z.boolean().optional(),
+        svgSimplifyStroke: z.boolean().optional(),
+    }),
+    execute: async ({ figmaToken, fileKey, images, scale, svgIncludeId, svgOutlineText, svgSimplifyStroke }) => {
+        try {
+            const byFormat = new Map();
+            for (const img of images) {
+                const fmt = (img.format ?? 'png').toLowerCase();
+                const list = byFormat.get(fmt) ?? [];
+                list.push(img);
+                byFormat.set(fmt, list);
+            }
+            const downloaded = [];
+            for (const [format, group] of byFormat) {
+                const render = await figmaRequest(figmaToken, `/v1/files/${fileKey}/images`, {
+                    query: {
+                        ids: group.map((g) => g.nodeId).join(','),
+                        format,
+                        scale: format === 'svg' || format === 'pdf' ? undefined : (scale ?? 2),
+                        svg_include_id: svgIncludeId,
+                        svg_outline_text: svgOutlineText,
+                        svg_simplify_stroke: svgSimplifyStroke,
+                    },
+                });
+                if (!render.ok) {
+                    for (const g of group) {
+                        downloaded.push({ node_id: g.nodeId, file_name: g.fileName, success: false, error: JSON.stringify(render.error) });
+                    }
+                    continue;
+                }
+                const urlMap = render.data.images ?? {};
+                for (const g of group) {
+                    const url = urlMap[g.nodeId];
+                    if (!url) {
+                        downloaded.push({ node_id: g.nodeId, file_name: g.fileName, success: false, error: 'Render returned null for node' });
+                        continue;
+                    }
+                    try {
+                        const bytes = await fetch(url).then((r) => {
+                            if (!r.ok)
+                                throw new Error(`HTTP ${r.status}`);
+                            return r.arrayBuffer();
+                        });
+                        downloaded.push({
+                            node_id: g.nodeId,
+                            file_name: g.fileName,
+                            success: true,
+                            mimetype: MIME_BY_FORMAT[format] ?? 'application/octet-stream',
+                            content_base64: Buffer.from(bytes).toString('base64'),
+                            source_url: url,
+                        });
+                    }
+                    catch (fetchError) {
+                        downloaded.push({ node_id: g.nodeId, file_name: g.fileName, success: false, error: fetchError instanceof Error ? fetchError.message : 'Download failed', source_url: url });
+                    }
+                }
+            }
+            const successfulCount = downloaded.filter((d) => d.success).length;
+            return { downloaded_images: downloaded, successful_count: successfulCount, failed_count: downloaded.length - successfulCount };
+        }
+        catch (error) {
+            return {
+                error: 'Error downloading Figma images',
+                message: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    },
+});
+//# sourceMappingURL=download-figma-images.js.map

package/dist/toolkits/figma/tools/extract-design-tokens.d.ts

@@ -0,0 +1,46 @@
+export declare const extractDesignTokens: import("ai").Tool<{
+    figmaToken: string;
+    fileKey: string;
+    includeVariables?: boolean | undefined;
+    includeLocalStyles?: boolean | undefined;
+    extractFromNodes?: boolean | undefined;
+}, {
+    error: string;
+    details: any;
+    colors?: undefined;
+    typography?: undefined;
+    spacing?: undefined;
+    border_radius?: undefined;
+    shadows?: undefined;
+    total_tokens?: undefined;
+    sources?: undefined;
+    message?: undefined;
+} | {
+    colors: {
+        name: string;
+        value: string;
+        source: string;
+        usage_count: number;
+    }[];
+    typography: Record<string, unknown>[];
+    spacing: Record<string, unknown>[];
+    border_radius: Record<string, unknown>[];
+    shadows: Record<string, unknown>[];
+    total_tokens: number;
+    sources: Record<string, number>;
+    error?: undefined;
+    details?: undefined;
+    message?: undefined;
+} | {
+    error: string;
+    message: string;
+    details?: undefined;
+    colors?: undefined;
+    typography?: undefined;
+    spacing?: undefined;
+    border_radius?: undefined;
+    shadows?: undefined;
+    total_tokens?: undefined;
+    sources?: undefined;
+}>;
+//# sourceMappingURL=extract-design-tokens.d.ts.map

package/dist/toolkits/figma/tools/extract-design-tokens.js

@@ -0,0 +1,146 @@
+// @ts-nocheck
+import { tool } from 'ai';
+import { z } from 'zod';
+import { figmaRequest, figmaTokenField } from './client.js';
+function rgbaToHex(color) {
+    const to255 = (v) => Math.round(Number(v ?? 0) * 255);
+    const hex = [to255(color.r), to255(color.g), to255(color.b)].map((v) => v.toString(16).padStart(2, '0')).join('');
+    return `#${hex}`;
+}
+function walk(node, visit) {
+    visit(node);
+    for (const child of (node.children ?? []))
+        walk(child, visit);
+}
+export const extractDesignTokens = tool({
+    description: 'Extracts colors, typography, spacing, radii, and shadows from styles, variables (optional), and node properties. Only style/variable-backed values are captured. Feed output into designTokensToTailwind.',
+    inputSchema: z.object({
+        figmaToken: figmaTokenField,
+        fileKey: z.string().describe('File key from the file URL'),
+        includeVariables: z.boolean().optional().describe('Include variables (use getLocalVariables for full mode/alias coverage)'),
+        includeLocalStyles: z.boolean().optional().describe('Include local styles (default true)'),
+        extractFromNodes: z.boolean().optional().describe('Extract from node properties (default true)'),
+    }),
+    execute: async ({ figmaToken, fileKey, includeVariables, includeLocalStyles, extractFromNodes }) => {
+        try {
+            const colors = new Map();
+            const typography = new Map();
+            const spacing = new Map();
+            const borderRadius = new Map();
+            const shadows = new Map();
+            const sources = { style: 0, variable: 0, extracted: 0 };
+            const bump = (map, key) => {
+                const entry = map.get(key);
+                if (entry)
+                    entry.usage_count += 1;
+            };
+            if (includeLocalStyles !== false) {
+                const res = await figmaRequest(figmaToken, `/v1/files/${fileKey}/styles`);
+                if (res.ok) {
+                    const styles = (res.data.meta?.styles ?? []);
+                    for (const s of styles) {
+                        sources.style += 1;
+                        const name = String(s.name ?? 'style');
+                        if (s.style_type === 'TEXT') {
+                            typography.set(name, { name, source: 'style', usage_count: 0 });
+                        }
+                        else {
+                            colors.set(name, { name, value: '#000000', source: 'style', usage_count: 0 });
+                        }
+                    }
+                }
+            }
+            if (includeVariables === true) {
+                const res = await figmaRequest(figmaToken, `/v1/files/${fileKey}/variables/local`);
+                if (res.ok) {
+                    const meta = res.data.meta;
+                    for (const v of Object.values(meta?.variables ?? {})) {
+                        sources.variable += 1;
+                        const name = String(v.name ?? 'variable');
+                        if (v.resolvedType === 'COLOR') {
+                            const modes = (v.valuesByMode ?? {});
+                            const first = Object.values(modes)[0];
+                            colors.set(name, { name, value: first && typeof first === 'object' ? rgbaToHex(first) : '#000000', source: 'variable', usage_count: 0 });
+                        }
+                    }
+                }
+            }
+            if (extractFromNodes !== false) {
+                const res = await figmaRequest(figmaToken, `/v1/files/${fileKey}`, { query: { depth: 4 } });
+                if (!res.ok)
+                    return { error: 'Failed to fetch file for token extraction', details: res.error };
+                const doc = res.data.document;
+                if (doc) {
+                    walk(doc, (n) => {
+                        for (const fill of (n.fills ?? [])) {
+                            if (fill.type === 'SOLID' && fill.color && fill.visible !== false) {
+                                const hex = rgbaToHex(fill.color);
+                                const existing = colors.get(hex);
+                                if (existing)
+                                    bump(colors, hex);
+                                else {
+                                    colors.set(hex, { name: hex, value: hex, source: 'extracted', usage_count: 1 });
+                                    sources.extracted += 1;
+                                }
+                            }
+                        }
+                        if (typeof n.cornerRadius === 'number' && n.cornerRadius > 0) {
+                            const key = `radius-${n.cornerRadius}`;
+                            const existing = borderRadius.get(key);
+                            if (existing)
+                                existing.usage_count += 1;
+                            else {
+                                borderRadius.set(key, { name: key, value: n.cornerRadius, source: 'extracted', usage_count: 1 });
+                                sources.extracted += 1;
+                            }
+                        }
+                        const style = n.style;
+                        if (n.type === 'TEXT' && style?.fontFamily) {
+                            const key = `${style.fontFamily}-${style.fontSize ?? ''}-${style.fontWeight ?? ''}`;
+                            const existing = typography.get(key);
+                            if (existing)
+                                existing.usage_count += 1;
+                            else {
+                                typography.set(key, { name: String(style.fontFamily), source: 'extracted', font_size: style.fontSize, font_family: style.fontFamily, font_weight: style.fontWeight, line_height: style.lineHeight, letter_spacing: style.letterSpacing, usage_count: 1 });
+                                sources.extracted += 1;
+                            }
+                        }
+                        for (const effect of (n.effects ?? [])) {
+                            if ((effect.type === 'DROP_SHADOW' || effect.type === 'INNER_SHADOW') && effect.visible !== false) {
+                                const key = `shadow-${effect.offset?.x ?? 0}-${effect.offset?.y ?? 0}-${effect.radius ?? 0}`;
+                                const existing = shadows.get(key);
+                                if (existing)
+                                    existing.usage_count += 1;
+                                else {
+                                    shadows.set(key, { name: key, source: 'extracted', shadows: [{ type: effect.type, color: effect.color, offset: effect.offset, radius: effect.radius, visible: true }], usage_count: 1 });
+                                    sources.extracted += 1;
+                                }
+                            }
+                        }
+                    });
+                }
+            }
+            const colorList = [...colors.values()];
+            const typoList = [...typography.values()];
+            const spacingList = [...spacing.values()];
+            const radiusList = [...borderRadius.values()];
+            const shadowList = [...shadows.values()];
+            return {
+                colors: colorList,
+                typography: typoList,
+                spacing: spacingList,
+                border_radius: radiusList,
+                shadows: shadowList,
+                total_tokens: colorList.length + typoList.length + spacingList.length + radiusList.length + shadowList.length,
+                sources,
+            };
+        }
+        catch (error) {
+            return {
+                error: 'Error extracting design tokens',
+                message: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    },
+});
+//# sourceMappingURL=extract-design-tokens.js.map

package/dist/toolkits/figma/tools/extract-prototype-interactions.d.ts

@@ -0,0 +1,38 @@
+export declare const extractPrototypeInteractions: import("ai").Tool<{
+    figmaToken: string;
+    fileKey: string;
+    analyzeComponents?: boolean | undefined;
+    includeAnimations?: boolean | undefined;
+}, {
+    error: string;
+    details: any;
+    interactions?: undefined;
+    component_states?: undefined;
+    prototype_flows?: undefined;
+    total_interactions?: undefined;
+    animation_types_used?: undefined;
+    message?: undefined;
+} | {
+    interactions: Record<string, unknown>[];
+    component_states: Record<string, unknown>[];
+    prototype_flows: {
+        name: string;
+        starting_node_id: string;
+        nodes_in_flow: string[];
+    }[];
+    total_interactions: number;
+    animation_types_used: string[];
+    error?: undefined;
+    details?: undefined;
+    message?: undefined;
+} | {
+    error: string;
+    message: string;
+    details?: undefined;
+    interactions?: undefined;
+    component_states?: undefined;
+    prototype_flows?: undefined;
+    total_interactions?: undefined;
+    animation_types_used?: undefined;
+}>;
+//# sourceMappingURL=extract-prototype-interactions.d.ts.map