AI-native design editor. Open-source Figma alternative.
Add heuristic overlap detection tool and CLI
Joseph Cuminesf862beb08d6c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex eaeb0de22..4ab0b1f08 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,10 @@- Add JSX authoring support for components, component sets, and instances.- Add type-validated `bindVariable`/`unbindVariable` with event emission and indexed binding format (`fills/N/color` instead of `fills[N]`).- Add `unbind_variable` MCP tool for removing variable bindings.+- Add `openpencil analyze overlaps`, the `analyze_overlaps` RPC command, and the `analyze_overlaps` ToolDef for heuristic overlap detection. The command reports sibling overlaps, children overflowing non-clipping parents, and overlay/backdrop patterns, with filters for page/page ID, scope, category, severity, min area/ratio, node type, hidden/locked/absolute nodes, result limit, and `--json` output.+- Add overlap analysis exports for automation consumers, including `computeOverlaps`, `analyzeOverlaps`, overlap result types, and parameter parsers from core subpath exports.+- Add world-matrix visual bounds to overlap analysis, covering vector/stroke/text geometry, ancestor clipping, rotated clipping frames, and nested ancestor rotations.+- Add the `@open-pencil/core/package.json` subpath export for package metadata consumers.### Fixes@@ -18,6 +22,7 @@- Improve Figma boolean imports by preserving XOR operations as editable exclude nodes and falling back to imported fill geometry when boolean path reconstruction cannot produce a path.- Preserve rotated Figma transform origins for imported vector nodes.- Render complex text fills through vector glyph outlines so imported Figma text can use the normal fill pipeline for gradients, images, patterns, and other non-solid paints.+- Fix file-backed CLI commands (`convert`, `eval --output`, `export`) to use Node `fs/promises` instead of Bun runtime APIs, so the published CLI works when installed and run under Node.## 0.13.2 — 2026-05-30diff --git a/README.md b/README.mdindex f2c3b6fa1..a369dcdce 100644--- a/README.md+++ b/README.md@@ -111,6 +111,7 @@ openpencil analyze colors design.figopenpencil analyze typography design.figopenpencil analyze spacing design.figopenpencil analyze clusters design.fig+openpencil analyze overlaps design.figopenpencil variables design.fig```diff --git a/packages/cli/src/commands/analyze/index.ts b/packages/cli/src/commands/analyze/index.tsindex a4cb7818f..39b0543b4 100644--- a/packages/cli/src/commands/analyze/index.ts+++ b/packages/cli/src/commands/analyze/index.ts@@ -2,6 +2,7 @@ import { defineCommand } from 'citty'import clusters from './clusters'import colors from './colors'+import overlaps from './overlaps'import spacing from './spacing'import typography from './typography'@@ -11,6 +12,7 @@ export default defineCommand({colors,typography,spacing,- clusters+ clusters,+ overlaps}})diff --git a/packages/cli/src/commands/analyze/overlaps.ts b/packages/cli/src/commands/analyze/overlaps.tsnew file mode 100644index 000000000..6f5ed9c00--- /dev/null+++ b/packages/cli/src/commands/analyze/overlaps.ts@@ -0,0 +1,264 @@+import { defineCommand } from 'citty'++import type { AnalyzeOverlapsResult } from '@open-pencil/core/rpc'+import {+ VALID_OVERLAP_CATEGORIES,+ VALID_OVERLAP_SCOPES,+ VALID_OVERLAP_SEVERITIES,+ parseOverlapCategories,+ parseOverlapScope,+ parseOverlapSeverity+} from '@open-pencil/core/tools'++import { bold, fail, fmtList, fmtSummary, kv } from '#cli/format'+import { loadRpcData } from '#cli/rpc-data'++function validateScope(scope: string): string | undefined {+ const normalized = scope.toLowerCase()+ return (VALID_OVERLAP_SCOPES as readonly string[]).includes(normalized)+ ? undefined+ : `Invalid scope "${scope}". Must be one of: ${[...VALID_OVERLAP_SCOPES].join(', ')}`+}++function validateSeverity(severity: string): string | undefined {+ const normalized = severity.toLowerCase()+ return (VALID_OVERLAP_SEVERITIES as readonly string[]).includes(normalized)+ ? undefined+ : `Invalid severity "${severity}". Must be one of: ${[...VALID_OVERLAP_SEVERITIES].join(', ')}`+}++function validateMinRatio(minRatio: number | undefined): string | undefined {+ if (minRatio === undefined) return undefined+ if (Number.isNaN(minRatio) || minRatio < 0 || minRatio > 1) {+ return '--min-ratio must be a number between 0.0 and 1.0'+ }+ return undefined+}++function validateLimit(limit: string): string | undefined {+ const value = Number(limit)+ if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {+ return '--limit must be a positive integer'+ }+ return undefined+}++function validateMinArea(minArea: string): string | undefined {+ const value = Number(minArea)+ if (!Number.isFinite(value) || value < 0) {+ return '--min-area must be a non-negative number'+ }+ return undefined+}++function validateCategory(category: string): string | undefined {+ const values = category+ .split(',')+ .map((c) => c.trim().toLowerCase())+ .filter((c) => c.length > 0)+ if (values.length === 0) return undefined+ const validCount = (parseOverlapCategories(category) ?? []).length+ if (validCount === 0) {+ return `Invalid categories: ${values.join(', ')}. Must be one or more of: ${[...VALID_OVERLAP_CATEGORIES].join(', ')}`+ }+ const invalid = values.filter((c) => !(VALID_OVERLAP_CATEGORIES as readonly string[]).includes(c))+ if (invalid.length > 0) {+ return `Invalid categor${invalid.length === 1 ? 'y' : 'ies'}: ${invalid.join(', ')}. Must be one or more of: ${[...VALID_OVERLAP_CATEGORIES].join(', ')}`+ }+ return undefined+}++function collectValidationError(args: {+ scope: string+ severity: string+ category?: string+ limit: string+ 'min-area'?: string+ 'min-ratio'?: string+}): string | undefined {+ return (+ validateScope(args.scope) ??+ validateSeverity(args.severity) ??+ validateLimit(args.limit) ??+ (args.category ? validateCategory(args.category) : undefined) ??+ (args['min-area'] !== undefined ? validateMinArea(args['min-area']) : undefined) ??+ validateMinRatio(args['min-ratio'] ? Number(args['min-ratio']) : undefined)+ )+}++function buildRpcArgs(args: {+ scope: string+ severity: string+ category?: string+ limit: string+ 'min-area'?: string+ 'min-ratio'?: string+ 'include-hidden'?: boolean+ 'include-locked'?: boolean+ 'include-absolute'?: boolean+ page?: string+ 'page-id'?: string+ type?: string+}): { rpcArgs: Record<string, unknown>; error?: string } {+ const error = collectValidationError(args)+ if (error) return { rpcArgs: {}, error }++ const minAreaRaw = args['min-area']+ const minArea = minAreaRaw ? Number(minAreaRaw) : undefined+ const minRatio = args['min-ratio'] ? Number(args['min-ratio']) : undefined++ const rpcArgs: Record<string, unknown> = {+ scope: parseOverlapScope(args.scope) ?? 'all',+ severity: parseOverlapSeverity(args.severity) ?? 'info',+ limit: Number(args.limit)+ }+ if (args.category) rpcArgs.category = args.category+ if (minArea !== undefined) rpcArgs.min_area = minArea+ if (minRatio !== undefined) rpcArgs.min_ratio = minRatio+ if (args['include-hidden']) rpcArgs.include_hidden = true+ if (args['include-locked']) rpcArgs.include_locked = true+ if (args['include-absolute']) rpcArgs.include_absolute = true+ if (args.page) rpcArgs.page = args.page+ if (args['page-id']) rpcArgs.page_id = args['page-id']+ if (args.type) rpcArgs.type = args.type++ return { rpcArgs }+}++export default defineCommand({+ meta: { description: 'Detect visual overlaps and layout overflows' },+ args: {+ file: {+ type: 'positional',+ description: '.fig file path (omit to connect to running app)',+ required: false+ },+ scope: {+ type: 'string',+ description:+ 'Which pairs to inspect: all, same-parent, cross-parent, top-level, inside-parent',+ default: 'all'+ },+ category: {+ type: 'string',+ description: 'Comma-separated categories: sibling-overlap, parent-overflow, overlay'+ },+ severity: {+ type: 'string',+ description: 'Minimum severity to include: critical, major, minor, info',+ default: 'info'+ },+ 'min-area': {+ type: 'string',+ description: 'Minimum overlap area in square pixels'+ },+ 'min-ratio': {+ type: 'string',+ description: 'Minimum overlap ratio relative to the smaller node, 0.0–1.0'+ },+ 'include-hidden': {+ type: 'boolean',+ description: 'Include hidden nodes in the analysis'+ },+ 'include-locked': {+ type: 'boolean',+ description: 'Include locked nodes in the analysis'+ },+ 'include-absolute': {+ type: 'boolean',+ description: 'Include absolutely-positioned nodes in the analysis'+ },+ page: {+ type: 'string',+ description: 'Limit analysis to nodes on the named page'+ },+ 'page-id': {+ type: 'string',+ description: 'Limit analysis to nodes on the page with this stable ID'+ },+ type: {+ type: 'string',+ description: 'Comma-separated node types to analyze, e.g. FRAME,TEXT'+ },+ limit: {+ type: 'string',+ description: 'Maximum overlap findings to show',+ default: '100'+ },+ json: { type: 'boolean', description: 'Output as JSON' }+ },+ async run({ args }) {+ const { rpcArgs, error } = buildRpcArgs(args)+ if (error) {+ console.error(fail(error))+ process.exit(1)+ }++ const data = await loadRpcData<AnalyzeOverlapsResult>(args.file, 'analyze_overlaps', rpcArgs)++ if (args.json) {+ console.log(JSON.stringify(data, null, 2))+ return+ }++ if (data.summary.overlapCount === 0) {+ console.log(kv('status', 'No overlaps found'))+ console.log(fmtSummary({ 'analyzed nodes': data.summary.analyzedNodes }))+ return+ }++ const showing = data.overlaps.length+ const total = data.summary.overlapCount+ const header =+ showing === total+ ? ` Overlaps — ${total} found`+ : ` Overlaps — ${total} found (${showing} shown)`++ console.log('')+ console.log(bold(header))+ console.log('')++ console.log(+ fmtList(+ data.overlaps.map((overlap) => ({+ header: `[${overlap.severity}] ${overlap.category}`,+ details: {+ message: overlap.message,+ area: `${overlap.area}px`,+ ratio: `${(overlap.ratio * 100).toFixed(1)}%`,+ a: `${overlap.nodeA.type} "${overlap.nodeA.name}" (${overlap.nodeA.id})`,+ b: `${overlap.nodeB.type} "${overlap.nodeB.name}" (${overlap.nodeB.id})`,+ suggestion: overlap.suggestion+ }+ }))+ )+ )++ console.log('')+ console.log(+ fmtSummary({+ 'analyzed nodes': data.summary.analyzedNodes,+ 'total nodes': data.summary.totalNodes+ })+ )+ console.log(+ kv(+ 'by category',+ Object.entries(data.summary.byCategory)+ .filter(([, count]) => count > 0)+ .map(([k, count]) => `${k}: ${count}`)+ .join(', ') || 'none'+ )+ )+ console.log(+ kv(+ 'by severity',+ Object.entries(data.summary.bySeverity)+ .filter(([, count]) => count > 0)+ .map(([k, count]) => `${k}: ${count}`)+ .join(', ') || 'none'+ )+ )+ console.log('')+ }+})diff --git a/packages/cli/src/commands/convert.ts b/packages/cli/src/commands/convert.tsindex d52681e87..a87c4b12b 100644--- a/packages/cli/src/commands/convert.ts+++ b/packages/cli/src/commands/convert.ts@@ -1,3 +1,4 @@+import { writeFile } from 'node:fs/promises'import { basename, extname, resolve } from 'node:path'import { defineCommand } from 'citty'@@ -52,7 +53,7 @@ export default defineCommand({const graph = await loadDocument(file)const result = await io.writeDocument(format, graph)const output = args.output ? resolve(args.output) : defaultOutput(file, format)- await Bun.write(output, result.data as Uint8Array)+ await writeFile(output, result.data as Uint8Array)console.log(ok(`Converted ${file} → ${output}`))}})diff --git a/packages/cli/src/commands/eval.ts b/packages/cli/src/commands/eval.tsindex e51ea99a3..32fa55311 100644--- a/packages/cli/src/commands/eval.ts+++ b/packages/cli/src/commands/eval.ts@@ -1,3 +1,5 @@+import { writeFile } from 'node:fs/promises'+import { defineCommand } from 'citty'import { FigmaAPI } from '@open-pencil/core/figma-api'@@ -96,7 +98,7 @@ export default defineCommand({const io = new IORegistry(BUILTIN_IO_FORMATS)const outPath = args.output ? args.output : fileconst result = await io.writeDocument('fig', graph)- await Bun.write(outPath, result.data as Uint8Array)+ await writeFile(outPath, result.data as Uint8Array)if (!args.quiet) {console.error(`Written to ${outPath}`)}diff --git a/packages/cli/src/commands/export.ts b/packages/cli/src/commands/export.tsindex f3eb47ee2..7ed1a0c16 100644--- a/packages/cli/src/commands/export.ts+++ b/packages/cli/src/commands/export.ts@@ -1,3 +1,4 @@+import { writeFile } from 'node:fs/promises'import { basename, extname, resolve } from 'node:path'import { defineCommand } from 'citty'@@ -29,7 +30,7 @@ interface ExportArgs {}async function writeAndLog(path: string, content: string | Uint8Array) {- await Bun.write(path, content)+ await writeFile(path, content)const size = typeof content === 'string' ? content.length : content.lengthconsole.log(ok(`Exported ${path} (${(size / 1024).toFixed(1)} KB)`))}diff --git a/packages/cli/src/headless.ts b/packages/cli/src/headless.tsindex e76217316..f6cae27c8 100644--- a/packages/cli/src/headless.ts+++ b/packages/cli/src/headless.ts@@ -1,3 +1,5 @@+import { readFile } from 'node:fs/promises'+import { BUILTIN_IO_FORMATS, IORegistry, initCanvasKit } from '@open-pencil/core/io'import { computeAllLayouts } from '@open-pencil/core/layout'import type { SceneGraph } from '@open-pencil/core/scene-graph'@@ -7,7 +9,7 @@ export { initCanvasKit }const io = new IORegistry(BUILTIN_IO_FORMATS)export async function loadDocument(filePath: string): Promise<SceneGraph> {- const bytes = new Uint8Array(await Bun.file(filePath).arrayBuffer())+ const bytes = new Uint8Array(await readFile(filePath))const { graph } = await io.readDocument({ name: filePath, data: bytes })computeAllLayouts(graph)return graphdiff --git a/packages/core/package.json b/packages/core/package.jsonindex 1a34dce99..bfdf83aae 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -8,6 +8,7 @@},"sideEffects": false,"exports": {+ "./package.json": "./package.json",".": {"types": "./dist/index.d.ts","default": "./dist/index.js",diff --git a/packages/core/src/geometry.ts b/packages/core/src/geometry.tsindex 4150c7a6a..d13e44f96 100644--- a/packages/core/src/geometry.ts+++ b/packages/core/src/geometry.ts@@ -137,7 +137,7 @@ export function polygonVertices(node: {})}-function strokeOverflow(strokes?: Stroke[]): number {+export function strokeOverflow(strokes?: Stroke[]): number {let overflow = 0for (const stroke of strokes ?? []) {if (!stroke.visible) continue@@ -149,7 +149,7 @@ function strokeOverflow(strokes?: Stroke[]): number {return overflow}-function effectOverflow(effects?: Effect[]) {+export function effectOverflow(effects?: Effect[]) {let left = 0let right = 0let top = 0@@ -398,3 +398,98 @@ export function computeDescendantVisualBounds(}return bounds}++// ── Rotated-rectangle clipping ──++function crossProduct(a: Vector, b: Vector, p: Vector): number {+ return (b.x - a.x) * (p.y - a.y) - (b.y - a.y) * (p.x - a.x)+}++function lineSegmentIntersect(p1: Vector, p2: Vector, p3: Vector, p4: Vector): Vector {+ const dx1 = p2.x - p1.x+ const dy1 = p2.y - p1.y+ const dx2 = p4.x - p3.x+ const dy2 = p4.y - p3.y+ const denom = dx1 * dy2 - dy1 * dx2+ if (denom === 0) return p1+ const t = ((p3.x - p1.x) * dy2 - (p3.y - p1.y) * dx2) / denom+ return { x: p1.x + t * dx1, y: p1.y + t * dy1 }+}++function clipHalfPlane(polygon: Vector[], a: Vector, b: Vector, wantPositive: boolean): Vector[] {+ const output: Vector[] = []+ const isInside = (p: Vector): boolean => {+ const cross = crossProduct(a, b, p)+ return wantPositive ? cross >= 0 : cross <= 0+ }+ for (let i = 0; i < polygon.length; i++) {+ const curr = polygon[i]+ const prev = polygon[i === 0 ? polygon.length - 1 : i - 1]+ const currInside = isInside(curr)+ const prevInside = isInside(prev)+ if (currInside) {+ if (!prevInside) output.push(lineSegmentIntersect(prev, curr, a, b))+ output.push(curr)+ } else if (prevInside) {+ output.push(lineSegmentIntersect(prev, curr, a, b))+ }+ }+ return output+}++/**+ * Clip an axis-aligned VisualBounds rectangle against a convex polygon+ * (e.g. the 4 canvas-space corners of a rotated clipping ancestor).+ *+ * Uses Sutherland–Hodgman polygon clipping with centroid-based interior+ * detection, making it robust to either winding order of the clip polygon.+ * Returns the AABB of the intersection, or null if the bounds are fully+ * outside the clip polygon.+ *+ * For a non-rotated clip (axis-aligned corners) the result is identical+ * to `intersectVisualBounds`.+ */+export function clipBoundsToPolygon(+ bounds: VisualBounds,+ clipCorners: Vector[]+): VisualBounds | null {+ if (clipCorners.length < 3) return bounds++ let cx = 0+ let cy = 0+ for (const c of clipCorners) {+ cx += c.x+ cy += c.y+ }+ cx /= clipCorners.length+ cy /= clipCorners.length++ let subject: Vector[] = [+ { x: bounds.minX, y: bounds.minY },+ { x: bounds.maxX, y: bounds.minY },+ { x: bounds.maxX, y: bounds.maxY },+ { x: bounds.minX, y: bounds.maxY }+ ]++ for (let i = 0; i < clipCorners.length; i++) {+ if (subject.length === 0) return null+ const a = clipCorners[i]+ const b = clipCorners[(i + 1) % clipCorners.length]+ const centroidCross = crossProduct(a, b, { x: cx, y: cy })+ subject = clipHalfPlane(subject, a, b, centroidCross >= 0)+ }++ if (subject.length === 0) return null++ let minX = Infinity+ let minY = Infinity+ let maxX = -Infinity+ let maxY = -Infinity+ for (const p of subject) {+ if (p.x < minX) minX = p.x+ if (p.y < minY) minY = p.y+ if (p.x > maxX) maxX = p.x+ if (p.y > maxY) maxY = p.y+ }+ return minX < maxX && minY < maxY ? { minX, minY, maxX, maxY } : null+}diff --git a/packages/core/src/rpc/analyze-commands.ts b/packages/core/src/rpc/analyze-commands.tsindex 3c624b32f..1a9439860 100644--- a/packages/core/src/rpc/analyze-commands.ts+++ b/packages/core/src/rpc/analyze-commands.ts@@ -3,10 +3,17 @@ import { orderBy, sortBy } from 'es-toolkit/array'import { colorToHex, colorDistance as colorDist } from '#core/color'import type { ColorUsageEntry } from '#core/color/analysis'import type { SceneGraph, SceneNode } from '#core/scene-graph'+import {+ computeOverlaps,+ type AnalyzeOverlapsArgs,+ type AnalyzeOverlapsResult+} from '#core/tools/analyze/overlaps'import type { Color } from '#core/types'import type { RpcCommand } from './types'+export type { AnalyzeOverlapsArgs, AnalyzeOverlapsResult } from '#core/tools/analyze/overlaps'+// ── analyze colors ──export interface AnalyzeColorsArgs {@@ -297,3 +304,10 @@ export const analyzeClustersCommand: RpcCommand<AnalyzeClustersArgs, AnalyzeClusreturn { clusters, totalNodes }}}++// ── analyze overlaps ──++export const analyzeOverlapsCommand: RpcCommand<AnalyzeOverlapsArgs, AnalyzeOverlapsResult> = {+ name: 'analyze_overlaps',+ execute: (graph, args) => computeOverlaps(graph, args)+}diff --git a/packages/core/src/rpc/commands.ts b/packages/core/src/rpc/commands.tsindex 4a0336a66..fa9c1f741 100644--- a/packages/core/src/rpc/commands.ts+++ b/packages/core/src/rpc/commands.ts@@ -3,6 +3,7 @@ import type { SceneGraph } from '#core/scene-graph'import {analyzeClustersCommand,analyzeColorsCommand,+ analyzeOverlapsCommand,analyzeSpacingCommand,analyzeTypographyCommand} from './analyze-commands'@@ -33,7 +34,8 @@ export const ALL_RPC_COMMANDS = [analyzeColorsCommand,analyzeTypographyCommand,analyzeSpacingCommand,- analyzeClustersCommand+ analyzeClustersCommand,+ analyzeOverlapsCommand] as RpcCommand[]export function executeRpcCommand(graph: SceneGraph, name: string, args: unknown): unknown {diff --git a/packages/core/src/rpc/index.ts b/packages/core/src/rpc/index.tsindex b3a239679..ba8d0e7f2 100644--- a/packages/core/src/rpc/index.ts+++ b/packages/core/src/rpc/index.ts@@ -21,5 +21,7 @@ export type {SpacingValue,AnalyzeClustersArgs,AnalyzeClustersResult,+ AnalyzeOverlapsArgs,+ AnalyzeOverlapsResult,TypographyStyle} from './commands'diff --git a/packages/core/src/tools/analyze.ts b/packages/core/src/tools/analyze.tsindex 5eab2bf34..0b2d13571 100644--- a/packages/core/src/tools/analyze.ts+++ b/packages/core/src/tools/analyze.ts@@ -3,5 +3,14 @@ export { analyzeColors } from './analyze/colors'export { diffCreate, diffShow } from './analyze/diff'export { evalCode } from './analyze/eval'export { wrapEvalCode } from './analyze/eval/wrap'+export { analyzeOverlaps, computeOverlaps } from './analyze/overlaps'+export type {+ AnalyzeOverlapsArgs,+ AnalyzeOverlapsResult,+ OverlapCategory,+ OverlapItem,+ OverlapNodeSummary,+ OverlapSeverity+} from './analyze/overlaps'export { analyzeSpacing } from './analyze/spacing'export { analyzeTypography } from './analyze/typography'diff --git a/packages/core/src/tools/analyze/overlaps/helpers.ts b/packages/core/src/tools/analyze/overlaps/helpers.tsnew file mode 100644index 000000000..637ecf841--- /dev/null+++ b/packages/core/src/tools/analyze/overlaps/helpers.ts@@ -0,0 +1,551 @@+import { getWorldMatrix } from '#core/canvas/coordinate'+import Matrix from '#core/canvas/matrix'+import {+ clipBoundsToPolygon,+ effectOverflow,+ geometryBlobBounds,+ intersectVisualBounds,+ strokeOverflow,+ unionVisualBounds,+ type VisualBounds+} from '#core/geometry'+import type { SceneGraph, SceneNode } from '#core/scene-graph'+import type { Rect, Vector } from '#core/types'++import type {+ AnalyzeOverlapsArgs,+ OverlapCategory,+ OverlapItem,+ OverlapNodeSummary,+ OverlapScope,+ OverlapSeverity+} from './index'+const SEVERITY_RANK: Record<OverlapSeverity, number> = {+ critical: 4,+ major: 3,+ minor: 2,+ info: 1+}++export function parseNodeTypes(raw: string | undefined): Set<string> | undefined {+ if (!raw) return undefined+ const types = raw+ .split(',')+ .map((v) => v.trim().toUpperCase())+ .filter((v) => v.length > 0)+ return types.length > 0 ? new Set(types) : undefined+}++export function visualBoundsArea(bounds: VisualBounds): number {+ const width = bounds.maxX - bounds.minX+ const height = bounds.maxY - bounds.minY+ return width > 0 && height > 0 ? width * height : 0+}++export function boundsToRect(bounds: VisualBounds): Rect {+ return {+ x: bounds.minX,+ y: bounds.minY,+ width: bounds.maxX - bounds.minX,+ height: bounds.maxY - bounds.minY+ }+}++export function toNodeSummary(node: SceneNode): OverlapNodeSummary {+ return {+ id: node.id,+ name: node.name,+ type: node.type,+ parentId: node.parentId,+ x: Math.round(node.x),+ y: Math.round(node.y),+ width: Math.round(node.width),+ height: Math.round(node.height),+ rotation: Math.round(node.rotation),+ opacity: node.opacity,+ visible: node.visible,+ locked: node.locked+ }+}++export function isEffectivelyHidden(graph: SceneGraph, node: SceneNode): boolean {+ let current: SceneNode | undefined = node+ while (current) {+ if (!current.visible) return true+ current = current.parentId ? graph.getNode(current.parentId) : undefined+ }+ return false+}++export function isEffectivelyLocked(graph: SceneGraph, node: SceneNode): boolean {+ let current: SceneNode | undefined = node+ while (current) {+ if (current.locked) return true+ current = current.parentId ? graph.getNode(current.parentId) : undefined+ }+ return false+}++export function findPageId(graph: SceneGraph, node: SceneNode): string | null {+ let current: SceneNode | undefined = node+ while (current) {+ if (current.type === 'CANVAS') return current.id+ if (current.parentId === null) return null+ current = graph.getNode(current.parentId)+ }+ return null+}++export function findPageIdByName(graph: SceneGraph, name: string | undefined): string | undefined {+ if (!name) return undefined+ const page = graph.getPages().find((p) => p.name === name)+ return page?.id+}++export function pairRelationship(+ nodeA: SceneNode,+ nodeB: SceneNode,+ graph: SceneGraph+): {+ sameParent: boolean+ topLevel: boolean+ insideParent: boolean+ ancestor: 'neither' | 'a-ancestor' | 'b-ancestor'+} {+ const sameParent = nodeA.parentId === nodeB.parentId && nodeA.parentId !== null+ const parentA = nodeA.parentId ? graph.getNode(nodeA.parentId) : undefined+ const parentB = nodeB.parentId ? graph.getNode(nodeB.parentId) : undefined+ const topLevel = parentA?.type === 'CANVAS' && parentB?.type === 'CANVAS'+ const insideParent = sameParent && parentA?.type !== 'CANVAS'+ let ancestor: 'neither' | 'a-ancestor' | 'b-ancestor' = 'neither'+ if (nodeA.id !== nodeB.id) {+ if (graph.isDescendant(nodeB.id, nodeA.id)) ancestor = 'a-ancestor'+ else if (graph.isDescendant(nodeA.id, nodeB.id)) ancestor = 'b-ancestor'+ }+ return { sameParent, topLevel, insideParent, ancestor }+}++export function matchesParentOverflowScope(scope: OverlapScope): boolean {+ return scope === 'all' || scope === 'inside-parent'+}++export function matchesScope(+ rel: ReturnType<typeof pairRelationship>,+ scope: OverlapScope+): boolean {+ switch (scope) {+ case 'all':+ return true+ case 'same-parent':+ return rel.sameParent+ case 'cross-parent':+ return !rel.sameParent+ case 'top-level':+ return rel.topLevel+ case 'inside-parent':+ return rel.insideParent+ default:+ return true+ }+}++export function scoredSeverity(severity: OverlapSeverity): number {+ return SEVERITY_RANK[severity]+}++function parentOverflowSeverity(outRatio: number): OverlapSeverity {+ if (outRatio > 0.25) return 'critical'+ if (outRatio > 0.05) return 'major'+ return 'minor'+}++function siblingOverlapSeverity(intersectionArea: number, smallerArea: number): OverlapSeverity {+ if (smallerArea <= 0) return 'info'+ const ratio = intersectionArea / smallerArea+ if (ratio > 0.5) return 'major'+ if (ratio > 0.08) return 'minor'+ return 'info'+}++function isCandidate(+ node: SceneNode,+ graph: SceneGraph,+ options: {+ includeHidden: boolean+ includeLocked: boolean+ includeAbsolute: boolean+ pageId: string | undefined+ }+): boolean {+ if (node.type === 'CANVAS') return false+ if (!options.includeHidden && isEffectivelyHidden(graph, node)) return false+ if (!options.includeLocked && isEffectivelyLocked(graph, node)) return false+ if (!options.includeAbsolute && node.layoutPositioning === 'ABSOLUTE') return false+ if (options.pageId && findPageId(graph, node) !== options.pageId) return false+ return true+}++export function filterNodes(+ graph: SceneGraph,+ args: AnalyzeOverlapsArgs+): { candidates: SceneNode[]; totalNodes: number; analyzedNodes: number } {+ const includeHidden = args.include_hidden === true+ const includeLocked = args.include_locked === true+ const includeAbsolute = args.include_absolute === true+ const pageIdFilter = args.page_id?.trim()+ const typeFilter = parseNodeTypes(args.type)++ const allNodes = [...graph.getAllNodes()]+ const candidates: SceneNode[] = []+ let totalNodes = 0++ for (const node of allNodes) {+ if (node.type === 'CANVAS') continue+ // Apply page scoping to totalNodes so summary counts reflect the filtered universe.+ if (pageIdFilter && findPageId(graph, node) !== pageIdFilter) continue+ totalNodes+++ if (+ !isCandidate(node, graph, {+ includeHidden,+ includeLocked,+ includeAbsolute,+ pageId: undefined+ })+ )+ continue+ if (typeFilter && !typeFilter.has(node.type)) continue+ candidates.push(node)+ }++ return { candidates, totalNodes, analyzedNodes: candidates.length }+}++const EMPTY_BOUNDS: VisualBounds = { minX: 0, maxX: 0, minY: 0, maxY: 0 }++/**+ * Map a node's 4 local corners through the world matrix to canvas space.+ * Unlike `getAbsolutePosition` + `rotatedBBox` (which only applies the node's+ * own rotation), this correctly accounts for all ancestor transforms+ * including nested rotations.+ */+function nodeWorldCorners(node: SceneNode, graph: SceneGraph): Vector[] {+ const matrix = getWorldMatrix(node, graph)+ const pts = Matrix.mapPoints(matrix, [+ 0,+ 0,+ node.width,+ 0,+ node.width,+ node.height,+ 0,+ node.height+ ])+ return [+ { x: pts[0], y: pts[1] },+ { x: pts[2], y: pts[3] },+ { x: pts[4], y: pts[5] },+ { x: pts[6], y: pts[7] }+ ]+}++function aabbFromCorners(corners: Vector[]): VisualBounds {+ let minX = Infinity+ let minY = Infinity+ let maxX = -Infinity+ let maxY = -Infinity+ for (const c of corners) {+ if (c.x < minX) minX = c.x+ if (c.y < minY) minY = c.y+ if (c.x > maxX) maxX = c.x+ if (c.y > maxY) maxY = c.y+ }+ return { minX, minY, maxX, maxY }+}++/**+ * Compute a node's visual bounds in canvas space using the world matrix,+ * correctly handling nested ancestor rotations. This replaces the previous+ * `nodeVisualBounds` call which used `rotatedBBox` with the node's LOCAL+ * rotation and the rotated origin — wrong when ancestors are rotated.+ *+ * Includes stroke overflow (uniform), effect overflow (directional),+ * fill/stroke geometry (transformed through the world matrix), and+ * text-decoration overflow (approximate: adds to canvas maxY).+ */+function computeNodeVisualBounds(node: SceneNode, graph: SceneGraph): VisualBounds {+ const matrix = getWorldMatrix(node, graph)+ const baseCorners = Matrix.mapPoints(matrix, [+ 0,+ 0,+ node.width,+ 0,+ node.width,+ node.height,+ 0,+ node.height+ ])+ let bounds = aabbFromCorners([+ { x: baseCorners[0], y: baseCorners[1] },+ { x: baseCorners[2], y: baseCorners[3] },+ { x: baseCorners[4], y: baseCorners[5] },+ { x: baseCorners[6], y: baseCorners[7] }+ ])++ const stroke = strokeOverflow(node.strokes)+ if (stroke > 0) {+ bounds.minX -= stroke+ bounds.minY -= stroke+ bounds.maxX += stroke+ bounds.maxY += stroke+ }++ const effects = effectOverflow(node.effects)+ bounds.minX -= effects.left+ bounds.minY -= effects.top+ bounds.maxX += effects.right+ bounds.maxY += effects.bottom++ const hasNonInsideStroke = node.strokes.some(+ (stroke) => stroke.visible && stroke.align !== 'INSIDE'+ )+ const localGeometry = geometryBlobBounds([+ ...node.fillGeometry,+ ...(hasNonInsideStroke ? node.strokeGeometry : [])+ ])+ if (localGeometry) {+ const geomCorners = Matrix.mapPoints(matrix, [+ localGeometry.x,+ localGeometry.y,+ localGeometry.x + localGeometry.width,+ localGeometry.y,+ localGeometry.x + localGeometry.width,+ localGeometry.y + localGeometry.height,+ localGeometry.x,+ localGeometry.y + localGeometry.height+ ])+ const geomBounds = aabbFromCorners([+ { x: geomCorners[0], y: geomCorners[1] },+ { x: geomCorners[2], y: geomCorners[3] },+ { x: geomCorners[4], y: geomCorners[5] },+ { x: geomCorners[6], y: geomCorners[7] }+ ])+ bounds = unionVisualBounds(bounds, geomBounds) ?? bounds+ }++ if (node.type === 'TEXT' && node.textDecoration !== 'NONE') {+ const fontSize = node.fontSize+ const underlineOffset = node.textUnderlineOffset ?? fontSize * 0.18+ const thickness = node.textDecorationThickness ?? Math.max(1, fontSize / 16)+ bounds.maxY += underlineOffset + thickness + fontSize * 0.35+ }++ return bounds+}++/**+ * Collect clipping ancestors as rotated polygons (4 canvas-space corners each).+ * Unlike the previous axis-aligned approach, this correctly represents rotated+ * clip frames by mapping their local corners through the world matrix.+ */+function collectClipChain(graph: SceneGraph, node: SceneNode): Vector[][] {+ const clips: Vector[][] = []+ let currentId = node.parentId+ while (currentId) {+ const current = graph.getNode(currentId)+ if (!current) break+ if (current.type === 'CANVAS') break+ if (+ current.clipsContent &&+ (current.type === 'FRAME' || current.type === 'COMPONENT' || current.type === 'INSTANCE')+ ) {+ clips.push(nodeWorldCorners(current, graph))+ }+ currentId = current.parentId+ }+ return clips+}++export function computeNodeBounds(+ node: SceneNode,+ graph: SceneGraph+): { bounds: VisualBounds; area: number } {+ let bounds = computeNodeVisualBounds(node, graph)+ const clips = collectClipChain(graph, node)+ for (const clip of clips) {+ const clipped = clipBoundsToPolygon(bounds, clip)+ if (!clipped) {+ return { bounds: EMPTY_BOUNDS, area: 0 }+ }+ bounds = clipped+ }+ return { bounds, area: visualBoundsArea(bounds) }+}++function makeOverlapItem(+ category: OverlapCategory,+ severity: OverlapSeverity,+ nodeA: SceneNode,+ boundsA: VisualBounds,+ nodeB: SceneNode,+ boundsB: VisualBounds,+ intersection: VisualBounds,+ message: string,+ suggestion: string,+ areaField: 'intersection' | 'overflow' = 'intersection'+): OverlapItem {+ const intersectionRect = boundsToRect(intersection)+ const area =+ areaField === 'intersection'+ ? visualBoundsArea(intersection)+ : visualBoundsArea(boundsA) - visualBoundsArea(intersection)+ const ratio =+ areaField === 'intersection'+ ? area / Math.max(1, Math.min(visualBoundsArea(boundsA), visualBoundsArea(boundsB)))+ : area / Math.max(1, visualBoundsArea(boundsA))++ return {+ category,+ severity,+ message,+ suggestion,+ area: Math.round(area),+ ratio: Math.round(ratio * 1000) / 1000,+ nodeA: toNodeSummary(nodeA),+ nodeB: toNodeSummary(nodeB),+ intersection: {+ ...intersectionRect,+ area: Math.round(visualBoundsArea(intersection))+ }+ }+}++export function buildParentOverflowResult(+ child: SceneNode,+ childBounds: VisualBounds,+ parent: SceneNode,+ parentBounds: VisualBounds+): OverlapItem | null {+ if (parent.clipsContent) return null+ const childArea = visualBoundsArea(childBounds)+ if (childArea <= 0) return null++ const intersection = intersectVisualBounds(childBounds, parentBounds)+ const outArea = intersection ? childArea - visualBoundsArea(intersection) : childArea+ if (outArea <= 0) return null++ const outRatio = outArea / childArea+ const severity = parentOverflowSeverity(outRatio)+ const message = `${child.type === 'TEXT' ? 'Text' : `Node`} "${child.name}" extends ${Math.round(outArea)}px outside parent "${parent.name}"`+ const suggestion =+ child.type === 'TEXT'+ ? 'Set the parent to clip content or constrain text sizing (textAutoResize, maxLines).'+ : `Reposition inside "${parent.name}" or enable clip content on the parent.`++ return makeOverlapItem(+ 'parent-overflow',+ severity,+ child,+ childBounds,+ parent,+ parentBounds,+ intersection ?? EMPTY_BOUNDS,+ message,+ suggestion,+ 'overflow'+ )+}++function isNodeAbove(ancestorGraph: SceneGraph, above: SceneNode, below: SceneNode): boolean {+ if (above.parentId !== below.parentId || above.parentId === null) return false+ const parent = ancestorGraph.getNode(above.parentId)+ if (!parent) return false+ const aboveIndex = parent.childIds.indexOf(above.id)+ const belowIndex = parent.childIds.indexOf(below.id)+ return aboveIndex > belowIndex+}++function detectSiblingOverlay(+ nodeA: SceneNode,+ boundsA: VisualBounds,+ nodeB: SceneNode,+ boundsB: VisualBounds,+ graph: SceneGraph+): OverlapCategory {+ const areaA = visualBoundsArea(boundsA)+ const areaB = visualBoundsArea(boundsB)+ const smallerArea = Math.min(areaA, areaB)+ const largerArea = Math.max(areaA, areaB)+ const intersection = intersectVisualBounds(boundsA, boundsB)+ if (!intersection || smallerArea <= 0) return 'sibling-overlap'+ const overlapArea = visualBoundsArea(intersection)+ const coversSmall = overlapArea / smallerArea > 0.85+ const sizeRatio = largerArea / Math.max(1, smallerArea)+ if (sizeRatio < 5 || !coversSmall) return 'sibling-overlap'++ const larger = areaA >= areaB ? nodeA : nodeB+ const smaller = areaA >= areaB ? nodeB : nodeA+ return isNodeAbove(graph, larger, smaller) ? 'overlay' : 'sibling-overlap'+}++export function buildSiblingOverlapResult(+ nodeA: SceneNode,+ boundsA: VisualBounds,+ nodeB: SceneNode,+ boundsB: VisualBounds,+ graph: SceneGraph+): OverlapItem | null {+ const intersection = intersectVisualBounds(boundsA, boundsB)+ if (!intersection) return null++ const areaA = visualBoundsArea(boundsA)+ const areaB = visualBoundsArea(boundsB)+ const smallerArea = Math.min(areaA, areaB)+ const category = detectSiblingOverlay(nodeA, boundsA, nodeB, boundsB, graph)+ const intersectionArea = visualBoundsArea(intersection)+ let severity: OverlapSeverity+ if (category === 'overlay') {+ severity = smallerArea > 0 && intersectionArea / smallerArea > 0.98 ? 'info' : 'minor'+ } else {+ severity = siblingOverlapSeverity(intersectionArea, smallerArea)+ }++ const larger = areaA >= areaB ? nodeA : nodeB+ const smaller = areaA >= areaB ? nodeB : nodeA++ const message =+ category === 'overlay'+ ? `"${larger.name}" appears to be an overlay covering "${smaller.name}"`+ : `"${nodeA.name}" overlaps "${nodeB.name}"`+ const suggestion =+ category === 'overlay'+ ? 'If intentional (modal/backdrop/dropdown), no action needed. Otherwise reposition or adjust z-order.'+ : 'Review stacking and spacing — this overlap is likely unintended.'++ return makeOverlapItem(+ category,+ severity,+ nodeA,+ boundsA,+ nodeB,+ boundsB,+ intersection,+ message,+ suggestion+ )+}++export function passesThresholds(+ item: OverlapItem,+ minArea: number,+ minRatio: number,+ categoryFilter: OverlapCategory[] | undefined,+ severityFilter: OverlapSeverity | undefined+): boolean {+ if (item.area < minArea) return false+ if (item.ratio < minRatio) return false+ if (categoryFilter && !categoryFilter.includes(item.category)) return false+ if (severityFilter && scoredSeverity(item.severity) < scoredSeverity(severityFilter)) return false+ return true+}++export type BoundsEntry = { node: SceneNode; bounds: VisualBounds; area: number }diff --git a/packages/core/src/tools/analyze/overlaps/index.ts b/packages/core/src/tools/analyze/overlaps/index.tsnew file mode 100644index 000000000..6aef894e3--- /dev/null+++ b/packages/core/src/tools/analyze/overlaps/index.ts@@ -0,0 +1,394 @@+import { orderBy } from 'es-toolkit/array'++import type { FigmaAPI } from '#core/figma-api'+import type { SceneGraph, SceneNode } from '#core/scene-graph'+import { defineTool } from '#core/tools/schema'++import {+ buildParentOverflowResult,+ buildSiblingOverlapResult,+ computeNodeBounds,+ filterNodes,+ findPageId,+ findPageIdByName,+ matchesParentOverflowScope,+ matchesScope,+ pairRelationship,+ passesThresholds,+ scoredSeverity,+ type BoundsEntry+} from './helpers'+import {+ parseOverlapCategories as parseCategoryFilter,+ parseOverlapScope as toScope,+ parseOverlapSeverity as parseSeverity+} from './params'++export type OverlapSeverity = 'critical' | 'major' | 'minor' | 'info'++export type OverlapScope = 'all' | 'same-parent' | 'cross-parent' | 'top-level' | 'inside-parent'++export type OverlapCategory = 'sibling-overlap' | 'parent-overflow' | 'overlay'++export { findPageId, findPageIdByName }++export interface OverlapNodeSummary {+ id: string+ name: string+ type: string+ parentId: string | null+ x: number+ y: number+ width: number+ height: number+ rotation: number+ opacity: number+ visible: boolean+ locked: boolean+}++export interface OverlapIntersection {+ x: number+ y: number+ width: number+ height: number+ area: number+}++export interface OverlapItem {+ category: OverlapCategory+ severity: OverlapSeverity+ message: string+ suggestion: string+ area: number+ ratio: number+ nodeA: OverlapNodeSummary+ nodeB: OverlapNodeSummary+ intersection: OverlapIntersection+}++export interface AnalyzeOverlapsArgs {+ scope?: OverlapScope+ category?: string+ severity?: OverlapSeverity+ min_area?: number+ min_ratio?: number+ include_hidden?: boolean+ include_locked?: boolean+ include_absolute?: boolean+ limit?: number+ /** Page name fallback; used only when `page_id` is not supplied. */+ page?: string+ /** Stable page ID; takes precedence over `page`. */+ page_id?: string+ type?: string+}++export interface AnalyzeOverlapsSummary {+ totalNodes: number+ analyzedNodes: number+ overlapCount: number+ byCategory: Record<OverlapCategory, number>+ bySeverity: Record<OverlapSeverity, number>+}++export interface AnalyzeOverlapsResult {+ overlaps: OverlapItem[]+ summary: AnalyzeOverlapsSummary+}++function buildBoundsCache(+ candidates: SceneNode[],+ graph: SceneGraph+): { boundsCache: Map<string, BoundsEntry>; entries: BoundsEntry[] } {+ const boundsCache = new Map<string, BoundsEntry>()+ const entries: BoundsEntry[] = []++ for (const node of candidates) {+ const cached = boundsCache.get(node.id)+ if (cached) {+ entries.push(cached)+ continue+ }+ const computed = computeNodeBounds(node, graph)+ if (computed.area <= 0) continue+ const entry: BoundsEntry = { node, ...computed }+ boundsCache.set(node.id, entry)+ entries.push(entry)+ }++ return { boundsCache, entries }+}++function collectParentOverflows(+ candidates: SceneNode[],+ graph: SceneGraph,+ boundsCache: Map<string, BoundsEntry>,+ scope: OverlapScope,+ minArea: number,+ minRatio: number,+ categoryFilter: OverlapCategory[] | undefined,+ severityFilter: OverlapSeverity | undefined+): OverlapItem[] {+ const overlaps: OverlapItem[] = []++ for (const child of candidates) {+ if (!child.parentId) continue+ const parent = graph.getNode(child.parentId)+ if (!parent || parent.type === 'CANVAS') continue+ const childEntry = boundsCache.get(child.id)+ if (!childEntry || childEntry.area <= 0) continue+ let parentEntry = boundsCache.get(parent.id)+ if (!parentEntry) {+ const computed = computeNodeBounds(parent, graph)+ if (computed.area <= 0) continue+ parentEntry = { node: parent, ...computed }+ boundsCache.set(parent.id, parentEntry)+ }+ const item = buildParentOverflowResult(child, childEntry.bounds, parent, parentEntry.bounds)+ if (+ item &&+ matchesParentOverflowScope(scope) &&+ passesThresholds(item, minArea, minRatio, categoryFilter, severityFilter)+ ) {+ overlaps.push(item)+ }+ }++ return overlaps+}++function collectSiblingOverlaps(+ entries: BoundsEntry[],+ graph: SceneGraph,+ scope: OverlapScope,+ minArea: number,+ minRatio: number,+ categoryFilter: OverlapCategory[] | undefined,+ severityFilter: OverlapSeverity | undefined+): OverlapItem[] {+ const overlaps: OverlapItem[] = []+ entries.sort((a, b) => a.bounds.minX - b.bounds.minX)++ for (let i = 0; i < entries.length; i++) {+ const entryA = entries[i]+ if (entryA.area <= 0) continue+ const maxX = entryA.bounds.maxX+ for (let j = i + 1; j < entries.length; j++) {+ const entryB = entries[j]+ if (entryB.bounds.minX > maxX) break+ if (entryB.bounds.maxY <= entryA.bounds.minY || entryB.bounds.minY >= entryA.bounds.maxY) {+ continue+ }++ const rel = pairRelationship(entryA.node, entryB.node, graph)+ if (rel.ancestor !== 'neither') continue+ if (!matchesScope(rel, scope)) continue++ const item = buildSiblingOverlapResult(+ entryA.node,+ entryA.bounds,+ entryB.node,+ entryB.bounds,+ graph+ )+ if (item && passesThresholds(item, minArea, minRatio, categoryFilter, severityFilter)) {+ overlaps.push(item)+ }+ }+ }++ return overlaps+}++function emptyByCategory(): Record<OverlapCategory, number> {+ return {+ 'sibling-overlap': 0,+ 'parent-overflow': 0,+ overlay: 0+ }+}++function emptyBySeverity(): Record<OverlapSeverity, number> {+ return {+ critical: 0,+ major: 0,+ minor: 0,+ info: 0+ }+}++/**+ * Compute overlap findings for a scoped subset of the graph.+ * Page, scope, type, and visibility filtering is applied via `args`.+ *+ * Heuristics implemented:+ * - `sibling-overlap`: two non-ancestor nodes visually intersect.+ * - `parent-overflow`: a child protrudes from a non-clipping parent.+ * - `overlay`: a large node covers a much smaller sibling (modal/backdrop pattern).+ *+ * Filters:+ * - hidden and locked nodes are skipped unless explicitly included+ * - absolutely-positioned nodes are skipped unless explicitly included+ * - ancestor/descendant pairs are never emitted as pair overlaps+ */+export function computeOverlaps(+ graph: SceneGraph,+ args: AnalyzeOverlapsArgs = {}+): AnalyzeOverlapsResult {+ const scope = toScope(args.scope) ?? 'all'+ const categoryFilter = parseCategoryFilter(args.category)+ const severityFilter = parseSeverity(args.severity)+ const minArea = Math.max(0, Number.isFinite(Number(args.min_area)) ? Number(args.min_area) : 0)+ const minRatio = Math.max(+ 0,+ Math.min(1, Number.isFinite(Number(args.min_ratio)) ? Number(args.min_ratio) : 0)+ )++ const explicitPageName = args.page?.trim()+ const explicitPageId = args.page_id?.trim()+ let resolvedPageId: string | undefined+ if (explicitPageId) {+ resolvedPageId = explicitPageId+ } else if (explicitPageName) {+ resolvedPageId = findPageIdByName(graph, explicitPageName)+ } else {+ resolvedPageId = graph.getPages()[0]?.id+ }++ if (!resolvedPageId) {+ return {+ overlaps: [],+ summary: {+ totalNodes: 0,+ analyzedNodes: 0,+ overlapCount: 0,+ byCategory: emptyByCategory(),+ bySeverity: emptyBySeverity()+ }+ }+ }++ const resolvedArgs: AnalyzeOverlapsArgs = { ...args, page_id: resolvedPageId }++ const { candidates, totalNodes, analyzedNodes } = filterNodes(graph, resolvedArgs)+ const { boundsCache, entries } = buildBoundsCache(candidates, graph)++ const overlaps = [+ ...collectParentOverflows(+ candidates,+ graph,+ boundsCache,+ scope,+ minArea,+ minRatio,+ categoryFilter,+ severityFilter+ ),+ ...collectSiblingOverlaps(+ entries,+ graph,+ scope,+ minArea,+ minRatio,+ categoryFilter,+ severityFilter+ )+ ]++ const sorted = orderBy(+ overlaps,+ [(o) => scoredSeverity(o.severity), (o) => o.area],+ ['desc', 'desc']+ )++ const limit = Math.max(0, Number.isFinite(Number(args.limit)) ? Number(args.limit) : 100)+ const trimmed = limit > 0 ? sorted.slice(0, limit) : sorted++ const byCategory = emptyByCategory()+ const bySeverity = emptyBySeverity()++ for (const item of sorted) {+ byCategory[item.category]+++ bySeverity[item.severity]+++ }++ return {+ overlaps: trimmed,+ summary: {+ totalNodes,+ analyzedNodes,+ overlapCount: sorted.length,+ byCategory,+ bySeverity+ }+ }+}++export const analyzeOverlaps = defineTool({+ name: 'analyze_overlaps',+ description:+ 'Detect visual overlaps and layout overflows across the current page. Useful for finding content that covers footers, text that bleeds outside frames, and accidental sibling overlaps.',+ params: {+ scope: {+ type: 'string',+ description:+ 'Which pairs to inspect: all, same-parent, cross-parent, top-level, inside-parent (default: all)',+ enum: ['all', 'same-parent', 'cross-parent', 'top-level', 'inside-parent'],+ default: 'all'+ },+ category: {+ type: 'string',+ description:+ 'Comma-separated categories: sibling-overlap, parent-overflow, overlay (default: all)'+ },+ severity: {+ type: 'string',+ description: 'Minimum severity to include: critical, major, minor, info (default: info)',+ enum: ['critical', 'major', 'minor', 'info'],+ default: 'info'+ },+ min_area: {+ type: 'number',+ description: 'Minimum overlap area in square pixels (default: 0)'+ },+ min_ratio: {+ type: 'number',+ description: 'Minimum overlap ratio relative to the smaller node, 0.0–1.0 (default: 0)'+ },+ include_hidden: {+ type: 'boolean',+ description: 'Include hidden nodes in the analysis'+ },+ include_locked: {+ type: 'boolean',+ description: 'Include locked nodes in the analysis'+ },+ include_absolute: {+ type: 'boolean',+ description: 'Include absolutely-positioned nodes in the analysis'+ },+ page: {+ type: 'string',+ description: 'Limit analysis to nodes on the named page'+ },+ page_id: {+ type: 'string',+ description:+ 'Limit analysis to nodes on the page with this stable ID (takes precedence over page)'+ },+ type: {+ type: 'string',+ description: 'Comma-separated node types to analyze, e.g. FRAME,TEXT'+ },+ limit: {+ type: 'number',+ description: 'Maximum overlap findings to return (default: 100)',+ default: 100+ }+ },+ execute: (figma: FigmaAPI, args) => {+ const page_id = args.page_id ?? (args.page ? undefined : figma.currentPageId)+ return computeOverlaps(figma.graph, { ...(args as AnalyzeOverlapsArgs), page_id })+ }+})diff --git a/packages/core/src/tools/analyze/overlaps/params.ts b/packages/core/src/tools/analyze/overlaps/params.tsnew file mode 100644index 000000000..f1844c5c1--- /dev/null+++ b/packages/core/src/tools/analyze/overlaps/params.ts@@ -0,0 +1,47 @@+import type { OverlapCategory, OverlapScope, OverlapSeverity } from './index'++export const VALID_OVERLAP_SCOPES: readonly OverlapScope[] = [+ 'all',+ 'same-parent',+ 'cross-parent',+ 'top-level',+ 'inside-parent'+]++export const VALID_OVERLAP_CATEGORIES: readonly OverlapCategory[] = [+ 'sibling-overlap',+ 'parent-overflow',+ 'overlay'+]++export const VALID_OVERLAP_SEVERITIES: readonly OverlapSeverity[] = [+ 'critical',+ 'major',+ 'minor',+ 'info'+]++export function parseOverlapScope(raw: string | undefined): OverlapScope | undefined {+ if (!raw) return undefined+ const normalized = raw.toLowerCase()+ return VALID_OVERLAP_SCOPES.find((scope) => scope === normalized)+}++export function parseOverlapCategories(raw: string | undefined): OverlapCategory[] | undefined {+ if (!raw) return undefined+ const values = raw+ .split(',')+ .map((v) => v.trim().toLowerCase())+ .filter((v) => v.length > 0)+ if (values.length === 0) return undefined+ const categories = values.filter((v): v is OverlapCategory =>+ VALID_OVERLAP_CATEGORIES.includes(v as OverlapCategory)+ )+ return categories.length > 0 ? categories : undefined+}++export function parseOverlapSeverity(raw: string | undefined): OverlapSeverity | undefined {+ if (!raw) return undefined+ const normalized = raw.toLowerCase()+ return VALID_OVERLAP_SEVERITIES.find((severity) => severity === normalized)+}diff --git a/packages/core/src/tools/index.ts b/packages/core/src/tools/index.tsindex 9d5d7808b..fe30d814e 100644--- a/packages/core/src/tools/index.ts+++ b/packages/core/src/tools/index.ts@@ -6,5 +6,13 @@ export type { ToolDef, ParamDef, ParamType } from './schema'export { toolsToAI, buildDebugLog } from './ai-adapter'export type { ToolLogEntry, ToolDebugLog, AIAdapterOptions, StepBudget } from './ai-adapter'export { calcClusterConfidence, wrapEvalCode } from './analyze'+export {+ VALID_OVERLAP_CATEGORIES,+ VALID_OVERLAP_SCOPES,+ VALID_OVERLAP_SEVERITIES,+ parseOverlapCategories,+ parseOverlapScope,+ parseOverlapSeverity+} from './analyze/overlaps/params'export { setPexelsApiKey, setUnsplashAccessKey } from './stock-photo'export { importSvg } from './create'diff --git a/packages/core/src/tools/registry-extended.ts b/packages/core/src/tools/registry-extended.tsindex fd0435bd8..4668cb9e5 100644--- a/packages/core/src/tools/registry-extended.ts+++ b/packages/core/src/tools/registry-extended.ts@@ -1,6 +1,7 @@import {analyzeClusters,analyzeColors,+ analyzeOverlaps,analyzeSpacing,analyzeTypography,diffCreate,@@ -185,6 +186,7 @@ export const EXTENDED_TOOLS: ToolDef[] = [analyzeTypography,analyzeSpacing,analyzeClusters,+ analyzeOverlaps,diffCreate,diffShow,// Codegendiff --git a/tests/engine/cli/eval.test.ts b/tests/engine/cli/eval.test.tsindex 95cc812da..e26104d9a 100644--- a/tests/engine/cli/eval.test.ts+++ b/tests/engine/cli/eval.test.ts@@ -3,9 +3,11 @@ import { randomUUID } from 'node:crypto'import { tmpdir } from 'node:os'import { join } from 'node:path'-import { cliSourcePath, repoPath } from '#tests/helpers/paths'+import { cliSourcePath, repoPath, requireBuiltWorkspacePackages } from '#tests/helpers/paths'import { heavy } from '#tests/helpers/test-utils'+requireBuiltWorkspacePackages()+setDefaultTimeout(30_000)const CLI = cliSourcePath('index.ts')diff --git a/tests/engine/cli/overlaps.test.ts b/tests/engine/cli/overlaps.test.tsnew file mode 100644index 000000000..171d16a6e--- /dev/null+++ b/tests/engine/cli/overlaps.test.ts@@ -0,0 +1,162 @@+import { expect, setDefaultTimeout, test } from 'bun:test'+import { mkdtempSync, writeFileSync } from 'node:fs'+import { tmpdir } from 'node:os'+import { join } from 'node:path'++import { SceneGraph } from '@open-pencil/core'+import { exportFigFile } from '@open-pencil/core/io/formats/fig'++import { cliSourcePath, repoPath, requireBuiltWorkspacePackages } from '#tests/helpers/paths'+import { heavy } from '#tests/helpers/test-utils'++requireBuiltWorkspacePackages()++setDefaultTimeout(30_000)++const CLI = cliSourcePath('index.ts')+const FIXTURE = repoPath('tests/fixtures/gold-preview.fig')++async function makeTwoPageFixture(): Promise<string> {+ const graph = new SceneGraph()+ const page1 = graph.getPages()[0].id+ const page2 = graph.addPage('Page 2')++ graph.createNode('RECTANGLE', page1, { name: 'A', x: 0, y: 0, width: 100, height: 100 })+ graph.createNode('RECTANGLE', page1, { name: 'B', x: 50, y: 50, width: 100, height: 100 })+ graph.createNode('RECTANGLE', page2.id, { name: 'C', x: 0, y: 0, width: 100, height: 100 })+ graph.createNode('RECTANGLE', page2.id, { name: 'D', x: 50, y: 50, width: 100, height: 100 })++ const data = await exportFigFile(graph)+ const dir = mkdtempSync(join(tmpdir(), 'overlap-cli-'))+ const file = join(dir, 'two-pages.fig')+ writeFileSync(file, data)+ return file+}++async function run(args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number }> {+ const proc = Bun.spawn(['bun', CLI, ...args], {+ stdout: 'pipe',+ stderr: 'pipe'+ })+ const [stdout, stderr] = await Promise.all([+ new Response(proc.stdout).text(),+ new Response(proc.stderr).text()+ ])+ const exitCode = await proc.exited+ return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode }+}++heavy('analyze overlaps CLI', () => {+ test('--json returns valid overlap data', async () => {+ const { stdout, exitCode } = await run(['analyze', 'overlaps', FIXTURE, '--json'])+ expect(exitCode).toBe(0)+ const data = JSON.parse(stdout)+ expect(data.overlaps).toBeArray()+ expect(typeof data.summary.totalNodes).toBe('number')+ expect(typeof data.summary.analyzedNodes).toBe('number')+ expect(typeof data.summary.overlapCount).toBe('number')+ })++ test('human-readable mode prints a summary', async () => {+ const { stdout, exitCode } = await run(['analyze', 'overlaps', FIXTURE])+ expect(exitCode).toBe(0)+ expect(stdout.length).toBeGreaterThan(0)+ expect(stdout).toContain('analyzed nodes')+ })++ test('invalid scope exits with error', async () => {+ const { exitCode, stderr } = await run(['analyze', 'overlaps', FIXTURE, '--scope', 'invalid'])+ expect(exitCode).not.toBe(0)+ expect(stderr).toContain('Invalid scope')+ })++ test('invalid severity exits with error', async () => {+ const { exitCode, stderr } = await run([+ 'analyze',+ 'overlaps',+ FIXTURE,+ '--severity',+ 'invalid'+ ])+ expect(exitCode).not.toBe(0)+ expect(stderr).toContain('Invalid severity')+ })++ test('invalid category exits with error', async () => {+ const { exitCode, stderr } = await run(['analyze', 'overlaps', FIXTURE, '--category', 'bogus'])+ expect(exitCode).not.toBe(0)+ expect(stderr).toContain('Invalid categor')+ })++ test('invalid --min-area exits with error', async () => {+ const { exitCode, stderr } = await run(['analyze', 'overlaps', FIXTURE, '--min-area', 'abc'])+ expect(exitCode).not.toBe(0)+ expect(stderr).toContain('--min-area')+ })++ test('invalid --limit exits with error', async () => {+ const { exitCode, stderr } = await run(['analyze', 'overlaps', FIXTURE, '--limit', '0'])+ expect(exitCode).not.toBe(0)+ expect(stderr).toContain('--limit')+ })++ test('--category filters results', async () => {+ const { stdout, exitCode } = await run([+ 'analyze',+ 'overlaps',+ FIXTURE,+ '--json',+ '--category',+ 'parent-overflow'+ ])+ expect(exitCode).toBe(0)+ const data = JSON.parse(stdout)+ expect(data.overlaps.every((o: { category: string }) => o.category === 'parent-overflow')).toBe(+ true+ )+ })++ test('scope argument is case-insensitive', async () => {+ const { stdout, exitCode } = await run([+ 'analyze',+ 'overlaps',+ FIXTURE,+ '--json',+ '--scope',+ 'SAME-PARENT'+ ])+ expect(exitCode).toBe(0)+ const data = JSON.parse(stdout)+ expect(data.overlaps).toBeArray()+ expect(typeof data.summary.totalNodes).toBe('number')+ })++ test('default mode scopes analysis to the first page only', async () => {+ const fixture = await makeTwoPageFixture()+ const { stdout, exitCode } = await run(['analyze', 'overlaps', fixture, '--json'])+ expect(exitCode).toBe(0)+ const data = JSON.parse(stdout)+ expect(data.summary.overlapCount).toBe(1)+ expect(data.summary.totalNodes).toBe(2)+ expect(data.overlaps[0].nodeA.name).toBe('A')+ expect(data.overlaps[0].nodeB.name).toBe('B')+ })++ test('--page scopes analysis to the named page', async () => {+ const fixture = await makeTwoPageFixture()+ const { stdout, exitCode } = await run([+ 'analyze',+ 'overlaps',+ fixture,+ '--json',+ '--page',+ 'Page 2'+ ])+ expect(exitCode).toBe(0)+ const data = JSON.parse(stdout)+ expect(data.summary.overlapCount).toBe(1)+ expect(data.summary.totalNodes).toBe(2)+ expect(data.overlaps[0].nodeA.name).toBe('C')+ expect(data.overlaps[0].nodeB.name).toBe('D')+ })+})diff --git a/tests/engine/tools/analyze/overlaps/bounds.test.ts b/tests/engine/tools/analyze/overlaps/bounds.test.tsnew file mode 100644index 000000000..5430f6003--- /dev/null+++ b/tests/engine/tools/analyze/overlaps/bounds.test.ts@@ -0,0 +1,181 @@+import { describe, expect, test } from 'bun:test'++import { SceneGraph, type Rect } from '@open-pencil/core'+import { computeOverlaps } from '@open-pencil/core/tools/analyze/overlaps'++import { frame, pageId, rect } from './helpers'++describe('analyze overlaps visible bounds', () => {+ test('large background below a small badge is not reported as overlay', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ rect(graph, 'Backdrop', page, 0, 0, 100, 100)+ rect(graph, 'Badge', page, 10, 10, 10, 10)++ const result = computeOverlaps(graph)+ expect(result.overlaps.some((o) => o.category === 'overlay')).toBe(false)+ expect(result.overlaps.some((o) => o.category === 'sibling-overlap')).toBe(true)+ })++ test('text decoration extends visual bounds below raw height', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const t = graph.createNode('TEXT', page, {+ name: 'Underlined',+ x: 0,+ y: 0,+ width: 100,+ height: 10,+ text: 'Underlined',+ fontSize: 14,+ textDecoration: 'UNDERLINE'+ })+ rect(graph, 'Below', page, 0, 11, 100, 10)++ const result = computeOverlaps(graph)+ expect(result.summary.overlapCount).toBeGreaterThan(0)+ expect(result.overlaps.some((o) => o.nodeA.id === t.id || o.nodeB.id === t.id)).toBe(true)+ })++ test('vector geometry expands bounds beyond width and height', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)++ function rectGeometryBlob(local: Rect) {+ const parts = [+ { cmd: 1, x: local.x, y: local.y },+ { cmd: 2, x: local.x + local.width, y: local.y },+ { cmd: 2, x: local.x + local.width, y: local.y + local.height },+ { cmd: 2, x: local.x, y: local.y + local.height },+ { cmd: 0 }+ ]+ let byteLength = 0+ for (const part of parts) {+ byteLength += 1+ if (part.x !== undefined) byteLength += 8+ }+ const bytes = new Uint8Array(byteLength)+ const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)+ let offset = 0+ for (const part of parts) {+ bytes[offset++] = part.cmd+ if (part.x !== undefined) {+ dv.setFloat32(offset, part.x, true)+ dv.setFloat32(offset + 4, part.y as number, true)+ offset += 8+ }+ }+ return bytes+ }++ const v = graph.createNode('VECTOR', page, {+ name: 'WideVector',+ x: 0,+ y: 0,+ width: 10,+ height: 10,+ fillGeometry: [+ {+ commandsBlob: rectGeometryBlob({ x: 0, y: 0, width: 200, height: 200 }),+ windingRule: 'NONZERO'+ }+ ]+ })+ rect(graph, 'Far', page, 150, 150, 50, 50)++ const result = computeOverlaps(graph)+ expect(result.summary.overlapCount).toBeGreaterThan(0)+ expect(result.overlaps.some((o) => o.nodeA.id === v.id || o.nodeB.id === v.id)).toBe(true)+ })++ test('ancestor clipping prevents false overlaps across the clip boundary', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)++ const clipFrame = frame(graph, 'ClipFrame', page, 0, 0, 50, 50, true)+ rect(graph, 'ClippedChild', clipFrame.id, 40, 0, 20, 20)+ rect(graph, 'Outside', page, 50, 0, 20, 20)++ const clipped = computeOverlaps(graph, { category: 'sibling-overlap' })+ expect(clipped.summary.overlapCount).toBe(0)++ const noClipFrame = frame(graph, 'NoClipFrame', page, 200, 0, 50, 50, false)+ rect(graph, 'UnclippedChild', noClipFrame.id, 40, 0, 20, 20)+ rect(graph, 'Outside2', page, 250, 0, 20, 20)++ const unclipped = computeOverlaps(graph, { category: 'sibling-overlap' })+ expect(unclipped.summary.overlapCount).toBe(1)+ })++ test('rotated clipping frame prevents false sibling overlap', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)++ // A 90°-rotated clipping frame. Its local space [0,100]x[0,100] maps to+ // canvas [0,100]x[0,100] (a square rotated 90° around its center is the+ // same square). But the OLD axis-aligned clip used the rotated origin+ // (100,0) and produced a wrong clip rectangle [100,200]x[0,100].+ const clipFrame = frame(graph, 'RotatedClip', page, 0, 0, 100, 100, true)+ graph.updateNode(clipFrame.id, { rotation: 90 })++ // Child at local (10,10,20,20). After 90° rotation around the frame+ // center (50,50), the child lands at canvas AABB [70,90]x[10,30].+ rect(graph, 'Child', clipFrame.id, 10, 10, 20, 20)++ // Outside node starting exactly at the clip frame's right boundary.+ // With the BUGGY code the child's clipped bounds were [100,110]x[10,30]+ // (wrong), producing a false overlap with [100,120]x[10,30].+ // With the fix the child's clipped bounds are [70,90]x[10,30] (correct),+ // so there is no overlap.+ rect(graph, 'Outside', page, 100, 10, 20, 20)++ const result = computeOverlaps(graph, { category: 'sibling-overlap' })+ expect(result.summary.overlapCount).toBe(0)+ })++ test('child of rotated non-clipping parent is detected at correct position', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)++ // Non-clipping parent rotated 90°. A child at local (10,10,20,20)+ // maps to canvas AABB [70,90]x[10,30] after rotation. A second node+ // placed at canvas (72,12,10,10) should overlap — proving the bounds+ // are computed from the world matrix, not from the rotated origin.+ const parent = frame(graph, 'RotatedParent', page, 0, 0, 100, 100, false)+ graph.updateNode(parent.id, { rotation: 90 })+ const child = rect(graph, 'Child', parent.id, 10, 10, 20, 20)+ rect(graph, 'OverlapTarget', page, 72, 12, 10, 10)++ const result = computeOverlaps(graph, { category: 'sibling-overlap' })+ expect(result.summary.overlapCount).toBeGreaterThan(0)+ expect(result.overlaps.some((o) => o.nodeA.id === child.id || o.nodeB.id === child.id)).toBe(+ true+ )+ })++ test('rotated clipping frame still clips children that protrude', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)++ // 90°-rotated clipping frame at (0,0,100,100). Its canvas-space clip is+ // [0,100]x[0,100] (a square rotated 90° around its center is the same+ // square). The OLD axis-aligned clip used the rotated origin (100,0) and+ // produced a wrong clip rectangle [100,200]x[0,100].+ const clipFrame = frame(graph, 'RotatedClip90', page, 0, 0, 100, 100, true)+ graph.updateNode(clipFrame.id, { rotation: 90 })++ // Child at local (10,10,80,80) — a large child whose AABB (after 90°+ // rotation) is [10,90]x[10,90], entirely inside the [0,100]x[0,100] clip.+ rect(graph, 'Center', clipFrame.id, 10, 10, 80, 80)++ // Outside node at (110,10,20,20) — its AABB [110,130]x[10,30] does NOT+ // overlap the child's clipped AABB [10,90]x[10,90] and does NOT overlap+ // the clip frame's AABB [0,100]x[0,100]. With the BUGGY code, the child's+ // clipped bounds were [100,170]x[10,90] (wrong), which WOULD overlap+ // [110,130]x[10,30] — a false positive.+ rect(graph, 'Outside', page, 110, 10, 20, 20)++ const result = computeOverlaps(graph, { category: 'sibling-overlap' })+ expect(result.summary.overlapCount).toBe(0)+ })+})diff --git a/tests/engine/tools/analyze/overlaps/helpers.ts b/tests/engine/tools/analyze/overlaps/helpers.tsnew file mode 100644index 000000000..5d2002469--- /dev/null+++ b/tests/engine/tools/analyze/overlaps/helpers.ts@@ -0,0 +1,57 @@+import type { SceneGraph } from '@open-pencil/core'++export function pageId(graph: SceneGraph) {+ return graph.getPages()[0].id+}++export function rect(+ graph: SceneGraph,+ name: string,+ parentId: string,+ x = 0,+ y = 0,+ w = 50,+ h = 50+) {+ return graph.createNode('RECTANGLE', parentId, { name, x, y, width: w, height: h })+}++export function frame(+ graph: SceneGraph,+ name: string,+ parentId: string,+ x = 0,+ y = 0,+ w = 100,+ h = 100,+ clipsContent = false+) {+ return graph.createNode('FRAME', parentId, {+ name,+ x,+ y,+ width: w,+ height: h,+ clipsContent+ })+}++export function text(+ graph: SceneGraph,+ name: string,+ parentId: string,+ x = 0,+ y = 0,+ w = 100,+ h = 20+) {+ return graph.createNode('TEXT', parentId, {+ name,+ x,+ y,+ width: w,+ height: h,+ text: name,+ fontSize: 14+ })+}diff --git a/tests/engine/tools/analyze/overlaps/index.test.ts b/tests/engine/tools/analyze/overlaps/index.test.tsnew file mode 100644index 000000000..14acfb329--- /dev/null+++ b/tests/engine/tools/analyze/overlaps/index.test.ts@@ -0,0 +1,420 @@+import { describe, expect, test } from 'bun:test'++import { FigmaAPI, SceneGraph } from '@open-pencil/core'+import {+ analyzeOverlaps,+ computeOverlaps,+ type OverlapScope+} from '@open-pencil/core/tools/analyze/overlaps'++import { frame, pageId, rect, text } from './helpers'++describe('analyze overlaps', () => {+ test('detects overlapping sibling rectangles', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const parent = frame(graph, 'Parent', page, 0, 0, 200, 200)+ rect(graph, 'A', parent.id, 0, 0, 100, 100)+ rect(graph, 'B', parent.id, 50, 50, 100, 100)++ const result = computeOverlaps(graph, { scope: 'same-parent' })+ expect(result.summary.overlapCount).toBeGreaterThan(0)+ expect(result.overlaps.some((o) => o.category === 'sibling-overlap')).toBe(true)+ })++ test('ignores separated rectangles', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ rect(graph, 'A', page, 0, 0, 50, 50)+ rect(graph, 'B', page, 200, 200, 50, 50)++ const result = computeOverlaps(graph)+ expect(result.summary.overlapCount).toBe(0)+ })++ test('skips hidden and locked nodes by default', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ rect(graph, 'A', page, 0, 0, 100, 100)+ const hidden = rect(graph, 'Hidden', page, 50, 50, 100, 100)+ graph.updateNode(hidden.id, { visible: false })++ const result = computeOverlaps(graph)+ expect(result.summary.overlapCount).toBe(0)+ })++ test('includes hidden nodes when include_hidden is true', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ rect(graph, 'A', page, 0, 0, 100, 100)+ const hidden = rect(graph, 'Hidden', page, 50, 50, 100, 100)+ graph.updateNode(hidden.id, { visible: false })++ const result = computeOverlaps(graph, { include_hidden: true })+ expect(result.summary.overlapCount).toBeGreaterThan(0)+ })++ test('reports text that overflows a non-clipping frame', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const parent = frame(graph, 'Frame', page, 0, 0, 80, 80)+ text(graph, 'Wide', parent.id, 0, 0, 200, 20)++ const result = computeOverlaps(graph)+ expect(result.overlaps.some((o) => o.category === 'parent-overflow')).toBe(true)+ })++ test('reports a child that is fully outside its non-clipping parent', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const parent = frame(graph, 'Frame', page, 0, 0, 100, 100)+ rect(graph, 'Stray', parent.id, 200, 0, 50, 50)++ const result = computeOverlaps(graph)+ expect(result.overlaps).toHaveLength(1)+ const overflow = result.overlaps[0]+ expect(overflow.category).toBe('parent-overflow')+ expect(overflow.area).toBe(2500)+ expect(overflow.ratio).toBe(1)+ })++ test('does not report overflow when parent clips content', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const parent = frame(graph, 'Frame', page, 0, 0, 80, 80, true)+ text(graph, 'Wide', parent.id, 0, 0, 200, 20)++ const result = computeOverlaps(graph)+ expect(result.overlaps).toHaveLength(0)+ })++ test('detects rotated overlap', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ rect(graph, 'A', page, 0, 0, 100, 20)+ const rotated = rect(graph, 'B', page, 0, 0, 100, 20)+ graph.updateNode(rotated.id, { rotation: 45 })++ const result = computeOverlaps(graph)+ expect(result.summary.overlapCount).toBeGreaterThan(0)+ })++ test('detects a suspicious overlay covering a smaller sibling', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ // Create the smaller node first so the later (and therefore visually on-top) larger node+ // genuinely covers it.+ rect(graph, 'Badge', page, 10, 10, 10, 10)+ rect(graph, 'Backdrop', page, 0, 0, 100, 100)++ const result = computeOverlaps(graph)+ expect(result.overlaps.some((o) => o.category === 'overlay')).toBe(true)+ const overlay = result.overlaps.find((o) => o.category === 'overlay')+ expect(overlay?.message).toContain('"Backdrop" appears to be an overlay covering "Badge"')+ })++ test('filters by node type', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ rect(graph, 'A', page, 0, 0, 100, 100)+ const t = text(graph, 'B', page, 50, 50, 100, 100)++ const result = computeOverlaps(graph, { type: 'TEXT' })+ expect(result.overlaps.every((o) => o.nodeA.id === t.id || o.nodeB.id === t.id)).toBe(true)+ })++ test('respects min_area threshold', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ rect(graph, 'A', page, 0, 0, 100, 100)+ rect(graph, 'B', page, 99, 99, 2, 2)++ const result = computeOverlaps(graph, { min_area: 100 })+ expect(result.summary.overlapCount).toBe(0)+ })++ test('does not flag ancestor-descendant overlap', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const parent = frame(graph, 'Frame', page, 0, 0, 200, 200)+ rect(graph, 'Child', parent.id, 0, 0, 100, 100)++ const result = computeOverlaps(graph)+ expect(result.summary.overlapCount).toBe(0)+ })++ test('scope=same-parent only reports siblings sharing a parent', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const parentA = frame(graph, 'ParentA', page, 0, 0, 200, 200)+ const parentB = frame(graph, 'ParentB', page, 300, 0, 200, 200)+ rect(graph, 'A1', parentA.id, 0, 0, 100, 100)+ rect(graph, 'A2', parentA.id, 50, 50, 100, 100)+ rect(graph, 'B1', parentB.id, 0, 0, 100, 100)+ rect(graph, 'B2', parentB.id, 50, 50, 100, 100)++ const result = computeOverlaps(graph, { scope: 'same-parent', category: 'sibling-overlap' })+ expect(result.summary.overlapCount).toBe(2)+ expect(+ result.overlaps.every(+ (o) => o.nodeA.parentId === o.nodeB.parentId && o.nodeA.parentId !== page+ )+ ).toBe(true)+ })++ test('scope=cross-parent only reports nodes from different parents', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const parentA = frame(graph, 'ParentA', page, 0, 0, 200, 200)+ const parentB = frame(graph, 'ParentB', page, 300, 0, 200, 200)+ rect(graph, 'A', parentA.id, 150, 0, 110, 100)+ rect(graph, 'B', parentB.id, -60, 0, 110, 100)++ const result = computeOverlaps(graph, { scope: 'cross-parent', category: 'sibling-overlap' })+ expect(result.summary.overlapCount).toBe(1)+ expect(result.overlaps[0].nodeA.parentId).not.toBe(result.overlaps[0].nodeB.parentId)+ })++ test('scope=top-level only reports direct page children', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ rect(graph, 'TopA', page, 0, 0, 100, 100)+ rect(graph, 'TopB', page, 50, 50, 100, 100)+ const parent = frame(graph, 'Parent', page, 300, 300, 200, 200)+ rect(graph, 'InnerA', parent.id, 0, 0, 100, 100)+ rect(graph, 'InnerB', parent.id, 50, 50, 100, 100)++ const result = computeOverlaps(graph, { scope: 'top-level' })+ expect(result.summary.overlapCount).toBe(1)+ expect(result.overlaps[0].nodeA.parentId).toBe(page)+ expect(result.overlaps[0].nodeB.parentId).toBe(page)+ })++ test('scope=inside-parent only reports children inside a non-page parent', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ rect(graph, 'TopA', page, 0, 0, 100, 100)+ rect(graph, 'TopB', page, 50, 50, 100, 100)+ const parent = frame(graph, 'Parent', page, 300, 300, 200, 200)+ rect(graph, 'InnerA', parent.id, 0, 0, 100, 100)+ rect(graph, 'InnerB', parent.id, 50, 50, 100, 100)++ const result = computeOverlaps(graph, { scope: 'inside-parent' })+ expect(result.summary.overlapCount).toBe(1)+ expect(result.overlaps[0].nodeA.parentId).toBe(parent.id)+ expect(result.overlaps[0].nodeB.parentId).toBe(parent.id)+ })++ test('respects min_ratio threshold', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const parent = frame(graph, 'Parent', page, 0, 0, 200, 200)+ rect(graph, 'A', parent.id, 0, 0, 100, 100)+ rect(graph, 'B', parent.id, 50, 50, 100, 100)++ const excluded = computeOverlaps(graph, { scope: 'same-parent', min_ratio: 0.5 })+ expect(excluded.overlaps).toHaveLength(0)++ const included = computeOverlaps(graph, { scope: 'same-parent', min_ratio: 0.1 })+ expect(included.overlaps.length).toBeGreaterThan(0)+ })++ test('excludes locked nodes by default', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const locked = rect(graph, 'Locked', page, 0, 0, 100, 100)+ graph.updateNode(locked.id, { locked: true })+ rect(graph, 'A', page, 50, 50, 100, 100)++ const result = computeOverlaps(graph)+ expect(+ result.overlaps.some((o) => o.nodeA.name === 'Locked' || o.nodeB.name === 'Locked')+ ).toBe(false)+ })++ test('includes locked nodes when include_locked is true', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const locked = rect(graph, 'Locked', page, 0, 0, 100, 100)+ graph.updateNode(locked.id, { locked: true })+ rect(graph, 'A', page, 50, 50, 100, 100)++ const result = computeOverlaps(graph, { include_locked: true })+ expect(+ result.overlaps.some((o) => o.nodeA.name === 'Locked' || o.nodeB.name === 'Locked')+ ).toBe(true)+ })++ test('excludes absolutely-positioned nodes by default', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const absolute = rect(graph, 'Absolute', page, 0, 0, 100, 100)+ graph.updateNode(absolute.id, { layoutPositioning: 'ABSOLUTE' })+ rect(graph, 'A', page, 50, 50, 100, 100)++ const result = computeOverlaps(graph)+ expect(+ result.overlaps.some((o) => o.nodeA.name === 'Absolute' || o.nodeB.name === 'Absolute')+ ).toBe(false)+ })++ test('includes absolutely-positioned nodes when include_absolute is true', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const absolute = rect(graph, 'Absolute', page, 0, 0, 100, 100)+ graph.updateNode(absolute.id, { layoutPositioning: 'ABSOLUTE' })+ rect(graph, 'A', page, 50, 50, 100, 100)++ const result = computeOverlaps(graph, { include_absolute: true })+ expect(+ result.overlaps.some((o) => o.nodeA.name === 'Absolute' || o.nodeB.name === 'Absolute')+ ).toBe(true)+ })++ test('filters results by page name', () => {+ const graph = new SceneGraph()+ const page1 = pageId(graph)+ const page2 = graph.addPage('Page 2')++ const a1 = rect(graph, 'A1', page1, 0, 0, 100, 100)+ const a2 = rect(graph, 'A2', page1, 50, 50, 100, 100)+ const b1 = rect(graph, 'B1', page2.id, 0, 0, 100, 100)+ const b2 = rect(graph, 'B2', page2.id, 50, 50, 100, 100)++ const page1Result = computeOverlaps(graph, { page: 'Page 1' })+ expect(page1Result.overlaps.length).toBeGreaterThan(0)+ expect(+ page1Result.overlaps.every(+ (o) =>+ (o.nodeA.id === a1.id || o.nodeA.id === a2.id) &&+ (o.nodeB.id === a1.id || o.nodeB.id === a2.id)+ )+ ).toBe(true)++ const page2Result = computeOverlaps(graph, { page: 'Page 2' })+ expect(page2Result.overlaps.length).toBeGreaterThan(0)+ expect(+ page2Result.overlaps.every(+ (o) =>+ (o.nodeA.id === b1.id || o.nodeA.id === b2.id) &&+ (o.nodeB.id === b1.id || o.nodeB.id === b2.id)+ )+ ).toBe(true)++ const missing = computeOverlaps(graph, { page: 'Missing' })+ expect(missing.overlaps).toHaveLength(0)+ })++ test('scope values are case-insensitive', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ rect(graph, 'A', page, 0, 0, 100, 100)+ rect(graph, 'B', page, 50, 50, 100, 100)++ const result = computeOverlaps(graph, { scope: 'SAME-PARENT' as OverlapScope })+ expect(result.overlaps.length).toBeGreaterThan(0)+ })++ test('ToolDef defaults to current page and does not report overlaps on other pages', () => {+ const graph = new SceneGraph()+ const page2 = graph.addPage('Page 2')++ rect(graph, 'A', page2.id, 0, 0, 100, 100)+ rect(graph, 'B', page2.id, 50, 50, 100, 100)++ const api = new FigmaAPI(graph)+ const result = analyzeOverlaps.execute(api, {})+ expect(result.summary.overlapCount).toBe(0)+ expect(result.overlaps).toHaveLength(0)+ })++ test('ToolDef respects explicit page argument', () => {+ const graph = new SceneGraph()+ const page2 = graph.addPage('Page 2')++ rect(graph, 'A', page2.id, 0, 0, 100, 100)+ rect(graph, 'B', page2.id, 50, 50, 100, 100)++ const api = new FigmaAPI(graph)+ const result = analyzeOverlaps.execute(api, { page: 'Page 2' })+ expect(result.summary.overlapCount).toBeGreaterThan(0)+ })++ test('scope=top-level excludes nested parent-overflow', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const parent = frame(graph, 'Frame', page, 0, 0, 80, 80)+ text(graph, 'Wide', parent.id, 0, 0, 200, 20)++ const all = computeOverlaps(graph)+ expect(all.overlaps.some((o) => o.category === 'parent-overflow')).toBe(true)++ const topLevel = computeOverlaps(graph, { scope: 'top-level' })+ expect(topLevel.overlaps.some((o) => o.category === 'parent-overflow')).toBe(false)+ })++ test('scope=inside-parent includes nested parent-overflow', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const parent = frame(graph, 'Frame', page, 0, 0, 80, 80)+ text(graph, 'Wide', parent.id, 0, 0, 200, 20)++ const result = computeOverlaps(graph, { scope: 'inside-parent' })+ expect(result.overlaps.some((o) => o.category === 'parent-overflow')).toBe(true)+ })++ test('skips nodes inside a hidden ancestor by default', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const hiddenParent = frame(graph, 'HiddenParent', page, 0, 0, 200, 200)+ graph.updateNode(hiddenParent.id, { visible: false })+ rect(graph, 'A', hiddenParent.id, 0, 0, 100, 100)+ rect(graph, 'B', hiddenParent.id, 50, 50, 100, 100)++ const result = computeOverlaps(graph)+ expect(result.summary.overlapCount).toBe(0)+ })++ test('includes nodes inside a hidden ancestor when include_hidden is true', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const hiddenParent = frame(graph, 'HiddenParent', page, 0, 0, 200, 200)+ graph.updateNode(hiddenParent.id, { visible: false })+ rect(graph, 'A', hiddenParent.id, 0, 0, 100, 100)+ rect(graph, 'B', hiddenParent.id, 50, 50, 100, 100)++ const result = computeOverlaps(graph, { include_hidden: true })+ expect(result.summary.overlapCount).toBeGreaterThan(0)+ })++ test('skips nodes inside a locked ancestor by default', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const lockedParent = frame(graph, 'LockedParent', page, 0, 0, 200, 200)+ graph.updateNode(lockedParent.id, { locked: true })+ rect(graph, 'A', lockedParent.id, 0, 0, 100, 100)+ rect(graph, 'B', lockedParent.id, 50, 50, 100, 100)++ const result = computeOverlaps(graph)+ expect(result.summary.overlapCount).toBe(0)+ })++ test('summary totals reflect full result set when a limit is applied', () => {+ const graph = new SceneGraph()+ const page = pageId(graph)+ const parent = frame(graph, 'Frame', page, 0, 0, 200, 200)++ for (let i = 0; i < 4; i++) {+ rect(graph, `R${i}`, parent.id, 0, 0, 100, 100)+ }++ const result = computeOverlaps(graph, { scope: 'inside-parent', limit: 2 })+ expect(result.overlaps.length).toBe(2)+ expect(result.summary.overlapCount).toBeGreaterThan(2)++ const totalByCategory = Object.values(result.summary.byCategory).reduce((a, b) => a + b, 0)+ expect(totalByCategory).toBe(result.summary.overlapCount)+ const totalBySeverity = Object.values(result.summary.bySeverity).reduce((a, b) => a + b, 0)+ expect(totalBySeverity).toBe(result.summary.overlapCount)+ })+})diff --git a/tests/engine/tools/analyze/overlaps/page-scope.test.ts b/tests/engine/tools/analyze/overlaps/page-scope.test.tsnew file mode 100644index 000000000..6e0b13b88--- /dev/null+++ b/tests/engine/tools/analyze/overlaps/page-scope.test.ts@@ -0,0 +1,90 @@+import { describe, expect, test } from 'bun:test'++import { FigmaAPI, SceneGraph } from '@open-pencil/core'+import {+ analyzeOverlaps,+ computeOverlaps,+ findPageId+} from '@open-pencil/core/tools/analyze/overlaps'++import { pageId, rect } from './helpers'++describe('analyze overlaps page scope', () => {+ test('default scope limits analysis to a single page', () => {+ const graph = new SceneGraph()+ const page1 = pageId(graph)+ const page2 = graph.addPage('Page 2')++ rect(graph, 'A', page1, 0, 0, 100, 100)+ rect(graph, 'B', page1, 50, 50, 100, 100)+ rect(graph, 'C', page2.id, 0, 0, 100, 100)+ rect(graph, 'D', page2.id, 50, 50, 100, 100)++ const result = computeOverlaps(graph)+ expect(result.summary.overlapCount).toBe(1)+ expect(result.overlaps).toHaveLength(1)+ expect(+ result.overlaps.every((o) => {+ const nodeA = graph.getNode(o.nodeA.id)+ const nodeB = graph.getNode(o.nodeB.id)+ if (!nodeA || !nodeB) return false+ return findPageId(graph, nodeA) === page1 && findPageId(graph, nodeB) === page1+ })+ ).toBe(true)+ })++ test('missing page name returns an empty result', () => {+ const graph = new SceneGraph()+ const page1 = pageId(graph)+ const page2 = graph.addPage('Page 2')++ rect(graph, 'A', page1, 0, 0, 100, 100)+ rect(graph, 'B', page1, 50, 50, 100, 100)+ rect(graph, 'C', page2.id, 0, 0, 100, 100)+ rect(graph, 'D', page2.id, 50, 50, 100, 100)++ const result = computeOverlaps(graph, { page: 'Missing' })+ expect(result.summary.totalNodes).toBe(0)+ expect(result.summary.analyzedNodes).toBe(0)+ expect(result.summary.overlapCount).toBe(0)+ expect(result.overlaps).toHaveLength(0)+ })++ test('ToolDef currentPage default uses page ID so duplicate page names do not leak', () => {+ const graph = new SceneGraph()+ const page1 = pageId(graph)+ const page2 = graph.addPage('Page 1')++ rect(graph, 'A', page2.id, 0, 0, 100, 100)+ rect(graph, 'B', page2.id, 50, 50, 100, 100)++ const api = new FigmaAPI(graph)+ expect(api.currentPageId).toBe(page1)++ const defaultResult = analyzeOverlaps.execute(api, {})+ expect(defaultResult.summary.overlapCount).toBe(0)+ expect(defaultResult.overlaps).toHaveLength(0)++ api.currentPage = api.wrapNode(page2.id)+ const currentResult = analyzeOverlaps.execute(api, {})+ expect(currentResult.summary.overlapCount).toBeGreaterThan(0)+ })++ test('page_id argument disambiguates duplicate page names', () => {+ const graph = new SceneGraph()+ const page1 = pageId(graph)+ const page2 = graph.addPage('Page 1')++ rect(graph, 'A', page2.id, 0, 0, 100, 100)+ rect(graph, 'B', page2.id, 50, 50, 100, 100)++ const byId = computeOverlaps(graph, { page_id: page2.id })+ expect(byId.summary.overlapCount).toBe(1)++ const byName = computeOverlaps(graph, { page: 'Page 1' })+ expect(byName.summary.overlapCount).toBe(0)++ const byFirstPage = computeOverlaps(graph, { page_id: page1 })+ expect(byFirstPage.summary.overlapCount).toBe(0)+ })+})diff --git a/tests/helpers/paths.ts b/tests/helpers/paths.tsindex cd33e27af..3c6d868b7 100644--- a/tests/helpers/paths.ts+++ b/tests/helpers/paths.ts@@ -1,3 +1,4 @@+import { existsSync } from 'node:fs'import { join } from 'node:path'const repoRoot = join(import.meta.dir, '..', '..')@@ -21,3 +22,12 @@ export function testPath(...segments: string[]): string {export function publicPath(...segments: string[]): string {return repoPath('public', ...segments)}++export function requireBuiltWorkspacePackages(): void {+ const coreDist = repoPath('packages/core/dist/index.js')+ if (!existsSync(coreDist)) {+ throw new Error(+ 'CLI integration tests require built workspace packages. Run `bun run check` or `bun run --filter @open-pencil/core build` first.'+ )+ }+}