actual-css 0.6.0 → 0.7.0

package/docs/design-notes/browser-support.md

@@ -23,6 +23,30 @@ Degraded browsers may still run some JavaScript successfully, but that
 behavior is not tested, documented as supported, or preserved when the
 runtime evolves.
 
+### Native Popover and the tiers
+
+Popover is not part of any Actual tier's guarantee below Recommended. It is a
+capability, not a browser generation: the core lifecycle landed around
+Chromium 116, Firefox 125 and Safari 17, which clears Recommended but sits
+above both Minimal and Intermediate on every engine.
+
+| Actual tier  | Core native Popover guaranteed | Recommended lifecycle owner     |
+| ------------ | ------------------------------ | ------------------------------- |
+| Degraded     | no                             | HTML/CSS fallback only          |
+| Minimal      | no                             | `surface.js`                    |
+| Intermediate | no                             | `surface.js`                    |
+| Recommended  | yes, core lifecycle            | native Popover, or `surface.js` |
+
+"Core lifecycle" means `popover="auto"`/`"manual"`, `popovertarget`,
+`showPopover`/`hidePopover` and `:popover-open` — not the entire Popover API.
+`popover="hint"` and interest invokers are much newer and are not covered at
+any tier. Safari coverage here is read as the desktop engine; some iOS versions
+through 18.2 still report partial support for parts of the API, so an
+application targeting iOS should verify the specific pieces it relies on.
+
+Actual's presentation classes compose with either lifecycle from Recommended
+up. The runtime itself depends on Popover at no tier.
+
 ## JavaScript philosophy
 
 > The Degraded tier exists primarily to preserve useful HTML and CSS on older
@@ -83,20 +107,21 @@ The tiers above are Actual's own contract. The table below tracks the Web
 Platform Baseline of the individual CSS features the framework uses; it is a
 different notion from an Actual tier.
 
-| Feature area                          | Baseline      | Progressive enhancement        |
-| ------------------------------------- | ------------- | ------------------------------ |
-| Layout (flex, grid, position)         | Baseline 2023 | —                              |
-| CSS custom properties                 | Baseline 2023 | —                              |
-| `:has()`                              | Baseline 2023 | —                              |
-| `<dialog>` element                    | Baseline 2023 | —                              |
-| `color-mix()`                         | Baseline 2023 | Fallback flat color            |
-| `light-dark()`                        | 2024+         | Manual theme override          |
-| `:user-invalid`                       | 2024+         | `[aria-invalid]` attribute     |
-| `transition-behavior: allow-discrete` | 2024+         | Native dialog open/close       |
-| `appearance: base-select`             | 2024+         | Native `<select>`              |
-| `@starting-style`                     | 2024+         | Instant appearance             |
-| View Transition API                   | 2024+         | Dialog open/close transition   |
-| CSS Anchor Positioning                | Future        | JS positioning (`floating.js`) |
+| Feature area                          | Baseline      | Progressive enhancement              |
+| ------------------------------------- | ------------- | ------------------------------------ |
+| Layout (flex, grid, position)         | Baseline 2023 | —                                    |
+| CSS custom properties                 | Baseline 2023 | —                                    |
+| `:has()`                              | Baseline 2023 | —                                    |
+| `<dialog>` element                    | Baseline 2023 | —                                    |
+| `color-mix()`                         | Baseline 2023 | Fallback flat color                  |
+| `light-dark()`                        | 2024+         | Manual theme override                |
+| `:user-invalid`                       | 2024+         | `[aria-invalid]` attribute           |
+| `transition-behavior: allow-discrete` | 2024+         | Native dialog open/close             |
+| `appearance: base-select`             | 2024+         | Native `<select>`                    |
+| `@starting-style`                     | 2024+         | Instant appearance                   |
+| View Transition API                   | 2024+         | Dialog open/close transition         |
+| Popover API (core)                    | Baseline 2025 | `surface.js` lifecycle               |
+| CSS Anchor Positioning                | Future        | JS positioning (`@lekoala/floating`) |
 
 Core layout and visual tokens work on all Baseline 2023 browsers. Features marked
 2024+ are gated with `@supports` or degrade gracefully through fallback values.

package/docs/design-notes/css-anchor.md

@@ -2,7 +2,7 @@
 
 ## Context
 
-Currently, the positioning logic for tooltips, flyouts, and context menus is handled by a custom JavaScript engine (in `floating.js`). This engine computes absolute coordinates, handles viewport boundaries, and applies "flip" and "shift" heuristics to prevent overflow.
+Currently, the positioning logic for tooltips, flyouts, and context menus is handled by the `@lekoala/floating` JavaScript dependency. This engine computes fixed coordinates, handles viewport boundaries, and applies "flip" and "shift" heuristics to prevent overflow.
 
 As of mid-2024, modern browsers started supporting the **CSS Anchor Positioning API**, which delegates this heavy mathematical lifting directly to the browser's layout engine.
 

package/docs/design-notes/platform-alignment.md

@@ -138,6 +138,57 @@ Actual class + native HTML
 
 rather than replacing one framework API with another.
 
+## Surface responsibility split
+
+Anchored surfaces are the clearest case where the platform is absorbing one
+responsibility at a time rather than a whole widget. Keeping the axes named
+separately is what lets each be replaced on its own schedule:
+
+```text
+Popover            = where the surface lives
+floating           = where it is placed
+surface.js         = when and how it opens
+flyout / tooltip   = what it looks like
+menu               = how its content behaves
+```
+
+The value of the split is that each line can change owner independently.
+Popover can take over the top layer without touching placement. Anchor
+positioning could later take over placement without touching lifecycle — though
+not yet, because the current positioner also reports *placement validity*, which
+the lifecycle uses to close a surface whose anchor has left the viewport, and
+declarative CSS positioning offers no equivalent signal.
+
+### Ceding the properties a capability is expressed through
+
+Keeping presentation and behavior separate is not enough on its own, because
+CSS expresses some behavior *as* presentation.
+
+> A presentation class that composes with `popover` may own its visible display
+> type, but must not override the platform's hidden-state display.
+
+`.flyout { display: grid }` is entirely legitimate. The problem is that the UA
+closes a popover with `display: none`, and an author declaration beats the UA
+origin whatever the specificity — so that legitimate choice silently leaves a
+closed popover painted on screen. The class was not implementing the lifecycle;
+it was overriding the property the lifecycle is written in.
+
+The general rule, then:
+
+> A class that is advertised as composing with a platform capability must cede
+> the properties that capability uses to express itself, for the states the
+> platform owns.
+
+This is checkable rather than aspirational: any Actual class that carries a
+`[popover]` reset must also restore `display` for `:not(:popover-open)`.
+
+The corresponding trap is adopting a capability in a way that adds an axis
+instead of replacing one. A second surface transport living alongside the
+existing one would leave the DOM-reparenting code in place while doubling the
+behavior matrix, which is the opposite of the deletion this note asks for. The
+acceptance criterion for moving Actual’s own surfaces onto the top layer is
+therefore concrete: the change should remove more surface code than it adds.
+
 ## Prefer capabilities over browser generations
 
 New platform features should not automatically raise Actual's Minimal browser floor.

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

@@ -0,0 +1,248 @@
+# 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, and the branch demonstrates it. What blocks shipping is not the
+architecture; it is the browser contract. 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
+
+Every measurement in this note was taken on Chromium — the browser test harness
+hardcodes `backend: "chrome"`. The floor's most notable step is Safari 17, so
+the transport has no measured evidence on the engine the raise actually buys.
+This is the one open technical gate on the migration, and the only item on the
+checklist below that is not already demonstrated.
+
+A permanent WebKit matrix is disproportionate for a decision taken once. One
+manual pass on a real Safari at the chosen floor, recorded here, is enough:
+
+```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
+```
+
+Record the result in this section:
+
+```text
+Verified manually on:
+  Safari __._ / macOS __
+  iOS Safari __._ / iOS __      (if reachable)
+Date: ____-__-__
+Scenarios: _/8 passed
+```
+
+Scenario 5 deserves the most attention. On Chromium the native top layer solved
+cleanly the problem that motivated `getSurfaceRoot()` in the first place — a
+modal dialog inerts the rest of the document — and that result is what makes
+the transport worth making mandatory. Scenario 2 is the second: the old
+transport used `[hidden]`, which `isElementVisible()` reads in its first
+branch, and the migration shifts the guard onto `checkVisibility()` with
+`getClientRects()` behind it. Which branch actually runs depends on what the
+bottom of the new floor implements, and the third has never been exercised.
+
+## 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. Pass the WebKit verification above and record it. This is the go/no-go.
+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`.
+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.
+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.
+
+## 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,122 @@
+# Surface reparenting breaks inherited presentation context
+
+Known defect, present on the current Minimal floor. Tracked separately from
+Popover adoption on purpose: Popover is the likely cure, but the defect exists
+now and needs to be understood on its own terms.
+
+## What happens
+
+`surface.js` moves 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 exists for good reasons — it escapes `overflow` clipping on any
+ancestor and sidesteps `z-index` stacking. But it also takes the panel out of
+every scope that reached it *by inheritance*. The panel is styled by one set of
+ancestors while it is closed, and by a different set from the moment it becomes
+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 is not one bug about themes. It is 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 breaks. Three consequences are worth stating plainly:
+
+- The theme case is visible, not theoretical: a flyout inside a dark island
+  turns light at the moment it opens.
+- The density case is measurable: menu rows render 38px instead of the 32px the
+  scope asked for.
+- The dialog case shows the `getSurfaceRoot()` special case does not help. The
+  panel does land inside the dialog, and still loses any scope sitting between
+  that dialog and its trigger. Choosing a nearer root loses less context; it
+  does not preserve it.
+
+Locked by `tests/browser/surface-inherited-context.test.js`, whose assertions
+describe the contract Actual owes and are marked `test.failing` until the
+transport stops reparenting.
+
+## Why the obvious repairs are wrong
+
+**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 is that the panel is moved at all. The repair is a transport that
+promotes the element without relocating it.
+
+## The actual repair
+
+A native popover renders in the top layer while staying exactly where the
+author put it in the DOM. That removes 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
+the criteria a component must meet before adopting Popover, and
+[browser-support](browser-support.md) for which tier guarantees it.
+
+That change is gated on Popover being available across Minimal. It is not
+available there today, and adopting it behind a capability branch would keep
+the reparenting code alive for the fallback path — so the defect would remain
+for exactly the browsers the branch was written to serve.
+
+## Until then
+
+The honest interim position is a documented limitation, not a patch:
+
+> A surface managed by `surface.js` is presented in the document's own context,
+> not its trigger's. Do not rely on a scoped theme, density, or custom property
+> reaching an anchored surface through inheritance.
+
+Applications that need a scoped surface today have two workarounds, both of
+which put the scope where the panel lands rather than where it starts: declare
+the scope on an ancestor that survives the move (`body`, or the dialog), or
+carry the scope on the panel element itself.
+
+## Experiment
+
+A branch has demonstrated the repair without changing any other contract:
+[popover-manual-poc](popover-manual-poc.md) records what it measured, what it
+refuted, and the checklist for the release that adopts it. Read that before
+attempting this again — it also holds the negative results.
+
+## Review trigger
+
+Revisit when Popover is guaranteed across Minimal, when a further inherited
+context is found to break, or if a transport that preserves DOM ancestry
+becomes available by another route.

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

@@ -8,7 +8,7 @@ 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`    |
+| Positioning, flip and shift        | `floating`    | `@lekoala/floating`         |
 | Open/close, sheet, backdrop, focus | `surface`     | `actual-css/js/surface`     |
 | Directional item lookup            | `keys`        | `actual-css/js/keys`        |
 | Menu-item vocabulary               | `menu`        | `actual-css/js/menu`        |
@@ -24,7 +24,7 @@ The named exports each module carries:
 
 - `enhance` — `enhance`, `registerEnhancement`
 - `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

package/docs/pages/enhancements/flyout.md

@@ -74,8 +74,98 @@ placement strings supported by the floating runtime, such as `bottom-start`,
 
 Use `data-flyout-distance` for the trigger gap in pixels. The default is `4`.
 
-Use `data-flyout-auto-close` when the default click dismissal behavior is not
-right. Escape still follows the shared surface lifecycle.
+### Native popover lifecycle
+
+The `.flyout` presentation also composes with an element carrying `popover`.
+Actual neutralizes the native popover geometry that conflicts with anchored
+positioning and recognizes `:popover-open` as the visible state. The browser or
+another library may therefore own opening, dismissal, and focus without
+requiring `.is-open` or `[hidden]`.
+
+Actual CSS does not position that independently managed popover. Its positioner
+must write fixed viewport coordinates (and may write `--available-height` and
+`--surface-anchor-width`); the built-in `surface.js` runtime remains the full
+fallback when Actual owns the lifecycle too. A bare `[popover]` without
+`.flyout` or `.tooltip` keeps its platform appearance.
+
+Native Popover is optional and is not part of Actual's Minimal contract:
+browsers within the Minimal range may not support it. Actual gates its own
+geometry reset behind `@supports selector(:popover-open)`, so an engine without
+Popover no longer gets a mispositioned panel — but that engine also never hides
+or promotes a `popover` element, so nothing dismisses the panel either.
+
+When the lifecycle must work across the full Minimal range, use `surface.js`.
+Otherwise using the native lifecycle is an application support decision. The
+two are alternatives, not layers.
+
+#### Choose one lifecycle owner
+
+The Actual runtime path, where `surface.js` owns opening, dismissal, focus and
+placement:
+
+```html
+<div class="flyout-trigger">
+  <button data-enhance="flyout" aria-controls="actions" aria-expanded="false">
+    Actions
+  </button>
+
+  <ul id="actions" class="flyout menu" hidden>
+    <li><button class="menu-item" type="button">Rename</button></li>
+  </ul>
+</div>
+```
+
+The native path, where the browser owns the lifecycle and the top layer:
+
+```html
+<button popovertarget="actions">Actions</button>
+
+<ul id="actions" class="flyout menu" popover>
+  <li><button class="menu-item" type="button">Rename</button></li>
+</ul>
+```
+
+Do not combine them. `surface.js` opens a panel by clearing `[hidden]` and
+adding `.is-open`; it never calls `showPopover()`, so a `popover` element handed
+to the runtime has two owners and stays closed. The runtime logs a warning if it
+is asked to retain one.
+
+**The native path still needs a positioner.** `popovertarget` gives the panel an
+implicit anchor reference to its invoker, but it does not place it: Actual's
+geometry reset clears the UA's centering, so an unpositioned native flyout is
+laid out at its static position rather than under its trigger. Supply
+coordinates the same way `surface.js` does:
+
+```js
+import { autoUpdate, reposition } from "@lekoala/floating";
+
+const trigger = document.querySelector("[popovertarget='actions']");
+const panel = document.getElementById("actions");
+
+// One tracker at a time. autoUpdate returns its own cleanup; releasing it
+// before every state change keeps repeated opens from stacking trackers, and
+// stops the scroll/resize work as soon as the panel closes.
+let stop;
+
+panel.addEventListener("toggle", (event) => {
+  stop?.();
+  stop = undefined;
+  if (event.newState !== "open") return;
+
+  stop = autoUpdate(trigger, panel, () => {
+    reposition(trigger, panel, { placement: "bottom-start", distance: 4 });
+  });
+});
+```
+
+CSS Anchor Positioning will eventually cover the simple anchored case from the
+stylesheet alone, using that implicit anchor reference. It is still only
+partially supported and is not the documented recipe yet.
+
+**When `surface.js` owns the lifecycle**, use `data-flyout-auto-close` if the
+default click dismissal behavior is not right. Escape still follows the shared
+surface lifecycle. These options do not reach a natively managed
+`popover="auto"`, whose dismissal belongs to the browser.
 
 - `true` is the default. Clicks inside or outside close the flyout.
 - `inside` closes on inside clicks only.

package/docs/pages/enhancements/status-bar.md

@@ -15,6 +15,7 @@ runtime targets, empty by default.
 - Use it for transient status (`Saved.`, `Reconnected.`, `Copied.`). Critical, persistent, or actionable information belongs in `.alert`, inline messages, or dialogs.
 - Intents: `danger`, `success`, `warning`, `neutral`. The default (no intent) is a neutral dark pill.
 - On mobile, the runtime keeps the bar above the software keyboard by tracking `visualViewport` while a message is showing.
+- A message originating inside an open modal dialog temporarily moves the singleton bar into that dialog. This keeps it in the active top-layer and accessibility subtree; the bar returns to its original DOM position after its exit.
 
 Clearing is deferred, not immediate: the bar closes first and only empties its
 text and intent once the exit transition has finished, so it leaves at the size
@@ -77,6 +78,25 @@ document.dispatchEvent(new CustomEvent("actual:status", {
 }));
 ```
 
+Dispatch from the control or region that produced the feedback when it lives
+inside a dialog; bubbling lets the runtime infer the active surface:
+
+```js
+saveButton.dispatchEvent(new CustomEvent("actual:status", {
+  bubbles: true,
+  detail: { message: "Saved.", intent: "success" },
+}));
+```
+
+Code importing `status()` directly passes the same origin as `source`:
+
+```js
+status("Saved.", { intent: "success", source: saveButton });
+```
+
+Validation and declarative status commands propagate their source
+automatically.
+
 ## CSS hooks
 
 - `--status-bg` — bar background.