@zeyos/zx 4.0.0 → 4.1.1

package/docs/api.json

@@ -130,6 +130,79 @@
     "events": [],
     "methods": []
   },
+  "AppIcon": {
+    "options": [
+      {
+        "name": "icon",
+        "type": "string|Node|(()=>string|Node)|null",
+        "default": "null",
+        "description": "Icon name, node, or lazy renderer."
+      },
+      {
+        "name": "color",
+        "type": "string|null",
+        "default": "null",
+        "description": "Identity colour; falls back to the accent colour."
+      },
+      {
+        "name": "size",
+        "type": "number|string",
+        "default": "36",
+        "description": "Edge length in pixels or any CSS length."
+      },
+      {
+        "name": "iconSize",
+        "type": "number|string",
+        "default": "'52%'",
+        "description": "Glyph size."
+      },
+      {
+        "name": "label",
+        "type": "string|null",
+        "default": "null",
+        "description": "Accessible image label; null makes the icon decorative."
+      },
+      {
+        "name": "badge",
+        "type": "string|number|null",
+        "default": "null",
+        "description": "Optional corner badge."
+      },
+      {
+        "name": "selected",
+        "type": "boolean",
+        "default": "false",
+        "description": "Whether the icon represents the active application."
+      },
+      {
+        "name": "glass",
+        "type": "false|'subtle'|'strong'",
+        "default": "'subtle'",
+        "description": "CSS-first glass treatment."
+      },
+      {
+        "name": "class",
+        "type": "string|string[]",
+        "default": null,
+        "description": "Additional class names."
+      }
+    ],
+    "events": [],
+    "methods": [
+      {
+        "name": "set",
+        "signature": "set(values)",
+        "returns": "this",
+        "description": "Updates identity or presentation without replacing the root."
+      },
+      {
+        "name": "destroy",
+        "signature": "destroy()",
+        "returns": "void",
+        "description": "Restores an enhanced target."
+      }
+    ]
+  },
   "AppSidebar": {
     "options": [
       {
@@ -2456,6 +2529,54 @@
     "events": [],
     "methods": []
   },
+  "EntitySelect": {
+    "options": [
+      {
+        "name": "recent",
+        "type": "SelectItem[]",
+        "default": "[]",
+        "description": "Choices pinned above ordinary results."
+      },
+      {
+        "name": "recentLabel",
+        "type": "string",
+        "default": "'Recent'",
+        "description": "Heading above recent choices."
+      },
+      {
+        "name": "create",
+        "type": "boolean|SelectAction",
+        "default": "false",
+        "description": "Optional create command at the bottom."
+      },
+      {
+        "name": "iconKey",
+        "type": "string|((item: SelectItem)=>unknown)",
+        "default": "'icon'",
+        "description": "Item icon reader."
+      },
+      {
+        "name": "colorKey",
+        "type": "string|((item: SelectItem)=>unknown)",
+        "default": "'color'",
+        "description": "Optional icon colour reader."
+      },
+      {
+        "name": "subtitleKey",
+        "type": "string|((item: SelectItem)=>unknown)",
+        "default": "'description'",
+        "description": "Secondary-text reader."
+      },
+      {
+        "name": "renderIcon",
+        "type": "((item: SelectItem, context:{selected:boolean})=>Node|string|null)|null",
+        "default": "null",
+        "description": "Entity icon renderer."
+      }
+    ],
+    "events": [],
+    "methods": []
+  },
   "Field": {
     "options": [
       {
@@ -2832,6 +2953,176 @@
       }
     ]
   },
+  "Filter": {
+    "options": [
+      {
+        "name": "fields",
+        "type": "FilterField[]",
+        "default": null,
+        "description": "Field definitions."
+      },
+      {
+        "name": "value",
+        "type": "FilterAst",
+        "default": null,
+        "description": "Initial expression."
+      },
+      {
+        "name": "operators",
+        "type": "Array<{id:string,label:string,arity:'none'|'single'|'pair'|'many',types:string[]}>",
+        "default": null,
+        "description": "Additional/overridden operators."
+      },
+      {
+        "name": "allowGroups",
+        "type": "boolean",
+        "default": "true",
+        "description": "Whether nested groups may be authored."
+      },
+      {
+        "name": "maxDepth",
+        "type": "number",
+        "default": "3",
+        "description": "Maximum nested group depth."
+      },
+      {
+        "name": "maxConditions",
+        "type": "number",
+        "default": "50",
+        "description": "Maximum condition count."
+      },
+      {
+        "name": "autoApply",
+        "type": "boolean",
+        "default": "false",
+        "description": "Emit apply after every valid mutation."
+      },
+      {
+        "name": "readonly",
+        "type": "boolean",
+        "default": "false",
+        "description": "Prevent mutations while keeping values readable."
+      },
+      {
+        "name": "disabled",
+        "type": "boolean",
+        "default": "false",
+        "description": "Disable all controls."
+      },
+      {
+        "name": "applyLabel",
+        "type": "string",
+        "default": "'Apply filters'",
+        "description": "Apply button label."
+      },
+      {
+        "name": "clearLabel",
+        "type": "string",
+        "default": "'Clear'",
+        "description": "Clear button label."
+      }
+    ],
+    "events": [
+      {
+        "name": "change",
+        "payload": "Record<string,unknown>",
+        "description": "Draft-change listener."
+      },
+      {
+        "name": "apply",
+        "payload": "Record<string,unknown>",
+        "description": "Valid-apply listener."
+      },
+      {
+        "name": "invalid",
+        "payload": "Record<string,unknown>",
+        "description": "Invalid-apply listener."
+      },
+      {
+        "name": "query",
+        "payload": "Record<string,unknown>",
+        "description": "Async query listener."
+      },
+      {
+        "name": "loaded",
+        "payload": "Record<string,unknown>",
+        "description": "Async loaded listener."
+      },
+      {
+        "name": "error",
+        "payload": "Record<string,unknown>",
+        "description": "Async failure listener."
+      }
+    ],
+    "methods": [
+      {
+        "name": "getValue",
+        "signature": "getValue()",
+        "returns": "FilterAst",
+        "description": "Returns a defensive AST copy."
+      },
+      {
+        "name": "setValue",
+        "signature": "setValue(value, [options])",
+        "returns": "this",
+        "description": "Atomically replaces the AST."
+      },
+      {
+        "name": "addCondition",
+        "signature": "addCondition([parentId], [initial])",
+        "returns": "string|null",
+        "description": "Adds a condition to a group."
+      },
+      {
+        "name": "addGroup",
+        "signature": "addGroup([parentId], [logic])",
+        "returns": "string|null",
+        "description": "Adds a nested group."
+      },
+      {
+        "name": "update",
+        "signature": "update(id, patch)",
+        "returns": "this",
+        "description": "Updates a node by stable ID."
+      },
+      {
+        "name": "remove",
+        "signature": "remove(id)",
+        "returns": "this",
+        "description": "Removes a non-root node."
+      },
+      {
+        "name": "move",
+        "signature": "move(id, parentId, index)",
+        "returns": "this",
+        "description": "Moves a node into a group while preserving its identity."
+      },
+      {
+        "name": "validate",
+        "signature": "validate()",
+        "returns": "{valid:boolean,errors:Array<Record<string,string>>}",
+        "description": "Returns semantic validity and errors."
+      },
+      {
+        "name": "apply",
+        "signature": "apply()",
+        "returns": "FilterAst|null",
+        "description": "Applies only a valid AST."
+      },
+      {
+        "name": "clear",
+        "signature": "clear([options])",
+        "returns": "this",
+        "description": "Clears all conditions."
+      },
+      {
+        "name": "focus",
+        "signature": "focus([id])",
+        "returns": "this",
+        "description": "Focuses a condition's field or the Add button."
+      }
+    ]
+  },
   "Finder": {
     "options": [
       {
@@ -5025,6 +5316,12 @@
         "default": "[]",
         "description": "Choices pinned above the list, kept through filtering and async loads."
       },
+      {
+        "name": "fixedLabel",
+        "type": "string|null",
+        "default": "null",
+        "description": "Optional heading above pinned choices."
+      },
       {
         "name": "valueKey",
         "type": "SelectValueReader",
@@ -5245,6 +5542,12 @@
         "returns": "Select",
         "description": "Creates a status picker with shape- and color-distinct workflow indicators."
       },
+      {
+        "name": "entity",
+        "signature": "entity(target, [options])",
+        "returns": "Select",
+        "description": "Creates a rich entity picker with optional Recent choices and a create command."
+      },
       {
         "name": "permission",
         "signature": "permission(target, [options])",
@@ -6379,6 +6682,30 @@
         "default": "false",
         "description": "Inline editing mode. `'cell'` edits one cell, `'row'` opens every editable cell of the row together and commits them as a unit. Editing is completely inert while this is `false`."
       },
+      {
+        "name": "editTrigger",
+        "type": "'single'|'double'",
+        "default": "'double'",
+        "description": "Gesture that starts an editable cell."
+      },
+      {
+        "name": "rowReorder",
+        "type": "boolean",
+        "default": "false",
+        "description": "Whether rows expose pointer/keyboard reorder handles."
+      },
+      {
+        "name": "columnVisibility",
+        "type": "boolean",
+        "default": "false",
+        "description": "Whether a column visibility chooser is rendered."
+      },
+      {
+        "name": "hiddenColumns",
+        "type": "string[]",
+        "default": "[]",
+        "description": "Initially hidden column IDs; at least one stays visible."
+      },
       {
         "name": "hierarchy",
         "type": "false|TableHierarchyOptions",
@@ -6446,6 +6773,16 @@
         "name": "rowtoggle",
         "payload": "{row, id, expanded}",
         "description": ""
+      },
+      {
+        "name": "rowmove",
+        "payload": "{row, id, target, targetId, position}",
+        "description": ""
+      },
+      {
+        "name": "columnvisibilitychange",
+        "payload": "{visible:string[],hidden:string[]}",
+        "description": ""
       }
     ],
     "methods": [
@@ -6491,6 +6828,36 @@
         "returns": "TableRow[]",
         "description": "Returns a shallow copy of the current rows in display order."
       },
+      {
+        "name": "getVisibleColumns",
+        "signature": "getVisibleColumns()",
+        "returns": "string[]",
+        "description": "Returns visible column IDs in caller order."
+      },
+      {
+        "name": "getHiddenColumns",
+        "signature": "getHiddenColumns()",
+        "returns": "string[]",
+        "description": "Returns hidden column IDs in caller order."
+      },
+      {
+        "name": "setColumnVisible",
+        "signature": "setColumnVisible(id, [visible], [options])",
+        "returns": "this",
+        "description": "Shows or hides one column. The final visible column cannot be hidden."
+      },
+      {
+        "name": "toggleColumn",
+        "signature": "toggleColumn(id, [options])",
+        "returns": "this",
+        "description": "Toggles one column."
+      },
+      {
+        "name": "moveRow",
+        "signature": "moveRow(id, targetId, [position])",
+        "returns": "this",
+        "description": "Reorders one row relative to another and emits a cancelable `rowmove` before committing. Hierarchical rows may only move among siblings; an active local sort disables manual order."
+      },
       {
         "name": "empty",
         "signature": "empty()",
@@ -6669,6 +7036,18 @@
         "default": "'name'",
         "description": "Item label property or reader."
       },
+      {
+        "name": "iconKey",
+        "type": "TagValueReader",
+        "default": "'icon'",
+        "description": "Optional item icon property or reader."
+      },
+      {
+        "name": "colorKey",
+        "type": "TagValueReader",
+        "default": "'color'",
+        "description": "Optional item colour property or reader."
+      },
       {
         "name": "searchKeys",
         "type": "Array<TagValueReader>|null",

package/docs/llms.md

@@ -73,6 +73,11 @@ renders every component family live and exports the CSS):
 Keep the 600 stop at 4.5:1 or better against white and the 400 stop at 4.5:1 against the dark page
 — that is what makes `--zx-color-on-accent` legible without being restated per theme.
 
+The theme studio treats those stable IDs as complete recipes: selecting a preset also changes its
+density, neutral tint, radius, control height, base text size, font stack, and material strength.
+Its **Material** control is CSS-first (`Flat`, `Glass`, or `Deep glass`); only the deep setting uses
+backdrop blur, and components fall back to solid surfaces under reduced-transparency preferences.
+
 Define a product theme by overriding **semantic** tokens under a `[data-zx-theme="name"]` selector:
 `--zx-color-bg-page/surface/raised/control/hover/selected`, `--zx-color-border(-strong/-control)`,
 `--zx-color-text(-muted/-placeholder)`, `--zx-color-accent(-hover)/on-accent`,
@@ -189,8 +194,8 @@ registerModules({ tickets: '#f04639', 'my-fork': { label: 'My Fork', icon: 'zeyo
 - `moduleIcon(name, {size, label, standard})` → the bare glyph; `standard: true` uses the stock
   Font Awesome fallback, for pages on a kit without the ZeyOS uploads.
 - `moduleChip(name, {size, iconSize, label, title, standard})` → `<span class="zx-module-icon">`
-  with the glyph on the module colour. The glyph colour is whichever of ZeyOS's two foregrounds
-  (`#ffffff`, `#141414`) contrasts better, via `moduleGlyphColor(hex)`.
+  with a centred white glyph on the module colour. `moduleGlyphColor(hex)` remains available as a
+  separate contrast helper for non-AppIcon integrations that deliberately choose their foreground.
 - `moduleInfo`/`moduleColor`/`moduleIconName`/`moduleKeys`/`normalizeModuleName` read the config.
   Module, entity, and API resource names are all accepted, case-insensitively, with dots and
   underscores normalized: `'transactions.billing'`, `'invoices'`, and `'Transactions Billing'` all
@@ -445,6 +450,32 @@ permissions, recent-history/cache policy, and the route or command ultimately in
   taking over application routing.
 <!-- /doc -->
 
+<!-- doc:app-icon -->
+### AppIcon — application identity
+
+A fixed-size, product-agnostic application tile. It keeps glyph geometry stable in launchers,
+sidebars, entity results, and recent-item rows while identity colour and material remain explicit
+options rather than application globals.
+
+- **Options** — `icon` (bundled name, Node, or lazy renderer), `color`, `size: 36`,
+  `iconSize: '52%'`, `label`, `badge`, `selected: false`, `glass: false|'subtle'|'strong'`, and
+  additional `class` names.
+- **Methods** — `set(partialOptions)` updates the existing root; `destroy()` restores an enhanced
+  target. `appIcon(options)` is the element-returning convenience factory.
+- **ZeyOS preset** — import `zeyosAppIcon(module, options)` from `@zeyos/zx/zeyos`. Every current
+  ZeyOS application/module has a canonical colour and icon mapping in `src/zeyos/modules.js`;
+  entity names and aliases resolve through the same catalogue. `moduleChip()` is the compatible
+  alias. An application may call `useZeyosIcons()` for the existing custom glyph kit or inject an
+  offline `icon` override; Zx never loads a network asset automatically.
+- **Material** — subtle glass is a CSS border/highlight treatment; strong glass progressively adds
+  `backdrop-filter`. `prefers-reduced-transparency` and browsers without support receive a solid
+  tile. Glyphs remain white and geometrically centred in either built-in SVG or Font Awesome form;
+  hover and focus feedback use the same semantic material tokens. The glyph and label semantics do
+  not depend on the visual treatment.
+- **Accessibility** — a non-empty `label` gives the root `role="img"`; otherwise it is decorative.
+  The badge is visual supplementary status, so include its meaning in `label` when it matters.
+<!-- /doc -->
+
 <!-- doc:avatar -->
 ### Avatar
 
@@ -483,7 +514,7 @@ out, or mutates the session.
 
 Unifies single-select, local filtering, and async loading.
 
-- **Options** — `items: []`, `fixedItems: []`, `valueKey: 'ID'` (string key or `(item)=>id`),
+- **Options** — `items: []`, `fixedItems: []`, optional `fixedLabel`, `valueKey: 'ID'` (string key or `(item)=>id`),
   `labelKey: 'name'` (string or `(item)=>string`), `renderItem`, `renderValue`,
   `renderValueAdornment`, `renderNone`, `noneLabel`, `actions`, `value`, `disabled`, `placeholder`,
   `clearable: false`, `filter: false | 'local' | async (query)=>items`, `searchKeys`,
@@ -504,11 +535,13 @@ Unifies single-select, local filtering, and async loading.
   and accepts replacement `items`; `Select.permission(target, {groups, value})` pins Private and
   Public above record-access groups. Its value is the tri-state ZeyOS stores (`false` private,
   `true` public, or a group ID), and `groups` takes an array or loader `(query)=>items`.
-- **ZeyOS entity preset** — import `zeyosEntitySelect(client, resource, options)` or the DOM-free
-  `buildZeyosEntitySelectConfig()` from `@zeyos/zx/zeyos`. It composes the async client binding
-  with module-colored icons, subtitle/group readers, a deliberate none row, and an optional
-  application-owned create command. The selected value remains the record ID and exact product
-  glyphs stay injectable through `renderIcon`.
+- **Entity preset** — `Select.entity(target, options)` renders icon/color, label, and secondary
+  text using `iconKey`, `colorKey`, and `subtitleKey` (or `renderIcon`). `recent` pins a deduplicated
+  **Recent** section above ordinary/local/async results; `create: true|actionDescriptor` appends an
+  application-owned command at the bottom without changing the selected ID. `recentLabel` and the
+  ordinary Select options remain overridable. For schema-driven ZeyOS loading,
+  `zeyosEntitySelect(client, resource, options)` and `buildZeyosEntitySelectConfig()` compose this
+  preset from `@zeyos/zx/zeyos`; the core preset itself is backend-neutral.
 - **Keyboard** (APG combobox) — ArrowDown/Alt+ArrowDown open; arrows navigate and wrap; Home/End;
   Enter selects; Esc closes; Tab closes; printable characters filter (editable) or run a typeahead
   (readonly). `aria-activedescendant` tracks the active option.
@@ -707,6 +740,8 @@ use `TimePicker` or `DateTimeBox`.
 
 Floating toasts come from statics; `new Message(target)` gives an inline, non-floating area with
 the same `.show()`. The toast region is `role="status"`/`aria-live` (`role="alert"` for errors).
+The shared floating region is fixed to the upper-right logical corner by default, sizes to its
+messages rather than the page, and uses the translucent glass surface tokens with a solid fallback.
 
 - **Statics** — `Message.info/success/warning/error(msg, opts)`,
   `Message.show(msg, { kind, timeout=4000, closable })` → `{ close() }`,
@@ -947,7 +982,8 @@ range select.
   `toggleRow()`, `expandRow()`, `collapseRow()`, `expandAll()`, `collapseAll()`, and
   `getExpanded()`. The native disclosure button works by pointer and keyboard without selecting
   or clicking the row.
-- **Editing** — `editMode: false|'cell'|'row'` (default `false`, and completely inert until set).
+- **Editing** — `editMode: false|'cell'|'row'` (default `false`, and completely inert until set),
+  plus `editTrigger: 'double'|'single'` (Table defaults to double; Grid defaults to single).
   `'cell'` edits one cell, `'row'` opens every editable cell of the row and commits them as a unit.
   Editors are sized into the cell without changing row height, and an editing cell carries
   `data-editing="true"` (`data-invalid="true"` plus an `aria-live` message when a validator rejects).
@@ -980,7 +1016,8 @@ range select.
   commit with no changes emits `editcommit` with an empty `changes` map and leaves the data alone.
   Sorting, filtering, or `setData()` while editing cancels the edit cleanly and emits `editcancel`.
 - **Editing keyboard** — Enter or F2 on a focused editable cell starts editing (editable cells share
-  one roving tab stop), double-click starts editing without emitting `rowdblclick`, Enter commits and
+  one roving tab stop); the configured single/double pointer gesture starts it without emitting
+  `rowdblclick`. Enter commits and
   returns focus to the cell (Shift+Enter stays a newline in a `'textarea'`, Space toggles a
   `'checkbox'`), Escape cancels and returns focus to the cell, Tab commits and moves to the next
   editable cell (Shift+Tab the previous), wrapping across rows, and tabbing past the last editable
@@ -1006,6 +1043,14 @@ range select.
 - **Empty state** — `emptyText` takes a string, a Node, or a function returning one, so an empty
   table can carry an icon, an explanation, and the action that resolves it (`emptyState({…})`).
   A function is re-called on every render, which is what to use when the placeholder holds controls.
+- **Row order** — `rowReorder: true` adds a dedicated drag handle. Pointer drag moves rows before
+  or after a sibling; Space/Enter grabs/releases the same handle and ArrowUp/ArrowDown moves it for
+  keyboard users. `moveRow(id, targetId, position)` exposes the same guarded operation. Hierarchical
+  rows only move among siblings, and an active local sort disables manual order. A cancelable
+  `rowmove {row,id,target,targetId,position}` fires before `datachange`.
+- **Column visibility** — `columnVisibility: true` renders a chooser; `hiddenColumns` seeds it.
+  `getVisibleColumns()`, `getHiddenColumns()`, `setColumnVisible()`, and `toggleColumn()` preserve
+  caller column order and never allow the final visible column to disappear.
 <!-- /doc -->
 
 <!-- doc:grid -->
@@ -1015,9 +1060,11 @@ range select.
 without forking its implementation, so sorting, selection, hierarchy, responsive stacking,
 editable cells/rows, loading, events, and teardown keep the Table contract.
 
-- **Constructor** — `new Grid(target, tableOptions)` accepts the complete `Table` API.
+- **Constructor** — `new Grid(target, tableOptions)` accepts the complete `Table` API and defaults
+  editable cells to a single-click trigger.
 - **Preset** — `Grid.BillingItems(target, options)` supplies an editable hierarchical billing
-  schema for item, quantity, unit, unit price, currency, and line total. It returns a `Grid`.
+  schema for item, quantity, unit, unit price, currency, and line total. It enables single-click
+  editing, hierarchy, row reorder handles, and the column visibility chooser. It returns a `Grid`.
 - **Billing options** — `data`, `fields` key overrides, `units`, `currencies`, fallback `currency`,
   `locale`, `decimals`, `columnOverrides`, complete `columns` replacement, `lineTotal(row, changes)`,
   and `oneditcommit` in addition to ordinary Table options.
@@ -1068,6 +1115,35 @@ Declarative client-side filter bar producing a filtered array, commonly wired to
 - **Events** — `filter {rows, state}`.
 <!-- /doc -->
 
+<!-- doc:filter -->
+### Filter — dynamic backend-neutral expressions
+
+An authoring component for typed, nested filter expressions. It never evaluates application data
+or interpolates query text: it emits a versioned, JSON-safe AST for an allowlisted application
+adapter to compile into its own backend query language.
+
+- **AST** — `{version: 1, root: {kind:'group', id, logic:'and'|'or', children}}`; children are
+  stable-ID groups or `{kind:'condition', id, field, operator, value}` records. Unknown field or
+  operator IDs survive parsing and render as unavailable/invalid instead of being silently lost.
+- **Fields** — `{id,label,type,operators?,defaultOperator?,choices?,loadChoices?,editor?,minQuery?,
+  debounce?}`. Built-in types cover text, number/money, date/datetime, boolean, enum/status/
+  priority/country/currency/unit/entity, and tags. Compatible operators and their arity come from
+  the exported `filterOperators` matrix; applications may explicitly override/add operator IDs.
+- **Options** — `fields`, `value`, `operators`, `allowGroups: true`, `maxDepth: 3`,
+  `maxConditions: 50`, `autoApply: false`, `readonly`, `disabled`, `applyLabel`, `clearLabel`.
+- **Methods** — `getValue()`, atomic `setValue()`, `addCondition()`, `addGroup()`, `update()`,
+  `remove()`, `move()`, `validate()`, `apply()`, `clear()`, `focus()`, `setReadonly()`,
+  `enable()`/`disable()`.
+- **Events** — `change {value,valid,errors,reason,nodeId}`, `apply {value}`, `invalid {errors}`,
+  and abortable async-choice lifecycle `query`, `loaded`, `error`. `apply()` returns null and
+  focuses the first invalid condition when validation fails.
+- **Pure exports** — `emptyFilterAst`, `filterCondition`, `filterGroup`, `parseFilterAst`,
+  `cloneFilterAst`, `cloneFilterValue`, `stringifyFilterAst`, and `validateFilterAst`.
+- **Boundary** — keep the AST in saved views/audit state and compile it in a backend-specific
+  adapter with an allowlist and bound parameters. Do not put SQL, URL query fragments, functions,
+  DOM nodes, Dates, non-finite numbers, or other executable/non-JSON values into conditions.
+<!-- /doc -->
+
 <!-- doc:tree -->
 ### TreeView
 
@@ -1278,10 +1354,13 @@ shows a fixed set, and `ValueList` takes free text with no catalogue. Unknown ID
 `setValues` still render as tags, so a stored selection survives a catalogue that has not loaded
 yet. Field type: `tagpicker`.
 
-- **Options** — `items`, `values: []`, `valueKey: 'ID'`, `labelKey: 'name'`, `searchKeys`,
+- **Options** — `items`, `values: []`, `valueKey: 'ID'`, `labelKey: 'name'`, `iconKey: 'icon'`,
+  `colorKey: 'color'`, `searchKeys`,
   `filter: 'local'|(query)=>Promise<items>`, `minQuery: 0`, `debounce: 200`, `allowCreate: false`,
   `max` (maximum tags; further options become `aria-disabled`), `closeOnSelect: false`,
   `placeholder`, `listHeight: 260`, `disabled`, `readonly`, `renderItem`, `renderTag`.
+- **Tag identity** — icon values accept a bundled icon name or Node; colors are scoped to the tag
+  and its option through `--zx-tag-color`. Custom `renderItem`/`renderTag` remain authoritative.
 - **Methods** — `getValues()`, `getItems()`, `setValues(values, {silent})`, `addValue()`,
   `removeValue()`, `clear()`, `reset()`, `setItems()`, `isFull()`, `open()`/`close()`, `focus()`,
   `setReadonly()`, `enable()`/`disable()`.
@@ -1584,16 +1663,16 @@ inline; every rail state opens descendants toward the workspace in anchored flyo
 
 - **Component** — the base class: `on`/`off`/`once`/`emit`, `listen`, `toElement`, `msg`,
   `destroy`, and the static `Component.from(el)`.
-- **DOM** — `h(tag, props, ...children)`, `h.raw(html)`, `htmlEscape`, `resolveElement`. The current
-  ZeyOS builder is also first-class: `__(tag#id.class, properties, content)` is the migration alias
-  for `compactElement()`. It preserves `D*` data, `S*` style, boolean/built-in property, attribute,
+- **DOM** — `h(tag, props, ...children)`, `h.raw(html)`, `htmlEscape`, `resolveElement`.
+  `__(tag#id.class, properties, content)` is Zx's compact DOM builder and public alias for
+  `compactElement()`. It preserves `D*` data, `S*` style, boolean/built-in property, attribute,
   and legacy `on*` callback rules while keeping content text-safe. `applyCompactProperties`,
   `appendContent`, `appendCompact` (parent return), `appendCompactChild` (child return), and
   `fragment(...children)` are the pure forms.
 - **Compact events** — `onCompactEvent`, `offCompactEvent`, and `fireCompactEvent` share one
   newest-first handler registry. Existing `DOM.on/remEvt/fireEvt` methods can delegate to this
-  triad. Zx never installs globals or alters DOM prototypes; the current application owns those
-  temporary seams while `UI.new*` implementations are replaced without rewriting `PG` routing.
+  triad. Zx never installs globals or alters DOM prototypes; applications decide whether to expose
+  these functions globally or compose them into their own UI and routing layer.
 - **Icons** — `icon(name, {size, label})` and `icons`; see the Icons section — bundled inline SVG
   by default, Font Awesome after an opt-in.
 - **Positioning** — `position(anchor, floating, {placement, offset, flip, matchWidth})` →