pi-mono-all 1.0.0

package/node_modules/pi-mono-figma/README.md

@@ -0,0 +1,236 @@
+# pi-mono-figma
+
+A pi extension and skill package that exposes native Figma tools for design exploration and design-to-code workflows. The default tools return compact, LLM-ready design context instead of raw Figma JSON.
+
+## Benefits over Figma MCP
+
+This package is Pi-native and uses Figma's REST API directly, with tools designed specifically for LLM-friendly design exploration and design-to-code workflows.
+
+- **No hosted Figma MCP quota path:** the extension calls Figma's REST API directly instead of using a hosted Claude/Figma connector quota path. It is still subject to Figma API limits, and the client smooths calls with a fixed 1s limiter plus a 5-minute TTL cache.
+- **Better LLM-shaped output:** `figma_get_node_summary`, `figma_explain_node`, and `figma_get_implementation_context` avoid raw Figma JSON by default. They cap depth, skip hidden nodes, vector internals, and component internals unless requested, and return `metadata.nextSteps` when follow-up inspection would help.
+- **Design-to-code specialization:** `figma_get_implementation_context` extracts fields, buttons, layout measurements, typography, colors, spacing, CSS/flex/grid hints, responsive guidance, accessibility hints, design tokens, assets, and optional framework starter snippets instead of simply relaying generic server output.
+- **Safer local auth UX:** `figma_configure_auth` uses masked local prompting and stores the token in Pi auth storage. The model never sees the token.
+- **Good raw escape hatches:** raw `figma_get_file` and `figma_get_nodes` tools are available for debugging, while tool descriptions steer agents toward processed tools first.
+- **Local asset handling:** `figma_render_nodes` can download rendered images to an OS temp directory by default, while `figma_extract_assets` returns a manifest for SVG icons, node renders, and image fills with node paths, hashes, byte sizes, and suggested names. Persistent project directories are used only when `outputDir` is explicitly provided.
+- **Broader inspection surface:** styles, variables, components, component sets, component search, metadata, text extraction, rendering, summaries, explanations, and implementation context are exposed as separate native tools.
+
+## Tools
+
+### Processed, LLM-ready tools (preferred)
+
+- `figma_parse_url` — parse a Figma URL into `fileKey` and `nodeId`.
+- `figma_find_nodes_by_name` — search layer/node names in a file or subtree and return compact path-aware matches.
+- `figma_find_nodes_by_text` — search visible text in a file or subtree and return matches with nearest parent context.
+- `figma_render_nodes` — render node image URLs and optionally download assets locally. Downloads use an OS temp directory by default unless the user explicitly provides `outputDir`.
+- `figma_get_node_summary` — fetch a compact structured summary of a node: name, type, size, layout, spacing, visual style, visible text, component properties, and shallow child hierarchy.
+- `figma_extract_text` — return visible text nodes only.
+- `figma_explain_node` — explain a node in Markdown using summary, visible text, hierarchy, and optional rendered asset.
+- `figma_get_implementation_context` — return coding-ready design context: purpose, sections, fields/buttons, measurements, typography, colors, spacing, CSS layout, responsive hints, accessibility hints, design token resolution, assets, component hierarchy, and optional snippets.
+- `figma_extract_assets` — extract SVG/icon exports, node renders, and image fills into a node-path manifest with hashes and local paths.
+- `figma_find_code_connect_mapping` — scan the current repo for Code Connect files, `figma.connect(...)`, Figma URLs/node IDs, and component key references.
+- `figma_get_component_implementation_hints` — combine summary, implementation context, variants/properties, tokens, assets, accessibility, optional Code Connect matches, and starter snippets.
+- `figma_get_design_context` — fetch compact file context. With `nodeId`, returns target node summary plus location/sibling context; without `nodeId`, returns canvases and top-level frames only.
+- `figma_get_node_metadata` — fetch compact spatial/layout metadata for one or more nodes.
+- `figma_get_styles` — fetch named styles.
+- `figma_get_variables` — fetch local variables/collections for design tokens.
+- `figma_get_components` — fetch component metadata.
+- `figma_get_component_sets` — fetch component set metadata.
+- `figma_search_components` — search components by name or description.
+- `figma_configure_auth` — securely prompt for and store a Figma token without exposing it to the model.
+
+### Raw escape hatches
+
+- `figma_get_file` — fetch raw Figma file JSON. Use only when raw Figma JSON is explicitly needed or when debugging the extension.
+- `figma_get_nodes` — fetch raw node JSON. Use only when raw Figma JSON is explicitly needed or when debugging the extension.
+
+The package also bundles the `figma` skill under `skills/figma/SKILL.md`.
+
+## Recommended workflows
+
+### Explaining a component
+
+```text
+figma_parse_url
+figma_render_nodes
+figma_explain_node
+```
+
+### Implementing a design
+
+```text
+figma_parse_url
+figma_find_nodes_by_name or figma_find_nodes_by_text when the URL does not include the exact target node
+figma_render_nodes
+figma_get_implementation_context with framework/styling when useful
+figma_get_node_summary for specific subnodes if needed
+```
+
+Example implementation-context options:
+
+```ts
+{
+  framework: "react",
+  styling: "styled-components",
+  resolveTokens: true,
+  includeCodeSnippets: true
+}
+```
+
+### Finding a frame or layer before implementation
+
+```text
+figma_get_design_context
+figma_find_nodes_by_name query="Checkout" nodeId=<top-level-frame-if-known>
+figma_find_nodes_by_text query="Submit" nodeId=<candidate-frame>
+```
+
+### Extracting assets for a frame
+
+```text
+figma_extract_assets assetTypes=["svgIcons", "nodeRenders", "imageFills"]
+```
+
+Use returned `nodePath`, `suggestedName`, `sha256`, and `bytes` to map downloaded files back to Figma layers and avoid duplicate assets.
+Omit `outputDir` unless the user asked for files to be saved in a persistent project location; the default is an OS temp directory.
+
+### Finding local Code Connect mappings
+
+```text
+figma_find_code_connect_mapping fileKey=<fileKey> nodeId=<nodeId>
+figma_get_component_implementation_hints includeCodeConnect=true framework="react"
+```
+
+Use Code Connect matches only as local implementation hints; no Figma write access is used.
+
+### Debugging raw Figma data
+
+```text
+figma_get_nodes
+```
+
+## Live selection boundary
+
+This package is REST/API-based and read-only. It can inspect files, nodes, styles, variables, renders, and local repository mappings when you provide a file key/node ID, but it does **not** currently know the live selection in an open Figma desktop/browser session.
+
+True Dev Mode-style live selection parity would require a separate local bridge or Figma plugin that captures the current selection and exposes selected file/node IDs to Pi. See [`docs/live-selection-bridge.md`](docs/live-selection-bridge.md) for a future architecture sketch.
+
+## Processed node options
+
+Processed tools fetch nodes with compact depth limits and summarize safely:
+
+```ts
+{
+  depth?: number; // default 2, capped at 4
+  includeHidden?: boolean; // default false
+  includeVectors?: boolean; // default false
+  includeComponentInternals?: boolean; // default false
+  framework?: "react" | "html" | "vue" | "angular" | "react-native";
+  styling?: "css" | "css-modules" | "styled-components" | "tailwind" | "inline";
+  resolveTokens?: boolean; // implementation context, default true
+  includeCodeSnippets?: boolean; // implementation context, default false
+}
+```
+
+Defaults intentionally avoid hidden layers, vector internals, and huge component instance trees. Increase depth or include internals only for a focused child node.
+
+## Output limits and truncation
+
+Processed tools default to compact responses (~20k chars unless overridden by `maxResponseChars`) and cap common large arrays:
+
+- visible text: 200 entries
+- children: 100 entries
+- depth: 4 max
+
+When data is capped, responses include `metadata.truncated: true`, `truncatedReasons`, and `nextSteps` such as inspecting a child node or increasing depth.
+
+## Authentication
+
+The extension looks for a Figma token in this order:
+
+1. in-memory token override created by `/figma-auth --force` or `figma_configure_auth`
+2. `FIGMA_TOKEN` environment variable
+3. `~/.pi/agent/auth.json` at `.figma.token`
+
+If no token is found, or if Figma rejects the token as invalid/expired, the native tools can prompt you with a masked local dialog and store the replacement token without returning it to the model.
+
+Do **not** paste tokens into an LLM chat.
+
+### Recommended: native auth command
+
+Run this in pi:
+
+```text
+/figma-auth --force
+```
+
+The command shows the Figma token URL and required scopes, prompts for the token with masked input, and writes it to `~/.pi/agent/auth.json` at `.figma.token`.
+
+The same flow is available to the agent through the `figma_configure_auth` tool. That tool returns only metadata such as `stored: true`; it never returns the token.
+
+### Option A: environment variable
+
+For the current shell session:
+
+```bash
+export FIGMA_TOKEN="figd_xxx"
+```
+
+To persist it, add that export to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.) or your preferred secrets manager.
+
+### Option B: pi auth file
+
+Create or update `~/.pi/agent/auth.json`:
+
+```json
+{
+  "figma": {
+    "token": "figd_xxx"
+  }
+}
+```
+
+Recommended file permissions:
+
+```bash
+mkdir -p ~/.pi/agent
+chmod 700 ~/.pi/agent
+chmod 600 ~/.pi/agent/auth.json
+```
+
+If the file already contains other credentials, merge the `figma.token` entry instead of overwriting the file.
+
+## Creating a Figma token
+
+1. Open Figma.
+2. Go to **Settings → Security → Personal access tokens**.
+3. Click **Generate new token**.
+4. Name it something recognizable, for example `pi-agent`.
+5. Enable the required scopes/permissions below.
+6. Copy the token once and store it via `FIGMA_TOKEN` or `~/.pi/agent/auth.json`.
+
+## Required scopes / permissions
+
+This extension is read-only. It needs permission to read file content and render nodes.
+
+Enable:
+
+- **File content** / read access to files
+
+Also make sure the token has access to the specific Figma file, project, or team you want to inspect. If your Figma organization supports resource scoping, grant access only to the minimum projects/files needed.
+
+No write/admin scopes are required.
+
+## Troubleshooting
+
+### `Token expired`
+
+Generate a new Figma personal access token and update `FIGMA_TOKEN` or `~/.pi/agent/auth.json`.
+
+### Missing or inaccessible file
+
+Confirm that:
+
+- the file key is correct,
+- the token has file-content read permission,
+- the token owner can access the file in Figma,
+- the node ID uses either URL format (`27399-4245`) or API format (`27399:4245`).

package/node_modules/pi-mono-figma/__tests__/code-connect.test.ts

@@ -0,0 +1,32 @@
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import assert from "node:assert/strict";
+import { findCodeConnectMapping } from "../src/code-connect.js";
+
+test("findCodeConnectMapping discovers figma.connect, URLs, and node IDs", async () => {
+	const root = await mkdtemp(join(tmpdir(), "figma-code-connect-"));
+	await writeFile(join(root, "Button.figma.tsx"), "figma.connect(Button, 'https://www.figma.com/design/FILE123/Name?node-id=1-2')\n");
+	await writeFile(join(root, "README.md"), "component key COMPONENT123\n");
+	const result = await findCodeConnectMapping({ cwd: root, fileKey: "FILE123", nodeId: "1:2", componentKey: "COMPONENT123" });
+	assert.ok(result.matches.some((match) => match.kind === "figma-connect"));
+	assert.ok(result.matches.some((match) => match.kind === "figma-file-reference"));
+	assert.ok(result.matches.some((match) => match.kind === "component-key-reference"));
+});
+
+test("findCodeConnectMapping ignores node_modules and enforces caps", async () => {
+	const root = await mkdtemp(join(tmpdir(), "figma-code-connect-"));
+	await mkdir(join(root, "node_modules"));
+	await writeFile(join(root, "node_modules", "Ignored.ts"), "figma.connect(Ignored)\n");
+	await writeFile(join(root, "One.ts"), "figma.connect(One)\nfigma.connect(Two)\n");
+	const result = await findCodeConnectMapping({ cwd: root, fileKey: "FILE123", maxMatches: 1 });
+	assert.equal(result.matches.length, 1);
+	assert.equal(result.matches[0]?.path, "One.ts");
+	assert.equal(result.metadata.truncated, true);
+});
+
+test("findCodeConnectMapping rejects rootDir outside cwd", async () => {
+	const root = await mkdtemp(join(tmpdir(), "figma-code-connect-"));
+	await assert.rejects(() => findCodeConnectMapping({ cwd: root, rootDir: "/", fileKey: "FILE123" }), /rootDir/);
+});

package/node_modules/pi-mono-figma/__tests__/figma-assets.test.ts

@@ -0,0 +1,38 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { collectAssetCandidates, formatFromPath, safeFilename, sha256 } from "../src/figma-assets.js";
+
+const assetTree = {
+	id: "10:1",
+	name: "Hero Card",
+	type: "FRAME",
+	absoluteBoundingBox: { width: 320, height: 200 },
+	fills: [{ type: "IMAGE", imageRef: "abc123", scaleMode: "FILL" }],
+	children: [
+		{ id: "10:2", name: "Close icon", type: "VECTOR", absoluteBoundingBox: { width: 16, height: 16 } },
+		{ id: "10:3", name: "Logo Mark", type: "FRAME", absoluteBoundingBox: { width: 32, height: 32 } },
+		{ id: "10:4", name: "Hidden asset", type: "VECTOR", visible: false, absoluteBoundingBox: { width: 16, height: 16 } },
+	],
+};
+
+test("collectAssetCandidates detects icons, node renders, image fills, and paths", () => {
+	const result = collectAssetCandidates(assetTree, { assetTypes: ["svgIcons", "nodeRenders", "imageFills"] });
+	assert.ok(result.assets.some((asset) => asset.kind === "svgIcon" && asset.nodePath === "Hero Card > Close icon"));
+	assert.ok(result.assets.some((asset) => asset.kind === "nodeRender" && asset.nodePath === "Hero Card"));
+	assert.ok(result.assets.some((asset) => asset.kind === "imageFill" && asset.imageRef === "abc123"));
+	assert.equal(result.assets.some((asset) => asset.nodeName === "Hidden asset"), false);
+});
+
+test("collectAssetCandidates supports hidden nodes and caps results", () => {
+	const result = collectAssetCandidates(assetTree, { includeHidden: true, maxAssets: 1 });
+	assert.equal(result.assets.length, 1);
+	assert.equal(result.metadata.truncated, true);
+	assert.ok(result.metadata.truncatedReasons.some((reason) => reason.includes("maxAssets")));
+});
+
+test("asset helper utilities normalize names, hashes, and formats", () => {
+	assert.equal(safeFilename("Close Icon / Primary"), "close-icon-primary");
+	assert.equal(sha256("abc"), "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad");
+	assert.equal(formatFromPath("/tmp/icon.svg"), "svg");
+	assert.equal(formatFromPath("/tmp/photo.jpeg"), "jpg");
+});

package/node_modules/pi-mono-figma/__tests__/figma-component-hints.test.ts

@@ -0,0 +1,23 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildComponentImplementationHints } from "../src/figma-component-hints.js";
+import { getImplementationContext, summarizeNode } from "../src/figma-summarizer.js";
+
+async function fixture(name: string): Promise<unknown> {
+	return JSON.parse(await readFile(join(import.meta.dirname, "fixtures", name), "utf8"));
+}
+
+test("buildComponentImplementationHints combines summary, variants, accessibility, tokens, and snippets", async () => {
+	const node = await fixture("component-instance.json");
+	const summary = summarizeNode(node, { depth: 3 });
+	const context = getImplementationContext(node, { framework: "react", includeCodeSnippets: true });
+	const hints = buildComponentImplementationHints(summary, context, { framework: "react", includeSnippet: true, includeCodeConnect: true }, { rootDir: "/repo", matches: [], metadata: { truncated: false, truncatedReasons: [], nextSteps: [] } });
+	assert.equal(hints.componentName, "SettingsModal");
+	assert.ok(hints.suggestedProps.some((prop) => prop.name === "children"));
+	assert.ok(hints.statesAndVariants.some((variant) => variant.name === "State"));
+	assert.ok(hints.accessibilityRequirements.some((hint) => hint.role === "dialog" || hint.role === "button"));
+	assert.match(String(hints.frameworkHints?.snippet), /export function SettingsModal/);
+	assert.ok(hints.metadata.nextSteps.some((step) => step.includes("Code Connect")));
+});

package/node_modules/pi-mono-figma/__tests__/figma-implementation-layout.test.ts

@@ -0,0 +1,47 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import test from "node:test";
+import assert from "node:assert/strict";
+import { getImplementationContext } from "../src/figma-summarizer.js";
+import { buildCssLayoutHints, buildResponsiveHints } from "../src/figma-implementation.js";
+
+async function fixture(name: string): Promise<unknown> {
+	return JSON.parse(await readFile(join(import.meta.dirname, "fixtures", name), "utf8"));
+}
+
+test("buildCssLayoutHints maps auto-layout to CSS flex and grid hints", async () => {
+	const node = await fixture("complex-auto-layout.json");
+	const hints = buildCssLayoutHints(node);
+	assert.deepEqual((hints.css as Record<string, unknown>).display, "flex");
+	assert.equal((hints.css as Record<string, unknown>).flexDirection, "column");
+	assert.equal((hints.css as Record<string, unknown>).gap, "16px");
+	assert.equal((hints.css as Record<string, unknown>).padding, "20px 24px 20px 24px");
+	assert.ok(Array.isArray((hints.css as Record<string, unknown>).layoutGrids));
+});
+
+test("buildResponsiveHints recommends fill, hug, fixed, and wrap behavior", async () => {
+	const node = await fixture("complex-auto-layout.json");
+	const hints = buildResponsiveHints(node);
+	assert.ok(hints.some((hint) => String(hint.name) === "Header Row" && (hint.recommendations as string[]).some((rec) => rec.includes("width: 100%"))));
+	assert.ok(hints.some((hint) => String(hint.name) === "Dashboard Card" && (hint.recommendations as string[]).some((rec) => rec.includes("Fixed width"))));
+});
+
+test("implementation context includes layout, responsive, accessibility, tokens, and snippets", async () => {
+	const node = await fixture("variables-and-styles.json");
+	const context = getImplementationContext(node, {
+		framework: "react",
+		styling: "styled-components",
+		includeCodeSnippets: true,
+		tokenMap: {
+			styles: { "S:primary-fill": { name: "Color/Primary", type: "FILL" }, "S:text-button": { name: "Typography/Button", type: "TEXT" } },
+			variables: { "VariableID:color-primary": { name: "color.primary" }, "VariableID:text-on-primary": { name: "color.onPrimary" }, "VariableID:radius-md": { name: "radius.md" } },
+			collections: {},
+			warnings: [],
+		},
+	});
+	assert.ok(context.cssLayout);
+	assert.ok(context.accessibility?.some((hint) => hint.role === "button"));
+	assert.ok((context.designTokens?.resolved as Array<Record<string, unknown>>).some((token) => token.name === "Color/Primary"));
+	assert.equal(context.frameworkHints?.framework, "react");
+	assert.match(String(context.frameworkHints?.snippet), /styled\.section/);
+});

package/node_modules/pi-mono-figma/__tests__/figma-search.test.ts

@@ -0,0 +1,51 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import test from "node:test";
+import assert from "node:assert/strict";
+import { findNodesByName, findNodesByText } from "../src/figma-search.js";
+
+async function fixture(name: string): Promise<unknown> {
+	return JSON.parse(await readFile(join(import.meta.dirname, "fixtures", name), "utf8"));
+}
+
+test("findNodesByName supports partial, exact, and case-sensitive matching", async () => {
+	const node = await fixture("complex-auto-layout.json");
+	assert.deepEqual(findNodesByName(node, { query: "button" }).matches.map((match) => match.name), ["Save button", "Button label"]);
+	assert.equal(findNodesByName(node, { query: "save button", exact: true }).matches.length, 1);
+	assert.equal(findNodesByName(node, { query: "save button", exact: true, caseSensitive: true }).matches.length, 0);
+});
+
+test("findNodesByText returns path and parent context", async () => {
+	const node = await fixture("complex-auto-layout.json");
+	const result = findNodesByText(node, { query: "Water risk" });
+	assert.equal(result.matches[0]?.text, "Water risk summary");
+	assert.equal(result.matches[0]?.parent?.name, "Header Row");
+	assert.match(result.matches[0]?.path ?? "", /Dashboard Card > Header Row > Title/);
+});
+
+test("findNodesByName respects hidden and vector filters", async () => {
+	const node = await fixture("hidden-and-vectors.json");
+	assert.equal(findNodesByName(node, { query: "Hidden" }).matches.length, 0);
+	assert.equal(findNodesByName(node, { query: "Hidden", includeHidden: true }).matches.length, 1);
+	assert.equal(findNodesByName(node, { query: "icon" }).matches.length, 0);
+	assert.equal(findNodesByName(node, { query: "icon", includeVectors: true }).matches.length, 1);
+});
+
+test("findNodesByText searches collapsed instance text but not vector internals", async () => {
+	const node = await fixture("component-instance.json");
+	const result = findNodesByText(node, { query: "Continue" });
+	assert.equal(result.matches.length, 1);
+	assert.equal(result.matches[0]?.parent?.name, "Primary CTA instance");
+	assert.ok(result.metadata.nextSteps.some((step) => step.includes("includeComponentInternals")));
+});
+
+test("findNodesByName enforces depth and result caps", async () => {
+	const node = await fixture("complex-auto-layout.json");
+	const depthLimited = findNodesByName(node, { query: "Title", depth: 1 });
+	assert.equal(depthLimited.matches.length, 0);
+	assert.ok(depthLimited.metadata.truncatedReasons.some((reason) => reason.includes("depth limit")));
+
+	const capped = findNodesByName(node, { query: "", maxResults: 1 });
+	assert.equal(capped.matches.length, 1);
+	assert.ok(capped.metadata.truncatedReasons.some((reason) => reason.includes("maxResults")));
+});

package/node_modules/pi-mono-figma/__tests__/figma-summarizer.test.ts

@@ -0,0 +1,65 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import test from "node:test";
+import assert from "node:assert/strict";
+import { extractVisibleText, getImplementationContext, summarizeNode } from "../src/figma-summarizer.js";
+
+async function fixture(name: string): Promise<unknown> {
+	const path = join(import.meta.dirname, "fixtures", name);
+	return JSON.parse(await readFile(path, "utf8"));
+}
+
+test("summarizeNode excludes hidden nodes and vector internals by default", async () => {
+	const node = await fixture("hidden-and-vectors.json");
+	const summary = summarizeNode(node, { depth: 3 });
+	assert.deepEqual(summary.visibleText, ["Visible copy"]);
+	assert.equal(summary.children?.some((child) => child.name === "Hidden text"), false);
+	assert.equal(summary.children?.some((child) => child.name === "Search icon"), false);
+});
+
+test("summarizeNode can include hidden nodes and vectors when requested", async () => {
+	const node = await fixture("hidden-and-vectors.json");
+	const summary = summarizeNode(node, { depth: 3, includeHidden: true, includeVectors: true });
+	assert.deepEqual(summary.visibleText, ["Visible copy", "Hidden copy"]);
+	assert.ok(summary.children?.some((child) => child.name === "Hidden text"));
+	assert.ok(summary.children?.some((child) => child.name === "Search icon"));
+});
+
+test("component instances collapse structural internals while retaining useful text", async () => {
+	const node = await fixture("component-instance.json");
+	const summary = summarizeNode(node, { depth: 2 });
+	const instance = summary.children?.find((child) => child.type === "INSTANCE");
+	assert.equal(instance?.children, undefined);
+	assert.deepEqual(instance?.text, ["Continue"]);
+	assert.ok(summary.metadata?.truncatedReasons.some((reason) => reason.includes("Collapsed component instance")));
+});
+
+test("extractVisibleText returns capped text metadata", async () => {
+	const node = await fixture("complex-auto-layout.json");
+	const result = extractVisibleText(node, { maxVisibleText: 1 });
+	assert.deepEqual(result.texts, ["Water risk summary"]);
+	assert.equal(result.metadata.truncated, true);
+	assert.ok(result.metadata.nextSteps.includes("Use figma_extract_text on a narrower child node to see more text."));
+});
+
+test("getImplementationContext deterministically extracts typography colors spacing and controls", async () => {
+	const node = await fixture("complex-auto-layout.json");
+	const context = getImplementationContext(node, { depth: 3 });
+	assert.match(context.purpose, /Water risk summary/);
+	assert.equal(context.sections.length, 2);
+	assert.ok(context.buttons.some((button) => button.name === "Save button"));
+	assert.ok(context.typography.some((entry) => entry.fontFamily === "Inter" && entry.fontSize === 18));
+	assert.ok(context.colors.some((entry) => entry.hex === "#ffffff"));
+	assert.ok(context.spacing.some((entry) => entry.itemSpacing === 16));
+});
+
+test("depth and children caps produce truncation metadata", async () => {
+	const node = await fixture("complex-auto-layout.json");
+	const depthLimited = summarizeNode(node, { depth: 1 });
+	assert.equal(depthLimited.metadata?.truncated, true);
+	assert.ok(depthLimited.metadata?.nextSteps.some((step) => step.includes("depth 2")));
+
+	const childLimited = summarizeNode(node, { depth: 2, maxChildren: 1 });
+	assert.equal(childLimited.children?.length, 1);
+	assert.ok(childLimited.metadata?.truncatedReasons.some((reason) => reason.includes("Capped children")));
+});

package/node_modules/pi-mono-figma/__tests__/fixtures/complex-auto-layout.json

@@ -0,0 +1,115 @@
+{
+  "id": "1:1",
+  "name": "Dashboard Card",
+  "type": "FRAME",
+  "visible": true,
+  "absoluteBoundingBox": { "width": 360, "height": 240 },
+  "layoutMode": "VERTICAL",
+  "primaryAxisAlignItems": "MIN",
+  "counterAxisAlignItems": "STRETCH",
+  "layoutWrap": "NO_WRAP",
+  "layoutSizingHorizontal": "FIXED",
+  "layoutSizingVertical": "HUG",
+  "itemSpacing": 16,
+  "paddingLeft": 24,
+  "paddingRight": 24,
+  "paddingTop": 20,
+  "paddingBottom": 20,
+  "layoutGrids": [
+    { "pattern": "COLUMNS", "count": 12, "gutterSize": 16, "sectionSize": 56 }
+  ],
+  "fills": [
+    { "type": "SOLID", "color": { "r": 1, "g": 1, "b": 1 }, "opacity": 1 }
+  ],
+  "strokes": [
+    {
+      "type": "SOLID",
+      "color": { "r": 0.8, "g": 0.84, "b": 0.9 },
+      "opacity": 1
+    }
+  ],
+  "cornerRadius": 12,
+  "children": [
+    {
+      "id": "1:2",
+      "name": "Header Row",
+      "type": "FRAME",
+      "absoluteBoundingBox": { "width": 312, "height": 40 },
+      "layoutMode": "HORIZONTAL",
+      "primaryAxisAlignItems": "SPACE_BETWEEN",
+      "counterAxisAlignItems": "CENTER",
+      "layoutSizingHorizontal": "FILL",
+      "layoutSizingVertical": "HUG",
+      "itemSpacing": 8,
+      "children": [
+        {
+          "id": "1:3",
+          "name": "Title",
+          "type": "TEXT",
+          "absoluteBoundingBox": { "width": 140, "height": 24 },
+          "characters": "Water risk summary",
+          "style": {
+            "fontFamily": "Inter",
+            "fontSize": 18,
+            "fontWeight": 700,
+            "lineHeightPx": 24
+          },
+          "fills": [
+            {
+              "type": "SOLID",
+              "color": { "r": 0.05, "g": 0.1, "b": 0.18 },
+              "opacity": 1
+            }
+          ]
+        },
+        {
+          "id": "1:4",
+          "name": "More icon",
+          "type": "VECTOR",
+          "absoluteBoundingBox": { "width": 20, "height": 20 },
+          "fills": [
+            {
+              "type": "SOLID",
+              "color": { "r": 0.3, "g": 0.35, "b": 0.44 },
+              "opacity": 1
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "1:5",
+      "name": "Save button",
+      "type": "FRAME",
+      "absoluteBoundingBox": { "width": 120, "height": 40 },
+      "layoutMode": "HORIZONTAL",
+      "primaryAxisAlignItems": "CENTER",
+      "counterAxisAlignItems": "CENTER",
+      "itemSpacing": 8,
+      "fills": [
+        {
+          "type": "SOLID",
+          "color": { "r": 0.05, "g": 0.42, "b": 0.95 },
+          "opacity": 1
+        }
+      ],
+      "children": [
+        {
+          "id": "1:6",
+          "name": "Button label",
+          "type": "TEXT",
+          "characters": "Save",
+          "absoluteBoundingBox": { "width": 34, "height": 20 },
+          "style": { "fontFamily": "Inter", "fontSize": 14, "fontWeight": 600 },
+          "fills": [
+            {
+              "type": "SOLID",
+              "color": { "r": 1, "g": 1, "b": 1 },
+              "opacity": 1
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/node_modules/pi-mono-figma/__tests__/fixtures/component-instance.json

@@ -0,0 +1,50 @@
+{
+  "id": "2:1",
+  "name": "Settings modal",
+  "type": "FRAME",
+  "absoluteBoundingBox": { "width": 480, "height": 360 },
+  "children": [
+    {
+      "id": "2:2",
+      "name": "Primary CTA instance",
+      "type": "INSTANCE",
+      "componentId": "99:1",
+      "componentSetId": "99:0",
+      "componentProperties": {
+        "State": { "type": "VARIANT", "value": "Default" },
+        "Disabled": { "type": "BOOLEAN", "value": false }
+      },
+      "absoluteBoundingBox": { "width": 180, "height": 44 },
+      "children": [
+        {
+          "id": "2:3",
+          "name": "Hidden icon",
+          "type": "VECTOR",
+          "absoluteBoundingBox": { "width": 16, "height": 16 }
+        },
+        {
+          "id": "2:4",
+          "name": "Label",
+          "type": "TEXT",
+          "characters": "Continue",
+          "absoluteBoundingBox": { "width": 70, "height": 20 },
+          "style": { "fontFamily": "Inter", "fontSize": 14, "fontWeight": 600 }
+        }
+      ]
+    },
+    {
+      "id": "2:5",
+      "name": "Email input field",
+      "type": "FRAME",
+      "absoluteBoundingBox": { "width": 300, "height": 48 },
+      "children": [
+        {
+          "id": "2:6",
+          "name": "Placeholder",
+          "type": "TEXT",
+          "characters": "Email address"
+        }
+      ]
+    }
+  ]
+}