@vielzeug/codex 26.11.3 → 26.11.5

package/data/catalog.json

@@ -35,7 +35,7 @@
         "rune"
       ],
       "slug": "archive",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -108,7 +108,7 @@
         "coins"
       ],
       "slug": "arsenal",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -160,7 +160,7 @@
         "refine"
       ],
       "slug": "assay",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -199,7 +199,7 @@
         "vault"
       ],
       "slug": "beacon",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -241,7 +241,7 @@
         "ward"
       ],
       "slug": "clockwork",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -274,7 +274,7 @@
         "refine"
       ],
       "slug": "codex",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -344,7 +344,7 @@
         "spell"
       ],
       "slug": "coins",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -385,7 +385,7 @@
         "rune"
       ],
       "slug": "conduit",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -427,7 +427,7 @@
         "postmaster"
       ],
       "slug": "courier",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -473,7 +473,7 @@
         "refine"
       ],
       "slug": "dnd",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -515,7 +515,7 @@
         "herald"
       ],
       "slug": "familiar",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -582,7 +582,7 @@
         "courier"
       ],
       "slug": "flux",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -622,7 +622,7 @@
         "ore"
       ],
       "slug": "focus",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -663,7 +663,7 @@
         "assay"
       ],
       "slug": "forge",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -701,7 +701,7 @@
         "keymap"
       ],
       "slug": "gesture",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -745,7 +745,7 @@
         "familiar"
       ],
       "slug": "herald",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -788,7 +788,7 @@
         "tempo"
       ],
       "slug": "illusionist",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -833,7 +833,7 @@
         "ore"
       ],
       "slug": "keymap",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -880,7 +880,7 @@
         "vault"
       ],
       "slug": "ledger",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -926,7 +926,7 @@
         "courier"
       ],
       "slug": "lingua",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -964,7 +964,7 @@
         "herald"
       ],
       "slug": "mesh",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1001,7 +1001,7 @@
         "ore"
       ],
       "slug": "necromancer",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1041,7 +1041,7 @@
         "prism"
       ],
       "slug": "orbit",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1106,7 +1106,7 @@
         "orbit"
       ],
       "slug": "ore",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1150,7 +1150,7 @@
         "ripple"
       ],
       "slug": "postmaster",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1191,7 +1191,7 @@
         "orbit"
       ],
       "slug": "prism",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1255,7 +1255,7 @@
         "clockwork"
       ],
       "slug": "pulse",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1270,7 +1270,6 @@
         "ore-accordion",
         "ore-accordion-item",
         "ore-alert",
-        "ore-async",
         "ore-avatar",
         "ore-avatar-group",
         "ore-badge",
@@ -1288,6 +1287,7 @@
         "ore-checkbox-group",
         "ore-chip",
         "ore-code-window",
+        "ore-color-picker",
         "ore-column",
         "ore-combobox",
         "ore-combobox-option",
@@ -1326,6 +1326,7 @@
         "ore-password-strength",
         "ore-popover",
         "ore-progress",
+        "ore-pull-to-refresh",
         "ore-qr-code",
         "ore-qr-scanner",
         "ore-query-bar",
@@ -1342,6 +1343,7 @@
         "ore-speech-player",
         "ore-speed-reading",
         "ore-spotlight",
+        "ore-state",
         "ore-stats",
         "ore-step",
         "ore-stepper",
@@ -1378,7 +1380,7 @@
         "keymap"
       ],
       "slug": "refine",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1423,7 +1425,7 @@
         "ledger"
       ],
       "slug": "ripple",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1477,7 +1479,7 @@
         "familiar"
       ],
       "slug": "rune",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1518,7 +1520,7 @@
         "refine"
       ],
       "slug": "sandbox",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1569,7 +1571,7 @@
         "ripple"
       ],
       "slug": "scout",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1622,7 +1624,7 @@
         "refine"
       ],
       "slug": "scroll",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1669,7 +1671,7 @@
         "gesture"
       ],
       "slug": "sentinel",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1709,7 +1711,7 @@
         "refine"
       ],
       "slug": "sigil",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1754,7 +1756,7 @@
         "wayfinder"
       ],
       "slug": "sourcerer",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1813,7 +1815,7 @@
         "vault"
       ],
       "slug": "spell",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1854,7 +1856,7 @@
         "ripple"
       ],
       "slug": "tandem",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1898,7 +1900,7 @@
         "herald"
       ],
       "slug": "tavern",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -1966,7 +1968,7 @@
         "vault"
       ],
       "slug": "tempo",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -2017,7 +2019,7 @@
         "ripple"
       ],
       "slug": "vault",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -2063,7 +2065,7 @@
         "refine"
       ],
       "slug": "ward",
-      "version": "26.11.2"
+      "version": "26.11.4"
     },
     {
       "availableDocPages": [
@@ -2117,8 +2119,8 @@
         "herald"
       ],
       "slug": "wayfinder",
-      "version": "26.11.2"
+      "version": "26.11.4"
     }
   ],
-  "version": "26.11.2"
+  "version": "26.11.4"
 }

package/data/llms-full.txt

@@ -1,6 +1,6 @@
 # Vielzeug: Full Documentation
 
-> Complete documentation for 43 packages. Version: 26.11.2
+> Complete documentation for 43 packages. Version: 26.11.4
 
 ---
 
@@ -21787,9 +21787,9 @@ Each entry below is a component with its own documentation page and registration
 
 **Content:** `ore-accordion`, `ore-avatar`, `ore-card`, `ore-carousel`, `ore-chat-message`, `ore-chat-panel`, `ore-code-window`, `ore-copy-command`, `ore-icon`, `ore-keyboard-key`, `ore-list`, `ore-marquee`, `ore-qr-code`, `ore-rank-list`, `ore-speech-player`, `ore-speed-reading`, `ore-stats`, `ore-table`, `ore-text`
 
-**Feedback:** `ore-alert`, `ore-async`, `ore-badge`, `ore-chip`, `ore-cookie-banner`, `ore-password-strength`, `ore-progress`, `ore-skeleton`, `ore-toast`, `ore-typing-indicator`
+**Feedback:** `ore-alert`, `ore-badge`, `ore-chip`, `ore-cookie-banner`, `ore-password-strength`, `ore-progress`, `ore-pull-to-refresh`, `ore-skeleton`, `ore-state`, `ore-toast`, `ore-typing-indicator`
 
-**Inputs:** `ore-button`, `ore-calendar`, `ore-checkbox`, `ore-combobox`, `ore-counter`, `ore-datagrid`, `ore-date-picker`, `ore-file-input`, `ore-input`, `ore-message-composer`, `ore-number-input`, `ore-otp-input`, `ore-qr-scanner`, `ore-query-bar`, `ore-radio`, `ore-rating`, `ore-select`, `ore-slider`, `ore-switch`, `ore-textarea`, `ore-time-picker`
+**Inputs:** `ore-button`, `ore-calendar`, `ore-checkbox`, `ore-color-picker`, `ore-combobox`, `ore-counter`, `ore-datagrid`, `ore-date-picker`, `ore-file-input`, `ore-input`, `ore-message-composer`, `ore-number-input`, `ore-otp-input`, `ore-qr-scanner`, `ore-query-bar`, `ore-radio`, `ore-rating`, `ore-select`, `ore-slider`, `ore-switch`, `ore-textarea`, `ore-time-picker`
 
 **Layout:** `ore-box`, `ore-dock`, `ore-grid`, `ore-navbar`, `ore-separator`, `ore-sidebar`
 
@@ -21852,6 +21852,8 @@ Classification guides discovery and bundle selection. It is not a reason to remo
 | `@vielzeug/refine/frameworks/react` | Register typed React JSX elements | Types only | Does not provide runtime wrappers |
 | `@vielzeug/refine/frameworks/vue` | Register typed Vue global components | Types only | Does not install a Vue plugin |
 | `@vielzeug/refine/theme` | `createThemeController()`: light/dark/system document theme | Sync | Does not persist the preference or set an accent color |
+| `@vielzeug/refine/blueprint` | `parseUiBlueprint()`: validate a model-authored UI document against a fixed registry | Sync | Pure contract only: it registers no components and renders nothing |
+| `@vielzeug/refine/blueprint/render` | `renderUiBlueprint()`: render a validated document with registered components | Sync | Registers its thirteen components on import; rejects before touching the container |
 | `eventFieldValue()` / `eventFieldChecked()` | Read a form control's value/checked from `event.currentTarget` | Sync | Exported from the package root; guards non-field targets |
 | `animateReflow()` | Token-driven FLIP reflow for keyed lists | Async (next frame) | Exported from the package root; elements need stable keys or it correctly does nothing |
 | `setMotionMode()` / `getMotionMode()` | Read/write the `data-motion` attribute on `` | Sync | Exported from the package root; an unknown mode throws `RangeError` |
@@ -21864,6 +21866,8 @@ Classification guides discovery and bundle selection. It is not a reason to remo
 | `@vielzeug/refine` | Export `registerIcons`, icon definition types, `RefineError`, `animateReflow`, the motion-mode functions, and the field readers without registering components |
 | `@vielzeug/refine/` | Register one component and export its tag constant, props, events, and related types |
 | `@vielzeug/refine/theme` | `createThemeController()` and its theme types |
+| `@vielzeug/refine/blueprint` | On-demand UI document contract: `parseUiBlueprint()`, the node types, bounds, `UI_BLUEPRINT_REGISTRY`, and `UI_BLUEPRINT_JSON_SCHEMA` |
+| `@vielzeug/refine/blueprint/render` | `renderUiBlueprint()` and the thirteen component tags it registers |
 | `@vielzeug/refine/tokens.css` | Required global design contract |
 | `@vielzeug/refine/fouc.css` | Optional pre-upgrade visibility rule |
 | `@vielzeug/refine/styles/*` | Focused theme, animation, layer, and preflight stylesheets |
@@ -21931,8 +21935,8 @@ import type { OreButtonProps } from '@vielzeug/refine/button';
 | Area | Components |
 | --- | --- |
 | Content | `accordion`, `avatar`, `card`, `carousel`, `chat-message`, `chat-panel`, `code-window`, `copy-command`, `icon`, `keyboard-key`, `list`, `marquee`, `qr-code`, `rank-list`, `speech-player`, `speed-reading`, `stats`, `table`, `text` |
-| Feedback | `alert`, `async`, `badge`, `chip`, `cookie-banner`, `password-strength`, `progress`, `skeleton`, `toast`, `typing-indicator` |
-| Inputs | `button`, `calendar`, `checkbox`, `combobox`, `counter`, `datagrid`, `date-picker`, `file-input`, `input`, `message-composer`, `number-input`, `otp-input`, `qr-scanner`, `query-bar`, `radio`, `rating`, `select`, `slider`, `switch`, `textarea`, `time-picker` |
+| Feedback | `alert`, `badge`, `chip`, `cookie-banner`, `password-strength`, `progress`, `pull-to-refresh`, `skeleton`, `state`, `toast`, `typing-indicator` |
+| Inputs | `button`, `calendar`, `checkbox`, `color-picker`, `combobox`, `counter`, `datagrid`, `date-picker`, `file-input`, `input`, `message-composer`, `number-input`, `otp-input`, `qr-scanner`, `query-bar`, `radio`, `rating`, `select`, `slider`, `switch`, `textarea`, `time-picker` |
 | Layout | `box`, `dock`, `grid`, `navbar`, `separator`, `sidebar` |
 | Navigation | `breadcrumb`, `navigation-menu`, `pagination`, `stepper`, `tabs` |
 | Overlay | `command-palette`, `dialog`, `drawer`, `menu`, `popover`, `spotlight`, `tooltip`, `tour` |
@@ -22035,6 +22039,68 @@ setMotionMode('reduced'); // returns the applied mode
 
 Read/write the `data-motion` attribute on `` (`'full' | 'reduced' | 'system'`; `'system'` removes the attribute). An unknown mode throws `RangeError`. The attribute drives the token layer: see [Animation & Motion → Motion Mode](./animation#motion-mode).
 
+## On-Demand UI Documents
+
+`@vielzeug/refine/blueprint` is the trusted boundary for UI that a model writes. A harness asks a model to describe a small UI in JSON, and this contract decides whether that JSON may be rendered. It is data only: no code, no HTML, no callbacks, no styles, no URLs. See [On-Demand UI Documents](./on-demand-ui) for the full guide.
+
+```ts
+import { parseUiBlueprint, safeParseUiBlueprint } from '@vielzeug/refine/blueprint';
+
+const result = safeParseUiBlueprint(JSON.parse(modelOutput)); // model output stays `unknown`
+if (!result.success) showError(result.issues); // safe to display: field paths, no secrets
+else renderValidated(result.document);
+```
+
+| Export | Purpose |
+| --- | --- |
+| `UI_BLUEPRINT_VERSION` | The only document version accepted (`1`) |
+| `parseUiBlueprint(value)` | Validate `unknown`. Returns the document unchanged, or throws `UiBlueprintError`. Nothing is repaired or partially accepted |
+| `safeParseUiBlueprint(value)` | Non-throwing form: `{ success: true, document }` or `{ success: false, issues }` |
+| `UiBlueprintError` | `RefineError` subclass carrying `issues: readonly string[]`, each a field path such as `root.children[0].size` |
+| `UI_BLUEPRINT_COMPONENTS` | The thirteen accepted component names: `text`, `box`, `card`, `button`, `badge`, `separator`, `slider`, `switch`, `checkbox`, `number-input`, `alert`, `progress`, `icon` |
+| `UI_BLUEPRINT_REGISTRY` | The same registry as data: element tag, child policy, attribute names, slot-text fields, and accepted values per component |
+| `UI_BLUEPRINT_JSON_SCHEMA` | JSON Schema (draft 2020-12) for the contract, for harnesses with structured output |
+| `BlueprintDocument`, `BlueprintNode`, and the node interfaces | TypeScript types for the document shape. Every node accepts an optional bounded `id` through `BlueprintNodeMeta` |
+| `MAX_BLUEPRINT_NODES`, `MAX_BLUEPRINT_DEPTH`, `MAX_BLUEPRINT_CHILDREN`, `MAX_BLUEPRINT_TEXT_LENGTH`, `MAX_BLUEPRINT_LABEL_LENGTH`, `MAX_BLUEPRINT_NUMBER`, `MAX_BLUEPRINT_ID_LENGTH` | Document bounds, not user-configurable |
+
+`@vielzeug/refine/blueprint` imports nothing but `RefineError`: it is pure, DOM-free, and safe to run in a model harness, a worker, or CI. It registers no components.
+
+`UI_BLUEPRINT_JSON_SCHEMA` constrains generation but cannot express the tree-wide node and depth bounds, so runtime validation stays mandatory. Treat the schema as a generation aid, never as the trust boundary.
+
+### `renderUiBlueprint(container, value, options?)`
+
+```ts
+import { renderUiBlueprint } from '@vielzeug/refine/blueprint/render';
+
+try {
+  const { element, nodes } = renderUiBlueprint(host, JSON.parse(modelOutput), { label: 'Generated summary' });
+  nodes.get('rate')?.addEventListener('change', () => recalculate());
+} catch (error) {
+  // The container is untouched: the previous preview is still on screen.
+}
+```
+
+Validate `value`, then render it into `container` using only registry components. Importing the entry registers those thirteen components, so no separate component imports are needed.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `container` | `HTMLElement` | Element that receives the rendered tree |
+| `value` | `unknown` | Untrusted model output. Validated before anything is rendered |
+| `options.label` | `string?` | Accessible name for a `role="group"` wrapper. Host-owned: a document cannot set it |
+| `options.replace` | `boolean?` | Clear the container first. Default `true`; `false` appends |
+
+**Returns** a `UiBlueprintRenderResult`: `{ element, nodes }`, the rendered root and a `ReadonlyMap` keyed by each node's optional `id` so the host can wire behaviour to addressable controls. `id` is host-facing metadata: the renderer never writes it to the DOM. Validation runs first, so a rejected document throws `UiBlueprintError` before the container is read or written: an invalid response can never partially render or erase a valid preview. Text becomes a text node, never markup.
+
+### `createUiBlueprintElement(node, owner?, nodes?)`
+
+```ts
+import { createUiBlueprintElement } from '@vielzeug/refine/blueprint/render';
+
+const element = createUiBlueprintElement(document.root, 'root', nodeMap);
+```
+
+Build one element for an already-validated node. Pass a `Map` as `nodes` to collect every id-tagged element it creates, including nested ones; `owner` labels the node's position in rejection messages. This is the component registry: adding a component means adding a rule in the contract and a case here, and nothing else. It throws `TypeError` for an unregistered node type, so a hand-built node cannot bypass validation either. Embedders that place nodes themselves use this; `renderUiBlueprint()` is the normal entry point.
+
 ## Types
 
 Component props follow the `OreProps` naming pattern. Event maps follow `OreEvents`. Import both from the component subpath that owns them.
@@ -22055,6 +22121,16 @@ class RefineError extends Error {
 
 Base class for public Refine errors. It preserves `cause` through `ErrorOptions`.
 
+### `UiBlueprintError`
+
+```ts
+class UiBlueprintError extends RefineError {
+  readonly issues: readonly string[];
+}
+```
+
+Thrown by `parseUiBlueprint()` and `renderUiBlueprint()` for a rejected on-demand UI document. Every rejection is collected first, so `issues` lists all of them at once, each as a field path plus a plain reason (`root.children[0].size: expected one of sm, md, lg, received string.`). The messages name fields and allowed values, report a wrong-typed value only as its *type*, and echo an accepted-type value only as a truncated snippet, so they are safe to display to a user. See [On-Demand UI Documents](./on-demand-ui).
+
 ### Usage Guide
 
 ## Basic Usage
@@ -22299,6 +22375,7 @@ Use Necromancer directly when you need animation handles, groups, or explicit ke
 - **Dispose** application-owned Ripple effects and service handles.
 - **Guard** DOM-dependent component registration during SSR.
 - **Working with AI agents?** Install the `vielzeug` skill (`npx -y @vielzeug/codex skills install`) so agents reach for Refine components and tokens instead of custom widgets: see the [Codex usage guide](../codex/usage.md#agent-skill).
+- **Rendering model-authored UI?** Validate it through the [on-demand UI document contract](./on-demand-ui) instead of trusting model output; never build DOM from unvalidated JSON.
 
 ---
 

package/data/llms.txt

@@ -1,6 +1,6 @@
 # Vielzeug
 
-> 43 focused TypeScript packages. Version: 26.11.2
+> 43 focused TypeScript packages. Version: 26.11.4
 
 Install any package independently: `pnpm add @vielzeug/<name>`
 

package/data/manifest.json

@@ -4,5 +4,5 @@
   "refine": "refine.json",
   "schemaVersion": 1,
   "search": "search.json",
-  "version": "26.11.2"
+  "version": "26.11.4"
 }

package/data/packages/assay.json

@@ -1,5 +1,5 @@
 {
-  "apiSource": "export { walkFlatTree } from './dom';\nexport { AssayError, AssayQueryError, AssayTimeoutError } from './errors';\nexport {\n  dispatch,\n  fireBlur,\n  fireChange,\n  fireClick,\n  fireCustom,\n  fireFocus,\n  fireInput,\n  fireKeyDown,\n  fireKeyUp,\n  fireSubmit,\n} from './events';\nexport { installFormInternalsPolyfill } from './form-internals';\nexport { getSlotted, type QueryScope, queryAllInShadow, queryInShadow, queryPart, within } from './query';\nexport {\n  type DelayOptions,\n  delay,\n  type EventuallyOptions,\n  eventually,\n  type WaitOptions,\n  waitForEvent,\n  waitUntil,\n} from './wait';\n",
+  "apiSource": "export { walkFlatTree } from './dom';\nexport { AssayError, AssayQueryError, AssayTimeoutError } from './errors';\nexport {\n  dispatch,\n  fireBlur,\n  fireChange,\n  fireClick,\n  fireCustom,\n  fireFocus,\n  fireInput,\n  fireKeyDown,\n  fireKeyUp,\n  fireSubmit,\n} from './events';\nexport { installFormInternalsPolyfill } from './form-internals';\nexport { installPopoverPolyfill } from './popover';\nexport { getSlotted, type QueryScope, queryAllInShadow, queryInShadow, queryPart, within } from './query';\nexport {\n  type DelayOptions,\n  delay,\n  type EventuallyOptions,\n  eventually,\n  type WaitOptions,\n  waitForEvent,\n  waitUntil,\n} from './wait';\n",
   "docs": {
     "index": "---\ntitle: 'Assay: Framework-agnostic DOM testing primitives'\ndescription: Scoped DOM queries, exact event dispatch, and cancellable async waiting for browser tests.\npackage: assay\ncategory: testing\nkeywords: [testing, dom, events, queries, custom-elements]\nrelated: [ore, refine]\nexports:\n  [\n    within,\n    queryInShadow,\n    queryAllInShadow,\n    queryPart,\n    getSlotted,\n    dispatch,\n    fireBlur,\n    fireChange,\n    fireClick,\n    fireCustom,\n    fireFocus,\n    fireInput,\n    fireKeyDown,\n    fireKeyUp,\n    fireSubmit,\n    waitUntil,\n    eventually,\n    waitForEvent,\n    delay,\n    walkFlatTree,\n    installFormInternalsPolyfill,\n    AssayError,\n    AssayQueryError,\n    AssayTimeoutError,\n  ]\nenvironments: [browser]\n---\n\n<!-- markdownlint-disable MD025 MD033 MD060 -->\n\n<PackageHero package=\"assay\" />\n\n## Why Assay?\n\nAssay provides focused DOM test primitives that work with vanilla elements, custom elements, and framework-rendered output. It scopes queries, dispatches exact browser event classes, and waits on explicit conditions without imposing a renderer or browser automation stack.\n\n```ts\n// Before\nbutton.dispatchEvent(new MouseEvent('click', { bubbles: true }));\nawait new Promise((resolve) => setTimeout(resolve, 100));\n\n// After\nfireClick(view.get('button.submit'));\nawait waitUntil(() => view.queryByText('Saved') !== null);\n```\n\n| Feature             | Assay                                        | Testing Library DOM                      | Browser automation                       |\n| ------------------- | -------------------------------------------- | ---------------------------------------- | ---------------------------------------- |\n| Bundle size         | <PackageInfo package=\"assay\" type=\"size\" />  | Larger query layer                       | Browser runtime required                 |\n| Zero dependencies   | <ore-icon name=\"check\" size=\"16\"></ore-icon> | <ore-icon name=\"x\" size=\"16\"></ore-icon> | <ore-icon name=\"x\" size=\"16\"></ore-icon> |\n| Scoped DOM queries  | `within()` and shadow helpers                | Renderer-oriented queries                | Manual selectors                         |\n| Deterministic waits | `waitUntil()` and `waitForEvent()`           | Framework-dependent                      | Full browser timing                      |\n\n<div class=\"decision-callout\">\n\n**Use Assay when** a DOM unit test needs readable queries, dispatched events, or a bounded async wait without adopting a rendering framework.\n\n**Consider browser integration tests when** correctness depends on browser default actions, focus behavior, pointer capture, layout, or accessibility-tree behavior.\n\n</div>\n\n## Installation\n\n::: code-group\n\n```sh [pnpm]\npnpm add -D @vielzeug/assay\n```\n\n```sh [npm]\nnpm install -D @vielzeug/assay\n```\n\n```sh [yarn]\nyarn add -D @vielzeug/assay\n```\n\n:::\n\n## Quick Start\n\nScope a test fixture, dispatch an event, and wait for resulting DOM state.\n\n```ts\nimport { fireClick, waitUntil, within } from '@vielzeug/assay';\n\nconst panel = document.createElement('section');\npanel.innerHTML = '<button>Save</button><output></output>';\npanel.querySelector('button')!.addEventListener('click', () => {\n  panel.querySelector('output')!.textContent = 'Saved';\n});\n\nconst view = within(panel);\nfireClick(view.get('button'));\nawait waitUntil(() => view.queryByText('Saved') !== null);\n```\n\n## Features\n\n<div class=\"features-grid\">\n\n- `within(root)` scopes nullable and required DOM queries.\n- `queryInShadow`, `queryPart`, and `getSlotted` cross custom-element boundaries explicitly.\n- `fireClick`, `fireInput`, `fireKeyDown`, and peers dispatch exact synchronous events.\n- `waitUntil`, `eventually`, and `waitForEvent` provide bounded, abortable async waiting.\n- `delay` models explicit cancellable timer scheduling.\n- `walkFlatTree` traverses the flat tree across slot boundaries jsdom's light-DOM queries miss.\n- `installFormInternalsPolyfill` gives jsdom the `ElementInternals` form-association API.\n- `AssayError`, `AssayQueryError`, and `AssayTimeoutError` provide typed failures.\n\n</div>\n\n## Documentation\n\n<div class=\"doc-links\">\n\n- [Usage Guide](./usage.md)\n- [API Reference](./api.md)\n- [Examples](./examples.md)\n- [Migration Guide](./migration.md)\n\n</div>\n\n## See Also\n\n<div class=\"see-also\">\n\n- [Ore](/ore/): component authoring and test fixtures that pair with Assay DOM helpers.\n- [Refine](/refine/): accessible components with component-specific test assertions.\n\n</div>\n\n<!-- markdownlint-enable MD025 MD033 MD060 -->\n",
     "api": "---\ntitle: 'Assay: API Reference'\ndescription: API reference for @vielzeug/assay queries, event dispatch, async waiting, and test-environment helpers.\n---\n\n[[toc]]\n\n## API Overview\n\n| Symbol                                       | Purpose                                     | Execution mode | Common gotcha                                    |\n| -------------------------------------------- | ------------------------------------------- | -------------- | ------------------------------------------------ |\n| `within`                                     | Creates scoped query API                    | Sync           | Required `get*` methods throw `AssayQueryError`  |\n| `queryInShadow` / `queryPart` / `getSlotted` | Crosses custom-element boundaries           | Sync           | Open shadow roots are required                   |\n\n| `fire*` / `dispatch`                         | Dispatches platform event instances         | Sync           | Does not reproduce browser default behavior      |\n| `waitUntil` / `eventually` / `waitForEvent`  | Waits for conditions, assertions, or events | Async          | Use a signal or timeout for bounded waits                     |\n| `delay`                                      | Schedules a cancellable timer               | Async          | Pass a signal to cancel a pending wait                        |\n| `walkFlatTree`                               | Walks the flat tree across slot boundaries  | Sync           | jsdom-only need: browsers already use the flat tree           |\n| `installFormInternalsPolyfill`               | Polyfills `ElementInternals` form association for jsdom | Sync | Global patches: only install in suites that need them |\n\n## Package Entry Point\n\n| Import            | Purpose                                              |\n| ----------------- | ---------------------------------------------------- |\n| `@vielzeug/assay` | DOM queries, events, wait helpers, test-environment helpers, errors, and types |\n\n## Queries\n\n### `within(root)`\n\nCreates a `QueryScope` for an `Element`, `ShadowRoot`, `Document`, or `DocumentFragment`.\n\n| Method                            | Returns           | Use                                          |\n| --------------------------------- | ----------------- | -------------------------------------------- |\n| `get(selector)`                   | `Element`         | Required CSS match; throws `AssayQueryError` |\n| `query(selector)`                 | `Element \\| null` | Optional CSS match                           |\n| `queryAll(selector)`              | `Element[]`       | All CSS matches                              |\n| `getByText(text, selector?)`      | `Element`         | Required exact trimmed-text match            |\n| `queryByText(text, selector?)`    | `Element \\| null` | Optional exact trimmed-text match            |\n| `queryAllByText(text, selector?)` | `Element[]`       | All exact trimmed-text matches               |\n| `getByTestId(id)`                 | `Element`         | Required `data-testid` match                 |\n| `queryByTestId(id)`               | `Element \\| null` | Optional `data-testid` match                 |\n| `queryAllByTestId(id)`            | `Element[]`       | All `data-testid` matches                    |\n\nText selectors default to `'*'`. Required-query failures include the lookup and a bounded view of the scoped DOM.\n\n### Shadow and slot helpers\n\n| Function                           | Returns           | Description                                          |\n| ---------------------------------- | ----------------- | ---------------------------------------------------- |\n| `queryInShadow(host, selector)`    | `Element \\| null` | First match in an open shadow root                   |\n| `queryAllInShadow(host, selector)` | `Element[]`       | All matches in an open shadow root                   |\n| `queryPart(host, part)`            | `Element \\| null` | First shadow element whose `part` token matches      |\n| `getSlotted(host, slotName?)`      | `Element[]`       | Direct light-DOM children in a named or default slot |\n\nThese helpers return `null` or `[]` when there is no shadow root. Dynamic test IDs, parts, and slot names are matched\nas attribute values rather than interpolated into CSS selectors.\n\n## Event dispatch\n\nAll event helpers synchronously return `dispatchEvent()`'s boolean result.\n\n```ts\nimport {\n  dispatch,\n  fireBlur,\n  fireChange,\n  fireClick,\n  fireCustom,\n  fireFocus,\n  fireInput,\n  fireKeyDown,\n  fireKeyUp,\n  fireSubmit,\n} from '@vielzeug/assay';\n\nfireClick(button, { clientX: 20 });\nfireInput(input);\nfireKeyDown(input, { key: 'Enter' });\nfireCustom(element, 'item-added', { detail: { id: '42' } });\ndispatch(element, new Event('ready'));\n```\n\n| Function                    | Event class     | Defaults                                               |\n| --------------------------- | --------------- | ------------------------------------------------------ |\n| `fireBlur` / `fireFocus`    | `FocusEvent`    | Platform defaults (`bubbles: false`)                   |\n| `fireChange`                | `Event`         | `bubbles: true`                                        |\n| `fireInput`                 | `InputEvent`    | `bubbles: true`                                        |\n| `fireClick`                 | `MouseEvent`    | `bubbles: true`, `cancelable: true`                    |\n| `fireKeyDown` / `fireKeyUp` | `KeyboardEvent` | `bubbles: true`, `cancelable: true`                    |\n| `fireSubmit`                | `SubmitEvent`   | `bubbles: true`, `cancelable: true`                    |\n| `fireCustom`                | `CustomEvent`   | `bubbles: true`, `cancelable: true`, `composed: false` |\n\n`fireCustom(target, type, init?)` dispatches a `CustomEvent` with the given type. Assay intentionally does not\nprovide browser-default or fallback pointer/touch simulation.\n\n## Async waiting\n\n```ts\nawait waitUntil(() => ready, { interval: 20, signal, timeout: 1000 });\nawait eventually(() => expect(spy).toHaveBeenCalled(), { signal, timeout: 1000 });\nawait waitForEvent(target, 'ready', { signal, timeout: 1000 });\nawait delay(100, { signal });\n```\n\n| Function                               | Success condition        | Options                                    |\n| -------------------------------------- | ------------------------ | ------------------------------------------ |\n| `waitUntil(predicate, options?)`       | Predicate returns `true` | `timeout`, `interval`, `signal`            |\n| `eventually(assertion, options?)`       | Assertion stops throwing | `timeout`, `interval`, `signal`, `message`            |\n| `waitForEvent(target, type, options?)` | Target emits `type`      | `timeout`, `signal`                        |\n| `delay(ms?, options?)`                 | Timer elapses            | `signal`                                   |\n\n\n`waitUntil()`, `eventually()`, and `waitForEvent()` reject with `AssayTimeoutError` when their shared deadline expires. `waitUntil()` and `eventually()` remain bounded while an asynchronous callback is pending. Abort rejects with the signal reason and removes Assay-owned timers and listeners. Callback work itself must cooperate with application cancellation.\n\n`timeout` and delay milliseconds must be finite, non-negative, and no greater than 2,147,483,647 ms; `interval` must be finite, positive, and within the same timer limit. Invalid durations throw `RangeError`. `eventually()` also accepts `message` for diagnostic timeout context.\n\n## Test-environment helpers\n\n### `walkFlatTree(root, visit)`\n\n```ts\nfunction walkFlatTree(root: Element, visit: (element: HTMLElement) => void): void;\n```\n\nWalks the flat tree below `root`, calling `visit` for each assigned or ordinary descendant (not for `root` itself).\nAt each `<slot>` it expands `assignedElements()` instead of descending into its (always empty, in jsdom) literal\nchildren. jsdom only\nimplements the light DOM tree, so `querySelectorAll()` never crosses a slot into its assigned elements; real\nbrowsers use the flat tree for that. This helper closes the gap for tests that must find form-associated (or\notherwise slotted) elements through shadow boundaries.\n\n```ts\nconst named: HTMLElement[] = [];\n\nwalkFlatTree(form, (el) => {\n  if (el.hasAttribute('name')) named.push(el);\n});\n```\n\n### `installFormInternalsPolyfill()`\n\n```ts\nfunction installFormInternalsPolyfill(): () => void;\n```\n\njsdom implements none of the `ElementInternals` form-association API: not `setFormValue`, not `setValidity`, not\nthe `checkValidity`/`reportValidity`/`validity`/`validationMessage` mixin real browsers put on every\n`formAssociated: true` element, not even `FormData` collecting a form-associated element's set value, or\n`<form>.reset()` invoking `formResetCallback()`. Every one of those gaps is exercised by `useField()` from\n`@vielzeug/ore`, so any package testing a form-associated component needs all of them.\n\nCall it from a test setup when the suite tests form-associated components; it returns an `uninstall()` that\nrestores every patched global. The patches are global monkey-patches and skip APIs already implemented by the\nenvironment, so suites without form-associated components shouldn't install them. If `ElementInternals` is absent,\nthe installer is a no-op. A downstream package should\nrely on this instead of hand-rolling its own copy.\n\n```ts\n// vitest.setup.ts\nimport { installFormInternalsPolyfill } from '@vielzeug/assay';\nimport { install } from '@vielzeug/ore/testing';\nimport { afterAll, afterEach } from 'vitest';\n\ninstall(afterEach);\nafterAll(installFormInternalsPolyfill());\n```\n\n## Types\n\n```ts\nexport interface QueryScope {\n  get<E extends Element = Element>(selector: string): E;\n  getByTestId<E extends Element = Element>(testId: string): E;\n  getByText<E extends Element = Element>(text: string, selector?: string): E;\n  query<E extends Element = Element>(selector: string): E | null;\n  queryAll<E extends Element = Element>(selector: string): E[];\n  queryAllByTestId<E extends Element = Element>(testId: string): E[];\n  queryAllByText<E extends Element = Element>(text: string, selector?: string): E[];\n  queryByTestId<E extends Element = Element>(testId: string): E | null;\n  queryByText<E extends Element = Element>(text: string, selector?: string): E | null;\n}\n```\n\nScoped query helpers returned by `within(root)`.\n\n```ts\nexport interface WaitOptions {\n  /** Polling interval in ms (default: 50). */\n  interval?: number;\n  /** Cancel the pending wait. */\n  signal?: AbortSignal;\n  /** Maximum wait time in ms (default: 1000). */\n  timeout?: number;\n}\n\nexport interface EventuallyOptions extends WaitOptions {\n  /** Context included in the timeout error. */\n  message?: string;\n}\n\nexport interface DelayOptions {\n  /** Cancel the pending delay. */\n  signal?: AbortSignal;\n}\n```\n\n`WaitOptions` configures `waitUntil()`. `EventuallyOptions` configures `eventually()`. `DelayOptions` configures `delay()`.\n\n## Errors\n\n| Error               | Meaning                                |\n| ------------------- | -------------------------------------- |\n| `AssayError`        | Base class for Assay-originated errors |\n| `AssayQueryError`   | A required `get*` query had no match   |\n| `AssayTimeoutError` | A wait operation reached its timeout   |\n\nUse `instanceof AssayError` to narrow any value to the Assay error hierarchy.\n",
@@ -23,6 +23,7 @@
     "fireKeyUp": "export {\n  dispatch,\n  fireBlur,\n  fireChange,\n  fireClick,\n  fireCustom,\n  fireFocus,\n  fireInput,\n  fireKeyDown,\n  fireKeyUp,\n  fireSubmit,\n} from './events';",
     "fireSubmit": "export {\n  dispatch,\n  fireBlur,\n  fireChange,\n  fireClick,\n  fireCustom,\n  fireFocus,\n  fireInput,\n  fireKeyDown,\n  fireKeyUp,\n  fireSubmit,\n} from './events';",
     "installFormInternalsPolyfill": "export { installFormInternalsPolyfill } from './form-internals';",
+    "installPopoverPolyfill": "export { installPopoverPolyfill } from './popover';",
     "getSlotted": "export { getSlotted, type QueryScope, queryAllInShadow, queryInShadow, queryPart, within } from './query';",
     "QueryScope": "export { getSlotted, type QueryScope, queryAllInShadow, queryInShadow, queryPart, within } from './query';",
     "queryAllInShadow": "export { getSlotted, type QueryScope, queryAllInShadow, queryInShadow, queryPart, within } from './query';",