pi-mono-all 1.0.0

package/node_modules/pi-mono-figma/src/figma-implementation.ts

@@ -0,0 +1,264 @@
+import type { FigmaNodeSummary } from "./figma-summarizer.js";
+import type { FigmaTokenMap } from "./figma-tokens.js";
+
+export type FigmaFramework = "react" | "html" | "vue" | "angular" | "react-native";
+export type FigmaStyling = "css" | "css-modules" | "styled-components" | "tailwind" | "inline";
+
+export interface FigmaImplementationOptions {
+	framework?: FigmaFramework;
+	styling?: FigmaStyling;
+	resolveTokens?: boolean;
+	includeCodeSnippets?: boolean;
+	tokenMap?: FigmaTokenMap;
+}
+
+export function buildCssLayoutHints(node: unknown): Record<string, unknown> {
+	const record = asRecord(node);
+	const mode = stringValue(record.layoutMode);
+	const css: Record<string, unknown> = {};
+	const notes: string[] = [];
+	if (mode === "HORIZONTAL" || mode === "VERTICAL") {
+		css.display = "flex";
+		css.flexDirection = mode === "HORIZONTAL" ? "row" : "column";
+		if (numberValue(record.itemSpacing) !== undefined) css.gap = px(numberValue(record.itemSpacing));
+		const padding = paddingValue(record);
+		if (padding) css.padding = padding;
+		const justify = mapPrimary(record.primaryAxisAlignItems);
+		const align = mapCounter(record.counterAxisAlignItems);
+		if (justify) css.justifyContent = justify;
+		if (align) css.alignItems = align;
+		if (record.layoutWrap === "WRAP") css.flexWrap = "wrap";
+	} else {
+		css.position = "relative";
+		notes.push("No auto-layout mode detected; absolute positioning may be needed for overlapping/freeform children.");
+	}
+	const grids = compactLayoutGrids(record.layoutGrids);
+	if (grids.length) {
+		css.layoutGrids = grids;
+		notes.push("Figma layout grids can map to CSS grid columns or container guides.");
+	}
+	const sizing = compactObject({
+		horizontal: record.layoutSizingHorizontal,
+		vertical: record.layoutSizingVertical,
+		width: numberValue(asRecord(record.absoluteBoundingBox).width),
+		height: numberValue(asRecord(record.absoluteBoundingBox).height),
+	});
+	return compactObject({ nodeId: record.id, nodeName: record.name, figma: compactObject({ layoutMode: mode, layoutWrap: record.layoutWrap }), css, sizing, notes }) ?? {};
+}
+
+export function buildResponsiveHints(node: unknown): Array<Record<string, unknown>> {
+	const hints: Array<Record<string, unknown>> = [];
+	walk(node, (record, path) => {
+		const recommendations: string[] = [];
+		const constraints = asRecord(record.constraints);
+		if (constraints.horizontal === "SCALE" || constraints.horizontal === "LEFT_RIGHT") recommendations.push("Use width: 100% or stretch within the parent container.");
+		if (constraints.vertical === "SCALE" || constraints.vertical === "TOP_BOTTOM") recommendations.push("Let height stretch or derive it from content plus min-height.");
+		if (record.layoutGrow === 1) recommendations.push("Use flex: 1 for fill-container sizing.");
+		if (record.layoutAlign === "STRETCH" || record.layoutSizingHorizontal === "FILL") recommendations.push("Use align-self: stretch or width: 100%.");
+		if (record.layoutSizingHorizontal === "HUG" || record.layoutSizingVertical === "HUG") recommendations.push("Prefer intrinsic/content sizing; avoid hard-coded dimensions unless necessary.");
+		if (record.layoutSizingHorizontal === "FIXED") recommendations.push("Fixed width from Figma may need max-width or responsive breakpoints.");
+		if (record.layoutWrap === "WRAP") recommendations.push("Enable flex-wrap and test narrow container widths.");
+		if (numberValue(record.minWidth) !== undefined) recommendations.push(`Respect min-width: ${px(numberValue(record.minWidth))}.`);
+		if (numberValue(record.maxWidth) !== undefined) recommendations.push(`Respect max-width: ${px(numberValue(record.maxWidth))}.`);
+		if (recommendations.length) {
+			hints.push({ id: record.id, name: record.name, type: record.type, path, constraints: compactObject(constraints), recommendations: uniqueStrings(recommendations) });
+		}
+	});
+	return hints.slice(0, 60);
+}
+
+export function buildAccessibilityHints(summary: FigmaNodeSummary): Array<Record<string, unknown>> {
+	const hints: Array<Record<string, unknown>> = [];
+	for (const node of flatten(summary)) {
+		const text = (node.text ?? []).join(" ");
+		const haystack = `${node.name} ${text} ${node.roleGuess ?? ""}`.toLowerCase();
+		let role: string | undefined;
+		let tag: string | undefined;
+		const notes: string[] = [];
+		if (/button|submit|save|continue|cancel|next|back/.test(haystack)) {
+			role = "button";
+			tag = "button";
+			notes.push("Ensure it is keyboard-focusable and supports Enter/Space activation.");
+		} else if (/link|learn more|view details/.test(haystack)) {
+			role = "link";
+			tag = "a";
+			notes.push("Use an href when navigation is intended.");
+		} else if (/input|field|placeholder|select|dropdown/.test(haystack)) {
+			role = /select|dropdown/.test(haystack) ? "combobox" : "textbox";
+			tag = /select|dropdown/.test(haystack) ? "select" : "input";
+			notes.push("Associate a visible label or aria-label with the control.");
+		} else if (/checkbox|toggle/.test(haystack)) {
+			role = "checkbox";
+			tag = "input";
+			notes.push("Expose checked state and keyboard toggling.");
+		} else if (/radio/.test(haystack)) {
+			role = "radio";
+			tag = "input";
+			notes.push("Group radios with fieldset/legend or radiogroup labeling.");
+		} else if (/modal|dialog/.test(haystack)) {
+			role = "dialog";
+			tag = "dialog";
+			notes.push("Trap focus, restore focus on close, and label with aria-labelledby.");
+		} else if (/tab/.test(haystack)) {
+			role = "tab";
+			tag = "button";
+			notes.push("Implement roving tabindex and aria-selected.");
+		} else if (/icon|image|avatar|photo/.test(haystack)) {
+			role = "img";
+			tag = "img";
+			notes.push(/icon/.test(haystack) ? "Use aria-hidden for decorative icons or provide accessible name when meaningful." : "Provide descriptive alt text.");
+		} else if (/title|heading|header/.test(haystack)) {
+			role = "heading";
+			tag = "h2";
+		}
+		if (role || node.roleGuess) hints.push({ id: node.id, name: node.name, role: role ?? node.roleGuess, suggestedTag: tag, labelSource: text ? "visible text" : "node name", accessibleName: text || node.name, notes });
+	}
+	return hints.slice(0, 60);
+}
+
+export function buildDesignTokenHints(node: unknown, tokenMap?: FigmaTokenMap): Record<string, unknown> {
+	const resolved: Array<Record<string, unknown>> = [];
+	const unresolved: string[] = [];
+	walk(node, (record, path) => {
+		const styles = asRecord(record.styles);
+		for (const [property, id] of Object.entries(styles)) {
+			const styleId = String(id);
+			const name = tokenMap?.styles[styleId]?.name;
+			if (name) resolved.push({ path, property, id: styleId, kind: "style", name, type: tokenMap?.styles[styleId]?.type });
+			else unresolved.push(styleId);
+		}
+		for (const binding of collectVariableBindings(record.boundVariables)) {
+			const variable = tokenMap?.variables[binding.id];
+			if (variable) resolved.push({ path, property: binding.property, id: binding.id, kind: "variable", name: variable.name, collection: variable.collectionName });
+			else unresolved.push(binding.id);
+		}
+	});
+	return { resolved: resolved.slice(0, 80), unresolved: uniqueStrings(unresolved).slice(0, 80), warnings: tokenMap ? [] : ["Token resolution requires Figma styles/variables metadata; unresolved IDs are still reported when present."] };
+}
+
+export function buildFrameworkHints(summary: FigmaNodeSummary, options: FigmaImplementationOptions): Record<string, unknown> | undefined {
+	if (!options.framework && !options.styling && !options.includeCodeSnippets) return undefined;
+	const framework = options.framework ?? "react";
+	const styling = options.styling ?? "css";
+	const componentName = toPascalCase(summary.name || "FigmaComponent");
+	const className = toKebabCase(summary.name || "figma-component");
+	return compactObject({
+		framework,
+		styling,
+		componentName,
+		fileHints: framework === "react" ? [`${componentName}.tsx`, `${componentName}.styles.ts`] : [`${className}.html`, `${className}.css`],
+		notes: ["Starter snippets are heuristic scaffolds, not production-ready generated code.", "Map Figma text/layers to semantic elements before final implementation."],
+		snippet: options.includeCodeSnippets ? snippetFor(summary, framework, styling, componentName, className) : undefined,
+	}) as Record<string, unknown> | undefined;
+}
+
+function snippetFor(summary: FigmaNodeSummary, framework: FigmaFramework, styling: FigmaStyling, componentName: string, className: string): string {
+	const text = summary.visibleText?.slice(0, 3).join(" / ") || summary.name;
+	if (framework === "react-native") return `export function ${componentName}() {\n  return <View><Text>${escapeSnippet(text)}</Text></View>;\n}`;
+	if (framework === "vue") return `<template>\n  <section class=\"${className}\">${escapeSnippet(text)}</section>\n</template>`;
+	if (framework === "angular") return `<section class=\"${className}\">${escapeSnippet(text)}</section>`;
+	if (framework === "html") return `<section class=\"${className}\">${escapeSnippet(text)}</section>`;
+	if (styling === "styled-components") return `const ${componentName}Root = styled.section\`\n  display: flex;\n\`;\n\nexport function ${componentName}() {\n  return <${componentName}Root>${escapeSnippet(text)}</${componentName}Root>;\n}`;
+	return `export function ${componentName}() {\n  return <section className=\"${className}\">${escapeSnippet(text)}</section>;\n}`;
+}
+
+function flatten(summary: FigmaNodeSummary): FigmaNodeSummary[] {
+	const out: FigmaNodeSummary[] = [];
+	function visit(node: FigmaNodeSummary): void {
+		out.push(node);
+		for (const child of node.children ?? []) visit(child);
+	}
+	visit(summary);
+	return out;
+}
+
+function walk(node: unknown, visit: (record: Record<string, unknown>, path: string) => void, path = ""): void {
+	const record = asRecord(node);
+	const name = String(record.name ?? "Unnamed node");
+	const nextPath = path ? `${path} > ${name}` : name;
+	visit(record, nextPath);
+	for (const child of Array.isArray(record.children) ? record.children : []) walk(child, visit, nextPath);
+}
+
+function collectVariableBindings(value: unknown): Array<{ property: string; id: string }> {
+	const out: Array<{ property: string; id: string }> = [];
+	function visit(raw: unknown, property: string): void {
+		if (Array.isArray(raw)) raw.forEach((item, index) => visit(item, `${property}[${index}]`));
+		else {
+			const record = asRecord(raw);
+			if (typeof record.id === "string") out.push({ property, id: record.id });
+			for (const [key, child] of Object.entries(record)) if (key !== "id" && key !== "type") visit(child, property ? `${property}.${key}` : key);
+		}
+	}
+	visit(value, "");
+	return out;
+}
+
+function compactLayoutGrids(value: unknown): Array<Record<string, unknown>> {
+	if (!Array.isArray(value)) return [];
+	return value.slice(0, 4).map((grid) => {
+		const record = asRecord(grid);
+		return compactObject({ pattern: record.pattern, count: record.count, gutterSize: record.gutterSize, sectionSize: record.sectionSize, alignment: record.alignment }) ?? {};
+	});
+}
+
+function paddingValue(record: Record<string, unknown>): string | undefined {
+	const top = numberValue(record.paddingTop);
+	const right = numberValue(record.paddingRight);
+	const bottom = numberValue(record.paddingBottom);
+	const left = numberValue(record.paddingLeft);
+	if ([top, right, bottom, left].every((value) => value === undefined)) return undefined;
+	return [top ?? 0, right ?? 0, bottom ?? 0, left ?? 0].map(px).join(" ");
+}
+
+function mapPrimary(value: unknown): string | undefined {
+	return ({ MIN: "flex-start", CENTER: "center", MAX: "flex-end", SPACE_BETWEEN: "space-between" } as Record<string, string>)[String(value)];
+}
+
+function mapCounter(value: unknown): string | undefined {
+	return ({ MIN: "flex-start", CENTER: "center", MAX: "flex-end", BASELINE: "baseline", STRETCH: "stretch" } as Record<string, string>)[String(value)];
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+function numberValue(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+	return typeof value === "string" ? value : undefined;
+}
+
+function compactObject(value: Record<string, unknown>): Record<string, unknown> | undefined {
+	const out: Record<string, unknown> = {};
+	for (const [key, raw] of Object.entries(value)) {
+		if (raw === undefined || raw === null) continue;
+		if (Array.isArray(raw) && raw.length === 0) continue;
+		if (typeof raw === "object" && !Array.isArray(raw) && Object.keys(raw).length === 0) continue;
+		out[key] = raw;
+	}
+	return Object.keys(out).length ? out : undefined;
+}
+
+function px(value: number | undefined): string {
+	return `${value ?? 0}px`;
+}
+
+function uniqueStrings(values: string[]): string[] {
+	return [...new Set(values)];
+}
+
+function toPascalCase(value: string): string {
+	const result = value.replace(/[^a-z0-9]+/gi, " ").trim().split(/\s+/).filter(Boolean).map((part) => part[0]?.toUpperCase() + part.slice(1)).join("");
+	return /^[A-Z]/.test(result) ? result : `Figma${result || "Component"}`;
+}
+
+function toKebabCase(value: string): string {
+	return value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "").toLowerCase() || "figma-component";
+}
+
+function escapeSnippet(value: string): string {
+	return value.replace(/[<>]/g, "");
+}

package/node_modules/pi-mono-figma/src/figma-schemas.ts

@@ -0,0 +1,139 @@
+import { Type } from "@sinclair/typebox";
+
+export const MaxResponseCharsSchema = Type.Optional(
+	Type.Number({ description: "Maximum characters returned to the model before truncation", minimum: 1 }),
+);
+
+export const FileKeySchema = Type.String({ description: "Figma file key from a Figma URL" });
+export const NodeIdSchema = Type.String({ description: "Figma node ID, either 1:2 API format or 1-2 URL format" });
+export const NodeIdsSchema = Type.Array(NodeIdSchema, {
+	description: "One or more Figma node IDs. Batch related nodes in one call.",
+	minItems: 1,
+});
+
+export const FigmaGetFileParams = Type.Object({
+	fileKey: FileKeySchema,
+	depth: Type.Optional(Type.Number({ description: "Optional Figma file depth query parameter", minimum: 1 })),
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const FigmaGetDesignContextParams = Type.Object({
+	fileKey: FileKeySchema,
+	nodeId: Type.Optional(NodeIdSchema),
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const FigmaGetNodesParams = Type.Object({
+	fileKey: FileKeySchema,
+	nodeIds: NodeIdsSchema,
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+const FigmaNodeProcessingOptions = {
+	depth: Type.Optional(Type.Number({ description: "How many levels of node hierarchy to include. Defaults to 2 and is capped at 4.", minimum: 1, maximum: 4 })),
+	includeHidden: Type.Optional(Type.Boolean({ description: "Include nodes where visible=false. Defaults to false." })),
+	includeVectors: Type.Optional(Type.Boolean({ description: "Include vector/icon internals. Defaults to false." })),
+	includeComponentInternals: Type.Optional(Type.Boolean({ description: "Expand component instance internals. Defaults to false." })),
+};
+
+const FigmaOptionalRenderOptions = {
+	renderImage: Type.Optional(Type.Boolean({ description: "Render the node and include image URL/local path in the response. Defaults to false." })),
+	outputDir: Type.Optional(Type.String({ description: "Optional directory for downloaded rendered image files. Omit unless the user requested persistent files; by default downloads go to an OS temp directory." })),
+	format: Type.Optional(Type.Unsafe<"png" | "jpg" | "svg" | "pdf">({ type: "string", enum: ["png", "jpg", "svg", "pdf"] })),
+	scale: Type.Optional(Type.Number({ description: "Render scale for bitmap formats", minimum: 0.01, maximum: 4 })),
+};
+
+export const FigmaProcessedNodeParams = Type.Object({
+	fileKey: FileKeySchema,
+	nodeId: NodeIdSchema,
+	...FigmaNodeProcessingOptions,
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const FigmaProcessedNodeWithRenderParams = Type.Object({
+	fileKey: FileKeySchema,
+	nodeId: NodeIdSchema,
+	...FigmaNodeProcessingOptions,
+	...FigmaOptionalRenderOptions,
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const FigmaImplementationContextParams = Type.Object({
+	fileKey: FileKeySchema,
+	nodeId: NodeIdSchema,
+	...FigmaNodeProcessingOptions,
+	...FigmaOptionalRenderOptions,
+	framework: Type.Optional(Type.Unsafe<"react" | "html" | "vue" | "angular" | "react-native">({ type: "string", enum: ["react", "html", "vue", "angular", "react-native"] })),
+	styling: Type.Optional(Type.Unsafe<"css" | "css-modules" | "styled-components" | "tailwind" | "inline">({ type: "string", enum: ["css", "css-modules", "styled-components", "tailwind", "inline"] })),
+	resolveTokens: Type.Optional(Type.Boolean({ description: "Resolve style and variable IDs into token names when possible. Defaults to true." })),
+	includeCodeSnippets: Type.Optional(Type.Boolean({ description: "Include compact starter snippets for the selected framework/styling target. Defaults to false." })),
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const FigmaSingleFileParams = Type.Object({
+	fileKey: FileKeySchema,
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const FigmaSearchComponentsParams = Type.Object({
+	fileKey: FileKeySchema,
+	query: Type.String({ description: "Case-insensitive component name/description search term" }),
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const FigmaFindNodesParams = Type.Object({
+	fileKey: FileKeySchema,
+	query: Type.String({ description: "Layer name or visible text query" }),
+	nodeId: Type.Optional(NodeIdSchema),
+	...FigmaNodeProcessingOptions,
+	exact: Type.Optional(Type.Boolean({ description: "Require an exact match instead of substring matching. Defaults to false." })),
+	caseSensitive: Type.Optional(Type.Boolean({ description: "Use case-sensitive matching. Defaults to false." })),
+	maxResults: Type.Optional(Type.Number({ description: "Maximum matches to return. Defaults to 50 and is capped at 200.", minimum: 1, maximum: 200 })),
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const FigmaRenderNodesParams = Type.Object({
+	fileKey: FileKeySchema,
+	nodeIds: NodeIdsSchema,
+	outputDir: Type.Optional(Type.String({ description: "Optional directory for downloaded image files. Omit unless the user requested persistent files; if omitted, an OS temp directory is created." })),
+	format: Type.Optional(Type.Unsafe<"png" | "jpg" | "svg" | "pdf">({ type: "string", enum: ["png", "jpg", "svg", "pdf"] })),
+	scale: Type.Optional(Type.Number({ description: "Render scale for bitmap formats", minimum: 0.01, maximum: 4 })),
+	download: Type.Optional(Type.Boolean({ description: "Download rendered assets locally. Defaults to true." })),
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const FigmaExtractAssetsParams = Type.Object({
+	fileKey: FileKeySchema,
+	nodeId: NodeIdSchema,
+	depth: Type.Optional(Type.Number({ description: "How many levels of node hierarchy to inspect for assets. Defaults to 3 and is capped at 4.", minimum: 1, maximum: 4 })),
+	assetTypes: Type.Optional(Type.Array(Type.Unsafe<"svgIcons" | "nodeRenders" | "imageFills">({ type: "string", enum: ["svgIcons", "nodeRenders", "imageFills"] }), { description: "Asset categories to extract. Defaults to all supported categories." })),
+	outputDir: Type.Optional(Type.String({ description: "Optional directory for downloaded asset files. Omit unless the user requested persistent files; by default files go to an OS temp directory." })),
+	includeHidden: Type.Optional(Type.Boolean({ description: "Include hidden nodes while discovering assets. Defaults to false." })),
+	maxAssets: Type.Optional(Type.Number({ description: "Maximum assets to include in the manifest. Defaults to 80.", minimum: 1, maximum: 500 })),
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const FigmaFindCodeConnectMappingParams = Type.Object({
+	fileKey: FileKeySchema,
+	nodeId: Type.Optional(NodeIdSchema),
+	componentKey: Type.Optional(Type.String({ description: "Optional Figma component key to search for locally." })),
+	rootDir: Type.Optional(Type.String({ description: "Optional directory under the current repo to scan. Defaults to cwd." })),
+	maxMatches: Type.Optional(Type.Number({ description: "Maximum local mapping matches to return. Defaults to 40.", minimum: 1, maximum: 200 })),
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const FigmaComponentImplementationHintsParams = Type.Object({
+	fileKey: FileKeySchema,
+	nodeId: NodeIdSchema,
+	...FigmaNodeProcessingOptions,
+	framework: Type.Optional(Type.Unsafe<"react" | "html" | "vue" | "angular" | "react-native">({ type: "string", enum: ["react", "html", "vue", "angular", "react-native"] })),
+	styling: Type.Optional(Type.Unsafe<"css" | "css-modules" | "styled-components" | "tailwind" | "inline">({ type: "string", enum: ["css", "css-modules", "styled-components", "tailwind", "inline"] })),
+	includeCodeConnect: Type.Optional(Type.Boolean({ description: "Scan the local repo for Figma Code Connect mappings. Defaults to true." })),
+	includeSnippet: Type.Optional(Type.Boolean({ description: "Include starter framework snippet. Defaults to false." })),
+	rootDir: Type.Optional(Type.String({ description: "Optional local repo subdirectory for Code Connect scanning." })),
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const FigmaParseUrlParams = Type.Object({
+	url: Type.String({ description: "Figma design/file URL" }),
+});

package/node_modules/pi-mono-figma/src/figma-search.ts

@@ -0,0 +1,195 @@
+export interface FigmaFindNodesOptions {
+	query: string;
+	depth?: number;
+	exact?: boolean;
+	caseSensitive?: boolean;
+	includeHidden?: boolean;
+	includeVectors?: boolean;
+	includeComponentInternals?: boolean;
+	maxResults?: number;
+}
+
+export interface FigmaNodeSearchMatch {
+	id?: string;
+	name: string;
+	type: string;
+	path: string;
+	visible: boolean;
+	text?: string;
+	parent?: { id?: string; name: string; type: string; path: string };
+	roleHint?: string;
+}
+
+export interface FigmaNodeSearchResult {
+	query: string;
+	matchType: "name" | "text";
+	matches: FigmaNodeSearchMatch[];
+	metadata: {
+		truncated: boolean;
+		truncatedReasons: string[];
+		nextSteps: string[];
+	};
+}
+
+interface NormalizedSearchOptions extends Required<Omit<FigmaFindNodesOptions, "query">> {
+	query: string;
+}
+
+const VECTOR_TYPES = new Set(["VECTOR", "BOOLEAN_OPERATION", "STAR", "LINE", "ELLIPSE", "POLYGON", "REGULAR_POLYGON"]);
+const DEFAULT_DEPTH = 4;
+const DEFAULT_MAX_RESULTS = 50;
+const MAX_DEPTH = 12;
+const MAX_RESULTS = 200;
+
+export function findNodesByName(node: unknown, options: FigmaFindNodesOptions): FigmaNodeSearchResult {
+	return findNodes(node, normalizeOptions(options), "name");
+}
+
+export function findNodesByText(node: unknown, options: FigmaFindNodesOptions): FigmaNodeSearchResult {
+	return findNodes(node, normalizeOptions(options), "text");
+}
+
+function findNodes(root: unknown, options: NormalizedSearchOptions, matchType: "name" | "text"): FigmaNodeSearchResult {
+	const matches: FigmaNodeSearchMatch[] = [];
+	const truncatedReasons: string[] = [];
+	let visited = 0;
+	let skippedHidden = 0;
+	let skippedVectors = 0;
+	let skippedInstances = 0;
+
+	function visit(node: unknown, level: number, path: string, parent?: FigmaNodeSearchMatch["parent"]): void {
+		const record = asRecord(node);
+		if (!Object.keys(record).length) return;
+		const visible = record.visible !== false;
+		if (!options.includeHidden && !visible) {
+			skippedHidden += 1;
+			return;
+		}
+		const type = String(record.type ?? "UNKNOWN");
+		const isVector = VECTOR_TYPES.has(type);
+		if (isVector && !options.includeVectors && level > 0) {
+			skippedVectors += 1;
+			return;
+		}
+		const name = String(record.name ?? "Unnamed node");
+		const nextPath = path ? `${path} > ${name}` : name;
+		visited += 1;
+
+		const candidate = matchType === "name" ? name : normalizeText(record.characters) ?? "";
+		if (candidate && isMatch(candidate, options)) {
+			if (matches.length < options.maxResults) {
+				matches.push({
+					id: stringValue(record.id),
+					name,
+					type,
+					path: nextPath,
+					visible,
+					text: matchType === "text" ? candidate : normalizeText(record.characters),
+					parent,
+					roleHint: roleHint(name, candidate, type),
+				});
+			} else if (!truncatedReasons.some((reason) => reason.includes("maxResults"))) {
+				truncatedReasons.push(`Reached maxResults ${options.maxResults}; additional matches were omitted.`);
+			}
+		}
+
+		if (level >= options.depth) {
+			if (getChildren(record).length && !truncatedReasons.some((reason) => reason.includes("depth limit"))) {
+				truncatedReasons.push(`Reached depth limit ${options.depth}; deeper descendants were not searched.`);
+			}
+			return;
+		}
+		if (type === "INSTANCE" && !options.includeComponentInternals && level > 0) {
+			skippedInstances += 1;
+			// Text labels inside instances remain useful search targets without exposing full structure.
+			for (const child of getChildren(record)) {
+				const childRecord = asRecord(child);
+				if (childRecord.type === "TEXT") visit(child, level + 1, nextPath, compactParent(record, nextPath));
+			}
+			return;
+		}
+		for (const child of getChildren(record)) visit(child, level + 1, nextPath, compactParent(record, nextPath));
+	}
+
+	visit(root, 0, "");
+
+	if (skippedHidden) truncatedReasons.push(`Skipped ${skippedHidden} hidden node(s). Set includeHidden=true to include them.`);
+	if (skippedVectors) truncatedReasons.push(`Skipped ${skippedVectors} vector/icon node(s). Set includeVectors=true to include them.`);
+	if (skippedInstances) truncatedReasons.push(`Collapsed ${skippedInstances} component instance subtree/subtrees. Set includeComponentInternals=true for internals.`);
+
+	const nextSteps = new Set<string>();
+	if (!matches.length) nextSteps.add("Try a broader query, disable exact matching, or search visible text instead of names.");
+	if (truncatedReasons.some((reason) => reason.includes("maxResults"))) nextSteps.add("Raise maxResults or narrow the search with nodeId/depth.");
+	if (truncatedReasons.some((reason) => reason.includes("depth limit")) && options.depth < MAX_DEPTH) nextSteps.add(`Increase depth to ${options.depth + 1} or search within a more specific nodeId.`);
+	if (skippedInstances) nextSteps.add("Set includeComponentInternals=true only for a focused component instance if internal layer matches matter.");
+
+	return {
+		query: options.query,
+		matchType,
+		matches,
+		metadata: {
+			truncated: truncatedReasons.some((reason) => !reason.startsWith("Skipped")) || matches.length >= options.maxResults,
+			truncatedReasons: uniqueStrings(truncatedReasons),
+			nextSteps: [...nextSteps],
+		},
+	};
+}
+
+function normalizeOptions(options: FigmaFindNodesOptions): NormalizedSearchOptions {
+	return {
+		query: options.query,
+		depth: clampInteger(options.depth ?? DEFAULT_DEPTH, 1, MAX_DEPTH),
+		exact: options.exact ?? false,
+		caseSensitive: options.caseSensitive ?? false,
+		includeHidden: options.includeHidden ?? false,
+		includeVectors: options.includeVectors ?? false,
+		includeComponentInternals: options.includeComponentInternals ?? false,
+		maxResults: clampInteger(options.maxResults ?? DEFAULT_MAX_RESULTS, 1, MAX_RESULTS),
+	};
+}
+
+function isMatch(candidate: string, options: NormalizedSearchOptions): boolean {
+	const haystack = options.caseSensitive ? candidate : candidate.toLowerCase();
+	const needle = options.caseSensitive ? options.query : options.query.toLowerCase();
+	return options.exact ? haystack === needle : haystack.includes(needle);
+}
+
+function compactParent(record: Record<string, unknown>, path: string): FigmaNodeSearchMatch["parent"] {
+	return { id: stringValue(record.id), name: String(record.name ?? "Unnamed node"), type: String(record.type ?? "UNKNOWN"), path };
+}
+
+function roleHint(name: string, text: string, type: string): string | undefined {
+	const haystack = `${name} ${text}`.toLowerCase();
+	if (/button|submit|save|continue|cancel|next|back/.test(haystack)) return "button";
+	if (/input|field|placeholder|select|dropdown/.test(haystack)) return "form-control";
+	if (/modal|dialog/.test(haystack)) return "dialog";
+	if (/icon/.test(haystack) || VECTOR_TYPES.has(type)) return "icon";
+	if (/title|heading|header/.test(haystack)) return "heading";
+	return undefined;
+}
+
+function getChildren(record: Record<string, unknown>): unknown[] {
+	return Array.isArray(record.children) ? record.children : [];
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+function normalizeText(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const text = value.replace(/\s+/g, " ").trim();
+	return text || undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+	return typeof value === "string" ? value : undefined;
+}
+
+function clampInteger(value: number, min: number, max: number): number {
+	return Math.max(min, Math.min(max, Math.trunc(value)));
+}
+
+function uniqueStrings(values: string[]): string[] {
+	return [...new Set(values)];
+}