/** * 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) */ 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; 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; className: string; elementID: string; frameBefore: UILayoutDebugFrame | null; frameAfter: UILayoutDebugFrame | null; } /** What caused a view to enter the layout queue. */ interface UILayoutDebugTrigger { callerFunction: string; cleanStack: string; } /** One step = one call to layoutIfNeeded() on one view. */ interface UILayoutDebugStep { stepIndex: number; iteration: number; viewIndex: number; className: string; elementID: string; frameBefore: UILayoutDebugFrame | null; frameAfter: UILayoutDebugFrame | null; cacheBefore: UILayoutDebugCacheSnapshot | null; cacheAfter: UILayoutDebugCacheSnapshot | null; subviewRecords: UILayoutDebugSubviewRecord[]; trigger: UILayoutDebugTrigger | null; } interface UILayoutDebugTreeNode { viewIndex: number; className: string; elementID: string; depth: number; frame: UILayoutDebugFrame | null; layoutCount: number; cacheAfterPass: UILayoutDebugCacheSnapshot | null; 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; views: Map; /** 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; iteration: number; viewIndex: number; className: string; elementID: string; cacheKey: string; newValue: { width: number; height: number; }; callerFunction: string; cleanStack: string; } export declare class UILayoutDebugger { static _isEnabled: boolean; static _breakpointsEnabled: boolean; static get isEnabled(): boolean; static get breakpointsEnabled(): boolean; static _passIndex: number; static _currentTrace: UILayoutDebugTrace | null; static _currentIteration: number; static _pendingStep: UILayoutDebugStep | null; static _pendingSubviewsBefore: Map; static _layoutCountsThisPass: Map; static _liveViewRegistry: Map; static _triggerMap: Map; static _noiseFramePrefixes: string[]; static _traces: UILayoutDebugTrace[]; static readonly maxStoredTraces = 20; static _replayTraceIndex: number; static _replayStepIndex: number; static _compareMode: boolean; static _frameFilter: "all" | "changed" | "unchanged"; /** * 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; static _compareTraceIndex: number; static _compareStepIndex: number; static _sharedExpandState: Map; static _singleExpandState: Map; static _liveExpandState: Map; static enable(): void; static disable(): void; /** * 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(): void; static disableBreakpoints(): void; static stepForward(): void; static stepBack(): void; static goToStep(stepIndex: number): void; static goToCompareStep(stepIndex: number): void; static showTrace(traceIndex: number): void; static showCompareTrace(traceIndex: number): void; static get _currentReplayTrace(): UILayoutDebugTrace | null; static get _currentCompareTrace(): UILayoutDebugTrace | null; static willBeginLayoutPass(viewsToLayout: any[]): void; static willBeginIteration(iteration: number): void; /** * 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): void; /** * 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): void; static willLayoutView(view: any): void; /** * Called immediately after view.layoutIfNeeded(). Closes the pending step * with the post-layout frame. */ static didLayoutView(view: any): void; static didFinishLayoutPass(iterationCount: number): void; /** Discard all recorded traces and reset the replay state. */ static clearTraces(): void; /** Capture the current view tree state as the baseline for future diffs. */ static captureBaseline(): void; /** Capture the current state and diff it against the baseline. */ static captureAndDiff(): void; static clearDiff(): void; /** * ☢ 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(): void; static clearStaleReport(): void; static toggleLiveInspector(): void; static _captureStateSnapshot(label: string): UILayoutDebugStateSnapshot | null; /** * 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; static _walkViewTree(view: any, out: Map, visited: Set): void; static _diffSnapshots(baseline: UILayoutDebugStateSnapshot, current: UILayoutDebugStateSnapshot): UILayoutDebugViewDiff[]; static _framesEqual(a: UILayoutDebugFrame | null, b: UILayoutDebugFrame | null): boolean; static _cachesEqual(a: UILayoutDebugCacheSnapshot | null, b: UILayoutDebugCacheSnapshot | null): boolean; /** * 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): void; /** * 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): void; /** * 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; static _cleanStack(rawStack: string): string; static _extractCallerFunctionName(cleanStack: string): string; static _captureFrame(view: any): UILayoutDebugFrame | null; static _captureCache(view: any): UILayoutDebugCacheSnapshot | null; static _buildTreeSnapshot(view: any, depth: number, visited?: Set): UILayoutDebugTreeNode; static _baseline: UILayoutDebugStateSnapshot | null; static _diffSnapshot: UILayoutDebugStateSnapshot | null; static _diffMode: boolean; static _liveInspectorMode: boolean; /** 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; passIndex: number; } | null; /** Whether the stale report side-panel is open. */ static _staleReportMode: boolean; static _lastKnownRootView: any; /** * 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; static _overlayRoot: HTMLElement | null; static _overlayVisible: boolean; static _helpMode: boolean; static _ensureOverlay(): void; static _removeOverlay(): void; static _renderOverlay(): void; static _renderPassColumn(traceIndex: number, stepIndex: number, onStepChange: (si: number) => void, onTraceChange: (ti: number) => void, expandState: Map | null, registerTree: (el: HTMLElement) => void, getPeerTree: () => HTMLElement | null): HTMLElement; static _renderStaleReportPanel(result: NonNullable): HTMLElement; static _renderHelpPanel(): HTMLElement; static _renderLiveInspectorPanel(): HTMLElement; static _renderLiveNode(view: any, container: HTMLElement, depth: number, visited: Set, expandState: Map): void; static _renderDiffPanel(baseline: UILayoutDebugStateSnapshot, current: UILayoutDebugStateSnapshot, onNavigate: (viewIndex: number) => void, baselineTakenAt: number): HTMLElement; static _renderStepDetail(activeStep: UILayoutDebugStep): HTMLElement; static _subtreeHasTouched(node: UILayoutDebugTreeNode, countMap: Map): boolean; static _subtreeContains(node: UILayoutDebugTreeNode, viewIndex: number): boolean; static _renderTreeNode(node: UILayoutDebugTreeNode, container: HTMLElement, countMap: Map, activeViewIndex: number, expandState: Map | null, stepMap: Map): HTMLElement | null; static _formatFrame(f: UILayoutDebugFrame | null): string; static _formatFrameDiff(before: UILayoutDebugFrame | null, after: UILayoutDebugFrame | null): string; static _formatCacheSnapshot(c: UILayoutDebugCacheSnapshot | null): string; static _formatCacheDiff(before: UILayoutDebugCacheSnapshot | null, after: UILayoutDebugCacheSnapshot | null): string; static _heatColor(count: number): string; static _el(tag: string, styles: string[]): HTMLElement; static _btnStyle(color: string): string[]; static _makeDraggable(panel: HTMLElement): void; } declare global { interface Window { UILayoutDebugger?: typeof UILayoutDebugger; } } export {};