@zeyos/zx 2.2.1 → 3.0.0

package/CHANGELOG.md

@@ -8,6 +8,203 @@ and friends remain the complete record.
 
 ## Unreleased
 
+## 3.0.0 — 2026-08-24
+
+### Added
+
+- **Xenon application shell components.** `Launcher` combines deterministic local ranking with
+  abortable grouped sources and a Cmd/Ctrl+K dialog; `Avatar` provides a stable initials fallback;
+  `AccountMenu` composes identity with an APG menu; `AppSidebar` is expanded vertical navigation;
+  and minimized `AppRail` keeps descendants in pointer-, focus-, and keyboard-accessible flyouts
+  for both vertical and horizontal placement. All route, permission, session, and persistence work
+  remains application-owned behind cancelable events.
+- **`Grid` and `Grid.BillingItems()`.** The public Table specialization keeps every Table feature
+  while providing a conventional editable billing schema for currencies, units, line totals, and
+  flat parent rows. The default line formula is quantity × unit price; tax, discount, rounding,
+  subtotal, validation, and persistence policy remain caller-owned.
+- **Engine-neutral `Chart` and injected `ChartJsAdapter`.** Chart owns responsive canvas lifecycle,
+  loading/empty/error states, Xenon theme defaults, point-selection events, and a synchronized
+  semantic data table. Chart.js 4.5.1 is pinned only as a development/documentation asset; the Zx
+  runtime has no chart import and no runtime dependency.
+- **Lateral anchored-overlay placement.** `position()`, `Dropdown`, `MenuButton`, and `Tooltip` now
+  accept left/right start/end variants for rail and account surfaces.
+
+- **`Questionnaire`** — a guided, one-question-at-a-time flow for onboarding intake, service
+  checklists, audits and surveys, where a `Form` full of fieldsets is the wrong shape. The root is
+  a real `<form>` and the choices are native radios and checkboxes carrying the item name, so
+  `new FormData(questionnaire.toElement())` reads the answers and the keyboard contract inside a
+  choice group is the browser's. Three things go beyond a stack of fieldsets: an item carries a
+  `when` predicate and a `next` target, so the flow **branches** — conditions cascade, an
+  abandoned branch's answers drop out of `getAnswers()`, progress counts the questions actually
+  reachable, and Back retraces the path walked rather than an array index; an item's answer control
+  can be **any registered `Field` type** (`field: {type: 'date'}`), which is what lets a question
+  ask for a date, a number, a rating or an upload; and `validate` may return a **promise**, so a
+  question can be gated on a server check. `review: true` adds a summary screen with jump-back-to-
+  edit, `advance: 'auto'` moves on by itself after a single choice, and `1`–`9`/`a`–`z` shortcuts
+  are assigned and shown on each answer.
+
+- **`Sheet`** — an edge-anchored `Dialog` covering both side-sheet and mobile-drawer patterns;
+  the two differ only in which edge they take, so `side` (`'start' | 'end' | 'top' | 'bottom'`,
+  logical) replaces a second component. `modal` is three-way rather than a boolean because the
+  three real behaviours do not collapse into two: `true` hands focus containment, page inertness,
+  Escape and the backdrop to the browser via `showModal()`, while `'trap-focus'` and `false` open
+  non-modally and re-implement only what they still want. `backdrop: 'dim'|'blur'|'none'` applies
+  to modal sheets alone — `::backdrop` does not render for a non-modal dialog, and a painted
+  stand-in would make a non-blocking sheet look blocking. Entry **and exit** animate, which a
+  `<dialog>` normally cannot do, via `@starting-style` and `transition-behavior: allow-discrete`
+  on `display`/`overlay`. `resizable`, `snap` detents and swipe-to-dismiss are deliberately one
+  gesture whose meaning is decided when the pointer settles, so the sheet follows the pointer the
+  whole way instead of pinning at its minimum and then vanishing.
+- **`SheetStack`** — several sheets as one drill-down. Small on purpose: nested dialogs already
+  stack in the top layer by open order and Escape already closes only the topmost, so no z-index
+  bookkeeping and no unwinding logic. `stack` slides covered sheets back, scales them down and
+  makes them `inert`; `cascade` shifts each clear of the ones in front by their **measured** size
+  so they sit side by side and all stay usable — usually the right one for an ERP screen, where
+  the parent record should stay readable while a line item is edited.
+- **`Dock`** — a stack of collapsible, resizable panes: the docked inspector column of a design
+  tool, and the detail side of a master–detail screen. A pane is either titled or a **tab group**
+  whose strip replaces the title. Giving the dock a `content` turns it into a region with panes on
+  either `side` of it, and nesting one dock in another's pane gives a workbench. Sizes, collapsed
+  panes and active tabs persist through `storageKey`; content factories run on first reveal.
+- **`Dock.adopt(sheet)`** — a dock can take over a `Sheet`'s positioning, so the sheet becomes a
+  track in the dock's flow instead of an overlay. A dock is a flex container by construction and
+  therefore always a valid host, which is why docking needs no arrangement from the application.
+  `dockAt` hands the sheet back to a free overlay below a breakpoint measured on the **dock's own
+  width**, so a dock inside a split pane behaves correctly where a viewport media query would not.
+  Nothing is rebuilt across the handoff: the element moves and reopens in place, so DOM state and
+  listeners survive and no `open`/`close` is emitted for what is only a change of address.
+- **`--zx-overlay-blur`** — tier-2 semantic token behind `Sheet`'s `'blur'` backdrop, default `8px`.
+
+### Changed
+
+- **`SplitView` now shares one axis-drag engine with `Sheet` and `Dock`**, extracted to
+  `core/drag-axis.js`: pointer capture, one write per frame, telling a click from a zero-distance
+  drag, and the WAI-ARIA keyboard map. Behaviour is unchanged. `resolveSize` moved to the kernel
+  and is re-exported from `split-view.js`, so every existing import keeps working.
+- **`Modal` gained three protected seams** — `mountTarget()`, `_show()` and `_isRealClose()` — so a
+  subclass can live somewhere other than `document.body`, open non-modally, and re-host itself.
+  `Dialog`'s size application became the overridable `_applySize()`. No public behaviour changed.
+- **The modal scroll lock keys off `:modal` rather than `[open]`**, so a non-modal dialog no longer
+  locks the page behind it. `Modal` and `Dialog` always open modally, so neither is affected.
+
+### Removed
+
+- **`Permission` is removed**, not just deprecated. 2.3.0 kept the class around for
+  `gx.zeyos.Permission` while pointing new code at `Select.permission()`; there is no longer a
+  second implementation to keep in sync, and `gx.zeyos.Permission` now builds directly on
+  `Select.permission()` instead of wrapping the removed class. The legacy constructor, options,
+  `get()`/`set()`, and the `change` event are unchanged — only the `zx.Permission` export is gone.
+
+## 2.3.0 — 2026-08-23
+
+### Added
+
+- **Six standard themes, as an attribute.** `data-zx-preset="zx" | "zeyos" | "ocean" | "violet" |
+  "rose" | "slate"` picks the accent ramp, orthogonally to `data-zx-theme` picking the polarity.
+  A preset is five tier-1 declarations — `--zx-accent-300` … `--zx-accent-700` — because the accent
+  roles now resolve through that ramp rather than through the green palette directly, so one block
+  rethemes light, dark, and auto together with no second list to keep in sync. Every shipped
+  preset keeps its 600 stop above 4.5:1 against white and its 400 stop above 4.5:1 against the dark
+  page, which is what lets `--zx-color-on-accent` stay a single value per theme. Status colours are
+  deliberately not part of a preset.
+- **A theme studio at `/theme.html`.** Every component on one page under a live theme: cycle the
+  standard presets (or press `[` and `]`), set a custom accent that is derived into a full ramp in
+  OKLab with the contrast ratio reported as you go, tint the neutral ramp, and change radius,
+  control height, base text size, type stack, and density — then copy the result out as CSS.
+  What you pick applies to the whole documentation site until you reset it.
+
+- **`Select` takes fixed choices.** `fixedItems` pins entries to the top of the list, above a rule,
+  and treats them as part of the control rather than of its data: a `filter` function replaces the
+  item list on every query, so a pinned entry is narrowed locally against the same query instead,
+  survives `setItems()`, shows below `minQuery`, and stays resolvable by `set()` once the first
+  results have landed. That is what a choice with no row in the source needs — "Unassigned",
+  "Everyone", "Private". `setFixedItems()` replaces them later.
+- **`Select.permission()`**, the record-access picker: Private and Public pinned above the groups a
+  record may be shared with, carrying the tri-state ZeyOS stores — `false`, `true`, or a group ID —
+  so it binds straight to the record field. `groups` takes an array, or a loader `(query) => items`
+  for an installation whose group list is too long to ship with the form.
+
+- **`MultiValueEditor` rows reorder by dragging.** Each row grows a handle that drags it to a new
+  position, with a line showing where it will land. `reorder` picks what a row offers — `'both'`
+  (the default), `'drag'` for the handle alone, `'buttons'` for the arrows alone, or `'none'`.
+  Dragging goes through the handle rather than the whole row, so selecting text inside a row's
+  input still works, and the handle is a keyboard control too (arrow keys, Home, End) — which is
+  what keeps `reorder: 'drag'` operable without a pointer.
+
+### Changed
+
+- **The documentation shows the demo data behind an example.** `items: catalogue()` documented
+  nothing on its own — the shape the component wants was in a helper the reader could only find by
+  opening the whole module. Every example's code block now carries a tab per module-level
+  declaration it uses, transitively, extracted from the demo module's own text. Nothing about
+  writing a demo changes: declare the data at the top of the module and it appears.
+
+### Deprecated
+
+- **`Permission`.** Its three radios and a disabled group picker spend a form row on a choice
+  `Select.permission()` makes in one control, and the group list could only ever be an array held
+  in memory. The class stays for `gx.zeyos.Permission` and goes away in 3.0; the value and the
+  `groups` option are identical, so replacing it is a one-line change.
+
+### Fixed
+
+- **`MultiValueEditor` no longer collapses in a host that sizes to its contents.** It is no longer
+  a size container at all. `inline-size: 100%` does not rescue one: the percentage resolves against
+  a containing block the host measured from the contribution containment had already zeroed, so the
+  editor still came out 26px wide in an inline-block, a table cell, or a shrink-to-fit flex row,
+  with the row spilling out to the left of it. The rows reflow on their own now — the controls wrap
+  under the value when the row runs out of room — which also reads the width that decides the
+  layout, the row's, rather than the editor's. Verified from a 1000px grid down to a 100px pane
+  with nothing overflowing. `DateRangePicker`, `Fieldset`, and `NavigationBar` still use
+  containment and are only partly rescued — see below.
+- **`MultiValueEditor` keeps focus on the move button.** Up and down disabled themselves at the
+  ends of the list, so a row that reached the top took focus down to the document with it, and a
+  move sent focus to the value input rather than leaving it on the button that had just moved the
+  row — pressing up twice was impossible without going back for it. The ends now mark themselves
+  `aria-disabled` and stay focusable.
+- **`MultiValueEditor` keeps a stored value its option list has lost.** A value with no matching
+  option displayed as the first option while `getValues()` went on returning the stored one, so a
+  form that was only opened and saved rewrote the field. The unknown value is now an option in its
+  own right.
+
+- **The × on a closable `Tabbox` tab closes it.** It was drawn as a decorative glyph with no
+  handler, so clicking it merely activated the tab and closing was reachable only through the
+  Delete key. It is now a real hit target that emits `close` and hands focus to the neighbouring
+  tab, with Delete unchanged. It stays a `<span>` rather than a nested `<button>`, which buttons
+  cannot contain.
+- **Size containers fill their host instead of collapsing inside it.** `DateRangePicker`,
+  `Fieldset`, and `NavigationBar` declare `container-type: inline-size` to pick their own layout,
+  which means they contribute nothing to their own intrinsic width — so in a flex row, an
+  inline-block, or a grid `auto` track they were squeezed to a few pixels and their contents
+  spilled out on top of each other. They now take `inline-size: 100%`, and `Form` does too, because
+  containment travels upward: a form shrink-wrapped to its action buttons while the fieldset inside
+  it overflowed. Eight examples on the documentation site were rendering this way.
+
+  This fixes every host that has a width of its own, which is the case that was actually biting.
+  It cannot fix a host that shrink-wraps its contents — an `inline-block` or a `fit-content` track
+  with no width of its own — because there 100% resolves against a containing block the collapse
+  has already zeroed. Only dropping containment does, as `MultiValueEditor` now has;
+  `DateRangePicker`, `Fieldset`, and `NavigationBar` still need a definite width from their host.
+  `tests/unit/size-containers.test.js` keeps every `container-type` rule declaring a width.
+- **A focused `Search` field is ringed as one control.** The input carried its own focus ring on
+  top of the ring the field already draws on `:focus-within`, so a smaller rounded box appeared
+  inside the field and cut the submit button out of it — the field read as an input with a
+  detached button beside it. The input now rides the field's ring, and the clear and submit
+  buttons mark themselves with an inset ring so tabbing still shows which one has focus without
+  breaking the outline.
+
+- **The generated API reference stopped losing methods to inline type casts.** `/** @type {X} */
+  (expr)` is a doc comment with no method behind it, and the scanner in `tools/build-api.js` was
+  allowed to run past it to the next one — swallowing that method's own comment, and with it the
+  method. Sixty-three public methods across forty-four components had no row on the documentation
+  site, `Dialog.open()` and `Table.commitEdit()` among them, and a few of the rows that did appear
+  had absorbed a neighbour's parameters into signatures like
+  `destroy(options, column, index, node)`.
+- **A horizontal `Stepper` spans its container.** The connectors were already written to absorb
+  whatever space was left over, but the steps themselves could not grow, so there was never any
+  slack to absorb and the rail bunched up on the left of a wide card. The labels still size to
+  themselves; the rules between them now stretch.
+
 ## 2.2.1 — 2026-08-21
 
 ### Fixed

package/DESIGN-SYSTEM.md

@@ -0,0 +1,136 @@
+# Xenon design-system audit
+
+Audit date: 2026-08-24. Xenon is the design system; Zx is its dependency-free JavaScript
+implementation. This document records the current coverage against ZeyOS Classic and the work
+needed for an incremental adoption that keeps the existing routing and business logic.
+
+## System boundary
+
+Xenon has four layers:
+
+1. **Foundations** — semantic tokens, typography, spacing, density, themes, icons, motion, i18n,
+   accessibility rules, and the safe DOM kernel.
+2. **Components** — lifecycle-safe controls and containers with one options/events/destroy model.
+3. **Patterns** — repeatable business interactions such as global launch, account/preferences,
+   record detail, transaction entry, filtering, and empty/loading/error handling.
+4. **Application layouts** — rails, bars, workspaces, master/detail, dashboards, inboxes, wizards,
+   and responsive shell geometry.
+
+This separation follows the enterprise-system intent described by the
+[Carbon Design System](https://carbondesignsystem.com/all-about-carbon/what-is-carbon/) and
+[SAP Fiori design principles](https://experience.sap.com/fiori-design-web/design-principles/),
+without copying either system's code, assets, or component contracts.
+
+Zx currently has more than 50 public component classes, 63 registered documentation/demo entries,
+a generated API reference, bundled local icons, and no runtime dependency. The foundations,
+component layer, and persistent application shell now cover the first ZeyOS adoption wave; domain
+patterns remain intentionally application-owned until their business invariants are specified.
+
+## ZeyOS adoption boundary
+
+ZeyOS Classic does not use `gx`. Across its 30 module files it has roughly 2,500 `UI.*` calls and
+2,600 `PG.*` calls. `PG` already owns navigation, transport, history, exit guards, and page
+lifecycle and remains authoritative.
+
+The existing compact DOM surface has 2,668 executable builder calls: 871 bare `__()` calls, 1,710
+parent-returning `parent.__()` calls, and 87 child-returning `parent.$__()` calls. Zx now provides
+the exact compact builder plus pure append/property/event helpers. Existing global and prototype
+names remain application-owned delegation seams; Zx does not install or replace them.
+
+Migration therefore replaces `UI.new*` implementations one family at a time, keeps their current
+DOM/value contracts until call sites reach zero, and leaves `PG`, `MD`, routes, and server payloads
+in place. See [MIGRATION.md](./MIGRATION.md) for the ordering and shell invariants.
+
+## Coverage ledger
+
+| Capability in current ZeyOS | Xenon/Zx status | Decision |
+| --- | --- | --- |
+| Buttons, inputs, toggles, dates, selects, checklists, tags | Covered by public components | Replace `UI.new*` families incrementally and preserve value/event contracts. |
+| Forms and fieldsets | Covered, including component-backed field adapters | Use for record editors; keep validation/business rules application-owned. |
+| Dialogs, sheets, dropdowns, context menus, tooltips, messages | Covered | Consolidate duplicate menu behavior before building account/launcher surfaces. |
+| Tabs, panels, toolbar, breadcrumbs, stepper, split view, dock | Covered | Compose layouts; do not let navigation components own routes. |
+| Sorting, selection, filtering, pagination, trees/finder | Covered | Suitable for generic data screens. |
+| Editable billing/transaction rows | Covered at generic-grid level | `Grid.BillingItems()` composes typed editable currency/unit columns and flat hierarchy over `Table`. Tax, subtotal, posting, rounding, and persistence stay domain code. |
+| Global launcher/search | Covered | `Launcher` combines ranked local applications with abortable grouped sources. ZeyOS still filters the catalogue and resolves selection through `PG`. |
+| Account/profile/preferences menu | Covered at presentation level | `Avatar` and `AccountMenu` provide identity and action UI. ZeyOS supplies role-filtered actions and owns preferences, authentication, and logout. |
+| Persistent app rail / side navigation | Covered | `AppSidebar` is the expanded vertical tree; minimized `AppRail` uses flyouts in every orientation. Both are route- and persistence-agnostic. |
+| Charts and analytical summaries | Covered through an adapter | `Chart` is engine-neutral and accessible; `ChartJsAdapter` accepts an injected Chart.js 4 engine. Chart.js is documentation/test tooling only. |
+| Local product/module icons | Partial | Use bundled icons or registered local assets; do not require the optional remote Font Awesome kit. |
+| Domain entity selectors/cards/links | Partial | Build patterns on `Select`, Table, Panel, and ContextMenu after the shell blockers. |
+| Persistent notification/activity center | Missing, lower priority | `Message` covers ephemeral feedback, not read/unread activity history. |
+
+### Launcher contract
+
+The current launcher searches applications, recent records, and grouped remote record types. A
+replacement supplies pinned-order ranking, request cancellation, Cmd/Ctrl+K, listbox keyboard
+behavior, native link metadata, and a cancelable action. Permission filtering, active-route state,
+cache and recent-history policy remain inputs from ZeyOS, which resolves actions through `PG.go()`.
+The component is deliberately not a second router.
+
+### Account contract
+
+The current account surface includes identity, role-dependent links, language, authentication and
+logout, theme and menu-position preferences, and About/version content. A shared `Menu` should
+first centralize the keyboard/typeahead/selection behavior currently duplicated by `MenuButton`
+and `ContextMenu`; `AccountMenu` then composes that primitive with `Avatar`/`Identity` and emits
+actions without owning routes or session state. `AccountMenu` now provides that composition over
+`MenuButton`; a future shared low-level `Menu` remains an internal consolidation opportunity, not
+an adoption blocker.
+
+## Table and transaction follow-ups
+
+The enhanced `Table` now keeps values numeric while formatting per-row locales, currencies, units,
+and decimals; numeric types infer `NumberField` editors. Flat `parentId` data is projected into a
+cycle-safe ARIA treegrid with local sibling sorting and expand/collapse APIs.
+
+`Grid.BillingItems()` now packages the conventional description, quantity, unit, unit-price,
+currency, line-total, and hierarchy schema while retaining Table's editing contract. Useful
+follow-ups, deliberately separate from this generic preset:
+
+- summary/footer rows and grouped subtotals;
+- column reorder and user-persisted column state;
+- product-specific invoice/transaction presets with tax, discount, rounding, and formula golden tests;
+- server persistence, optimistic rejection, and undo owned by the application/controller layer.
+
+## Chart-engine candidates
+
+Chart.js was selected for the first adapter. It is pinned at 4.5.1 as a development dependency for
+tests and the documentation asset, but is never imported by Zx runtime source. Applications inject
+their chosen engine into the adapter. Published browser artifact sizes below are approximate and
+remain useful when choosing a different future adapter.
+
+| Engine | Current state at audit | Approx. browser cost | Best fit | Main trade-off |
+| --- | --- | ---: | --- | --- |
+| [Chart.js](https://github.com/chartjs/Chart.js/releases) 4.5.1 | Mature, active, MIT | 209 kB / 71 kB gzip (UMD) | Broad default: bar, line, doughnut, mixed business charts | Larger than focused engines; canvas requires a separate accessible data summary. |
+| [Frappe Charts](https://github.com/frappe/charts/releases) 1.6.x | Zero-dependency SVG, ERP-oriented, MIT | 69 kB / 18 kB gzip (UMD) | Lean dashboards with common chart types | GitHub release and npm publication were out of step; ecosystem and extension surface are smaller. |
+| [uPlot](https://github.com/leeoniya/uPlot) 1.6.32 | Active, MIT, highly optimized | 51 kB JS + 2 kB CSS / about 23 kB gzip | Dense time-series and operational telemetry | Deliberately narrow; not a general categorical/stacked business-chart toolkit. |
+| [Apache ECharts](https://echarts.apache.org/en/changelog.html) 6.1.0 | Very capable, active, Apache-2.0 | 1.12 MB / 369 kB gzip (full build) | Advanced analytical visualization | Too large as Xenon's default; only sensible as an opt-in advanced adapter or custom build. |
+
+Implemented architecture: `Chart` accepts an injected engine adapter, maps Xenon semantic tokens,
+owns loading/empty/error states, and mirrors its data in an accessible table. Chart.js is the broad
+default adapter; Frappe Charts remains the lean ERP-oriented alternative, uPlot a specialized
+time-series candidate, and ECharts an opt-in advanced adapter. Any additional package still
+requires explicit dependency approval.
+
+## Review corrections completed
+
+- Generated API records no longer let helper typedefs overwrite component options; inline JSDoc
+  tags are parsed, and audited runtime events are present in types and documentation.
+- Form documentation exposes `Form`, `Fieldset`, and `Field`; `MonthPicker` has its own constructor
+  type.
+- Theme Studio destroys registered component instances on every rebuild and describes its honest
+  family-level coverage.
+- Documentation separates Presets from green-accent Examples and uses callable preset names.
+- Current source and documentation no longer carry branding from the retired framework experiment.
+
+## Recommended sequence
+
+1. Ship the Zx runtime and delegate the current compact DOM/event seams; verify no navigation or
+   listener regressions.
+2. Mount `Launcher`, `Avatar`/`AccountMenu`, and `AppSidebar`/`AppRail` behind the current shell
+   fixtures, permission filters, and preference store.
+3. Replace high-volume `UI.new*` families, one discriminating fixture set at a time.
+4. Introduce `Grid.BillingItems()` where its generic schema fits; add domain presets only with
+   formula and rounding fixtures.
+5. Inject Chart.js into `ChartJsAdapter` only on analytical surfaces that need it; keep the engine
+   out of the base Zx runtime bundle.

package/MIGRATION.md

@@ -4,6 +4,136 @@ Zx replaces the MooTools-era `gx` UI libraries with dependency-free ES2022 modul
 compatibility bundle lets mapped legacy code keep running while classes are migrated one at a
 time. Compatibility constructors warn once per legacy class so remaining call sites are visible.
 
+Xenon is the ZeyOS design system; Zx is its browser implementation. A complete migration therefore
+means more than swapping constructors: foundations, components, application patterns, and layout
+contracts must move together while routing and business behavior stay authoritative.
+
+## Introducing Xenon into ZeyOS Classic
+
+The current ZeyOS Classic application is **not** a `gx.*` application. Its modules call the global
+`UI` factories, use `PG` for routing and page lifecycle, and rely on an extended DOM API including a
+CSS-like `__()` element builder. Do not call `gx.compat.installGlobals()` there: that opt-in helper
+preserves an existing `__()` but installs unrelated `gx` globals and prototype compatibility that
+the current application does not need.
+
+The migration does not need a separate application bridge. Zx now exports the established builder
+directly, including its exact compact tag and property conventions:
+
+```js
+const node = zx.__('button#save.primary', {
+  Daction: 'save',
+  onclick: () => save()
+}, 'Save');
+```
+
+Zx does not install globals or alter DOM prototypes. The current runtime keeps owning its global
+`__`, `_`, `Node._`, `Node.__`, `Node.$__`, and `Element.be` seams during the migration and delegates
+their bodies to `zx.compactElement()`, `zx.appendContent()`, `zx.appendCompact()`,
+`zx.appendCompactChild()`, and `zx.applyCompactProperties()`. Its `DOM.on`, `DOM.remEvt`, and
+`DOM.fireEvt` facade likewise delegates to Zx's shared compact-event helpers, so registration,
+removal, and synthetic firing always see the same handlers. Replace the implementations of
+`UI.new*` component families progressively with Zx components; do not insert a second routing or
+application abstraction between those components and `PG`.
+
+### Keep these authorities in place
+
+- `PG` remains responsible for URL construction, history, transport, exit guards, page dispatch,
+  and the `page:beforeUnmount` / `page:mounted` lifecycle.
+- Existing `MD` handlers and business logic continue receiving the same page data.
+- Existing `UI.new*` call sites keep their DOM return values and `getV` / `setV` / chaining
+  contracts while each factory implementation is replaced. New code uses the Zx component API
+  directly; the old factory is removed when its call-site count reaches zero.
+- Zx owns only the mounted component subtree and tears that subtree down exactly once.
+- New client/schema-driven screens may use `@zeyos/zx/zeyos`; adopting that optional layer is not a
+  prerequisite for converting current server-rendered screens.
+
+Safe bootstrap order is the normal Zx bundle, the current Classic runtime delegating its compact
+DOM seams to Zx, then the existing `Z(data)` application bootstrap. Component actions must call
+`PG.go()` for internal routes; do not let a navigation component fall back to `location.assign()`.
+
+### Recommended adoption waves
+
+1. Mount persistent shell components behind current lifecycle events: launcher, account menu,
+   application rail, detail chrome, and overlays.
+2. Replace the highest-volume `UI.new*` implementations—inputs, Selects, tabs, menus, dialogs, and
+   tables—one family at a time while preserving their existing call-site contract.
+3. Move record and transaction patterns only after old/new behavior has discriminating fixtures.
+4. Use direct Zx and the ZeyOS schema binding for new surfaces; retire an old factory only after its
+   remaining call-site count reaches zero.
+
+### Shell components and ownership
+
+`Search` remains a field-level input. `Launcher` is the shell-level application/record surface: it
+ranks local items, debounces and aborts grouped sources, ignores stale responses, and supplies the
+Cmd/Ctrl+K dialog/listbox interaction. ZeyOS filters permissions, supplies apps/recent records,
+decides caching, and handles the cancelable selection through `PG`; Launcher never becomes a
+router.
+
+`Avatar` and `AccountMenu` provide the identity trigger, profile header, grouped actions, focus
+return, and compact rail presentation. ZeyOS still decides permission-dependent routes, language
+and theme choices, authentication/logout, and About/version data. A selection is a request to the
+application, not a session mutation.
+
+`AppSidebar` is the expanded vertical application tree and is the only presentation with inline
+children. Its collapsed state renders `AppRail`. A standalone rail may be vertical or horizontal,
+but every child collection remains a hover/focus/keyboard flyout. Both components accept native
+links or cancelable actions and expose active/collapsed/expanded state without persisting it.
+
+Use bundled Zx icons or explicitly registered local assets. The optional ZeyOS icon helper's
+remote Font Awesome kit is not appropriate for a dependency-free production shell.
+
+### Persistent shell contract
+
+These invariants were validated while prototyping the replacement shell and remain binding for a
+Xenon implementation:
+
+- Application-menu position is `top`, `bottom`, `left`, `right`, or `none`, defaulting to `left`.
+  Persist it under `zeyos.appMenu.position` (scope-suffixed where separate workspaces share an
+  origin) and publish the resolved value on `:root[data-app-menu-effective]`.
+- Sidebar minimization is a user choice, never a hover side effect. Keep the existing
+  `zeyos.appRail.expanded` preference while migrating and map it to
+  `AppSidebar.setCollapsed(!expanded)`. `AppRail` itself never expands labels or inline children.
+- The minimized rail is 48 px and the expanded sidebar 184 px. The application bar is 48 px; tiles
+  are 30 px, glyphs 22 px, and compact controls 31 px. Workspace tools in a side layout remain
+  inside the rail, and page insets derive from the effective rail/bar geometry.
+- Theme preference is `auto`, `light`, or `dark`, persisted under `zeyos.theme` and applied before
+  paint. `auto` follows the system color-scheme media query.
+- The dark neutral ramp is a coal surface rebased from Carbon Gray 100 toward `#0b0c0e`. Avoid a
+  cyan/slate cast that competes with ZeyOS module colors; module accents must retain clear contrast
+  on both shell and content surfaces.
+
+### Migration proof points
+
+Before replacing any Classic surface, verify that internal navigation and browser history still use
+`PG.go()` without a full reload; page-scoped instances are destroyed exactly once; persistent shell
+listeners do not multiply across navigation or language changes; launcher output matches permission,
+app, recent, and search fixtures; account content matches ordinary/admin/developer roles; and the
+production shell loads no remote UI or icon dependency.
+
+The shell wiring stays direct:
+
+```js
+const launcher = new zx.Launcher(null, {
+  items: applicationCatalogue,
+  sources: recordSources,
+  onselect(event) {
+    event.preventDefault();
+    PG.go(resolveLauncherRoute(event.detail.item));
+  }
+});
+
+const sidebar = new zx.AppSidebar(shellHost, {
+  items: applicationTree,
+  active: currentRouteId,
+  collapsed: !savedAppRailExpanded,
+  footer: accountMenu,
+  onselect(event) {
+    event.preventDefault();
+    PG.go(event.detail.href);
+  }
+});
+```
+
 ## Deployment script swap
 
 For deployments that serve the old libraries directly from
@@ -25,8 +155,9 @@ with this order:
 ```
 
 The compatibility entry exposes both `window.zx` and `window.gx`. Element
-`store`/`retrieve`/`eliminate` is installed automatically. If the application uses `__()`, `_()`,
-`String.prototype.htmlSpecialChars`, or `Array.prototype.findBy`, opt in after both scripts load:
+`store`/`retrieve`/`eliminate` is installed automatically. If a genuine gx application uses its
+free parser, `_()`, `String.prototype.htmlSpecialChars`, or `Array.prototype.findBy`, opt in after
+both scripts load. An existing `__()` is deliberately never replaced:
 
 ```js
 gx.compat.installGlobals();
@@ -251,14 +382,14 @@ list.setValues([1, 2]);
 
 For remote data pass `load: () => Promise<items>` and listen for `loaded`.
 
-### `gx.zeyos.Permission` → `zx.Permission`
+### `gx.zeyos.Permission` → `zx.Select.permission()`
 
 ```js
 // gx
 const permission = new gx.zeyos.Permission(host, { value: true, groups });
 
 // Zx
-const permission = new zx.Permission(host, { value: 'public', groups });
+const permission = zx.Select.permission(host, { value: true, groups });
 permission.on('change', (event) => save(event.detail.value));
 ```
 
@@ -295,6 +426,26 @@ table.addData([{ ID: 1, name: 'Ada' }]);
 
 Use `setData`, `addData`, `updateRow`, `removeRow`, and `getData` for row operations.
 
+### Billing/transaction rows → `zx.Grid.BillingItems()`
+
+Use the generic preset when the existing screen has description, quantity, unit, unit price,
+currency, total, and optional parent rows:
+
+```js
+const items = zx.Grid.BillingItems(host, {
+  data: rows,
+  units: unitChoices,
+  currencies: currencyChoices,
+  oneditcommit(event) {
+    if (!controller.accept(event.detail.changes)) event.preventDefault();
+  }
+});
+```
+
+The default line total is quantity × unit price. Keep taxes, discounts, subtotal/group updates,
+rounding policy, posting, server persistence, and undo in the existing controller. Override
+`lineTotal` only when that calculation is a stable screen-level rule.
+
 ### `gx.zeyos.Tabbox` and `gx.bootstrap.Tabbox` → `zx.Tabbox`
 
 ```js