actual-css 0.5.0 → 0.6.0

package/docs/pages/forms/joined-controls.md

@@ -6,10 +6,10 @@
 
 ## Class reference
 
-| Class         | Kind        | Description                                                                     |
-|---------------|-------------|---------------------------------------------------------------------------------|
-| `.join`       | Composition | Visually joins adjacent controls into a single unit.                            |
-| `.join-addon` | Composition | Static prefix/suffix content such as currency symbols, units, or protocol text. |
+| Class         | Kind        | Description                                 |
+| ------------- | ----------- | ------------------------------------------- |
+| `.join`       | Composition | Joins adjacent controls into a single unit. |
+| `.join-addon` | Composition | Static prefix or suffix content.            |
 
 Add `.join` to the wrapper that groups the controls. Use `.join-addon` for static prefix/suffix content such as currency symbols, units, or protocol text. Action buttons inside the group should use `.btn`. The wrapper should still carry `role="group"` with a label for accessibility.
 

package/docs/pages/forms/labels.md

@@ -4,11 +4,14 @@
 
 ## Class reference
 
-| Class            | Kind        | Description                                                                                  |
-|------------------|-------------|----------------------------------------------------------------------------------------------|
-| `.field`         | Composition | Field wrapper; canonical on `<label>` or `<div>`.                                            |
-| `.field-label`   | Composition | Label text, element-agnostic — works on `<span>`, a detached `<label for>`, or a `<legend>`. |
-| `.required-mark` | Composition | Visual required marker (`aria-hidden`) added inside a label.                                 |
+| Class            | Kind        | Description                                       |
+| ---------------- | ----------- | ------------------------------------------------- |
+| `.field`         | Composition | Field wrapper; canonical on `<label>` or `<div>`. |
+| `.field-label`   | Composition | Label text, element-agnostic.                     |
+| `.required-mark` | Composition | Visual required marker (`aria-hidden`).           |
+
+`.field-label` works on a `<span>`, on a detached `<label for>`, or on a
+`<legend>`. `.required-mark` goes inside a label.
 
 Use a **wrapped label** for simple hand-authored forms. The whole label area becomes the click target, there is no `id` noise, and the markup is harder to break.
 

package/docs/pages/forms/overview.md

@@ -9,27 +9,34 @@
 - Proper focus style that preserves keyboard navigation.
 - `.field-group` and `.choice` provide layout without depending on parent scope.
 - Customizable select is progressive enhancement only — the native select remains the baseline.
+- Searchable selects, tags and autocomplete are a JavaScript widget concern; theme an external combobox with Actual tokens — see the [combobox template](../../demo/templates/combobox.html).
 
 ## Class reference
 
-| Class           | Kind        | Description                                                                   |
-|-----------------|-------------|-------------------------------------------------------------------------------|
-| `.input`        | Component   | Text input; shares the text-control recipe with `.textarea` and `.select`.    |
-| `.textarea`     | Component   | Multi-line text control.                                                      |
-| `.select`       | Component   | Dropdown — native baseline with a CSS chevron and an opt-in enhanced picker.  |
-| `.check`        | Component   | Styled checkbox.                                                              |
-| `.radio`        | Component   | Styled radio button.                                                          |
-| `.switch`       | Component   | Toggle switch on a checkbox input with `role="switch"`.                       |
-| `.range`        | Component   | Native range slider with a theme-aware accent color.                          |
-| `.file`         | Component   | Native file input with a themed picker button.                                |
-| `.color`        | Component   | Native color picker in a control-sized box.                                   |
-| `.field`        | Composition | Field wrapper that works on `<label>` and `<div>`.                            |
-| `.field-label`  | Composition | Label text; element-agnostic — `<span>`, detached `<label>`, or `<legend>`.   |
-| `.field-help`   | Composition | Supporting helper text under a control.                                       |
-| `.field-error`  | Composition | Inline error message shown while the field is invalid.                        |
-| `.field-group`  | Composition | Grouped `<fieldset>` container with a tunable legend gutter.                  |
-| `.choice`       | Composition | Choice-label layout wrapping a `.check`, `.radio`, or `.switch`.              |
-| `.form-actions` | Composition | Class-only flex row that closes a form; works inside or outside the `<form>`. |
+| Class           | Kind        | Description                                   |
+| --------------- | ----------- | --------------------------------------------- |
+| `.input`        | Component   | Text input.                                   |
+| `.textarea`     | Component   | Multi-line text control.                      |
+| `.select`       | Component   | Dropdown, native baseline with a CSS chevron. |
+| `.check`        | Component   | Styled checkbox.                              |
+| `.radio`        | Component   | Styled radio button.                          |
+| `.switch`       | Component   | Toggle switch on a `role="switch"` checkbox.  |
+| `.range`        | Component   | Native range slider, theme-aware accent.      |
+| `.file`         | Component   | Native file input, themed picker button.      |
+| `.color`        | Component   | Native color picker in a control-sized box.   |
+| `.field`        | Composition | Field wrapper, on `<label>` or `<div>`.       |
+| `.field-label`  | Composition | Label text, element-agnostic.                 |
+| `.field-help`   | Composition | Supporting helper text under a control.       |
+| `.field-error`  | Composition | Inline error message, shown while invalid.    |
+| `.field-group`  | Composition | `<fieldset>` with a tunable legend gutter.    |
+| `.choice`       | Composition | Choice-label layout around an inline control. |
+| `.form-actions` | Composition | Class-only flex row that closes a form.       |
+
+`.input` shares the text-control recipe with `.textarea` and `.select`, and
+`.select` also has an opt-in enhanced picker. `.field-label` works on a
+`<span>`, a detached `<label>` or a `<legend>`. `.choice` wraps a `.check`,
+`.radio` or `.switch`, and `.form-actions` works inside or outside the
+`<form>`.
 
 ## Example form
 

package/docs/pages/forms/password.md

@@ -1,8 +1,9 @@
 # Password Toggle
 
 > A password field reveals its value through a linked button. The markup is a
-> plain command invoker; the behavior ships with the JS runtime
-> (`actual-css/js` or `actual-css/js/password`).
+> plain command invoker; the behavior ships with the full JS runtime
+> (`actual-css/js/full`) and can also be imported independently
+> (`actual-css/js/password`).
 
 Point a `button` at the input with `commandfor` and
 `command="--password-toggle"`. Use `.join` when the button should sit attached

package/docs/pages/forms/range.md

@@ -1,8 +1,11 @@
 # Range
 
-> Native range inputs with theme-aware accent color.
+> Native range input with a lightweight theme-aware custom skin.
 
-Core: native range, enhanced by `accent-color`. Optional richer skin may come later.
+`.range` keeps the native range control and its interaction semantics, while
+customizing the track, thumb, focus state, intents, and disabled state. The
+focus ring targets the thumb — the surface the user actually manipulates —
+rather than the CSS box.
 
 **Related terms:** slider, range input, scrubber.
 
@@ -13,7 +16,15 @@ Core: native range, enhanced by `accent-color`. Optional richer skin may come la
 </label>
 ```
 
+Actual deliberately does not emulate filled tracks, tick marks, value labels,
+or multi-thumb ranges. Those still require engine-specific pseudo-elements or a
+value duplicated out of the HTML into CSS. Prefer the platform as richer range
+styling becomes interoperable — see
+[Enhanced range controls](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/platform-alignment.md).
+
 ## CSS hooks
 
 - `--range-thumb-size` — thumb diameter.
 - `--range-track-height` — track thickness.
+- `--range-thumb-bg` — thumb color. Defaults to the local intent, then `--primary`.
+- `--range-track-bg` — track color.

package/docs/pages/forms/states-and-sizes.md

@@ -4,10 +4,12 @@
 
 ## Class reference
 
-| Class | Kind     | Description                                                                              |
-|-------|----------|------------------------------------------------------------------------------------------|
-| `.sm` | Modifier | Compact control height and spacing rhythm; sets `--control-size` to `--control-size-sm`. |
-| `.lg` | Modifier | Large control height and spacing rhythm; sets `--control-size` to `--control-size-lg`.   |
+| Class | Kind     | Description                                |
+| ----- | -------- | ------------------------------------------ |
+| `.sm` | Modifier | Compact control height and spacing rhythm. |
+| `.lg` | Modifier | Large control height and spacing rhythm.   |
+
+Each sets `--control-size` to `--control-size-sm` or `--control-size-lg`.
 
 Use `readonly` for text-like values that can still be focused, selected, and submitted. Use `disabled` for unavailable controls that should not receive focus or submit a value.
 

package/docs/pages/forms/validation.md

@@ -6,14 +6,18 @@
 
 ## Class reference
 
-| Class               | Kind        | Description                                                                     |
-|---------------------|-------------|---------------------------------------------------------------------------------|
-| `.field-error`      | Composition | Canonical inline error message; shown while the field is invalid.               |
-| `.field-help`       | Composition | Canonical helper text; carries supporting copy before and after validation.     |
-| `.field.danger`     | Modifier    | Manual invalid marking on the field wrapper.                                    |
-| `.needs-validation` | Modifier    | Opt-in class for the validation enhancer and `:user-invalid` styling.           |
-| `.was-validated`    | Modifier    | Added to the form by the enhancer after the first submit attempt.               |
-| `.status-bar`       | Component   | Optional status element that shows `data-validation-message` on invalid submit. |
+| Class               | Kind        | Description                                  |
+| ------------------- | ----------- | -------------------------------------------- |
+| `.field-error`      | Composition | Canonical inline error message.              |
+| `.field-help`       | Composition | Canonical helper text.                       |
+| `.field.danger`     | Modifier    | Manual invalid marking on the wrapper.       |
+| `.needs-validation` | Modifier    | Opt-in for the enhancer and `:user-invalid`. |
+| `.was-validated`    | Modifier    | Set by the enhancer after a submit attempt.  |
+| `.status-bar`       | Component   | Optional form-level status element.          |
+
+`.field-error` shows while the field is invalid; `.field-help` carries
+supporting copy before and after validation. `.status-bar` shows
+`data-validation-message` on an invalid submit.
 
 - `.field-error` is the canonical error message. It is wired to `aria-invalid="true"` via the input, so the visual border and the assistive-tech announcement move together.
 - `.field-help` is the canonical helper text. It carries supporting copy before and after validation.
@@ -49,7 +53,7 @@
 
 Native validation first; the enhancer only adds state and focus behavior.
 
-Actual CSS ships validation *styles*. Invalid fields are marked with `aria-invalid="true"` (or the manual `.field.danger` wrapper class). The default forms bundle imports `forms/validation.css`; custom builds may omit that file when validation styling is app-owned. A small enhancer (`actual-css/js/validation`), included in the default runtime (`actual-css/js`) and also importable on its own, prevents premature error display, marks invalid fields on blur and submit, focuses the first invalid field on submit, and supports a few custom rules. It is not a validation framework — server and AJAX validation stay in app code.
+Actual CSS ships validation *styles*. Invalid fields are marked with `aria-invalid="true"` (or the manual `.field.danger` wrapper class). The default forms bundle imports `forms/validation.css`; custom builds may omit that file when validation styling is app-owned. A small enhancer (`actual-css/js/validation`), included in the full runtime (`actual-css/js/full`) and also importable on its own, prevents premature error display, marks invalid fields on blur and submit, focuses the first invalid field on submit, and supports a few custom rules. It is not a validation framework — server and AJAX validation stay in app code.
 
 Opt in with the `.needs-validation` class. Importing the module registers the behavior; there is no init call.
 

package/docs/pages/foundations/tokens.md

@@ -247,6 +247,7 @@ Icons used by CSS-only controls are public tokens because users may need to repl
   --icon-chevron: url("data:image/svg+xml,...");
   --icon-check: url("data:image/svg+xml,...");
   --icon-close: url("data:image/svg+xml,...");
+  --icon-plus: url("data:image/svg+xml,...");
 }
 ```
 
@@ -275,12 +276,14 @@ Under `forced-colors: active`, `--backdrop-fill` maps to `Canvas`.
 
 A small z-index scale orders non-dialog overlays. Native `<dialog>` elements (modal, drawer) render on the platform top-layer, which has no numeric z-index and always paints above the page — they never compete with this scale.
 
-| Token         | Value | Used by                                                                           |
-|---------------|-------|-----------------------------------------------------------------------------------|
-| `--z-sticky`  | 10    | Sticky page chrome (`form-actions.sticky`, `topbar`).                             |
-| `--z-menu`    | 20    | Floating menus (`flyout`); `.surface-backdrop` sits at `calc(var(--z-menu) - 1)`. |
-| `--z-tooltip` | 50    | Tooltips.                                                                         |
-| `--z-status`  | 60    | `status-bar`.                                                                     |
+| Token         | Value | Used by                         |
+| ------------- | ----- | ------------------------------- |
+| `--z-sticky`  | 10    | `form-actions.sticky`, `topbar` |
+| `--z-menu`    | 20    | Floating menus (`flyout`)       |
+| `--z-tooltip` | 50    | Tooltips                        |
+| `--z-status`  | 60    | `status-bar`                    |
+
+`.surface-backdrop` sits just under the menus, at `calc(var(--z-menu) - 1)`.
 
 Stacking-context traps: a flyout or tooltip that is a DOM descendant of a dialog, or of a container with `transform`, `filter`, `contain`, `isolation`, or `will-change`, is confined to that ancestor's stacking context. Its z-index token only orders it against siblings within that context. When a dialog's top-layer clips a descendant flyout, move the flyout markup outside the dialog or use a portal/popover to escape the stacking context.
 

package/docs/pages/foundations/typography.md

@@ -66,7 +66,7 @@ documentation homepages) import it manually:
 The module exposes three size tokens and three composed classes. It is deliberately not the foundation: body text, app UI, and the default prose scale stay static.
 
 | Token             | Class           | Purpose                               |
-|-------------------|-----------------|---------------------------------------|
+| ----------------- | --------------- | ------------------------------------- |
 | `--fluid-display` | `.text-display` | Hero / display sizes.                 |
 | `--fluid-title`   | `.text-title`   | Section titles.                       |
 | `--fluid-lead`    | `.text-lead`    | Intro paragraphs on display surfaces. |

package/docs/pages/guides/bootstrap.md

@@ -43,7 +43,7 @@ Remove the compatibility mechanism when Bootstrap is gone. The public Actual API
 Many common Bootstrap components translate directly.
 
 | Bootstrap                  | Actual CSS              |
-|----------------------------|-------------------------|
+| -------------------------- | ----------------------- |
 | `.btn .btn-primary`        | `.btn .primary`         |
 | `.btn .btn-outline-danger` | `.btn .danger .outline` |
 | `.btn .btn-sm`             | `.btn .sm`              |
@@ -101,7 +101,7 @@ Actual:
 Common translations include:
 
 | Bootstrap                     | Actual CSS                     |
-|-------------------------------|--------------------------------|
+| ----------------------------- | ------------------------------ |
 | `.form-control` on an input   | `.input`                       |
 | `.form-control` on a textarea | `.textarea`                    |
 | `.form-select`                | `.select`                      |
@@ -213,7 +213,7 @@ Think in terms of the relationship between children rather than translating each
 Typical choices are:
 
 | Bootstrap pattern                          | Actual approach                            |
-|--------------------------------------------|--------------------------------------------|
+| ------------------------------------------ | ------------------------------------------ |
 | flex row that may wrap                     | `.cluster`                                 |
 | vertical flex stack                        | `.stack`                                   |
 | exact structural columns                   | `.grid-2`, `.grid-3`, `.grid-4`, `.grid-6` |

package/docs/pages/guides/introduction.md

@@ -140,7 +140,7 @@ internal design documents for contributors.
 Actual CSS is built around progressive enhancement.
 
 | Tier         | Firefox | Safari    | Chromium |
-|--------------|---------|-----------|----------|
+| ------------ | ------- | --------- | -------- |
 | Degraded     | 78+     | 14+       | 88+      |
 | **Minimal**  | **98+** | **15.4+** | **99+**  |
 | Intermediate | 121+    | 16+       | 106+     |

package/docs/pages/guides/modular-import.md

@@ -29,16 +29,27 @@ When an interactive state replaces the outline, it must preserve a visible focus
 
 ## Family manifests
 
-| Family           | Import                      | Contents                                                                                                                        |
-| ---------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| Core             | `actual-css/css`            | reset, tokens, theme, base, intents, variants, focus, print                                                                     |
-| Typography       | `actual-css/css/typography` | prose, overline, fluid                                                                                                          |
-| Layout           | `actual-css/css/layout`     | stack, cluster, center, frame, media, switcher, sidebar-layout, grid, scroller, scroll-snap, topbar, container-query, app-shell |
-| Forms            | `actual-css/css/forms`      | native control baseline                                                                                                         |
-| Forms (complete) | `actual-css/css/forms/all`  | base plus input-icon, switch, range, choice-card, custom-select, floating-field, otp                                            |
-| Components       | `actual-css/css/components` | buttons, surfaces, overlays, feedback, navigation, data and composed controls                                                   |
-| Effects          | `actual-css/css/effects`    | aura                                                                                                                            |
-| Utilities        | `actual-css/css/utilities`  | base and extra utilities                                                                                                        |
+Each family is one import. The contents are enumerations rather than table
+cells, so they read as a list:
+
+- **Core** — `actual-css/css`
+  reset, tokens, theme, base, intents, variants, focus, print
+- **Typography** — `actual-css/css/typography`
+  prose, overline, fluid
+- **Layout** — `actual-css/css/layout`
+  stack, cluster, center, frame, media, switcher, sidebar-layout, grid,
+  scroller, scroll-snap, topbar, container-query, app-shell
+- **Forms** — `actual-css/css/forms`
+  native control baseline
+- **Forms (complete)** — `actual-css/css/forms/all`
+  base plus input-icon, switch, range, choice-card, custom-select,
+  floating-field, otp
+- **Components** — `actual-css/css/components`
+  buttons, surfaces, overlays, feedback, navigation, data and composed controls
+- **Effects** — `actual-css/css/effects`
+  aura
+- **Utilities** — `actual-css/css/utilities`
+  base and extra utilities
 
 Individual modules can be imported through their domain path:
 

package/docs/pages/guides/progressive-enhancement.md

@@ -3,7 +3,7 @@
 > The optional JavaScript runtime that progressively enhances Actual's semantic markup — self-registering side-effect modules, the `enhance()` DOM lifecycle, stateless command routing, and the floating and surface contracts for custom widgets.
 
 Actual's JavaScript modules are optional. Importing `actual-css/js/full`
-registers the complete default runtime — every built-in enhancer, including
+registers the full runtime — every built-in enhancer, including
 validation and status. Importing `actual-css/js` registers only the enhancement
 manifest loader; importing a specific module registers only that behavior. The
 runtime does not require `DOMContentLoaded` or manual init calls, and it never
@@ -18,7 +18,7 @@ runtime evolves. The runtime assumes the modern platform primitives available
 across Minimal and ships no compatibility layer or polyfill.
 
 | Tier         | Firefox | Safari    | Chromium |
-|--------------|---------|-----------|----------|
+| ------------ | ------- | --------- | -------- |
 | Degraded     | 78+     | 14+       | 88+      |
 | **Minimal**  | **98+** | **15.4+** | **99+**  |
 | Intermediate | 121+    | 16+       | 106+     |
@@ -56,7 +56,7 @@ Modules are safe to import during SSR — registration is a no-op when there is
 DOM. The runtime remains active until the page unloads; there is no teardown
 handle, and cleanup happens per element when an element leaves the DOM.
 
-## The default runtime
+## The full runtime
 
 Loading `dist/actual.full.js` as a plain `<script>` (no `type="module"`, no
 bundler, no `import`) gets the full runtime. Static HTML that needs to trigger
@@ -74,22 +74,25 @@ example:
 </script>
 ```
 
-| Module                             | Behavior                                                                      |
-|------------------------------------|-------------------------------------------------------------------------------|
-| `actual-css/js/flyout`             | Trigger → panel surface: positioning, open/close, sheet mode (token `flyout`) |
-| `actual-css/js/context-menu`       | Context menus on `data-context-menu`                                          |
-| `actual-css/js/focus-group`        | Reusable roving-focus controller; no automatic discovery                      |
-| `actual-css/js/dialog`             | Native `<dialog>` behavior, focus management, dismissal                       |
-| `actual-css/js/dismiss`            | The generic `--dismiss` command                                               |
-| `actual-css/js/tab`                | Tab panels and arrow-key navigation (token `tabs`)                            |
-| `actual-css/js/tooltip`            | Tooltips on `data-tooltip`                                                    |
-| `actual-css/js/scrollspy`          | Scroll-driven nav highlighting (token `scrollspy`)                            |
-| `actual-css/js/filter`             | Input value filtering on `data-filter`                                        |
-| `actual-css/js/mask`               | Input masks on `data-mask`                                                    |
-| `actual-css/js/password`           | Password reveal toggle                                                        |
-| `actual-css/js/validation`         | Form validation (token `validation`)                                          |
-| `actual-css/js/status`             | Singleton status bar on `[data-status][role="status"]`                        |
-| `actual-css/js/enhancement-loader` | Declared enhancement manifests (`data-enhance-modules`, `Enhance-Modules`)    |
+| Module                             | Behavior                                                    |
+| ---------------------------------- | ----------------------------------------------------------- |
+| `actual-css/js/flyout`             | Trigger → panel positioning and open/close (token `flyout`) |
+| `actual-css/js/context-menu`       | Context menus on `data-context-menu`                        |
+| `actual-css/js/focus-group`        | Reusable roving-focus controller; no automatic discovery    |
+| `actual-css/js/dialog`             | Native `<dialog>` behavior, focus management, dismissal     |
+| `actual-css/js/dismiss`            | The generic `--dismiss` command                             |
+| `actual-css/js/tab`                | Tab panels and arrow-key navigation (token `tabs`)          |
+| `actual-css/js/tooltip`            | Tooltips on `data-tooltip`                                  |
+| `actual-css/js/scrollspy`          | Scroll-driven nav highlighting (token `scrollspy`)          |
+| `actual-css/js/filter`             | Input value filtering on `data-filter`                      |
+| `actual-css/js/mask`               | Input masks on `data-mask`                                  |
+| `actual-css/js/password`           | Password reveal toggle                                      |
+| `actual-css/js/validation`         | Form validation (token `validation`)                        |
+| `actual-css/js/status`             | Singleton status bar on `[data-status][role="status"]`      |
+| `actual-css/js/enhancement-loader` | Declared enhancement manifests                              |
+
+The enhancement loader reads its manifests from `data-enhance-modules` or the
+`Enhance-Modules` header.
 
 Use `actual-css/js/full` for demos, playgrounds, and smoke tests where one import
 enables every built-in behavior. Production apps can import individual modules
@@ -125,7 +128,7 @@ see the widget-primitives design note. Every primitive subpath is published in
 `package.json#exports`:
 
 | Subpath                  | Purpose                                                          |
-|--------------------------|------------------------------------------------------------------|
+| ------------------------ | ---------------------------------------------------------------- |
 | `actual-css/js/enhance`  | DOM lifecycle engine: `enhance()`, `registerEnhancement`, tokens |
 | `actual-css/js/escape`   | Per-document LIFO Escape dismissal stack                         |
 | `actual-css/js/events`   | The `actual:*` event name constants                              |
@@ -155,14 +158,16 @@ const stop = autoUpdate(float, () => {
 
 Options passed to `reposition()`:
 
-| Option         | Default          | Contract                                                         |
-|----------------|------------------|------------------------------------------------------------------|
-| `placement`    | `"bottom-start"` | Preferred side and alignment (`-start` / `-end`)                 |
-| `distance`     | `0`              | Gap between the reference and the floating element               |
-| `flip`         | `true`           | Flip to the opposite side when the preferred side is out of view |
-| `shift`        | `true`           | Shift along the main axis to stay within the boundary            |
-| `shiftPadding` | `4`              | Minimum space kept from the boundary                             |
-| `scope`        | viewport         | Boundary element for overflow decisions                          |
+| Option         | Default          | Contract                                    |
+| -------------- | ---------------- | ------------------------------------------- |
+| `placement`    | `"bottom-start"` | Preferred side and alignment                |
+| `distance`     | `0`              | Gap from the reference element              |
+| `flip`         | `true`           | Flip when the preferred side is out of view |
+| `shift`        | `true`           | Shift along the main axis to stay in bounds |
+| `shiftPadding` | `4`              | Minimum space kept from the boundary        |
+| `scope`        | viewport         | Boundary element for overflow decisions     |
+
+`placement` takes a `-start` or `-end` alignment suffix.
 
 `autoUpdate(element, callback)` batches scroll, resize, and element-resize
 callbacks per document and returns a stop handle; it does not keep a closed or
@@ -206,22 +211,33 @@ visible dismissable UI to the shared per-document Escape stack.
 widgets can veto or decorate opens, and context menus inject their own
 `source`/`restoreFocusTo` through it.
 
-| Option            | Default               | Contract                                                                                                                                                          |
-|-------------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `trigger`         | —                     | Anchoring element; also the focus-restore target by default                                                                                                       |
-| `source`          | —                     | Alternate anchor when there is no trigger                                                                                                                         |
-| `x`, `y`          | —                     | Position at a fixed viewport point instead of an anchor (context menus)                                                                                           |
-| `placement`       | `"bottom-start"`      | Preferred placement                                                                                                                                               |
-| `distance`        | `4`                   | Gap between anchor and surface                                                                                                                                    |
-| `flip`            | `true`                | Flip when the preferred side is out of view                                                                                                                       |
-| `shift`           | `true`                | Shift to stay within the boundary                                                                                                                                 |
-| `shiftPadding`    | `4`                   | Minimum space kept from the boundary                                                                                                                              |
-| `scope`           | viewport              | Boundary element                                                                                                                                                  |
-| `mobile`          | `"auto"`              | `"auto"`, `"sheet"`, `"none"`, or `"anchored"` sheet behavior                                                                                                     |
-| `breakpoint`      | `768`                 | Max viewport width for an automatic sheet                                                                                                                         |
-| `autoClose`       | `"outside"`           | `"true"` closes for inside and outside clicks; `"inside"` and `"outside"` limit the side; `"false"` disables automatic click closing. Invalid values use `"true"` |
-| `dismissOnScroll` | `false`               | Close when scrolling outside the surface follows a new user input; opening/focus scroll is ignored                                                                |
-| `restoreFocusTo`  | `trigger` or `source` | Element focused on close                                                                                                                                          |
+| Option            | Default          | Contract                                    |
+| ----------------- | ---------------- | ------------------------------------------- |
+| `trigger`         | —                | Anchoring element, and focus-restore target |
+| `source`          | —                | Alternate anchor when there is no trigger   |
+| `x`, `y`          | —                | Position at a fixed viewport point          |
+| `placement`       | `"bottom-start"` | Preferred placement                         |
+| `distance`        | `4`              | Gap between anchor and surface              |
+| `flip`            | `true`           | Flip when the preferred side is hidden      |
+| `shift`           | `true`           | Shift to stay within the boundary           |
+| `shiftPadding`    | `4`              | Minimum space kept from the boundary        |
+| `scope`           | viewport         | Boundary element                            |
+| `mobile`          | `"auto"`         | Sheet behavior                              |
+| `breakpoint`      | `768`            | Max viewport width for an automatic sheet   |
+| `autoClose`       | `"outside"`      | Which clicks close the surface              |
+| `dismissOnScroll` | `false`          | Close on a scroll the user just started     |
+| `restoreFocusTo`  | `trigger`        | Element focused on close                    |
+
+`x`, `y` replace the anchor entirely, which is what a context menu needs.
+`mobile` takes `"auto"`, `"sheet"`, `"none"` or `"anchored"`.
+
+`autoClose` takes `"true"` to close on inside and outside clicks, `"inside"` or
+`"outside"` to limit it to one side, and `"false"` to disable automatic click
+closing; an invalid value reads as `"true"`.
+
+`dismissOnScroll` only fires when the scroll follows a new user input — the
+scroll that opening or focusing causes is ignored. `restoreFocusTo` falls back
+to `source` when there is no `trigger`.
 
 The click policy belongs to the surface rather than to a particular menu
 anatomy. The generic primitive defaults to outside-click dismissal; flyout and
@@ -242,14 +258,18 @@ The runtime dispatches a small set of public `actual:*` events. All are
 listenable on the document; cancelable events veto the associated action when
 `preventDefault()` is called.
 
-| Event                  | Dispatch                                   | Contract                                                                                       |
-|------------------------|--------------------------------------------|------------------------------------------------------------------------------------------------|
-| `actual:surface-open`  | `openSurface()`, before a surface opens    | Cancelable. `detail: { surface, options }`                                                     |
-| `actual:context-menu`  | context-menu, before its menu opens        | Cancelable. `detail: { menu, context, origin, trigger }`                                       |
-| `actual:status`        | status module, or any code                 | Show or clear the status bar. `detail: { message, intent, duration }`; omit `message` to clear |
-| `actual:invalid`       | validation, after a submit was blocked     | `detail: { form, firstInvalid, message }`                                                      |
-| `actual:dialog-cancel` | dialog, before native cancel close         | Cancelable. `detail: { dialog, sourceEvent }`                                                  |
-| `actual:dismiss`       | `--dismiss` command, after hiding a target | `detail: { trigger }`                                                                          |
+| Event                  | Dispatch                       | `detail`                             |
+| ---------------------- | ------------------------------ | ------------------------------------ |
+| `actual:surface-open`  | before a surface opens         | `{ surface, options }`               |
+| `actual:context-menu`  | before a context menu opens    | `{ menu, context, origin, trigger }` |
+| `actual:status`        | status module, or any code     | `{ message, intent, duration }`      |
+| `actual:invalid`       | after a submit was blocked     | `{ form, firstInvalid, message }`    |
+| `actual:dialog-cancel` | before a native cancel close   | `{ dialog, sourceEvent }`            |
+| `actual:dismiss`       | after `--dismiss` hid a target | `{ trigger }`                        |
+
+`actual:surface-open`, `actual:context-menu` and `actual:dialog-cancel` are
+cancelable. `actual:status` both shows and clears the status bar — omit
+`message` to clear it.
 
 ## Extending the runtime
 
@@ -388,7 +408,8 @@ import { loadEnhancement, loadEnhancements, loadResponse } from "actual-css/js/e
 
 await loadEnhancements(); // every manifest block in the document
 await loadEnhancement("autosubmit", "/js/autosubmit.js");
-await loadResponse(fetch("/...").then((r) => r)); // Enhance-Modules header
+const response = await fetch("/...");
+await loadResponse(response); // Enhance-Modules header
 ```
 
 The `Enhance-Modules` HTTP header carries the same JSON object. Loaded modules
@@ -638,7 +659,7 @@ enhance({
 
 ## Form validation
 
-`actual-css/js/validation` is part of the default runtime and also importable on
+`actual-css/js/validation` is part of the full runtime and also importable on
 its own — it is an enhancer, not a validation framework. Forms opt in with the
 `data-enhance="validation"` token (`.needs-validation` is a presentation class
 for CSS-only `:user-invalid` feedback and does not by itself register the

package/docs/pages/guides/tailwind.md

@@ -205,7 +205,7 @@ Actual does not prohibit media queries. It simply does not encode every media qu
 ## Utility translation guide
 
 | Tailwind usage                       | Actual approach                                   |
-|--------------------------------------|---------------------------------------------------|
+| ------------------------------------ | ------------------------------------------------- |
 | `flex flex-col gap-*`                | `.stack`                                          |
 | `flex flex-wrap items-center gap-*`  | `.cluster`                                        |
 | `grid grid-cols-*`                   | `.grid`, `.grid-2`, `.grid-3`, etc.               |
@@ -407,7 +407,7 @@ Do not remove Tailwind from the build until migrated screens no longer depend on
 ## Where migration is genuinely harder
 
 | Existing Tailwind usage                            | Migration cost |
-|----------------------------------------------------|----------------|
+| -------------------------------------------------- | -------------- |
 | buttons, badges, alerts, forms                     | low            |
 | repeated card/panel patterns                       | low            |
 | basic flex/grid composition                        | low to medium  |

package/docs/pages/layout/app-shell.md

@@ -1,11 +1,11 @@
 # App Shell
 
-Full-height, single-column document flow. Despite its historical name, this is
-the general shell for ordinary pages as well as simple applications.
+Full-height, single-column document flow. Use it as the outer shell for ordinary pages,
+simple applications, and other layouts that need a header / main / footer structure spanning the viewport.
 
 Header and footer are document landmarks, not required layout classes.
-Use semantic elements by default. `.app-shell` already supplies the outer
-column, so do not add a `.stack` solely to arrange the page landmarks.
+Use semantic elements by default. .app-shell already supplies the outer column,
+so do not add a .stack solely to arrange the page landmarks.
 
 ```html demo
 <body class="app-shell">

package/docs/pages/layout/choosing.md

@@ -5,10 +5,14 @@ number of children visible in one mockup.
 
 ## Page and application shells
 
-| Situation | Recipe |
-|---|---|
-| Public, marketing, editorial, or normally scrolling page | Semantic landmarks; optionally `.app-shell`, with `.navbar` for site navigation |
-| Persistent topbar + independently scrolling main + bottom-to-side primary navigation | `.app-layout` with its exact direct-child contract |
+| Situation                              | Recipe                                      |
+| -------------------------------------- | ------------------------------------------- |
+| A normally scrolling page              | Semantic landmarks, optionally `.app-shell` |
+| Topbar + scrolling main + adaptive nav | `.app-layout`                               |
+
+The first covers public, marketing and editorial pages; add `.navbar` for site
+navigation. The second is `.app-layout` with its exact direct-child contract,
+where the primary navigation moves from bottom to side.
 
 Do not choose `.app-layout` from the word "app" or from the presence of a
 header. Its viewport-sized grid, hidden shell overflow, internal main scroll,
@@ -19,11 +23,11 @@ below.
 ## Content relationships
 
 | Situation                                                    | Primitive         |
-|--------------------------------------------------------------|-------------------|
+| ------------------------------------------------------------ | ----------------- |
 | Vertical flow                                                | `.stack`          |
 | Inline actions, tags, or navigation that may wrap            | `.cluster`        |
 | Responsive collection; an incomplete final row is acceptable | `.grid`           |
-| Known structural density, at most N columns                 | `.grid-N`         |
+| Known structural density, at most N columns                  | `.grid-N`         |
 | Peer regions that must switch together                       | `.switcher`       |
 | Main content followed by a secondary region                  | `.sidebar-layout` |
 | Fixed media followed by flexible content                     | `.media`          |