actual-css 0.6.0 → 0.8.0

package/docs/design-notes/popover-manual-poc.md

@@ -0,0 +1,328 @@
+# POC: native popover as the surface transport
+
+A record of an experiment, not a plan of record. It exists so the reasoning
+outlives the branch that produced it — including the parts that came out
+negative, which are the ones a future attempt would otherwise repeat.
+
+Question asked: can `popover="manual"` replace the DOM reparenting in
+`surface.js` without changing anything else?
+
+Answer: yes. The branch demonstrated it, the WebKit gate below closed it, and
+the migration checklist at the end has been executed — so this note is now also
+the record of what the checklist got wrong. The cost was a browser floor, not
+an architecture change; see [browser-support](browser-support.md).
+
+## Branch
+
+`poc/popover-manual-surfaces`, four commits on top of `0f4f8b7`:
+
+| SHA       | Step                                              |
+| --------- | ------------------------------------------------- |
+| `bf1e53d` | Pass 1 — manual transport, reparenting removed    |
+| `4d598dd` | Extract the popover test stub, cut to the minimum |
+| `ececcd6` | Pass 2 — keep a runtime scrim, fix its placement  |
+| `27b34f1` | Finish as a transparent migration                 |
+
+## What the transport actually needs
+
+Derived from the branch, not from a compatibility badge. The distinction between
+the two contracts matters: they fail differently, and only the first gates the
+runtime.
+
+```text
+JS requirement (gates the runtime)
+----------------------------------
+popover="manual"
+showPopover()
+hidePopover()
+top-layer promotion + closed-state display:none
+
+CSS enhancement (already @supports-gated, degrades)
+---------------------------------------------------
+:popover-open
+overlay
+transition-behavior: allow-discrete
+@starting-style
+```
+
+The runtime never reads `:popover-open`. It was removed from `isSurfaceOpen()`
+and from the `autoUpdate` guard because a partially-implemented selector engine
+answers `false` rather than throwing, which is a silent wrong answer (see the
+happy-dom finding below). `.is-open` is the single state the runtime writes and
+reads, and the class the CSS keys on.
+
+Two capabilities that are *not* required, which matters because both are newer
+than Popover and would have pushed the floor much higher:
+
+- `overlay` / `allow-discrete` — the exit fade. Gated; without it the exit is
+  instant and correct.
+- `::backdrop` — proved unusable, see below.
+
+## Findings
+
+**happy-dom implements no Popover element API.** Version 20.11 has the invoker
+attributes (`popoverTargetElement`, `popoverTargetAction` on button and input)
+but not `showPopover` / `hidePopover` / `togglePopover`, and
+`matches(":popover-open")` answers `false` rather than throwing. The silent
+false is the dangerous half: reading the pseudo-class in `isSurfaceOpen()` made
+all 647 unit tests see "never open". Resolved by reading `.is-open` only, plus
+two no-op stubs in `tests/helpers/popover-stub.js`. Transport behavior moved to
+the browser layer, which is where it belonged.
+
+**`::backdrop` cannot replace the sheet scrim.** Negative result, measured, and
+the one most likely to be re-attempted. The native backdrop is painted for a
+manual popover, covers the viewport, and does inherit custom properties from
+its originating element — a scoped `--backdrop-fill` on an ancestor of the
+panel resolved into it, which a body-level div cannot do. But the UA sets
+`pointer-events: none` on an open popover's backdrop and it is not overridable
+from author CSS: both `pointer-events: auto` and `pointer-events: auto
+!important` computed as `none`, since a UA `!important` outranks an author one.
+Measured with a real CDP click on the scrim, the element behind it received the
+click and its handler fired. The scrim has two jobs — painting, and absorbing
+the pointer — and the platform only offers the first, so it stays an Actual
+element.
+
+**The scrim's placement, not the scrim, was what pass 1 broke.**
+`menu.before(backdrop)` put it beside a panel that no longer moves, stranding
+it inside the author's container. It goes to the document root instead, which
+reproduces exactly where it landed before. This is the one fragment of
+`getSurfaceRoot()` that survives, and it is not the reparenting the transport
+removed: the scrim is runtime-created, has no author identity, and nothing
+inherited to preserve.
+
+**A surface inside a modal dialog works.** This was the open question, since a
+modal dialog inerts the rest of the document — which is why the old transport
+moved the panel into the dialog. Measured: the panel is promoted above the
+dialog, stays in the dialog subtree and in its own host element, wins the hit
+test, and takes focus.
+
+**`aria-expanded` is computed natively for a `popovertarget` invoker** —
+`expanded: false` closed, `true` open, on the AX tree. Deliberately not
+exploited: the public contract is `aria-controls`, so `popovertarget` would be
+a markup migration for adopters rather than an internal transport detail, and
+`linkedTriggers()` supports several triggers per panel where `popovertarget`
+covers one.
+
+## Measurements
+
+| Measure                   | `master` |             POC |
+| ------------------------- | -------: | --------------: |
+| `surface.js` code lines   |      358 |         **337** |
+| `surface.js` total lines  |      431 |             436 |
+| Transport concepts        |        4 |           **1** |
+| Inherited contexts broken |      3/3 |         **0/3** |
+| Unit tests                |      647 | **650**, 0 fail |
+| Browser tests             |       50 |  **55**, 0 fail |
+| JS full, brotli           |  16.1 KB |     **16.0 KB** |
+| Public contracts changed  |        — |        **none** |
+
+Removed: `mountedSurfaces`, `getSurfaceRoot()`, `mountSurface()`,
+`restoreSurface()`, `disconnectSurface`'s `{ restore }` option, and the
+`[popover]` conflict warning — the runtime is that owner now.
+
+The total line count *grows* by five. The 21 fewer code lines are outweighed by
+added comments. "Remove more than you add" is a signal, not a rule: what leaves
+is a concept — a component no longer has to leave its place in the DOM to be
+painted above the page — plus a defect with no generic repair and three
+transport abstractions.
+
+## Acceptance criterion
+
+> A transport migration may change assertions about transport markers, but must
+> not require changing behavioral assertions.
+
+This is stricter and more useful than "no public API change". The 57
+`hidden → .is-open` edits qualify: they replace observing a mechanism with
+observing the lifecycle that owns it. If a future attempt has to modify an
+assertion about focus, dismissal, positioning or events to make the transport
+pass, it is no longer a transport swap and the claim does not hold.
+
+## Go / no-go: WebKit verification
+
+The measurements above were taken on Chromium — the browser test harness
+hardcodes `backend: "chrome"`. The floor's most notable step is Safari 17, so
+the transport needed evidence on the engine the raise actually buys. That was
+the one open technical gate on the migration. It is now closed.
+
+A permanent WebKit matrix was disproportionate for a decision taken once. One
+manual pass on a real Safari at the chosen floor:
+
+```text
+1. showPopover() / hidePopover() in manual mode
+2. a closed panel is genuinely invisible and unfocusable
+3. the DOM parent is unchanged before, during and after opening
+4. inherited theme, density and custom properties survive opening
+5. a surface inside <dialog open> and inside a modal dialog
+6. reopening during the exit transition
+7. a context menu at pointer coordinates
+8. the sheet scrim covers and intercepts the click
+```
+
+`demo/templates/popover-transport.html` is that pass, scored by the page. It
+loads no Actual JavaScript and measures the platform subset above, so it
+answers on `master` without checking the branch out. Scenarios 1–6 run
+unattended; 7 and 8 need a real gesture. It scores 8/8 on Chromium and
+reproduces the findings above, `::backdrop` included — so a deviation on WebKit
+is the engine, not the bench.
+
+### Result — gate passed
+
+```text
+Verified manually on:
+  iOS Safari 17.0 / iOS 17.0        8/8 passed
+  Safari 17.3 / macOS unrecorded    8/8 passed
+Date: 2026-09-04
+```
+
+iOS 17.0 is the bottom of the proposed floor, measured rather than inferred.
+The desktop score is the union of two page loads on one engine, the iOS score a
+single session at 390×745; a second iOS pass at 341×651 reproduced everything
+but scenario 7, whose assertion the bench has since corrected — see below.
+Safari freezes its macOS UA token at `10_15_7`, so the desktop host version is
+not recoverable from a report. macOS Safari 17.0–17.2 stay inferred, on the
+same WebKit that iOS 17.0 exercised.
+
+Scenario 7 ran through the synthetic fallback on both iOS passes: iOS fires no
+`contextmenu` from a long press, so that event path is unexercised on the port
+where it matters most, and the scenario attests placement only.
+
+Both ports report the same subset: the four runtime primitives and
+`selector(:popover-open)` present; `checkVisibility()`, `overlay`,
+`transition-behavior: allow-discrete` and `@starting-style` absent. That
+matches WebKit's published timeline — Popover in 17.0, the rest in 17.4 and
+17.5 — which is corroboration that the bench measures rather than guesses.
+
+Four results carry consequences:
+
+**Scenario 5 passes on both ports**, which is what makes the transport worth
+making mandatory: the native top layer solves on WebKit the problem that
+motivated `getSurfaceRoot()` in the first place, on a 390px phone included.
+
+**Scenario 2 passes on the fallback branch.** `checkVisibility()` does not
+exist below Safari 17.4, so `isElementVisible()` runs its `getClientRects()`
+branch at the floor — the branch that had never been exercised. It works, and
+it is load-bearing rather than dead.
+
+**`::backdrop` is weaker on WebKit, not stronger.** Author `pointer-events` on
+an open popover's backdrop still computes to `none`, the native backdrop still
+lets the pointer through, and an Actual scrim element still absorbs it,
+confirmed with a real tap. The one thing `::backdrop` did well on Chromium —
+resolving a custom property scoped to an ancestor of the panel — resolves to
+nothing on WebKit. The scrim stays an Actual element on both engines, and not
+by Chromium's accident.
+
+**An overflowing top-layer box is adjusted differently.** Asked to place a
+panel at a point that would push it past the right edge of a 341px viewport,
+iOS Safari 17.0 offset it by 11px; Chromium at the identical viewport and
+overflow offset it by 0. Not a gate: `surface.js` positions through floating's
+`shift` middleware with `shiftPadding: 4`, so it never asks for such a point
+and measures the rendered rect afterwards. The bench now picks a point that
+fits, so scenario 7 measures placement rather than the UA's correction.
+
+## Changelog framing for the raise
+
+State what stops working before what it buys, with versions named. Something
+along these lines:
+
+> **JavaScript browser floor raised** to Safari 17+, Firefox 125+ and
+> Chromium 116+. Interactive surfaces now use the native manual Popover
+> transport (`popover`, `showPopover()`, `hidePopover()`) instead of
+> physically reparenting author DOM. This preserves inherited themes, density
+> and application custom properties while leaving Actual's dismissal, focus
+> and positioning contracts unchanged.
+>
+> Browsers below this JavaScript floor no longer receive the supported full
+> Actual runtime. Core HTML/CSS degradation remains governed separately by the
+> Degraded tier.
+
+Not "Popover is now required": that reads as a dependency on the whole API
+family, when the requirement is the four primitives listed above.
+
+## Migration checklist
+
+For the release that raises Minimal. Items 4–7 are scaffolding built for a floor
+that will no longer exist; a gate outliving its reason is silent dead weight, so
+they belong here rather than being found later.
+
+1. WebKit verification — done, 8/8 on Safari 17.3, recorded above. Cleared.
+2. Raise Minimal to the required subset above. The justification is the defect
+   and the transparent migration, not a download count: npm figures conflate
+   CI, bots, caches and the author, and say nothing about the end browser.
+3. Delete the `Intermediate` tier. It is not merely less useful — with a new
+   Minimal above it on all three engines it is arithmetically absorbed, so its
+   features become floor-guaranteed and no information is lost.
+4. Reclassify those features (`color-mix()`, `oklch()/oklab()`, `dvh/svh/lvh`,
+   `scrollbar-gutter`, `scrollbar-width`, `scrollbar-color`) as Minimal
+   baseline and drop their `check-compat` entries.
+5. Remove the `@supports selector(:popover-open)` gates in `flyout.css` and
+   `tooltip.css`. Those only: the `@supports (transition-behavior:
+   allow-discrete)` gate and the `@starting-style` blocks stay, since neither
+   is in the floor — Safari 17.4 and 17.5.
+6. Remove the two `popover` entries from `check-compat`'s feature table.
+7. Remove the associated `compat-ok:` pragmas, and `hasPragma()` itself if
+   nothing else consumes it.
+8. Move `surface.js` to the manual transport, with no fallback branch. This
+   does not reach `isElementVisible()` in `focus.js`: `checkVisibility()` is
+   Safari 17.4, so its `getClientRects()` fallback is the branch that runs at
+   the floor and must stay.
+9. Drop `test.failing` from the reparenting tests in
+   `tests/browser/surface-inherited-context.test.js`, keeping the assertions.
+10. Update [surface-reparenting](surface-reparenting.md) from a known limitation
+   to resolved.
+
+Steps 8 and 9 are linked but not enforced. The `test.failing` markers guarantee
+that step 8 becomes unavoidable — they turn red as unexpected passes the moment
+the transport changes — but nothing forces step 9. The test file points at the
+note, and the note points back here; that is as far as documentation can close
+the loop.
+
+### Executed — where the checklist was wrong
+
+All ten items are done. Three needed correcting on contact, and the corrections
+are worth more than the items were.
+
+**Item 4 rested on a false premise.** Raising Minimal does not make a CSS
+capability baseline, because Minimal is the *JavaScript* floor: a Degraded
+browser runs no supported runtime and still receives every stylesheet, so CSS
+owes its fallbacks that far down. `check:compat` now states the Degraded floor
+and keeps the entries, relabelled — dropping them would have removed the only
+machine check that keeps those fallbacks honest. Two of the six features were
+also mistagged before the migration: `scrollbar-gutter`, `scrollbar-width` and
+`scrollbar-color` land in Safari 18.2, above every tier including Recommended,
+so they are `optional` rather than absorbed. The same relabelling moved `:has()`
+and `@container` to `minimal` — the new floor genuinely does absorb them, which
+the checklist missed because it enumerated the Intermediate tier's features
+instead of reading the new floor.
+
+**Item 7 cost more than it removed.** `hasPragma()` had no consumer left once
+the popover entries went, so it is gone — and with it five tests, including the
+one recording that prose must not excuse an optional structural use. The
+discovery is now a comment in `check-compat.js` naming the pragma to reinstate.
+Deleting a guard whose only proof of value was its own test is the trade this
+item asked for; it should be re-read before the next optional structural
+capability arrives.
+
+**Item 8 left one author-facing decision open.** The POC preserved an author's
+own `popover` value and only defaulted a missing one. `prepareSurface()` now
+writes `manual` unconditionally: any other mode hands the UA a dismissal policy,
+and native light dismiss closes on outside clicks only — which silently defeats
+`data-flyout-auto-close="false"`. The old `[popover]` conflict warning had
+caught that case; overwriting the attribute is what replaces it.
+
+## What was deliberately left out
+
+Not attempted, and not because it looked hard:
+
+- **`popover="auto"`.** It cannot express `data-flyout-auto-close`, whose
+  default closes on an inside click; native light-dismiss closes on outside
+  clicks only, and `false` is inexpressible altogether. Adopting it would be a
+  behavior change to the component, not a transport swap.
+- **Nested surfaces.** `openSurface()` closes every other open surface in the
+  document; the runtime is strictly flat and the transport change does not
+  alter that. Nesting is a separate feature decision, and the choice between
+  extending Actual's own stack and adopting the native one is functional before
+  it is technical.
+- **`popover="hint"`, interest invokers, CSS anchor positioning.** Watch.
+- **Further deletion for its own sake.** The branch's value is that it changes
+  the transport and nothing else. Broadening it would cost exactly the property
+  that makes it usable as a migration.

package/docs/design-notes/surface-reparenting.md

@@ -0,0 +1,131 @@
+# Surface reparenting broke inherited presentation context
+
+Resolved. The record is kept because the defect had no generic repair, three of
+the obvious ones look right and are wrong, and the transport that fixed it is
+the reason the JavaScript floor sits where it does.
+
+## What used to happen
+
+`surface.js` moved an open surface out of its place in the document:
+
+```text
+getSurfaceRoot()   → nearest <dialog>, else body
+mountSurface()     → root.append(panel)
+restoreSurface()   → put it back once the exit transition ends
+```
+
+The move existed for good reasons — it escaped `overflow` clipping on any
+ancestor and sidestepped `z-index` stacking. But it also took the panel out of
+every scope that reached it *by inheritance*. The panel was styled by one set of
+ancestors while closed, and by a different set from the moment it became
+visible.
+
+Actual leans on inheritance deliberately: theme islands, density, `.inverted`,
+and the custom properties an application scopes to its own containers all
+travel that way. So this was not one bug about themes. It was the same bug in as
+many forms as there are inherited contexts.
+
+## Measured
+
+Chrome, one `.flyout` per scope, values read off the panel before and after the
+click that opens it:
+
+| Scope                     | Closed                                   | Open                 |
+| ------------------------- | ---------------------------------------- | -------------------- |
+| `[data-theme="dark"]`     | `background: rgb(30, 26, 35)`            | `rgb(255, 255, 255)` |
+| `.sm`                     | `--control-size: 2rem`                   | `2.375rem`           |
+| `.inverted`               | `--ui-fg: light-dark(hsl(0 0% 100%), …)` | *(unset)*            |
+| app-scoped `--app-accent` | `rgb(1, 2, 3)`                           | *(unset)*            |
+| `.sm` inside a `<dialog>` | `--control-size: 2rem`                   | `2.375rem`           |
+
+Every context broke. Three consequences were worth stating plainly:
+
+- The theme case was visible, not theoretical: a flyout inside a dark island
+  turned light at the moment it opened.
+- The density case was measurable: menu rows rendered 38px instead of the 32px
+  the scope asked for.
+- The dialog case showed the `getSurfaceRoot()` special case did not help. The
+  panel did land inside the dialog, and still lost any scope sitting between
+  that dialog and its trigger. Choosing a nearer root loses less context; it
+  does not preserve it.
+
+`tests/browser/surface-inherited-context.test.js` holds those assertions and
+now passes against the shipped transport.
+
+## Why the obvious repairs are wrong
+
+Still wrong, and still tempting — this section is the reason the note is kept.
+
+**Copying `data-theme` onto the moved panel.** Fixes the one symptom that was
+noticed and leaves the other four broken. It also turns an inherited contract
+into an enumerated one, so every future scope has to be added to a list.
+
+**Snapshotting custom properties before the move.** There is no bounded set to
+snapshot — an application's own hooks are unknowable by definition, and
+`getComputedStyle` cannot enumerate inherited custom properties portably. It
+would also freeze values that should stay live.
+
+**Mounting to a nearer root.** The dialog row above is the experiment: it
+reduces the damage without addressing the cause.
+
+The cause was that the panel was moved at all. The repair is a transport that
+promotes the element without relocating it.
+
+## The repair, as shipped
+
+A native popover renders in the top layer while staying exactly where the
+author put it in the DOM. That removed the reason to reparent, and with it the
+whole mechanism:
+
+```text
+mountedSurfaces
+getSurfaceRoot()
+mountSurface()
+restoreSurface()
+```
+
+`popover="manual"` is the mode that fits: it supplies the top layer and nothing
+else, so `surface.js` keeps its dismissal policy, Escape ordering, focus
+restoration and placement orchestration unchanged. See
+[platform-alignment](platform-alignment.md) for the responsibility split, and
+[browser-support](browser-support.md) for the floor it requires.
+
+Adopting it behind a capability branch was rejected rather than overlooked: the
+fallback path *is* the defect, so a branch would have kept the bug alive for
+exactly the browsers it was written to serve. Raising the floor was the cheaper
+half of the decision.
+
+## The contract now
+
+> A surface managed by `surface.js` is presented in its trigger's context. A
+> scoped theme, density, or custom property reaches an anchored surface through
+> inheritance, open or closed.
+
+The two workarounds this note used to recommend — declaring the scope on `body`
+or on the panel itself — are no longer needed and can be removed from
+application code.
+
+`tooltip.js` reached the same contract later, and for the same reason: it moved
+an explicit tooltip to the dialog or the body on first hover, which is this
+defect in a second component. An explicit tooltip now stays where it was
+written and inherits accordingly.
+
+A generated tooltip (`data-tooltip="text"`) is deliberately outside the
+contract. Actual creates that element, so Actual places it, and it goes to
+document level rather than beside the trigger — a generated sibling would take
+`.join > :last-child` from a trigger that ends a group, since structural
+pseudo-classes are DOM-based and `position: fixed` does not exempt an element
+from them. The shorthand therefore promises no inheritance; the explicit form
+is the one to use when local context matters.
+
+## Experiment
+
+[popover-manual-poc](popover-manual-poc.md) records what the branch measured,
+what it refuted, and the checklist the migration followed. Read that before
+touching the transport again — it holds the negative results, `::backdrop`
+included.
+
+## Review trigger
+
+Revisit if a further inherited context is found to break, or if a transport
+that promotes without the top layer becomes available by another route.

package/docs/design-notes/tooltip-coordinate-space.md

@@ -0,0 +1,132 @@
+# Tooltip coordinate space, and what an unpositionable tip means
+
+Two changes to `tooltip.js`, both consequences of one question: what a floating
+element's coordinates are relative to, and what it means when there are none.
+
+## The lag
+
+Scrolling is asynchronous. The compositor can move the page before any script
+runs, so a `position: fixed` element written from JavaScript is always one frame
+behind the content it is attached to. `autoUpdate()` coalesces to a frame by
+design, which is correct for the work and still visible as a wobble on touch
+devices, where scrolling is driven off the main thread.
+
+`@lekoala/floating` 0.2.0 adds `coordinateSpace: "document"`: the same viewport
+measurement, written as `left`/`top` plus the page scroll, for an absolutely
+positioned box whose containing block is the initial one. The browser then
+carries the element with the page and there is nothing to correct.
+
+Two candidates were rejected before this one:
+
+- **Popper's `strategy: "absolute"`.** Relative to a *containing block*, not to
+  the reference — which means resolving the offset parent, its borders, its
+  scroll offsets, its transforms, and its own nested scrollers. That is the
+  machinery `floating` exists without.
+- **Repositioning synchronously on scroll** instead of at the next frame.
+  Cheaper to write, and it only shortens the lag; it cannot remove it, because
+  the scroll that moved the page never reached the main thread in time.
+
+## The containing block is not a problem here
+
+Document coordinates assume the initial containing block. A tip is an open
+popover, so it is in the top layer, where an absolutely positioned box resolves
+against the initial containing block whatever its ancestors do. Measured in
+Chrome, writing viewport point `(200, 300)` in document coordinates at
+`scrollY: 640` and reading the resulting rect back:
+
+| Ancestor of the tip  | Rect      |
+| -------------------- | --------- |
+| `position: relative` | `200,300` |
+| `transform`          | `200,300` |
+| `filter`             | `200,300` |
+| `contain: paint`     | `200,300` |
+| `dialog` (`show()`)  | `200,300` |
+| `dialog` (modal)     | `200,300` |
+
+So where the tip lives never enters into it, and the placement contract — an
+explicit tip stays where the author wrote it, a generated one goes to the
+dialog subtree or the body — is untouched.
+
+## The trigger is the problem
+
+Document coordinates are only right while the *trigger* scrolls with the page.
+Against a trigger that does not, the browser carries the tip away on every
+scroll and the next frame snaps it back: a worse artefact than the lag it
+removes, and a real one — `.fab`, `.status-bar` and `.drawer` are fixed,
+`.navbar`, `.topbar`, `.app-nav` and `.form-actions` are sticky.
+
+`isViewportAnchored()` therefore walks up from the trigger for a computed
+`fixed` or `sticky`, and separately asks for `dialog:modal, :popover-open`,
+which the walk cannot see: a modal dialog computes `position: absolute` and is
+laid out against the viewport by the top layer. Sticky counts even while
+unstuck, because nothing in the DOM changes when it becomes stuck.
+
+The modal case is the one worth naming, because a modal dialog does **not**
+stop the page from scrolling behind it — measured, wheel included. A trigger
+inside one is as viewport-anchored as a fixed bar, and keeps `position: fixed`.
+
+## The scrollable overflow case
+
+An absolutely positioned box in the top layer joins the document's scrollable
+overflow; a fixed one never does. The scrollable height becomes the greater of
+the content's own bottom and the tip's, and the threshold is exact: walking a
+20px tip down a 2000px document in Chrome, `scrollHeight` reads 2000 for every
+tip bottom through 2000, and the tip's own bottom from 2001 on.
+
+A tip past the end of the content therefore raises the scroll maximum while it
+is up, and hiding it clamps back any position only that tip made reachable —
+the page appears to jump upwards.
+
+Placement is what prevents this, not anything in `tooltip.js`. Flip and shift
+put the tip inside the viewport, which at any scroll position is inside the
+document, so only overflow the engine explicitly accepts — a tip it could not
+fit anywhere — reaches past the end of the content. Nor does the demote and
+promote path add a case: the coordinates are a document point, so a tip that
+was inside the document when it went down is still inside it when it comes
+back up, exit fade included.
+
+It is a failure mode to test for, then, not a standing cost of document
+coordinates. If the page ever does jump, `documentElement.scrollHeight` across
+a show and a hide separates this from everything else that moves a page: it
+moves with the tip here, and holds steady for anything else.
+
+## `false` is a geometry answer
+
+`reposition()` returns `false` when it cannot place the element, an anchor
+outside the boundary included. `tooltip.js` used to read that as the end of the
+interaction and call `hideTip()`, which stopped position tracking.
+
+On a touch device that loses the tooltip for good: tap a trigger, it takes
+focus and the tip appears; scroll the trigger past the boundary and the tip is
+torn down; scroll back and nothing is watching any more. Tapping again does not
+help either — the trigger is already focused, so no `focusin` fires, and a
+repeat tap on the same element fires no `mouseover`.
+
+So the runtime now keeps two states. `wanted` is what the interaction asks for
+and only `hideTip()` clears it; `visible` is what is promoted. An
+unpositionable tip is demoted and stays tracked, and the next tick that can
+place it brings it back up.
+
+`floating` was deliberately left out of this: no `{ positioned, reason }`
+return, no option. Its README already documents the pattern — a failed
+positioning may be temporary without `autoUpdate()` being stopped.
+
+## Surfaces share geometry, not lifecycle
+
+Element-anchored surfaces use the same coupled coordinate and CSS position mode
+as tooltips. Point-positioned surfaces stay fixed because their `x` and `y` are
+client coordinates. A nested scroll container remains a separate boundary:
+document coordinates move natively with page scroll, while container scroll
+still waits for `autoUpdate()` to correct the placement.
+
+A surface that fits inside its boundary must not create scrollable overflow
+merely because it uses document coordinates. This is not a guarantee for an
+arbitrarily large custom surface: the positioner deliberately accepts overflow
+when no placement can physically contain it.
+
+`surface.js` still closes on `false`, and that stays a separate decision. A
+flyout close restores focus, fires an event and releases an Escape entry;
+hiding one while its trigger is off-boundary would leave a panel the user
+cannot see holding all three. The prerequisite named in
+[css-anchor](css-anchor.md) — "an out-of-view surface hides instead of closing"
+— is a component decision, and it has been taken for tooltips only.

package/docs/design-notes/widget-primitives.md

@@ -8,8 +8,8 @@ The JS runtime doubles as a primitive kit for building custom widgets.
 | ---------------------------------- | ------------- | --------------------------- |
 | Discovery, lifecycle, cleanup      | `enhance`     | `actual-css/js/enhance`     |
 | Per-document LIFO Escape dismissal | `escape`      | `actual-css/js/escape`      |
-| Positioning, flip and shift        | `floating`    | `actual-css/js/floating`    |
-| Open/close, sheet, backdrop, focus | `surface`     | `actual-css/js/surface`     |
+| Positioning, flip and shift        | `floating`    | `@lekoala/floating`         |
+| Open/close, dismissal, focus       | `surface`     | `actual-css/js/surface`     |
 | Directional item lookup            | `keys`        | `actual-css/js/keys`        |
 | Menu-item vocabulary               | `menu`        | `actual-css/js/menu`        |
 | Focusable lookup, visibility       | `focus`       | `actual-css/js/focus`       |
@@ -22,9 +22,9 @@ The JS runtime doubles as a primitive kit for building custom widgets.
 
 The named exports each module carries:
 
-- `enhance` — `enhance`, `registerEnhancement`
+- `enhance` — `enhance`, `registerEnhancement`, `applyEnhancement`
 - `escape` — `registerEscapeDismissal`
-- `floating` — `track`, `reposition`, `repositionAt`, plus
+- `floating` — `autoUpdate`, `reposition`, `repositionAt`, plus
   `--available-height` and `data-placement`
 - `keys` — `itemForKey`, `firstItem`, `lastItem`, `nextItem`, with edge,
   wrapping and RTL handling
@@ -89,12 +89,12 @@ an inline autocomplete that should survive an outside click).
 
 ```
 enhance
-surface   (Escape, outside click, focus restore, sheet mode)
+surface   (Escape, outside click, focus restore)
 floating
 keys
 ```
 
-Less code. Inherits the runtime's dismissal semantics and mobile sheet. Use for
+Less code. Inherits the runtime's dismissal semantics. Use for
 anything that behaves like a popup.
 
 > A `[role="listbox"]` surface with `[role="option"]` children gets no key handling and
@@ -130,6 +130,9 @@ state to style or ignore.
 
 ## Honest gaps
 
+- No nested surfaces — one Actual surface is open per document, and opening one
+  closes the rest. A widget that needs a second level owns its own popup
+  (composition A above).
 - No typeahead helper — filter, debounce, render are author concerns.
 - No `aria-activedescendant` helper — the author manages the composite-widget pattern.
 - No virtual-list support.