AI-native design editor. Open-source Figma alternative.
chore: organize repo tooling under tools
Danila Poyarkov72e3bc4fb531
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.mdindex b91139c82..cbf6522d9 100644--- a/.github/copilot-instructions.md+++ b/.github/copilot-instructions.md@@ -25,7 +25,7 @@ bun run checkPackage publishing changes should also run:```sh-bun scripts/smoke-packages.ts+bun run test:packages```## Code conventionsdiff --git a/AGENTS.md b/AGENTS.mdindex 65fa6e843..a35c4822b 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -35,6 +35,7 @@ The root app (`src/`) is the Tauri/Vite desktop editor. App-specific editor, doc| `@open-pencil/core/editor` | createEditor, Editor, EditorState | — || `@open-pencil/core/tools` | ToolDef, ALL_TOOLS, AI adapter | diff || `@open-pencil/core/kiwi` | .fig parse/serialize, codec, protocol | fflate, fzstd |+| `@open-pencil/core/clipboard` | Figma/OpenPencil clipboard parsing and import helpers | — || `@open-pencil/core/rpc` | RPC commands for CLI | — || `@open-pencil/core/lint` | design linter rules and presets | — || `@open-pencil/core/profiler` | render profiling | — |@@ -96,7 +97,8 @@ The app editor session (`src/app/editor/session/create.ts`) is a thin Vue wrappe- `bun run check` — type-aware lint + typecheck via oxlint + tsgo + architecture checks (run before committing)- `bun run check:arch` — Steiger architecture lint for project-specific import boundaries- `bun run check:vue` — vue-tsc type-check for .vue files (has pre-existing errors, fix progressively)-- `bun run test:dupes` — jscpd copy-paste detection across all TS sources+- `bun run test:dupes` — jscpd copy-paste detection across product TS sources+- `bun run test:tools` — tests for private repo tooling under `tools/*`- `bun run format` — oxfmt with import sorting- `bun test ./tests/engine` — unit tests- `bun run test` — Playwright visual regression@@ -146,6 +148,7 @@ Run all quality gates (see [Code quality](#code-quality) for the self-review chebun run check # oxlint + tsgo type-aware lint & typecheckbun run format # oxfmtbun run test:dupes # jscpd — zero clones+bun run test:tools # private repo tooling testsbun run test:unit # bun:testbun run test # Playwright E2E```@@ -253,6 +256,20 @@ OpenPencil follows a Reka UI-inspired component namespace structure:- Multi-file root components live inside their component namespace folder, not beside it.- Use subfolders for multi-file domains instead of sibling files with repeated prefixes. Prefer `selection/container.ts`, `selection/hit-test.ts` over `selection-container.ts`, `selection-hit-test.ts`. When adding a second file for a domain (e.g. `eval-wrap.ts` next to `eval.ts`), create the folder immediately (`eval/index.ts` + `eval/wrap.ts`) instead of prefixing. Oxlint catches sibling prefix files when a sibling folder exists; Steiger catches 3+ sibling files with the same prefix. The convention applies even before either rule triggers.+### Repo tools and scripts++Private repository tooling lives under `tools/<domain>/`, not as ad-hoc root scripts. Use kebab-case domain folders and split by capability inside `src/`:++```text+tools/<domain>/+ package.json+ src/index.ts+ src/<capability>.ts+ tests/<capability>.test.ts+```++Use `scripts/` only for tiny compatibility entrypoint shims that import `../tools/<domain>/src/...`; do not put implementation logic there. Workflow helpers, release packaging helpers, architecture rules, package checks, visual-oracle utilities, and other maintainable programs belong in `tools/` with focused tests when they contain logic. Steiger enforces tool layout and script shims. `bun run check` includes `bun run test:tools`, and lint/format cover `tools/`.+- `@/` import alias for app cross-directory imports; app feature code lives under `src/app/*`- Use package-local aliases inside workspace packages: `#vue/*` in `packages/vue`, `#cli/*` in `packages/cli`, `#mcp/*` in `packages/mcp`, and `#core/*` when core code needs an alias. Prefer relative imports within nearby core modules when that is clearer than an alias.- No `any` — use proper types, generics, declaration merging@@ -280,6 +297,7 @@ Before submitting a PR, run the full quality gate and do a self-review:bun run check # oxlint + tsgo type-aware lint & typecheck — zero errors requiredbun run format # oxfmt with import sortingbun run test:dupes # jscpd — zero clones required+bun run test:tools # private repo tooling testsbun run test:unit # bun:testbun run test # Playwright E2E```diff --git a/oxlint.json b/oxlint.jsonindex bb4022c85..d4a995247 100644--- a/oxlint.json+++ b/oxlint.json@@ -464,7 +464,8 @@},{"files": [- "scripts/**/*.ts"+ "scripts/**/*.ts",+ "tools/**/*.ts"],"rules": {"no-console": "off"diff --git a/package.json b/package.jsonindex dcd0f4ab1..796b6608a 100644--- a/package.json+++ b/package.json@@ -17,8 +17,8 @@"format": "oxfmt --write .oxfmtrc.json vite.config.ts vite/ src/ packages/core/src/ packages/cli/src/ packages/mcp/src/ packages/vue/src/ tests scripts/ tools/","format:check": "bun run format && status=$(git status --porcelain -uall) && test -z \"$status\" || (echo \"$status\" && exit 1)","check": "bun run build:packages && bun run lint && tsgo --noEmit && bun run check:vue && bun run check:i18n && bun run check:packages && bun run check:arch && bun run test:type-shapes && bun run test:tools && bun run test:dupes",- "check:i18n": "bun scripts/check-locales.ts",- "check:packages": "bun scripts/check-package-metadata.ts",+ "check:i18n": "bun tools/i18n/src/check-locales.ts",+ "check:packages": "bun tools/package-quality/src/check-metadata.ts","check:arch": "steiger .","check:vue": "vue-tsc --noEmit -p tsconfig.json && vue-tsc --noEmit -p packages/vue/tsconfig.json","test": "playwright test --project=openpencil",@@ -27,17 +27,17 @@"figma:debug": "open -a Figma --args --remote-debugging-port=9222","test:unit": "bun test ./tests/engine","test:coverage": "bun test --coverage ./tests/engine",- "test:type-shapes": "bun scripts/type-shapes.ts",+ "test:type-shapes": "bun tools/type-shapes/src/index.ts","test:tools": "bun tools/test.ts","test:dupes": "jscpd packages/core/src packages/cli/src src --min-lines 5 --min-tokens 50 --format typescript --threshold 0",- "test:packages": "bun scripts/check-package-metadata.ts && bun scripts/smoke-packages.ts",+ "test:packages": "bun tools/package-quality/src/check-metadata.ts && bun tools/package-quality/src/smoke.ts","build:packages": "bun --filter @open-pencil/core build && bun --filter @open-pencil/vue build && bun --filter @open-pencil/mcp build && bun --filter @open-pencil/cli build","open-pencil": "bun packages/cli/src/index.ts","docs:dev": "bun --filter @open-pencil/docs dev","docs:build": "bun --filter @open-pencil/docs build","docs:preview": "bun --filter @open-pencil/docs preview",- "visual-compare": "bun scripts/visual-compare.ts",- "generate:tauri-menu": "bun scripts/generate-tauri-menu.ts"+ "visual-compare": "bun tools/visual-oracles/src/compare.ts",+ "generate:tauri-menu": "bun tools/tauri-menu/src/generate.ts"},"dependencies": {"@ai-sdk/anthropic": "^3.0.74",diff --git a/packages/core/package.json b/packages/core/package.jsonindex 5c36d11c4..1a34dce99 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -113,6 +113,11 @@"default": "./dist/kiwi/index.js","import": "./dist/kiwi/index.js"},+ "./clipboard": {+ "types": "./dist/clipboard.d.ts",+ "default": "./dist/clipboard.js",+ "import": "./dist/clipboard.js"+ },"./constants": {"types": "./dist/constants.d.ts","default": "./dist/constants.js",diff --git a/packages/docs/development/roadmap.md b/packages/docs/development/roadmap.mdindex a3c3451f1..c8aed67dd 100644--- a/packages/docs/development/roadmap.md+++ b/packages/docs/development/roadmap.md@@ -19,7 +19,7 @@ OpenPencil is moving toward production-grade Figma compatibility while keeping d### Figma fidelity- Preserve and round-trip more Figma metadata safely.-- Add visual regression coverage for full multi-page `.fig` documents. `scripts/export-fixture-visuals.ts` exports current smoke fixture pages to `/tmp` for manual comparison without committing large images; `tests/fixtures/figma-oracles/visual-comparison-report.json` records the current Figma-vs-OpenPencil oracle diff findings.+- Add visual regression coverage for full multi-page `.fig` documents. `tools/visual-oracles/src/export-fixtures.ts` exports current smoke fixture pages to `/tmp` for manual comparison without committing large images; `tests/fixtures/figma-oracles/visual-comparison-report.json` records the current Figma-vs-OpenPencil oracle diff findings.- Close high-impact renderer gaps: remaining mask edge cases, blend isolation, pattern fills, and broader variable-font fixtures.- Improve boolean operation editing/export now that imported Figma `BOOLEAN_OPERATION` nodes remain boolean operations.diff --git a/scripts/export-fixture-visuals.ts b/scripts/export-fixture-visuals.tsindex 4bba74d11..39c2cec5b 100644--- a/scripts/export-fixture-visuals.ts+++ b/scripts/export-fixture-visuals.ts@@ -1,55 +1,2 @@#!/usr/bin/env bun--import { mkdirSync } from 'node:fs'-import { parseArgs } from 'node:util'--import { $ } from 'bun'--interface FixtureExportTarget {- file: string- page: string- outputName: string- heavy?: boolean-}--const TARGETS: FixtureExportTarget[] = [- {- file: 'tests/fixtures/gold-preview.fig',- page: 'Page 1',- outputName: 'gold-preview-page-1.png'- },- {- file: 'tests/fixtures/material3.fig',- page: 'Getting started',- outputName: 'material3-getting-started.png'- },- {- file: 'tests/fixtures/nuxtui.fig',- page: 'Components',- outputName: 'nuxtui-components.png',- heavy: true- }-]--const { values } = parseArgs({- options: {- output: { type: 'string', short: 'o', default: '/tmp/open-pencil-fixture-visuals' },- heavy: { type: 'boolean', default: false }- }-})--const outputDir = values.output ?? '/tmp/open-pencil-fixture-visuals'-mkdirSync(outputDir, { recursive: true })--for (const target of TARGETS) {- if (target.heavy && !values.heavy) {- console.log(`Skipping ${target.file} (${target.page}); pass --heavy to include it.`)- continue- }-- const outputPath = `${outputDir}/${target.outputName}`- console.log(`Exporting ${target.file} / ${target.page} → ${outputPath}`)- await $`bun open-pencil export ${target.file} --page ${target.page} --output ${outputPath}`-}--console.log(`Fixture visuals written to ${outputDir}`)+import '../tools/visual-oracles/src/export-fixtures'diff --git a/scripts/generate-tauri-menu.ts b/scripts/generate-tauri-menu.tsindex dada21fb4..1407f4c72 100644--- a/scripts/generate-tauri-menu.ts+++ b/scripts/generate-tauri-menu.ts@@ -1,35 +1,2 @@-import { mkdirSync, writeFileSync } from 'node:fs'-import { dirname } from 'node:path'--import { APP_MENU_SCHEMA } from '../src/app/shell/menu/schema'-import type { AppMenuEntry, AppMenuGroupSchema } from '../src/app/shell/menu/schema'-import { shortcutTokenToAccelerator } from '../src/app/shell/menu/shortcut'--function isNativeVisible(entry: { target?: string }): boolean {- return entry.target !== 'browser'-}--function cleanEntry(entry: AppMenuEntry): unknown | null {- if (!isNativeVisible(entry)) return null- if (entry.type === 'separator') return { type: 'separator' }- return {- id: entry.id,- label: entry.label,- accelerator: entry.accelerator ?? shortcutTokenToAccelerator(entry.shortcut),- checkbox: entry.checkbox,- sub: entry.sub?.map(cleanEntry).filter(Boolean)- }-}--function cleanGroup(group: AppMenuGroupSchema): unknown | null {- if (!isNativeVisible(group)) return null- return {- label: group.label,- items: group.items.map(cleanEntry).filter(Boolean)- }-}--const outputPath = 'desktop/generated/menu.json'-const menu = APP_MENU_SCHEMA.map(cleanGroup).filter(Boolean)-mkdirSync(dirname(outputPath), { recursive: true })-writeFileSync(outputPath, `${JSON.stringify(menu, null, 2)}\n`)+#!/usr/bin/env bun+import '../tools/tauri-menu/src/generate'diff --git a/scripts/visual-bisect.ts b/scripts/visual-bisect.tsindex 4c14065bd..0f0165daa 100644--- a/scripts/visual-bisect.ts+++ b/scripts/visual-bisect.ts@@ -1,334 +1,2 @@#!/usr/bin/env bun--import { existsSync, mkdirSync } from 'node:fs'-import { basename } from 'node:path'-import { parseArgs } from 'node:util'--import { $ } from 'bun'--import { parseColor } from '@open-pencil/core/color'-import { headlessRenderNodes, initCanvasKit, parseFigFile } from '@open-pencil/core/io'-import { computeAllLayouts } from '@open-pencil/core/layout'-import type { SceneGraph } from '@open-pencil/core/scene-graph'--interface DiffMetrics {- mean: number- above5: number- above10: number- above20: number- above40: number- above80: number-}--interface BisectResult {- depth: number- indices: number[]- names: string[]- metrics: DiffMetrics- figmaPath: string- openPencilPath: string-}--const { values, positionals } = parseArgs({- allowPositionals: true,- options: {- page: { type: 'string', short: 'p' },- 'figma-page-id': { type: 'string' },- output: { type: 'string', short: 'o', default: '/tmp/open-pencil-visual-bisect' },- scale: { type: 'string', default: '1' },- threshold: { type: 'string', default: '0.25' },- depth: { type: 'string', default: '8' },- 'min-size': { type: 'string', default: '1' },- background: { type: 'string', default: '#f9f9f9' },- 'root-node-id': { type: 'string' },- 'figma-root-id': { type: 'string' }- }-})--const figPath = positionals[0]-if (!figPath || !values.page || !values['figma-page-id']) {- console.error(`Usage:- bun scripts/visual-bisect.ts <file.fig> --page Primitives --figma-page-id 1:22 [options]--Options:- --output DIR Output directory (default: /tmp/open-pencil-visual-bisect)- --scale N Export scale (default: 1)- --threshold PERCENT Stop splitting groups under this >40 diff percent (default: 0.25)- --depth N Max bisection depth (default: 8)- --min-size N Stop splitting groups at this child count (default: 1)- --background HEX Matte color for transparent pixels (default: #f9f9f9)- --root-node-id ID OpenPencil node whose children should be bisected- --figma-root-id ID Matching Figma node whose children should be bisected--What it does:- It hides all top-level page children except a candidate subset in both Figma- and OpenPencil, exports that subset from both renderers, diffs the images,- then recursively splits only subsets that still differ. This isolates which- top-level page children introduce visual differences without staring at the- full-page diff.`)- process.exit(1)-}--const pageName = values.page-const figmaPageId = values['figma-page-id']-const outputDir = values.output ?? '/tmp/open-pencil-visual-bisect'-const scale = Number(values.scale ?? '1')-const threshold = Number(values.threshold ?? '0.25')-const maxDepth = Number(values.depth ?? '8')-const minSize = Number(values['min-size'] ?? '1')-const matteColor = colorBytes(values.background ?? '#f9f9f9')--if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true })--const graph = await loadGraph(figPath, pageName)-const page = graph.getPages().find((candidate) => candidate.name === pageName)-if (!page) throw new Error(`Page not found in .fig: ${pageName}`)-const rootNodeId = values['root-node-id'] ?? page.id-const figmaRootId = values['figma-root-id'] ?? figmaPageId-const rootNode = graph.getNode(rootNodeId)-if (!rootNode) throw new Error(`Root node not found in .fig: ${rootNodeId}`)-const childIds = [...rootNode.childIds]-const childNames = childIds.map((id) => graph.getNode(id)?.name ?? id)--console.log(`Visual bisect: ${basename(figPath)} / ${pageName}`)-console.log(`Root: ${rootNode.name} (${rootNode.id})`)-console.log(`Children: ${childIds.length}`)-console.log(`Output: ${outputDir}`)--const initialVisibility = await captureFigmaVisibility(figmaRootId)-const results: BisectResult[] = []--try {- await bisect(- childIds.map((_, index) => index),- 0- )-} finally {- await restoreFigmaVisibility(figmaRootId, initialVisibility)-}--results.sort((a, b) => b.metrics.above40 - a.metrics.above40 || a.indices.length - b.indices.length)-await writeReport(results)--console.log('\nTop suspects:')-for (const result of results.slice(0, 12)) {- console.log(- `${result.indices.join(',')} | >40 ${result.metrics.above40.toFixed(3)}% | ${result.names.join(' / ')}`- )-}-console.log(`\nReport: ${outputDir}/report.md`)--async function loadGraph(path: string, targetPageName: string): Promise<SceneGraph> {- const bytes = new Uint8Array(await Bun.file(path).arrayBuffer())- const parsed = await parseFigFile(- bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),- {- populate: 'all'- }- )- const targetPage = parsed.getPages().find((candidate) => candidate.name === targetPageName)- if (targetPage) computeAllLayouts(parsed, targetPage.id)- return parsed-}--async function bisect(indices: number[], depth: number): Promise<void> {- if (indices.length === 0 || depth > maxDepth) return-- const result = await compareSubset(indices, depth)- const label = `[depth ${depth}] [${indices.join(',')}] >40=${result.metrics.above40.toFixed(3)}% ${result.names.join(' / ')}`- console.log(label)-- if (result.metrics.above40 <= threshold) return- results.push(result)-- if (indices.length <= minSize) return- const mid = Math.floor(indices.length / 2)- await bisect(indices.slice(0, mid), depth + 1)- await bisect(indices.slice(mid), depth + 1)-}--async function compareSubset(indices: number[], depth: number): Promise<BisectResult> {- const stem = `d${depth}-${indices[0]}-${indices.at(-1)}-${indices.length}`- const figmaPath = `${outputDir}/${stem}-figma.png`- const openPencilPath = `${outputDir}/${stem}-open-pencil.png`-- await exportFigmaSubset(figmaRootId, indices, figmaPath)- await exportOpenPencilSubset(indices, openPencilPath)-- return {- depth,- indices,- names: indices.map((index) => childNames[index]),- metrics: await diffImages(figmaPath, openPencilPath),- figmaPath,- openPencilPath- }-}--async function exportOpenPencilSubset(indices: number[], path: string): Promise<void> {- const indexSet = new Set(indices)- const changed: Array<{ id: string; visible: boolean }> = []- for (let index = 0; index < childIds.length; index++) {- const node = graph.getNode(childIds[index])- if (!node) continue- changed.push({ id: node.id, visible: node.visible })- node.visible = indexSet.has(index)- }-- try {- const nodeIds =- rootNode.type === 'CANVAS' ? indices.map((index) => childIds[index]) : [rootNode.id]- const data = await headlessRenderNodes(graph, page.id, nodeIds, {- scale,- format: 'PNG',- trimTransparent: nodeIds.every((id) => graph.getNode(id)?.type === 'TEXT')- })- if (!data) throw new Error(`OpenPencil render produced no image for ${indices.join(',')}`)- await Bun.write(path, data)- } finally {- for (const entry of changed) {- const node = graph.getNode(entry.id)- if (node) node.visible = entry.visible- }- }-}--async function exportFigmaSubset(pageId: string, indices: number[], path: string): Promise<void> {- await setFigmaVisibleIndices(pageId, indices)- await $`figma-use export node ${pageId} --output ${path} --scale ${String(scale)}`.quiet()-}--async function captureFigmaVisibility(pageId: string): Promise<boolean[]> {- const code = `- const node = figma.getNodeById(${JSON.stringify(pageId)});- if (!node || !('children' in node)) throw new Error('Node has no children: ${pageId}');- return node.children.map((child) => child.visible);- `- const out = await $`figma-use eval ${code} --json`.quiet()- return JSON.parse(out.text().trim())-}--async function setFigmaVisibleIndices(pageId: string, indices: number[]): Promise<void> {- const code = `- const visible = new Set(${JSON.stringify(indices)});- const node = figma.getNodeById(${JSON.stringify(pageId)});- if (!node || !('children' in node)) throw new Error('Node has no children: ${pageId}');- node.children.forEach((child, index) => { child.visible = visible.has(index); });- `- await $`figma-use eval ${code}`.quiet()-}--async function restoreFigmaVisibility(pageId: string, visibility: boolean[]): Promise<void> {- const code = `- const visibility = ${JSON.stringify(visibility)};- const node = figma.getNodeById(${JSON.stringify(pageId)});- if (!node || !('children' in node)) return;- node.children.forEach((child, index) => { child.visible = visibility[index] ?? child.visible; });- `- await $`figma-use eval ${code}`.quiet().nothrow()-}--async function diffImages(expectedPath: string, actualPath: string): Promise<DiffMetrics> {- const ck = await initCanvasKit()- const expected = ck.MakeImageFromEncoded(await Bun.file(expectedPath).bytes())- const actual = ck.MakeImageFromEncoded(await Bun.file(actualPath).bytes())- if (!expected || !actual) throw new Error('Failed to decode PNGs')-- try {- const width = Math.min(expected.width(), actual.width())- const height = Math.min(expected.height(), actual.height())- const imageInfo = {- width,- height,- colorType: ck.ColorType.RGBA_8888,- alphaType: ck.AlphaType.Unpremul,- colorSpace: ck.ColorSpace.SRGB- }- const expectedPixels = expected.readPixels(0, 0, imageInfo)- const actualPixels = actual.readPixels(0, 0, imageInfo)- if (!expectedPixels || !actualPixels) throw new Error('Failed to read image pixels')-- let sum = 0- let above5 = 0- let above10 = 0- let above20 = 0- let above40 = 0- let above80 = 0- const total = width * height- const bg = matteColor- for (let pixel = 0; pixel < total; pixel++) {- const offset = pixel * 4- const expectedRgb = compositeRgb(expectedPixels, offset, bg)- const actualRgb = compositeRgb(actualPixels, offset, bg)- const dr = Math.abs(expectedRgb[0] - actualRgb[0])- const dg = Math.abs(expectedRgb[1] - actualRgb[1])- const db = Math.abs(expectedRgb[2] - actualRgb[2])- const max = Math.max(dr, dg, db)- sum += dr + dg + db- if (max > 5) above5++- if (max > 10) above10++- if (max > 20) above20++- if (max > 40) above40++- if (max > 80) above80++- }-- return {- mean: sum / total,- above5: (above5 / total) * 100,- above10: (above10 / total) * 100,- above20: (above20 / total) * 100,- above40: (above40 / total) * 100,- above80: (above80 / total) * 100- }- } finally {- expected.delete()- actual.delete()- }-}--async function writeReport(items: BisectResult[]): Promise<void> {- const lines = [- `# Visual bisect report`,- ``,- `- File: ${figPath}`,- `- Page: ${pageName}`,- `- Figma page id: ${figmaPageId}`,- `- Scale: ${scale}`,- `- Threshold (>40): ${threshold}%`,- ``,- `| depth | indices | >40 | >20 | mean | names | images |`,- `|---:|---|---:|---:|---:|---|---|`- ]-- for (const item of items) {- lines.push(- `| ${item.depth} | ${item.indices.join(',')} | ${item.metrics.above40.toFixed(3)}% | ${item.metrics.above20.toFixed(3)}% | ${item.metrics.mean.toFixed(3)} | ${item.names.map(escapePipes).join('<br>')} | [figma](${item.figmaPath}) / [open-pencil](${item.openPencilPath}) |`- )- }-- await Bun.write(`${outputDir}/report.md`, `${lines.join('\n')}\n`)-}--function colorBytes(input: string): readonly [number, number, number] {- const color = parseColor(input)- return [color.r * 255, color.g * 255, color.b * 255]-}--function compositeRgb(- pixels: Uint8Array,- offset: number,- bg: readonly [number, number, number]-): [number, number, number] {- const alpha = pixels[offset + 3] / 255- if (alpha >= 1) return [pixels[offset], pixels[offset + 1], pixels[offset + 2]]- if (alpha <= 0) return [bg[0], bg[1], bg[2]]- return [- pixels[offset] * alpha + bg[0] * (1 - alpha),- pixels[offset + 1] * alpha + bg[1] * (1 - alpha),- pixels[offset + 2] * alpha + bg[2] * (1 - alpha)- ]-}--function escapePipes(value: string): string {- return value.replaceAll('|', '\\|')-}+import '../tools/visual-oracles/src/bisect'diff --git a/scripts/visual-compare.ts b/scripts/visual-compare.tsindex 8b834f08f..ff1d42f7a 100644--- a/scripts/visual-compare.ts+++ b/scripts/visual-compare.ts@@ -1,296 +1,2 @@#!/usr/bin/env bun-/**- * Visual comparison pipeline: Figma vs OpenPencil renderer.- *- * Copy an element in Figma, then run:- * bun scripts/visual-compare.ts [--scale 2] [--output /tmp/visual-compare]- *- * Or pass a node ID directly (skips clipboard):- * bun scripts/visual-compare.ts --node 1:23 [--scale 2]- *- * Outputs:- * figma.png — exported from real Figma- * ours.png — rendered by OpenPencil headless SkiaRenderer- * diff.png — visual diff (red = changed pixels)- */--import { existsSync, mkdirSync, writeFileSync } from 'node:fs'-import { parseArgs } from 'node:util'--import { $ } from 'bun'--import { SkiaRenderer } from '@open-pencil/core/canvas'-import { renderNodesToImage, initCanvasKit } from '@open-pencil/core/io'-import { computeAllLayouts } from '@open-pencil/core/layout'-import { SceneGraph } from '@open-pencil/core/scene-graph'-import { fontManager } from '@open-pencil/core/text'--import { parseFigmaClipboard, importClipboardNodes } from '#core/clipboard'--const { values: opts } = parseArgs({- options: {- scale: { type: 'string', default: '2' },- output: { type: 'string', short: 'o', default: '/tmp/visual-compare' },- node: { type: 'string', short: 'n' },- resize: { type: 'boolean', default: false },- fuzz: { type: 'string', default: '1%' },- 'alpha-diff': { type: 'boolean', default: false },- 'metrics-json': { type: 'string' }- }-})--const scale = Number(opts.scale)-const outputDir = opts.output ?? '/tmp/visual-compare'-const figmaPath = `${outputDir}/figma.png`-const oursPath = `${outputDir}/ours.png`-const normalizedOursPath = `${outputDir}/ours-normalized.png`-const diffPath = `${outputDir}/diff.png`-const metricsPath = opts['metrics-json'] ?? `${outputDir}/metrics.json`-const alphaFigmaPath = `${outputDir}/figma-alpha.png`-const alphaOursPath = `${outputDir}/ours-alpha.png`-const alphaDiffPath = `${outputDir}/diff-alpha.png`--if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true })--if (opts.node) {- await runWithNodeId(opts.node)-} else {- await runWithClipboard()-}--// --- Mode 1: Clipboard -----async function runWithClipboard() {- console.log('📋 Reading clipboard…')- const html = await readClipboardHtml()- if (!html) bail('No HTML on clipboard. Copy an element in Figma first.')-- const parsed = await parseFigmaClipboard(html)- if (!parsed) bail('Clipboard has no Figma data. Copy an element in Figma first.')- console.log(` ${parsed.nodes.length} node changes, ${parsed.blobs.length} blobs`)-- console.log('🖼️ Rendering with OpenPencil…')- await renderOurs(html)-- console.log('🎨 Pasting into Figma & exporting…')- await ensureFigmaConnected()- await renderFigmaViaPaste()-- await diff()-}--// --- Mode 2: Node ID -----async function runWithNodeId(nodeId: string) {- await ensureFigmaConnected()-- console.log(`🎨 Exporting node ${nodeId} from Figma…`)- await $`figma-use export node ${nodeId} --output ${figmaPath} --scale ${String(scale)}`.quiet()- console.log(` → ${figmaPath}`)-- console.log('📋 Exporting clipboard data from Figma…')- // Select the node, copy, read clipboard, render with our engine- const nodeIdLiteral = JSON.stringify(nodeId)- await $`figma-use eval ${`const n = figma.getNodeById(${nodeIdLiteral}); if (!n) return; let page = n.parent; while (page && page.type !== 'PAGE') page = page.parent; if (page) { await figma.setCurrentPageAsync(page); page.selection = [n]; }`}`.quiet()- await Bun.sleep(200)- await $`osascript -e 'tell application "Figma" to activate'`.quiet()- await Bun.sleep(300)- await $`osascript -e 'tell application "System Events" to keystroke "c" using command down'`.quiet()- await Bun.sleep(1000)-- const html = await readClipboardHtml()- if (!html) bail('Failed to copy from Figma')- const parsed = await parseFigmaClipboard(html)- if (!parsed) bail('Clipboard has no Figma data after copy')-- console.log('🖼️ Rendering with OpenPencil…')- await renderOurs(html)-- await diff()-}--// --- Rendering -----async function renderOurs(html: string) {- const result = await parseFigmaClipboard(html)- if (!result) throw new Error('Failed to parse clipboard')-- const graph = new SceneGraph()- const pageId = graph.getPages()[0].id-- const createdIds = importClipboardNodes(result.nodes, graph, pageId, 0, 0, result.blobs)- if (createdIds.length === 0) throw new Error('No nodes imported from clipboard')-- computeAllLayouts(graph)-- const families = new Set<string>()- for (const node of graph.getAllNodes()) {- if (node.fontFamily) families.add(node.fontFamily)- }- for (const family of families) {- await fontManager.loadFont(family)- }-- const ck = await initCanvasKit()- const surface = ck.MakeSurface(1, 1)- if (!surface) throw new Error('Failed to create CanvasKit surface')- const renderer = new SkiaRenderer(ck, surface)- renderer.viewportWidth = 1- renderer.viewportHeight = 1- renderer.dpr = 1-- const data = renderNodesToImage(ck, renderer, graph, pageId, createdIds, {- scale,- format: 'PNG'- })-- surface.delete()- if (!data) throw new Error('Render produced no image')- await Bun.write(oursPath, data)- console.log(` → ${oursPath}`)-}--async function renderFigmaViaPaste() {- // Create temp page so we don't pollute the user's work- await $`figma-use eval ${'(() => { const p = figma.createPage(); p.name = "__visual_compare__"; figma.currentPage = p; return p.id; })()'} --json`.quiet()-- try {- // Activate Figma and paste- await $`osascript -e 'tell application "Figma" to activate'`.quiet()- await Bun.sleep(500)- await $`osascript -e 'tell application "System Events" to keystroke "v" using command down'`.quiet()- await Bun.sleep(2000)-- // Get pasted selection- const selJson = await $`figma-use selection get --json`.quiet()- const selection = JSON.parse(selJson.text().trim())- if (!selection.length) throw new Error('Nothing pasted. Ensure clipboard has Figma data.')-- const nodeId = selection[0].id-- // Export from Figma- await $`figma-use export node ${nodeId} --output ${figmaPath} --scale ${String(scale)}`.quiet()- console.log(` → ${figmaPath}`)- } finally {- // Clean up: remove temp page- await $`figma-use eval ${'(() => { const ps = figma.root.children; const tmp = ps.find(p => p.name === "__visual_compare__"); if (tmp) { const other = ps.find(p => p !== tmp); if (other) figma.currentPage = other; tmp.remove(); } })()'}`- .quiet()- .nothrow()- }-}--// --- Diff -----async function diff() {- console.log('🔍 Computing diff…')-- const figmaSize = (await $`identify -format '%wx%h' ${figmaPath}`.quiet()).text().trim()- const oursSize = (await $`identify -format '%wx%h' ${oursPath}`.quiet()).text().trim()-- const compareOursPath = figmaSize === oursSize ? oursPath : normalizedOursPath- if (figmaSize !== oursSize) {- const mode = opts.resize ? 'resizing' : 'padding/cropping without scaling'- console.log(` ⚠ Size mismatch: Figma ${figmaSize}, Ours ${oursSize} → ${mode}`)- if (opts.resize) {- await $`magick ${oursPath} -resize ${figmaSize}! ${normalizedOursPath}`.quiet()- } else {- await $`magick ${oursPath} -background none -gravity northwest -extent ${figmaSize} ${normalizedOursPath}`.quiet()- }- }-- const result =- await $`magick compare -metric AE -highlight-color red -lowlight-color '#FFFFFF33' -compose src ${figmaPath} ${compareOursPath} ${diffPath}`- .quiet()- .nothrow()-- const fuzzResult =- await $`magick compare -metric AE -fuzz ${opts.fuzz} ${figmaPath} ${compareOursPath} null:`- .quiet()- .nothrow()- const rmseResult = await $`magick compare -metric RMSE ${figmaPath} ${compareOursPath} null:`- .quiet()- .nothrow()- const rmse = rmseResult.stderr.toString().trim()- const diffPixels = Number.parseInt(result.stderr.toString().trim(), 10) || 0- const fuzzPixels = Number.parseInt(fuzzResult.stderr.toString().trim(), 10) || 0- const [w, h] = figmaSize.split('x').map(Number)- const total = w * h- const pct = (diffPixels / total) * 100- const fuzzPct = (fuzzPixels / total) * 100- const alphaMetrics = opts['alpha-diff'] ? await diffAlpha(compareOursPath, total) : null- const metrics = {- figmaSize,- openPencilSize: oursSize,- comparedOpenPencilPath: compareOursPath,- resized: Boolean(opts.resize && figmaSize !== oursSize),- normalized: figmaSize !== oursSize,- differentPixels: diffPixels,- differentPercent: Number(pct.toFixed(2)),- fuzz: opts.fuzz,- fuzzDifferentPixels: fuzzPixels,- fuzzDifferentPercent: Number(fuzzPct.toFixed(2)),- rmse,- alpha: alphaMetrics- }- writeFileSync(metricsPath, `${JSON.stringify(metrics, null, 2)}\n`)-- console.log(` → ${diffPath}`)- console.log(- ` ${diffPixels.toLocaleString()} different pixels (${pct.toFixed(2)}% of ${total.toLocaleString()})`- )- console.log(- ` ${fuzzPixels.toLocaleString()} different pixels with ${opts.fuzz} fuzz (${fuzzPct.toFixed(2)}%)`- )- console.log(` RMSE ${rmse}`)- if (alphaMetrics) {- console.log(- ` Alpha AE ${alphaMetrics.differentPixels.toLocaleString()} pixels (${alphaMetrics.differentPercent.toFixed(2)}%)`- )- }- console.log(` Metrics → ${metricsPath}`)- console.log(`\n✅ Done! Images in ${outputDir}/`)-}--async function diffAlpha(compareOursPath: string, total: number) {- await $`magick ${figmaPath} -alpha extract ${alphaFigmaPath}`.quiet()- await $`magick ${compareOursPath} -alpha extract ${alphaOursPath}`.quiet()- const result =- await $`magick compare -metric AE -highlight-color red -lowlight-color '#FFFFFF33' -compose src ${alphaFigmaPath} ${alphaOursPath} ${alphaDiffPath}`- .quiet()- .nothrow()- const differentPixels = Number.parseInt(result.stderr.toString().trim(), 10) || 0- return {- path: alphaDiffPath,- differentPixels,- differentPercent: (differentPixels / total) * 100- }-}--// --- Helpers -----async function readClipboardHtml(): Promise<string | null> {- const proc = Bun.spawn(- [- 'swift',- '-e',- 'import AppKit; if let h = NSPasteboard.general.string(forType: .html) { print(h) } else { exit(1) }'- ],- { stdout: 'pipe', stderr: 'pipe' }- )- const text = await new Response(proc.stdout).text()- return (await proc.exited) === 0 ? text.trim() : null-}--async function ensureFigmaConnected() {- const s = await $`figma-use status`.quiet().nothrow()- if (s.exitCode !== 0) {- bail(- 'figma-use not connected. Start Figma with:\n open -a Figma --args --remote-debugging-port=9222'- )- }-}--function bail(msg: string): never {- console.error(msg)- process.exit(1)-}+import '../tools/visual-oracles/src/compare'diff --git a/steiger.config.ts b/steiger.config.tsindex 1e137d73b..66fb9e929 100644--- a/steiger.config.ts+++ b/steiger.config.ts@@ -1,7 +1,7 @@import fsd from '@feature-sliced/steiger-plugin'import { defineConfig } from 'steiger'-import { openPencilArchitecturePlugin } from './scripts/steiger-rules.ts'+import { openPencilArchitecturePlugin } from './tools/architecture/src/steiger-rules.ts'// OpenPencil is not laid out as canonical Feature-Sliced Design layers.// Keep Steiger focused on project-specific architecture boundaries instead of@@ -37,7 +37,9 @@ export default defineConfig(['open-pencil/no-non-ui-imports-in-shared-ui': 'error','open-pencil/no-app-imports-in-shared-ui': 'error','open-pencil/no-property-panel-internals-outside-panel': 'error',- 'open-pencil/no-ui-imports-in-core': 'error'+ 'open-pencil/no-ui-imports-in-core': 'error',+ 'open-pencil/scripts-are-entrypoint-shims': 'error',+ 'open-pencil/strict-tools-layout': 'error'}}])diff --git a/tests/fixtures/figma-oracles/visual-comparison-report.json b/tests/fixtures/figma-oracles/visual-comparison-report.jsonindex 82232aa07..cba7af2ab 100644--- a/tests/fixtures/figma-oracles/visual-comparison-report.json+++ b/tests/fixtures/figma-oracles/visual-comparison-report.json@@ -1,6 +1,6 @@{"source": {- "tool": "scripts/visual-compare.ts",+ "tool": "tools/visual-oracles/src/compare.ts","captured": "2026-05-22","outputRoot": "/tmp/open-pencil-oracles"},diff --git a/tools/architecture/package.json b/tools/architecture/package.jsonnew file mode 100644index 000000000..0a09dc9c3--- /dev/null+++ b/tools/architecture/package.json@@ -0,0 +1,5 @@+{+ "name": "@open-pencil/architecture-tools",+ "private": true,+ "type": "module"+}diff --git a/scripts/steiger-rules.ts b/tools/architecture/src/steiger-rules.tssimilarity index 94%rename from scripts/steiger-rules.tsrename to tools/architecture/src/steiger-rules.tsindex dce22c128..8daff720b 100644--- a/scripts/steiger-rules.ts+++ b/tools/architecture/src/steiger-rules.ts@@ -210,6 +210,27 @@ const preferDomainFoldersOverFilenamePrefixes: Rule = {}}+const scriptsAreEntrypointShims = createTextRule(+ 'open-pencil/scripts-are-entrypoint-shims',+ (sourceRel, content) => {+ if (!sourceRel.startsWith('scripts/')) return []+ if (/^#!\/usr\/bin\/env bun\s+import ['"]\.\.\/tools\/[^'"]+['"]\s*;?$/u.test(content.trim())) return []+ return [{ message: 'Root scripts must be tiny shims. Move implementation logic into tools/<domain>/.' }]+ }+)++const TOOL_LAYOUT_MESSAGE = 'Tool files must live under tools/<domain>/src/** or tools/<domain>/tests/*.test.ts.'++const strictToolsLayout = createFileRule('open-pencil/strict-tools-layout', (sourceRel) => {+ if (!sourceRel.startsWith('tools/') || !TEXT_EXTENSIONS.has(path.extname(sourceRel))) return null+ if (sourceRel === 'tools/test.ts') return null+ const [, domain, segment] = sourceRel.split('/')+ if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(domain)) return 'Tool package folders must use kebab-case domain names.'+ if (segment === 'src') return null+ if (segment === 'tests' && sourceRel.endsWith('.test.ts')) return null+ return TOOL_LAYOUT_MESSAGE+})+const strictTestFilePlacement = createFileRule('open-pencil/strict-test-file-placement',(sourceRel) => {@@ -549,6 +570,8 @@ export const openPencilArchitecturePlugin = {meta: { name: 'open-pencil-architecture', version: '0.0.0' },ruleDefinitions: [preferDomainFoldersOverFilenamePrefixes,+ scriptsAreEntrypointShims,+ strictToolsLayout,strictTestFilePlacement,noMisplacedEngineTestDomainPaths,noKitchenSinkEngineBasicTests,diff --git a/tools/i18n/package.json b/tools/i18n/package.jsonnew file mode 100644index 000000000..0dd2ae1b5--- /dev/null+++ b/tools/i18n/package.json@@ -0,0 +1,5 @@+{+ "name": "@open-pencil/i18n-tools",+ "private": true,+ "type": "module"+}diff --git a/scripts/check-locales.ts b/tools/i18n/src/check-locales.tssimilarity index 100%rename from scripts/check-locales.tsrename to tools/i18n/src/check-locales.tsdiff --git a/tools/package-quality/package.json b/tools/package-quality/package.jsonnew file mode 100644index 000000000..a81073e2d--- /dev/null+++ b/tools/package-quality/package.json@@ -0,0 +1,5 @@+{+ "name": "@open-pencil/package-quality-tools",+ "private": true,+ "type": "module"+}diff --git a/scripts/check-package-metadata.ts b/tools/package-quality/src/check-metadata.tssimilarity index 100%rename from scripts/check-package-metadata.tsrename to tools/package-quality/src/check-metadata.tsdiff --git a/scripts/smoke-packages.ts b/tools/package-quality/src/smoke.tssimilarity index 97%rename from scripts/smoke-packages.tsrename to tools/package-quality/src/smoke.tsindex a8b72af2d..216e46943 100644--- a/scripts/smoke-packages.ts+++ b/tools/package-quality/src/smoke.ts@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os'import { basename, join } from 'node:path'import { fileURLToPath } from 'node:url'-const rootDir = fileURLToPath(new URL('..', import.meta.url))+const rootDir = fileURLToPath(new URL('../../..', import.meta.url))const packageDirs = ['packages/core', 'packages/vue', 'packages/mcp', 'packages/cli']function run(command: string[], cwd = rootDir): string {diff --git a/tools/tauri-menu/package.json b/tools/tauri-menu/package.jsonnew file mode 100644index 000000000..2a2001a51--- /dev/null+++ b/tools/tauri-menu/package.json@@ -0,0 +1,5 @@+{+ "name": "@open-pencil/tauri-menu-tools",+ "private": true,+ "type": "module"+}diff --git a/tools/tauri-menu/src/generate.ts b/tools/tauri-menu/src/generate.tsnew file mode 100644index 000000000..d241c3faa--- /dev/null+++ b/tools/tauri-menu/src/generate.ts@@ -0,0 +1,35 @@+import { mkdirSync, writeFileSync } from 'node:fs'+import { dirname } from 'node:path'++import { APP_MENU_SCHEMA } from '@/app/shell/menu/schema'+import type { AppMenuEntry, AppMenuGroupSchema } from '@/app/shell/menu/schema'+import { shortcutTokenToAccelerator } from '@/app/shell/menu/shortcut'++function isNativeVisible(entry: { target?: string }): boolean {+ return entry.target !== 'browser'+}++function cleanEntry(entry: AppMenuEntry): unknown | null {+ if (!isNativeVisible(entry)) return null+ if (entry.type === 'separator') return { type: 'separator' }+ return {+ id: entry.id,+ label: entry.label,+ accelerator: entry.accelerator ?? shortcutTokenToAccelerator(entry.shortcut),+ checkbox: entry.checkbox,+ sub: entry.sub?.map(cleanEntry).filter(Boolean)+ }+}++function cleanGroup(group: AppMenuGroupSchema): unknown | null {+ if (!isNativeVisible(group)) return null+ return {+ label: group.label,+ items: group.items.map(cleanEntry).filter(Boolean)+ }+}++const outputPath = 'desktop/generated/menu.json'+const menu = APP_MENU_SCHEMA.map(cleanGroup).filter(Boolean)+mkdirSync(dirname(outputPath), { recursive: true })+writeFileSync(outputPath, `${JSON.stringify(menu, null, 2)}\n`)diff --git a/tools/type-shapes/package.json b/tools/type-shapes/package.jsonnew file mode 100644index 000000000..0365037c7--- /dev/null+++ b/tools/type-shapes/package.json@@ -0,0 +1,5 @@+{+ "name": "@open-pencil/type-shapes-tools",+ "private": true,+ "type": "module"+}diff --git a/scripts/type-shapes.ts b/tools/type-shapes/src/index.tssimilarity index 99%rename from scripts/type-shapes.tsrename to tools/type-shapes/src/index.tsindex c66c0cf50..13c93aa09 100644--- a/scripts/type-shapes.ts+++ b/tools/type-shapes/src/index.ts@@ -7,7 +7,8 @@ const roots = ['packages/cli/src','packages/mcp/src','tests',- 'scripts'+ 'scripts',+ 'tools']type ShapeLocation = { file: string; line: number; name: string }diff --git a/tools/visual-oracles/package.json b/tools/visual-oracles/package.jsonnew file mode 100644index 000000000..18abfc624--- /dev/null+++ b/tools/visual-oracles/package.json@@ -0,0 +1,5 @@+{+ "name": "@open-pencil/visual-oracle-tools",+ "private": true,+ "type": "module"+}diff --git a/scripts/analyze-pattern-oracle.ts b/tools/visual-oracles/src/analyze-pattern.tssimilarity index 100%rename from scripts/analyze-pattern-oracle.tsrename to tools/visual-oracles/src/analyze-pattern.tsdiff --git a/scripts/analyze-text-decoration-oracle.ts b/tools/visual-oracles/src/analyze-text-decoration.tssimilarity index 100%rename from scripts/analyze-text-decoration-oracle.tsrename to tools/visual-oracles/src/analyze-text-decoration.tsdiff --git a/tools/visual-oracles/src/bisect.ts b/tools/visual-oracles/src/bisect.tsnew file mode 100644index 000000000..4c14065bd--- /dev/null+++ b/tools/visual-oracles/src/bisect.ts@@ -0,0 +1,334 @@+#!/usr/bin/env bun++import { existsSync, mkdirSync } from 'node:fs'+import { basename } from 'node:path'+import { parseArgs } from 'node:util'++import { $ } from 'bun'++import { parseColor } from '@open-pencil/core/color'+import { headlessRenderNodes, initCanvasKit, parseFigFile } from '@open-pencil/core/io'+import { computeAllLayouts } from '@open-pencil/core/layout'+import type { SceneGraph } from '@open-pencil/core/scene-graph'++interface DiffMetrics {+ mean: number+ above5: number+ above10: number+ above20: number+ above40: number+ above80: number+}++interface BisectResult {+ depth: number+ indices: number[]+ names: string[]+ metrics: DiffMetrics+ figmaPath: string+ openPencilPath: string+}++const { values, positionals } = parseArgs({+ allowPositionals: true,+ options: {+ page: { type: 'string', short: 'p' },+ 'figma-page-id': { type: 'string' },+ output: { type: 'string', short: 'o', default: '/tmp/open-pencil-visual-bisect' },+ scale: { type: 'string', default: '1' },+ threshold: { type: 'string', default: '0.25' },+ depth: { type: 'string', default: '8' },+ 'min-size': { type: 'string', default: '1' },+ background: { type: 'string', default: '#f9f9f9' },+ 'root-node-id': { type: 'string' },+ 'figma-root-id': { type: 'string' }+ }+})++const figPath = positionals[0]+if (!figPath || !values.page || !values['figma-page-id']) {+ console.error(`Usage:+ bun scripts/visual-bisect.ts <file.fig> --page Primitives --figma-page-id 1:22 [options]++Options:+ --output DIR Output directory (default: /tmp/open-pencil-visual-bisect)+ --scale N Export scale (default: 1)+ --threshold PERCENT Stop splitting groups under this >40 diff percent (default: 0.25)+ --depth N Max bisection depth (default: 8)+ --min-size N Stop splitting groups at this child count (default: 1)+ --background HEX Matte color for transparent pixels (default: #f9f9f9)+ --root-node-id ID OpenPencil node whose children should be bisected+ --figma-root-id ID Matching Figma node whose children should be bisected++What it does:+ It hides all top-level page children except a candidate subset in both Figma+ and OpenPencil, exports that subset from both renderers, diffs the images,+ then recursively splits only subsets that still differ. This isolates which+ top-level page children introduce visual differences without staring at the+ full-page diff.`)+ process.exit(1)+}++const pageName = values.page+const figmaPageId = values['figma-page-id']+const outputDir = values.output ?? '/tmp/open-pencil-visual-bisect'+const scale = Number(values.scale ?? '1')+const threshold = Number(values.threshold ?? '0.25')+const maxDepth = Number(values.depth ?? '8')+const minSize = Number(values['min-size'] ?? '1')+const matteColor = colorBytes(values.background ?? '#f9f9f9')++if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true })++const graph = await loadGraph(figPath, pageName)+const page = graph.getPages().find((candidate) => candidate.name === pageName)+if (!page) throw new Error(`Page not found in .fig: ${pageName}`)+const rootNodeId = values['root-node-id'] ?? page.id+const figmaRootId = values['figma-root-id'] ?? figmaPageId+const rootNode = graph.getNode(rootNodeId)+if (!rootNode) throw new Error(`Root node not found in .fig: ${rootNodeId}`)+const childIds = [...rootNode.childIds]+const childNames = childIds.map((id) => graph.getNode(id)?.name ?? id)++console.log(`Visual bisect: ${basename(figPath)} / ${pageName}`)+console.log(`Root: ${rootNode.name} (${rootNode.id})`)+console.log(`Children: ${childIds.length}`)+console.log(`Output: ${outputDir}`)++const initialVisibility = await captureFigmaVisibility(figmaRootId)+const results: BisectResult[] = []++try {+ await bisect(+ childIds.map((_, index) => index),+ 0+ )+} finally {+ await restoreFigmaVisibility(figmaRootId, initialVisibility)+}++results.sort((a, b) => b.metrics.above40 - a.metrics.above40 || a.indices.length - b.indices.length)+await writeReport(results)++console.log('\nTop suspects:')+for (const result of results.slice(0, 12)) {+ console.log(+ `${result.indices.join(',')} | >40 ${result.metrics.above40.toFixed(3)}% | ${result.names.join(' / ')}`+ )+}+console.log(`\nReport: ${outputDir}/report.md`)++async function loadGraph(path: string, targetPageName: string): Promise<SceneGraph> {+ const bytes = new Uint8Array(await Bun.file(path).arrayBuffer())+ const parsed = await parseFigFile(+ bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),+ {+ populate: 'all'+ }+ )+ const targetPage = parsed.getPages().find((candidate) => candidate.name === targetPageName)+ if (targetPage) computeAllLayouts(parsed, targetPage.id)+ return parsed+}++async function bisect(indices: number[], depth: number): Promise<void> {+ if (indices.length === 0 || depth > maxDepth) return++ const result = await compareSubset(indices, depth)+ const label = `[depth ${depth}] [${indices.join(',')}] >40=${result.metrics.above40.toFixed(3)}% ${result.names.join(' / ')}`+ console.log(label)++ if (result.metrics.above40 <= threshold) return+ results.push(result)++ if (indices.length <= minSize) return+ const mid = Math.floor(indices.length / 2)+ await bisect(indices.slice(0, mid), depth + 1)+ await bisect(indices.slice(mid), depth + 1)+}++async function compareSubset(indices: number[], depth: number): Promise<BisectResult> {+ const stem = `d${depth}-${indices[0]}-${indices.at(-1)}-${indices.length}`+ const figmaPath = `${outputDir}/${stem}-figma.png`+ const openPencilPath = `${outputDir}/${stem}-open-pencil.png`++ await exportFigmaSubset(figmaRootId, indices, figmaPath)+ await exportOpenPencilSubset(indices, openPencilPath)++ return {+ depth,+ indices,+ names: indices.map((index) => childNames[index]),+ metrics: await diffImages(figmaPath, openPencilPath),+ figmaPath,+ openPencilPath+ }+}++async function exportOpenPencilSubset(indices: number[], path: string): Promise<void> {+ const indexSet = new Set(indices)+ const changed: Array<{ id: string; visible: boolean }> = []+ for (let index = 0; index < childIds.length; index++) {+ const node = graph.getNode(childIds[index])+ if (!node) continue+ changed.push({ id: node.id, visible: node.visible })+ node.visible = indexSet.has(index)+ }++ try {+ const nodeIds =+ rootNode.type === 'CANVAS' ? indices.map((index) => childIds[index]) : [rootNode.id]+ const data = await headlessRenderNodes(graph, page.id, nodeIds, {+ scale,+ format: 'PNG',+ trimTransparent: nodeIds.every((id) => graph.getNode(id)?.type === 'TEXT')+ })+ if (!data) throw new Error(`OpenPencil render produced no image for ${indices.join(',')}`)+ await Bun.write(path, data)+ } finally {+ for (const entry of changed) {+ const node = graph.getNode(entry.id)+ if (node) node.visible = entry.visible+ }+ }+}++async function exportFigmaSubset(pageId: string, indices: number[], path: string): Promise<void> {+ await setFigmaVisibleIndices(pageId, indices)+ await $`figma-use export node ${pageId} --output ${path} --scale ${String(scale)}`.quiet()+}++async function captureFigmaVisibility(pageId: string): Promise<boolean[]> {+ const code = `+ const node = figma.getNodeById(${JSON.stringify(pageId)});+ if (!node || !('children' in node)) throw new Error('Node has no children: ${pageId}');+ return node.children.map((child) => child.visible);+ `+ const out = await $`figma-use eval ${code} --json`.quiet()+ return JSON.parse(out.text().trim())+}++async function setFigmaVisibleIndices(pageId: string, indices: number[]): Promise<void> {+ const code = `+ const visible = new Set(${JSON.stringify(indices)});+ const node = figma.getNodeById(${JSON.stringify(pageId)});+ if (!node || !('children' in node)) throw new Error('Node has no children: ${pageId}');+ node.children.forEach((child, index) => { child.visible = visible.has(index); });+ `+ await $`figma-use eval ${code}`.quiet()+}++async function restoreFigmaVisibility(pageId: string, visibility: boolean[]): Promise<void> {+ const code = `+ const visibility = ${JSON.stringify(visibility)};+ const node = figma.getNodeById(${JSON.stringify(pageId)});+ if (!node || !('children' in node)) return;+ node.children.forEach((child, index) => { child.visible = visibility[index] ?? child.visible; });+ `+ await $`figma-use eval ${code}`.quiet().nothrow()+}++async function diffImages(expectedPath: string, actualPath: string): Promise<DiffMetrics> {+ const ck = await initCanvasKit()+ const expected = ck.MakeImageFromEncoded(await Bun.file(expectedPath).bytes())+ const actual = ck.MakeImageFromEncoded(await Bun.file(actualPath).bytes())+ if (!expected || !actual) throw new Error('Failed to decode PNGs')++ try {+ const width = Math.min(expected.width(), actual.width())+ const height = Math.min(expected.height(), actual.height())+ const imageInfo = {+ width,+ height,+ colorType: ck.ColorType.RGBA_8888,+ alphaType: ck.AlphaType.Unpremul,+ colorSpace: ck.ColorSpace.SRGB+ }+ const expectedPixels = expected.readPixels(0, 0, imageInfo)+ const actualPixels = actual.readPixels(0, 0, imageInfo)+ if (!expectedPixels || !actualPixels) throw new Error('Failed to read image pixels')++ let sum = 0+ let above5 = 0+ let above10 = 0+ let above20 = 0+ let above40 = 0+ let above80 = 0+ const total = width * height+ const bg = matteColor+ for (let pixel = 0; pixel < total; pixel++) {+ const offset = pixel * 4+ const expectedRgb = compositeRgb(expectedPixels, offset, bg)+ const actualRgb = compositeRgb(actualPixels, offset, bg)+ const dr = Math.abs(expectedRgb[0] - actualRgb[0])+ const dg = Math.abs(expectedRgb[1] - actualRgb[1])+ const db = Math.abs(expectedRgb[2] - actualRgb[2])+ const max = Math.max(dr, dg, db)+ sum += dr + dg + db+ if (max > 5) above5+++ if (max > 10) above10+++ if (max > 20) above20+++ if (max > 40) above40+++ if (max > 80) above80+++ }++ return {+ mean: sum / total,+ above5: (above5 / total) * 100,+ above10: (above10 / total) * 100,+ above20: (above20 / total) * 100,+ above40: (above40 / total) * 100,+ above80: (above80 / total) * 100+ }+ } finally {+ expected.delete()+ actual.delete()+ }+}++async function writeReport(items: BisectResult[]): Promise<void> {+ const lines = [+ `# Visual bisect report`,+ ``,+ `- File: ${figPath}`,+ `- Page: ${pageName}`,+ `- Figma page id: ${figmaPageId}`,+ `- Scale: ${scale}`,+ `- Threshold (>40): ${threshold}%`,+ ``,+ `| depth | indices | >40 | >20 | mean | names | images |`,+ `|---:|---|---:|---:|---:|---|---|`+ ]++ for (const item of items) {+ lines.push(+ `| ${item.depth} | ${item.indices.join(',')} | ${item.metrics.above40.toFixed(3)}% | ${item.metrics.above20.toFixed(3)}% | ${item.metrics.mean.toFixed(3)} | ${item.names.map(escapePipes).join('<br>')} | [figma](${item.figmaPath}) / [open-pencil](${item.openPencilPath}) |`+ )+ }++ await Bun.write(`${outputDir}/report.md`, `${lines.join('\n')}\n`)+}++function colorBytes(input: string): readonly [number, number, number] {+ const color = parseColor(input)+ return [color.r * 255, color.g * 255, color.b * 255]+}++function compositeRgb(+ pixels: Uint8Array,+ offset: number,+ bg: readonly [number, number, number]+): [number, number, number] {+ const alpha = pixels[offset + 3] / 255+ if (alpha >= 1) return [pixels[offset], pixels[offset + 1], pixels[offset + 2]]+ if (alpha <= 0) return [bg[0], bg[1], bg[2]]+ return [+ pixels[offset] * alpha + bg[0] * (1 - alpha),+ pixels[offset + 1] * alpha + bg[1] * (1 - alpha),+ pixels[offset + 2] * alpha + bg[2] * (1 - alpha)+ ]+}++function escapePipes(value: string): string {+ return value.replaceAll('|', '\\|')+}diff --git a/tools/visual-oracles/src/compare.ts b/tools/visual-oracles/src/compare.tsnew file mode 100644index 000000000..7a181c1b1--- /dev/null+++ b/tools/visual-oracles/src/compare.ts@@ -0,0 +1,295 @@+#!/usr/bin/env bun+/**+ * Visual comparison pipeline: Figma vs OpenPencil renderer.+ *+ * Copy an element in Figma, then run:+ * bun scripts/visual-compare.ts [--scale 2] [--output /tmp/visual-compare]+ *+ * Or pass a node ID directly (skips clipboard):+ * bun scripts/visual-compare.ts --node 1:23 [--scale 2]+ *+ * Outputs:+ * figma.png — exported from real Figma+ * ours.png — rendered by OpenPencil headless SkiaRenderer+ * diff.png — visual diff (red = changed pixels)+ */++import { existsSync, mkdirSync, writeFileSync } from 'node:fs'+import { parseArgs } from 'node:util'++import { $ } from 'bun'++import { SkiaRenderer } from '@open-pencil/core/canvas'+import { importClipboardNodes, parseFigmaClipboard } from '@open-pencil/core/clipboard'+import { renderNodesToImage, initCanvasKit } from '@open-pencil/core/io'+import { computeAllLayouts } from '@open-pencil/core/layout'+import { SceneGraph } from '@open-pencil/core/scene-graph'+import { fontManager } from '@open-pencil/core/text'++const { values: opts } = parseArgs({+ options: {+ scale: { type: 'string', default: '2' },+ output: { type: 'string', short: 'o', default: '/tmp/visual-compare' },+ node: { type: 'string', short: 'n' },+ resize: { type: 'boolean', default: false },+ fuzz: { type: 'string', default: '1%' },+ 'alpha-diff': { type: 'boolean', default: false },+ 'metrics-json': { type: 'string' }+ }+})++const scale = Number(opts.scale)+const outputDir = opts.output ?? '/tmp/visual-compare'+const figmaPath = `${outputDir}/figma.png`+const oursPath = `${outputDir}/ours.png`+const normalizedOursPath = `${outputDir}/ours-normalized.png`+const diffPath = `${outputDir}/diff.png`+const metricsPath = opts['metrics-json'] ?? `${outputDir}/metrics.json`+const alphaFigmaPath = `${outputDir}/figma-alpha.png`+const alphaOursPath = `${outputDir}/ours-alpha.png`+const alphaDiffPath = `${outputDir}/diff-alpha.png`++if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true })++if (opts.node) {+ await runWithNodeId(opts.node)+} else {+ await runWithClipboard()+}++// --- Mode 1: Clipboard ---++async function runWithClipboard() {+ console.log('📋 Reading clipboard…')+ const html = await readClipboardHtml()+ if (!html) bail('No HTML on clipboard. Copy an element in Figma first.')++ const parsed = await parseFigmaClipboard(html)+ if (!parsed) bail('Clipboard has no Figma data. Copy an element in Figma first.')+ console.log(` ${parsed.nodes.length} node changes, ${parsed.blobs.length} blobs`)++ console.log('🖼️ Rendering with OpenPencil…')+ await renderOurs(html)++ console.log('🎨 Pasting into Figma & exporting…')+ await ensureFigmaConnected()+ await renderFigmaViaPaste()++ await diff()+}++// --- Mode 2: Node ID ---++async function runWithNodeId(nodeId: string) {+ await ensureFigmaConnected()++ console.log(`🎨 Exporting node ${nodeId} from Figma…`)+ await $`figma-use export node ${nodeId} --output ${figmaPath} --scale ${String(scale)}`.quiet()+ console.log(` → ${figmaPath}`)++ console.log('📋 Exporting clipboard data from Figma…')+ // Select the node, copy, read clipboard, render with our engine+ const nodeIdLiteral = JSON.stringify(nodeId)+ await $`figma-use eval ${`const n = figma.getNodeById(${nodeIdLiteral}); if (!n) return; let page = n.parent; while (page && page.type !== 'PAGE') page = page.parent; if (page) { await figma.setCurrentPageAsync(page); page.selection = [n]; }`}`.quiet()+ await Bun.sleep(200)+ await $`osascript -e 'tell application "Figma" to activate'`.quiet()+ await Bun.sleep(300)+ await $`osascript -e 'tell application "System Events" to keystroke "c" using command down'`.quiet()+ await Bun.sleep(1000)++ const html = await readClipboardHtml()+ if (!html) bail('Failed to copy from Figma')+ const parsed = await parseFigmaClipboard(html)+ if (!parsed) bail('Clipboard has no Figma data after copy')++ console.log('🖼️ Rendering with OpenPencil…')+ await renderOurs(html)++ await diff()+}++// --- Rendering ---++async function renderOurs(html: string) {+ const result = await parseFigmaClipboard(html)+ if (!result) throw new Error('Failed to parse clipboard')++ const graph = new SceneGraph()+ const pageId = graph.getPages()[0].id++ const createdIds = importClipboardNodes(result.nodes, graph, pageId, 0, 0, result.blobs)+ if (createdIds.length === 0) throw new Error('No nodes imported from clipboard')++ computeAllLayouts(graph)++ const families = new Set<string>()+ for (const node of graph.getAllNodes()) {+ if (node.fontFamily) families.add(node.fontFamily)+ }+ for (const family of families) {+ await fontManager.loadFont(family)+ }++ const ck = await initCanvasKit()+ const surface = ck.MakeSurface(1, 1)+ if (!surface) throw new Error('Failed to create CanvasKit surface')+ const renderer = new SkiaRenderer(ck, surface)+ renderer.viewportWidth = 1+ renderer.viewportHeight = 1+ renderer.dpr = 1++ const data = renderNodesToImage(ck, renderer, graph, pageId, createdIds, {+ scale,+ format: 'PNG'+ })++ surface.delete()+ if (!data) throw new Error('Render produced no image')+ await Bun.write(oursPath, data)+ console.log(` → ${oursPath}`)+}++async function renderFigmaViaPaste() {+ // Create temp page so we don't pollute the user's work+ await $`figma-use eval ${'(() => { const p = figma.createPage(); p.name = "__visual_compare__"; figma.currentPage = p; return p.id; })()'} --json`.quiet()++ try {+ // Activate Figma and paste+ await $`osascript -e 'tell application "Figma" to activate'`.quiet()+ await Bun.sleep(500)+ await $`osascript -e 'tell application "System Events" to keystroke "v" using command down'`.quiet()+ await Bun.sleep(2000)++ // Get pasted selection+ const selJson = await $`figma-use selection get --json`.quiet()+ const selection = JSON.parse(selJson.text().trim())+ if (!selection.length) throw new Error('Nothing pasted. Ensure clipboard has Figma data.')++ const nodeId = selection[0].id++ // Export from Figma+ await $`figma-use export node ${nodeId} --output ${figmaPath} --scale ${String(scale)}`.quiet()+ console.log(` → ${figmaPath}`)+ } finally {+ // Clean up: remove temp page+ await $`figma-use eval ${'(() => { const ps = figma.root.children; const tmp = ps.find(p => p.name === "__visual_compare__"); if (tmp) { const other = ps.find(p => p !== tmp); if (other) figma.currentPage = other; tmp.remove(); } })()'}`+ .quiet()+ .nothrow()+ }+}++// --- Diff ---++async function diff() {+ console.log('🔍 Computing diff…')++ const figmaSize = (await $`identify -format '%wx%h' ${figmaPath}`.quiet()).text().trim()+ const oursSize = (await $`identify -format '%wx%h' ${oursPath}`.quiet()).text().trim()++ const compareOursPath = figmaSize === oursSize ? oursPath : normalizedOursPath+ if (figmaSize !== oursSize) {+ const mode = opts.resize ? 'resizing' : 'padding/cropping without scaling'+ console.log(` ⚠ Size mismatch: Figma ${figmaSize}, Ours ${oursSize} → ${mode}`)+ if (opts.resize) {+ await $`magick ${oursPath} -resize ${figmaSize}! ${normalizedOursPath}`.quiet()+ } else {+ await $`magick ${oursPath} -background none -gravity northwest -extent ${figmaSize} ${normalizedOursPath}`.quiet()+ }+ }++ const result =+ await $`magick compare -metric AE -highlight-color red -lowlight-color '#FFFFFF33' -compose src ${figmaPath} ${compareOursPath} ${diffPath}`+ .quiet()+ .nothrow()++ const fuzzResult =+ await $`magick compare -metric AE -fuzz ${opts.fuzz} ${figmaPath} ${compareOursPath} null:`+ .quiet()+ .nothrow()+ const rmseResult = await $`magick compare -metric RMSE ${figmaPath} ${compareOursPath} null:`+ .quiet()+ .nothrow()+ const rmse = rmseResult.stderr.toString().trim()+ const diffPixels = Number.parseInt(result.stderr.toString().trim(), 10) || 0+ const fuzzPixels = Number.parseInt(fuzzResult.stderr.toString().trim(), 10) || 0+ const [w, h] = figmaSize.split('x').map(Number)+ const total = w * h+ const pct = (diffPixels / total) * 100+ const fuzzPct = (fuzzPixels / total) * 100+ const alphaMetrics = opts['alpha-diff'] ? await diffAlpha(compareOursPath, total) : null+ const metrics = {+ figmaSize,+ openPencilSize: oursSize,+ comparedOpenPencilPath: compareOursPath,+ resized: Boolean(opts.resize && figmaSize !== oursSize),+ normalized: figmaSize !== oursSize,+ differentPixels: diffPixels,+ differentPercent: Number(pct.toFixed(2)),+ fuzz: opts.fuzz,+ fuzzDifferentPixels: fuzzPixels,+ fuzzDifferentPercent: Number(fuzzPct.toFixed(2)),+ rmse,+ alpha: alphaMetrics+ }+ writeFileSync(metricsPath, `${JSON.stringify(metrics, null, 2)}\n`)++ console.log(` → ${diffPath}`)+ console.log(+ ` ${diffPixels.toLocaleString()} different pixels (${pct.toFixed(2)}% of ${total.toLocaleString()})`+ )+ console.log(+ ` ${fuzzPixels.toLocaleString()} different pixels with ${opts.fuzz} fuzz (${fuzzPct.toFixed(2)}%)`+ )+ console.log(` RMSE ${rmse}`)+ if (alphaMetrics) {+ console.log(+ ` Alpha AE ${alphaMetrics.differentPixels.toLocaleString()} pixels (${alphaMetrics.differentPercent.toFixed(2)}%)`+ )+ }+ console.log(` Metrics → ${metricsPath}`)+ console.log(`\n✅ Done! Images in ${outputDir}/`)+}++async function diffAlpha(compareOursPath: string, total: number) {+ await $`magick ${figmaPath} -alpha extract ${alphaFigmaPath}`.quiet()+ await $`magick ${compareOursPath} -alpha extract ${alphaOursPath}`.quiet()+ const result =+ await $`magick compare -metric AE -highlight-color red -lowlight-color '#FFFFFF33' -compose src ${alphaFigmaPath} ${alphaOursPath} ${alphaDiffPath}`+ .quiet()+ .nothrow()+ const differentPixels = Number.parseInt(result.stderr.toString().trim(), 10) || 0+ return {+ path: alphaDiffPath,+ differentPixels,+ differentPercent: (differentPixels / total) * 100+ }+}++// --- Helpers ---++async function readClipboardHtml(): Promise<string | null> {+ const proc = Bun.spawn(+ [+ 'swift',+ '-e',+ 'import AppKit; if let h = NSPasteboard.general.string(forType: .html) { print(h) } else { exit(1) }'+ ],+ { stdout: 'pipe', stderr: 'pipe' }+ )+ const text = await new Response(proc.stdout).text()+ return (await proc.exited) === 0 ? text.trim() : null+}++async function ensureFigmaConnected() {+ const s = await $`figma-use status`.quiet().nothrow()+ if (s.exitCode !== 0) {+ bail(+ 'figma-use not connected. Start Figma with:\n open -a Figma --args --remote-debugging-port=9222'+ )+ }+}++function bail(msg: string): never {+ console.error(msg)+ process.exit(1)+}diff --git a/tools/visual-oracles/src/export-fixtures.ts b/tools/visual-oracles/src/export-fixtures.tsnew file mode 100644index 000000000..4bba74d11--- /dev/null+++ b/tools/visual-oracles/src/export-fixtures.ts@@ -0,0 +1,55 @@+#!/usr/bin/env bun++import { mkdirSync } from 'node:fs'+import { parseArgs } from 'node:util'++import { $ } from 'bun'++interface FixtureExportTarget {+ file: string+ page: string+ outputName: string+ heavy?: boolean+}++const TARGETS: FixtureExportTarget[] = [+ {+ file: 'tests/fixtures/gold-preview.fig',+ page: 'Page 1',+ outputName: 'gold-preview-page-1.png'+ },+ {+ file: 'tests/fixtures/material3.fig',+ page: 'Getting started',+ outputName: 'material3-getting-started.png'+ },+ {+ file: 'tests/fixtures/nuxtui.fig',+ page: 'Components',+ outputName: 'nuxtui-components.png',+ heavy: true+ }+]++const { values } = parseArgs({+ options: {+ output: { type: 'string', short: 'o', default: '/tmp/open-pencil-fixture-visuals' },+ heavy: { type: 'boolean', default: false }+ }+})++const outputDir = values.output ?? '/tmp/open-pencil-fixture-visuals'+mkdirSync(outputDir, { recursive: true })++for (const target of TARGETS) {+ if (target.heavy && !values.heavy) {+ console.log(`Skipping ${target.file} (${target.page}); pass --heavy to include it.`)+ continue+ }++ const outputPath = `${outputDir}/${target.outputName}`+ console.log(`Exporting ${target.file} / ${target.page} → ${outputPath}`)+ await $`bun open-pencil export ${target.file} --page ${target.page} --output ${outputPath}`+}++console.log(`Fixture visuals written to ${outputDir}`)diff --git a/scripts/pixel-image.ts b/tools/visual-oracles/src/pixel-image.tssimilarity index 100%rename from scripts/pixel-image.tsrename to tools/visual-oracles/src/pixel-image.tsdiff --git a/scripts/update-visual-report.ts b/tools/visual-oracles/src/update-report.tssimilarity index 100%rename from scripts/update-visual-report.tsrename to tools/visual-oracles/src/update-report.ts