@slexkit/mcp 0.3.3 → 0.4.0

package/dist/data/llms-runtime.txt

@@ -4,306 +4,310 @@
 
 Raw Markdown: /docs/reference/spec.md
 
----
-title: Slex Specification v0.1
-category: Reference
-status: ready
-order: 10
-summary: "Public Slex expression envelope, component keys, props, directives, lifecycle, and runtime API contract."
-slexkitRenderMode: component
----
-
-# Slex Specification v0.1
-
-Slex expression envelope, component keys, props, directives, lifecycle, and runtime API contract — SlexKit v0's entire public protocol in one place. Source of truth for implementors, test authors, and host adapter authors.
-
-**v0/beta.** The current implementation may evolve, but the protocol version (v0.1) is independent of the SlexKit package version. The same protocol may remain stable across multiple package releases.
-
-## 1. Slex expression envelope
-
-The canonical Slex expression is an object. Slex source is the JavaScript object literal string form of that expression:
-
-```ts
-type SlexExpression = {
-  slex?: "0.1";
-  namespace: string;
-  g: Record<string, unknown>;
-  layout: Record<string, unknown>;
-};
-```
-
-`slex`, `namespace`, `g`, and `layout` are the standard envelope fields. `slex: "0.1"` is an optional protocol marker for humans, agents, and validators; it does not affect namespace identity or state merging. The runtime also accepts a bare component tree as shorthand: if the input has component keys at the top level and does not define `namespace`, `g`, or `layout`, it is normalized to:
-
-```js
-{ namespace: "default", g: {}, layout: <input> }
-```
-
-## 2. Layout key
-
-Component keys use the format:
-
-```
-ComponentKey = ComponentType ":" Identifier
-```
-
-- `ComponentType` maps to a type in the component registry.
-- `Identifier` may be empty (e.g. `"box:"`).
-- Named components use `Identifier` for instance state and lifecycle hooks.
-- Keys without `:` are not rendered as component nodes.
-
-Reserved context names: `g`, `std`, `api`, `$event`, `$item`, `$index`, `$key`.
-
-## 3. Props classification
-
-### Static props
-
-Passed to the component unchanged:
-
-```js
-"text:title": { text: "Hello" }
-```
-
-### `$` read-pipes
-
-A string value on a `$`-prefixed key (excluding `$if`, `$for`, `$key`) is evaluated as a JavaScript expression. The result is passed under the key with the `$` prefix removed:
-
-```js
-"text:value": { "$content": "'Count: ' + g.count" }
-// Resolves to: content = "Count: <value of g.count>"
-```
-
-### `on*` write-pipes
-
-A string value on an `on*`-prefixed key is executed as a JavaScript statement:
-
-```js
-"button:add": { onclick: "g.count++" }
-"input:name": { onchange: "g.name = String($event || '')" }
-```
-
-The handler receives `$event` as the event data.
-
-### Structural directives
-
-`$if`, `$for`, `$key` are structural directives and are never passed to the component as props. Children of `$if` and `$for` components are treated as the conditional/iterated subtree.
-
-## 4. `g` merge
-
-When the same namespace is mounted or ingested again, the new `g` is merged into the existing store:
-
-| Value type          | Merge behavior           |
-| ------------------- | ------------------------ |
-| Function            | Overwrites the old value |
-| Array               | Replaces entirely        |
-| Plain object        | Recursively deep-merges  |
-| Other scalar        | Overwrites the old value |
-| Keys not in new `g` | Preserved from old `g`   |
-
-The new `layout` always replaces the current layout. Layout is never deep-merged.
-
-## 5. Expression context
-
-Expressions can access these variables:
-
-| Variable           | Type                          | Scope                    |
-| ------------------ | ----------------------------- | ------------------------ |
-| `g`                | Reactive state proxy          | Always                   |
-| `std`              | Pure SlexKit standard library | Always                   |
-| Component state    | e.g. `slider.value`           | Named components         |
-| `api`              | Host-injected object          | If `api` option provided |
-| `$event`           | Event data                    | `on*` handlers only      |
-| `$item`            | Current array item            | `$for` context only      |
-| `$index`           | Current array index           | `$for` context only      |
-| `$key`             | Current item key              | `$for` context only      |
-| Named `$for` alias | e.g. `user` for `"card:user"` | `$for` context only      |
-
-`std` contains deterministic helpers for math, formatting, units, and small statistics. Sensitive capabilities stay under host-injected `api.*` and may require secure runtime policy.
-
-Expression evaluation errors are caught and produce a warning with namespace and path information. The last known value is returned as a fallback.
-
-## 6. Component instance state
-
-Component registration declares a state mode:
-
-```ts
-register(type, renderer, { state: "value" | "checked" | "enabled" | "readable" | "none" });
-```
-
-| Mode       | Writable           | Behavior                                                      |
-| ---------- | ------------------ | ------------------------------------------------------------- |
-| `value`    | `value`            | Input component; `value` writable from expressions and events |
-| `checked`  | `checked`, `value` | Checkbox-like boolean component; both synced and writable     |
-| `enabled`  | `enabled`          | Switch-like boolean component; enabled state is writable      |
-| `readable` | (none)             | Readable from expressions; write emits console warning        |
-| `none`     | (none)             | No instance state exposed                                     |
-
-Input components (`value`/`checked`/`enabled` modes) sync `change` events to instance state automatically. Duplicate-named components share one namespace-level state instance.
-
-`input` with `type: "engineering"` is a value-mode component with additional parsed fields. `value` remains the raw input string, while `number`, `valid`, `prefix`, `unit`, `normalized`, and optional `error` expose the parsed engineering number. Supported v1 notation includes scientific notation plus SI prefixes (`p`, `n`, `u`, `µ`, `m`, `k`, `K`, `M`, `meg`, `G`, `T`) with an optional unit suffix. Units are captured but not dimension-converted.
-
-## 7. `$if`
-
-`$if` controls component existence:
-
-```js
-"card:panel": {
-  "$if": "g.visible",
-  "text:body": { text: "Visible" }
-}
-```
-
-- **Truthy** -mounts the component and its subtree with enter animation if `$enter` is defined.
-- **Falsy** -unmounts the component and subtree with leave animation if `$leave` is defined, then fires lifecycle hooks, disposers, and subtree cleanup.
-
-## 8. `$for`
-
-`$for` renders a component for each array element:
-
-```js
-"text:item": {
-  "$for": "g.items",
-  "$key": "id",
-  "$content": "$item.label"
-}
-```
-
-Context variables: `$item`, `$index`, `$key`. Named components inject the current item as a same-name variable.
-
-### `$key` strategy
-
-| `$key` value             | Behavior                                                                        |
-| ------------------------ | ------------------------------------------------------------------------------- |
-| `"$value"`               | Use the primitive item itself                                                   |
-| `"id"` or other property | Read that property from object items                                            |
-| Omitted                  | Use `item.id` if available; otherwise fall back to index with a console warning |
-
-Primitive arrays should always specify `$key: "$value"`.
-
-### $for phases
-
-1. **Delete** -Remove items whose keys are absent from the new array (with leave animation).
-2. **Add/update/reorder** -Create new items for new keys; update retained items' `forCtx` (item reference, index); reorder DOM nodes to match array order. Updated items fire `onUpdate_<name>`.
-3. **Trim** -Defensively remove excess children.
-
-## 9. Lifecycle and cleanup
-
-Convention hooks on `g`:
-
-```
-g.onMount_<name>()      -after component is appended to DOM
-g.onUnmount_<name>()    -before component is removed from DOM
-g.onUpdate_<name>()     -after $for item changes (index or item reference)
-```
-
-Component implementations can register resource cleanup:
-
-```ts
-attachComponentDisposer(el, dispose);
-```
-
-Component disposal is triggered by normal unmount, `$if` toggle-off, `$for` item removal, root cleanup, and `disposeNamespace()`.
-
-## 10. Public runtime API
-
-| Function                            | Signature                                   | Description                                                          |
-| ----------------------------------- | ------------------------------------------- | -------------------------------------------------------------------- |
-| `mount`                             | `(input, container, options?) => Cleanup`   | Parse, merge state, render component tree                            |
-| `ingest`                            | `(input) => boolean`                        | Ingest state-only Slex, no rendering                                 |
-| `boot`                              | `(options?) => void`                        | Enhance static page code blocks                                      |
-| `disposeNamespace`                  | `(namespace) => void`                       | Release namespace roots, store, and cache                            |
-| `register`                          | `(type, renderer, options?) => void`        | Register component type                                              |
-| `getRenderer`                       | `(type) => ComponentRenderer \| undefined`  | Look up a registered renderer                                        |
-| `getIcon`                           | `(name, state?) => string`                  | Resolve a registered or bundled icon synchronously                   |
-| `loadIcon`                          | `(name, state?) => Promise<string>`         | Resolve an icon, using Iconify fallback when not bundled             |
-| `registerIcon`                      | `(name, svg, options?) => void`             | Register one global SVG icon for all components with an `icon` field |
-| `registerIcons`                     | `(icons, options?) => void`                 | Register multiple global SVG icons                                   |
-| `clearRegisteredIcons`              | `() => void`                                | Clear all custom registered icons                                    |
-| `getRegisteredIcon`                 | `(name, state?) => string`                  | Look up only registered icons (no Phosphor fallback)                 |
-| `normalizeIconName`                 | `(name) => string`                          | Normalize icon name to kebab-case with set prefix                    |
-| `resolveIconWeight`                 | `(state?) => IconWeight`                    | Resolve icon weight from component state                             |
-| `resolveIconifyIcon`                | `(name, state?) => {prefix, name}`          | Resolve to Iconify-compatible name pair                              |
-| `iconifySvgUrl`                     | `(name, state?) => string`                  | Build full Iconify API SVG URL                                       |
-| `configureComponentScope`           | `(options) => void`                         | Configure framework adapter flush                                    |
-| `attachComponentDisposer`           | `(el, dispose) => void`                     | Bind cleanup to element lifecycle                                    |
-| `createSecureRuntime`               | `(policy, adapter?) => SecureRuntimeHandle` | Create gated runtime instance                                        |
-| `mountSecureArtifact`               | `(input, container, options) => Cleanup`    | Mount in secure sandbox                                              |
-| `createSlexKitMarkdownRuntimeHost`  | `(options?) => MarkdownRuntimeHost`         | Create Markdown host instance                                        |
-| `getSlexKitMarkdownRuntimeHost`     | `() => MarkdownRuntimeHost`                 | Get or create global Markdown host                                   |
-| `installSlexKitMarkdownRuntimeHost` | `(options?) => MarkdownRuntimeHost`         | Install and return global Markdown host                              |
-| `getSlexKitRuntimeUrl`              | `() => string \| undefined`                 | Get default sandbox runtime URL                                      |
-| `setSlexKitRuntimeUrl`              | `(url) => void`                             | Set default sandbox runtime URL                                      |
-| `diagnoseSlexKitSource`             | `(source, error) => Diagnostic`             | Locate syntax error in source                                        |
-| `parseSlexSource`                   | `(source) => ParseResult`                   | Parse Slex source to object                                          |
-| `formatSlexKitDiagnostic`           | `(diagnostic) => string`                    | Format diagnostic to readable string                                 |
-
-## 11. Error types
-
-### SlexKitSyntaxError
-
-Thrown when Slex source parsing fails. Includes a `diagnostic` property with `message`, `line`, `column`, `detail`, and `excerpt`.
-
-### SlexKitRuntimeError
-
-Thrown when a runtime operation violates policy or encounters a runtime failure. Has properties: `kind` (`"policy"` | `"network"` | `"timeout"`), `code` (specific error code string), `message`, `elapsedMs`.
-
-## 12. Markdown language handling
-
-SlexKit hosts must only process explicit fence language tags:
-
-- `slex`
-
-Plain JavaScript, JSON, or untagged code blocks must not be scanned or executed.
-
-## 13. Secure runtime types
-
-```ts
-type SecureRuntimeHandle = {
-  api: SlexKitRuntimeApi;
-  dispose: () => void;
-};
-```
-
-For full secure runtime types (`HostRuntimePolicy`, `HostRuntimeAdapter`, `SlexKitRuntimeApi`, `SecureFrameOptions`, `SecureMountOptions`, sandbox message types), see the [security runtime contract](/docs/reference/security).
-
-## 14. ToolHost
-
-ToolHost bridges AI tool calls to interactive UI that returns structured user input. It is separate from display-oriented `slex` fences.
-
-**Public API:**
-
-| Function | Signature | Description |
-|----------|-----------|-------------|
-| `renderToolCall` | `(call, container) => ToolRenderHandle` | Compile and mount tool UI, return promise |
-| `registerToolTemplate` | `(name, compiler) => void` | Register a custom tool template compiler |
-
-**Result type:**
-
-```ts
-type ToolResult =
-  | { toolCallId?: string; toolName: string; status: "submitted"; value: Record<string, unknown> }
-  | { toolCallId?: string; toolName: string; status: "ignored"; value: null };
-```
-
-**Built-in templates:** `confirm-action`, `choose-options`, `option-list`, `fill-form`. Templates compile to standard Slex expressions using `card:tool` and `submit:actions` components. The `submit:actions` component serves as the completion boundary — it is only used by tool templates, not general display fences.
-
-For full template reference, arguments, type definitions, and custom template development, see [ToolHost documentation](/docs/reference/toolhost).
-
-## 15. Icon system
-
-SlexKit includes a built-in icon system with Phosphor Icons, a custom registration API, and Iconify fallback support.
-
-**Public API (10 functions):** `registerIcon`, `registerIcons`, `clearRegisteredIcons`, `getIcon`, `getRegisteredIcon`, `loadIcon`, `normalizeIconName`, `resolveIconWeight`, `resolveIconifyIcon`, `iconifySvgUrl`.
-
-Icons are resolved through a three-tier chain: registered icons → bundled Phosphor (24 icons, 2 weights) → Iconify API fetch (async, `loadIcon` only). Components that accept an `icon` prop automatically display the resolved SVG.
-
-For the full API reference, icon list, naming conventions, and custom icon registration, see [Icon system documentation](/docs/reference/icons).
-
-## 16. Non-goals
-
-- No public stable compatibility commitment (v0/beta).
-- Not a pure JSON cross-platform protocol.
-- No automatic security hardening of arbitrary browser APIs.
-- No heuristic scanning of code blocks to guess whether to render.
+---
+title: Slex Specification v0.1
+category: Reference
+status: ready
+order: 10
+summary: "Public Slex expression envelope, component keys, props, directives, lifecycle, and runtime API contract."
+slexkitRenderMode: component
+---
+
+# Slex Specification v0.1
+
+Slex expression envelope, component keys, props, directives, lifecycle, and runtime API contract — SlexKit v0's entire public protocol in one place. Canonical reference for implementors, test authors, and host adapter authors.
+
+**v0/beta.** The current implementation may evolve, but the protocol version (v0.1) is independent of the SlexKit package version. The same protocol may remain stable across multiple package releases.
+
+## 1. Slex expression envelope
+
+The canonical Slex expression is an object. Slex source is the JavaScript object literal string form of that expression:
+
+```ts
+type SlexExpression = {
+  slex?: "0.1";
+  namespace: string;
+  g: Record<string, unknown>;
+  layout: Record<string, unknown>;
+};
+```
+
+`slex`, `namespace`, `g`, and `layout` are the standard envelope fields. `slex: "0.1"` is an optional protocol marker for humans, agents, and validators; it does not affect namespace identity or state merging. The runtime also accepts a bare component tree as shorthand: if the input has component keys at the top level and does not define `namespace`, `g`, or `layout`, it is normalized to:
+
+```js
+{ namespace: "default", g: {}, layout: <input> }
+```
+
+## 2. Layout key
+
+Component keys use the format:
+
+```
+ComponentKey = ComponentType ":" Identifier
+```
+
+- `ComponentType` maps to a type in the component registry.
+- `Identifier` may be empty (e.g. `"box:"`).
+- Named components use `Identifier` for instance state and lifecycle hooks.
+- Keys without `:` are not rendered as component nodes.
+
+Reserved context names: `g`, `std`, `api`, `$event`, `$item`, `$index`, `$key`.
+
+## 3. Props classification
+
+### Static props
+
+Passed to the component unchanged:
+
+```js
+"text:title": { text: "Hello" }
+```
+
+### `$` read-pipes
+
+A string value on a `$`-prefixed key (excluding `$if`, `$for`, `$key`) is evaluated as a JavaScript expression. The result is passed under the key with the `$` prefix removed:
+
+```js
+"text:value": { "$content": "'Count: ' + g.count" }
+// Resolves to: content = "Count: <value of g.count>"
+```
+
+### `on*` write-pipes
+
+A string value on an `on*`-prefixed key is executed as a JavaScript statement:
+
+```js
+"button:add": { onclick: "g.count++" }
+"input:name": { onchange: "g.name = String($event || '')" }
+```
+
+The handler receives `$event` as the event data.
+
+### Structural directives
+
+`$if`, `$for`, `$key` are structural directives and are never passed to the component as props. Children of `$if` and `$for` components are treated as the conditional/iterated subtree.
+
+## 4. `g` merge
+
+When the same namespace is mounted or ingested again, the new `g` is merged into the existing store:
+
+| Value type          | Merge behavior           |
+| ------------------- | ------------------------ |
+| Function            | Overwrites the old value |
+| Array               | Replaces entirely        |
+| Plain object        | Recursively deep-merges  |
+| Other scalar        | Overwrites the old value |
+| Keys not in new `g` | Preserved from old `g`   |
+
+The new `layout` always replaces the current layout. Layout is never deep-merged.
+
+## 5. Expression context
+
+Expressions can access these variables:
+
+| Variable           | Type                          | Scope                    |
+| ------------------ | ----------------------------- | ------------------------ |
+| `g`                | Reactive state proxy          | Always                   |
+| `std`              | Pure SlexKit standard library | Always                   |
+| Component state    | e.g. `slider.value`           | Named components         |
+| `api`              | Host-injected object          | If `api` option provided |
+| `$event`           | Event data                    | `on*` handlers only      |
+| `$item`            | Current array item            | `$for` context only      |
+| `$index`           | Current array index           | `$for` context only      |
+| `$key`             | Current item key              | `$for` context only      |
+| Named `$for` alias | e.g. `user` for `"card:user"` | `$for` context only      |
+
+`std` contains deterministic helpers for math, formatting, units, and small statistics. Sensitive capabilities stay under host-injected `api.*` and may require secure runtime policy.
+
+Expression evaluation errors are caught and produce a warning with namespace and path information. The last known value is returned as a fallback.
+
+## 6. Component instance state
+
+Component registration declares a state mode:
+
+```ts
+register(type, renderer, { state: "value" | "checked" | "enabled" | "readable" | "none" });
+```
+
+| Mode       | Writable           | Behavior                                                      |
+| ---------- | ------------------ | ------------------------------------------------------------- |
+| `value`    | `value`            | Input component; `value` writable from expressions and events |
+| `checked`  | `checked`, `value` | Checkbox-like boolean component; both synced and writable     |
+| `enabled`  | `enabled`          | Switch-like boolean component; enabled state is writable      |
+| `readable` | (none)             | Readable from expressions; write emits console warning        |
+| `none`     | (none)             | No instance state exposed                                     |
+
+Input components (`value`/`checked`/`enabled` modes) sync `change` events to instance state automatically. Duplicate-named components share one namespace-level state instance.
+
+`input` with `type: "engineering"` is a value-mode component with additional parsed fields. `value` remains the raw input string, while `number`, `valid`, `prefix`, `unit`, `normalized`, and optional `error` expose the parsed engineering number. Supported v1 notation includes scientific notation plus SI prefixes (`p`, `n`, `u`, `µ`, `m`, `k`, `K`, `M`, `meg`, `G`, `T`) with an optional unit suffix. Units are captured but not dimension-converted.
+
+## 7. `$if`
+
+`$if` controls component existence:
+
+```js
+"card:panel": {
+  "$if": "g.visible",
+  "text:body": { text: "Visible" }
+}
+```
+
+- **Truthy** -mounts the component and its subtree with enter animation if `$enter` is defined.
+- **Falsy** -unmounts the component and subtree with leave animation if `$leave` is defined, then fires lifecycle hooks, disposers, and subtree cleanup.
+
+## 8. `$for`
+
+`$for` renders a component for each array element:
+
+```js
+"text:item": {
+  "$for": "g.items",
+  "$key": "id",
+  "$content": "$item.label"
+}
+```
+
+Context variables: `$item`, `$index`, `$key`. Named components inject the current item as a same-name variable.
+
+### `$key` strategy
+
+| `$key` value             | Behavior                                                                        |
+| ------------------------ | ------------------------------------------------------------------------------- |
+| `"$value"`               | Use the primitive item itself                                                   |
+| `"id"` or other property | Read that property from object items                                            |
+| Omitted                  | Use `item.id` if available; otherwise fall back to index with a console warning |
+
+Primitive arrays should always specify `$key: "$value"`.
+
+### $for phases
+
+1. **Delete** -Remove items whose keys are absent from the new array (with leave animation).
+2. **Add/update/reorder** -Create new items for new keys; update retained items' `forCtx` (item reference, index); reorder DOM nodes to match array order. Updated items fire `onUpdate_<name>`.
+3. **Trim** -Defensively remove excess children.
+
+## 9. Lifecycle and cleanup
+
+Convention hooks on `g`:
+
+```
+g.onMount_<name>()      -after component is appended to DOM
+g.onUnmount_<name>()    -before component is removed from DOM
+g.onUpdate_<name>()     -after $for item changes (index or item reference)
+```
+
+Component implementations can register resource cleanup:
+
+```ts
+attachComponentDisposer(el, dispose);
+```
+
+Component disposal is triggered by normal unmount, `$if` toggle-off, `$for` item removal, root cleanup, and `disposeNamespace()`.
+
+## 10. Public runtime API
+
+| Function                            | Signature                                   | Description                                                          |
+| ----------------------------------- | ------------------------------------------- | -------------------------------------------------------------------- |
+| `mount`                             | `(input, container, options?) => Cleanup`   | Parse, merge state, render component tree                            |
+| `ingest`                            | `(input) => boolean`                        | Ingest state-only Slex, no rendering                                 |
+| `boot`                              | `(options?) => void`                        | Enhance static page code blocks                                      |
+| `disposeNamespace`                  | `(namespace) => void`                       | Release namespace roots, store, and cache                            |
+| `register`                          | `(type, renderer, options?) => void`        | Register component type                                              |
+| `getRenderer`                       | `(type) => ComponentRenderer \| undefined`  | Look up a registered renderer                                        |
+| `getIcon`                           | `(name, state?) => string`                  | Resolve a registered or bundled icon synchronously                   |
+| `loadIcon`                          | `(name, state?) => Promise<string>`         | Resolve an icon, using Iconify fallback when not bundled             |
+| `registerIcon`                      | `(name, svg, options?) => void`             | Register one global SVG icon for all components with an `icon` field |
+| `registerIcons`                     | `(icons, options?) => void`                 | Register multiple global SVG icons                                   |
+| `clearRegisteredIcons`              | `() => void`                                | Clear all custom registered icons                                    |
+| `getRegisteredIcon`                 | `(name, state?) => string`                  | Look up only registered icons (no Phosphor fallback)                 |
+| `normalizeIconName`                 | `(name) => string`                          | Normalize icon name to kebab-case with set prefix                    |
+| `resolveIconWeight`                 | `(state?) => IconWeight`                    | Resolve icon weight from component state                             |
+| `resolveIconifyIcon`                | `(name, state?) => {prefix, name}`          | Resolve to Iconify-compatible name pair                              |
+| `iconifySvgUrl`                     | `(name, state?) => string`                  | Build full Iconify API SVG URL                                       |
+| `configureComponentScope`           | `(options) => void`                         | Configure framework adapter flush                                    |
+| `attachComponentDisposer`           | `(el, dispose) => void`                     | Bind cleanup to element lifecycle                                    |
+| `createSecureRuntime`               | `(policy, adapter?) => SecureRuntimeHandle` | Create gated runtime instance                                        |
+| `mountSecureArtifact`               | `(input, container, options) => Cleanup`    | Mount in secure sandbox                                              |
+| `createSlexKitMarkdownRuntimeHost`  | `(options?) => MarkdownRuntimeHost`         | Create Markdown host instance                                        |
+| `getSlexKitMarkdownRuntimeHost`     | `() => MarkdownRuntimeHost`                 | Get or create global Markdown host                                   |
+| `installSlexKitMarkdownRuntimeHost` | `(options?) => MarkdownRuntimeHost`         | Install and return global Markdown host                              |
+| `getSlexKitRuntimeUrl`              | `() => string \| undefined`                 | Get default sandbox runtime URL                                      |
+| `setSlexKitRuntimeUrl`              | `(url) => void`                             | Set default sandbox runtime URL                                      |
+| `diagnoseSlexKitSource`             | `(source, error) => Diagnostic`             | Locate syntax error in source                                        |
+| `parseSlexSource`                   | `(source) => ParseResult`                   | Parse Slex source to object                                          |
+| `validateSlexSource`                | `(source, options?) => ValidationResult`    | Parse-first validation with versions, usage, and stable warning codes |
+| `runSlexConformance`                | `(options?) => ConformanceReport`           | Run bundled standard conformance fixtures                            |
+| `formatSlexKitDiagnostic`           | `(diagnostic) => string`                    | Format diagnostic to readable string                                 |
+
+For full runtime behavior, see [Runtime Model](/docs/reference/runtime).
+
+## 11. Error types
+
+### SlexKitSyntaxError
+
+Thrown when Slex source parsing fails. Includes a `diagnostic` property with `message`, `line`, `column`, `detail`, and `excerpt`.
+
+### SlexKitRuntimeError
+
+Thrown when a runtime operation violates policy or encounters a runtime failure. Has properties: `kind` (`"policy"` | `"network"` | `"timeout"`), `code` (specific error code string), `message`, `elapsedMs`.
+
+## 12. Markdown language handling
+
+SlexKit hosts must only process explicit fence language tags:
+
+- `slex`
+
+Plain JavaScript, JSON, or untagged code blocks must not be scanned or executed.
+
+## 13. Secure runtime types
+
+```ts
+type SecureRuntimeHandle = {
+  api: SlexKitRuntimeApi;
+  dispose: () => void;
+};
+```
+
+For full secure runtime types (`HostRuntimePolicy`, `HostRuntimeAdapter`, `SlexKitRuntimeApi`, `SecureFrameOptions`, `SecureMountOptions`, sandbox message types), see the [security runtime contract](/docs/reference/security).
+
+## 14. ToolHost
+
+ToolHost bridges AI tool calls to interactive UI that returns structured user input. It is separate from display-oriented `slex` fences.
+
+**Public API:**
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `renderToolCall` | `(call, container) => ToolRenderHandle` | Compile and mount tool UI, return promise |
+| `registerToolTemplate` | `(name, compiler) => void` | Register a custom tool template compiler |
+
+**Result type:**
+
+```ts
+type ToolResult =
+  | { toolCallId?: string; toolName: string; status: "submitted"; value: Record<string, unknown> }
+  | { toolCallId?: string; toolName: string; status: "ignored"; value: null };
+```
+
+**Built-in templates:** `confirm-action`, `choose-options`, `option-list`, `fill-form`. Templates compile to standard Slex expressions using `card:tool` and `submit:actions` components. The `submit:actions` component submits the tool result; it is only used by tool templates, not general display fences.
+
+For full template reference, arguments, type definitions, and custom template development, see [ToolHost documentation](/docs/reference/toolhost).
+
+## 15. Icon system
+
+SlexKit includes a built-in icon system with Phosphor Icons, a custom registration API, and Iconify fallback support.
+
+**Public API (10 functions):** `registerIcon`, `registerIcons`, `clearRegisteredIcons`, `getIcon`, `getRegisteredIcon`, `loadIcon`, `normalizeIconName`, `resolveIconWeight`, `resolveIconifyIcon`, `iconifySvgUrl`.
+
+Icons are resolved through a three-tier chain: registered icons → bundled Phosphor (24 icons, 2 weights) → Iconify API fetch (async, `loadIcon` only). Components that accept an `icon` prop automatically display the resolved SVG.
+
+For the full API reference, icon list, naming conventions, and custom icon registration, see [Icon system documentation](/docs/reference/icons).
+
+## 16. Non-goals
+
+- No public stable compatibility commitment (v0/beta).
+- Not a pure JSON cross-platform protocol.
+- No automatic security hardening of arbitrary browser APIs.
+- No heuristic scanning of code blocks to guess whether to render.
 - No implicit wrapping of display UI as function calls.
 
 ---
@@ -312,244 +316,244 @@ For the full API reference, icon list, naming conventions, and custom icon regis
 
 Raw Markdown: /docs/reference/usage.md
 
----
-title: Slex Usage Reference
-category: Reference
-status: ready
-order: 20
-summary: "Reference for Slex source structure, props, directives, events, theming, custom components, and ToolHost boundaries."
-slexkitRenderMode: component
----
-
-# Slex Usage Reference
-
-Slex source shape and runtime-facing authoring rules: props, directives, events, theming, custom components, and ToolHost boundaries. For first-time setup, start with [Getting Started](/docs/guides/quick-start). For exact protocol compatibility, use the [Slex Specification](/docs/reference/spec).
-
-## Installation
-
-Most hosts install the root package:
-
-```sh
-npm install slexkit
-```
-
-```js
-import { mount } from "slexkit";
-import "slexkit/style.css";
-```
-
-Component-free bare runtime:
-
-```sh
-npm install slexkit @slexkit/runtime
-```
-
-```js
-import { mount, register } from "@slexkit/runtime";
-import "@slexkit/components-svelte";
-import "@slexkit/theme-shadcn/style.css";
-```
-
-For package boundaries and host-specific install commands, see [Package Boundaries](/docs/reference/packages).
-
-## Slex source structure
-
-A Slex source is a JavaScript object literal:
-
-```js
-{
-  slex: "0.1",
-  namespace: "demo",
-  g: { count: 0 },
-  layout: {
-    "button:add": { text: "Add", onclick: "g.count++" },
-    "text:value": { "$content": "'Count: ' + g.count" }
-  }
-}
-```
-
-- `slex` -optional Slex protocol marker; use `"0.1"` for the current public protocol.
-- `namespace` -state domain identifier (defaults to `"default"`).
-- `g` -reactive state and logic (functions, data).
-- `layout` -component tree.
-
-As a convenience, a bare component tree (keys containing `:`) is normalized to `{ namespace: "default", g: {}, layout: <tree> }`. If the bare tree includes `slex: "0.1"`, that marker is preserved while component keys move under `layout`.
-
-## Props
-
-### Static props
-
-Passed to the component as-is:
-
-```js
-"text:title": { text: "Hello World" }
-```
-
-### Dynamic read-pipes (`$`)
-
-A string value on a `$`-prefixed key is evaluated as a JavaScript expression. The result replaces the key stripped of the `$` prefix:
-
-```js
-"text:value": { "$content": "'Count: ' + g.count" }
-```
-
-The `$` prefix is removed. The prop passed to the component is `content`. Re-evaluation is triggered automatically when any reactive dependency changes.
-
-### Write-pipes (`on*`)
-
-A string value on an `on*`-prefixed key is executed as a JavaScript statement:
-
-```js
-"button:add": { onclick: "g.count++" }
-"input:name": { onchange: "g.name = String($event || '')" }
-```
-
-The handler receives `$event` as the event data.
-
-### Structural directives
-
-`$if`, `$for`, and `$key` are structural directives -they are not passed to the component as props.
-
-## `$if` -conditional rendering
-
-Controls whether the component and its subtree are mounted:
-
-```js
-"card:panel": {
-  "$if": "g.visible",
-  "text:body": { text: "I am visible" }
-}
-```
-
-When the expression is truthy, the component mounts (with enter animation if `$enter` is defined). When falsy, it unmounts (with leave animation if `$leave` is defined, then cleanup).
-
-## `$for` -array iteration
-
-Renders a component for each item in an array:
-
-```js
-"text:item": {
-  "$for": "g.items",
-  "$key": "id",
-  "$content": "$item.label"
-}
-```
-
-Context variables available inside `$for`: `$item` (current item), `$index` (current index), `$key` (item key). Named components also inject the current item as a same-name variable (e.g. `"card:user"` makes `user` available).
-
-### Key strategy
-
-`$key` supports:
-- `"$value"` -use the primitive item itself as key.
-- `"id"` (or any property name) -read that property from object items.
-- Omitted -uses `item.id` if available, otherwise falls back to index with a console warning.
-
-Primitive array items should always specify `$key: "$value"`.
-
-### $for update algorithm
-
-1. **Delete phase** -remove items whose keys are no longer in the array (with leave animation).
-2. **Add/update/reorder phase** -create new items, update retained items' context (index, item reference), and reorder DOM nodes to match the array.
-3. **Trim phase** -defensively remove any excess children.
-
-When an item's index or item reference changes, `onUpdate_<name>` is called.
-
-## Events
-
-Event handlers are defined as `on*` write-pipes. The component's native change/input events are automatically wired to component instance state for writable components:
-
-```js
-"input:name": { onchange: "g.name = String($event || '')" }
-```
-
-The `$event` variable contains the event data. For change events on writable components (`value`, `checked`, or `enabled` mode), the component state is automatically synced before the handler runs.
-
-## Trusted vs secure mode
-
-### Trusted mode (default)
-
-Slex source executes in the host page realm. Use for application-generated content, repository-maintained Slex source, or already-reviewed snippets.
-
-```js
-import { mount } from "slexkit";
-
-mount(script, container, { theme: "host-shadcn" });
-```
-
-### Secure mode
-
-Untrusted or agent-generated Slex source runs in a sandbox iframe with opaque origin. Sensitive capabilities are gated behind host policy:
-
-```js
-import { mountSecureArtifact } from "slexkit";
-
-mountSecureArtifact(script, container, {
-  policy: {},
-  frame: { runtimeUrl: "/slexkit.runtime.js" },
-});
-```
-
-Use [Secure Runtime Setup](/docs/guides/security-runtime) for the deployment checklist. Use the [Security Runtime Contract](/docs/reference/security) for the full policy model, sandbox behavior, bridge protocol, and fail-closed requirements.
-
-## Theming
-
-Theme mode is resolved from the `theme` option:
-
-| Value | Behavior |
-|-------|----------|
-| `"auto"` | Checks container for known theme classes; falls back to `"uno"` |
-| `"host-shadcn"` | shadcn/ui compatible |
-| `"uno"` | Uno/Flowbite compatible |
-| `"flowbite"` | Flowbite compatible |
-
-Direction (`ltr`, `rtl`, `auto`) is resolved from the inherited `dir` attribute or the document element.
-
-```js
-mount(script, container, { theme: "host-shadcn", dir: "auto" });
-```
-
-## Custom components
-
-Register a component type with a render function:
-
-```ts
-import { register } from "slexkit";
-
-register("custom", (props, name, ctx) => {
-  const el = ctx.document.createElement("div");
-  el.textContent = String(props.label ?? name);
-  return el;
-}, { state: "value" });
-```
-
-The `RenderContext` provides:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `g` | reactive proxy | Global state |
-| `std` | `SlexKitStdlib` | Pure deterministic helpers |
-| `api` | `Record<string, unknown>` | Host-injected capabilities |
-| `dir` | `"ltr"` or `"rtl"` | Resolved direction |
-| `labels` | `Partial<Record<string, string>>` | Runtime labels |
-| `id` | `string \| null` | Component name |
-| `emit` | `(event, data?) => void` | Event emitter |
-| `children` | `Record<string, unknown>` | Nested component tree |
-| `document` | `Document` | Owner document |
-| `renderTree` | function | Recursive render helper |
-
-Use `attachComponentDisposer(el, fn)` to bind cleanup to the component's DOM lifecycle.
-
-## ToolHost
-
-ToolHost handles UI that must return structured user input (confirmations, selections, forms). It is separate from display-oriented `slex` fences.
-
-Built-in templates:
-- `confirm-action` -yes/no confirmation
-- `choose-options` -single or multi-select
-- `option-list` -scrollable option list
-- `fill-form` -structured form with submit
-
-Templates compile to standard Slex source. The `submit` component serves as the completion boundary -only tool templates use it, not display fences.
+---
+title: Slex Usage Reference
+category: Reference
+status: ready
+order: 20
+summary: "Slex source structure, props, directives, events, theming, custom components, and ToolHost usage."
+slexkitRenderMode: component
+---
+
+# Slex Usage Reference
+
+Slex source authoring covers props, directives, events, theming, custom components, and ToolHost. For first-time setup, start with [Getting Started](/docs/guides/quick-start). Protocol compatibility is covered in the [Slex Specification](/docs/reference/spec).
+
+## Installation
+
+Most hosts install the root package:
+
+```sh
+npm install slexkit
+```
+
+```js
+import { mount } from "slexkit";
+import "slexkit/style.css";
+```
+
+Component-free bare runtime:
+
+```sh
+npm install slexkit @slexkit/runtime
+```
+
+```js
+import { mount, register } from "@slexkit/runtime";
+```
+
+This entry does not auto-register the official Svelte components. Use the root `slexkit` package, or explicitly import `@slexkit/components-svelte`, when you want the bundled components.
+
+For package roles and host-specific install commands, see [Packages](/docs/reference/packages).
+
+## Slex source structure
+
+A Slex source is a JavaScript object literal:
+
+```js
+{
+  slex: "0.1",
+  namespace: "demo",
+  g: { count: 0 },
+  layout: {
+    "button:add": { text: "Add", onclick: "g.count++" },
+    "text:value": { "$content": "'Count: ' + g.count" }
+  }
+}
+```
+
+- `slex` - optional Slex protocol marker; use `"0.1"` for the current public protocol.
+- `namespace` - state domain identifier (defaults to `"default"`).
+- `g` - reactive state and logic (functions, data).
+- `layout` - component tree.
+
+As a convenience, a bare component tree (keys containing `:`) is normalized to `{ namespace: "default", g: {}, layout: <tree> }`. If the bare tree includes `slex: "0.1"`, that marker is preserved while component keys move under `layout`.
+
+## Props
+
+### Static props
+
+Passed to the component as-is:
+
+```js
+"text:title": { text: "Hello World" }
+```
+
+### Dynamic read-pipes (`$`)
+
+A string value on a `$`-prefixed key is evaluated as a JavaScript expression. The result replaces the key stripped of the `$` prefix:
+
+```js
+"text:value": { "$content": "'Count: ' + g.count" }
+```
+
+The `$` prefix is removed. The prop passed to the component is `content`. Re-evaluation is triggered automatically when any reactive dependency changes.
+
+### Write-pipes (`on*`)
+
+A string value on an `on*`-prefixed key is executed as a JavaScript statement:
+
+```js
+"button:add": { onclick: "g.count++" }
+"input:name": { onchange: "g.name = String($event || '')" }
+```
+
+The handler receives `$event` as the event data.
+
+### Structural directives
+
+`$if`, `$for`, and `$key` are structural directives - they are not passed to the component as props.
+
+## `$if` - conditional rendering
+
+Controls whether the component and its subtree are mounted:
+
+```js
+"card:panel": {
+  "$if": "g.visible",
+  "text:body": { text: "I am visible" }
+}
+```
+
+When the expression is truthy, the component mounts (with enter animation if `$enter` is defined). When falsy, it unmounts (with leave animation if `$leave` is defined, then cleanup).
+
+## `$for` - array iteration
+
+Renders a component for each item in an array:
+
+```js
+"text:item": {
+  "$for": "g.items",
+  "$key": "id",
+  "$content": "$item.label"
+}
+```
+
+Context variables available inside `$for`: `$item` (current item), `$index` (current index), `$key` (item key). Named components also inject the current item as a same-name variable (e.g. `"card:user"` makes `user` available).
+
+### Key strategy
+
+`$key` supports:
+- `"$value"` - use the primitive item itself as key.
+- `"id"` (or any property name) - read that property from object items.
+- Omitted - uses `item.id` if available, otherwise falls back to index with a console warning.
+
+Primitive array items should always specify `$key: "$value"`.
+
+### $for update algorithm
+
+1. **Delete phase** - remove items whose keys are no longer in the array (with leave animation).
+2. **Add/update/reorder phase** - create new items, update retained items' context (index, item reference), and reorder DOM nodes to match the array.
+3. **Trim phase** - defensively remove any excess children.
+
+When an item's index or item reference changes, `onUpdate_<name>` is called.
+
+## Events
+
+Event handlers are defined as `on*` write-pipes. The component's native change/input events are automatically wired to component instance state for writable components:
+
+```js
+"input:name": { onchange: "g.name = String($event || '')" }
+```
+
+The `$event` variable contains the event data. For change events on writable components (`value`, `checked`, or `enabled` mode), the component state is automatically synced before the handler runs.
+
+## Trusted vs secure mode
+
+### Trusted mode (default)
+
+Slex source executes in the host page realm. Use for application-generated content, repository-maintained Slex source, or already-reviewed snippets.
+
+```js
+import { mount } from "slexkit";
+
+mount(script, container, { theme: "host-shadcn" });
+```
+
+### Secure mode
+
+Untrusted or agent-generated Slex source runs in a sandbox iframe with opaque origin. Sensitive capabilities are gated behind host policy:
+
+```js
+import { mountSecureArtifact } from "slexkit";
+
+mountSecureArtifact(script, container, {
+  policy: {},
+  frame: { runtimeUrl: "/slexkit.runtime.js" },
+});
+```
+
+Use [Secure Runtime Setup](/docs/guides/security-runtime) for deployment steps. The [Security Runtime Contract](/docs/reference/security) covers policy, sandbox behavior, bridge protocol, and fail-closed requirements.
+
+## Theming
+
+Theme mode is resolved from the `theme` option:
+
+| Value | Behavior |
+|-------|----------|
+| `"auto"` | Checks container for known theme classes; falls back to `"uno"` |
+| `"host-shadcn"` | shadcn/ui compatible |
+| `"uno"` | Uno/Flowbite compatible |
+| `"flowbite"` | Flowbite compatible |
+
+Direction (`ltr`, `rtl`, `auto`) is resolved from the inherited `dir` attribute or the document element.
+
+```js
+mount(script, container, { theme: "host-shadcn", dir: "auto" });
+```
+
+## Custom components
+
+Register a component type with a render function:
+
+```ts
+import { register } from "slexkit";
+
+register("custom", (props, name, ctx) => {
+  const el = ctx.document.createElement("div");
+  el.textContent = String(props.label ?? name);
+  return el;
+}, { state: "value" });
+```
+
+The `RenderContext` provides:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `g` | reactive proxy | Global state |
+| `std` | `SlexKitStdlib` | Pure deterministic helpers |
+| `api` | `Record<string, unknown>` | Host-injected capabilities |
+| `dir` | `"ltr"` or `"rtl"` | Resolved direction |
+| `labels` | `Partial<Record<string, string>>` | Runtime labels |
+| `id` | `string \| null` | Component name |
+| `emit` | `(event, data?) => void` | Event emitter |
+| `children` | `Record<string, unknown>` | Nested component tree |
+| `document` | `Document` | Owner document |
+| `renderTree` | function | Recursive render helper |
+
+Use `attachComponentDisposer(el, fn)` to bind cleanup to the component's DOM lifecycle.
+
+## ToolHost
+
+ToolHost handles UI that must return structured user input (confirmations, selections, forms). It is separate from display-oriented `slex` fences.
+
+Built-in templates:
+- `confirm-action` - yes/no confirmation
+- `choose-options` - single or multi-select
+- `option-list` - scrollable option list
+- `fill-form` - structured form with submit
+
+Templates compile to standard Slex source. The `submit` component submits the result; only tool templates use it, not display fences.
 
 ---
 
@@ -557,189 +561,210 @@ Templates compile to standard Slex source. The `submit` component serves as the
 
 Raw Markdown: /docs/reference/runtime.md
 
----
-title: Runtime Model
-category: Reference
-status: ready
-order: 30
-summary: "Mounting, ingestion, boot, namespace store, lifecycle hooks, component state, and runtime APIs."
-slexkitRenderMode: component
----
-
-# Runtime Model
-
-The core SlexKit runtime: entry points, namespace store, component state, lifecycle hooks, and expression evaluation.
-
-Slex source syntax is covered in the [protocol specification](/docs/reference/spec). Secure mode isolation is covered in the [security runtime contract](/docs/reference/security).
-
-## Entry points
-
-### `mount(input, container, options)`
-
-Parses Slex source object or source string, merges state into the namespace store, renders the component tree into `container`, returns a root cleanup function.
-
-```ts
-function mount(
-  input: SlexExpression | string,
-  container: HTMLElement,
-  options?: MountOptions
-): () => void;
-
-type MountOptions = {
-  theme?: "auto" | "host-shadcn" | "uno" | "flowbite";
-  dir?: "ltr" | "rtl" | "auto";
-  labels?: Partial<Record<string, string>>;
-  api?: Record<string, unknown>;
-};
-```
-
-Calling `mount()` again on the same `container` clears the old root first, then appends a new root. The returned cleanup only unmounts the current root; it does not delete the namespace store.
-
-Every expression receives `std`, SlexKit's pure deterministic standard library. Hosts can still inject capability objects through `api`, but network, timers, animation, and canvas should remain policy-gated in secure mode.
-
-### `ingest(input)`
-
-Ingests state-only Slex: updates `g` without rendering UI. Used by the Markdown runtime host for state-only fences. Returns `true` if parsing succeeded.
-
-```ts
-function ingest(input: SlexExpression | string): boolean;
-```
-
-### `disposeNamespace(namespace)`
-
-Permanently releases all roots, cleanups, store entries, and expression caches for a namespace. Call this when a document, message domain, or page section is permanently removed. Root cleanup is not equivalent to namespace disposal.
-
-```ts
-function disposeNamespace(namespace: string): void;
-```
-
-### `boot(options)`
-
-Enhances static pages by auto-discovering explicitly marked Slex blocks (`<pre><code class="language-slex">`) and mounting live previews.
-
-```ts
-function boot(options?: BootOptions): void;
-
-type BootOptions = {
-  selector?: string;
-  sourceControls?: boolean;
-  theme?: ThemeMode;
-  dir?: MountOptions["dir"];
-  labels?: MountOptions["labels"];
-};
-```
-
-Default selector covers: `language-slex`.
-
-Hosts like React/Streamdown or Obsidian should typically use the Markdown runtime host directly rather than `boot()`.
-
-### `register(type, renderer, options)`
-
-Registers a component type with a render function and state mode.
-
-```ts
-function register(
-  type: string,
-  renderer: ComponentRenderer,
-  options?: ComponentRegistrationOptions
-): void;
-
-type ComponentRenderer = (
-  props: Record<string, unknown>,
-  name: string,
-  ctx: RenderContext
-) => HTMLElement | void;
-
-type ComponentRegistrationOptions = {
-  state?: "value" | "checked" | "enabled" | "readable" | "none";
-};
-```
-
-### `configureComponentScope(options)`
-
-Configures a flush function for component scope -used by framework adapters to synchronize DOM after reactive updates.
-
-```ts
-function configureComponentScope(options: { flush?: () => void }): void;
-```
-
-## Namespace store
-
-`namespace` is the state domain. Multiple mounts with the same namespace share one store:
-
-- New `g` is deep-merged into the old `g` (functions overwrite, objects recursively merge, arrays replace, scalars overwrite).
-- New `layout` replaces the current layout (no deep merge for layout).
-- Component instance state is persisted within the namespace.
-- Expression caches are managed per namespace.
-
-This allows a document, message domain, or tool panel to update its UI incrementally while preserving state.
-
-## Component instance state
-
-Named components can expose instance state. Which prop is writable depends on the component's registered state mode:
-
-| Mode | Writable prop | Behavior |
-|------|---------------|----------|
-| `value` | `value` | Writable from expressions and events |
-| `checked` | `checked`, `value` | Both synced, writable |
-| `enabled` | `enabled` | Switch enabled state, writable |
-| `readable` | (none) | Readable from expressions, write emits a console warning |
-| `none` | (none) | No state exposed |
-
-```js
-{
-  layout: {
-    "slider:threshold": { value: 42 },
-    "text:preview": { "$content": "'Threshold: ' + threshold.value" }
-  }
-}
-```
-
-Repeatedly named components share namespace-level state. `$for` items with the same component name also share one state instance.
-
-## Lifecycle hooks
-
-The runtime calls convention-based hooks on the `g` object:
-
-```
-g.onMount_<name>()      -after component is appended to DOM
-g.onUnmount_<name>()    -before component is removed from DOM
-g.onUpdate_<name>()     -after $for item index or item reference changes
-```
-
-These hooks fire for normal components, `$if` branches, and `$for` slots. Root cleanup and `disposeNamespace()` trigger `onUnmount`.
-
-## Component disposer
-
-Framework components, event listeners, subscriptions, and external resources should bind their cleanup to the component DOM element:
-
-```ts
-import { register, attachComponentDisposer } from "slexkit/runtime";
-
-register("custom", (props, name, ctx) => {
-  const el = ctx.document.createElement("div");
-  const stop = subscribeSomething();
-  attachComponentDisposer(el, stop);
-  return el;
-});
-```
-
-The runtime calls the disposer when the element is unmounted. The official Svelte adapter uses this mechanism to destroy Svelte component instances.
-
-## Expression evaluation context
-
-Expressions in `$` read-pipes and statements in `on*` write-pipes can access these variables:
-
-| Variable | Type | Availability |
-|----------|------|--------------|
-| `g` | reactive state proxy | always |
-| `api` | host-injected capabilities | if `api` option passed to `mount()` |
-| `$event` | event data | `on*` handlers only |
-| `$item` | current array item | `$for` context only |
-| `$index` | current array index | `$for` context only |
-| `$key` | current item key | `$for` context only |
-| named component state | e.g. `threshold.value` | named components |
-
+---
+title: Runtime Model
+category: Reference
+status: ready
+order: 30
+summary: "Mounting, ingestion, boot, namespace store, lifecycle hooks, component state, and runtime APIs."
+slexkitRenderMode: component
+---
+
+# Runtime Model
+
+The core SlexKit runtime: entry points, namespace store, component state, lifecycle hooks, and expression evaluation.
+
+Slex source syntax is covered in the [protocol specification](/docs/reference/spec). Secure mode isolation is covered in the [security runtime contract](/docs/reference/security).
+
+## Entry points
+
+### `mount(input, container, options)`
+
+Parses Slex source object or source string, merges state into the namespace store, renders the component tree into `container`, returns a root cleanup function.
+
+```ts
+function mount(
+  input: SlexExpression | string,
+  container: HTMLElement,
+  options?: MountOptions
+): () => void;
+
+type MountOptions = {
+  theme?: "auto" | "host-shadcn" | "uno" | "flowbite";
+  dir?: "ltr" | "rtl" | "auto";
+  labels?: Partial<Record<string, string>>;
+  api?: Record<string, unknown>;
+};
+```
+
+Calling `mount()` again on the same `container` clears the old root first, then appends a new root. The returned cleanup only unmounts the current root; it does not delete the namespace store.
+
+Every expression receives `std`, SlexKit's pure deterministic standard library. Hosts can still inject capability objects through `api`, but network, timers, animation, and canvas should remain policy-gated in secure mode.
+
+### `ingest(input)`
+
+Ingests state-only Slex: updates `g` without rendering UI. Used by the Markdown runtime host for state-only fences. Returns `true` if parsing succeeded.
+
+```ts
+function ingest(input: SlexExpression | string): boolean;
+```
+
+### `disposeNamespace(namespace)`
+
+Permanently releases all roots, cleanups, store entries, and expression caches for a namespace. Call this when a document, message domain, or page section is permanently removed. Root cleanup is not equivalent to namespace disposal.
+
+```ts
+function disposeNamespace(namespace: string): void;
+```
+
+### `boot(options)`
+
+Enhances static pages by auto-discovering explicitly marked Slex blocks (`<pre><code class="language-slex">`) and mounting live previews.
+
+```ts
+function boot(options?: BootOptions): void;
+
+type BootOptions = {
+  selector?: string;
+  sourceControls?: boolean;
+  theme?: ThemeMode;
+  dir?: MountOptions["dir"];
+  labels?: MountOptions["labels"];
+};
+```
+
+Default selector covers: `language-slex`.
+
+Hosts like React/Streamdown or Obsidian should typically use the Markdown runtime host directly rather than `boot()`.
+
+### `register(type, renderer, options)`
+
+Registers a component type with a render function and state mode.
+
+```ts
+function register(
+  type: string,
+  renderer: ComponentRenderer,
+  options?: ComponentRegistrationOptions
+): void;
+
+type ComponentRenderer = (
+  props: Record<string, unknown>,
+  name: string,
+  ctx: RenderContext
+) => HTMLElement | void;
+
+type ComponentRegistrationOptions = {
+  state?: "value" | "checked" | "enabled" | "readable" | "none";
+};
+```
+
+### `configureComponentScope(options)`
+
+Configures a flush function for component scope. Framework adapters use it to synchronize DOM after reactive updates.
+
+```ts
+function configureComponentScope(options: { flush?: () => void }): void;
+```
+
+## Validation and conformance
+
+### `validateSlexSource(source, options)`
+
+Validates Slex source after parsing. The result includes `schemaVersion`, `protocolVersion`, `logicProfileVersion`, usage lists, and warning codes. Syntax failures return a diagnostic.
+
+```ts
+function validateSlexSource(
+  source: string,
+  options?: { mode?: "trusted" | "secure" }
+): ValidationResult;
+```
+
+### `runSlexConformance(options)`
+
+Runs the bundled standard fixtures against the current validator. Pass `fixtureId` to run one fixture.
+
+```ts
+function runSlexConformance(options?: { fixtureId?: string }): ConformanceReport;
+```
+
+## Namespace store
+
+`namespace` is the state domain. Multiple mounts with the same namespace share one store:
+
+- New `g` is deep-merged into the old `g` (functions overwrite, objects recursively merge, arrays replace, scalars overwrite).
+- New `layout` replaces the current layout (no deep merge for layout).
+- Component instance state is persisted within the namespace.
+- Expression caches are managed per namespace.
+
+This allows a document, message domain, or tool panel to update its UI incrementally while preserving state.
+
+## Component instance state
+
+Named components can expose instance state. Which prop is writable depends on the component's registered state mode:
+
+| Mode | Writable prop | Behavior |
+|------|---------------|----------|
+| `value` | `value` | Writable from expressions and events |
+| `checked` | `checked`, `value` | Both synced, writable |
+| `enabled` | `enabled` | Switch enabled state, writable |
+| `readable` | (none) | Readable from expressions, write emits a console warning |
+| `none` | (none) | No state exposed |
+
+```js
+{
+  layout: {
+    "slider:threshold": { value: 42 },
+    "text:preview": { "$content": "'Threshold: ' + threshold.value" }
+  }
+}
+```
+
+Repeatedly named components share namespace-level state. `$for` items with the same component name also share one state instance.
+
+## Lifecycle hooks
+
+The runtime calls convention-based hooks on the `g` object:
+
+```
+g.onMount_<name>()      // after component is appended to DOM
+g.onUnmount_<name>()    // before component is removed from DOM
+g.onUpdate_<name>()     // after $for item index or item reference changes
+```
+
+These hooks fire for normal components, `$if` branches, and `$for` slots. Root cleanup and `disposeNamespace()` trigger `onUnmount`.
+
+## Component disposer
+
+Framework components, event listeners, subscriptions, and external resources should bind their cleanup to the component DOM element:
+
+```ts
+import { register, attachComponentDisposer } from "slexkit/runtime";
+
+register("custom", (props, name, ctx) => {
+  const el = ctx.document.createElement("div");
+  const stop = subscribeSomething();
+  attachComponentDisposer(el, stop);
+  return el;
+});
+```
+
+The runtime calls the disposer when the element is unmounted. The official Svelte adapter uses this mechanism to destroy Svelte component instances.
+
+## Expression evaluation context
+
+Expressions in `$` read-pipes and statements in `on*` write-pipes can access these variables:
+
+| Variable | Type | Availability |
+|----------|------|--------------|
+| `g` | reactive state proxy | always |
+| `api` | host-injected capabilities | if `api` option passed to `mount()` |
+| `$event` | event data | `on*` handlers only |
+| `$item` | current array item | `$for` context only |
+| `$index` | current array index | `$for` context only |
+| `$key` | current item key | `$for` context only |
+| named component state | e.g. `threshold.value` | named components |
+
 Expression evaluation uses `new Function()` in trusted mode. Evaluation errors are caught and produce a console warning with namespace and path information; the last known value is used as a fallback.
 
 ---
@@ -748,275 +773,334 @@ Expression evaluation uses `new Function()` in trusted mode. Evaluation errors a
 
 Raw Markdown: /docs/reference/integration.md
 
----
-title: Host Integration
-category: Reference
-status: ready
-order: 40
-summary: "MarkdownRuntimeHost, trusted and secure host integrations, Streamdown, Obsidian, and custom adapters."
-slexkitRenderMode: component
----
-
-# Host Integration
-
-How to integrate SlexKit into Markdown renderers, chat hosts, document viewers, and custom platforms.
-
-## Core concepts
-
-### Artifact
-
-An artifact is a group of Slex blocks belonging to the same document, message, or note. Hosts identify an artifact by an `artifactId` and group related blocks into one runtime domain.
-
-In **trusted mode**, the runtime prefixes each block's namespace with the artifact ID to prevent cross-document state pollution. `disposeArtifact()` releases all namespace stores for that artifact.
-
-In **secure mode**, all fences in one artifact are combined into a single sandbox iframe. The runtime maintains artifact slots, syncing rendered heights back to the original Markdown placeholder containers.
-
-### Block
-
-A block is a single Slex block: one renderable unit. It has:
-- A source (Slex expression object or source string).
-- A container element (where the rendered output goes).
-- An optional `artifactId` (for grouping into an artifact).
-
-### Cleanup
-
-Every block mount returns a cleanup function. The host must call it when the block is removed. For artifact-level cleanup, call `disposeArtifact(artifactId)`. For global cleanup, call `disposeAll()`.
-
-## MarkdownRuntimeHost
-
-The `SlexKitMarkdownRuntimeHost` is the recommended API for Markdown-based hosts. It handles mode selection, artifact management, and block lifecycle.
-
-```ts
-import {
-  createSlexKitMarkdownRuntimeHost,
-  getSlexKitMarkdownRuntimeHost,
-  installSlexKitMarkdownRuntimeHost
-} from "slexkit";
-```
-
-### Interface
-
-```ts
-type SlexKitMarkdownRuntimeHost = {
-  configure(options: Partial<SlexKitMarkdownRuntimeOptions>): void;
-  getMode(): "trusted" | "secure";
-  mountBlock(block: SlexKitMarkdownBlock): () => void;
-  disposeBlock(container: HTMLElement): void;
-  disposeArtifact(artifactId: string): void;
-  disposeAll(): void;
-};
-
-type SlexKitMarkdownBlock = {
-  artifactId?: string;
-  blockId?: string;
-  source: SlexExpression | string;
-  container: HTMLElement;
-  stateOnly?: boolean;
-  theme?: ThemeMode;
-  dir?: MountOptions["dir"];
-  labels?: MountOptions["labels"];
-};
-
-type SlexKitMarkdownRuntimeOptions = {
-  mode?: "trusted" | "secure";
-  policy?: HostRuntimePolicy;
-  hostAdapter?: HostRuntimeAdapter;
-  secureFrame?: boolean | SecureFrameOptions;
-  theme?: ThemeMode;
-  dir?: MountOptions["dir"];
-  labels?: MountOptions["labels"];
-};
-```
-
-### Global singleton
-
-The module provides a global singleton for convenience:
-
-```ts
-// Install explicitly
-const runtime = installSlexKitMarkdownRuntimeHost({
-  mode: "secure",
-  policy: { execution: { maxUnresponsiveMs: 30000 } },
-  secureFrame: { runtimeUrl: "/slexkit.runtime.js" }
-});
-
-// Or use lazy global (auto-creates with defaults on first call)
-const runtime = getSlexKitMarkdownRuntimeHost();
-```
-
-Use the singleton when the entire application shares one runtime configuration. Avoid it when different host contexts need different policies.
-
-## Trusted mode integration
-
-Trusted mode runs Slex source in the host page realm. Use for local documents, application-generated content, or reviewed Slex source.
-
-```ts
-const runtime = createSlexKitMarkdownRuntimeHost({
-  mode: "trusted",
-  theme: "host-shadcn"
-});
-
-// Detect a slex fence at position <container>
-const cleanup = runtime.mountBlock({
-  artifactId: "doc-1",
-  source: fenceSource,
-  container: fenceContainer
-});
-
-// When the fence container is removed
-runtime.disposeBlock(fenceContainer);
-
-// When the document is closed
-runtime.disposeArtifact("doc-1");
-
-// When the plugin or page unloads
-runtime.disposeAll();
-```
-
-In trusted mode, the runtime automatically scopes namespaces by artifact ID (`<artifactId>::<namespace>`) to prevent different documents from polluting each other's state.
-
-State-only blocks (no `layout`, only `g` updates) are detected automatically and ingested via `ingest()`. Subsequent renderable blocks in the same artifact can read that state.
-
-## Secure mode integration
-
-Secure mode runs Slex source in a sandbox iframe. Use for untrusted or agent-generated Markdown.
-
-```ts
-const runtime = createSlexKitMarkdownRuntimeHost({
-  mode: "secure",
-  policy: {
-    execution: { maxUnresponsiveMs: 30000 }
-  },
-  secureFrame: {
-    runtimeUrl: "/slexkit.runtime.js"
-  },
-  theme: "host-shadcn"
-});
-
-const cleanup = runtime.mountBlock({
-  artifactId: "agent-msg-1",
-  source: agentGeneratedDsl,
-  container: fenceContainer
-});
-```
-
-Omitted capability policies deny access by default. Add `network`, `timer`, `animation`, or `canvas` policy objects only when the host intentionally enables those capabilities.
-
-### Artifact slot bridge
-
-When multiple secure blocks belong to the same artifact, they share one sandbox iframe. The first block (in document order) becomes the iframe anchor. Other blocks act as slots -their containers receive position and height updates from the sandbox via the postMessage bridge.
-
-```html
-<!-- In Markdown, the first fence becomes the anchor -->
-<div id="fence-1"><!-- anchor: iframe rendered here --></div>
-<div id="fence-2"><!-- slot: height synced from iframe --></div>
-<div id="fence-3"><!-- slot: height synced from iframe --></div>
-```
-
-This allows state sharing across fences within one artifact while keeping all execution confined to one sandbox.
-
-### `runtimeUrl` requirements
-
-The `runtimeUrl` must serve the SlexKit runtime as an ES module with:
-
-```
-Access-Control-Allow-Origin: *
-Content-Type: text/javascript
-```
-
-The build output includes `dist/runtime.js` for this purpose. The `slex copy-runtime` command copies that module to `public/slexkit.runtime.js` by default so existing secure-frame URLs can stay stable. Configure your CDN or static file server to serve it with the correct headers.
-
-## Streamdown / React integration
-
-The `@slexkit/streamdown` package provides a React/Streamdown custom renderer:
-
-```tsx
-import { Streamdown } from "streamdown";
-import { slexkitRenderer } from "@slexkit/streamdown";
-import "@slexkit/theme-shadcn/style.css";
-import "@slexkit/streamdown/style.css";
-
-export function Message({ markdown }: { markdown: string }) {
-  return (
-    <Streamdown plugins={{ renderers: [slexkitRenderer] }}>
-      {markdown}
-    </Streamdown>
-  );
-}
-```
-
-The renderer handles `slex` fences. It supports both trusted and secure runtime modes and can delegate to a shared Markdown runtime host instance.
-
-## Obsidian integration
-
-The official Obsidian plugin lives in <https://github.com/slexkit/obsidian-slexkit> and registers the `slex` fenced code block processor:
-
-```ts
-// In the plugin:
-registerMarkdownCodeBlockProcessor("slex", (source, el, ctx) => { ... });
-```
-
-The adapter renders blocks in **reading mode only** and does not write back to the vault. Blocks within the same note share a trusted artifact runtime.
-
-**Important**: The Obsidian adapter uses trusted mode because it renders content from the user's local vault. It is not designed as a security boundary for untrusted or agent-generated Markdown.
-
-## Writing a custom host adapter
-
-To integrate SlexKit into a custom Markdown renderer or chat host:
-
-### 1. Detect fence language
-
-Only process fences tagged with `slex`. Never scan plain JavaScript, JSON, or untagged code blocks.
-
-### 2. Create a runtime host
-
-```ts
-import { createSlexKitMarkdownRuntimeHost } from "slexkit";
-
-const runtime = createSlexKitMarkdownRuntimeHost({
-  mode: "trusted",   // or "secure"
-  theme: "host-shadcn"
-});
-```
-
-### 3. Mount blocks
-
-For each detected fence, create a container element and mount:
-
-```ts
-function processFence(source: string, fenceIndex: number) {
-  const container = document.createElement("div");
-  // Insert container at the fence position in the document
-
-  const cleanup = runtime.mountBlock({
-    artifactId: "message-42",
-    source,
-    container
-  });
-
-  return cleanup;
-}
-```
-
-### 4. Manage lifecycle
-
-```ts
-// When a single block is removed
-runtime.disposeBlock(container);
-
-// When the entire artifact (message/document) is removed
-runtime.disposeArtifact("message-42");
-
-// When the plugin/page unloads
-runtime.disposeAll();
-```
-
-### 5. Handle secure mode
-
-If using secure mode, serve `slexkit.runtime.js` as a public ES module with the correct CORS headers, and configure `secureFrame.runtimeUrl`.
-
-## Fallback rendering
-
+---
+title: Host Integration
+category: Reference
+status: ready
+order: 40
+summary: "MarkdownRuntimeHost, trusted and secure host integrations, Svelte custom hosts, Streamdown, Tiptap, Obsidian, and custom adapters."
+slexkitRenderMode: component
+---
+
+# Host Integration
+
+How to integrate SlexKit into Markdown renderers, chat hosts, document viewers, and custom platforms.
+
+## Core concepts
+
+### Artifact
+
+An artifact is a group of Slex blocks belonging to the same document, message, or note. Hosts identify an artifact by an `artifactId` and group related blocks into one runtime domain.
+
+In **trusted mode**, the runtime prefixes each block's namespace with the artifact ID to prevent cross-document state pollution. `disposeArtifact()` releases all namespace stores for that artifact.
+
+In **secure mode**, all fences in one artifact are combined into a single sandbox iframe. The runtime uses artifact slots to sync rendered heights back to the original Markdown placeholder containers.
+
+### Block
+
+A block is a single Slex block: one renderable unit. It has:
+- A source (Slex expression object or source string).
+- A container element (where the rendered output goes).
+- An optional `artifactId` (for grouping into an artifact).
+
+### Cleanup
+
+Every block mount returns a cleanup function. The host must call it when the block is removed. For artifact-level cleanup, call `disposeArtifact(artifactId)`. For global cleanup, call `disposeAll()`.
+
+## MarkdownRuntimeHost
+
+The `SlexKitMarkdownRuntimeHost` is the recommended API for Markdown-based hosts. It handles mode selection, artifact management, and block lifecycle.
+
+```ts
+import {
+  createSlexKitMarkdownRuntimeHost,
+  getSlexKitMarkdownRuntimeHost,
+  installSlexKitMarkdownRuntimeHost
+} from "slexkit";
+```
+
+### Interface
+
+```ts
+type SlexKitMarkdownRuntimeHost = {
+  configure(options: Partial<SlexKitMarkdownRuntimeOptions>): void;
+  getMode(): "trusted" | "secure";
+  mountBlock(block: SlexKitMarkdownBlock): () => void;
+  disposeBlock(container: HTMLElement): void;
+  disposeArtifact(artifactId: string): void;
+  disposeAll(): void;
+};
+
+type SlexKitMarkdownBlock = {
+  artifactId?: string;
+  blockId?: string;
+  source: SlexExpression | string;
+  container: HTMLElement;
+  stateOnly?: boolean;
+  theme?: ThemeMode;
+  dir?: MountOptions["dir"];
+  labels?: MountOptions["labels"];
+  executionMode?: MountOptions["executionMode"];
+};
+
+type SlexKitMarkdownRuntimeOptions = {
+  mode?: "trusted" | "secure";
+  policy?: HostRuntimePolicy;
+  hostAdapter?: HostRuntimeAdapter;
+  secureFrame?: boolean | SecureFrameOptions;
+  theme?: ThemeMode;
+  dir?: MountOptions["dir"];
+  labels?: MountOptions["labels"];
+  executionMode?: MountOptions["executionMode"];
+};
+```
+
+`executionMode: "preview"` is for speculative renders of repaired streaming prefixes. In preview mode, trusted mounts render readable UI but freeze write handlers, component emits, lifecycle hooks, and `api.*` capabilities. Blocks can override a host-level default by passing `executionMode` directly to `mountBlock()`.
+
+### Global singleton
+
+The module provides a global singleton for convenience:
+
+```ts
+// Install explicitly
+const runtime = installSlexKitMarkdownRuntimeHost({
+  mode: "secure",
+  policy: { execution: { maxUnresponsiveMs: 30000 } },
+  secureFrame: { runtimeUrl: "/slexkit.runtime.js" }
+});
+
+// Or use lazy global (auto-creates with defaults on first call)
+const runtime = getSlexKitMarkdownRuntimeHost();
+```
+
+Use the singleton when the entire application shares one runtime configuration. Avoid it when different host contexts need different policies.
+
+## Trusted mode integration
+
+Trusted mode runs Slex source in the host page realm. Use for local documents, application-generated content, or reviewed Slex source.
+
+```ts
+const runtime = createSlexKitMarkdownRuntimeHost({
+  mode: "trusted",
+  theme: "host-shadcn"
+});
+
+// Detect a slex fence at position <container>
+const cleanup = runtime.mountBlock({
+  artifactId: "doc-1",
+  source: fenceSource,
+  container: fenceContainer
+});
+
+// When the fence container is removed
+runtime.disposeBlock(fenceContainer);
+
+// When the document is closed
+runtime.disposeArtifact("doc-1");
+
+// When the plugin or page unloads
+runtime.disposeAll();
+```
+
+In trusted mode, the runtime automatically scopes namespaces by artifact ID (`<artifactId>::<namespace>`) to prevent different documents from polluting each other's state.
+
+State-only blocks (no `layout`, only `g` updates) are detected automatically and ingested via `ingest()`. Subsequent renderable blocks in the same artifact can read that state.
+
+## Secure mode integration
+
+Secure mode runs Slex source in a sandbox iframe. Use for untrusted or agent-generated Markdown.
+
+```ts
+const runtime = createSlexKitMarkdownRuntimeHost({
+  mode: "secure",
+  policy: {
+    execution: { maxUnresponsiveMs: 30000 }
+  },
+  secureFrame: {
+    runtimeUrl: "/slexkit.runtime.js"
+  },
+  theme: "host-shadcn"
+});
+
+const cleanup = runtime.mountBlock({
+  artifactId: "agent-msg-1",
+  source: agentGeneratedDsl,
+  container: fenceContainer
+});
+```
+
+Omitted capability policies deny access by default. Add `network`, `timer`, `animation`, or `canvas` policy objects only when the host intentionally enables those capabilities.
+
+### Artifact slot bridge
+
+When multiple secure blocks belong to the same artifact, they share one sandbox iframe. The first block (in document order) becomes the iframe anchor. Other blocks act as slots; their containers receive position and height updates from the sandbox via the postMessage bridge.
+
+```html
+<!-- In Markdown, the first fence becomes the anchor -->
+<div id="fence-1"><!-- anchor: iframe rendered here --></div>
+<div id="fence-2"><!-- slot: height synced from iframe --></div>
+<div id="fence-3"><!-- slot: height synced from iframe --></div>
+```
+
+This allows state sharing across fences within one artifact while keeping all execution confined to one sandbox.
+
+### `runtimeUrl` requirements
+
+The `runtimeUrl` must serve the SlexKit runtime as an ES module with:
+
+```
+Access-Control-Allow-Origin: *
+Content-Type: text/javascript
+```
+
+The build output includes `dist/runtime.js` for this purpose. The `slex copy-runtime` command copies that module to `public/slexkit.runtime.js` by default so existing secure-frame URLs can stay stable. Configure the CDN or static file server to serve it with the correct headers.
+
+## Svelte custom Markdown host
+
+The SlexKit website uses Svelte plus a custom Markdown renderer instead of a packaged Svelte Markdown adapter. The public contract is still `createSlexKitMarkdownRuntimeHost`; the Svelte pieces are host code.
+
+```js
+import { mount, unmount } from "svelte";
+import { createSlexKitMarkdownRuntimeHost } from "slexkit";
+import MarkdownRenderer from "./MarkdownRenderer.svelte";
+
+export function renderMarkdown(content, container, options = {}) {
+  const runtimeHost = options.slexkitRuntimeHost ?? createSlexKitMarkdownRuntimeHost({
+    mode: options.runtimeMode ?? "trusted",
+    theme: "host-shadcn"
+  });
+
+  const app = mount(MarkdownRenderer, {
+    target: container,
+    props: {
+      content,
+      runtimeHost,
+      artifactId: options.artifactId,
+      slexkitRenderMode: options.slexkitRenderMode ?? "component"
+    }
+  });
+
+  return () => unmount(app);
+}
+```
+
+Use this as an implementation reference when the host owns its Markdown AST or Svelte renderer. Do not treat `site/markdown/*` as a separately versioned package API.
+
+## Streamdown / React integration
+
+The `@slexkit/streamdown` package provides a React/Streamdown custom renderer:
+
+```tsx
+import { Streamdown } from "streamdown";
+import { slexkitRenderer } from "@slexkit/streamdown";
+import "@slexkit/theme-shadcn/style.css";
+import "@slexkit/streamdown/style.css";
+
+export function Message({ markdown }: { markdown: string }) {
+  return (
+    <Streamdown plugins={{ renderers: [slexkitRenderer] }}>
+      {markdown}
+    </Streamdown>
+  );
+}
+```
+
+The renderer handles `slex` fences. It supports both trusted and secure runtime modes and can delegate to a shared Markdown runtime host instance.
+
+During token streaming, `streaming="repair"` is the default for trusted renders. A parseable source mounts immediately; a source missing only EOF closing tokens mounts as preview; uncertain prefixes stay on the placeholder; clear syntax errors still render diagnostics. Use `streaming="stable"` to render only already-parseable prefixes, or `streaming={false}` to wait for the closing fence. Secure runtime and secure runtime-host renders do not execute repaired prefixes in the host realm.
+
+## Tiptap integration
+
+The `@slexkit/tiptap` package provides a framework-free Tiptap `CodeBlock` extension:
+
+```ts
+import StarterKit from "@tiptap/starter-kit";
+import { Markdown } from "@tiptap/markdown";
+import { createSlexKitTiptapExtension } from "@slexkit/tiptap";
+import "@slexkit/theme-shadcn/style.css";
+import "@slexkit/tiptap/style.css";
+
+const extensions = [
+  StarterKit.configure({ codeBlock: false }),
+  Markdown,
+  createSlexKitTiptapExtension({ artifactId: "doc-1" })
+];
+```
+
+The adapter only takes over `codeBlock` nodes with `language === "slex"`. Non-Slex code blocks remain ordinary Tiptap code blocks, and Markdown import/export keeps standard ` ```slex ` fences through Tiptap's Markdown extension.
+
+Each editor instance gets one trusted Markdown runtime host by default. Blocks in that editor share an artifact ID, so state-only fences can seed later renderable fences. Pass `runtimeHost` or `artifactId` when the host needs explicit lifecycle ownership.
+
+## Obsidian integration
+
+The official Obsidian plugin is available at <https://github.com/slexkit/obsidian-slexkit> and registers the `slex` fenced code block processor:
+
+```ts
+// In the plugin:
+registerMarkdownCodeBlockProcessor("slex", (source, el, ctx) => { ... });
+```
+
+The adapter renders blocks in **reading mode only** and does not write back to the vault. Blocks within the same note share a trusted artifact runtime.
+
+**Important**: The Obsidian adapter uses trusted mode because it renders content from the user's local vault. It is not designed as a security boundary for untrusted or agent-generated Markdown.
+
+## Writing a custom host adapter
+
+To integrate SlexKit into a custom Markdown renderer or chat host:
+
+### 1. Detect fence language
+
+Only process fences tagged with `slex`. Never scan plain JavaScript, JSON, or untagged code blocks.
+
+### 2. Create a runtime host
+
+```ts
+import { createSlexKitMarkdownRuntimeHost } from "slexkit";
+
+const runtime = createSlexKitMarkdownRuntimeHost({
+  mode: "trusted",   // or "secure"
+  theme: "host-shadcn"
+});
+```
+
+### 3. Mount blocks
+
+For each detected fence, create a container element and mount:
+
+```ts
+function processFence(source: string, fenceIndex: number) {
+  const container = document.createElement("div");
+  // Insert container at the fence position in the document
+
+  const cleanup = runtime.mountBlock({
+    artifactId: "message-42",
+    source,
+    container
+  });
+
+  return cleanup;
+}
+```
+
+### 4. Manage lifecycle
+
+```ts
+// When a single block is removed
+runtime.disposeBlock(container);
+
+// When the entire artifact (message/document) is removed
+runtime.disposeArtifact("message-42");
+
+// When the plugin/page unloads
+runtime.disposeAll();
+```
+
+### 5. Handle secure mode
+
+If using secure mode, serve `slexkit.runtime.js` as a public ES module with the correct CORS headers, and configure `secureFrame.runtimeUrl`.
+
+## Fallback rendering
+
 SlexKit-capable hosts should still include the raw fence content or a plain text fallback in the DOM for environments that don't support SlexKit. The runtime replaces the container children, so fallback text is only visible before mount or after disposal.
 
 ---
@@ -1025,456 +1109,643 @@ SlexKit-capable hosts should still include the raw fence content or a plain text
 
 Raw Markdown: /docs/reference/security.md
 
----
-title: Security Runtime Contract
-category: Reference
-status: ready
-order: 50
-summary: "Threat model, sandbox iframe deployment, host policy, postMessage bridge, and fail-closed behavior."
-slexkitRenderMode: component
----
-
-# Security Runtime Contract
-
-The secure runtime defines what untrusted Slex source can and cannot do, how the host authorizes capabilities, and how sandbox isolation works.
-
-## Threat model
-
-- The host page and host application are trusted.
-- Slex source may be untrusted.
-- Secure artifacts run inside a sandbox iframe.
-- The iframe uses an opaque origin by default (no `allow-same-origin`).
-- Slex source must not access the host DOM, cookies, `localStorage`, `IndexedDB`, or host global objects.
-
-Secure mode confines expression execution to an isolated environment and consolidates sensitive capabilities under the host `policy` and `api.*`.
-
-## Authorization source
-
-The sole authorization source is the `HostRuntimePolicy` provided by the host. Slex source fields such as `capabilities`, `permissions`, `api`, or other top-level declarations cannot grant themselves authority.
-
-All capabilities are accessed through `api.*`:
-
-```
-api.get(url, options)
-api.post(url, body, options)
-api.fetch(url, options)
-
-api.setTimeout(fn, ms)
-api.clearTimeout(id)
-api.setInterval(fn, ms)
-api.clearInterval(id)
-
-api.raf(fn)
-api.cancelRaf(id)
-
-api.createCanvas(width, height)
-api.getCanvasContext(canvas, contextId, options)
-
-api.onDispose(fn)
-api.now()
-
-api.isTimeoutError(error)
-api.isNetworkError(error)
-api.isPolicyError(error)
-api.errorMessage(error)
-```
-
-Capabilities not exposed through `api.*` are unsupported.
-
-## HostRuntimePolicy
-
-```ts
-type HostRuntimePolicy = {
-  network?: {
-    enabled: boolean;
-    methods: ("GET" | "POST")[];
-    allowOrigins: string[];
-    allowHeaders?: string[];
-    allowContentTypes?: string[];
-    credentials: "omit" | "same-origin" | "include";
-    timeoutMs: number;
-    maxBodyBytes: number;
-    maxResponseBytes?: number;
-  };
-  timer?: {
-    enabled: boolean;
-    maxTimers: number;
-    minIntervalMs: number;
-  };
-  animation?: {
-    enabled: boolean;
-  };
-  canvas?: {
-    enabled: boolean;
-    maxCanvases?: number;
-    maxPixels?: number;
-    allowedContexts?: ("2d" | "webgl" | "webgl2" | "bitmaprenderer")[];
-  };
-  execution?: {
-    heartbeatIntervalMs?: number;
-    maxUnresponsiveMs?: number;
-  };
-};
-```
-
-### Network policy
-
-Network is denied by default unless `policy.network.enabled` is `true`. The policy constrains:
-- HTTP method (only listed methods allowed)
-- Origin (supports `*`, exact match, `protocol://*` protocol wildcard, and `protocol://*.domain` subdomain wildcard)
-- Request headers (only listed headers pass; `Authorization`, `Cookie`, `Proxy-Authorization`, `Set-Cookie`, and Sec-Fetch headers are always blocked)
-- Credentials mode
-- Request body size
-- Request timeout
-- Response body size
-- Response content-type
-
-`hostAdapter.fetch` can replace the actual request implementation. `hostAdapter.onNetworkLog` is observational only -it must not alter runtime behavior.
-
-### Timer, animation, and canvas
-
-- **Timer**: denied by default. When enabled, subject to `maxTimers` (total concurrent) and `minIntervalMs` (minimum delay). All timers and intervals are cleaned up on dispose.
-- **Animation**: denied by default. Controlled via `animation.enabled`; `api.raf` is the only animation primitive.
-- **Canvas**: denied by default. When enabled, subject to `maxCanvases`, `maxPixels`, and `allowedContexts`.
-
-### Execution monitoring
-
-`execution.heartbeatIntervalMs` controls how often the sandbox sends a heartbeat to the host. `execution.maxUnresponsiveMs` defines the maximum silence before the sandbox is terminated as unresponsive.
-
-## HostRuntimeAdapter
-
-The adapter allows the host to override or observe runtime behavior:
-
-```ts
-type HostRuntimeAdapter = {
-  fetch?: (request: HostFetchRequest) => Promise<NetworkResult>;
-  onNetworkLog?: (event: RuntimeNetworkLogEvent) => void;
-  onRuntimeError?: (event: RuntimeErrorEvent) => void;
-  now?: () => number;
-  setTimeout?: (fn: () => void, ms: number) => TimerId;
-  clearTimeout?: (id: TimerId) => void;
-  setInterval?: (fn: () => void, ms: number) => TimerId;
-  clearInterval?: (id: TimerId) => void;
-  requestAnimationFrame?: (fn: (time: number) => void) => RafId;
-  cancelAnimationFrame?: (id: RafId) => void;
-};
-```
-
-`onNetworkLog` and `onRuntimeError` are audit hooks -they must not change runtime behavior. Errors thrown within them are silently caught.
-
-## Sandbox iframe deployment
-
-The secure frame imports the main runtime module from a `runtimeUrl`:
-
-```ts
-mountSecureArtifact(script, container, {
-  frame: {
-    runtimeUrl: "/slexkit.runtime.js"
-  }
-});
-```
-
-This URL must serve as a public ES module and return:
-
-```
-Access-Control-Allow-Origin: *
-Content-Type: text/javascript
-```
-
-This is server or deployment layer configuration -it cannot be set from frontend JavaScript.
-
-### CSP
-
-The sandbox iframe is served via `srcdoc` with a strict Content-Security-Policy:
-
-```
-default-src 'none'
-script-src 'nonce-{random}' 'unsafe-eval' {runtimeOrigin}
-connect-src 'none'
-img-src data: blob:
-style-src 'unsafe-inline'
-font-src data:
-form-action 'none'
-base-uri 'none'
-```
-
-A random nonce is generated for each frame instance. `unsafe-eval` is required because Slex source expression evaluation uses `eval()` inside the sandbox.
-
-### Sandbox attribute
-
-The iframe requires `allow-scripts`. `allow-same-origin` is **blocked by default** -it would weaken the opaque origin isolation. Only set `unsafeAllowSameOrigin: true` explicitly if the host accepts the risk:
-
-```ts
-frame: {
-  unsafeAllowSameOrigin: true,  // only with explicit host acceptance
-  sandbox: "allow-scripts allow-same-origin"
-}
-```
-
-Do not add `allow-same-origin` to fix CORS or debugging issues.
-
-## postMessage bridge protocol
-
-The host and sandbox communicate via `window.postMessage`. All messages are tagged with `channel: "slexkit-secure"`.
-
-### Host -Sandbox messages
-
-| Type | Purpose |
-|------|---------|
-| `mount` | Sends Slex source, policy, theme to render |
-| `dispose` | Tells sandbox to tear down |
-| `fetch-result` | Returns fetch response or error |
-| `slots` | Synchronizes artifact slot positions |
-
-### Sandbox -Host messages
-
-| Type | Purpose |
-|------|---------|
-| `ready` | Runner module loaded and listening |
-| `mounted` | Artifact render confirmed |
-| `disposed` | Sandbox teardown acknowledged |
-| `heartbeat` | Periodic liveness signal |
-| `error` | Mount or runtime error |
-| `fetch` | Proxied network request |
-| `slot-size` | Artifact slot height report |
-
-Every host→sandbox message includes an `id` and `token`. The token is opaque, cryptographically random, and scoped to a single mount instance. Messages with mismatched tokens are rejected.
-
-Messages are verified: the sandbox checks `event.source === window.parent`; the host checks `event.source === iframe.contentWindow`.
-
-## Artifact slot bridge
-
-Multiple Markdown fences belonging to one artifact share a single sandbox iframe. The host sends slot rectangles to the sandbox, which renders each fence's output inside the corresponding slot container. The sandbox reports each slot's rendered height back via `slot-size` messages.
-
-A `ResizeObserver` on the host side and inside the sandbox keeps positions and heights synchronized. This allows visual continuity across fence boundaries while keeping all execution confined to one isolation context.
-
-## Heartbeat watchdog
-
-When `execution.maxUnresponsiveMs` is set, the host monitors the sandbox heartbeat interval. If no heartbeat arrives within the threshold, the iframe is terminated, a diagnostic alert (`role="alert"`) is rendered, and a `console.error` is emitted.
-
-## Fail-closed behavior
-
-If the iframe cannot load the runtime, does not send a ready/mounted message, or the heartbeat times out, SlexKit:
-
-1. Removes the unresponsive iframe.
-2. Renders a `role="alert"` diagnostic element with a description of the failure.
-3. Emits the same information via `console.error`.
-
-Load timeout is configurable via `frame.loadTimeoutMs` (default: 8000ms).
-
-## Escape hatches
-
-### `unsafeInlineExecution`
-
-Allows a secure artifact to execute inline in the host page with an injected secure runtime API. **Intended for testing or host-trusted content only.** Not recommended for untrusted paths.
-
-```ts
-mountSecureArtifact(script, container, {
-  policy,
-  hostAdapter,
-  unsafeInlineExecution: true
-});
-```
-
-### `unsafeAllowSameOrigin`
-
-Allows `allow-same-origin` in the sandbox attribute. **Reduces isolation strength** -only use when the host explicitly accepts the risk.
-
-```ts
-frame: {
-  sandbox: "allow-scripts allow-same-origin",
-  unsafeAllowSameOrigin: true
-}
-```
-
-## Sandbox hardening
-
-When the sandbox runner starts, it hardens the global scope:
-
-**Blocked network globals** -`fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource`, `Worker`, `SharedWorker`, and `navigator.sendBeacon` are replaced with functions that throw, ensuring all network traffic must go through the bridge.
-
-**Blocked scheduling globals** -`setTimeout`, `setInterval`, `requestAnimationFrame` are replaced with functions that throw, directing code to `api.setTimeout()`, `api.setInterval()`, and `api.raf()`.
-
-**Canvas prototype wrapping** -`HTMLCanvasElement.prototype.getContext` is wrapped to enforce canvas policy on context creation. `OffscreenCanvas` is replaced with a subclass that validates dimensions on construction.
-
-## Maintenance principles
-
-- New capabilities must define a policy field first, then an `api.*` method, then the bridge.
-- Slex source declarations are never an authorization source.
-- Default to opaque origin.
-- Always fail closed.
-- Log and error hooks are observational -they must not alter runtime behavior.
+---
+title: Security Runtime Contract
+category: Reference
+status: ready
+order: 50
+summary: "Threat model, sandbox iframe deployment, host policy, postMessage bridge, and fail-closed behavior."
+slexkitRenderMode: component
+---
+
+# Security Runtime Contract
+
+The secure runtime defines what untrusted Slex source can and cannot do, how the host authorizes capabilities, and how sandbox isolation works.
+
+## Threat model
+
+- The host page and host application are trusted.
+- Slex source may be untrusted.
+- Secure artifacts run inside a sandbox iframe.
+- The iframe uses an opaque origin by default (no `allow-same-origin`).
+- Slex source must not access the host DOM, cookies, `localStorage`, `IndexedDB`, or host global objects.
+
+Secure mode confines expression execution to an isolated environment and consolidates sensitive capabilities under the host `policy` and `api.*`.
+
+## Authorization source
+
+The sole authorization source is the `HostRuntimePolicy` provided by the host. Slex source fields such as `capabilities`, `permissions`, `api`, or other top-level declarations cannot grant themselves authority.
+
+All capabilities are accessed through `api.*`:
+
+```
+api.get(url, options)
+api.post(url, body, options)
+api.fetch(url, options)
+
+api.setTimeout(fn, ms)
+api.clearTimeout(id)
+api.setInterval(fn, ms)
+api.clearInterval(id)
+
+api.raf(fn)
+api.cancelRaf(id)
+
+api.createCanvas(width, height)
+api.getCanvasContext(canvas, contextId, options)
+
+api.onDispose(fn)
+api.now()
+
+api.isTimeoutError(error)
+api.isNetworkError(error)
+api.isPolicyError(error)
+api.errorMessage(error)
+```
+
+Capabilities not exposed through `api.*` are unsupported.
+
+## HostRuntimePolicy
+
+```ts
+type HostRuntimePolicy = {
+  network?: {
+    enabled: boolean;
+    methods: ("GET" | "POST")[];
+    allowOrigins: string[];
+    allowHeaders?: string[];
+    allowContentTypes?: string[];
+    credentials: "omit" | "same-origin" | "include";
+    timeoutMs: number;
+    maxBodyBytes: number;
+    maxResponseBytes?: number;
+  };
+  timer?: {
+    enabled: boolean;
+    maxTimers: number;
+    minIntervalMs: number;
+  };
+  animation?: {
+    enabled: boolean;
+  };
+  canvas?: {
+    enabled: boolean;
+    maxCanvases?: number;
+    maxPixels?: number;
+    allowedContexts?: ("2d" | "webgl" | "webgl2" | "bitmaprenderer")[];
+  };
+  execution?: {
+    heartbeatIntervalMs?: number;
+    maxUnresponsiveMs?: number;
+  };
+};
+```
+
+### Network policy
+
+Network is denied by default unless `policy.network.enabled` is `true`. The policy constrains:
+- HTTP method (only listed methods allowed)
+- Origin (supports `*`, exact match, `protocol://*` protocol wildcard, and `protocol://*.domain` subdomain wildcard)
+- Request headers (only listed headers pass; `Authorization`, `Cookie`, `Proxy-Authorization`, `Set-Cookie`, and Sec-Fetch headers are always blocked)
+- Credentials mode
+- Request body size
+- Request timeout
+- Response body size
+- Response content-type
+
+`hostAdapter.fetch` can replace the actual request implementation. `hostAdapter.onNetworkLog` is observational only; it must not alter runtime behavior.
+
+### Timer, animation, and canvas
+
+- **Timer**: denied by default. When enabled, subject to `maxTimers` (total concurrent) and `minIntervalMs` (minimum delay). All timers and intervals are cleaned up on dispose.
+- **Animation**: denied by default. Controlled via `animation.enabled`; `api.raf` is the only animation primitive.
+- **Canvas**: denied by default. When enabled, subject to `maxCanvases`, `maxPixels`, and `allowedContexts`.
+
+### Execution monitoring
+
+`execution.heartbeatIntervalMs` controls how often the sandbox sends a heartbeat to the host. `execution.maxUnresponsiveMs` defines the maximum silence before the sandbox is terminated as unresponsive.
+
+## HostRuntimeAdapter
+
+The adapter allows the host to override or observe runtime behavior:
+
+```ts
+type HostRuntimeAdapter = {
+  fetch?: (request: HostFetchRequest) => Promise<NetworkResult>;
+  onNetworkLog?: (event: RuntimeNetworkLogEvent) => void;
+  onRuntimeError?: (event: RuntimeErrorEvent) => void;
+  now?: () => number;
+  setTimeout?: (fn: () => void, ms: number) => TimerId;
+  clearTimeout?: (id: TimerId) => void;
+  setInterval?: (fn: () => void, ms: number) => TimerId;
+  clearInterval?: (id: TimerId) => void;
+  requestAnimationFrame?: (fn: (time: number) => void) => RafId;
+  cancelAnimationFrame?: (id: RafId) => void;
+};
+```
+
+`onNetworkLog` and `onRuntimeError` are audit hooks; they must not change runtime behavior. Errors thrown within them are silently caught.
+
+## Sandbox iframe deployment
+
+The secure frame imports the main runtime module from a `runtimeUrl`:
+
+```ts
+mountSecureArtifact(script, container, {
+  frame: {
+    runtimeUrl: "/slexkit.runtime.js"
+  }
+});
+```
+
+This URL must serve as a public ES module and return:
+
+```
+Access-Control-Allow-Origin: *
+Content-Type: text/javascript
+```
+
+This is server or deployment layer configuration; it cannot be set from frontend JavaScript.
+
+### CSP
+
+The sandbox iframe is served via `srcdoc` with a strict Content-Security-Policy:
+
+```
+default-src 'none'
+script-src 'nonce-{random}' 'unsafe-eval' {runtimeOrigin}
+connect-src 'none'
+img-src data: blob:
+style-src 'unsafe-inline'
+font-src data:
+form-action 'none'
+base-uri 'none'
+```
+
+A random nonce is generated for each frame instance. `unsafe-eval` is required because Slex source expression evaluation uses `eval()` inside the sandbox.
+
+### Sandbox attribute
+
+The iframe requires `allow-scripts`. `allow-same-origin` is **blocked by default** because it would weaken the opaque origin isolation. Only set `unsafeAllowSameOrigin: true` explicitly if the host accepts the risk:
+
+```ts
+frame: {
+  unsafeAllowSameOrigin: true,  // only with explicit host acceptance
+  sandbox: "allow-scripts allow-same-origin"
+}
+```
+
+Do not add `allow-same-origin` to fix CORS or debugging issues.
+
+## postMessage bridge protocol
+
+The host and sandbox communicate via `window.postMessage`. All messages are tagged with `channel: "slexkit-secure"`.
+
+### Host -Sandbox messages
+
+| Type | Purpose |
+|------|---------|
+| `mount` | Sends Slex source, policy, theme to render |
+| `dispose` | Tells sandbox to tear down |
+| `fetch-result` | Returns fetch response or error |
+| `slots` | Synchronizes artifact slot positions |
+
+### Sandbox -Host messages
+
+| Type | Purpose |
+|------|---------|
+| `ready` | Runner module loaded and listening |
+| `mounted` | Artifact render confirmed |
+| `disposed` | Sandbox teardown acknowledged |
+| `heartbeat` | Periodic liveness signal |
+| `error` | Mount or runtime error |
+| `fetch` | Proxied network request |
+| `slot-size` | Artifact slot height report |
+
+Every host→sandbox message includes an `id` and `token`. The token is opaque, cryptographically random, and scoped to a single mount instance. Messages with mismatched tokens are rejected.
+
+Messages are verified: the sandbox checks `event.source === window.parent`; the host checks `event.source === iframe.contentWindow`.
+
+## Artifact slot bridge
+
+Multiple Markdown fences belonging to one artifact share a single sandbox iframe. The host sends slot rectangles to the sandbox, which renders each fence's output inside the corresponding slot container. The sandbox reports each slot's rendered height back via `slot-size` messages.
+
+A `ResizeObserver` on the host side and inside the sandbox keeps positions and heights synchronized. This preserves visual continuity across fences while keeping all execution confined to one isolation context.
+
+## Heartbeat watchdog
+
+When `execution.maxUnresponsiveMs` is set, the host monitors the sandbox heartbeat interval. If no heartbeat arrives within the threshold, the iframe is terminated, a diagnostic alert (`role="alert"`) is rendered, and a `console.error` is emitted.
+
+## Fail-closed behavior
+
+If the iframe cannot load the runtime, does not send a ready/mounted message, or the heartbeat times out, SlexKit:
+
+1. Removes the unresponsive iframe.
+2. Renders a `role="alert"` diagnostic element with a description of the failure.
+3. Emits the same information via `console.error`.
+
+Load timeout is configurable via `frame.loadTimeoutMs` (default: 8000ms).
+
+## Escape hatches
+
+### `unsafeInlineExecution`
+
+Allows a secure artifact to execute inline in the host page with an injected secure runtime API. **Intended for testing or host-trusted content only.** Not recommended for untrusted paths.
+
+```ts
+mountSecureArtifact(script, container, {
+  policy,
+  hostAdapter,
+  unsafeInlineExecution: true
+});
+```
+
+### `unsafeAllowSameOrigin`
+
+Allows `allow-same-origin` in the sandbox attribute. **Reduces isolation strength**; only use when the host explicitly accepts the risk.
+
+```ts
+frame: {
+  sandbox: "allow-scripts allow-same-origin",
+  unsafeAllowSameOrigin: true
+}
+```
+
+## Sandbox hardening
+
+When the sandbox runner starts, it hardens the global scope:
+
+**Blocked network globals** -`fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource`, `Worker`, `SharedWorker`, and `navigator.sendBeacon` are replaced with functions that throw, ensuring all network traffic must go through the bridge.
+
+**Blocked scheduling globals** -`setTimeout`, `setInterval`, `requestAnimationFrame` are replaced with functions that throw, directing code to `api.setTimeout()`, `api.setInterval()`, and `api.raf()`.
+
+**Canvas prototype wrapping** -`HTMLCanvasElement.prototype.getContext` is wrapped to enforce canvas policy on context creation. `OffscreenCanvas` is replaced with a subclass that validates dimensions on construction.
+
+## Maintenance principles
+
+- New capabilities must define a policy field first, then an `api.*` method, then the bridge.
+- Slex source declarations are never an authorization source.
+- Default to opaque origin.
+- Always fail closed.
+- Log and error hooks are observational; they must not alter runtime behavior.
 
 ---
 
-## Package Boundaries
+## Packages
 
 Raw Markdown: /docs/reference/packages.md
 
----
-title: Package Boundaries
-category: Reference
-status: ready
-order: 60
-summary: "Package relationships, installation matrix, publish contents, and release quality gates."
-slexkitRenderMode: component
----
-
-# Package Boundaries
-
-SlexKit v0/beta npm packages, their relationships, and installation.
-
-## Package relationship
-
-```
-slexkit (root - real code)
- ├── runtime entry
- ├── Svelte component registrations
- ├── ToolHost
- ├── default styles
- └── secure iframe runner
-
- @slexkit/runtime (thin wrapper) ─── re-exports slexkit/runtime
- @slexkit/components-svelte (thin wrapper) ─── re-exports slexkit/components-svelte
- @slexkit/theme-shadcn ─── CSS only
- @slexkit/streamdown ─── React/Streamdown renderer
- @slexkit/mcp ─── read-only MCP server for AI agents
-```
-
-`@slexkit/runtime` and `@slexkit/components-svelte` are thin wrappers that re-export from the root `slexkit` package. They are not standalone physical packages; installing them still requires installing `slexkit`. `@slexkit/theme-shadcn` is CSS-only and contains no runtime implementation.
-
-## slexkit (root)
-
-The actual implementation package. Contains the runtime engine, official Svelte components, ToolHost, and styles.
-
-```sh
-npm install slexkit
-```
-
-```js
-import { mount, disposeNamespace, boot } from "slexkit";
-import "slexkit/style.css";       // default styles (includes all component CSS)
-import "slexkit/dist/style.css";  // same distributed CSS bundle via dist alias
-```
-
-Version helpers are exported from both the root and runtime entries:
-
-```js
-import { SLEXKIT_VERSION, SLEX_PROTOCOL_VERSION, getSlexKitInfo } from "slexkit";
-```
-
-## @slexkit/runtime
-
-Component-free runtime entry point. Does not auto-register any official Svelte components.
-
-```sh
-npm install slexkit @slexkit/runtime
-```
-
-```js
-import { mount, register, createSecureRuntime } from "@slexkit/runtime";
-```
-
-Use this when you want to register your own component set instead of the bundled Svelte components.
-
-## @slexkit/components-svelte
-
-Side-effect import that registers all official Svelte components into the runtime registry.
-
-```sh
-npm install slexkit @slexkit/runtime @slexkit/components-svelte
-```
-
-```js
-import { mount } from "@slexkit/runtime";
-import "@slexkit/components-svelte";
-```
-
-Public component specs: action (2), component capability (1), content (6), data (1), disclosure (2), display (2), feedback (2), input (6), layout (4), navigation (1), tooling (1).
+---
+title: Packages
+category: Reference
+status: ready
+order: 60
+summary: "SlexKit npm package roles, install combinations, publish contents, and release checks."
+slexkitRenderMode: component
+---
+
+# Packages
+
+SlexKit v0/beta package references list npm packages, install commands, and release checks.
+
+## Package Map
+
+```
+slexkit (root package)
+ ├── runtime entry
+ ├── Svelte component registrations
+ ├── ToolHost
+ ├── default styles
+ └── secure iframe runner
+
+ @slexkit/runtime ─── re-exports slexkit/runtime
+ @slexkit/components-svelte ─── re-exports slexkit/components-svelte
+ @slexkit/theme-shadcn ─── CSS only
+ @slexkit/streamdown ─── React/Streamdown renderer
+ @slexkit/assistant-ui ─── assistant-ui Streamdown text wrapper
+ @slexkit/tiptap ─── framework-free Tiptap NodeView adapter
+ @slexkit/mcp ─── read-only MCP server for AI agents
+```
+
+`@slexkit/runtime` and `@slexkit/components-svelte` are published npm packages, but their code wraps the root `slexkit` package. They are not independent implementation packages; installing them still requires installing `slexkit`. `@slexkit/theme-shadcn` is CSS-only and contains no runtime implementation.
+
+## slexkit (root)
+
+The main implementation package. It contains the runtime engine, official Svelte components, ToolHost, and styles.
+
+```sh
+npm install slexkit
+```
+
+```js
+import { mount, disposeNamespace, boot } from "slexkit";
+import "slexkit/style.css";       // default styles (includes all component CSS)
+```
+
+`slexkit/dist/style.css` is a compatibility alias for the same distributed CSS bundle; do not import both paths.
+
+Version helpers are exported from both the root and runtime entries:
+
+```js
+import { SLEXKIT_VERSION, SLEX_PROTOCOL_VERSION, getSlexKitInfo } from "slexkit";
+```
+
+The root package also ships the `slex` CLI:
+
+```sh
+slex copy-runtime public/slexkit.runtime.js
+slex validate ./artifact.slex --mode secure
+slex validate --standard
+```
+
+`slex validate --standard` runs the bundled Slex conformance fixtures against the validator shipped with the package. Use `--json` for CI or agent consumption.
+
+## @slexkit/runtime
+
+Component-free runtime entry point. Does not auto-register any official Svelte components.
+
+```sh
+npm install slexkit @slexkit/runtime
+```
+
+```js
+import { mount, register, createSecureRuntime } from "@slexkit/runtime";
+```
+
+Use this to register a custom component set instead of the bundled Svelte components.
+
+## @slexkit/components-svelte
+
+Side-effect import that registers all official Svelte components into the runtime registry.
+
+```sh
+npm install slexkit @slexkit/runtime @slexkit/components-svelte
+```
+
+```js
+import { mount } from "@slexkit/runtime";
+import "@slexkit/components-svelte";
+```
+
+Public component specs: action (1), component (1), content (6), data (1), disclosure (2), display (3), feedback (2), input (6), layout (4), navigation (1), tooling (3).
+
+## @slexkit/theme-shadcn
+
+CSS theme bundle (shadcn/ui compatible).
+
+```sh
+npm install @slexkit/theme-shadcn
+```
+
+```js
+import "@slexkit/theme-shadcn/style.css";
+```
+
+## @slexkit/streamdown
+
+React/Streamdown custom renderer for Markdown-hosted SlexKit fences.
+
+```sh
+npm install slexkit @slexkit/theme-shadcn @slexkit/streamdown streamdown react react-dom
+```
+
+```tsx
+import { Streamdown } from "streamdown";
+import { slexkitRenderer } from "@slexkit/streamdown";
+import "@slexkit/theme-shadcn/style.css";
+import "@slexkit/streamdown/style.css";
+
+export function Message({ markdown }: { markdown: string }) {
+  return (
+    <Streamdown plugins={{ renderers: [slexkitRenderer] }}>
+      {markdown}
+    </Streamdown>
+  );
+}
+```
+
+Processes `slex` fences. Supports both trusted and secure runtime modes.
+
+## @slexkit/assistant-ui
+
+assistant-ui message text wrapper for SlexKit fences. It delegates Markdown rendering to `@assistant-ui/react-streamdown` and only overrides the `slex` language block with `@slexkit/streamdown`.
+
+```sh
+npm install slexkit @slexkit/theme-shadcn @slexkit/streamdown @slexkit/assistant-ui @assistant-ui/react @assistant-ui/react-streamdown streamdown react react-dom
+```
+
+```tsx
+import { MessagePrimitive } from "@assistant-ui/react";
+import { SlexKitAssistantStreamdownText } from "@slexkit/assistant-ui";
+import "@slexkit/theme-shadcn/style.css";
+import "@slexkit/assistant-ui/style.css";
+
+export function AssistantMessage() {
+  return (
+    <MessagePrimitive.Parts>
+      {({ part }) =>
+        part.type === "text" ? (
+          <SlexKitAssistantStreamdownText
+            artifactId="message-1"
+            secureFrame={{ runtimeUrl: "/slexkit.runtime.js" }}
+          />
+        ) : null
+      }
+    </MessagePrimitive.Parts>
+  );
+}
+```
+
+The runtime defaults to secure. assistant-ui tool calls and ToolHost flows still use their own integration layers.
+
+## @slexkit/tiptap
+
+Tiptap extension for rendering explicit `slex` code blocks as SlexKit previews while preserving normal fenced code block Markdown roundtrip.
+
+```sh
+npm install slexkit @slexkit/theme-shadcn @slexkit/tiptap @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extension-code-block @tiptap/markdown
+```
+
+```ts
+import StarterKit from "@tiptap/starter-kit";
+import { createSlexKitTiptapExtension } from "@slexkit/tiptap";
+import "@slexkit/theme-shadcn/style.css";
+import "@slexkit/tiptap/style.css";
+
+const extensions = [
+  StarterKit.configure({ codeBlock: false }),
+  createSlexKitTiptapExtension({ artifactId: "doc-1" })
+];
+```
+
+The extension only takes over code blocks whose language is `slex`; ordinary code blocks stay native to Tiptap. It uses a trusted Markdown runtime host unless configured otherwise. Add `@tiptap/markdown` when loading or exporting Markdown.
+
+## Obsidian plugin
+
+The official Obsidian plugin lives in a separate release repository: <https://github.com/slexkit/obsidian-slexkit>.
+
+Install **SlexKit** through Obsidian Community Plugins for normal vault use. Use BRAT or manual GitHub release assets only when testing unreleased builds from `slexkit/obsidian-slexkit`.
+
+The community plugin is marked desktop-only and compatible with Obsidian 1.5.0+.
+
+The plugin treats the user's local vault as trusted and uses trusted runtime mode. Do not use it as a sandbox for third-party or agent-generated Markdown; the v0 adapter does not include secure sandbox support.
+
+## @slexkit/mcp
+
+Read-only MCP server for AI agents. It serves generated LLM docs, component metadata, examples, runtime docs, ToolHost docs, and Slex source validation.
+
+```sh
+npx -y @slexkit/mcp
+```
+
+The server does not modify project files. Use it when an agent needs SlexKit component or runtime context.
+
+## Installation matrix
+
+| Use case | Install command |
+|----------|----------------|
+| Quick start, everything included | `npm install slexkit` |
+| Component-free, custom components | `npm install slexkit @slexkit/runtime` |
+| With Svelte components | `npm install slexkit @slexkit/runtime @slexkit/components-svelte` |
+| Add shadcn theme | `npm install @slexkit/theme-shadcn` |
+| React/Streamdown host | `npm install slexkit @slexkit/theme-shadcn @slexkit/streamdown streamdown react react-dom` |
+| assistant-ui host | `npm install slexkit @slexkit/theme-shadcn @slexkit/streamdown @slexkit/assistant-ui @assistant-ui/react @assistant-ui/react-streamdown streamdown react react-dom` |
+| Tiptap editor host | `npm install slexkit @slexkit/theme-shadcn @slexkit/tiptap @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extension-code-block @tiptap/markdown` |
+| Obsidian plugin | Install **SlexKit** from Obsidian Community Plugins |
+| AI agent MCP server | `npx -y @slexkit/mcp` |
+
+## v0 Package Layout
+
+In v0, the root `slexkit` package carries the main implementation. Scoped `@slexkit/*` packages provide clearer install entry points. If these become physical packages later, source code, build output, and publish workflows need to split together.
+
+## Release Check
+
+Check all scoped packages together before publishing:
+
+```sh
+bun run build
+bun run test
+bun run lint
+bun run smoke:release
+npm pack --dry-run --json
+slex validate --standard --json
+```
+
+The release smoke packs and installs every scoped package in this repository, verifies public entry points, verifies CSS subpath exports, runs the installed `slex validate --standard --json`, and starts the MCP stdio binary to check `initialize`, `tools/list`, and `slexkitValidate`.
+
+Before publishing, check that `npm pack --dry-run --json` includes `dist/standard/*` and `scripts/cli.mjs`. Standard artifacts must match `package.json`, `SLEX_PROTOCOL_VERSION`, and the bundled conformance fixtures.
 
-## @slexkit/theme-shadcn
-
-CSS theme bundle (shadcn/ui compatible).
-
-```sh
-npm install @slexkit/theme-shadcn
-```
-
-```js
-import "@slexkit/theme-shadcn/style.css";
-```
-
-## @slexkit/streamdown
-
-React/Streamdown custom renderer for Markdown-hosted SlexKit fences.
-
-```sh
-npm install slexkit @slexkit/theme-shadcn @slexkit/streamdown streamdown react react-dom
-```
-
-```tsx
-import { Streamdown } from "streamdown";
-import { slexkitRenderer } from "@slexkit/streamdown";
-import "@slexkit/theme-shadcn/style.css";
-import "@slexkit/streamdown/style.css";
-
-export function Message({ markdown }: { markdown: string }) {
-  return (
-    <Streamdown plugins={{ renderers: [slexkitRenderer] }}>
-      {markdown}
-    </Streamdown>
-  );
-}
-```
-
-Processes `slex` fences. Supports both trusted and secure runtime modes.
-
-## Obsidian plugin
-
-The official Obsidian plugin lives in a separate release repository: <https://github.com/slexkit/obsidian-slexkit>.
-
-Install **SlexKit** through Obsidian Community Plugins for normal vault use. Use BRAT or manual GitHub release assets only when testing unreleased builds from `slexkit/obsidian-slexkit`.
-
-The community plugin is currently desktop-only and compatible with Obsidian 1.5.0+. Mobile support should be enabled only after real mobile vault testing.
-
-The adapter uses trusted runtime mode - it renders content from the user's local vault and is not designed as a sandbox for third-party or agent-generated Markdown. Secure sandbox support is not part of the v0 adapter.
-
-## @slexkit/mcp
-
-Read-only MCP server for AI agents. It serves generated LLM docs, component metadata, examples, runtime docs, ToolHost docs, and Slex source validation.
-
-```sh
-npx -y @slexkit/mcp
-```
-
-The server does not modify project files. Use it when an agent needs current SlexKit component or runtime context.
-
-## Installation matrix
-
-| Use case | Install command |
-|----------|----------------|
-| Quick start, everything included | `npm install slexkit` |
-| Component-free, custom components | `npm install slexkit @slexkit/runtime` |
-| With Svelte components | `npm install slexkit @slexkit/runtime @slexkit/components-svelte` |
-| Add shadcn theme | `npm install @slexkit/theme-shadcn` |
-| React/Streamdown host | `npm install slexkit @slexkit/theme-shadcn @slexkit/streamdown streamdown react react-dom` |
-| Obsidian plugin | Install **SlexKit** from Obsidian Community Plugins |
-| AI agent MCP server | `npx -y @slexkit/mcp` |
-
-## v0 packaging strategy
-
-The current approach keeps the root `slexkit` package as the real code carrier. Scoped `@slexkit/*` wrappers exist to define future package boundaries. If physical package splitting happens in the future, it will involve splitting source code, build output, and publishing workflows.
-
-## Release quality gate
-
-All scoped packages are release-checked together:
-
-```sh
-bun run build
-bun run test
-bun run smoke:release
-```
+---
 
-The release smoke packs and installs every scoped package in this repository, verifies public entry points, verifies CSS subpath exports, and starts the MCP stdio binary to check `initialize`, `tools/list`, and `slexkitValidate`.
+## Slex Standard Artifacts
+
+Raw Markdown: /docs/reference/standard.md
+
+---
+title: Slex Standard Artifacts
+category: Reference
+status: ready
+order: 65
+summary: "JSON artifacts for the Slex envelope, component catalog, logic profile, capabilities, conformance fixtures, and manifest."
+slexkitRenderMode: component
+---
+
+# Slex Standard Artifacts
+
+SlexKit provides machine-readable JSON files for agents, host runtimes, MCP servers, and package users. These files describe Slex as a Markdown-embedded UI artifact with local state and logic, not as a pure JSON card catalog.
+
+The JSON files are generated from the TypeScript runtime registry, component specs, runtime version constants, expression capability metadata, and conformance fixtures.
+
+## Files
+
+- [`/standard/slex-standard-manifest.json`](/standard/slex-standard-manifest.json): version, protocol, logic profile, artifact paths, and hashes.
+- [`/standard/slex-expression.schema.json`](/standard/slex-expression.schema.json): JSON Schema for the Slex envelope, `namespace`, `g`, `layout`, component keys, and directive fields.
+- [`/standard/slex-component-catalog.json`](/standard/slex-component-catalog.json): public component props, dynamic flags, generated prop JSON Schema, state modes, children, examples, docs, and per-component hashes.
+- [`/standard/slex-logic-profile.json`](/standard/slex-logic-profile.json): `$` read-pipes, `on*` write-pipes, `$if`, `$for`, `$key`, context variables, reserved names, component state, and secure-mode native capability policy.
+- [`/standard/slex-capabilities.catalog.json`](/standard/slex-capabilities.catalog.json): deterministic `std.*` functions and policy-gated `api.*` secure runtime capabilities.
+- [`/standard/slex-conformance.json`](/standard/slex-conformance.json): valid, warning, and invalid fixtures with stable expected diagnostic codes, paths, and values.
+
+## Validation Model
+
+Validation is parse-first:
+
+1. Parse the JavaScript object literal source.
+2. Validate the Slex envelope and component-key shape.
+3. Compare component names and props against the generated component catalog.
+4. Scan logic strings and source text against the logic profile.
+5. Return stable diagnostic and warning codes.
+
+`validateSlexSource()` keeps its previous structured output and adds `schemaVersion`, `protocolVersion`, and `logicProfileVersion`. Secure-mode diagnostics should guide authors toward policy-gated `api.*` capabilities instead of treating all logic as forbidden.
+
+Warnings are path-aware after parsing. For example, an unknown `std.*` call in `layout.text:value.$text` and a native `fetch()` call in `g.load` produce different stable paths, so tools can point to one expression instead of rewriting the whole artifact.
+
+## Run Conformance
+
+Use the bundled conformance runner to verify that SlexKit's validator still matches the published standard fixtures:
+
+```sh
+slex validate --standard
+slex validate --standard --json
+slex validate --standard --fixture valid-full-envelope
+```
+
+Use file validation for a single Slex source:
+
+```sh
+slex validate ./artifact.slex --mode secure
+slex validate ./artifact.slex --mode trusted --strict
+```
+
+Conformance validates source shape, logic profile diagnostics, capability checks, and warning stability. It is not a visual renderer screenshot test.
+
+## Diagnostic Codes
+
+Clients use `code`, `path`, and `value` for program logic. `message` is for display.
+
+| Code | Severity | Meaning |
+|---|---|---|
+| `syntax` | error | JavaScript object literal parsing failed. Returned as `diagnostic.code`, not a warning. |
+| `unsupported_protocol` | warning | The optional `slex` marker does not match the supported protocol version. |
+| `invalid_component_key` | warning | A component key does not match the `type:identifier` shape. |
+| `invalid_directive_type` | warning | A structural directive such as `$if`, `$for`, or `$key` has an invalid value type. |
+| `unknown_component` | warning | The component type is not present in the generated component catalog. |
+| `unknown_prop` | warning | A component prop is not declared by that component's public spec. |
+| `unknown_std_member` | warning | A logic expression references a `std.*` helper outside the published capability catalog. |
+| `unknown_api_member` | warning | A logic expression references an `api.*` member outside the secure runtime capability catalog. |
+| `native_secure_capability` | warning | Secure mode source uses native browser capability names such as `fetch`, timers, or `WebSocket`; use policy-gated `api.*` instead. |
+| `reserved_context_shadowing` | warning | `g` keys or component identifiers shadow reserved expression context names. |
+
+Paths refer to the parsed source tree, for example `g.load` or `layout.text:value.$text`. If parsing fails, validation can still return source-level usage warnings, but not parsed-tree paths.
+
+## Conformance Fixture Contract
+
+`slex-conformance.json` contains `valid`, `warning`, and `invalid` fixtures. Each fixture has an `id`, `mode`, source text, and an `expected` object.
+
+- `expected.ok` is the validator success state.
+- `expected.warnings` is the warning set for the fixture. The runner fails if an expected warning is missing or if an extra warning appears.
+- Warning matching uses `code`, and when present also `path` and `value`.
+- `expected.diagnostic` is the expected parse diagnostic code for invalid fixtures.
+- Fixture IDs stay stable. If behavior changes, add a new fixture ID.
+
+The conformance suite checks source validation semantics only. It does not assert component screenshots, browser layout, CSS output, or host adapter lifecycle behavior.
+
+## Versioning Policy
+
+SlexKit exposes separate version fields:
+
+- `packageVersion`: npm package version, from `package.json`.
+- `protocolVersion`: accepted Slex source protocol marker, `0.1`.
+- `schemaVersion`: generated artifact schema generation, using date-style values.
+- `logicProfileVersion`: expression, context, stdlib, and secure capability profile version.
+
+Compatible package releases may update catalog hashes, add components or props, add examples, or improve messages without changing `protocolVersion`.
+
+Changes that alter source interpretation, remove or rename diagnostic codes, change expression semantics, or change secure capability behavior require a protocol or logic profile review. Artifact hashes are for cache invalidation, not semantic versioning.
+
+## Difference From A2UI
+
+A2UI describes cross-platform declarative UI. SlexKit describes Markdown-embedded, stateful, executable UI artifacts; the host chooses trusted runtime or secure runtime.
+
+JSON Schema describes the envelope and catalog. The JavaScript expression profile is part of the standard because local logic and state are part of the artifact.
 
 ---