@zeyos/zx 2.3.0 → 4.0.0

package/CHANGELOG.md

@@ -8,6 +8,144 @@ and friends remain the complete record.
 
 ## Unreleased
 
+## 4.0.0 — 2026-08-24
+
+### Added
+
+- **`Card`.** A semantic, product-agnostic content and record surface with optional media, native
+  title link, secondary actions, footer metadata, three variants, horizontal/vertical layout, and
+  exact enhanced-target restoration. The root never impersonates a link or button, so nested
+  controls remain valid and independently keyboard-accessible.
+
+### Changed
+
+- **One public application-navigation component.** `AppSidebar` now owns expanded vertical, minimized
+  vertical, and horizontal rail presentations over one active/branch state model. Descendants are
+  inline only while expanded and use pointer-, focus-, and keyboard-accessible flyouts in rail
+  states; its minimized renderer is an implementation detail, not a second public component.
+- **Richer Select presets.** `Select.priority()` now uses the five-square ZeyOS scale;
+  `Select.status()` adds shape- and semantic-color-distinct workflow states; and the optional
+  `zeyosEntitySelect()` binding adds grouped remote records, module-colored icons, an explicit
+  empty choice, and application-owned command rows without changing the selected-ID contract.
+- **Full launcher parity.** `Launcher` now distinguishes application tiles from record rows,
+  exposes current and pinned state, spatial keyboard movement, visible hints, query-state/source
+  ordering, and injected icon factories. The optional ZeyOS adapter maps all 29 prototype
+  applications, forks/weblets, cached or async recent records, and grouped abortable search while
+  leaving permissions, icons, destinations, and routing with the host application.
+- The documentation now has a global destination search, a clearer uppercase green
+  Presets/Examples hierarchy, and product-agnostic Xenon positioning. The internal rollout guide
+  is no longer shipped or linked from public surfaces.
+
+### Removed
+
+- **The separate `AppRail` constructor.** Use `AppSidebar` with `collapsed: true` for a vertical
+  rail or `orientation: 'horizontal'` for a horizontal rail. This completes the single-owner
+  navigation contract instead of maintaining two public root-DOM models.
+- **Public gx compatibility entry points and bundles.** The compact `__()` DOM builder is part of
+  the Zx core; gx adapter source remains repository-internal and is no longer exported, built, or
+  included in the npm package.
+
+### Fixed
+
+- Late Launcher sources preserve the current keyboard choice only while completing the same query;
+  a new query resets to its own best match.
+- Card rejects control-obfuscated unsafe URL schemes; Launcher and every AppSidebar presentation
+  strip executable/data destinations and disable inert descriptors. AppSidebar also relocates focus,
+  emits its effective collapse state across layout changes, and releases obsolete mode listeners.
+- Card restores an enhanced target after failed construction, releases callbacks when links or
+  actions are replaced, and keeps the full non-interactive body inside the primary-link target.
+- Status shortcut hints now activate their options, async permission group loaders cannot be
+  disconnected by a filter override, and enhanced billing grids restore every target attribute.
+- Billing totals now distinguish a missing operand from an explicit zero, and Chart renders a
+  consistent error state for falsy payloads and errors without a message.
+
+## 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

package/DESIGN-SYSTEM.md

@@ -0,0 +1,96 @@
+# Xenon Design System
+
+Xenon is a product-agnostic design system for browser applications; Zx is its dependency-free
+JavaScript implementation. It provides shared foundations, accessible components, interaction
+patterns, and application layouts without taking ownership of an application's routing or domain
+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 keeps foundations, components, patterns, and layouts independently reusable while
+preserving a coherent API and visual language.
+
+Zx has a generated API reference, live examples, bundled local icons, and no runtime dependency.
+Its compact `__()` DOM builder and pure append/property/event helpers let established applications
+adopt the system without introducing a framework runtime. Domain policy, transport, persistence,
+and navigation remain application-owned.
+
+## Coverage ledger
+
+| Front-end capability | Xenon/Zx status | Design-system boundary |
+| --- | --- | --- |
+| Buttons, inputs, toggles, dates, selects, checklists, tags | Covered by public components | Components preserve native semantics and expose consistent 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 an application grid, current/pinned state, recent records, and abortable grouped sources. The optional ZeyOS adapter maps the complete 29-app shell catalogue while the host retains permissions, icons, and routing. |
+| Account/profile/preferences menu | Covered at presentation level | `Avatar` and `AccountMenu` provide identity and action UI. The host supplies permitted actions and owns preferences, authentication, and logout. |
+| Persistent app rail / side navigation | Covered | One route-agnostic `AppSidebar` owns expanded, minimized, and horizontal presentations. Only expanded vertical branches render inline; every rail presentation uses flyouts. |
+| 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 | Covered at generic presentation level | `Card` provides media, native primary links, secondary actions, and metadata; applications own entity routing and policy. |
+| Persistent notification/activity center | Missing, lower priority | `Message` covers ephemeral feedback, not read/unread activity history. |
+
+### Launcher contract
+
+The launcher searches applications, recent records, and grouped remote record types. The generic
+component supplies the tile/list layouts, pinned-order ranking, current-route marker, request
+cancellation, spatial keyboard movement, visible keyboard hints, native link metadata, and a
+cancelable action. The optional ZeyOS adapter accepts all 29 prototype modules plus forks and
+weblets, cached or async recent items, grouped legacy search payloads, permission/current state,
+and host icon renderers. All state is injected; the adapter reads no shell globals and deliberately
+does not become a second router.
+
+### Account contract
+
+A typical account surface includes identity, role-dependent links, language, authentication and
+logout, preferences, and About/version content. `AccountMenu` composes `Avatar` with the existing
+menu behavior and emits actions without owning routes or session state. The host decides which
+actions exist and what each one does.
+
+## 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.

package/README.md

@@ -1,10 +1,13 @@
-# Zx
+# Xenon Design System (Zx)
 
-Zx is the dependency-free, vanilla-JavaScript component library for ZeyOS business applications:
-ES2022 modules, accessible native controls, semantic design tokens, and lifecycle-safe components.
-Source modules run directly in a browser; the distribution also provides ESM and classic-script
-bundles. An opt-in compatibility layer keeps existing MooTools-era `gx` code running while it is
-modernised.
+Xenon is a dependency-free design system for browser applications; Zx is its vanilla-JavaScript
+implementation. It combines foundations, accessible components, repeatable workflow patterns,
+and application layouts in plain ES2022 modules. Source modules run directly in a browser; the
+distribution also provides ESM and classic-script bundles. Xenon originated at ZeyOS, while its
+components and contracts remain product- and framework-agnostic.
+
+The [design-system audit](./DESIGN-SYSTEM.md) records current ZeyOS coverage, missing shell
+patterns, the adoption boundary, transaction-grid follow-ups, and chart-engine candidates.
 
 ## Quick start
 
@@ -38,15 +41,15 @@ For an application built from classic scripts, the IIFE bundle exposes the same
 </script>
 ```
 
-Import one component instead of the library when a bundler is doing the work:
+Import a component source module directly when a bundler needs the narrowest possible graph:
 
 ```js
 import { Slider } from '@zeyos/zx/src/components/slider/slider.js';
 ```
 
-An application using two components bundles 26 kB minified this way against 157 kB through the
-package entry point. Load the one stylesheet either way — it is 13 kB gzipped whole, and splitting
-it per component costs more than it saves.
+The package also exposes the bundled ESM entry for ordinary named imports. Load the complete
+stylesheet either way: it contains the shared tokens and cross-component states that make the
+system coherent, while JavaScript can still be tree-shaken or imported component by component.
 
 TypeScript definitions ship with the package. They are generated from the JSDoc that documents
 every option, method, and event, so `new Slider(null, { … })` is checked against `SliderOptions`
@@ -95,7 +98,8 @@ ZeyOS binding — see `src/zeyos/modules.js`.
 | `CheckButton` | Two-state pressed button with optional state-specific labels. |
 | `Toggle` | Native-button switch with a separate submitted value. |
 | `Search` | Search input with debounced input, submit, and clear events. |
-| `Select` | APG combobox with local or async filtering and a priority preset. |
+| `Launcher` | Cmd/Ctrl+K application and record launcher with ranked local items and abortable grouped sources. |
+| `Select` | APG combobox with local or async filtering, pinned items, priority/status/permission presets, and an optional ZeyOS entity picker. |
 | `Checklist` | Searchable checkbox group with optional async loading. |
 | `TagPicker` | Multi-select combobox that keeps its selection as removable tags. |
 | `NumberField` | APG spinbutton with step buttons, ranges, units, and wrapping. |
@@ -122,12 +126,16 @@ ZeyOS binding — see `src/zeyos/modules.js`.
 | `MenuButton` | APG menu button built on `Dropdown`. |
 | `ContextMenu` | APG right-click menu for a region or, via `selector`, per row. |
 | `Tooltip`, `tooltip()`, `describe()` | Hover/focus description bubble anchored with `position()`. |
+| `Avatar` | Fixed-size user image with initials fallback and optional presence. |
+| `AccountMenu` | Identity trigger and grouped account actions over `MenuButton`. |
 
 ### Data
 
 | API | Description |
 | --- | --- |
-| `Table` | Semantic sortable table with local/server sorting, row selection, and opt-in inline cell/row editing. |
+| `Table` | Sortable/selectable table with typed transaction columns, flat-data hierarchy/treegrid projection, and opt-in cell/row editing. |
+| `Grid`, `Grid.BillingItems()` | Table-compatible preset surface with editable currencies, units, totals, and sub-items. |
+| `Chart`, `ChartJsAdapter` | Accessible engine-neutral chart host and explicitly injected Chart.js adapter. |
 | `DataFilter` | Declarative select, text, and custom filters for client-side row sets. |
 | `TreeView` | APG tree with lazy children, filtering, and tri-state checkboxes. |
 | `Finder` | Miller-columns hierarchy browser with an optional preview pane. |
@@ -137,10 +145,10 @@ ZeyOS binding — see `src/zeyos/modules.js`.
 
 | API | Description |
 | --- | --- |
-| `Permission` | Private, public, or group-level permission selector. |
 | `Field` | Label, description, validation state, and adapter-backed form control. |
 | `Fieldset` | Native fieldset that owns and coordinates fields. |
 | `Form` | Form composition, values, validation, highlighting, and actions. |
+| `Questionnaire` | Guided one-question-at-a-time flow: branching, path-aware progress, review. |
 | `ValueList` | Validated, sortable tag/chip editor. |
 | `MultiValueEditor` | Ordered editable rows with add, remove, and move controls. |
 | `FieldUpload` | Click/drop file upload with progress, abort, validation, and preview. |
@@ -150,10 +158,12 @@ ZeyOS binding — see `src/zeyos/modules.js`.
 | API | Description |
 | --- | --- |
 | `Groupbox` | Collapsible section backed by native `<details>`. |
+| `Card` | Semantic content/record surface with media, native title link, actions, and footer. |
 | `Panel` | Framed, optionally collapsible section with a footer. |
 | `MasterPanel` | Full-height application panel with fixed header actions and footer. |
 | `Tabbox` | APG tabs in four appearances, with lazy content, closing, badges, and disabled states. |
 | `NavigationBar` | Responsive application navigation with optional tab panels and overflow. |
+| `AppSidebar` | Expanded or minimized vertical application navigation plus horizontal rails; descendants are inline only while expanded. |
 | `Toolbar` | APG toolbar: one tab stop, arrow-key movement, and overflow into a menu. |
 | `SplitView` | Resizable two-pane split with a keyboard-operable separator. |
 | `Stepper` | Linear multi-step progress with completed, active, and error states. |
@@ -241,7 +251,7 @@ through, so a preset rethemes light, dark, and auto at once:
 
 Light surfaces take the 600 and 700 stops, dark ones take 300, 400, and 500 — so keep 600 legible
 against white and 400 against near-black, and `--zx-color-on-accent` stays correct in both. The
-[theme studio](https://zx.zeyos.com/theme.html) renders every component under a live theme and
+[theme studio](https://zx.zeyos.com/theme.html) renders every component family under a live theme and
 exports the result.
 
 Anything beyond the accent is a semantic token override, without reaching into component CSS:
@@ -273,7 +283,7 @@ JavaScript positioning fallback.
 
 ## Development
 
-Install the single development dependency and start the no-build demo server:
+Install the development toolchain and start the no-build demo server:
 
 ```sh
 npm install
@@ -287,7 +297,7 @@ classic-script distribution tests.
 
 ```sh
 npm test           # Node unit tests plus semantic-token lint
-npm run build      # writes ESM, global, compatibility, and CSS assets to dist/
+npm run build      # writes ESM, ZeyOS, global, CSS, and declaration assets to dist/
 npm run build:site # assembles the deployable documentation site into site/
 npm run serve:site # serves site/ exactly as it will be deployed
 ```
@@ -303,27 +313,7 @@ import { Table, Message } from '@zeyos/zx';
 import '@zeyos/zx/zx.css';
 ```
 
-Additional entry points: `@zeyos/zx/zeyos` (the schema-driven ZeyOS binding), `@zeyos/zx/compat`
-(the gx compatibility namespace), and `@zeyos/zx/global` for classic script tags.
-
-Documentation lives at <https://zx.zeyos.com>; see `docs/RELEASING.md` for how the site and the
-package are published.
-
-## `gx` compatibility layer
-
-During an incremental migration, load the global API before the compatibility bundle:
-
-```html
-<link rel="stylesheet" href="/assets/zx.css">
-<script src="/assets/zx.global.js"></script>
-<script src="/assets/zx-compat.global.js"></script>
-<script>
-  // Only when old code relies on __(), _(), or prototype conveniences:
-  gx.compat.installGlobals();
-</script>
-```
+Additional entry points: `@zeyos/zx/zeyos` (the schema-driven ZeyOS binding) and
+`@zeyos/zx/global` for classic script tags.
 
-The compatibility bundle always exposes `window.gx` and installs only the element
-`store`/`retrieve`/`eliminate` shim automatically. Legacy globals and prototype conveniences are
-an explicit opt-in through `gx.compat.installGlobals()`. See [MIGRATION.md](./MIGRATION.md) for
-class mappings, script replacement, deliberate behavior changes, and unsupported legacy APIs.
+Documentation lives at <https://zx.zeyos.com>.

package/dist/types/components/account-menu/account-menu.d.ts

@@ -0,0 +1,144 @@
+import { Component } from '../../core/component.js';
+import { Avatar } from '../avatar/avatar.js';
+import { MenuButton } from '../menu-button/menu-button.js';
+export type MenuButtonItem = import('../menu-button/menu-button.js').MenuButtonItem;
+export type AccountIdentity = {
+    /**
+     * Primary identity.
+     */
+    name?: string;
+    /**
+     * Email, company, or other secondary identity.
+     */
+    secondary?: string;
+    /**
+     * Avatar image URL.
+     */
+    src?: string | null;
+    /**
+     * Explicit avatar initials.
+     */
+    initials?: string | null;
+    /**
+     * Presence state.
+     */
+    status?: 'online' | 'away' | 'busy' | 'offline' | null;
+    /**
+     * Presence text alternative.
+     */
+    statusLabel?: string | null;
+};
+export type AccountMenuOptions = {
+    /**
+     * Account presentation supplied by the application.
+     */
+    account?: AccountIdentity;
+    /**
+     * Account actions and `'-'` separators.
+     */
+    items?: MenuButtonItem[];
+    /**
+     * Whether only the avatar is visually shown in the trigger.
+     */
+    compact?: boolean;
+    /**
+     * Trigger label; defaults to `Account menu for <name>`.
+     */
+    label?: string | null;
+    /**
+     * Popup placement.
+     */
+    placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end' | 'bottom' | 'top' | 'right-start' | 'right-end' | 'left-start' | 'left-end' | 'right' | 'left';
+    /**
+     * Preventable action listener.
+     */
+    onselect?: (event: CustomEvent<{
+        value: unknown;
+        item: object;
+    }>) => void;
+    /**
+     * Open listener.
+     */
+    onopen?: (event: CustomEvent<Record<string, never>>) => void;
+    /**
+     * Close listener.
+     */
+    onclose?: (event: CustomEvent<Record<string, never>>) => void;
+};
+/** @typedef {import('../menu-button/menu-button.js').MenuButtonItem} MenuButtonItem */
+/**
+ * @typedef {Object} AccountIdentity
+ * @property {string} [name=''] Primary identity.
+ * @property {string} [secondary=''] Email, company, or other secondary identity.
+ * @property {string|null} [src=null] Avatar image URL.
+ * @property {string|null} [initials=null] Explicit avatar initials.
+ * @property {'online'|'away'|'busy'|'offline'|null} [status=null] Presence state.
+ * @property {string|null} [statusLabel=null] Presence text alternative.
+ */
+/**
+ * @typedef {Object} AccountMenuOptions
+ * @property {AccountIdentity} [account={}] Account presentation supplied by the application.
+ * @property {MenuButtonItem[]} [items=[]] Account actions and `'-'` separators.
+ * @property {boolean} [compact=false] Whether only the avatar is visually shown in the trigger.
+ * @property {string|null} [label=null] Trigger label; defaults to `Account menu for <name>`.
+ * @property {'bottom-start'|'bottom-end'|'top-start'|'top-end'|'bottom'|'top'|'right-start'|'right-end'|'left-start'|'left-end'|'right'|'left'} [placement='top-start'] Popup placement.
+ * @property {(event: CustomEvent<{value: unknown, item: object}>) => void} [onselect] Preventable action listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close listener.
+ */
+/**
+ * Avatar-backed APG account action menu; session/authentication behavior remains application-owned.
+ * @fires AccountMenu#select
+ * @fires AccountMenu#open
+ * @fires AccountMenu#close
+ * @extends {Component<AccountMenuOptions>}
+ */
+export declare class AccountMenu extends Component<AccountMenuOptions> {
+    _avatar: Avatar;
+    _menu: MenuButton;
+    _createdRoot: boolean;
+    _original: {
+        attributes: string[][];
+        children: ChildNode[];
+    };
+    _account: AccountIdentity & {
+        name: string;
+        secondary: string;
+    };
+    static cssName: string;
+    /** @type {Readonly<AccountMenuOptions>} */
+    static defaults: Readonly<AccountMenuOptions>;
+    /**
+     * Creates or enhances an account-menu host.
+     * @param {Element|string|null} target Host target.
+     * @param {AccountMenuOptions} [options={}] Account-menu options.
+     */
+    constructor(target?: Element | string | null, options?: AccountMenuOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Opens the account menu. @returns {this} */
+    open(): this;
+    /** Closes the account menu. @returns {this} */
+    close(): this;
+    /** Toggles the account menu. @returns {this} */
+    toggle(): this;
+    /** Reports whether the menu is open. @returns {boolean} */
+    isOpen(): boolean;
+    /** Replaces account presentation without touching session state. @param {AccountIdentity} account @returns {this} */
+    setAccount(account: AccountIdentity): this;
+    /** Replaces account actions. @param {MenuButtonItem[]} items @returns {this} */
+    setItems(items: MenuButtonItem[]): this;
+    /** Focuses the account trigger. @returns {this} */
+    focus(): this;
+    /** Returns the underlying menu panel for shell hover/focus coordination. @returns {HTMLElement} */
+    getPanel(): HTMLElement;
+    /** Destroys child components and restores/removes the host. @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _renderIdentity(): void;
+    /** @returns {void} */
+    _renderPanelHeader(): void;
+}
+/** Fired when an action is activated. @event AccountMenu#select @type {CustomEvent<{value: unknown, item: object}>} */
+/** Fired after the popup opens. @event AccountMenu#open @type {CustomEvent<Record<string, never>>} */
+/** Fired after the popup closes. @event AccountMenu#close @type {CustomEvent<Record<string, never>>} */