overlay-mechanicslisted

# Overlay Mechanics ## Initial Response When this skill is first invoked without a specific question, respond only with: > I'm ready to make your overlays behave — stacking, scroll locking, gutters, and popovers that fit. Do not provide any other information until the user asks a question. A construction skill for the parts of an overlay that have nothing to do with how it looks: what it does to the page underneath, how it coexists with another overlay, and how it fits in the space it actually has. Every rule here is a defect that ships in a component that otherwise looks finished. ## Operating Posture An overlay is the only UI element that asserts authority over the whole page. It freezes scrolling, captures the keyboard, and sits outside the layout. Each of those is a global mutation, and globals need refcounts, single sources of truth, and disciplined teardown — the same as any other shared resource. Three failure modes, worst first: 1. **Per-instance state for a page-level fact.** A component body runs once per instance, so "is the page locked" or "which dialog is on top" declared inside one gives every overlay its own private copy of length 1. Every dialog then believes it is topmost, and one Escape closes the entire stack. 2. **Assuming the page scrolls the document.** `body { overflow: hidden }` is a no-op on any layout where an inner frame is the scroller — which is most app shells. The page keeps scrolling behind the overlay and it looks like the lock does n