@vielzeug/codex 26.11.3 → 26.11.4

package/data/catalog.json

@@ -35,7 +35,7 @@
         "rune"
       ],
       "slug": "archive",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -108,7 +108,7 @@
         "coins"
       ],
       "slug": "arsenal",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -160,7 +160,7 @@
         "refine"
       ],
       "slug": "assay",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -199,7 +199,7 @@
         "vault"
       ],
       "slug": "beacon",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -241,7 +241,7 @@
         "ward"
       ],
       "slug": "clockwork",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -274,7 +274,7 @@
         "refine"
       ],
       "slug": "codex",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -344,7 +344,7 @@
         "spell"
       ],
       "slug": "coins",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -385,7 +385,7 @@
         "rune"
       ],
       "slug": "conduit",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -427,7 +427,7 @@
         "postmaster"
       ],
       "slug": "courier",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -473,7 +473,7 @@
         "refine"
       ],
       "slug": "dnd",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -515,7 +515,7 @@
         "herald"
       ],
       "slug": "familiar",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -582,7 +582,7 @@
         "courier"
       ],
       "slug": "flux",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -622,7 +622,7 @@
         "ore"
       ],
       "slug": "focus",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -663,7 +663,7 @@
         "assay"
       ],
       "slug": "forge",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -701,7 +701,7 @@
         "keymap"
       ],
       "slug": "gesture",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -745,7 +745,7 @@
         "familiar"
       ],
       "slug": "herald",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -788,7 +788,7 @@
         "tempo"
       ],
       "slug": "illusionist",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -833,7 +833,7 @@
         "ore"
       ],
       "slug": "keymap",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -880,7 +880,7 @@
         "vault"
       ],
       "slug": "ledger",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -926,7 +926,7 @@
         "courier"
       ],
       "slug": "lingua",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -964,7 +964,7 @@
         "herald"
       ],
       "slug": "mesh",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1001,7 +1001,7 @@
         "ore"
       ],
       "slug": "necromancer",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1041,7 +1041,7 @@
         "prism"
       ],
       "slug": "orbit",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1106,7 +1106,7 @@
         "orbit"
       ],
       "slug": "ore",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1150,7 +1150,7 @@
         "ripple"
       ],
       "slug": "postmaster",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1191,7 +1191,7 @@
         "orbit"
       ],
       "slug": "prism",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1255,7 +1255,7 @@
         "clockwork"
       ],
       "slug": "pulse",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1378,7 +1378,7 @@
         "keymap"
       ],
       "slug": "refine",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1423,7 +1423,7 @@
         "ledger"
       ],
       "slug": "ripple",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1477,7 +1477,7 @@
         "familiar"
       ],
       "slug": "rune",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1518,7 +1518,7 @@
         "refine"
       ],
       "slug": "sandbox",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1569,7 +1569,7 @@
         "ripple"
       ],
       "slug": "scout",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1622,7 +1622,7 @@
         "refine"
       ],
       "slug": "scroll",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1669,7 +1669,7 @@
         "gesture"
       ],
       "slug": "sentinel",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1709,7 +1709,7 @@
         "refine"
       ],
       "slug": "sigil",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1754,7 +1754,7 @@
         "wayfinder"
       ],
       "slug": "sourcerer",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1813,7 +1813,7 @@
         "vault"
       ],
       "slug": "spell",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1854,7 +1854,7 @@
         "ripple"
       ],
       "slug": "tandem",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1898,7 +1898,7 @@
         "herald"
       ],
       "slug": "tavern",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -1966,7 +1966,7 @@
         "vault"
       ],
       "slug": "tempo",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -2017,7 +2017,7 @@
         "ripple"
       ],
       "slug": "vault",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -2063,7 +2063,7 @@
         "refine"
       ],
       "slug": "ward",
-      "version": "26.11.2"
+      "version": "26.11.3"
     },
     {
       "availableDocPages": [
@@ -2117,8 +2117,8 @@
         "herald"
       ],
       "slug": "wayfinder",
-      "version": "26.11.2"
+      "version": "26.11.3"
     }
   ],
-  "version": "26.11.2"
+  "version": "26.11.3"
 }

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.3
 
 ---
 
@@ -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 |
@@ -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.3
 
 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.3"
 }