slexkit 0.2.0

package/dist/ai/llms-runtime.txt

@@ -0,0 +1,1475 @@
+# SlexKit Runtime for LLMs
+
+## Slex Specification
+
+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`, `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                   |
+| 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      |
+
+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.
+- No implicit wrapping of display UI as function calls.
+
+---
+
+## Slex Usage Reference
+
+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 |
+| `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.
+
+---
+
+## Runtime Model
+
+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.
+
+### `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 |
+
+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.
+
+---
+
+## Host Integration
+
+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 `@slexkit/obsidian` package registers the `slex` fenced code block processor in Obsidian:
+
+```ts
+// In the Obsidian 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 login 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.
+
+---
+
+## Security Runtime
+
+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.
+
+---
+
+## Package Boundaries
+
+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/obsidian ─── Obsidian plugin
+ @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).
+
+## @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/obsidian
+
+Obsidian plugin adapter. Registers SlexKit fenced code block processors and renders local vault content in reading mode.
+
+```sh
+npm install slexkit @slexkit/obsidian
+```
+
+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. Obsidian 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 | `npm install slexkit @slexkit/obsidian` |
+| 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, verifies public entry points, verifies CSS subpath exports, loads the Obsidian CJS bundle with an Obsidian module mock, and starts the MCP stdio binary to check `initialize`, `tools/list`, and `slexkitValidate`.
+
+---