# 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. 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.

---

## Slex Usage Reference

Raw Markdown: /docs/reference/usage.md

---
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.

---

## 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.

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.

---

## Host Integration

Raw Markdown: /docs/reference/integration.md

---
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.

---

## 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** 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.

---

## Packages

Raw Markdown: /docs/reference/packages.md

---
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.

---

## 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.

---