uicore-ts 1.1.310 → 1.1.315

package/scripts/UILayoutDebugger.ts

@@ -0,0 +1,3252 @@
+/// #if DEV
+
+/**
+ * UILayoutDebugger
+ *
+ * A development-only utility for visualizing and debugging the UIView layout
+ * system. Disabled entirely at runtime unless explicitly enabled.
+ *
+ * FEATURES
+ * ─────────
+ *
+ * 1. Record-and-replay step debugger
+ *    Every layout pass is recorded as an ordered sequence of steps. Each step
+ *    captures the view that was laid out, its frame before and after, and the
+ *    frames assigned to each of its subviews. After the pass completes you can
+ *    scrub through the steps one at a time in the overlay UI, seeing exactly
+ *    which view was processed at each point and how the frames changed.
+ *
+ * 2. Live breakpoint step-through
+ *    When breakpoint mode is enabled (UILayoutDebugger.enableBreakpoints()), a
+ *    special sentinel line is executed before each view's layoutIfNeeded() call.
+ *    Put a browser debugger breakpoint on that line and the JS debugger will
+ *    pause before every layout step — the full live JS stack and all object
+ *    state are available at that point, exactly as with any other breakpoint.
+ *
+ *    The sentinel line is:
+ *      const breakpointOnThisLine = "Add a breakpoint on this line to step through layout."
+ *    Search for that string in the Sources panel to find it quickly.
+ *
+ * 3. View-tree heat-map overlay
+ *    A floating panel renders the full view hierarchy as an indented tree.
+ *    Each node is coloured by how many times it was laid out in the most recent
+ *    pass: untouched (grey), once (green), twice (orange), three-or-more (red).
+ *    The node currently active in the step scrubber is highlighted in blue.
+ *    Hovering a node shows its class, elementID, and frame.
+ *
+ * INTEGRATION POINTS IN UIView.ts
+ * ────────────────────────────────
+ * Add the following calls alongside the existing UILayoutCycleTracer calls:
+ *
+ *   layoutViewsIfNeeded():
+ *     window.UILayoutDebugger?.willBeginLayoutPass(UIView._viewsToLayout)    // before the while loop
+ *     window.UILayoutDebugger?.willBeginIteration(iteration)                 // inside the while loop, top
+ *     window.UILayoutDebugger?.willLayoutView(view)                          // before view.layoutIfNeeded()
+ *     [breakpoint sentinel — see below]
+ *     view.layoutIfNeeded()
+ *     window.UILayoutDebugger?.didLayoutView(view)                           // after view.layoutIfNeeded()
+ *     window.UILayoutDebugger?.didFinishLayoutPass(iteration)                // after the while loop
+ *
+ *   layoutSubviews():
+ *     window.UILayoutDebugger?.willSetSubviewFrames(this)                    // before the subview loop
+ *     [existing subview loop]
+ *     window.UILayoutDebugger?.didSetSubviewFrames(this)                     // after the subview loop
+ *
+ *   The breakpoint sentinel block (inside layoutViewsIfNeeded, before
+ *   view.layoutIfNeeded()):
+ *
+ *     if (window.UILayoutDebugger?._shouldHitBreakpoint(view)) {
+ *         const breakpointOnThisLine = "Add a breakpoint on this line to step through layout."
+ *     }
+ *
+ * USAGE
+ * ─────
+ *   UILayoutDebugger.enable()            — record traces and show the overlay
+ *   UILayoutDebugger.disable()           — hide overlay and stop recording
+ *   UILayoutDebugger.enableBreakpoints() — also pause at each layout step
+ *   UILayoutDebugger.stepForward()       — advance the replay scrubber by one
+ *   UILayoutDebugger.stepBack()          — retreat the replay scrubber by one
+ *   UILayoutDebugger.goToStep(n)         — jump to step n (0-based)
+ */
+
+
+// ─── Data model ─────────────────────────────────────────────────────────────
+
+interface UILayoutDebugFrame {
+    top: number
+    left: number
+    width: number
+    height: number
+}
+
+/** A snapshot of a view's intrinsic size cache at a point in time. */
+interface UILayoutDebugCacheSnapshot {
+    entryCount: number
+    entries: Record<string, { width: number; height: number }>
+    isShared: boolean
+    sharedKey?: string
+    /** Whether _frameCache was populated at snapshot time. */
+    hasFrameCache: boolean
+    /** Snapshot of _frameCache if populated; null if absent. */
+    frameCache: UILayoutDebugFrame | null
+    /** Whether _frameCacheForVirtualLayouting was populated at snapshot time. */
+    hasVirtualFrameCache: boolean
+    /** Snapshot of _frameCacheForVirtualLayouting if populated; null if absent. */
+    virtualFrameCache: UILayoutDebugFrame | null
+}
+
+/**
+ * Global UITextMeasurement cache sizes at a snapshot instant.
+ * These are not per-view — they're attached to the snapshot as a whole.
+ */
+interface UILayoutDebugTextMeasurementSnapshot {
+    preparedCacheSize: number
+    styleCacheSize: number
+}
+
+interface UILayoutDebugSubviewRecord {
+    viewIndex: number           // _UIViewIndex of the subview
+    className: string
+    elementID: string
+    frameBefore: UILayoutDebugFrame | null
+    frameAfter: UILayoutDebugFrame | null
+}
+
+/** What caused a view to enter the layout queue. */
+interface UILayoutDebugTrigger {
+    callerFunction: string      // first application frame, e.g. "MyView.layoutSubviews"
+    cleanStack: string          // full cleaned stack string
+}
+
+/** One step = one call to layoutIfNeeded() on one view. */
+interface UILayoutDebugStep {
+    stepIndex: number
+    iteration: number
+    viewIndex: number           // _UIViewIndex of the laid-out view
+    className: string
+    elementID: string
+    frameBefore: UILayoutDebugFrame | null
+    frameAfter: UILayoutDebugFrame | null
+    cacheBefore: UILayoutDebugCacheSnapshot | null
+    cacheAfter: UILayoutDebugCacheSnapshot | null
+    subviewRecords: UILayoutDebugSubviewRecord[]
+    trigger: UILayoutDebugTrigger | null    // what called setNeedsLayout on this view
+}
+
+interface UILayoutDebugTreeNode {
+    viewIndex: number
+    className: string
+    elementID: string
+    depth: number
+    frame: UILayoutDebugFrame | null
+    layoutCount: number         // times laid out in the recorded pass
+    cacheAfterPass: UILayoutDebugCacheSnapshot | null   // intrinsic cache state after the pass
+    children: UILayoutDebugTreeNode[]
+}
+
+interface UILayoutDebugTrace {
+    passIndex: number
+    steps: UILayoutDebugStep[]
+    roots: UILayoutDebugTreeNode[]
+    totalIterations: number
+    cacheChanges: UILayoutDebugCacheChangeEvent[]
+}
+
+/** A flat snapshot of every view's frame and intrinsic cache at a point in time. */
+interface UILayoutDebugStateSnapshot {
+    label: string
+    takenAt: number                          // Date.now()
+    views: Map<number, UILayoutDebugViewState>
+    /** Global UITextMeasurement cache sizes at the instant this snapshot was taken. */
+    textMeasurement: UILayoutDebugTextMeasurementSnapshot
+}
+
+interface UILayoutDebugViewState {
+    viewIndex: number
+    className: string
+    elementID: string
+    frame: UILayoutDebugFrame | null
+    cache: UILayoutDebugCacheSnapshot | null
+}
+
+type UILayoutDebugDiffKind = "appeared" | "disappeared" | "frame" | "cache" | "both" | "unchanged"
+
+interface UILayoutDebugViewDiff {
+    kind: UILayoutDebugDiffKind
+    viewIndex: number
+    className: string
+    elementID: string
+    baselineFrame: UILayoutDebugFrame | null
+    currentFrame: UILayoutDebugFrame | null
+    baselineCache: UILayoutDebugCacheSnapshot | null
+    currentCache: UILayoutDebugCacheSnapshot | null
+}
+
+/**
+ * Fired when _getCachedIntrinsicSize returns a value that differs from the
+ * last value we observed for that view+cacheKey combination.
+ */
+interface UILayoutDebugCacheChangeEvent {
+    eventIndex: number
+    stepIndex: number           // which step was active when the write occurred (-1 = between steps)
+    iteration: number
+    viewIndex: number
+    className: string
+    elementID: string
+    cacheKey: string            // raw key, e.g. "h_0__w_500"
+    newValue: { width: number; height: number }
+    callerFunction: string      // first app-code frame at point of write
+    cleanStack: string
+}
+
+
+// ─── Main class ──────────────────────────────────────────────────────────────
+
+export class UILayoutDebugger {
+    
+    // ── Runtime guard ────────────────────────────────────────────────────────
+    // The #if DEV preprocessor comment may not be present in every build.
+    // This flag is the authoritative runtime gate. All hook methods check it
+    // first and are no-ops unless _isEnabled is true.
+    
+    static _isEnabled: boolean = false
+    static _breakpointsEnabled: boolean = false
+    
+    static get isEnabled(): boolean { return UILayoutDebugger._isEnabled }
+    static get breakpointsEnabled(): boolean { return UILayoutDebugger._breakpointsEnabled }
+    
+    
+    // ── Recording state ──────────────────────────────────────────────────────
+    
+    static _passIndex: number = 0
+    static _currentTrace: UILayoutDebugTrace | null = null
+    static _currentIteration: number = 0
+    
+    // Pending step being built as a view is being laid out
+    static _pendingStep: UILayoutDebugStep | null = null
+    
+    // Subview frames captured during layoutSubviews() of the pending step's view
+    static _pendingSubviewsBefore: Map<number, UILayoutDebugFrame | null> = new Map()
+    
+    // Per-view layout counts for the current pass (used for tree colouring)
+    static _layoutCountsThisPass: Map<number, number> = new Map()
+    
+    // Live view object references keyed by _UIViewIndex, populated during the
+    // pass and used to build the subtree forest in didFinishLayoutPass.
+    static _liveViewRegistry: Map<number, any> = new Map()
+    
+    // First setNeedsLayout trigger per view per pass. Only the first enqueue
+    // is recorded — subsequent redundant calls on the same view are ignored.
+    static _triggerMap: Map<number, UILayoutDebugTrigger> = new Map()
+    
+    // Stack frames belonging to framework internals that should be stripped
+    // from the top of a captured stack so the first visible frame is always
+    // application code.
+    static _noiseFramePrefixes: string[] = [
+        "UILayoutDebugger",
+        "UIView.setNeedsLayout",
+        "setNeedsLayout",
+        "UIView.didLayoutSubviews",
+        "didLayoutSubviews",
+        "UIView.layoutSubviews",
+        "UIView.layoutIfNeeded",
+        "layoutIfNeeded",
+        "UIView.layoutViewsIfNeeded",
+        "layoutViewsIfNeeded",
+        "UIView._setCachedIntrinsicSize",
+        "_setCachedIntrinsicSize",
+    ]
+    
+    // All completed traces, newest first
+    static _traces: UILayoutDebugTrace[] = []
+    static readonly maxStoredTraces = 20
+    
+    
+    // ── Replay state ─────────────────────────────────────────────────────────
+    
+    static _replayTraceIndex: number = 0     // which trace is shown in left/single pane
+    static _replayStepIndex: number = -1     // -1 = before any step
+    
+    // ── Compare mode state ────────────────────────────────────────────────────
+    
+    static _compareMode: boolean = false
+    static _frameFilter: "all" | "changed" | "unchanged" = "all"
+    
+    /**
+     * When true, frame comparisons ignore origin (x/y) and only consider size
+     * (width/height) — i.e. they diff bounds rather than frames.
+     * A position-only move does not trigger a layout recompute of content, so
+     * bounds mode surfaces only the changes that actually matter for sizing.
+     */
+    static _boundsBasedDiff: boolean = false
+    static _compareTraceIndex: number = 1    // which trace is shown in right pane
+    static _compareStepIndex: number = -1
+    
+    // Shared expand/collapse state for the tree in compare mode, keyed by
+    // viewIndex. When both trees render from the same map, toggling one node
+    // collapses/expands the same node in both panes simultaneously.
+    static _sharedExpandState: Map<number, boolean> = new Map()
+    
+    // Expand state for the single-column pass inspector. Kept persistent so
+    // the live inspector can sync from it.
+    static _singleExpandState: Map<number, boolean> = new Map()
+    
+    // Expand state for the live inspector panel.
+    static _liveExpandState: Map<number, boolean> = new Map()
+    
+    
+    // ── Public API ───────────────────────────────────────────────────────────
+    
+    static enable() {
+        UILayoutDebugger._isEnabled = true
+        UILayoutDebugger._ensureOverlay()
+        UILayoutDebugger._renderOverlay()
+        console.log(
+            "%c[UILayoutDebugger] ENABLED — recording layout traces and showing overlay.",
+            "color: #4CAF50; font-weight: bold"
+        )
+    }
+    
+    static disable() {
+        UILayoutDebugger._isEnabled = false
+        UILayoutDebugger._breakpointsEnabled = false
+        UILayoutDebugger._removeOverlay()
+        console.log(
+            "%c[UILayoutDebugger] DISABLED.",
+            "color: #9E9E9E; font-weight: bold"
+        )
+    }
+    
+    /**
+     * Enable the breakpoint sentinel. Once enabled, _shouldHitBreakpoint()
+     * returns true before every layoutIfNeeded() call so the browser debugger
+     * can pause on the sentinel line in UIView.ts.
+     */
+    static enableBreakpoints() {
+        if (!UILayoutDebugger._isEnabled) {
+            UILayoutDebugger.enable()
+        }
+        UILayoutDebugger._breakpointsEnabled = true
+        console.log(
+            "%c[UILayoutDebugger] Breakpoint mode ON. " +
+            "Search for 'breakpointOnThisLine' in Sources to set your breakpoint.",
+            "color: #FF9800; font-weight: bold"
+        )
+    }
+    
+    static disableBreakpoints() {
+        UILayoutDebugger._breakpointsEnabled = false
+        console.log(
+            "%c[UILayoutDebugger] Breakpoint mode OFF.",
+            "color: #9E9E9E"
+        )
+    }
+    
+    // ── Replay controls ──────────────────────────────────────────────────────
+    
+    static stepForward() {
+        if (!UILayoutDebugger._isEnabled) { return }
+        const trace = UILayoutDebugger._currentReplayTrace
+        if (!trace) { return }
+        const next = UILayoutDebugger._replayStepIndex + 1
+        UILayoutDebugger.goToStep(Math.min(next, trace.steps.length - 1))
+    }
+    
+    static stepBack() {
+        if (!UILayoutDebugger._isEnabled) { return }
+        UILayoutDebugger.goToStep(Math.max(UILayoutDebugger._replayStepIndex - 1, -1))
+    }
+    
+    static goToStep(stepIndex: number) {
+        if (!UILayoutDebugger._isEnabled) { return }
+        UILayoutDebugger._replayStepIndex = stepIndex
+        UILayoutDebugger._renderOverlay()
+    }
+    
+    static goToCompareStep(stepIndex: number) {
+        if (!UILayoutDebugger._isEnabled) { return }
+        UILayoutDebugger._compareStepIndex = stepIndex
+        UILayoutDebugger._renderOverlay()
+    }
+    
+    static showTrace(traceIndex: number) {
+        if (!UILayoutDebugger._isEnabled) { return }
+        const clamped = Math.max(0, Math.min(traceIndex, UILayoutDebugger._traces.length - 1))
+        UILayoutDebugger._replayTraceIndex = clamped
+        UILayoutDebugger._replayStepIndex = -1
+        UILayoutDebugger._singleExpandState = new Map()
+        UILayoutDebugger._renderOverlay()
+    }
+    
+    static showCompareTrace(traceIndex: number) {
+        if (!UILayoutDebugger._isEnabled) { return }
+        const clamped = Math.max(0, Math.min(traceIndex, UILayoutDebugger._traces.length - 1))
+        UILayoutDebugger._compareTraceIndex = clamped
+        UILayoutDebugger._compareStepIndex = -1
+        UILayoutDebugger._renderOverlay()
+    }
+    
+    static get _currentReplayTrace(): UILayoutDebugTrace | null {
+        return UILayoutDebugger._traces[UILayoutDebugger._replayTraceIndex] ?? null
+    }
+    
+    static get _currentCompareTrace(): UILayoutDebugTrace | null {
+        return UILayoutDebugger._traces[UILayoutDebugger._compareTraceIndex] ?? null
+    }
+    
+    
+    // ── Hook: called from layoutViewsIfNeeded() ──────────────────────────────
+    
+    static willBeginLayoutPass(viewsToLayout: any[]) {
+        if (!UILayoutDebugger._isEnabled) { return }
+        
+        UILayoutDebugger._currentTrace = {
+            passIndex: UILayoutDebugger._passIndex++,
+            steps: [],
+            roots: [],
+            cacheChanges: [],
+            totalIterations: 0,
+        }
+        UILayoutDebugger._currentIteration = 0
+        UILayoutDebugger._layoutCountsThisPass = new Map()
+        UILayoutDebugger._liveViewRegistry = new Map()
+        UILayoutDebugger._pendingStep = null
+        UILayoutDebugger._pendingSubviewsBefore = new Map()
+    }
+    
+    static willBeginIteration(iteration: number) {
+        if (!UILayoutDebugger._isEnabled) { return }
+        UILayoutDebugger._currentIteration = iteration
+    }
+    
+    /**
+     * Called from setNeedsLayout() each time a view is enqueued.
+     * Only the *first* enqueue per view per pass is recorded — that is the
+     * call that actually caused the view to enter the queue. Subsequent calls
+     * on the same view within the same pass are redundant and ignored.
+     */
+    static viewDidCallSetNeedsLayout(view: any) {
+        if (!UILayoutDebugger._isEnabled) { return }
+        
+        const viewIdx: number = view?._UIViewIndex ?? -1
+        if (viewIdx < 0) { return }
+        
+        // Only record the first enqueue per view per pass.
+        if (UILayoutDebugger._triggerMap.has(viewIdx)) { return }
+        
+        const rawStack = new Error().stack ?? ""
+        const cleanStack = UILayoutDebugger._cleanStack(rawStack)
+        const callerFunction = UILayoutDebugger._extractCallerFunctionName(cleanStack)
+        
+        UILayoutDebugger._triggerMap.set(viewIdx, { callerFunction, cleanStack })
+    }
+    
+    /**
+     * Called from _setCachedIntrinsicSize() after the value is written.
+     * Every write is a change by definition, so no history comparison is needed.
+     *
+     * Call site in UIView.ts, at the end of _setCachedIntrinsicSize():
+     *
+     *   window.UILayoutDebugger?.didSetCachedIntrinsicSize(this, cacheKey, size)
+     */
+    static didSetCachedIntrinsicSize(view: any, cacheKey: string, value: any) {
+        if (!UILayoutDebugger._isEnabled) { return }
+        
+        const trace = UILayoutDebugger._currentTrace
+        if (!trace) { return }
+        
+        const viewIdx: number = view?._UIViewIndex ?? -1
+        if (viewIdx < 0) { return }
+        
+        const rawStack = new Error().stack ?? ""
+        const cleanStack = UILayoutDebugger._cleanStack(rawStack)
+        const callerFunction = UILayoutDebugger._extractCallerFunctionName(cleanStack)
+        
+        const event: UILayoutDebugCacheChangeEvent = {
+            eventIndex: trace.cacheChanges.length,
+            stepIndex: UILayoutDebugger._pendingStep?.stepIndex ?? -1,
+            iteration: UILayoutDebugger._currentIteration,
+            viewIndex: viewIdx,
+            className: view?.constructor?.name ?? "UnknownView",
+            elementID: view?.elementID ?? String(viewIdx),
+            cacheKey,
+            newValue: { width: value?.width ?? 0, height: value?.height ?? 0 },
+            callerFunction,
+            cleanStack,
+        }
+        trace.cacheChanges.push(event)
+    }
+    static willLayoutView(view: any) {
+        if (!UILayoutDebugger._isEnabled) { return }
+        
+        const stepIndex = UILayoutDebugger._currentTrace?.steps.length ?? 0
+        const viewIdx: number = view?._UIViewIndex ?? -1
+        
+        // Keep a live reference so didFinishLayoutPass can reach .rootView.
+        if (viewIdx >= 0) {
+            UILayoutDebugger._liveViewRegistry.set(viewIdx, view)
+        }
+        
+        UILayoutDebugger._pendingStep = {
+            stepIndex,
+            iteration: UILayoutDebugger._currentIteration,
+            viewIndex: viewIdx,
+            className: view?.constructor?.name ?? "UnknownView",
+            elementID: view?.elementID ?? String(viewIdx),
+            frameBefore: UILayoutDebugger._captureFrame(view),
+            frameAfter: null,
+            cacheBefore: UILayoutDebugger._captureCache(view),
+            cacheAfter: null,
+            subviewRecords: [],
+            trigger: UILayoutDebugger._triggerMap.get(viewIdx) ?? null,
+        }
+        // Consume the trigger so it doesn't linger across future passes.
+        UILayoutDebugger._triggerMap.delete(viewIdx)
+        
+        // Capture subview frames *before* layout. The post-layout capture
+        // happens in didSetSubviewFrames() which is called from layoutSubviews().
+        UILayoutDebugger._pendingSubviewsBefore = new Map()
+        const subviews: any[] = view?.subviews ?? []
+        for (let i = 0; i < subviews.length; i++) {
+            const sv = subviews[i]
+            const idx: number = sv?._UIViewIndex ?? -i
+            UILayoutDebugger._pendingSubviewsBefore.set(idx, UILayoutDebugger._captureFrame(sv))
+        }
+    }
+    
+    /**
+     * Called immediately after view.layoutIfNeeded(). Closes the pending step
+     * with the post-layout frame.
+     */
+    static didLayoutView(view: any) {
+        if (!UILayoutDebugger._isEnabled) { return }
+        
+        const step = UILayoutDebugger._pendingStep
+        if (!step) { return }
+        
+        step.frameAfter = UILayoutDebugger._captureFrame(view)
+        step.cacheAfter = UILayoutDebugger._captureCache(view)
+        
+        const viewIdx: number = view?._UIViewIndex ?? -1
+        const prev = UILayoutDebugger._layoutCountsThisPass.get(viewIdx) ?? 0
+        UILayoutDebugger._layoutCountsThisPass.set(viewIdx, prev + 1)
+        
+        UILayoutDebugger._currentTrace?.steps.push(step)
+        UILayoutDebugger._pendingStep = null
+    }
+    
+    static didFinishLayoutPass(iterationCount: number) {
+        if (!UILayoutDebugger._isEnabled) { return }
+        
+        const trace = UILayoutDebugger._currentTrace
+        if (!trace) { return }
+        
+        trace.totalIterations = iterationCount
+        
+        // Build a single full-tree snapshot by starting from the global root.
+        // Any laid-out view has a .rootView property that walks to the top of
+        // the hierarchy, giving full context around the affected views.
+        const anyView = UILayoutDebugger._liveViewRegistry.values().next().value
+        const rootView = anyView?.rootView
+        if (rootView) {
+            UILayoutDebugger._lastKnownRootView = rootView
+            const visited = new Set<number>()
+            const rootIdx: number = rootView._UIViewIndex ?? -1
+            if (rootIdx >= 0) { visited.add(rootIdx) }
+            trace.roots = [UILayoutDebugger._buildTreeSnapshot(rootView, 0, visited)]
+        }
+        
+        // Prepend and evict old traces.
+        UILayoutDebugger._traces.unshift(trace)
+        if (UILayoutDebugger._traces.length > UILayoutDebugger.maxStoredTraces) {
+            UILayoutDebugger._traces.length = UILayoutDebugger.maxStoredTraces
+        }
+        
+        UILayoutDebugger._replayTraceIndex = 0
+        UILayoutDebugger._replayStepIndex = -1
+        UILayoutDebugger._currentTrace = null
+        UILayoutDebugger._liveViewRegistry.clear()
+        
+        UILayoutDebugger._renderOverlay()
+    }
+    
+    /** Discard all recorded traces and reset the replay state. */
+    static clearTraces() {
+        UILayoutDebugger._traces = []
+        UILayoutDebugger._passIndex = 0
+        UILayoutDebugger._replayTraceIndex = 0
+        UILayoutDebugger._compareTraceIndex = 1
+        UILayoutDebugger._replayStepIndex = -1
+        UILayoutDebugger._compareStepIndex = -1
+        UILayoutDebugger._renderOverlay()
+    }
+    
+    // ── Baseline / diff API ──────────────────────────────────────────────────
+    
+    /** Capture the current view tree state as the baseline for future diffs. */
+    static captureBaseline() {
+        if (!UILayoutDebugger._isEnabled) { return }
+        const snap = UILayoutDebugger._captureStateSnapshot("Baseline")
+        if (!snap) {
+            console.warn("[UILayoutDebugger] captureBaseline: no root view found yet — trigger a layout pass first.")
+            return
+        }
+        UILayoutDebugger._baseline = snap
+        UILayoutDebugger._diffSnapshot = null
+        UILayoutDebugger._diffMode = false
+        UILayoutDebugger._renderOverlay()
+        console.log(
+            `%c[UILayoutDebugger] Baseline captured — ${snap.views.size} views.`,
+            "color: #88ddff; font-weight: bold"
+        )
+    }
+    
+    /** Capture the current state and diff it against the baseline. */
+    static captureAndDiff() {
+        if (!UILayoutDebugger._isEnabled) { return }
+        if (!UILayoutDebugger._baseline) {
+            console.warn("[UILayoutDebugger] captureAndDiff: no baseline set. Call captureBaseline() first.")
+            return
+        }
+        const snap = UILayoutDebugger._captureStateSnapshot("Current")
+        if (!snap) {
+            console.warn("[UILayoutDebugger] captureAndDiff: could not find root view.")
+            return
+        }
+        UILayoutDebugger._diffSnapshot = snap
+        UILayoutDebugger._diffMode = true
+        UILayoutDebugger._renderOverlay()
+    }
+    
+    static clearDiff() {
+        UILayoutDebugger._baseline = null
+        UILayoutDebugger._diffSnapshot = null
+        UILayoutDebugger._diffMode = false
+        UILayoutDebugger._renderOverlay()
+    }
+    
+    /**
+     * ☢  Stale Layout Report
+     *
+     * The single authoritative way to discover missing cache invalidations.
+     *
+     * What this does, in order:
+     *   1. Snapshots every view's frame and intrinsic cache right now (the
+     *      "before" state — potentially stale/incorrect).
+     *   2. Calls performForcedSubtreeLayout() on the root view, which nukes all
+     *      caches and forces a complete cold remeasure of the entire tree.
+     *   3. Snapshots again ("after" state — ground truth).
+     *   4. Diffs the two snapshots.  Any view that changed between before and
+     *      after had stale state that was never correctly invalidated.
+     *   5. For each changed view, cross-references the cache writes from the
+     *      forced pass so you can see exactly which call path recomputed the
+     *      correct value — working backwards from that to find the missing
+     *      invalidation site.
+     *
+     * The result is shown in the ☢ Stale panel to the right of the pass
+     * inspector.  Views corrected by the forced pass are also tinted amber in
+     * the pass inspector tree on the subsequent pass.
+     *
+     * Limitations:
+     *   - Calls performForcedSubtreeLayout(), which is itself a nuclear option.
+     *     The tree will be left in its corrected state — not the buggy state.
+     *     Use this at the point where the bug is visible, not before.
+     *   - The forced layout will generate a new trace (the remeasure pass).
+     *     The ☢ panel cross-references its cache writes automatically.
+     *   - Only intrinsic-size cache corrections are cross-referenced. Frame
+     *     corrections are shown as diffs but do not yet have a write-stack.
+     */
+    static captureStaleLayoutReport() {
+        if (!UILayoutDebugger._isEnabled) { return }
+        const rootView = UILayoutDebugger._lastKnownRootView
+        if (!rootView) {
+            console.warn(
+                "[UILayoutDebugger] captureStaleLayoutReport: no root view found yet — " +
+                "trigger a layout pass first."
+            )
+            return
+        }
+        
+        // Step 1 — snapshot before.
+        // We pin rootView here and pass it directly to a targeted walk rather than
+        // going through _lastKnownRootView, because performForcedSubtreeLayout
+        // drives layoutViewsIfNeeded synchronously, which fires didFinishLayoutPass,
+        // which may update _lastKnownRootView to a detached view that was temporarily
+        // inserted into document.body for intrinsic-size measurement.  If that
+        // happened the "after" snapshot would walk from a completely different root
+        // than "before", causing spurious diffs for every view in the real tree.
+        const before = UILayoutDebugger._captureStateSnapshotFromRoot(rootView, "Before (potentially stale)")
+        
+        // Step 2 — nuclear reset
+        rootView.performForcedSubtreeLayout?.()
+        
+        // Step 3 — snapshot after (ground truth), using the same pinned root.
+        const after = UILayoutDebugger._captureStateSnapshotFromRoot(rootView, "After (forced cold remeasure)")
+        
+        // Step 4 — diff
+        const diffs = UILayoutDebugger._diffSnapshots(before, after)
+            .filter(d => d.kind !== "unchanged")
+        
+        // Step 5 — collect cache writes from the forced pass (the trace that was
+        // just recorded by performForcedSubtreeLayout), keyed by viewIndex.
+        const forcedPassCacheChanges = new Map<number, UILayoutDebugCacheChangeEvent[]>()
+        const forcedTrace = UILayoutDebugger._traces[0] ?? null  // newest = the forced pass
+        const forcedPassIndex = forcedTrace?.passIndex ?? -1
+        if (forcedTrace) {
+            for (const ev of forcedTrace.cacheChanges) {
+                let bucket = forcedPassCacheChanges.get(ev.viewIndex)
+                if (!bucket) {
+                    bucket = []
+                    forcedPassCacheChanges.set(ev.viewIndex, bucket)
+                }
+                bucket.push(ev)
+            }
+        }
+        
+        UILayoutDebugger._staleReportResult = { before, after, diffs, forcedPassCacheChanges, passIndex: forcedPassIndex }
+        UILayoutDebugger._staleReportMode = true
+        UILayoutDebugger._renderOverlay()
+        
+        const correctedCount = diffs.length
+        console.log(
+            `%c[UILayoutDebugger] Stale layout report: ${correctedCount} view(s) had stale state corrected by forced layout.`,
+            "color: #ffaa55; font-weight: bold"
+        )
+    }
+    
+    static clearStaleReport() {
+        UILayoutDebugger._staleReportResult = null
+        UILayoutDebugger._staleReportMode = false
+        UILayoutDebugger._renderOverlay()
+    }
+    
+    static toggleLiveInspector() {
+        UILayoutDebugger._liveInspectorMode = !UILayoutDebugger._liveInspectorMode
+        UILayoutDebugger._renderOverlay()
+    }
+    
+    static _captureStateSnapshot(label: string): UILayoutDebugStateSnapshot | null {
+        const rootView = UILayoutDebugger._lastKnownRootView
+        if (!rootView) { return null }
+        return UILayoutDebugger._captureStateSnapshotFromRoot(rootView, label)
+    }
+    
+    /**
+     * Like _captureStateSnapshot but walks from an explicit root rather than
+     * _lastKnownRootView. Use this whenever the root must be pinned across a
+     * call that may update _lastKnownRootView (e.g. captureStaleLayoutReport,
+     * which drives a layout pass internally).
+     */
+    static _captureStateSnapshotFromRoot(rootView: any, label: string): UILayoutDebugStateSnapshot {
+        const views = new Map<number, UILayoutDebugViewState>()
+        UILayoutDebugger._walkViewTree(rootView, views, new Set())
+        
+        // Read UITextMeasurement global cache sizes. Both maps are private, but
+        // accessible via the class reference on window if exposed, or via the
+        // module-level import. We reach them defensively so the debugger never
+        // throws if the import shape changes.
+        const tm: any = (window as any).UITextMeasurement
+        const textMeasurement: UILayoutDebugTextMeasurementSnapshot = {
+            preparedCacheSize: tm?._preparedCache?.size ?? -1,
+            styleCacheSize:    tm?.globalStyleCache?.size ?? -1,
+        }
+        
+        return { label, takenAt: Date.now(), views, textMeasurement }
+    }
+    
+    static _walkViewTree(
+        view: any,
+        out: Map<number, UILayoutDebugViewState>,
+        visited: Set<number>,
+    ) {
+        const idx: number = view?._UIViewIndex ?? -1
+        if (idx < 0 || visited.has(idx)) { return }
+        visited.add(idx)
+        
+        out.set(idx, {
+            viewIndex: idx,
+            className: view?.constructor?.name ?? "UnknownView",
+            elementID: view?.elementID ?? String(idx),
+            frame: UILayoutDebugger._captureFrame(view),
+            cache: UILayoutDebugger._captureCache(view),
+        })
+        
+        const subviews: any[] = view?.subviews ?? []
+        for (const sv of subviews) { UILayoutDebugger._walkViewTree(sv, out, visited) }
+    }
+    
+    static _diffSnapshots(
+        baseline: UILayoutDebugStateSnapshot,
+        current: UILayoutDebugStateSnapshot,
+    ): UILayoutDebugViewDiff[] {
+        const diffs: UILayoutDebugViewDiff[] = []
+        const allKeys = new Set([...baseline.views.keys(), ...current.views.keys()])
+        
+        for (const idx of allKeys) {
+            const b = baseline.views.get(idx) ?? null
+            const c = current.views.get(idx) ?? null
+            
+            if (!b) {
+                diffs.push({ kind: "appeared", viewIndex: idx,
+                    className: c!.className, elementID: c!.elementID,
+                    baselineFrame: null, currentFrame: c!.frame,
+                    baselineCache: null, currentCache: c!.cache })
+                continue
+            }
+            if (!c) {
+                diffs.push({ kind: "disappeared", viewIndex: idx,
+                    className: b.className, elementID: b.elementID,
+                    baselineFrame: b.frame, currentFrame: null,
+                    baselineCache: b.cache, currentCache: null })
+                continue
+            }
+            
+            const frameChanged = UILayoutDebugger._framesEqual(b.frame, c.frame) === false
+            const cacheChanged = UILayoutDebugger._cachesEqual(b.cache, c.cache) === false
+            const kind: UILayoutDebugDiffKind =
+                frameChanged && cacheChanged ? "both"
+                                             : frameChanged ? "frame"
+                                                            : cacheChanged ? "cache"
+                                                                           : "unchanged"
+            
+            diffs.push({ kind, viewIndex: idx,
+                className: c.className, elementID: c.elementID,
+                baselineFrame: b.frame, currentFrame: c.frame,
+                baselineCache: b.cache, currentCache: c.cache })
+        }
+        
+        // Sort: appeared, disappeared, both, frame, cache, unchanged
+        const order: Record<UILayoutDebugDiffKind, number> = {
+            appeared: 0, disappeared: 1, both: 2, frame: 3, cache: 4, unchanged: 5,
+        }
+        diffs.sort((a, b) => order[a.kind] - order[b.kind])
+        return diffs
+    }
+    
+    static _framesEqual(a: UILayoutDebugFrame | null, b: UILayoutDebugFrame | null): boolean {
+        if (!a && !b) { return true }
+        if (!a || !b) { return false }
+        if (UILayoutDebugger._boundsBasedDiff) {
+            // Bounds mode: ignore origin, compare size only.
+            return a.width === b.width && a.height === b.height
+        }
+        return a.left === b.left && a.top === b.top && a.width === b.width && a.height === b.height
+    }
+    
+    static _cachesEqual(a: UILayoutDebugCacheSnapshot | null, b: UILayoutDebugCacheSnapshot | null): boolean {
+        if (!a && !b) { return true }
+        if (!a || !b) { return false }
+        if (a.entryCount !== b.entryCount) { return false }
+        for (const key of Object.keys(a.entries)) {
+            const ae = a.entries[key]
+            const be = b.entries[key]
+            if (!be || ae.width !== be.width || ae.height !== be.height) { return false }
+        }
+        if (a.hasFrameCache !== b.hasFrameCache) { return false }
+        if (a.hasFrameCache && b.hasFrameCache) {
+            const af = a.frameCache, bf = b.frameCache
+            if (!af || !bf || af.top !== bf.top || af.left !== bf.left || af.width !== bf.width || af.height !== bf.height) { return false }
+        }
+        if (a.hasVirtualFrameCache !== b.hasVirtualFrameCache) { return false }
+        if (a.hasVirtualFrameCache && b.hasVirtualFrameCache) {
+            const av = a.virtualFrameCache, bv = b.virtualFrameCache
+            if (!av || !bv || av.top !== bv.top || av.left !== bv.left || av.width !== bv.width || av.height !== bv.height) { return false }
+        }
+        return true
+    }
+    
+    
+    // ── Hook: called from layoutSubviews() ───────────────────────────────────
+    
+    /**
+     * Called at the top of layoutSubviews(), before the subview frame loop.
+     * Nothing to do here — before-frames were already captured in willLayoutView().
+     */
+    static willSetSubviewFrames(_view: any) {
+        // Reserved for future use; before-frames captured in willLayoutView().
+    }
+    
+    /**
+     * Called at the bottom of layoutSubviews(), after the subview frame loop.
+     * Merges the before/after subview frames into the pending step.
+     */
+    static didSetSubviewFrames(view: any) {
+        if (!UILayoutDebugger._isEnabled) { return }
+        
+        const step = UILayoutDebugger._pendingStep
+        if (!step) { return }
+        
+        const subviews: any[] = view?.subviews ?? []
+        for (let i = 0; i < subviews.length; i++) {
+            const sv = subviews[i]
+            const idx: number = sv?._UIViewIndex ?? -i
+            const record: UILayoutDebugSubviewRecord = {
+                viewIndex: idx,
+                className: sv?.constructor?.name ?? "UnknownView",
+                elementID: sv?.elementID ?? String(idx),
+                frameBefore: UILayoutDebugger._pendingSubviewsBefore.get(idx) ?? null,
+                frameAfter: UILayoutDebugger._captureFrame(sv),
+            }
+            step.subviewRecords.push(record)
+        }
+    }
+    
+    
+    // ── Breakpoint sentinel ──────────────────────────────────────────────────
+    
+    /**
+     * Returns true when breakpoints are enabled, causing the sentinel block
+     * in UIView.ts to execute. Put a browser debugger breakpoint on the
+     * `const breakpointOnThisLine` assignment inside that block.
+     */
+    static _shouldHitBreakpoint(_view: any): boolean {
+        return UILayoutDebugger._isEnabled && UILayoutDebugger._breakpointsEnabled
+    }
+    
+    
+    // ── Internal helpers ─────────────────────────────────────────────────────
+    
+    static _cleanStack(rawStack: string): string {
+        const lines = rawStack.split("\n")
+        let firstAppFrameIndex = 1 // skip the "Error" header on line 0
+        
+        for (let i = 1; i < lines.length; i++) {
+            const trimmed = lines[i].trim()
+            
+            // V8 frame: "at ClassName.methodName (file:line:col)"
+            // or:       "at methodName (file:line:col)"
+            // or:       "at file:line:col"
+            // Extract just the function/method name for noise matching.
+            const atMatch = trimmed.match(/^at\s+([\w.<>$\s]+?)\s*(?:\(|$)/)
+            const frameName = atMatch ? atMatch[1].trim() : trimmed
+            
+            // The method name is the part after the last dot (if any).
+            const methodName = frameName.includes(".")
+                               ? frameName.slice(frameName.lastIndexOf(".") + 1)
+                               : frameName
+            
+            const isNoise = UILayoutDebugger._noiseFramePrefixes.some(prefix => {
+                // Match against the full qualified name OR just the method name,
+                // so "setNeedsLayout" catches UITextField.setNeedsLayout too.
+                return frameName === prefix || methodName === prefix || frameName.endsWith("." + prefix)
+            })
+            
+            if (!isNoise) {
+                firstAppFrameIndex = i
+                break
+            }
+        }
+        return lines.slice(firstAppFrameIndex).join("\n")
+    }
+    
+    static _extractCallerFunctionName(cleanStack: string): string {
+        const firstLine = cleanStack.split("\n")[0]?.trim() ?? ""
+        // V8: "at ClassName.methodName (file:line:col)"
+        const atMatch = firstLine.match(/^at\s+([\w.<>$\s]+?)\s*(?:\(|$)/)
+        if (atMatch) { return atMatch[1].trim() }
+        return firstLine.substring(0, 80) || "(unknown)"
+    }
+    
+    static _captureFrame(view: any): UILayoutDebugFrame | null {
+        const f = view?._frame
+        if (!f) { return null }
+        return {
+            top: f.top ?? f.y ?? 0,
+            left: f.left ?? f.x ?? 0,
+            width: f.width ?? 0,
+            height: f.height ?? 0,
+        }
+    }
+    
+    static _captureCache(view: any): UILayoutDebugCacheSnapshot | null {
+        if (!view) { return null }
+        const sharedKey: string | undefined = view.sharedIntrinsicSizeCacheIdentifier
+        const isShared = !!sharedKey
+        let rawEntries: Record<string, any>
+        if (isShared) {
+            rawEntries = (view.constructor?._sharedIntrinsicSizeCaches ?? view.__proto__?.constructor?._sharedIntrinsicSizeCaches)
+                ?.get(sharedKey) ?? {}
+        }
+        else {
+            rawEntries = view._intrinsicSizesCache ?? {}
+        }
+        const entries: Record<string, { width: number; height: number }> = {}
+        for (const key of Object.keys(rawEntries)) {
+            const r = rawEntries[key]
+            entries[key] = { width: r?.width ?? 0, height: r?.height ?? 0 }
+        }
+        
+        // Frame caches — these are per-instance UIRectangle | undefined fields.
+        const rawFrameCache = view._frameCache
+        const rawVirtualFrameCache = view._frameCacheForVirtualLayouting
+        const frameCache: UILayoutDebugFrame | null = rawFrameCache
+                                                      ? { top: rawFrameCache.top ?? rawFrameCache.y ?? 0, left: rawFrameCache.left ?? rawFrameCache.x ?? 0, width: rawFrameCache.width ?? 0, height: rawFrameCache.height ?? 0 }
+                                                      : null
+        const virtualFrameCache: UILayoutDebugFrame | null = rawVirtualFrameCache
+                                                             ? { top: rawVirtualFrameCache.top ?? rawVirtualFrameCache.y ?? 0, left: rawVirtualFrameCache.left ?? rawVirtualFrameCache.x ?? 0, width: rawVirtualFrameCache.width ?? 0, height: rawVirtualFrameCache.height ?? 0 }
+                                                             : null
+        
+        return {
+            entryCount: Object.keys(entries).length,
+            entries,
+            isShared,
+            sharedKey,
+            hasFrameCache: rawFrameCache !== undefined,
+            frameCache,
+            hasVirtualFrameCache: rawVirtualFrameCache !== undefined,
+            virtualFrameCache,
+        }
+    }
+    
+    static _buildTreeSnapshot(
+        view: any,
+        depth: number,
+        visited: Set<number> = new Set(),
+    ): UILayoutDebugTreeNode {
+        const idx: number = view?._UIViewIndex ?? -1
+        const node: UILayoutDebugTreeNode = {
+            viewIndex: idx,
+            className: view?.constructor?.name ?? "UnknownView",
+            elementID: view?.elementID ?? String(idx),
+            depth,
+            frame: UILayoutDebugger._captureFrame(view),
+            layoutCount: UILayoutDebugger._layoutCountsThisPass.get(idx) ?? 0,
+            cacheAfterPass: UILayoutDebugger._captureCache(view),
+            children: [],
+        }
+        const subviews: any[] = view?.subviews ?? []
+        for (let i = 0; i < subviews.length; i++) {
+            const sv = subviews[i]
+            const svIdx: number = sv?._UIViewIndex ?? -1
+            if (svIdx < 0 || visited.has(svIdx)) { continue }
+            visited.add(svIdx)
+            node.children.push(UILayoutDebugger._buildTreeSnapshot(sv, depth + 1, visited))
+        }
+        return node
+    }
+    
+    
+    // ── Baseline / diff state ─────────────────────────────────────────────────
+    
+    static _baseline: UILayoutDebugStateSnapshot | null = null
+    static _diffSnapshot: UILayoutDebugStateSnapshot | null = null
+    static _diffMode: boolean = false
+    static _liveInspectorMode: boolean = false
+    
+    // ── Stale layout report state ─────────────────────────────────────────────
+    
+    /** Result of the last captureStaleLayoutReport() run. */
+    static _staleReportResult: {
+        before: UILayoutDebugStateSnapshot
+        after: UILayoutDebugStateSnapshot
+        diffs: UILayoutDebugViewDiff[]
+        /** viewIndex → cacheChanges from the forced-layout pass, for cross-referencing */
+        forcedPassCacheChanges: Map<number, UILayoutDebugCacheChangeEvent[]>
+        passIndex: number
+    } | null = null
+    
+    /** Whether the stale report side-panel is open. */
+    static _staleReportMode: boolean = false
+    
+    // Persists across passes so captureBaseline() works between passes.
+    static _lastKnownRootView: any = null
+    
+    /**
+     * Finds the first trace (chronologically) recorded after baselineTakenAt
+     * that contains a step for the given viewIndex. Returns {traceIndex, stepIndex}
+     * into _traces, or null if none found.
+     */
+    static _findCausingTrace(
+        viewIndex: number,
+        baselineTakenAt: number,
+    ): { traceIndex: number; stepIndex: number; passIndex: number } | null {
+        // _traces is newest-first, so iterate in reverse for chronological order
+        for (let ti = UILayoutDebugger._traces.length - 1; ti >= 0; ti--) {
+            const trace = UILayoutDebugger._traces[ti]
+            // We don't store a timestamp on traces, but passIndex is monotonically
+            // increasing. The baseline was taken at a wall-clock time; the closest
+            // proxy is to find traces whose passIndex is greater than any pass that
+            // completed before the baseline. Since we can't correlate exactly, we
+            // just find the first trace (oldest) that touched the view and show it.
+            const si = trace.steps.findIndex(s => s.viewIndex === viewIndex)
+            if (si >= 0) {
+                return { traceIndex: ti, stepIndex: si, passIndex: trace.passIndex }
+            }
+        }
+        return null
+    }
+    
+    // ── Overlay UI ───────────────────────────────────────────────────────────
+    
+    static _overlayRoot: HTMLElement | null = null
+    static _overlayVisible: boolean = true
+    static _helpMode: boolean = false
+    
+    static _ensureOverlay() {
+        if (UILayoutDebugger._overlayRoot) { return }
+        
+        const root = document.createElement("div")
+        root.id = "__UILayoutDebugger_overlay"
+        root.style.cssText = [
+            "position: fixed",
+            "top: 8px",
+            "right: 8px",
+            "max-height: calc(100vh - 16px)",
+            "background: rgba(15, 15, 20, 0.96)",
+            "color: #e8e8e8",
+            "font: 11px/1.4 'SF Mono', 'Menlo', 'Consolas', monospace",
+            "border-radius: 8px",
+            "border: 1px solid rgba(255,255,255,0.12)",
+            "box-shadow: 0 8px 32px rgba(0,0,0,0.6)",
+            "z-index: 2147483647",
+            "display: flex",
+            "flex-direction: column",
+            "overflow: hidden",
+            "user-select: none",
+        ].join("; ")
+        
+        document.body.appendChild(root)
+        UILayoutDebugger._overlayRoot = root
+        UILayoutDebugger._makeDraggable(root)
+    }
+    
+    static _removeOverlay() {
+        UILayoutDebugger._overlayRoot?.remove()
+        UILayoutDebugger._overlayRoot = null
+    }
+    
+    static _renderOverlay() {
+        const root = UILayoutDebugger._overlayRoot
+        if (!root) { return }
+        
+        const cmp = UILayoutDebugger._compareMode
+        const diff = UILayoutDebugger._diffMode && !!UILayoutDebugger._baseline && !!UILayoutDebugger._diffSnapshot
+        const live = UILayoutDebugger._liveInspectorMode && !!UILayoutDebugger._lastKnownRootView
+        const stale = UILayoutDebugger._staleReportMode && !!UILayoutDebugger._staleReportResult
+        const passWidth = cmp ? 1140 : 570
+        const extraWidth = (diff ? 320 : 0) + (live ? 320 : 0) + (stale ? 360 : 0)
+        root.style.width = (passWidth + extraWidth) + "px"
+        root.innerHTML = ""
+        
+        // ── Header ──────────────────────────────────────────────────────────
+        // ── Header row 1: title + core controls ─────────────────────────────
+        const headerRow1 = UILayoutDebugger._el("div", [
+            "padding: 8px 10px 5px",
+            "background: rgba(255,255,255,0.05)",
+            "display: flex",
+            "align-items: center",
+            "gap: 6px",
+            "cursor: move",
+            "flex-shrink: 0",
+        ])
+        headerRow1.dataset.dragHandle = "1"
+        
+        const title = UILayoutDebugger._el("span", ["flex: 1", "font-weight: bold", "font-size: 11px", "color: #c8d8ff"])
+        title.textContent = "⚙ UILayoutDebugger"
+        
+        const helpBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle(
+            UILayoutDebugger._helpMode ? "#ffcc88" : "#9090a8"
+        ))
+        helpBtn.textContent = "ⓘ"
+        helpBtn.title = "Show help"
+        helpBtn.onclick = () => {
+            UILayoutDebugger._helpMode = !UILayoutDebugger._helpMode
+            UILayoutDebugger._renderOverlay()
+        }
+        
+        const bpBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle(
+            UILayoutDebugger._breakpointsEnabled ? "#ffaa33" : "#9090a8"
+        ))
+        bpBtn.textContent = UILayoutDebugger._breakpointsEnabled ? "⏸ BP ON" : "⏸ BP OFF"
+        bpBtn.title = "Toggle breakpoint step-through"
+        bpBtn.onclick = () => {
+            UILayoutDebugger._breakpointsEnabled
+            ? UILayoutDebugger.disableBreakpoints()
+            : UILayoutDebugger.enableBreakpoints()
+            UILayoutDebugger._renderOverlay()
+        }
+        
+        const cmpBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle(cmp ? "#7bc8ff" : "#9090a8"))
+        cmpBtn.textContent = cmp ? "⧉ Compare ON" : "⧉ Compare"
+        cmpBtn.title = "Toggle side-by-side pass comparison"
+        cmpBtn.onclick = () => {
+            UILayoutDebugger._compareMode = !UILayoutDebugger._compareMode
+            if (UILayoutDebugger._compareMode) {
+                UILayoutDebugger._compareTraceIndex = Math.min(1, UILayoutDebugger._traces.length - 1)
+                UILayoutDebugger._compareStepIndex = -1
+                UILayoutDebugger._sharedExpandState = new Map()
+            }
+            UILayoutDebugger._renderOverlay()
+        }
+        
+        const filterLabels: Record<string, string> = {
+            all:       "⊘ All",
+            changed:   "⊘ Changed",
+            unchanged: "⊘ Unchanged",
+        }
+        const filterColors: Record<string, string> = {
+            all:       "#9090a8",
+            changed:   "#7bc8ff",
+            unchanged: "#ffcc88",
+        }
+        const filterCycle: Record<string, "all" | "changed" | "unchanged"> = {
+            all: "changed", changed: "unchanged", unchanged: "all",
+        }
+        const filterBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle(
+            filterColors[UILayoutDebugger._frameFilter]
+        ))
+        filterBtn.textContent = filterLabels[UILayoutDebugger._frameFilter]
+        filterBtn.title = "Cycle: show all steps → only changed frames → only unchanged frames"
+        filterBtn.onclick = () => {
+            UILayoutDebugger._frameFilter = filterCycle[UILayoutDebugger._frameFilter]
+            UILayoutDebugger._replayStepIndex = -1
+            UILayoutDebugger._compareStepIndex = -1
+            UILayoutDebugger._renderOverlay()
+        }
+        
+        const clearBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle("#9090a8"))
+        clearBtn.textContent = "⌫ Clear"
+        clearBtn.title = "Clear all recorded traces and restart recording"
+        clearBtn.onclick = () => UILayoutDebugger.clearTraces()
+        
+        const toggleBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle("#9090a8"))
+        toggleBtn.textContent = UILayoutDebugger._overlayVisible ? "▾" : "▸"
+        toggleBtn.title = "Collapse / expand"
+        toggleBtn.onclick = () => {
+            UILayoutDebugger._overlayVisible = !UILayoutDebugger._overlayVisible
+            UILayoutDebugger._renderOverlay()
+        }
+        
+        const closeBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle("#dd5555"))
+        closeBtn.textContent = "✕"
+        closeBtn.title = "Disable UILayoutDebugger"
+        closeBtn.onclick = () => UILayoutDebugger.disable()
+        
+        headerRow1.append(title, helpBtn, bpBtn, cmpBtn, filterBtn, clearBtn, toggleBtn, closeBtn)
+        
+        // ── Header row 2: baseline / diff and future feature buttons ─────────
+        const headerRow2 = UILayoutDebugger._el("div", [
+            "padding: 4px 10px 6px",
+            "background: rgba(255,255,255,0.05)",
+            "border-bottom: 1px solid rgba(255,255,255,0.10)",
+            "display: flex",
+            "align-items: center",
+            "gap: 6px",
+            "flex-shrink: 0",
+            "flex-wrap: wrap",
+        ])
+        headerRow2.dataset.dragHandle = "1"
+        
+        const hasBaseline = !!UILayoutDebugger._baseline
+        const baselineBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle(
+            UILayoutDebugger._diffMode ? "#88ddff" : hasBaseline ? "#ffcc88" : "#9090a8"
+        ))
+        baselineBtn.textContent = UILayoutDebugger._diffMode
+                                  ? "⊕ Diff ON"
+                                  : hasBaseline ? "📍 Baseline set" : "📍 Baseline"
+        baselineBtn.title = hasBaseline
+                            ? "Baseline captured — click to recapture, or use ⊕ to diff against it"
+                            : "Capture current view tree state as baseline"
+        baselineBtn.onclick = () => {
+            if (UILayoutDebugger._diffMode) {
+                UILayoutDebugger.clearDiff()
+            } else {
+                UILayoutDebugger.captureBaseline()
+            }
+        }
+        
+        const diffBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle(
+            hasBaseline ? "#88ff99" : "#9090a8"
+        )) as HTMLButtonElement
+        diffBtn.textContent = "⊕ Diff"
+        diffBtn.title = "Capture current state and diff against baseline"
+        diffBtn.disabled = !hasBaseline
+        diffBtn.onclick = () => UILayoutDebugger.captureAndDiff()
+        
+        const liveBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle(
+            live ? "#88ff99" : "#9090a8"
+        ))
+        liveBtn.textContent = live ? "👁 Live ON" : "👁 Live"
+        liveBtn.title = "Show live view tree with current frames and cache state"
+        liveBtn.onclick = () => UILayoutDebugger.toggleLiveInspector()
+        
+        const hasStaleResult = !!UILayoutDebugger._staleReportResult
+        const staleBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle(
+            stale ? "#ffaa55" : hasStaleResult ? "#a06030" : "#9090a8"
+        ))
+        staleBtn.textContent = stale ? "☢ Stale ON" : "☢ Stale"
+        staleBtn.title = hasStaleResult
+                         ? "Stale layout report available — click to toggle the panel, or re-run to refresh"
+                         : "Run a forced full-tree remeasure and show which views had stale/missing invalidations"
+        staleBtn.onclick = () => {
+            if (stale) {
+                // Panel already open — toggle it off
+                UILayoutDebugger._staleReportMode = false
+                UILayoutDebugger._renderOverlay()
+            }
+            else if (hasStaleResult) {
+                // Result exists but panel is closed — reopen it
+                UILayoutDebugger._staleReportMode = true
+                UILayoutDebugger._renderOverlay()
+            }
+            else {
+                UILayoutDebugger.captureStaleLayoutReport()
+            }
+        }
+        
+        // Long-press / right-click to re-run even when a result already exists
+        staleBtn.oncontextmenu = (e) => {
+            e.preventDefault()
+            UILayoutDebugger.captureStaleLayoutReport()
+        }
+        
+        const boundsToggleBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle(
+            UILayoutDebugger._boundsBasedDiff ? "#c8d8ff" : "#9090a8"
+        ))
+        boundsToggleBtn.textContent = UILayoutDebugger._boundsBasedDiff ? "⬚ Bounds" : "⬚ Frame"
+        boundsToggleBtn.title = UILayoutDebugger._boundsBasedDiff
+                                ? "Diffing by bounds (size only — origin ignored). Click to switch to frame diffing (position + size)."
+                                : "Diffing by frame (position + size). Click to switch to bounds diffing (size only — position changes are ignored)."
+        boundsToggleBtn.onclick = () => {
+            UILayoutDebugger._boundsBasedDiff = !UILayoutDebugger._boundsBasedDiff
+            UILayoutDebugger._renderOverlay()
+        }
+        
+        headerRow2.append(baselineBtn, diffBtn, liveBtn, staleBtn, boundsToggleBtn)
+        
+        // ── Wrap both rows in the header container ────────────────────────────
+        const header = UILayoutDebugger._el("div", ["flex-shrink: 0"])
+        header.append(headerRow1, headerRow2)
+        root.appendChild(header)
+        
+        if (!UILayoutDebugger._overlayVisible) { return }
+        
+        // ── Help panel ───────────────────────────────────────────────────────
+        if (UILayoutDebugger._helpMode) {
+            root.appendChild(UILayoutDebugger._renderHelpPanel())
+            return
+        }
+        
+        // ── Baseline captured but no diff yet ────────────────────────────────
+        if (UILayoutDebugger._baseline && !diff) {
+            const msg = UILayoutDebugger._el("div", [
+                "padding: 8px 12px",
+                "color: #ffcc88",
+                "font-size: 10px",
+                "border-bottom: 1px solid rgba(255,255,255,0.08)",
+                "flex-shrink: 0",
+            ])
+            const ts = new Date(UILayoutDebugger._baseline.takenAt)
+            msg.textContent = `📍 Baseline set at ${ts.toLocaleTimeString()} — ${UILayoutDebugger._baseline.views.size} views. Hit ⊕ Diff to compare.`
+            root.appendChild(msg)
+        }
+        
+        if (UILayoutDebugger._traces.length === 0 && !diff) {
+            const msg = UILayoutDebugger._el("div", ["padding: 10px 12px", "color: #9090a8", "font-size: 10px"])
+            msg.textContent = "No layout pass recorded yet. Trigger a layout to begin."
+            root.appendChild(msg)
+            return
+        }
+        
+        // ── Main body: pass inspector + optional diff panel ──────────────────
+        const body = UILayoutDebugger._el("div", [
+            "display: flex",
+            "flex: 1",
+            "overflow: hidden",
+            "min-height: 0",
+        ])
+        root.appendChild(body)
+        
+        // ── Pass inspector (single or compare columns) ────────────────────────
+        if (UILayoutDebugger._traces.length > 0) {
+            const passSection = UILayoutDebugger._el("div", [
+                "display: flex",
+                "flex: 1",
+                "overflow: hidden",
+                "min-height: 0",
+            ])
+            
+            if (cmp) {
+                let leftTreeEl: HTMLElement | null = null
+                let rightTreeEl: HTMLElement | null = null
+                
+                const leftCol = UILayoutDebugger._renderPassColumn(
+                    UILayoutDebugger._replayTraceIndex,
+                    UILayoutDebugger._replayStepIndex,
+                    (si) => { UILayoutDebugger._replayStepIndex = si; UILayoutDebugger._renderOverlay() },
+                    (ti) => { UILayoutDebugger._replayTraceIndex = ti; UILayoutDebugger._replayStepIndex = -1; UILayoutDebugger._renderOverlay() },
+                    UILayoutDebugger._sharedExpandState,
+                    (el) => { leftTreeEl = el },
+                    () => rightTreeEl,
+                )
+                const colDivider = UILayoutDebugger._el("div", [
+                    "width: 1px", "background: rgba(255,255,255,0.10)", "flex-shrink: 0",
+                ])
+                const rightCol = UILayoutDebugger._renderPassColumn(
+                    UILayoutDebugger._compareTraceIndex,
+                    UILayoutDebugger._compareStepIndex,
+                    (si) => { UILayoutDebugger._compareStepIndex = si; UILayoutDebugger._renderOverlay() },
+                    (ti) => { UILayoutDebugger._compareTraceIndex = ti; UILayoutDebugger._compareStepIndex = -1; UILayoutDebugger._renderOverlay() },
+                    UILayoutDebugger._sharedExpandState,
+                    (el) => { rightTreeEl = el },
+                    () => leftTreeEl,
+                )
+                passSection.append(leftCol, colDivider, rightCol)
+            }
+            else {
+                const col = UILayoutDebugger._renderPassColumn(
+                    UILayoutDebugger._replayTraceIndex,
+                    UILayoutDebugger._replayStepIndex,
+                    (si) => { UILayoutDebugger._replayStepIndex = si; UILayoutDebugger._renderOverlay() },
+                    (ti) => { UILayoutDebugger._replayTraceIndex = ti; UILayoutDebugger._replayStepIndex = -1; UILayoutDebugger._renderOverlay() },
+                    UILayoutDebugger._singleExpandState,
+                    () => {},
+                    () => null,
+                )
+                col.style.flex = "1"
+                passSection.appendChild(col)
+            }
+            
+            body.appendChild(passSection)
+        }
+        
+        // ── Diff panel ────────────────────────────────────────────────────────
+        if (diff) {
+            const divider = UILayoutDebugger._el("div", [
+                "width: 1px", "background: rgba(255,255,255,0.10)", "flex-shrink: 0",
+            ])
+            const diffPanel = UILayoutDebugger._renderDiffPanel(
+                UILayoutDebugger._baseline!,
+                UILayoutDebugger._diffSnapshot!,
+                (viewIndex) => {
+                    for (let ti = 0; ti < UILayoutDebugger._traces.length; ti++) {
+                        const trace = UILayoutDebugger._traces[ti]
+                        const si = trace.steps.findIndex(s => s.viewIndex === viewIndex)
+                        if (si >= 0) {
+                            UILayoutDebugger._replayTraceIndex = ti
+                            UILayoutDebugger._replayStepIndex = si
+                            UILayoutDebugger._renderOverlay()
+                            return
+                        }
+                    }
+                },
+                UILayoutDebugger._baseline!.takenAt,
+            )
+            diffPanel.style.width = "320px"
+            diffPanel.style.flexShrink = "0"
+            body.append(divider, diffPanel)
+        }
+        
+        // ── Live inspector panel ──────────────────────────────────────────────
+        if (live) {
+            const divider = UILayoutDebugger._el("div", [
+                "width: 1px", "background: rgba(255,255,255,0.10)", "flex-shrink: 0",
+            ])
+            const livePanel = UILayoutDebugger._renderLiveInspectorPanel()
+            livePanel.style.width = "320px"
+            livePanel.style.flexShrink = "0"
+            body.append(divider, livePanel)
+        }
+        
+        // ── Stale layout report panel ─────────────────────────────────────────
+        if (stale) {
+            const divider = UILayoutDebugger._el("div", [
+                "width: 1px", "background: rgba(255,255,255,0.10)", "flex-shrink: 0",
+            ])
+            const stalePanel = UILayoutDebugger._renderStaleReportPanel(UILayoutDebugger._staleReportResult!)
+            stalePanel.style.width = "360px"
+            stalePanel.style.flexShrink = "0"
+            body.append(divider, stalePanel)
+        }
+    }
+    
+    static _renderPassColumn(
+        traceIndex: number,
+        stepIndex: number,
+        onStepChange: (si: number) => void,
+        onTraceChange: (ti: number) => void,
+        expandState: Map<number, boolean> | null,
+        registerTree: (el: HTMLElement) => void,
+        getPeerTree: () => HTMLElement | null,
+    ): HTMLElement {
+        const col = UILayoutDebugger._el("div", [
+            "display: flex",
+            "flex-direction: column",
+            "flex: 1",
+            "min-width: 0",
+            "overflow: hidden",
+        ])
+        
+        const trace = UILayoutDebugger._traces[traceIndex] ?? null
+        
+        // ── Trace picker ─────────────────────────────────────────────────────
+        const pickerRow = UILayoutDebugger._el("div", [
+            "padding: 5px 10px",
+            "border-bottom: 1px solid rgba(255,255,255,0.08)",
+            "display: flex",
+            "align-items: center",
+            "gap: 6px",
+            "flex-shrink: 0",
+            "font-size: 10px",
+        ])
+        const pickerLabel = UILayoutDebugger._el("span", ["color: #a0a0b8", "flex-shrink: 0"])
+        pickerLabel.textContent = "Pass:"
+        
+        const sel = document.createElement("select")
+        sel.style.cssText = [
+            "flex: 1",
+            "background: #1e1e2e",
+            "color: #d8d8f0",
+            "border: 1px solid #444",
+            "border-radius: 3px",
+            "font: inherit",
+            "padding: 1px 4px",
+        ].join("; ")
+        
+        for (let i = 0; i < UILayoutDebugger._traces.length; i++) {
+            const t = UILayoutDebugger._traces[i]
+            const opt = document.createElement("option")
+            opt.value = String(i)
+            opt.textContent = `#${t.passIndex}  (${t.steps.length} steps, ${t.totalIterations} iter)`
+            if (i === traceIndex) { opt.selected = true }
+            sel.appendChild(opt)
+        }
+        sel.onchange = () => onTraceChange(parseInt(sel.value, 10))
+        pickerRow.append(pickerLabel, sel)
+        col.appendChild(pickerRow)
+        
+        if (!trace) { return col }
+        
+        // Apply frame filter to produce the visible step list.
+        const frameFilter = UILayoutDebugger._frameFilter
+        const visibleSteps = frameFilter === "all"
+                             ? trace.steps
+                             : trace.steps.filter(s => {
+                const f = s.frameBefore
+                const g = s.frameAfter
+                const changed = !f || !g
+                    || f.left !== g.left || f.top !== g.top
+                    || f.width !== g.width || f.height !== g.height
+                return frameFilter === "changed" ? changed : !changed
+            })
+        
+        const clampedStep = Math.max(-1, Math.min(stepIndex, visibleSteps.length - 1))
+        const activeStep = visibleSteps[clampedStep] ?? null
+        const activeViewIndex = activeStep?.viewIndex ?? -1
+        
+        // countMap still uses all steps for heat colouring (unfiltered).
+        // stepMap stores the last step per viewIndex for frame/cache delta display.
+        const countMap = new Map<number, number>()
+        const stepMap = new Map<number, UILayoutDebugStep>()
+        for (const step of trace.steps) {
+            countMap.set(step.viewIndex, (countMap.get(step.viewIndex) ?? 0) + 1)
+            stepMap.set(step.viewIndex, step)
+        }
+        
+        // ── Step controls ─────────────────────────────────────────────────────
+        const stepBar = UILayoutDebugger._el("div", [
+            "padding: 5px 10px",
+            "border-bottom: 1px solid rgba(255,255,255,0.08)",
+            "display: flex",
+            "align-items: center",
+            "gap: 6px",
+            "flex-shrink: 0",
+        ])
+        
+        const backBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle("#59599b")) as HTMLButtonElement
+        backBtn.textContent = "◀"
+        backBtn.title = "Step back"
+        backBtn.disabled = clampedStep <= -1
+        backBtn.onclick = () => onStepChange(Math.max(clampedStep - 1, -1))
+        
+        const fwdBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle("#59599b")) as HTMLButtonElement
+        fwdBtn.textContent = "▶"
+        fwdBtn.title = "Step forward"
+        fwdBtn.disabled = clampedStep >= visibleSteps.length - 1
+        fwdBtn.onclick = () => onStepChange(Math.min(clampedStep + 1, visibleSteps.length - 1))
+        
+        const slider = document.createElement("input")
+        slider.type = "range"
+        slider.min = "-1"
+        slider.max = String(visibleSteps.length - 1)
+        slider.value = String(clampedStep)
+        slider.style.cssText = "flex: 1; cursor: pointer; accent-color: #59599b;"
+        slider.oninput = () => onStepChange(parseInt(slider.value, 10))
+        
+        const stepLabel = UILayoutDebugger._el("span", ["color: #b0b0c8", "font-size: 10px", "white-space: nowrap"])
+        const totalLabel = frameFilter === "all"
+                           ? String(visibleSteps.length)
+                           : `${visibleSteps.length}/${trace.steps.length}`
+        stepLabel.textContent = clampedStep < 0
+                                ? `— / ${totalLabel}`
+                                : `${clampedStep + 1} / ${totalLabel}`
+        
+        stepBar.append(backBtn, slider, fwdBtn, stepLabel)
+        col.appendChild(stepBar)
+        
+        // ── Active step detail ────────────────────────────────────────────────
+        if (activeStep) {
+            col.appendChild(UILayoutDebugger._renderStepDetail(activeStep))
+        }
+        
+        // ── View tree ─────────────────────────────────────────────────────────
+        const treeContainer = UILayoutDebugger._el("div", [
+            "overflow-y: scroll",
+            "flex: 1",
+            "padding: 4px 0",
+            "min-height: 0",
+            "position: relative",
+        ])
+        registerTree(treeContainer)
+        
+        treeContainer.addEventListener("scroll", () => {
+            const peer = getPeerTree()
+            if (peer && peer.scrollTop !== treeContainer.scrollTop) {
+                peer.scrollTop = treeContainer.scrollTop
+            }
+        })
+        
+        if (trace.roots.length > 0) {
+            let activeRow: HTMLElement | null = null
+            for (const treeRoot of trace.roots) {
+                const result = UILayoutDebugger._renderTreeNode(
+                    treeRoot, treeContainer, countMap, activeViewIndex, expandState, stepMap
+                )
+                if (result) { activeRow = result }
+            }
+            // Scroll the active row into view after the DOM is fully built.
+            // Use a 0ms timeout so the browser has laid out the container first.
+            if (activeRow) {
+                const rowRef = activeRow
+                const containerRef = treeContainer
+                setTimeout(() => {
+                    const rowTop = rowRef.offsetTop
+                    const rowBottom = rowTop + rowRef.offsetHeight
+                    const visTop = containerRef.scrollTop
+                    const visBottom = visTop + containerRef.clientHeight
+                    if (rowTop < visTop || rowBottom > visBottom) {
+                        containerRef.scrollTop = rowTop - containerRef.clientHeight / 2
+                    }
+                }, 0)
+            }
+        }
+        else {
+            const msg = UILayoutDebugger._el("div", ["padding: 8px 10px", "color: #6a6a80"])
+            msg.textContent = "No steps recorded in this pass."
+            treeContainer.appendChild(msg)
+        }
+        
+        col.appendChild(treeContainer)
+        
+        // ── Cache change events ───────────────────────────────────────────────
+        if (trace.cacheChanges.length > 0) {
+            let cacheListExpanded = false
+            
+            const cacheHeader = UILayoutDebugger._el("div", [
+                "padding: 5px 10px",
+                "border-top: 1px solid rgba(255,255,255,0.08)",
+                "display: flex",
+                "align-items: center",
+                "gap: 5px",
+                "flex-shrink: 0",
+                "cursor: pointer",
+                "font-size: 10px",
+            ])
+            
+            const cacheChevron = UILayoutDebugger._el("span", ["color: #7070a0", "font-size: 8px", "width: 10px"])
+            cacheChevron.textContent = "▸"
+            
+            const cacheTitle = UILayoutDebugger._el("span", ["color: #a0a0b8"])
+            cacheTitle.textContent = `Cache writes (${trace.cacheChanges.length})`
+            
+            cacheHeader.append(cacheChevron, cacheTitle)
+            col.appendChild(cacheHeader)
+            
+            const cacheList = UILayoutDebugger._el("div", [
+                "display: none",
+                "overflow-y: auto",
+                "max-height: 180px",
+                "flex-shrink: 0",
+                "font-size: 10px",
+                "padding: 2px 0",
+            ])
+            
+            for (const ev of trace.cacheChanges) {
+                const evRow = UILayoutDebugger._el("div", [
+                    "padding: 2px 10px 2px 14px",
+                    "display: flex",
+                    "flex-direction: column",
+                    "gap: 1px",
+                    "border-bottom: 1px solid rgba(255,255,255,0.04)",
+                ])
+                
+                const topLine = UILayoutDebugger._el("div", ["display: flex", "gap: 5px", "align-items: baseline"])
+                
+                const evIdx = UILayoutDebugger._el("span", ["color: #5a5a70", "flex-shrink: 0"])
+                evIdx.textContent = `#${ev.eventIndex}`
+                
+                const evClass = UILayoutDebugger._el("span", ["color: #ffcc88", "font-weight: bold"])
+                evClass.textContent = ev.className
+                
+                const evEid = UILayoutDebugger._el("span", ["color: #6a6a80"])
+                evEid.textContent = `#${ev.elementID}`
+                
+                const evKey = UILayoutDebugger._el("span", ["color: #9090a8"])
+                const match = ev.cacheKey.match(/h_(\d+(?:\.\d+)?)__w_(\d+(?:\.\d+)?)/)
+                evKey.textContent = match
+                                    ? (match[1] !== "0" && match[2] !== "0"
+                                       ? `h≤${match[1]} w≤${match[2]}`
+                                       : match[2] !== "0" ? `w≤${match[2]}` : `h≤${match[1]}`)
+                                    : ev.cacheKey
+                
+                const evVal = UILayoutDebugger._el("span", ["color: #88ddff", "margin-left: auto"])
+                evVal.textContent = `${ev.newValue.width.toFixed(0)}×${ev.newValue.height.toFixed(0)}`
+                
+                topLine.append(evIdx, evClass, evEid, evKey, evVal)
+                
+                const callerLine = UILayoutDebugger._el("div", [
+                    "display: flex", "gap: 5px", "align-items: baseline",
+                ])
+                const stepRef = UILayoutDebugger._el("span", ["color: #5a5a70", "flex-shrink: 0"])
+                stepRef.textContent = ev.stepIndex >= 0 ? `step ${ev.stepIndex}` : "between steps"
+                
+                const callerFn = UILayoutDebugger._el("span", ["color: #7878a0", "cursor: pointer"])
+                callerFn.textContent = ev.callerFunction + "()"
+                callerFn.title = ev.cleanStack
+                
+                let stackExpanded = false
+                const stackEl = UILayoutDebugger._el("div", [
+                    "display: none",
+                    "margin-top: 2px",
+                    "padding: 3px 6px",
+                    "background: rgba(255,255,255,0.04)",
+                    "border-radius: 3px",
+                    "color: #6060808",
+                    "font-size: 9px",
+                    "white-space: pre",
+                    "overflow-x: auto",
+                ])
+                stackEl.textContent = ev.cleanStack
+                callerFn.onclick = () => {
+                    stackExpanded = !stackExpanded
+                    stackEl.style.display = stackExpanded ? "block" : "none"
+                }
+                
+                callerLine.append(stepRef, callerFn)
+                evRow.append(topLine, callerLine, stackEl)
+                cacheList.appendChild(evRow)
+            }
+            
+            cacheHeader.onclick = () => {
+                cacheListExpanded = !cacheListExpanded
+                cacheList.style.display = cacheListExpanded ? "block" : "none"
+                cacheChevron.textContent = cacheListExpanded ? "▾" : "▸"
+            }
+            
+            col.appendChild(cacheList)
+        }
+        
+        return col
+    }
+    
+    static _renderStaleReportPanel(result: NonNullable<typeof UILayoutDebugger._staleReportResult>): HTMLElement {
+        const panel = UILayoutDebugger._el("div", [
+            "display: flex",
+            "flex-direction: column",
+            "flex: 1",
+            "min-height: 0",
+            "overflow: hidden",
+        ])
+        
+        // ── Header bar ────────────────────────────────────────────────────────
+        const bar = UILayoutDebugger._el("div", [
+            "padding: 5px 10px",
+            "border-bottom: 1px solid rgba(255,255,255,0.08)",
+            "display: flex",
+            "align-items: center",
+            "gap: 6px",
+            "flex-shrink: 0",
+            "font-size: 10px",
+        ])
+        
+        const barTitle = UILayoutDebugger._el("span", ["color: #ffaa55", "flex: 1", "font-weight: bold"])
+        barTitle.textContent = "☢ Stale Layout Report"
+        
+        const rerunBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle("#ffaa55"))
+        rerunBtn.textContent = "↺ Re-run"
+        rerunBtn.title = "Re-run performForcedSubtreeLayout and refresh the report"
+        rerunBtn.onclick = () => UILayoutDebugger.captureStaleLayoutReport()
+        
+        const closeBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle("#9090a8"))
+        closeBtn.textContent = "✕"
+        closeBtn.title = "Close stale report panel"
+        closeBtn.onclick = () => {
+            UILayoutDebugger._staleReportMode = false
+            UILayoutDebugger._renderOverlay()
+        }
+        
+        bar.append(barTitle, rerunBtn, closeBtn)
+        panel.appendChild(bar)
+        
+        // ── Summary bar ───────────────────────────────────────────────────────
+        const { diffs, forcedPassCacheChanges, passIndex } = result
+        
+        const counts = { frame: 0, cache: 0, both: 0, appeared: 0, disappeared: 0 }
+        for (const d of diffs) {
+            if (d.kind === "frame") { counts.frame++ }
+            else if (d.kind === "cache") { counts.cache++ }
+            else if (d.kind === "both") { counts.both++ }
+            else if (d.kind === "appeared") { counts.appeared++ }
+            else if (d.kind === "disappeared") { counts.disappeared++ }
+        }
+        const totalCorrected = diffs.length
+        
+        const summaryBar = UILayoutDebugger._el("div", [
+            "padding: 5px 10px",
+            "border-bottom: 1px solid rgba(255,255,255,0.08)",
+            "display: flex",
+            "gap: 8px",
+            "align-items: center",
+            "flex-shrink: 0",
+            "font-size: 10px",
+            "flex-wrap: wrap",
+        ])
+        
+        if (totalCorrected === 0) {
+            const clean = UILayoutDebugger._el("span", ["color: #88ff99", "font-weight: bold"])
+            clean.textContent = "✓ No stale state detected — all views were already correct."
+            summaryBar.appendChild(clean)
+        }
+        else {
+            const total = UILayoutDebugger._el("span", ["color: #ffaa55", "font-weight: bold"])
+            total.textContent = `${totalCorrected} stale view${totalCorrected !== 1 ? "s" : ""} corrected`
+            summaryBar.appendChild(total)
+            
+            const summaryItems: [string, number, string][] = [
+                ["frame+cache", counts.both,        "#ffaa55"],
+                ["frame",       counts.frame,       "#7bc8ff"],
+                ["cache",       counts.cache,       "#ffcc88"],
+                ["appeared",    counts.appeared,    "#88ff99"],
+                ["disappeared", counts.disappeared, "#ff8888"],
+            ]
+            for (const [label, count, color] of summaryItems) {
+                if (count === 0) { continue }
+                const chip = UILayoutDebugger._el("span", [`color: ${color}`])
+                chip.textContent = `${count} ${label}`
+                summaryBar.appendChild(chip)
+            }
+        }
+        
+        const passTag = UILayoutDebugger._el("span", ["color: #5a5a70", "margin-left: auto", "white-space: nowrap", "flex-shrink: 0"])
+        passTag.textContent = passIndex >= 0 ? `forced pass #${passIndex}` : ""
+        summaryBar.appendChild(passTag)
+        panel.appendChild(summaryBar)
+        
+        // ── UITextMeasurement global cache summary ────────────────────────────
+        const tmBefore = result.before.textMeasurement
+        const tmAfter  = result.after.textMeasurement
+        const tmPreparedCleared = tmBefore.preparedCacheSize > 0 && tmAfter.preparedCacheSize === 0
+        const tmStyleCleared    = tmBefore.styleCacheSize > 0 && tmAfter.styleCacheSize === 0
+        const tmKnown = tmBefore.preparedCacheSize >= 0
+        
+        if (tmKnown) {
+            const tmBar = UILayoutDebugger._el("div", [
+                "padding: 4px 10px",
+                "border-bottom: 1px solid rgba(255,255,255,0.08)",
+                "display: flex",
+                "gap: 10px",
+                "flex-shrink: 0",
+                "font-size: 9px",
+                "color: #7060a0",
+                "flex-wrap: wrap",
+            ])
+            const tmLabel = UILayoutDebugger._el("span", ["color: #7060a0", "font-weight: bold", "flex-shrink: 0"])
+            tmLabel.textContent = "UITextMeasurement (global):"
+            tmBar.appendChild(tmLabel)
+            
+            const prepChip = UILayoutDebugger._el("span", [
+                "color: " + (tmPreparedCleared ? "#ffaa55" : "#5a5a70"),
+            ])
+            prepChip.textContent = `preparedCache ${tmBefore.preparedCacheSize} → ${tmAfter.preparedCacheSize}` +
+                (tmPreparedCleared ? " ✓ cleared" : "")
+            tmBar.appendChild(prepChip)
+            
+            const styleChip = UILayoutDebugger._el("span", [
+                "color: " + (tmStyleCleared ? "#ffaa55" : "#5a5a70"),
+            ])
+            styleChip.textContent = `styleCache ${tmBefore.styleCacheSize} → ${tmAfter.styleCacheSize}` +
+                (tmStyleCleared ? " ✓ cleared" : "")
+            tmBar.appendChild(styleChip)
+            
+            panel.appendChild(tmBar)
+        }
+        
+        // ── Filter tabs ───────────────────────────────────────────────────────
+        type StaleFilter = "all" | "frame" | "cache"
+        let staleFilter: StaleFilter = totalCorrected > 0 ? "all" : "all"
+        
+        const tabBar = UILayoutDebugger._el("div", [
+            "display: flex",
+            "border-bottom: 1px solid rgba(255,255,255,0.08)",
+            "flex-shrink: 0",
+            "font-size: 10px",
+        ])
+        
+        const list = UILayoutDebugger._el("div", [
+            "overflow-y: auto",
+            "flex: 1",
+            "padding: 4px 0",
+        ])
+        
+        const renderList = (filter: StaleFilter) => {
+            list.innerHTML = ""
+            
+            if (diffs.length === 0) {
+                const msg = UILayoutDebugger._el("div", ["padding: 10px 12px", "color: #88ff99", "font-size: 10px"])
+                msg.textContent = "✓ Nothing was corrected — no missing invalidations detected."
+                list.appendChild(msg)
+                return
+            }
+            
+            const visible = filter === "all"
+                            ? diffs
+                            : filter === "frame"
+                              ? diffs.filter(d => d.kind === "frame" || d.kind === "both")
+                              : diffs.filter(d => d.kind === "cache" || d.kind === "both")
+            
+            if (visible.length === 0) {
+                const msg = UILayoutDebugger._el("div", ["padding: 8px 12px", "color: #5a5a70", "font-size: 10px"])
+                msg.textContent = "No items."
+                list.appendChild(msg)
+                return
+            }
+            
+            for (const d of visible) {
+                const cacheWrites = forcedPassCacheChanges.get(d.viewIndex) ?? []
+                
+                const row = UILayoutDebugger._el("div", [
+                    "padding: 5px 10px",
+                    "border-bottom: 1px solid rgba(255,255,255,0.05)",
+                    "font-size: 10px",
+                ])
+                
+                // ── Top line: kind tag + class + elementID ────────────────────
+                const topLine = UILayoutDebugger._el("div", ["display: flex", "gap: 6px", "align-items: baseline", "margin-bottom: 2px"])
+                
+                const kindColors: Record<UILayoutDebugDiffKind, string> = {
+                    appeared: "#88ff99", disappeared: "#ff8888",
+                    both: "#ffaa55", frame: "#7bc8ff", cache: "#ffcc88", unchanged: "#5a5a70",
+                }
+                const kindTag = UILayoutDebugger._el("span", [
+                    `color: ${kindColors[d.kind]}`,
+                    "flex-shrink: 0",
+                    "font-size: 9px",
+                    "font-weight: bold",
+                    "min-width: 70px",
+                ])
+                kindTag.textContent = d.kind.toUpperCase()
+                
+                const cls = UILayoutDebugger._el("span", ["color: #ffcc88", "font-weight: bold"])
+                cls.textContent = d.className
+                
+                const eid = UILayoutDebugger._el("span", ["color: #6a6a80"])
+                eid.textContent = ` #${d.elementID}`
+                
+                // Jump to the forced pass in the pass inspector
+                const jumpBtn = UILayoutDebugger._el("span", [
+                    "color: #59599b",
+                    "margin-left: auto",
+                    "font-size: 9px",
+                    "cursor: pointer",
+                    "flex-shrink: 0",
+                ])
+                jumpBtn.textContent = `pass #${passIndex} ↗`
+                jumpBtn.title = "Jump to this view in the forced-layout pass"
+                jumpBtn.onclick = () => {
+                    const trace = UILayoutDebugger._traces.find(t => t.passIndex === passIndex)
+                    if (!trace) { return }
+                    const ti = UILayoutDebugger._traces.indexOf(trace)
+                    const si = trace.steps.findIndex(s => s.viewIndex === d.viewIndex)
+                    if (si < 0) { return }
+                    UILayoutDebugger._replayTraceIndex = ti
+                    UILayoutDebugger._replayStepIndex = si
+                    UILayoutDebugger._renderOverlay()
+                }
+                
+                topLine.append(kindTag, cls, eid, jumpBtn)
+                row.appendChild(topLine)
+                
+                // ── Frame correction ──────────────────────────────────────────
+                if (d.kind === "frame" || d.kind === "both") {
+                    const frameLine = UILayoutDebugger._el("div", ["padding-left: 76px", "color: #b0b0c8", "font-size: 9px", "margin-bottom: 1px"])
+                    frameLine.textContent = "frame: " + UILayoutDebugger._formatFrameDiff(d.baselineFrame, d.currentFrame)
+                    row.appendChild(frameLine)
+                }
+                
+                // ── Cache correction + write cross-reference ──────────────────
+                if (d.kind === "cache" || d.kind === "both") {
+                    const cacheLine = UILayoutDebugger._el("div", ["padding-left: 76px", "color: #a0a090", "font-size: 9px", "margin-bottom: 1px"])
+                    cacheLine.textContent = "cache: " + UILayoutDebugger._formatCacheDiff(d.baselineCache, d.currentCache)
+                    row.appendChild(cacheLine)
+                    
+                    // Cross-reference: which call paths recomputed the correct value?
+                    if (cacheWrites.length > 0) {
+                        const xrefHeader = UILayoutDebugger._el("div", [
+                            "padding-left: 76px",
+                            "color: #7060a0",
+                            "font-size: 9px",
+                            "margin-top: 3px",
+                            "margin-bottom: 1px",
+                            "font-weight: bold",
+                        ])
+                        xrefHeader.textContent = `↳ recomputed by (${cacheWrites.length} write${cacheWrites.length !== 1 ? "s" : ""} in forced pass):`
+                        row.appendChild(xrefHeader)
+                        
+                        for (const ev of cacheWrites) {
+                            const writeRow = UILayoutDebugger._el("div", [
+                                "padding-left: 84px",
+                                "display: flex",
+                                "gap: 5px",
+                                "align-items: baseline",
+                                "font-size: 9px",
+                            ])
+                            
+                            const keyMatch = ev.cacheKey.match(/h_(\d+(?:\.\d+)?)__w_(\d+(?:\.\d+)?)/)
+                            const keyLabel = keyMatch
+                                             ? (keyMatch[1] !== "0" && keyMatch[2] !== "0"
+                                                ? `h≤${keyMatch[1]} w≤${keyMatch[2]}`
+                                                : keyMatch[2] !== "0" ? `w≤${keyMatch[2]}` : `h≤${keyMatch[1]}`)
+                                             : ev.cacheKey
+                            
+                            const keySpan = UILayoutDebugger._el("span", ["color: #6060808", "flex-shrink: 0"])
+                            keySpan.textContent = keyLabel
+                            
+                            const valSpan = UILayoutDebugger._el("span", ["color: #88ddff", "flex-shrink: 0"])
+                            valSpan.textContent = `→ ${ev.newValue.width.toFixed(0)}×${ev.newValue.height.toFixed(0)}`
+                            
+                            const callerSpan = UILayoutDebugger._el("span", ["color: #7070a8", "cursor: pointer"])
+                            callerSpan.textContent = ev.callerFunction + "()"
+                            callerSpan.title = ev.cleanStack
+                            
+                            let stackOpen = false
+                            const stackEl = UILayoutDebugger._el("div", [
+                                "display: none",
+                                "margin-top: 2px",
+                                "padding: 3px 6px",
+                                "background: rgba(255,255,255,0.04)",
+                                "border-radius: 3px",
+                                "color: #6060808",
+                                "font-size: 9px",
+                                "white-space: pre",
+                                "overflow-x: auto",
+                            ])
+                            stackEl.textContent = ev.cleanStack
+                            callerSpan.onclick = () => {
+                                stackOpen = !stackOpen
+                                stackEl.style.display = stackOpen ? "block" : "none"
+                            }
+                            
+                            writeRow.append(keySpan, valSpan, callerSpan)
+                            row.appendChild(writeRow)
+                            row.appendChild(stackEl)
+                        }
+                    }
+                }
+                
+                list.appendChild(row)
+            }
+        }
+        
+        const filterTabs: [string, StaleFilter, number, string][] = [
+            ["All",   "all",   diffs.length,              "#ffaa55"],
+            ["Frame", "frame", counts.frame + counts.both, "#7bc8ff"],
+            ["Cache", "cache", counts.cache + counts.both, "#ffcc88"],
+        ]
+        
+        const buildTabs = () => {
+            tabBar.innerHTML = ""
+            for (const [label, filter, count, color] of filterTabs) {
+                if (count === 0 && filter !== "all") { continue }
+                const tab = UILayoutDebugger._el("div", [
+                    "padding: 4px 8px",
+                    "cursor: pointer",
+                    "border-bottom: 2px solid " + (staleFilter === filter ? color : "transparent"),
+                    `color: ${staleFilter === filter ? color : "#6a6a80"}`,
+                    "white-space: nowrap",
+                    "font-size: 10px",
+                ])
+                tab.textContent = `${label} (${count})`
+                tab.onclick = () => {
+                    staleFilter = filter
+                    buildTabs()
+                    renderList(staleFilter)
+                }
+                tabBar.appendChild(tab)
+            }
+        }
+        
+        buildTabs()
+        panel.appendChild(tabBar)
+        panel.appendChild(list)
+        renderList(staleFilter)
+        
+        return panel
+    }
+    
+    
+    static _renderHelpPanel(): HTMLElement {
+        const panel = UILayoutDebugger._el("div", [
+            "overflow-y: auto",
+            "flex: 1",
+            "padding: 14px 16px",
+            "font-size: 11px",
+            "line-height: 1.6",
+            "color: #c0c0d8",
+        ])
+        
+        const section = (heading: string, body: string) => {
+            const h = UILayoutDebugger._el("div", [
+                "font-weight: bold",
+                "color: #c8d8ff",
+                "margin-top: 14px",
+                "margin-bottom: 4px",
+                "font-size: 11px",
+                "border-bottom: 1px solid rgba(255,255,255,0.08)",
+                "padding-bottom: 3px",
+            ])
+            h.textContent = heading
+            const b = UILayoutDebugger._el("div", ["color: #a0a0b8", "white-space: pre-wrap"])
+            b.textContent = body
+            panel.appendChild(h)
+            panel.appendChild(b)
+        }
+        
+        const kv = (key: string, value: string) => {
+            const row = UILayoutDebugger._el("div", ["display: flex", "gap: 8px", "margin-bottom: 4px"])
+            const k = UILayoutDebugger._el("span", [
+                "color: #ffcc88",
+                "font-weight: bold",
+                "flex-shrink: 0",
+                "min-width: 110px",
+            ])
+            k.textContent = key
+            const v = UILayoutDebugger._el("span", ["color: #a0a0b8"])
+            v.textContent = value
+            row.append(k, v)
+            panel.appendChild(row)
+        }
+        
+        // ── Concepts ─────────────────────────────────────────────────────────
+        
+        section("Core concepts", "")
+        
+        kv("Pass",
+            "One full run of layoutViewsIfNeeded(). The scheduler collects every " +
+            "view that called setNeedsLayout() and works through them all. A single " +
+            "user action typically triggers one pass.")
+        
+        kv("Iteration",
+            "One loop of the while-loop inside a pass. Laying out a view can call " +
+            "setNeedsLayout() on another view, adding it to the queue mid-pass. " +
+            "The loop repeats until the queue is empty. Most passes have 1 iteration; " +
+            "more than 1 signals that layout is triggering further layout.")
+        
+        kv("Step",
+            "One view being laid out within a pass — one call to layoutIfNeeded(). " +
+            "A pass with 8 steps means 8 views had their layout computed. Steps are " +
+            "the atomic unit you step through in the scrubber.")
+        
+        kv("Trigger",
+            "The call stack at the moment setNeedsLayout() was called on a view. " +
+            "Tells you what caused the view to enter the layout queue.")
+        
+        kv("Heat colour",
+            "Green = laid out once. Orange = laid out twice (possible unnecessary work). " +
+            "Red = laid out 3+ times (likely a layout cycle or redundant invalidation).")
+        
+        // ── Pass inspector ────────────────────────────────────────────────────
+        
+        section("Pass inspector", "")
+        
+        kv("Pass picker",
+            "Selects which recorded pass to inspect. The most recent pass is shown " +
+            "first. Up to 20 passes are stored.")
+        
+        kv("◀ ▶ scrubber",
+            "Steps through the views laid out in the selected pass one at a time. " +
+            "The active view is highlighted in the tree and its frame diff, intrinsic " +
+            "cache diff, trigger stack, and subview changes are shown above.")
+        
+        kv("Frame filter",
+            "All: show every step. Changed: only steps where the frame actually moved " +
+            "or resized. Unchanged: only no-ops. The counter shows n/total when filtered.")
+        
+        kv("Compare ⧉",
+            "Splits the panel into two columns, each showing an independent pass. " +
+            "The tree expands and collapses in sync between both columns.")
+        
+        kv("Cache writes",
+            "Collapsible section at the bottom of each column. Every write to a " +
+            "view's intrinsic size cache during that pass is listed, with the value " +
+            "written and the caller that triggered the measurement.")
+        
+        // ── Baseline / diff ───────────────────────────────────────────────────
+        
+        section("Baseline & diff", "")
+        
+        kv("📍 Baseline",
+            "Captures a flat snapshot of every view's frame and intrinsic cache right " +
+            "now. Requires at least one layout pass to have run so the root view is " +
+            "known. Click again to recapture.")
+        
+        kv("⊕ Diff",
+            "Captures a second snapshot and shows what changed since the baseline. " +
+            "Changes are sorted: appeared, disappeared, frame+cache, frame-only, " +
+            "cache-only. Click any row to jump to the pass that caused that change.")
+        
+        kv("pass #N tag",
+            "Shown on each diff row. Indicates the first recorded pass (by pass " +
+            "number) in which that view was laid out after the baseline was taken.")
+        
+        kv("⬚ Frame / Bounds",
+            "Toggles how frame comparisons are made across all diff panels. " +
+            "Frame mode (default): a view is considered changed if its position or " +
+            "size changed. Bounds mode: only size changes are counted — origin (x/y) " +
+            "is ignored. Use bounds mode when you care only about content-affecting " +
+            "size changes and want to suppress noise from views that merely moved.")
+        
+        // ── Stale layout report ───────────────────────────────────────────────
+        
+        section("Stale layout report  ☢", "")
+        
+        kv("☢ Stale",
+            "The primary tool for finding missing cache invalidations. Click once to " +
+            "snapshot the current tree state, then immediately call " +
+            "performForcedSubtreeLayout() for a complete cold remeasure, then diff the " +
+            "two snapshots. Any view that changed was holding stale/incorrect state — " +
+            "its invalidation was missed somewhere.")
+        
+        kv("Corrected views",
+            "Each row in the ☢ panel is a view the forced pass corrected. The kind " +
+            "tag shows whether the frame, intrinsic cache, or both were stale.")
+        
+        kv("↳ recomputed by",
+            "For cache corrections, the exact call path(s) that recomputed the correct " +
+            "value during the forced pass are listed below each row, with expandable " +
+            "stack traces. Work backwards from that call site to find where the " +
+            "corresponding invalidation should have been triggered but wasn't.")
+        
+        kv("pass #N ↗",
+            "Each row has a jump link to the forced-layout pass in the pass inspector " +
+            "so you can step through the remeasure for that view in full detail.")
+        
+        kv("Re-run",
+            "Right-click the ☢ Stale button (or use ↺ Re-run in the panel) to re-run " +
+            "the report without closing and reopening. Useful after you've applied a fix " +
+            "and want to verify the stale count drops to zero.")
+        
+        kv("When to use it",
+            "Reproduce the bug, then immediately click ☢ Stale before triggering any " +
+            "other layout. The tree must be in its incorrect state at the moment you " +
+            "click. The forced layout will correct it, which is visible in the UI after " +
+            "the report runs.")
+        
+        // ── Live inspector ────────────────────────────────────────────────────
+        
+        section("Live inspector  👁", "")
+        
+        kv("👁 Live",
+            "Shows the current view tree as it exists right now — not a recorded " +
+            "snapshot. Frames and cache entries reflect the live DOM state. " +
+            "Use ↺ Refresh to re-read after triggering layout manually.")
+        
+        // ── Breakpoints ───────────────────────────────────────────────────────
+        
+        section("Breakpoint mode  ⏸", "")
+        
+        kv("⏸ BP",
+            "When enabled, a sentinel line executes before every layoutIfNeeded() " +
+            "call. Set a browser debugger breakpoint on that line to pause before " +
+            "each step with the full live JS stack in scope.")
+        
+        kv("Finding the line",
+            "In Chrome DevTools Sources, press Cmd+Opt+F (Mac) or Ctrl+Shift+F " +
+            "(Windows) and search for: breakpointOnThisLine")
+        
+        // ── Console API ───────────────────────────────────────────────────────
+        
+        section("Console API", "All methods are on the global UILayoutDebugger object.")
+        
+        kv("UILayoutDebugger.enable()",              "Start or stop recording and show/hide the overlay.")
+        kv("UILayoutDebugger.disable()",             "Stop recording and hide the overlay.")
+        kv("UILayoutDebugger.enableBreakpoints()",   "Turn on breakpoint step-through mode.")
+        kv("UILayoutDebugger.captureBaseline()",     "Snapshot current state as baseline.")
+        kv("UILayoutDebugger.captureAndDiff()",      "Snapshot and diff against baseline.")
+        kv("UILayoutDebugger.captureStaleLayoutReport()", "Snapshot → forced remeasure → diff. Primary cache-staleness diagnostic.")
+        kv("UILayoutDebugger.clearStaleReport()",    "Clear the stale report result and close the panel.")
+        kv("UILayoutDebugger.clearTraces()",         "Discard all recorded passes and reset the counter.")
+        kv("UILayoutDebugger.goToStep(n)",           "Jump to step n (0-based) in the current pass.")
+        kv("UILayoutDebugger.toggleLiveInspector()", "Show or hide the live view tree panel.")
+        kv("UILayoutDebugger._boundsBasedDiff = true", "Switch all frame diffs to size-only (bounds) mode from the console.")
+        
+        return panel
+    }
+    
+    static _renderLiveInspectorPanel(): HTMLElement {
+        const panel = UILayoutDebugger._el("div", [
+            "display: flex",
+            "flex-direction: column",
+            "flex: 1",
+            "min-height: 0",
+            "overflow: hidden",
+        ])
+        
+        // ── Header bar ────────────────────────────────────────────────────────
+        const bar = UILayoutDebugger._el("div", [
+            "padding: 5px 10px",
+            "border-bottom: 1px solid rgba(255,255,255,0.08)",
+            "display: flex",
+            "align-items: center",
+            "gap: 6px",
+            "flex-shrink: 0",
+            "font-size: 10px",
+        ])
+        
+        const barTitle = UILayoutDebugger._el("span", ["color: #a0a0b8", "flex: 1", "font-weight: bold"])
+        barTitle.textContent = "👁 Live View Tree"
+        
+        const refreshBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle("#9090a8"))
+        refreshBtn.textContent = "↺ Refresh"
+        refreshBtn.title = "Re-capture current state"
+        refreshBtn.onclick = () => UILayoutDebugger._renderOverlay()
+        
+        const syncBtn = UILayoutDebugger._el("button", UILayoutDebugger._btnStyle("#9090a8"))
+        syncBtn.textContent = "⇄ Sync"
+        syncBtn.title = "Sync collapse/expand state from pass inspector. Views not in the pass inspector are kept collapsed."
+        syncBtn.onclick = () => {
+            // Read the active pass expand state
+            const source = UILayoutDebugger._compareMode
+                           ? UILayoutDebugger._sharedExpandState
+                           : UILayoutDebugger._singleExpandState
+            
+            // Build a set of all viewIndices that appear in any recorded trace step
+            const tracedViews = new Set<number>()
+            for (const trace of UILayoutDebugger._traces) {
+                for (const step of trace.steps) { tracedViews.add(step.viewIndex) }
+            }
+            
+            // Copy source state; any viewIndex not in source and not in traced
+            // views defaults to collapsed
+            const newState = new Map<number, boolean>()
+            for (const [idx, expanded] of source) {
+                newState.set(idx, expanded)
+            }
+            // For views present in the live tree but absent from pass inspector
+            // state, collapse them unless they appear in a trace
+            UILayoutDebugger._walkViewTree(
+                UILayoutDebugger._lastKnownRootView,
+                new Map(),  // discard — we only need the side effect of visiting indices
+                new Set(),
+            )
+            // Actually walk to collect all live view indices
+            const liveIndices = new Set<number>()
+            const collectIndices = (view: any, visited: Set<number>) => {
+                const idx: number = view?._UIViewIndex ?? -1
+                if (idx < 0 || visited.has(idx)) { return }
+                visited.add(idx)
+                liveIndices.add(idx)
+                for (const sv of view?.subviews ?? []) { collectIndices(sv, visited) }
+            }
+            collectIndices(UILayoutDebugger._lastKnownRootView, new Set())
+            
+            for (const idx of liveIndices) {
+                if (!newState.has(idx)) {
+                    // Not in pass expand state: expand only if it appears in a trace
+                    newState.set(idx, tracedViews.has(idx))
+                }
+            }
+            
+            UILayoutDebugger._liveExpandState = newState
+            UILayoutDebugger._renderOverlay()
+        }
+        
+        bar.append(barTitle, refreshBtn, syncBtn)
+        panel.appendChild(bar)
+        
+        const root = UILayoutDebugger._lastKnownRootView
+        if (!root) {
+            const msg = UILayoutDebugger._el("div", ["padding: 10px 12px", "color: #6a6a80", "font-size: 10px"])
+            msg.textContent = "No root view found yet — trigger a layout pass first."
+            panel.appendChild(msg)
+            return panel
+        }
+        
+        // ── Tree ──────────────────────────────────────────────────────────────
+        const treeContainer = UILayoutDebugger._el("div", [
+            "overflow-y: auto",
+            "flex: 1",
+            "padding: 4px 0",
+            "position: relative",
+        ])
+        
+        UILayoutDebugger._renderLiveNode(
+            root, treeContainer, 0, new Set(), UILayoutDebugger._liveExpandState
+        )
+        panel.appendChild(treeContainer)
+        return panel
+    }
+    
+    static _renderLiveNode(
+        view: any,
+        container: HTMLElement,
+        depth: number,
+        visited: Set<number>,
+        expandState: Map<number, boolean>,
+    ) {
+        const idx: number = view?._UIViewIndex ?? -1
+        if (idx < 0 || visited.has(idx)) { return }
+        visited.add(idx)
+        
+        const frame = UILayoutDebugger._captureFrame(view)
+        const cache = UILayoutDebugger._captureCache(view)
+        const className: string = view?.constructor?.name ?? "UnknownView"
+        const elementID: string = view?.elementID ?? String(idx)
+        const subviews: any[] = view?.subviews ?? []
+        const hasChildren = subviews.length > 0
+        
+        // Default to expanded if not in state map yet
+        if (!expandState.has(idx)) { expandState.set(idx, true) }
+        let expanded = expandState.get(idx)!
+        
+        const row = UILayoutDebugger._el("div", [
+            "display: flex",
+            "align-items: baseline",
+            "padding: 1px 10px 1px " + (10 + depth * 12) + "px",
+            "cursor: " + (hasChildren ? "pointer" : "default"),
+            "border-radius: 3px",
+            "margin: 0 4px",
+        ])
+        
+        const chevron = UILayoutDebugger._el("span", [
+            "display: inline-block", "width: 10px", "flex-shrink: 0",
+            "color: #7070a0", "font-size: 8px", "margin-right: 2px", "text-align: center",
+        ])
+        chevron.textContent = !hasChildren ? "" : expanded ? "▾" : "▸"
+        
+        const dot = UILayoutDebugger._el("span", [
+            "display: inline-block", "width: 7px", "height: 7px",
+            "border-radius: 50%", "margin-right: 5px", "flex-shrink: 0",
+            "background: #4a4a5a",
+        ])
+        
+        const classSpan = UILayoutDebugger._el("span", ["color: #9090a8"])
+        classSpan.textContent = className
+        
+        const eidSpan = UILayoutDebugger._el("span", ["color: #6a6a80", "margin-left: 4px"])
+        eidSpan.textContent = `#${elementID}`
+        
+        const frameSpan = UILayoutDebugger._el("span", ["color: #55556a", "margin-left: 4px", "font-size: 9px"])
+        frameSpan.textContent = frame
+                                ? `${frame.left.toFixed(0)},${frame.top.toFixed(0)}  ${frame.width.toFixed(0)}×${frame.height.toFixed(0)}`
+                                : ""
+        
+        row.append(chevron, dot, classSpan, eidSpan, frameSpan)
+        
+        row.title = [
+            `${className} #${elementID}`,
+            frame
+            ? `frame: ${frame.left.toFixed(1)},${frame.top.toFixed(1)}  ${frame.width.toFixed(1)}×${frame.height.toFixed(1)}`
+            : "frame: (none)",
+            "cache: " + UILayoutDebugger._formatCacheSnapshot(cache),
+        ].join("\n")
+        
+        container.appendChild(row)
+        
+        if (!hasChildren) { return }
+        
+        const childContainer = UILayoutDebugger._el("div", [
+            "display: " + (expanded ? "block" : "none"),
+        ])
+        container.appendChild(childContainer)
+        
+        for (const sv of subviews) {
+            UILayoutDebugger._renderLiveNode(sv, childContainer, depth + 1, visited, expandState)
+        }
+        
+        row.onclick = () => {
+            expanded = !expanded
+            expandState.set(idx, expanded)
+            childContainer.style.display = expanded ? "block" : "none"
+            chevron.textContent = expanded ? "▾" : "▸"
+        }
+    }
+    
+    static _renderDiffPanel(
+        baseline: UILayoutDebugStateSnapshot,
+        current: UILayoutDebugStateSnapshot,
+        onNavigate: (viewIndex: number) => void,
+        baselineTakenAt: number,
+    ): HTMLElement {
+        const panel = UILayoutDebugger._el("div", [
+            "display: flex",
+            "flex-direction: column",
+            "flex: 1",
+            "min-height: 0",
+            "overflow: hidden",
+        ])
+        
+        // ── Summary bar ───────────────────────────────────────────────────────
+        const diffs = UILayoutDebugger._diffSnapshots(baseline, current)
+        const counts = { appeared: 0, disappeared: 0, frame: 0, cache: 0, both: 0, unchanged: 0 }
+        for (const d of diffs) { counts[d.kind]++ }
+        const changed = counts.appeared + counts.disappeared + counts.frame + counts.cache + counts.both
+        
+        const summaryBar = UILayoutDebugger._el("div", [
+            "padding: 5px 10px",
+            "border-bottom: 1px solid rgba(255,255,255,0.08)",
+            "display: flex",
+            "gap: 8px",
+            "align-items: center",
+            "flex-shrink: 0",
+            "font-size: 10px",
+            "flex-wrap: wrap",
+        ])
+        
+        const summaryItems: [string, number, string][] = [
+            ["appeared",    counts.appeared,    "#88ff99"],
+            ["disappeared", counts.disappeared, "#ff8888"],
+            ["frame+cache", counts.both,        "#ffaa55"],
+            ["frame",       counts.frame,       "#7bc8ff"],
+            ["cache",       counts.cache,       "#ffcc88"],
+            ["unchanged",   counts.unchanged,   "#5a5a70"],
+        ]
+        for (const [label, count, color] of summaryItems) {
+            if (count === 0) { continue }
+            const chip = UILayoutDebugger._el("span", [`color: ${color}`])
+            chip.textContent = `${count} ${label}`
+            summaryBar.appendChild(chip)
+        }
+        if (changed === 0) {
+            const chip = UILayoutDebugger._el("span", ["color: #9090a8"])
+            chip.textContent = "No changes"
+            summaryBar.appendChild(chip)
+        }
+        
+        const ts = UILayoutDebugger._el("span", ["color: #5a5a70", "margin-left: auto", "white-space: nowrap"])
+        const elapsed = ((current.takenAt - baseline.takenAt) / 1000).toFixed(1)
+        ts.textContent = `+${elapsed}s`
+        summaryBar.appendChild(ts)
+        
+        panel.appendChild(summaryBar)
+        
+        // ── Filter tabs ───────────────────────────────────────────────────────
+        let diffFilter: UILayoutDebugDiffKind | "all" = changed > 0 ? "frame" : "all"
+        
+        const tabBar = UILayoutDebugger._el("div", [
+            "display: flex",
+            "border-bottom: 1px solid rgba(255,255,255,0.08)",
+            "flex-shrink: 0",
+            "font-size: 10px",
+        ])
+        
+        const list = UILayoutDebugger._el("div", [
+            "overflow-y: auto",
+            "flex: 1",
+            "padding: 4px 0",
+        ])
+        
+        const renderList = (filter: UILayoutDebugDiffKind | "all") => {
+            list.innerHTML = ""
+            const visible = filter === "all"
+                            ? diffs
+                            : diffs.filter(d => d.kind === filter || (filter === "frame" && d.kind === "both"))
+            
+            if (visible.length === 0) {
+                const msg = UILayoutDebugger._el("div", ["padding: 8px 12px", "color: #5a5a70"])
+                msg.textContent = "No items."
+                list.appendChild(msg)
+                return
+            }
+            
+            for (const d of visible) {
+                const kindColors: Record<UILayoutDebugDiffKind, string> = {
+                    appeared: "#88ff99", disappeared: "#ff8888",
+                    both: "#ffaa55", frame: "#7bc8ff", cache: "#ffcc88", unchanged: "#5a5a70",
+                }
+                
+                // Find which pass first changed this view after the baseline
+                const causingTrace = d.kind !== "disappeared"
+                                     ? UILayoutDebugger._findCausingTrace(d.viewIndex, baselineTakenAt)
+                                     : null
+                const hasTrace = !!causingTrace
+                
+                const row = UILayoutDebugger._el("div", [
+                    "padding: 3px 10px",
+                    "border-bottom: 1px solid rgba(255,255,255,0.04)",
+                    "font-size: 10px",
+                    hasTrace ? "cursor: pointer" : "cursor: default",
+                ])
+                if (hasTrace) {
+                    row.title = `Click to jump to pass #${causingTrace!.passIndex} in the pass inspector`
+                    row.onmouseenter = () => { row.style.background = "rgba(255,255,255,0.06)" }
+                    row.onmouseleave = () => { row.style.background = "" }
+                    row.onclick = () => onNavigate(d.viewIndex)
+                }
+                
+                const topLine = UILayoutDebugger._el("div", ["display: flex", "gap: 6px", "align-items: baseline"])
+                
+                const kindTag = UILayoutDebugger._el("span", [
+                    `color: ${kindColors[d.kind]}`,
+                    "flex-shrink: 0",
+                    "font-size: 9px",
+                    "font-weight: bold",
+                    "min-width: 70px",
+                ])
+                kindTag.textContent = d.kind.toUpperCase()
+                
+                const cls = UILayoutDebugger._el("span", ["color: #ffcc88", "font-weight: bold"])
+                cls.textContent = d.className
+                
+                const eid = UILayoutDebugger._el("span", ["color: #6a6a80"])
+                eid.textContent = `#${d.elementID}`
+                
+                if (causingTrace) {
+                    const passTag = UILayoutDebugger._el("span", [
+                        "color: #59599b",
+                        "margin-left: auto",
+                        "font-size: 9px",
+                        "flex-shrink: 0",
+                    ])
+                    passTag.textContent = `pass #${causingTrace.passIndex}`
+                    topLine.append(kindTag, cls, eid, passTag)
+                }
+                else {
+                    topLine.append(kindTag, cls, eid)
+                }
+                row.appendChild(topLine)
+                
+                if (d.kind !== "appeared" && d.kind !== "disappeared") {
+                    if (d.kind === "frame" || d.kind === "both") {
+                        const frameLine = UILayoutDebugger._el("div", ["padding-left: 76px", "color: #b0b0c8", "font-size: 9px"])
+                        frameLine.textContent = "frame: " + UILayoutDebugger._formatFrameDiff(d.baselineFrame, d.currentFrame)
+                        row.appendChild(frameLine)
+                    }
+                    if (d.kind === "cache" || d.kind === "both") {
+                        const cacheLine = UILayoutDebugger._el("div", ["padding-left: 76px", "color: #a0a090", "font-size: 9px"])
+                        cacheLine.textContent = "cache: " + UILayoutDebugger._formatCacheDiff(d.baselineCache, d.currentCache)
+                        row.appendChild(cacheLine)
+                    }
+                }
+                else {
+                    const frameLine = UILayoutDebugger._el("div", ["padding-left: 76px", "color: #b0b0c8", "font-size: 9px"])
+                    frameLine.textContent = "frame: " + UILayoutDebugger._formatFrame(
+                        d.kind === "appeared" ? d.currentFrame : d.baselineFrame
+                    )
+                    row.appendChild(frameLine)
+                }
+                
+                list.appendChild(row)
+            }
+        }
+        
+        const tabs: [string, UILayoutDebugDiffKind | "all", number, string][] = [
+            ["All",         "all",         diffs.length,          "#9090a8"],
+            ["Frame",       "frame",       counts.frame + counts.both, "#7bc8ff"],
+            ["Cache",       "cache",       counts.cache + counts.both, "#ffcc88"],
+            ["Appeared",    "appeared",    counts.appeared,       "#88ff99"],
+            ["Disappeared", "disappeared", counts.disappeared,    "#ff8888"],
+        ]
+        
+        const buildTabs = () => {
+            tabBar.innerHTML = ""
+            for (const [label, filter, count, color] of tabs) {
+                if (count === 0 && filter !== "all") { continue }
+                const tab = UILayoutDebugger._el("div", [
+                    "padding: 4px 8px",
+                    "cursor: pointer",
+                    "border-bottom: 2px solid " + (diffFilter === filter ? color : "transparent"),
+                    `color: ${diffFilter === filter ? color : "#6a6a80"}`,
+                    "white-space: nowrap",
+                    "font-size: 10px",
+                ])
+                tab.textContent = `${label} (${count})`
+                tab.onclick = () => {
+                    diffFilter = filter
+                    buildTabs()
+                    renderList(diffFilter)
+                }
+                tabBar.appendChild(tab)
+            }
+        }
+        
+        buildTabs()
+        panel.appendChild(tabBar)
+        panel.appendChild(list)
+        renderList(diffFilter)
+        
+        return panel
+    }
+    
+    static _renderStepDetail(activeStep: UILayoutDebugStep): HTMLElement {
+        const detail = UILayoutDebugger._el("div", [
+            "padding: 6px 10px",
+            "border-bottom: 1px solid rgba(255,255,255,0.08)",
+            "flex-shrink: 0",
+            "font-size: 10px",
+        ])
+        
+        const titleRow = UILayoutDebugger._el("div", ["margin-bottom: 3px"])
+        
+        const stepTag = UILayoutDebugger._el("span", [
+            "background: #2a2a44",
+            "border-radius: 3px",
+            "padding: 0 4px",
+            "margin-right: 5px",
+            "color: #aac8ff",
+            "font-weight: bold",
+        ])
+        stepTag.textContent = `step ${activeStep.stepIndex}`
+        
+        const iterTag = UILayoutDebugger._el("span", ["color: #9090a8", "margin-right: 6px"])
+        iterTag.textContent = `iter ${activeStep.iteration + 1}`
+        
+        const className = UILayoutDebugger._el("span", ["color: #ffcc88", "font-weight: bold"])
+        className.textContent = activeStep.className
+        
+        const eid = UILayoutDebugger._el("span", ["color: #9090a8", "margin-left: 4px"])
+        eid.textContent = `#${activeStep.elementID}`
+        
+        titleRow.append(stepTag, iterTag, className, eid)
+        detail.appendChild(titleRow)
+        
+        const frameRow = UILayoutDebugger._el("div", ["color: #c0c0d8", "margin-bottom: 2px"])
+        frameRow.textContent = "frame: " + UILayoutDebugger._formatFrameDiff(activeStep.frameBefore, activeStep.frameAfter)
+        detail.appendChild(frameRow)
+        
+        // ── Intrinsic cache diff ──────────────────────────────────────────────
+        const cacheDiffStr = UILayoutDebugger._formatCacheDiff(activeStep.cacheBefore, activeStep.cacheAfter)
+        const cacheRow = UILayoutDebugger._el("div", ["margin-bottom: 3px"])
+        
+        const cacheLabel = UILayoutDebugger._el("span", ["color: #8888a0", "margin-right: 4px"])
+        cacheLabel.textContent = "cache:"
+        
+        const cacheChanged =
+            (activeStep.cacheBefore?.entryCount ?? 0) !== (activeStep.cacheAfter?.entryCount ?? 0) ||
+            cacheDiffStr.includes("~") || cacheDiffStr.includes("+") || cacheDiffStr.includes("-")
+        
+        const cacheSummary = UILayoutDebugger._el("span", [
+            "color: " + (cacheChanged ? "#ffcc88" : "#7878a0"),
+            "cursor: pointer",
+            "font-weight: " + (cacheChanged ? "bold" : "normal"),
+        ])
+        const bCount = activeStep.cacheBefore?.entryCount ?? 0
+        const aCount = activeStep.cacheAfter?.entryCount ?? 0
+        cacheSummary.textContent = bCount === aCount
+                                   ? `${aCount} entr${aCount === 1 ? "y" : "ies"}${cacheChanged ? " (changed)" : ""}`
+                                   : `${bCount} → ${aCount} entries`
+        
+        let cacheExpanded = false
+        const cacheDetail = UILayoutDebugger._el("div", [
+            "display: none",
+            "margin-top: 2px",
+            "padding: 4px 6px",
+            "background: rgba(255,255,255,0.04)",
+            "border-radius: 3px",
+            "color: #9090a8",
+            "font-size: 9px",
+            "line-height: 1.6",
+            "white-space: pre",
+        ])
+        cacheDetail.textContent = cacheDiffStr
+        
+        cacheSummary.onclick = () => {
+            cacheExpanded = !cacheExpanded
+            cacheDetail.style.display = cacheExpanded ? "block" : "none"
+        }
+        
+        cacheRow.append(cacheLabel, cacheSummary)
+        detail.appendChild(cacheRow)
+        detail.appendChild(cacheDetail)
+        
+        const trigger = activeStep.trigger
+        const triggerRow = UILayoutDebugger._el("div", ["margin-top: 4px", "margin-bottom: 2px"])
+        if (trigger) {
+            const triggerLabel = UILayoutDebugger._el("span", ["color: #8888a0", "margin-right: 4px"])
+            triggerLabel.textContent = "setNeedsLayout from"
+            
+            const triggerFn = UILayoutDebugger._el("span", ["color: #88ddff", "font-weight: bold", "cursor: pointer"])
+            triggerFn.textContent = trigger.callerFunction + "()"
+            triggerFn.title = trigger.cleanStack
+            
+            let stackExpanded = false
+            const stackEl = UILayoutDebugger._el("div", [
+                "display: none",
+                "margin-top: 3px",
+                "padding: 4px 6px",
+                "background: rgba(255,255,255,0.04)",
+                "border-radius: 3px",
+                "color: #7878a0",
+                "font-size: 9px",
+                "line-height: 1.5",
+                "white-space: pre",
+                "overflow-x: auto",
+            ])
+            stackEl.textContent = trigger.cleanStack
+            
+            triggerFn.onclick = () => {
+                stackExpanded = !stackExpanded
+                stackEl.style.display = stackExpanded ? "block" : "none"
+            }
+            
+            triggerRow.append(triggerLabel, triggerFn)
+            detail.appendChild(triggerRow)
+            detail.appendChild(stackEl)
+        }
+        else {
+            const triggerLabel = UILayoutDebugger._el("span", ["color: #5a5a70"])
+            triggerLabel.textContent = "setNeedsLayout trigger not captured"
+            triggerRow.appendChild(triggerLabel)
+            detail.appendChild(triggerRow)
+        }
+        
+        if (activeStep.subviewRecords.length > 0) {
+            const svHeader = UILayoutDebugger._el("div", ["color: #8888a0", "margin-top: 4px", "margin-bottom: 2px"])
+            svHeader.textContent = `Subviews set (${activeStep.subviewRecords.length}):`
+            detail.appendChild(svHeader)
+            
+            for (const sv of activeStep.subviewRecords) {
+                const svRow = UILayoutDebugger._el("div", ["padding-left: 8px", "color: #a0a0b8"])
+                const svClass = UILayoutDebugger._el("span", ["color: #d8aacc"])
+                svClass.textContent = sv.className
+                const svEid = UILayoutDebugger._el("span", ["color: #6a6a80"])
+                svEid.textContent = ` #${sv.elementID}  `
+                const svFrames = UILayoutDebugger._el("span", ["color: #9090a8"])
+                svFrames.textContent = UILayoutDebugger._formatFrameDiff(sv.frameBefore, sv.frameAfter)
+                svRow.append(svClass, svEid, svFrames)
+                detail.appendChild(svRow)
+            }
+        }
+        
+        return detail
+    }
+    
+    static _subtreeHasTouched(node: UILayoutDebugTreeNode, countMap: Map<number, number>): boolean {
+        if ((countMap.get(node.viewIndex) ?? 0) > 0) { return true }
+        for (const child of node.children) {
+            if (UILayoutDebugger._subtreeHasTouched(child, countMap)) { return true }
+        }
+        return false
+    }
+    
+    static _subtreeContains(node: UILayoutDebugTreeNode, viewIndex: number): boolean {
+        if (node.viewIndex === viewIndex) { return true }
+        for (const child of node.children) {
+            if (UILayoutDebugger._subtreeContains(child, viewIndex)) { return true }
+        }
+        return false
+    }
+    
+    static _renderTreeNode(
+        node: UILayoutDebugTreeNode,
+        container: HTMLElement,
+        countMap: Map<number, number>,
+        activeViewIndex: number,
+        expandState: Map<number, boolean> | null,
+        stepMap: Map<number, UILayoutDebugStep>,
+    ): HTMLElement | null {
+        const count = countMap.get(node.viewIndex) ?? 0
+        const isActive = node.viewIndex === activeViewIndex && activeViewIndex >= 0
+        const hasChildren = node.children.length > 0
+        
+        // Expand only if this node is on the path to the active view.
+        // If there is no active view, fall back to "has touched descendants"
+        // so the tree isn't entirely collapsed before any step is selected.
+        const isAncestorOfActive = activeViewIndex >= 0
+                                   ? UILayoutDebugger._subtreeContains(node, activeViewIndex)
+                                   : node.children.some(c => UILayoutDebugger._subtreeHasTouched(c, countMap))
+        const defaultExpanded = isAncestorOfActive || isActive
+        
+        let childrenExpanded: boolean
+        if (expandState !== null) {
+            if (!expandState.has(node.viewIndex)) {
+                expandState.set(node.viewIndex, defaultExpanded)
+            }
+            childrenExpanded = expandState.get(node.viewIndex)!
+        }
+        else {
+            childrenExpanded = defaultExpanded
+        }
+        
+        // ── Row ──────────────────────────────────────────────────────────────
+        const row = UILayoutDebugger._el("div", [
+            "display: flex",
+            "align-items: baseline",
+            "padding: 1px 10px 1px " + (10 + node.depth * 12) + "px",
+            "cursor: " + (hasChildren ? "pointer" : "default"),
+            "border-radius: 3px",
+            "margin: 0 4px",
+            isActive
+            ? "background: rgba(100,120,220,0.35); outline: 1px solid #59599b"
+            : "background: transparent",
+        ])
+        
+        // Expand/collapse chevron
+        const chevron = UILayoutDebugger._el("span", [
+            "display: inline-block",
+            "width: 10px",
+            "flex-shrink: 0",
+            "color: #7070a0",
+            "font-size: 8px",
+            "margin-right: 2px",
+            "text-align: center",
+        ])
+        chevron.textContent = !hasChildren ? "" : childrenExpanded ? "▾" : "▸"
+        
+        // Heat dot
+        const dot = UILayoutDebugger._el("span", [
+            "display: inline-block",
+            "width: 7px",
+            "height: 7px",
+            "border-radius: 50%",
+            "margin-right: 5px",
+            "flex-shrink: 0",
+            "background: " + UILayoutDebugger._heatColor(count),
+        ])
+        
+        // Untouched nodes are muted; touched nodes are bright
+        const untouchedColor = count === 0 ? "#9090a8" : "#ffcc88"
+        const className = UILayoutDebugger._el("span", [
+            "color: " + untouchedColor,
+            "font-weight: " + (count > 0 ? "bold" : "normal"),
+        ])
+        className.textContent = node.className
+        
+        const eid = UILayoutDebugger._el("span", [
+            "color: " + (count === 0 ? "#6a6a80" : "#a0a0b8"),
+            "margin-left: 4px",
+        ])
+        eid.textContent = `#${node.elementID}`
+        
+        const frameStr = node.frame
+                         ? `  ${node.frame.left.toFixed(0)},${node.frame.top.toFixed(0)}  ${node.frame.width.toFixed(0)}×${node.frame.height.toFixed(0)}`
+                         : ""
+        const frameSpan = UILayoutDebugger._el("span", [
+            "color: " + (count === 0 ? "#55556a" : "#7878a0"),
+            "margin-left: 4px",
+        ])
+        frameSpan.textContent = frameStr
+        
+        // For touched nodes, show what changed in this pass inline
+        const step = stepMap.get(node.viewIndex)
+        const frameChanged = step
+                             ? !UILayoutDebugger._framesEqual(step.frameBefore, step.frameAfter)
+                             : false
+        const cacheChanged = step
+                             ? !UILayoutDebugger._cachesEqual(step.cacheBefore, step.cacheAfter)
+                             : false
+        
+        const deltaSpan = UILayoutDebugger._el("span", [
+            "margin-left: 5px",
+            "font-size: 9px",
+            "flex-shrink: 0",
+        ])
+        if (frameChanged && cacheChanged) {
+            deltaSpan.style.color = "#ffaa55"
+            deltaSpan.textContent = "frame+cache"
+        }
+        else if (frameChanged) {
+            deltaSpan.style.color = "#7bc8ff"
+            deltaSpan.textContent = UILayoutDebugger._formatFrameDiff(step!.frameBefore, step!.frameAfter)
+        }
+        else if (cacheChanged) {
+            deltaSpan.style.color = "#ffcc88"
+            deltaSpan.textContent = "cache changed"
+        }
+        
+        if (count > 0) {
+            const countBadge = UILayoutDebugger._el("span", [
+                "margin-left: 5px",
+                "background: " + UILayoutDebugger._heatColor(count),
+                "color: #000",
+                "border-radius: 8px",
+                "padding: 0 4px",
+                "font-size: 9px",
+                "font-weight: bold",
+            ])
+            countBadge.textContent = String(count) + "×"
+            if (frameChanged || cacheChanged) {
+                row.append(chevron, dot, className, eid, frameSpan, deltaSpan, countBadge)
+            }
+            else {
+                row.append(chevron, dot, className, eid, frameSpan, countBadge)
+            }
+        }
+        else {
+            row.append(chevron, dot, className, eid, frameSpan)
+        }
+        
+        // Tooltip on hover
+        const cacheStr = UILayoutDebugger._formatCacheSnapshot(node.cacheAfterPass)
+        const tooltipLines = [
+            node.className + " #" + node.elementID,
+            "viewIndex: " + node.viewIndex,
+            node.frame
+            ? `frame: ${node.frame.left.toFixed(1)}, ${node.frame.top.toFixed(1)}  ${node.frame.width.toFixed(1)}×${node.frame.height.toFixed(1)}`
+            : "frame: (none)",
+            "laid out: " + count + "×",
+            "intrinsic cache (post-pass): " + cacheStr,
+        ]
+        if (step && frameChanged) {
+            tooltipLines.push("frame Δ: " + UILayoutDebugger._formatFrameDiff(step.frameBefore, step.frameAfter))
+        }
+        if (step && cacheChanged) {
+            tooltipLines.push("cache Δ: " + UILayoutDebugger._formatCacheDiff(step.cacheBefore, step.cacheAfter))
+        }
+        row.title = tooltipLines.join("\n")
+        
+        container.appendChild(row)
+        
+        // ── Children container ───────────────────────────────────────────────
+        if (!hasChildren) { return isActive ? row : null }
+        
+        const childContainer = UILayoutDebugger._el("div", [
+            "display: " + (childrenExpanded ? "block" : "none"),
+        ])
+        container.appendChild(childContainer)
+        
+        let activeRow: HTMLElement | null = isActive ? row : null
+        
+        for (const child of node.children) {
+            const result = UILayoutDebugger._renderTreeNode(
+                child, childContainer, countMap, activeViewIndex, expandState, stepMap
+            )
+            if (result) { activeRow = result }
+        }
+        
+        // Toggle expand/collapse on row click.
+        row.onclick = () => {
+            childrenExpanded = !childrenExpanded
+            if (expandState !== null) {
+                expandState.set(node.viewIndex, childrenExpanded)
+            }
+            childContainer.style.display = childrenExpanded ? "block" : "none"
+            chevron.textContent = childrenExpanded ? "▾" : "▸"
+        }
+        
+        return activeRow
+    }
+    
+    
+    // ── Formatting helpers ───────────────────────────────────────────────────
+    
+    static _formatFrame(f: UILayoutDebugFrame | null): string {
+        if (!f) { return "(none)" }
+        return `${f.left.toFixed(0)},${f.top.toFixed(0)}  ${f.width.toFixed(0)}×${f.height.toFixed(0)}`
+    }
+    
+    static _formatFrameDiff(
+        before: UILayoutDebugFrame | null,
+        after: UILayoutDebugFrame | null
+    ): string {
+        if (!before && !after) { return "(no frame data)" }
+        const bounds = UILayoutDebugger._boundsBasedDiff
+        const fmt = (f: UILayoutDebugFrame | null) => {
+            if (!f) { return "(none)" }
+            return bounds
+                   ? `${f.width.toFixed(0)}×${f.height.toFixed(0)}`
+                   : UILayoutDebugger._formatFrame(f)
+        }
+        if (!before) { return `→ ${fmt(after)}` }
+        if (!after)  { return `${fmt(before)} → (none)` }
+        const changed = bounds
+                        ? (before.width !== after.width || before.height !== after.height)
+                        : (before.left !== after.left || before.top !== after.top ||
+                before.width !== after.width || before.height !== after.height)
+        if (!changed) {
+            return `= ${fmt(after)}`
+        }
+        return `${fmt(before)}  →  ${fmt(after)}`
+    }
+    
+    static _formatCacheSnapshot(c: UILayoutDebugCacheSnapshot | null): string {
+        if (!c) { return "(none)" }
+        const lines: string[] = []
+        if (c.entryCount === 0) {
+            lines.push("intrinsic: empty")
+        }
+        else {
+            const intrinsicLines = Object.entries(c.entries).map(([key, val]) => {
+                const match = key.match(/h_(\d+(?:\.\d+)?)__w_(\d+(?:\.\d+)?)/)
+                const label = match
+                              ? (match[1] !== "0" && match[2] !== "0"
+                                 ? `h≤${match[1]} w≤${match[2]}`
+                                 : match[2] !== "0" ? `w≤${match[2]}` : `h≤${match[1]}`)
+                              : key
+                return `  ${label}: ${val.width.toFixed(0)}×${val.height.toFixed(0)}`
+            })
+            const prefix = c.isShared ? `shared(${c.sharedKey}) ` : ""
+            lines.push(`${prefix}${c.entryCount} entr${c.entryCount === 1 ? "y" : "ies"}`)
+            lines.push(...intrinsicLines)
+        }
+        lines.push(c.hasFrameCache
+                   ? `frameCache: ${UILayoutDebugger._formatFrame(c.frameCache)}`
+                   : "frameCache: (empty)")
+        lines.push(c.hasVirtualFrameCache
+                   ? `virtualFrameCache: ${UILayoutDebugger._formatFrame(c.virtualFrameCache)}`
+                   : "virtualFrameCache: (empty)")
+        return lines.join("\n")
+    }
+    
+    static _formatCacheDiff(
+        before: UILayoutDebugCacheSnapshot | null,
+        after: UILayoutDebugCacheSnapshot | null
+    ): string {
+        if (!before && !after) { return "(no cache data)" }
+        const bCount = before?.entryCount ?? 0
+        const aCount = after?.entryCount ?? 0
+        if (bCount === 0 && aCount === 0 && !before?.hasFrameCache && !after?.hasFrameCache && !before?.hasVirtualFrameCache && !after?.hasVirtualFrameCache) { return "empty → empty" }
+        
+        const lines: string[] = []
+        const allKeys = new Set([
+            ...Object.keys(before?.entries ?? {}),
+            ...Object.keys(after?.entries ?? {}),
+        ])
+        for (const key of allKeys) {
+            const b = before?.entries[key]
+            const a = after?.entries[key]
+            const match = key.match(/h_(\d+(?:\.\d+)?)__w_(\d+(?:\.\d+)?)/)
+            const label = match
+                          ? (match[1] !== "0" && match[2] !== "0"
+                             ? `h≤${match[1]} w≤${match[2]}`
+                             : match[2] !== "0" ? `w≤${match[2]}` : `h≤${match[1]}`)
+                          : key
+            if (!b) {
+                lines.push(`  + ${label}: ${a!.width.toFixed(0)}×${a!.height.toFixed(0)}`)
+            }
+            else if (!a) {
+                lines.push(`  - ${label}: ${b.width.toFixed(0)}×${b.height.toFixed(0)}`)
+            }
+            else if (b.width !== a.width || b.height !== a.height) {
+                lines.push(`  ~ ${label}: ${b.width.toFixed(0)}×${b.height.toFixed(0)} → ${a.width.toFixed(0)}×${a.height.toFixed(0)}`)
+            }
+            else {
+                lines.push(`  = ${label}: ${a.width.toFixed(0)}×${a.height.toFixed(0)}`)
+            }
+        }
+        
+        // Frame cache diff
+        const bHasF = before?.hasFrameCache ?? false
+        const aHasF = after?.hasFrameCache ?? false
+        if (bHasF || aHasF) {
+            if (bHasF && !aHasF) {
+                lines.push(`  - frameCache: ${UILayoutDebugger._formatFrame(before!.frameCache)}`)
+            }
+            else if (!bHasF && aHasF) {
+                lines.push(`  + frameCache: ${UILayoutDebugger._formatFrame(after!.frameCache)}`)
+            }
+            else {
+                const bf = before!.frameCache, af = after!.frameCache
+                const changed = !bf || !af || bf.top !== af.top || bf.left !== af.left || bf.width !== af.width || bf.height !== af.height
+                lines.push(changed
+                           ? `  ~ frameCache: ${UILayoutDebugger._formatFrame(bf)} → ${UILayoutDebugger._formatFrame(af)}`
+                           : `  = frameCache: ${UILayoutDebugger._formatFrame(af)}`)
+            }
+        }
+        else {
+            lines.push("  = frameCache: (empty)")
+        }
+        
+        // Virtual frame cache diff
+        const bHasV = before?.hasVirtualFrameCache ?? false
+        const aHasV = after?.hasVirtualFrameCache ?? false
+        if (bHasV || aHasV) {
+            if (bHasV && !aHasV) {
+                lines.push(`  - virtualFrameCache: ${UILayoutDebugger._formatFrame(before!.virtualFrameCache)}`)
+            }
+            else if (!bHasV && aHasV) {
+                lines.push(`  + virtualFrameCache: ${UILayoutDebugger._formatFrame(after!.virtualFrameCache)}`)
+            }
+            else {
+                const bv = before!.virtualFrameCache, av = after!.virtualFrameCache
+                const changed = !bv || !av || bv.top !== av.top || bv.left !== av.left || bv.width !== av.width || bv.height !== av.height
+                lines.push(changed
+                           ? `  ~ virtualFrameCache: ${UILayoutDebugger._formatFrame(bv)} → ${UILayoutDebugger._formatFrame(av)}`
+                           : `  = virtualFrameCache: ${UILayoutDebugger._formatFrame(av)}`)
+            }
+        }
+        
+        const header = bCount === aCount
+                       ? `${aCount} entr${aCount === 1 ? "y" : "ies"}`
+                       : `${bCount} → ${aCount} entries`
+        return lines.length ? `${header}\n${lines.join("\n")}` : header
+    }
+    
+    static _heatColor(count: number): string {
+        if (count === 0) { return "#4a4a5a" }
+        if (count === 1) { return "#3a8" }
+        if (count === 2) { return "#e80" }
+        return "#d33"
+    }
+    
+    static _el(tag: string, styles: string[]): HTMLElement {
+        const el = document.createElement(tag)
+        el.style.cssText = styles.join("; ")
+        return el
+    }
+    
+    static _btnStyle(color: string): string[] {
+        return [
+            `color: ${color}`,
+            "background: rgba(255,255,255,0.06)",
+            "border: 1px solid rgba(255,255,255,0.1)",
+            "border-radius: 4px",
+            "padding: 1px 6px",
+            "font: inherit",
+            "cursor: pointer",
+            "flex-shrink: 0",
+        ]
+    }
+    
+    
+    // ── Drag-to-move ─────────────────────────────────────────────────────────
+    
+    static _makeDraggable(panel: HTMLElement) {
+        let dragging = false
+        let startX = 0, startY = 0, origRight = 8, origTop = 8
+        
+        panel.addEventListener("mousedown", (e: MouseEvent) => {
+            const target = e.target as HTMLElement
+            if (!target.closest("[data-drag-handle]")) { return }
+            dragging = true
+            startX = e.clientX
+            startY = e.clientY
+            origRight = parseInt(panel.style.right, 10) || 8
+            origTop = parseInt(panel.style.top, 10) || 8
+            e.preventDefault()
+        })
+        
+        document.addEventListener("mousemove", (e: MouseEvent) => {
+            if (!dragging) { return }
+            const dx = e.clientX - startX
+            const dy = e.clientY - startY
+            panel.style.right = (origRight - dx) + "px"
+            panel.style.top = (origTop + dy) + "px"
+        })
+        
+        document.addEventListener("mouseup", () => { dragging = false })
+    }
+    
+}
+
+
+// ── Window registration & global helpers ─────────────────────────────────────
+
+window.UILayoutDebugger = UILayoutDebugger
+
+declare global {
+    interface Window {
+        UILayoutDebugger?: typeof UILayoutDebugger
+    }
+}
+
+/// #endif