@zeyos/zx 3.0.0 → 4.1.0

package/CHANGELOG.md

@@ -8,6 +8,101 @@ and friends remain the complete record.
 
 ## Unreleased
 
+## 4.1.0 — 2026-08-25
+
+### Added
+
+- **`AppIcon`.** A reusable application-identity surface with safe semantic colours, badges,
+  accessible labelled and decorative modes, and an optional CSS-only translucent glass material.
+  The ZeyOS adapter supplies presets for all 29 current applications while keeping glyph loading
+  and routing application-owned.
+- **`Filter`.** A backend-neutral visual expression builder with a versioned JSON-safe AST,
+  nested AND/OR groups, typed operators and value editors, abortable asynchronous choices,
+  structural and semantic validation, defensive limits, deterministic keyboard focus, and
+  valid-only Apply events. Query compilation, saved views, and URL state remain adapter concerns.
+- **Richer entity and tag selection.** `Select.entity()` supports optional recent items and an
+  application-owned create command; `TagPicker` now renders native item icons and semantic colours
+  without overriding a custom renderer.
+
+### Changed
+
+- **Transaction grids are faster to operate.** `Grid.BillingItems()` and `Table` now support
+  single-click typed editing, opt-in double-click compatibility, same-parent row reordering by
+  drag or keyboard, hierarchy-safe branch moves, and accessible column visibility controls.
+- **ZeyOS identity is consistent across workflows.** Launcher application tiles use the new
+  AppIcons, while Launcher recents and entity-select results use module/entity identities and
+  colours rather than generic placeholders.
+- **The documentation shell is easier to navigate.** Global search is centred in every header and
+  reports full breadcrumb paths; component groups are alphabetized, application-shell primitives
+  are collected under Layout, narrow API tables remain locally scrollable, and public navigation
+  and footer links are reduced to their canonical destinations.
+- **Theme Studio now applies complete recipes.** Presets change typography, tint, radius, density,
+  control sizing, and glass strength in addition to colour; the house preset is named `ZeyOS`.
+
+### Fixed
+
+- Select preset chevrons retain their alignment across theme recipes and enhanced
+  `Select.entity()` targets restore their exact original DOM when destroyed.
+- Floating messages default to a content-sized upper-right glass surface instead of stretching
+  with the document, with opaque and reduced-transparency fallbacks.
+- Filter mutations preserve keyboard focus and accessible announcements; asynchronous editors
+  expose busy state and abort stale work.
+- Row editing no longer targets hidden columns or hijacks buttons and links rendered inside cells;
+  column toggles retain focus and row drags do not export record identifiers as plain text.
+- Application and tag colour overrides reject CSS image and URL values before reaching public
+  custom properties.
+
+## 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

package/DESIGN-SYSTEM.md

@@ -1,8 +1,9 @@
-# Xenon design-system audit
+# Xenon Design System
 
-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.
+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
 
@@ -16,66 +17,104 @@ Xenon has four layers:
 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.
+This separation keeps foundations, components, patterns, and layouts independently reusable while
+preserving a coherent API and visual language.
 
-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.
+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
 
-| Capability in current ZeyOS | Xenon/Zx status | Decision |
+| Front-end capability | Xenon/Zx status | Design-system boundary |
 | --- | --- | --- |
-| Buttons, inputs, toggles, dates, selects, checklists, tags | Covered by public components | Replace `UI.new*` families incrementally and preserve value/event contracts. |
+| 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 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. |
+| Sorting, selection, dynamic/local filtering, pagination, trees/finder | Covered | `Filter` authors typed nested expressions; `DataFilter` executes simple local predicates. Backend query compilation stays in adapters. |
+| Editable billing/transaction rows | Covered at generic-grid level | `Grid.BillingItems()` composes single-click typed currency/unit editors, flat hierarchy, same-parent row movement, and column visibility 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 | Partial | Build patterns on `Select`, Table, Panel, and ContextMenu after the shell blockers. |
+| Local product/module icons | Covered | `AppIcon` is generic; `zeyosAppIcon()` maps every current ZeyOS module/entity identity and accepts an offline glyph override. The optional remote Font Awesome kit is never loaded automatically. |
+| 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. |
 
+## Current ZeyOS delta audit (25 August 2026)
+
+This is a source audit, not a visual inventory. The comparison uses the current ZeyOS DOM/UI
+implementation as evidence: its generic control catalogue is concentrated in
+[`4-ui.orig.js`](../zeyos/ext/global.orig/4-ui.orig.js), configurable index-column management in
+[`4-pg.orig.js`](../zeyos/ext/global.orig/4-pg.orig.js#L3464), and the multi-view scheduling surface
+in [`calendar.orig.js`](../zeyos/ext/mod/calendar.orig.js#L61). Capabilities already represented by
+a Zx component or a documented composition are not counted as gaps.
+
+### Already closed by Zx core
+
+| ZeyOS behavior | Source evidence | Xenon/Zx coverage |
+| --- | --- | --- |
+| Dynamic search/filter authoring and saved filter controls | [`UI.newSearch`](../zeyos/ext/global.orig/4-ui.orig.js#L3378) and [`UI.newContainerFilters`](../zeyos/ext/global.orig/4-ui.orig.js#L7723) | `Filter` supplies a typed/versioned AST editor; `DataFilter` remains the lightweight local-row helper. A compiler and persistence service are intentionally not core. |
+| Editable transaction rows and row movement | [`_newTblAddColEdit`](../zeyos/ext/global.orig/4-ui.orig.js#L5613) and [`newTblItems`](../zeyos/ext/global.orig/4-ui.orig.js#L6070) | `Table`/`Grid.BillingItems()` cover typed editing, currencies/units, hierarchy, single-click entry, same-parent drag/keyboard reorder, and show/hide columns. |
+| Entity selection, priority, status, and permission choices | [`newSelEntity`](../zeyos/ext/global.orig/4-ui.orig.js#L3296), [`newSelPriority`](../zeyos/ext/global.orig/4-ui.orig.js#L3101), and the surrounding Select family | `Select.entity()`, `.priority()`, `.status()`, and `.permission()` cover the interaction contract; the ZeyOS adapter owns schemas and localized catalogues. |
+| Application launcher and module/entity identity | [`newExpLst`](../zeyos/ext/global.orig/4-ui.orig.js#L4355) and entity/module item builders through line 4457 | `Launcher`, `AppIcon`, and the optional ZeyOS adapter cover the full app catalogue, current/pinned state, recent records, grouped abortable search, forks/weblets, and injected routing. |
+| Expanded/minimized/horizontal app navigation | Current shell navigation plus the same module identity catalogue | One public `AppSidebar` owns all presentations. The rail renderer is an internal presenter, not a second component; only expanded vertical branches render inline and rail branches use anchored flyouts. |
+| Toasts, loading, cards, dialogs, forms, grids, charts, and layout primitives | Multiple `newContainer*`, input, table, and progress families in `4-ui.orig.js` | Covered by existing Zx components and documented composition; these are not delta items merely because the legacy factory names differ. |
+
+### Recommended additions to Zx core
+
+| Priority | Missing reusable contract | Evidence and proposed boundary |
+| --- | --- | --- |
+| P0 | **EntityRef** | ZeyOS has a large family of linked/static entity presentations with subtitle, owner/group/assignee context, fork, and record actions: [`newLinkEntity*`](../zeyos/ext/global.orig/4-ui.orig.js#L225) and [`newEntityStatic`/`newEntity*`](../zeyos/ext/global.orig/4-ui.orig.js#L8262). A generic `EntityRef` should own icon/title/subtitle/metadata/link/action semantics; ZeyOS routing, permissions, and context menus remain injected. `Card` is too large for dense table/feed rows. |
+| P0 | **FileItem / FileList** | Existing-file, temporary-file, waiting/progress, MIME, size, and download rows recur in [`newFile`, `newFileTemp`, and `newFileWait`](../zeyos/ext/global.orig/4-ui.orig.js#L8158). `FieldUpload` owns selection/upload but not durable file presentation. Core should render file identity/state/actions; transport, authorization, preview, and download URLs stay with the host. |
+| P0 | **ActivityList / ActivityItem** | [`newFeed`](../zeyos/ext/global.orig/4-ui.orig.js#L8704) combines chronological records, comments, attachments, likes, and incremental updates. Core should own an accessible chronological list, grouping, loading/empty state, and action slots. Posting, reactions, channels, permissions, and persistence remain application code. |
+| P1 | **Scheduler** | The current calendar implements agenda/day/week/month/year views, timed and spanning items, keyboard/routing affordances, and dense collision layout in [`calendar.orig.js`](../zeyos/ext/mod/calendar.orig.js#L61). A generic scheduler is a real core gap, but should be a separate workstream with interval-layout and accessibility invariants; recurrence, DAV, permissions, and routes are adapters/application logic. |
+| P1 | **FacetList** | Counted activity/status/tag/entity side filters appear in [`newNavActivityStatus`](../zeyos/ext/global.orig/4-ui.orig.js#L3967), `newNavTag`, and `newNavEntity`. `Filter` is an expression author, not a compact persistent facet navigator. Core should own selection/count/collapse/loading behavior; query mapping stays injected. |
+| P1 | **EditorHost** | ZeyOS uses plain/Markdown/contenteditable/iframe editors through [`newEditor`](../zeyos/ext/global.orig/4-ui.orig.js#L1607) and `newFrameEditor`. Like `Chart`, core should provide labels, toolbar/action slots, value/lifecycle, dirty/read-only/error states, and an injected engine adapter. Sanitization and document/media policy must not be implicit core behavior. |
+| P1 | **ColorPicker** | The reusable swatch picker is [`newCl`](../zeyos/ext/global.orig/4-ui.orig.js#L3753). A dependency-free accessible swatch/custom-color picker belongs in core and would also serve the Theme Studio. |
+| P2 | **Metric / Summary** | [`newSummary`](../zeyos/ext/global.orig/4-ui.orig.js#L7312) repeatedly formats counts, money, timing, size, stock, and relative values. These can currently be composed from Card and format helpers, but a small semantic Metric/DescriptionList pair would remove repeated markup without importing business formulas. |
+| P2 | **RecordPreview** | Typed preview builders for appointments, contacts, links, messages, tasks, and tickets start at [`newPreviewForm`](../zeyos/ext/global.orig/4-ui.orig.js#L9589). Core should offer a generic preview anatomy or engine-neutral preview host, not one component per ZeyOS entity. |
+| P2 | **Shortcut / Kbd** | Launcher and menus expose shortcuts but Zx has no reusable semantic `<kbd>` treatment. A tiny factory is justified once shortcuts appear outside those components. |
+
+### Adapter work, not new core components
+
+- A **ZeyOS Filter compiler** mapping allowlisted AST field/operator IDs to the server's plural
+  `filters` query shape, plus a parser for stored legacy filter state. Compilation must use bound/
+  structured values and never accept raw SQL or URL fragments.
+- A shared **ZeyOS field/status/priority catalogue** built from runtime schemas and localization,
+  feeding `Field`, `Filter`, `Select.status()`, and `Select.priority()` without hard-coding
+  entity-specific policy in core.
+- **EntityRef/FileItem/ActivityList adapters** that resolve routes, icons, permissions, server
+  payloads, and action menus while leaving their visual/interaction contracts reusable.
+- Optional persistence connectors for column visibility/order, sidebar state, saved filters, recent
+  items, and theme preferences. Core should expose serializable state and events only.
+
+### Deliberately application-owned
+
+Routing/history, authentication/session/logout, authorization, server transport/caching, saved-view
+storage, audit policy, transaction tax/discount/subtotal/posting formulas, optimistic writes/undo,
+calendar recurrence/DAV synchronization, rich-text sanitization, and activity actions are not
+design-system responsibilities. Moving them into Zx would reproduce ZeyOS application logic inside
+the library and make Xenon less reusable.
+
 ### 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.
+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
 
-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.
+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
 
@@ -111,26 +150,3 @@ owns loading/empty/error states, and mirrors its data in an accessible table. Ch
 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/README.md

@@ -1,10 +1,10 @@
 # Xenon Design System (Zx)
 
-Xenon is the dependency-free design system for ZeyOS business 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. An opt-in compatibility
-layer remains available for genuine MooTools-era `gx` applications while they are 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.
@@ -41,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`
@@ -99,7 +99,7 @@ ZeyOS binding — see `src/zeyos/modules.js`.
 | `Toggle` | Native-button switch with a separate submitted value. |
 | `Search` | Search input with debounced input, submit, and clear events. |
 | `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 fixed items, and priority/permission presets. |
+| `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. |
@@ -158,12 +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 vertical application navigation with inline disclosure children. |
-| `AppRail` | Minimized vertical/horizontal application navigation with flyout-only descendants. |
+| `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. |
@@ -297,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
 ```
@@ -313,28 +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.
+Additional entry points: `@zeyos/zx/zeyos` (the schema-driven ZeyOS binding) 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 for gx-era free functions; an existing ZeyOS __() is preserved:
-  gx.compat.installGlobals();
-</script>
-```
-
-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()`; it never replaces an existing `__`.
-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/app-icon/app-icon.d.ts

@@ -0,0 +1,88 @@
+import { Component } from '../../core/component.js';
+export type AppIconOptions = {
+    /**
+     * Icon name, node, or lazy renderer.
+     */
+    icon?: string | Node | (() => string | Node) | null;
+    /**
+     * Identity colour; falls back to the accent colour.
+     */
+    color?: string | null;
+    /**
+     * Edge length in pixels or any CSS length.
+     */
+    size?: number | string;
+    /**
+     * Glyph size.
+     */
+    iconSize?: number | string;
+    /**
+     * Accessible image label; null makes the icon decorative.
+     */
+    label?: string | null;
+    /**
+     * Optional corner badge.
+     */
+    badge?: string | number | null;
+    /**
+     * Whether the icon represents the active application.
+     */
+    selected?: boolean;
+    /**
+     * CSS-first glass treatment.
+     */
+    glass?: false | 'subtle' | 'strong';
+    /**
+     * Additional class names.
+     */
+    class?: string | string[];
+};
+/**
+ * @typedef {Object} AppIconOptions
+ * @property {string|Node|(()=>string|Node)|null} [icon=null] Icon name, node, or lazy renderer.
+ * @property {string|null} [color=null] Identity colour; falls back to the accent colour.
+ * @property {number|string} [size=36] Edge length in pixels or any CSS length.
+ * @property {number|string} [iconSize='52%'] Glyph size.
+ * @property {string|null} [label=null] Accessible image label; null makes the icon decorative.
+ * @property {string|number|null} [badge=null] Optional corner badge.
+ * @property {boolean} [selected=false] Whether the icon represents the active application.
+ * @property {false|'subtle'|'strong'} [glass='subtle'] CSS-first glass treatment.
+ * @property {string|string[]} [class] Additional class names.
+ */
+/**
+ * Stable application-identity tile with progressive CSS glass treatment.
+ * @extends {Component<AppIconOptions>}
+ */
+export declare class AppIcon extends Component<AppIconOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _state: {
+        icon?: string | Node | (() => string | Node) | null;
+        color?: string | null;
+        size?: number | string;
+        iconSize?: number | string;
+        label?: string | null;
+        badge?: string | number | null;
+        selected?: boolean;
+        glass?: false | 'subtle' | 'strong';
+        class?: string | string[];
+    };
+    _appliedClasses: any[] | string[];
+    static cssName: string;
+    /** @type {Readonly<AppIconOptions>} */
+    static defaults: Readonly<AppIconOptions>;
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Updates identity or presentation without replacing the root. @param {Partial<AppIconOptions>} values @returns {this} */
+    set(values?: Partial<AppIconOptions>): this;
+    /** Restores an enhanced target. @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _sync(): void;
+}
+/**
+ * Creates an AppIcon element without retaining a component lifecycle handle.
+ * @param {AppIconOptions} [options={}] Icon options.
+ * @returns {HTMLElement}
+ */
+export declare function appIcon(options?: AppIconOptions): HTMLElement;