diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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-30
 
diff --git a/README.md b/README.md
index f2c3b6fa1..a369dcdce 100644
--- a/README.md
+++ b/README.md
@@ -111,6 +111,7 @@ openpencil analyze colors design.fig
 openpencil analyze typography design.fig
 openpencil analyze spacing design.fig
 openpencil analyze clusters design.fig
+openpencil analyze overlaps design.fig
 openpencil variables design.fig
 ```
 
diff --git a/packages/cli/src/commands/analyze/index.ts b/packages/cli/src/commands/analyze/index.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 : file
       const 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.ts
index 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.length
   console.log(ok(`Exported ${path} (${(size / 1024).toFixed(1)} KB)`))
 }
diff --git a/packages/cli/src/headless.ts b/packages/cli/src/headless.ts
index 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 graph
diff --git a/packages/core/package.json b/packages/core/package.json
index 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.ts
index 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 = 0
   for (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 = 0
   let right = 0
   let 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.ts
index 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, AnalyzeClus
     return { 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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,
   // Codegen
diff --git a/tests/engine/cli/eval.test.ts b/tests/engine/cli/eval.test.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.'
+    )
+  }
+}