{ "name": "slexkit-ai-docs", "packageName": "slexkit", "version": "0.4.0", "generatedAt": "2026-07-04T06:03:31.466Z", "docs": { "llms.txt": { "path": "/llms.txt", "title": "llms.txt", "summary": "- [Full documentation](/llms-full.txt): all canonical English docs pages in one text file.", "hash": "c549225b" }, "llms-full.txt": { "path": "/llms-full.txt", "title": "llms-full.txt", "summary": "Version: 0.4.0", "hash": "b577f4b8" }, "llms-components.txt": { "path": "/llms-components.txt", "title": "llms-components.txt", "summary": "Use these components inside Markdown `slex` fences. Raw component docs are ordinary `.md` pages that preserve `slex` examples.", "hash": "7cf4a1b4" }, "llms-runtime.txt": { "path": "/llms-runtime.txt", "title": "llms-runtime.txt", "summary": "Raw Markdown: /docs/reference/spec.md", "hash": "4f8910b4" }, "llms-capabilities.txt": { "path": "/llms-capabilities.txt", "title": "llms-capabilities.txt", "summary": "Use `std.*` for pure deterministic calculations and formatting. Use `api.*` only for host-injected or secure-runtime capabilities that may require policy.", "hash": "89c92bfd" }, "llms-toolhost.txt": { "path": "/llms-toolhost.txt", "title": "llms-toolhost.txt", "summary": "ToolHost is the structured-input path for confirmations, choices, and forms. Do not use it for ordinary display-only UI.", "hash": "29fb8a59" }, "llms-authoring.txt": { "path": "/llms-authoring.txt", "title": "llms-authoring.txt", "summary": "SlexKit's agent-readable source is Markdown with explicit `slex` fences. Do not use `.mdx`; `slex` fences are the interactive layer.", "hash": "fcc8b8b6" } }, "pages": [ { "id": "README", "group": "Guides", "title": "README", "summary": "Root package overview and installation matrix.", "href": "/", "rawHref": "/README.md", "sourcePath": "README.md", "body": "
\n

\n \"SlexKit\"\n

\n

SlexKit

\n

Streaming Live EXpressions Kit

\n

\n \"Docs as tools, tools as docs.\" Render explicit Markdown fences as live, stateful UI blocks.\n

\n

\n Documentation ·\n Components ·\n Specification ·\n AI / Agents ·\n 简体中文\n

\n

\n \"version\"\n \"script\"\n \"TypeScript\"\n \"Svelte\n \"license\"\n

\n

\n \"SlexKit\n

\n
\n\n## Live interface blocks inside Markdown\n\n**SlexKit** turns explicit `slex` Markdown fences into live, stateful UI blocks. A Slex source is just a JavaScript object literal: `g` holds state and logic, `layout` describes the component tree, and the browser runtime renders the result in place.\n\nIt is built for chat messages, documents, agent panels, tool results, and AI-authored dashboards. It is not a full application framework.\n\n## Installation\n\n> Just want to use SlexKit in Obsidian? Open **Settings -> Community plugins**, search for **SlexKit**, then install and enable it. The npm package below is for developers integrating SlexKit into web apps, Markdown renderers, Streamdown, or custom hosts.\n\n```sh\nnpm install slexkit\n```\n\n```ts\nimport { mount } from \"slexkit\";\nimport \"slexkit/style.css\";\n```\n\n## Usage\n\n```html\n
\n\n\n```\n\n## Markdown Native\n\nSlexKit-capable hosts process explicit `slex` fences only. Plain `js`, `json`, and unlabeled code blocks stay inert.\n\n````md\n```slex\n{\n slex: \"0.1\",\n namespace: \"status\",\n g: { done: 3, total: 4 },\n layout: {\n \"badge:state\": { label: \"Ready\", tone: \"success\" },\n \"text:summary\": { \"$text\": \"g.done + '/' + g.total + ' complete'\" }\n }\n}\n```\n\n**Status:** Ready. 3/4 complete.\n````\n\nMarkdown platforms without SlexKit support show the fallback text. Hosts with SlexKit render the interactive UI.\n\n## What You Get\n\n- **Zero-build Slex source**: object literals with no imports, scaffolding, or component bundling in the generated output.\n- **Reactive `g` / `layout` model**: centralized state and logic with declarative component trees.\n- **Expression pipes**: `$` read expressions for dynamic props and `on*` write expressions for events.\n- **Directives**: `$if` and `$for` for conditional rendering and keyed list reconciliation.\n- **Official Svelte components**: 30 components across layout, input, content, display, disclosure, feedback, and tooling.\n- **Extensible registry**: custom component types, Svelte renderers, and component state modes.\n- **Trusted and secure runtimes**: host-realm rendering for trusted content, sandbox iframe rendering for untrusted source.\n- **ToolHost**: confirm, choose, and fill-form templates for structured AI tool-call UX.\n- **AI-friendly docs surface**: `llms.txt`, skills, and the `@slexkit/mcp` read-only MCP server.\n\n## Packages\n\n| Package | Install | Contents |\n| --- | --- | --- |\n| `slexkit` | `npm install slexkit` | Runtime, Svelte components, ToolHost, styles |\n| `@slexkit/runtime` | `npm install slexkit @slexkit/runtime` | Component-free runtime wrapper |\n| `@slexkit/components-svelte` | `npm install slexkit @slexkit/runtime @slexkit/components-svelte` | Svelte component registration |\n| `@slexkit/theme-shadcn` | `npm install @slexkit/theme-shadcn` | CSS theme tokens |\n| `@slexkit/streamdown` | `npm install slexkit @slexkit/theme-shadcn @slexkit/streamdown streamdown react react-dom` | React / Streamdown Markdown renderer |\n| `@slexkit/assistant-ui` | `npm install slexkit @slexkit/theme-shadcn @slexkit/streamdown @slexkit/assistant-ui @assistant-ui/react @assistant-ui/react-streamdown streamdown react react-dom` | assistant-ui message text wrapper for `slex` fences |\n| `@slexkit/tiptap` | `npm install slexkit @slexkit/theme-shadcn @slexkit/tiptap @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extension-code-block @tiptap/markdown` | Tiptap code block NodeView for `slex` fences |\n| `@slexkit/mcp` | `npx -y @slexkit/mcp` | Read-only MCP server for docs, examples, and source validation |\n\nSee [Packages](site/content/reference/packages/en-US.md) for details.\n\n## Integrations\n\n| Host | Path |\n| --- | --- |\n| Browser DOM | `mount()`, `ingest()`, `boot()`, `disposeNamespace()` |\n| Markdown renderers | `createSlexKitMarkdownRuntimeHost()` |\n| assistant-ui | `@slexkit/assistant-ui` |\n| React / Streamdown | `@slexkit/streamdown` |\n| Tiptap | `@slexkit/tiptap` |\n| Obsidian | Install **SlexKit** from Community Plugins; release repo: |\n| AI agents | `@slexkit/mcp`, `llms.txt`, SlexKit skill docs |\n| Custom components | `register()`, `registerSvelteComponent()`, `registerSubset()` |\n\n## Security Runtime\n\nTrusted mode runs inside the host realm and is intended for application-authored or reviewed source. Secure mode isolates untrusted Slex source in a sandbox iframe with an opaque origin, nonce-based CSP, locked-down globals, host-mediated network access, and a heartbeat watchdog.\n\nRead the [Security Runtime](site/content/reference/security/en-US.md) docs before rendering unreviewed user or model output.\n\n## Documentation\n\n| Document | Topic |\n| --- | --- |\n| [Getting Started](site/content/guides/quick-start/en-US.md) | Install and render a first Markdown-friendly Slex source |\n| [Integration](site/content/guides/integration/en-US.md) | Streamdown, Tiptap, Obsidian, and custom host paths |\n| [Runtime model](site/content/reference/runtime/en-US.md) | Mounting, updates, namespace store, lifecycle |\n| [Slex usage reference](site/content/reference/usage/en-US.md) | Source structure, directives, expressions, events, custom components |\n| [Security runtime](site/content/reference/security/en-US.md) | Threat model, sandbox iframe, policy, postMessage bridge |\n| [Slex Specification](site/content/reference/spec/en-US.md) | Protocol v0.1, types, merge rules, lifecycle hooks |\n| [ToolHost](site/content/reference/toolhost/en-US.md) | Tool-call rendering and custom templates |\n| [Icon system](site/content/reference/icons/en-US.md) | Phosphor icons, custom registration, Iconify fallback |\n| [AI / Agents](site/content/guides/ai-agents/en-US.md) | `llms.txt`, MCP server, skills, and authoring rules |\n| [Changelog](CHANGELOG.md) | Release notes and notable changes |\n\n## Version Information\n\n```ts\nimport { SLEXKIT_VERSION, SLEX_PROTOCOL_VERSION, getSlexKitInfo } from \"slexkit\";\n```\n\nThe npm package version, component implementation version, and Slex protocol version are exposed separately. The current public protocol is `v0.1`.\n\n## License\n\nMIT", "hash": "89c07911" }, { "id": "guides/intro", "group": "Guides", "title": "SlexKit Introduction", "summary": "What SlexKit is and where it fits.", "href": "/docs/guides/intro", "rawHref": "/docs/guides/intro.md", "sourcePath": "site/content/guides/intro/en-US.md", "body": "---\ntitle: SlexKit Introduction\ncategory: Guides\nstatus: ready\norder: 10\nsummary: \"Markdown-friendly reactive UI runtime for explicit slex fences.\"\nslexkitRenderMode: component\n---\n\n# SlexKit Introduction\n\nSlexKit renders Markdown fences marked as `slex` into small interactive UI. Use it for local interaction inside chat messages, documents, agent panels, and dashboards without adding a build step for those fragments.\n\nSlexKit is v0/beta. The public surface is usable, but long-term compatibility is not yet guaranteed.\n\n## When To Use It\n\nWhen Markdown needs a small amount of interaction:\n\n- Status cards, counters, calculators, parameter panels, lightweight dashboards\n- AI-generated UI fragments that should degrade to plain Markdown\n- React, Svelte, Obsidian, or vanilla HTML hosts rendering the same fenced source\n\nSlexKit is not a full application framework. It does not provide routing, server-side rendering, a data fetching layer, or a cross-platform pure JSON UI standard.\n\n## Source Format\n\nA Slex source is a JavaScript object literal with state in `g` and the component tree in `layout`:\n\n```slex\n{\n namespace: \"intro_counter\",\n g: {\n count: 0\n },\n layout: {\n \"card:counter\": {\n title: \"Counter\",\n \"text:value\": {\n \"$text\": \"'Count: ' + g.count\"\n },\n \"button:add\": {\n label: \"+1\",\n onclick: \"g.count++\"\n }\n }\n }\n}\n```\n\n- `namespace` identifies the state domain\n- `g` contains reactive state, functions, and small calculations\n- `layout` contains component nodes keyed as `type:name`\n- `$`-prefixed props are read expressions, such as `\"$text\": \"'Count: ' + g.count\"`\n- `on*` props are write expressions, such as `onclick: \"g.count++\"`\n\nThe runtime also accepts a bare component tree as shorthand, but the full envelope is preferred for documentation and shared examples.\n\n## Fence Convention\n\nHosts must process only fences explicitly marked as `slex`:\n\n````md\n```slex\n{\n namespace: \"status\",\n layout: {\n \"badge:state\": { label: \"Ready\", tone: \"success\" }\n }\n}\n```\n\n**Status:** Ready\n````\n\nThe Markdown after the fence is the fallback. Plain Markdown readers show the fallback text; SlexKit-capable hosts replace the fence with interactive UI.\n\nPlain JavaScript, JSON, or untagged code blocks must not be scanned or executed.\n\n## Runtime Modes\n\n**Trusted mode** executes Slex source in the host page. Use it for application-generated content, local documents, and repository-maintained examples.\n\n**Secure mode** executes untrusted or agent-generated source in a sandbox iframe. Sensitive capabilities such as network, timers, animation, and canvas are exposed only through host policy and `api.*`.\n\nUse secure mode when rendering third-party or unreviewed content. See [Secure Runtime Setup](security-runtime).\n\n## Display UI And Tool Calls\n\n**Display UI** renders via `slex` fences or `mount()`. These fragments show information and local interaction but are not function calls.\n\n**ToolHost** is for confirmations, option pickers, and forms that must return structured input to the host. The `submit` component ends a tool template and submits the result.\n\nThis separation prevents ordinary display UI from being mispackaged as tool invocations.\n\n## Core APIs\n\n| API | Use |\n|---|---|\n| `mount(input, container, options?)` | Render trusted Slex source into a container |\n| `ingest(input)` | Merge state-only source without rendering UI |\n| `boot(options?)` | Enhance static page `slex` fences |\n| `createSlexKitMarkdownRuntimeHost(options?)` | Recommended API for Markdown hosts |\n| `mountSecureArtifact(input, container, options)` | Render source in the secure sandbox runtime |\n| `renderToolCall(call, container)` | Render a ToolHost template and collect a result |\n\nType details and beta compatibility notes are in the [Slex Specification](/docs/reference/spec).\n\n## Keep Reading\n\n- [Getting Started](quick-start): developer integration path\n- [Integration](integration): Streamdown and Obsidian host plugins\n- [Design Guidelines](design): authoring public examples and component usage\n- [Secure Runtime Setup](security-runtime): untrusted content boundary\n- [Component Reference](../components/card): built-in component catalog\n- [AI / Agents](ai-agents): SlexKit context for models and agents", "hash": "b6265c0d" }, { "id": "guides/quick-start", "group": "Guides", "title": "Quick Start", "summary": "Install SlexKit and render a first Markdown-friendly Slex source.", "href": "/docs/guides/quick-start", "rawHref": "/docs/guides/quick-start.md", "sourcePath": "site/content/guides/quick-start/en-US.md", "body": "---\ntitle: Getting Started\ncategory: Guides\nstatus: ready\norder: 20\nsummary: \"Install SlexKit, mount a first fragment, and keep readable Markdown fallback.\"\nslexkitRenderMode: component\n---\n\n# Getting Started\n\n> For Obsidian plugin installation, open **Settings -> Community plugins**, search for **SlexKit**, then install and enable it. The npm package path below targets web apps, Markdown hosts, Streamdown, and custom runtimes.\n\nStart by installing `slexkit` and mounting a trusted fragment. Once basic rendering works, move on to Markdown hosts, Streamdown, or the Obsidian plugin.\n\n## Installation Entry\n\nFor most apps, start by installing the root package:\n\n```sh\nnpm install slexkit\n```\n\n```ts\nimport { mount } from \"slexkit\";\nimport \"slexkit/style.css\";\n```\n\nFor host-specific packages, choose by scenario:\n\n| Use case | Install |\n|---|---|\n| Custom components or component-free runtime | `npm install slexkit @slexkit/runtime` |\n| Official Svelte component registration | `npm install slexkit @slexkit/runtime @slexkit/components-svelte` |\n| Standalone shadcn-token theme CSS | `npm install @slexkit/theme-shadcn` |\n| React + Streamdown Markdown host | `npm install slexkit @slexkit/theme-shadcn @slexkit/streamdown streamdown react react-dom` |\n| Obsidian vault rendering | Install **SlexKit** from Obsidian Community Plugins |\n\n`@slexkit/runtime` and `@slexkit/components-svelte` wrap the root package; they are not independent implementations.\n\n## Trusted Fragment\n\nStart with trusted mode for application-authored source, local examples, repository examples, and reviewed snippets.\n\n```ts\nimport { mount } from \"slexkit\";\nimport \"slexkit/style.css\";\n\nconst source = {\n namespace: \"getting_started_counter\",\n g: {\n count: 0\n },\n layout: {\n \"card:demo\": {\n title: \"Counter\",\n \"text:value\": {\n \"$text\": \"'Count: ' + g.count\"\n },\n \"button:add\": {\n label: \"+1\",\n onclick: \"g.count++\"\n }\n }\n }\n};\n\nconst cleanup = mount(source, document.getElementById(\"app\")!);\n```\n\nCall `cleanup()` when removing containers, replacing messages, or unloading pages. If the namespace won't be reused, call `disposeNamespace(namespace)`.\n\n## Markdown Fallback\n\nWhen source appears in Markdown, handle only explicit `slex` fences and keep readable fallback text after the fence:\n\n````md\n```slex\n{\n namespace: \"release_status\",\n layout: {\n \"badge:status\": { label: \"Ready\", tone: \"success\" },\n \"text:summary\": { text: \"3 of 3 checks passed.\" }\n }\n}\n```\n\n**Release status:** Ready. 3 of 3 checks passed.\n````\n\nSlexKit-capable hosts render the fence. Plain Markdown hosts show the fallback. Do not infer executable SlexKit source from `js`, `json`, or unlabeled code blocks.\n\n## Markdown Host\n\nFor chat messages, docs pages, or long Markdown content, use `createSlexKitMarkdownRuntimeHost`. It lets multiple `slex` blocks in one document share state and provides one place for cleanup and trusted/secure mode selection.\n\n```ts\nimport { createSlexKitMarkdownRuntimeHost } from \"slexkit\";\nimport \"slexkit/style.css\";\n\nconst runtime = createSlexKitMarkdownRuntimeHost({\n mode: \"trusted\",\n theme: \"host-shadcn\"\n});\n\nexport function mountSlexFence(source: string, container: HTMLElement) {\n return runtime.mountBlock({\n artifactId: \"message-42\",\n source,\n container\n });\n}\n```\n\nWhen the whole document or message thread is destroyed, call `runtime.disposeArtifact(artifactId)` or `runtime.disposeAll()`.\n\n## Content Source\n\n| Content source | Use |\n|---|---|\n| App-generated source, repository examples, local vault content | trusted |\n| Unreviewed user input, third-party Markdown, direct agent output | secure |\n\nSecure mode requires a sandbox iframe, a publicly served `slexkit.runtime.js`, and a host policy. See [Secure Runtime Setup](security-runtime).\n\n## Keep Reading\n\n- [Integration](integration): React/Streamdown and Obsidian plugins\n- [Secure Runtime Setup](security-runtime): untrusted or agent-generated content\n- [Component Reference](../components/card): built-in component catalog\n- [AI / Agents](ai-agents): SlexKit authoring context for models and agents", "hash": "16b8ecd9" }, { "id": "guides/integration", "group": "Guides", "title": "Integration", "summary": "Streamdown, Tiptap, Obsidian, and custom Markdown hosts for explicit Slex fences.", "href": "/docs/guides/integration", "rawHref": "/docs/guides/integration.md", "sourcePath": "site/content/guides/integration/en-US.md", "body": "---\ntitle: Integration\ncategory: Guides\nstatus: ready\norder: 25\nsummary: \"Connect SlexKit to assistant-ui, Streamdown, Tiptap, Obsidian, or a custom Markdown renderer.\"\nslexkitRenderMode: component\n---\n\n# Integration\n\nChoose the right SlexKit host integration by matching where Markdown is rendered. Every integration renders only fenced code blocks whose language is `slex`; ordinary `js`, `json`, and unlabeled code blocks stay with the host Markdown renderer.\n\nFor the full host API, see the [Host Integration reference](/docs/reference/integration).\n\n## Choose An Integration\n\n| Host | Install or enable | Render target | Default mode |\n|---|---|---|---|\n| assistant-ui | `@slexkit/assistant-ui` | text message parts | secure |\n| React / Streamdown | `@slexkit/streamdown` | chat messages and React Markdown pages | trusted or secure |\n| Tiptap | `@slexkit/tiptap` | `slex` code block previews in an editor | trusted |\n| Obsidian | **SlexKit** from Community Plugins | local notes in reading mode | trusted readonly |\n| Custom Markdown host | `slexkit` | product docs, document viewers, site renderers | trusted or secure |\n\nassistant-ui, Streamdown, and Tiptap have ready-made packages. Custom Markdown renderers can use `createSlexKitMarkdownRuntimeHost` directly. The Obsidian plugin can be installed from Community Plugins; use the [plugin repository](https://github.com/slexkit/obsidian-slexkit) only when testing unreleased builds.\n\nPackage exports and install combinations are listed in [Packages](/docs/reference/packages).\n\n## Runnable Examples\n\nRunnable examples show the integration behavior before app wiring. Streamdown and Tiptap use the same RC low-pass Markdown source, so read-only rendering and editor preview can be compared directly:\n\n- [Streamdown Host Adapter](/examples/streamdown-host) mirrors `examples/streamdown`.\n- [Tiptap Editor Adapter](/examples/tiptap-host) mirrors `examples/tiptap`.\n- [assistant-ui Adapter](/examples/assistant-ui-host) mirrors `examples/assistant-ui`.\n\n## Svelte Markdown Host\n\nThe SlexKit website uses a custom Markdown renderer inside a Svelte app. There is no separate Svelte Markdown adapter package. When an app owns Markdown parsing, hand each `slex` code block to SlexKit like this:\n\n```js\nimport { createSlexKitMarkdownRuntimeHost } from \"slexkit\";\nimport MarkdownRenderer from \"./MarkdownRenderer.svelte\";\n\nconst runtimeHost = createSlexKitMarkdownRuntimeHost({\n mode: \"trusted\",\n theme: \"host-shadcn\"\n});\n\nmount(MarkdownRenderer, {\n target: container,\n props: {\n content: markdown,\n artifactId: \"docs-page\",\n runtimeHost,\n slexkitRenderMode: \"component\"\n }\n});\n```\n\nUse this pattern when the product owns the Markdown parser, Svelte component tree, or document shell. Keep three rules in place: detect only `slex` fences, pass a stable `artifactId` for the document, and call cleanup when the rendered document unmounts.\n\n## Streamdown\n\nInstall the runtime, theme, plugin, and React peer dependencies:\n\n```sh\nnpm install slexkit @slexkit/theme-shadcn @slexkit/streamdown streamdown react react-dom\n```\n\nImport styles once in the app entry:\n\n```ts\nimport \"@slexkit/theme-shadcn/style.css\";\nimport \"@slexkit/streamdown/style.css\";\n```\n\nRegister the renderer with Streamdown:\n\n```tsx\nimport { Streamdown } from \"streamdown\";\nimport { slexkitRenderer } from \"@slexkit/streamdown\";\n\nexport function Message({ markdown }: { markdown: string }) {\n return (\n \n {markdown}\n \n );\n}\n```\n\nThis renderer only replaces `slex` code blocks. Other code blocks stay with Streamdown.\n\n## assistant-ui\n\nWhen an assistant-ui app already renders text through `@assistant-ui/react-streamdown`, use the SlexKit wrapper for message text parts:\n\n```sh\nnpm install slexkit @slexkit/theme-shadcn @slexkit/streamdown @slexkit/assistant-ui @assistant-ui/react @assistant-ui/react-streamdown streamdown react react-dom\n```\n\nImport styles once in the app entry:\n\n```ts\nimport \"@slexkit/theme-shadcn/style.css\";\nimport \"@slexkit/assistant-ui/style.css\";\n```\n\nUse the wrapper where assistant-ui renders text message parts:\n\n```tsx\nimport { MessagePrimitive } from \"@assistant-ui/react\";\nimport { SlexKitAssistantStreamdownText } from \"@slexkit/assistant-ui\";\n\nexport function AssistantMessage() {\n return (\n \n \n {({ part }) =>\n part.type === \"text\" ? (\n \n ) : null\n }\n \n \n );\n}\n```\n\nThe wrapper only replaces the `slex` language block. Threads, composer state, message state, tool calls, approvals, and form submissions stay with the existing assistant-ui or ToolHost layer.\n\n## Tiptap\n\nInstall the SlexKit adapter, theme, and Tiptap dependencies:\n\n```sh\nnpm install slexkit @slexkit/theme-shadcn @slexkit/tiptap @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extension-code-block @tiptap/markdown\n```\n\nImport styles once in the app entry:\n\n```ts\nimport \"@slexkit/theme-shadcn/style.css\";\nimport \"@slexkit/tiptap/style.css\";\n```\n\nDisable StarterKit's default code block, then register the SlexKit extension:\n\n```ts\nimport { Editor } from \"@tiptap/core\";\nimport StarterKit from \"@tiptap/starter-kit\";\nimport { Markdown } from \"@tiptap/markdown\";\nimport { createSlexKitTiptapExtension } from \"@slexkit/tiptap\";\n\nconst editor = new Editor({\n element: document.querySelector(\"#editor\"),\n extensions: [\n StarterKit.configure({ codeBlock: false }),\n Markdown,\n createSlexKitTiptapExtension({ artifactId: \"doc-1\" })\n ],\n content: markdown,\n contentType: \"markdown\"\n});\n```\n\nThe extension only takes over code blocks whose language is exactly `slex`. Other code blocks remain normal editable Tiptap code blocks.\n\nAll `slex` blocks in one editor share state: a state-only block can seed a later layout block. The Tiptap integration uses trusted mode by default; render unreviewed user Markdown or third-party content in a secure web host instead.\n\n## Streamdown Options\n\nUse `createSlexKitRenderer` to set the message/domain, hide source, enable playground behavior, or switch to secure mode:\n\n```tsx\nimport { createSlexKitRenderer } from \"@slexkit/streamdown\";\n\nconst renderer = createSlexKitRenderer({\n domain: \"chat-thread-42\",\n showChrome: false,\n showSource: false,\n runtime: \"trusted\"\n});\n```\n\nInside the same `domain`, an earlier state-only block can provide data for a later layout block:\n\n````md\n```slex\n{\n namespace: \"calc\",\n g: { value: 21 }\n}\n```\n\n```slex\n{\n namespace: \"calc\",\n layout: {\n \"text:answer\": { \"$text\": \"'answer: ' + (g.value * 2)\" }\n }\n}\n```\n````\n\nFor unreviewed user input, third-party Markdown, or direct agent output, switch to secure mode:\n\n```tsx\nconst renderer = createSlexKitRenderer({\n runtime: \"secure\",\n secureFrame: {\n runtimeUrl: \"/slexkit.runtime.js\"\n },\n securePolicy: {\n execution: {\n maxUnresponsiveMs: 30000\n }\n }\n});\n```\n\nUse [Secure Runtime Setup](security-runtime) and the [Security Runtime Contract](/docs/reference/security) when deploying the sandbox iframe, runtime file, and policy fields.\n\n## Obsidian\n\n> For Obsidian plugin installation only, the developer integration material above is unnecessary. Search for **SlexKit** in Obsidian **Community plugins**, then install and enable it.\n\nThe Obsidian plugin renders `slex` code blocks from your local vault in reading mode. It does not write rendered output back to notes.\n\nInstall the plugin from Obsidian Community Plugins:\n\n1. Open **Settings -> Community plugins**.\n2. Disable **Restricted mode** if needed.\n3. Search for **SlexKit**.\n4. Install and enable the plugin.\n\nThe community plugin is marked desktop-only and compatible with Obsidian 1.5.0+.\n\nTo test an unreleased build, use BRAT:\n\n```text\nBRAT repository: https://github.com/slexkit/obsidian-slexkit\n```\n\nManual installs copy the GitHub release assets into the vault:\n\n```text\n.obsidian/plugins/slexkit/\n main.js\n manifest.json\n styles.css\n```\n\nEnable **SlexKit** in Obsidian's community plugin settings.\n\n## Obsidian Example\n\nWrite an explicit `slex` fence in a note:\n\n````md\n```slex\n{\n namespace: \"vault_status\",\n layout: {\n \"card:status\": {\n title: \"Vault status\",\n \"badge:ready\": { label: \"Ready\", tone: \"success\" },\n \"text:note\": { text: \"Rendered by SlexKit in reading mode.\" }\n }\n }\n}\n```\n\nVault status: Ready.\n````\n\n`slex` code blocks in the same note share state, so an earlier state block can affect a later rendered block.\n\n## Obsidian Security Notes\n\nThe official plugin treats local vault content as trusted. It is not a sandbox for third-party Markdown or direct agent output.\n\nFor untrusted content, use secure mode in a web host with a sandbox frame and host policy.\n\n## Before You Ship\n\n- Process only fences whose language is exactly `slex`\n- Keep Markdown fallback for environments without SlexKit\n- Use a stable artifact/domain for each document, message, or note\n- Call cleanup when a container unmounts; dispose the artifact when the document is destroyed\n- Use secure mode for untrusted content instead of trusted mode", "hash": "5ddf362e" }, { "id": "guides/design", "group": "Guides", "title": "Design Guidelines", "summary": "Design and authoring guidelines for SlexKit components and docs.", "href": "/docs/guides/design", "rawHref": "/docs/guides/design.md", "sourcePath": "site/content/guides/design/en-US.md", "body": "---\ntitle: Design Philosophy\ncategory: Guides\nstatus: ready\norder: 30\nsummary: \"Design principles for live Markdown, components, and agent-generated UI.\"\nincludeTitleInToc: true\nslexkitRenderMode: component\n---\n\n# SlexKit Design Philosophy\n\n**Docs as tools, tools as docs.**\n\nStatic documents can embed interactive components, and agent output can carry structured UI.\n\n```slex\n{\n namespace: \"design_philosophy\",\n layout: {\n \"diagram:philosophy\": {},\n \"grid:philosophy\": {\n columns: 1,\n lgColumns: 3,\n \"card:task\": {\n tone: \"primary\",\n \"heading:title\": { level: 4, title: \"Task-First\" },\n \"text:bodyA\": { text: \"Start from the task the user needs to complete.\" },\n \"text:bodyB\": { text: \"Every design decision serves the core task.\" }\n },\n \"card:intuitive\": {\n tone: \"info\",\n \"heading:title\": { level: 4, title: \"Intuitive\" },\n \"text:bodyA\": { text: \"Docs include live examples that update instantly.\" },\n \"text:bodyB\": { text: \"Data flows across components through scoped binding.\" }\n },\n \"card:breath\": {\n tone: \"success\",\n \"heading:title\": { level: 4, title: \"Visual Breath\" },\n \"text:bodyA\": { text: \"Whitespace and spacing create visual rhythm.\" },\n \"text:bodyB\": { text: \"Typography and color build clear hierarchy.\" }\n }\n }\n }\n}\n```\n\n## Color Semantics\n\nColor expresses role, not personal preference.\n\n```slex\n{\n namespace: \"design_color\",\n layout: {\n \"grid:colors\": {\n columns: 1,\n mdColumns: 2,\n lgColumns: 3,\n \"card:primary\": {\n tone: \"primary\",\n \"swatch:primary\": { tone: \"primary\" },\n \"heading:title\": { level: 4, title: \"Primary\" },\n \"text:body\": { text: \"Main actions, current selection, high-priority emphasis. Do not use as decoration.\" }\n },\n \"card:info\": {\n tone: \"info\",\n \"swatch:info\": { tone: \"info\" },\n \"heading:title\": { level: 4, title: \"Info\" },\n \"text:body\": { text: \"Guidance, hints, informational states. Do not replace Primary.\" }\n },\n \"card:success\": {\n tone: \"success\",\n \"swatch:success\": { tone: \"success\" },\n \"heading:title\": { level: 4, title: \"Success\" },\n \"text:body\": { text: \"Completed, passed, safe to continue. Use only when the result is confirmed.\" }\n },\n \"card:warning\": {\n tone: \"warning\",\n \"swatch:warning\": { tone: \"warning\" },\n \"heading:title\": { level: 4, title: \"Warning\" },\n \"text:body\": { text: \"Risk, threshold, needs attention but not failed. Do not use to brighten pages.\" }\n },\n \"card:destructive\": {\n tone: \"destructive\",\n \"swatch:destructive\": { tone: \"destructive\" },\n \"heading:title\": { level: 4, title: \"Destructive\" },\n \"text:body\": { text: \"Errors, deletions, irreversible actions. Must include consequence description.\" }\n },\n \"card:neutral\": {\n tone: \"neutral\",\n \"swatch:neutral\": { tone: \"neutral\" },\n \"heading:title\": { level: 4, title: \"Neutral\" },\n \"text:body\": { text: \"Backgrounds, dividers, secondary information, default containers. Provides structure, not emphasis.\" }\n }\n }\n }\n}\n```\n\n## Card Arrangement\n\nSmall cards are for comparison and judgment. Run metrics side-by-side; the system handles equal width, spacing, and wrapping. Wrap in a parent card when items share context; stack vertically when order matters.\n\n```slex\n{\n namespace: \"design_arrangement\",\n layout: {\n \"column:arrange\": {\n \"row:metrics\": {\n \"stat:requests\": {\n label: \"Requests\",\n value: \"1.2k\",\n unit: \"/min\",\n tone: \"info\"\n },\n \"stat:success\": {\n label: \"Success\",\n value: \"98.4\",\n unit: \"%\",\n tone: \"success\"\n },\n \"stat:latency\": {\n label: \"Latency\",\n value: \"42\",\n unit: \"ms\"\n },\n \"stat:errors\": {\n label: \"Errors\",\n value: \"3\",\n tone: \"warning\"\n },\n \"stat:queued\": {\n label: \"Queued\",\n value: \"8\"\n }\n },\n \"grid:examples\": {\n columns: 1,\n mdColumns: 2,\n \"card:summary\": {\n title: \"Same Object\",\n \"row:service\": {\n \"stat:idle\": {\n label: \"Pending\",\n value: \"12\"\n },\n \"stat:active\": {\n label: \"Running\",\n value: \"5\",\n tone: \"info\"\n },\n \"stat:done\": {\n label: \"Done\",\n value: \"47\",\n tone: \"success\"\n },\n \"stat:failed\": {\n label: \"Failed\",\n value: \"2\",\n tone: \"danger\"\n }\n }\n },\n \"card:flow\": {\n title: \"Sequential\",\n \"column:steps\": {\n \"stat:input\": {\n label: \"Input\",\n value: \"1\"\n },\n \"stat:compute\": {\n label: \"Compute\",\n value: \"2\",\n tone: \"info\"\n },\n \"stat:output\": {\n label: \"Output\",\n value: \"3\",\n tone: \"success\"\n }\n }\n }\n }\n }\n }\n}\n```\n\n## Typography & Icons\n\nSlexKit's typography is calm, clear, and technical. Icons are light, rounded, and restrained — serving as punctuation marks in the interface, not illustrations.\n\n```slex\n{\n namespace: \"design_type_icon\",\n layout: {\n \"grid:type\": {\n columns: 1,\n lgColumns: 2,\n \"card:type\": {\n \"heading:title\": { level: 4, title: \"Type Voice\", meta: \"GEIST / NOTO SANS SC\" },\n \"diagram:font\": { kind: \"font-sample\" },\n \"text:body\": { text: \"English uses Geist, Chinese uses Noto Sans SC. Letterforms stay open and clean, serving readability rather than volume.\" }\n },\n \"card:icon\": {\n \"heading:title\": { level: 4, title: \"Icon Voice\", meta: \"PHOSPHOR ICONS\" },\n \"row:icons\": {\n \"button:sparkle\": { icon: \"sparkle\", iconOnly: true, label: \"Assist\" },\n \"button:book\": { icon: \"book-open-text\", iconOnly: true, label: \"Manual\" },\n \"button:terminal\": { icon: \"terminal-window\", iconOnly: true, label: \"Terminal\" },\n \"button:cursor\": { icon: \"cursor-click\", iconOnly: true, label: \"Click\" },\n \"button:nut\": { icon: \"nut\", iconOnly: true, label: \"Nut\" },\n \"button:gear\": { icon: \"gear-six\", iconOnly: true, label: \"Gear\" }\n },\n \"text:body\": { text: \"Phosphor's character comes from geometric outlines, rounded corners, and consistent stroke width. When choosing icons, first check tone consistency, then semantic accuracy.\" }\n }\n }\n }\n}\n```\n\n## Markdown Authoring\n\nDesign specs and component pages use Markdown for prose, with `slex` fenced blocks for runnable examples, achieving docs-as-examples authoring.\n\n```slex\n{\n namespace: \"design_markdown\",\n layout: {\n \"grid:doc\": {\n columns: 1,\n lgColumns: 3,\n \"card:write\": {\n \"diagram:markdown\": {},\n \"heading:title\": { level: 4, title: \"Prose in Markdown\" },\n \"text:body\": { text: \"Explain context, boundaries, and rules. Do not write explanations inside UI components.\" }\n },\n \"card:run\": {\n \"diagram:fence\": {},\n \"heading:title\": { level: 4, title: \"Examples in slex\" },\n \"text:body\": { text: \"Every key example should render and preview live, not be a screenshot.\" }\n },\n \"card:compare\": {\n \"diagram:cards\": {},\n \"heading:title\": { level: 4, title: \"Rules as Small Cards\" },\n \"text:body\": { text: \"Put comparable principles into cards so readers can judge at a glance.\" }\n }\n }\n }\n}\n```\n\n## Product Shape\n\nSlexKit is for interactive fragments inside Markdown, not full applications. Typical scenarios include:\n\n- A card explaining a result\n- A row of metrics\n- A form-like control area\n- A status or confirmation block\n\nThe framework focuses on embedded document interactions, not routing, global app state, SSR, data fetching frameworks, or general UI standardization.\n\n```slex\n{\n namespace: \"design_shape\",\n layout: {\n \"card:status\": {\n title: \"Build summary\",\n tone: \"info\",\n \"row:metrics\": {\n \"stat:passed\": { label: \"Passed\", value: 28, tone: \"success\" },\n \"stat:failed\": { label: \"Failed\", value: 1, tone: \"danger\" },\n \"stat:queued\": { label: \"Queued\", value: 3, tone: \"muted\" }\n },\n \"text:note\": {\n text: \"Keep the surface focused on one document or message task.\"\n }\n }\n }\n}\n```\n\n## Tone Rules\n\nComponents support semantic tone values for expressing state roles.\n\n```slex\n{\n namespace: \"design_tones\",\n layout: {\n \"grid:tones\": {\n columns: 1,\n mdColumns: 2,\n lgColumns: 3,\n \"card:info\": {\n tone: \"info\",\n \"badge:tone\": { label: \"info\", tone: \"info\" },\n \"text:body\": { text: \"Neutral guidance, current process, or informational state.\" }\n },\n \"card:success\": {\n tone: \"success\",\n \"badge:tone\": { label: \"success\", tone: \"success\" },\n \"text:body\": { text: \"Completed, accepted, or safe-to-continue state.\" }\n },\n \"card:warning\": {\n tone: \"warning\",\n \"badge:tone\": { label: \"warning\", tone: \"warning\" },\n \"text:body\": { text: \"Risk, threshold, or review-needed state.\" }\n },\n \"card:danger\": {\n tone: \"danger\",\n \"badge:tone\": { label: \"danger\", tone: \"danger\" },\n \"text:body\": { text: \"Error, destructive action, or blocked state.\" }\n },\n \"card:muted\": {\n tone: \"muted\",\n \"badge:tone\": { label: \"muted\", tone: \"muted\" },\n \"text:body\": { text: \"Secondary or background information.\" }\n }\n }\n }\n}\n```\n\n## Display UI Versus ToolHost\n\nDisplay UI is for information presentation and local interaction. ToolHost mode is used when the host needs structured results from the user.\n\n```slex\n{\n namespace: \"design_boundary\",\n layout: {\n \"grid:boundary\": {\n columns: 1,\n mdColumns: 2,\n \"card:display\": {\n tone: \"muted\",\n title: \"Display UI\",\n \"text:body\": { text: \"Use slex fences for status, metrics, previews, and local controls.\" },\n \"badge:kind\": { label: \"No host result\", tone: \"muted\" }\n },\n \"card:toolhost\": {\n tone: \"info\",\n title: \"ToolHost\",\n \"text:body\": { text: \"Use tool templates when confirmation or form data must return to the host.\" },\n \"badge:kind\": { label: \"Returns ToolResult\", tone: \"info\" }\n }\n }\n }\n}\n```", "hash": "43eeb379" }, { "id": "guides/security-runtime", "group": "Guides", "title": "Secure Runtime Setup", "summary": "Decision and setup guide for rendering untrusted or agent-generated Slex source.", "href": "/docs/guides/security-runtime", "rawHref": "/docs/guides/security-runtime.md", "sourcePath": "site/content/guides/security-runtime/en-US.md", "body": "---\ntitle: Secure Runtime Setup\ncategory: Guides\nstatus: ready\norder: 40\nsummary: \"Use secure mode for unreviewed user input, third-party Markdown, or agent output.\"\nslexkitRenderMode: component\n---\n\n# Secure Runtime Setup\n\nUse secure mode when the host does not fully control the Slex source: unreviewed user input, third-party Markdown, direct agent output, or shared documents where authorship is unclear.\n\nSecure mode needs both deployment and policy setup. The threat model, `HostRuntimePolicy`, sandbox attributes, bridge messages, and fail-closed behavior are covered in the [Security Runtime Contract](/docs/reference/security).\n\n## When To Use Secure Mode\n\n| Source | Use | Notes |\n|---|---|---|\n| Application-generated source | trusted | The source is created by the app. |\n| Repository examples or reviewed snippets | trusted | Keep examples explicit and versioned. |\n| Local Obsidian vault notes | trusted readonly | The Obsidian plugin does not provide sandbox isolation. |\n| User-submitted Markdown | secure | Treat source as untrusted even when the Markdown looks harmless. |\n| Direct agent output | secure | Do not grant network, timer, animation, or canvas access by default. |\n\nIf the answer is unclear, start with secure mode and enable capabilities only after the host has a concrete product need.\n\n## Minimal Host Setup\n\nFor Markdown hosts, prefer `createSlexKitMarkdownRuntimeHost`. It lets multiple `slex` blocks in one document share state, and it keeps block cleanup and secure-frame mounting in one place.\n\n```ts\nimport { createSlexKitMarkdownRuntimeHost } from \"slexkit\";\nimport \"slexkit/style.css\";\n\nconst runtime = createSlexKitMarkdownRuntimeHost({\n mode: \"secure\",\n theme: \"host-shadcn\",\n secureFrame: {\n runtimeUrl: \"/slexkit.runtime.js\"\n },\n policy: {\n execution: {\n heartbeatIntervalMs: 1000,\n maxUnresponsiveMs: 30000\n }\n }\n});\n\nexport function mountSlexFence(source: string, container: HTMLElement) {\n return runtime.mountBlock({\n artifactId: \"message-42\",\n source,\n container\n });\n}\n```\n\nCall `disposeBlock(container)` when a fence disappears, and call `disposeArtifact(artifactId)` when the full message, document, or note is destroyed.\n\nOmitted capability policies deny access by default. Add `network`, `timer`, `animation`, or `canvas` policy objects only when the host intentionally enables those capabilities.\n\n## Runtime Module\n\nThe secure iframe imports the runtime from `secureFrame.runtimeUrl`. Serve that file as a public ES module:\n\n```http\nAccess-Control-Allow-Origin: *\nContent-Type: text/javascript\n```\n\nThis is server or deployment configuration. It cannot be repaired from frontend JavaScript after the request has already failed.\n\n## Policy Settings\n\n- Keep network disabled unless a specific product feature needs it.\n- If network is enabled, allow only required methods, origins, headers, body sizes, response sizes, and content types.\n- Keep timers, animation, and canvas disabled unless the Slex source needs them.\n- Never treat `capabilities`, `permissions`, `api`, or similar fields inside Slex source as authorization.\n- Do not add `allow-same-origin` to solve CORS or debugging issues.\n- Keep unresponsive runtime failures visible through the built-in fail-closed diagnostic.\n\nPolicy fields and allowed adapter hooks are listed in the [Security Runtime Contract](/docs/reference/security).\n\n## Host Notes\n\n`@slexkit/streamdown` can run trusted or secure. Use secure mode for chat messages and agent output unless the message source is already trusted by the host.\n\nThe official Obsidian plugin treats local vault content as trusted. Do not use it to isolate third-party Markdown or direct agent output.\n\nCustom Markdown hosts should still process only fences whose language is exactly `slex` and should preserve readable Markdown fallback for non-SlexKit environments.\n\n## Production Checklist\n\n- Stable `artifactId` per message, document, or note\n- Explicit `slex` fence detection only\n- Public `slexkit.runtime.js` module with CORS and JavaScript content type\n- Deny-by-default host policy\n- Cleanup on block removal and artifact destruction\n- Visible fallback text after each interactive fence\n- Policy, bridge, CSP, and sandbox details have been checked", "hash": "f34de795" }, { "id": "guides/ai-agents", "group": "Guides", "title": "AI / Agents", "summary": "LLM docs, MCP server, skills, and authoring rules for SlexKit agents.", "href": "/docs/guides/ai-agents", "rawHref": "/docs/guides/ai-agents.md", "sourcePath": "site/content/guides/ai-agents/en-US.md", "body": "---\ntitle: AI / Agents\ncategory: Guides\nstatus: ready\norder: 50\nsummary: \"LLM docs, MCP server, skills, and authoring rules for SlexKit agents.\"\nslexkitRenderMode: component\n---\n\n# AI / Agents\n\n## AI Accessible Documentation\n\nSlexKit exposes AI-facing documentation as a small set of predictable entry points: a clear index, a full-context file, task-oriented skills, and a minimal MCP surface. Raw docs stay as `.md` pages, and interactive examples use explicit `slex` fences.\n\n```slex\n{\n namespace: \"ai_docs_links\",\n layout: {\n \"column:links\": {\n gap: \"sm\",\n \"link:index\": { href: \"/llms.txt\", text: \"/llms.txt - docs index\", icon: \"list-magnifying-glass\" },\n \"link:full\": { href: \"/llms-full.txt\", text: \"/llms-full.txt - full English context\", icon: \"book-open-text\" },\n \"link:components\": { href: \"/llms-components.txt\", text: \"/llms-components.txt - components and API\", icon: \"puzzle-piece\" },\n \"link:runtime\": { href: \"/llms-runtime.txt\", text: \"/llms-runtime.txt - runtime and host integration\", icon: \"cpu\" },\n \"link:capabilities\": { href: \"/llms-capabilities.txt\", text: \"/llms-capabilities.txt - std and api capabilities\", icon: \"function\" },\n \"link:toolhost\": { href: \"/llms-toolhost.txt\", text: \"/llms-toolhost.txt - structured input\", icon: \"cursor-click\" },\n \"link:authoring\": { href: \"/llms-authoring.txt\", text: \"/llms-authoring.txt - slex fence authoring rules\", icon: \"pencil-simple\" },\n \"link:manifest\": { href: \"/slexkit-ai-manifest.json\", text: \"/slexkit-ai-manifest.json - machine-readable index\", icon: \"brackets-curly\" },\n \"link:standard\": { href: \"/standard/slex-standard-manifest.json\", text: \"/standard/slex-standard-manifest.json - standard artifacts\", icon: \"brackets-curly\" },\n \"link:catalog\": { href: \"/standard/slex-component-catalog.json\", text: \"/standard/slex-component-catalog.json - component catalog\", icon: \"puzzle-piece\" },\n \"link:logic\": { href: \"/standard/slex-logic-profile.json\", text: \"/standard/slex-logic-profile.json - logic profile\", icon: \"function\" },\n \"link:conformance\": { href: \"/standard/slex-conformance.json\", text: \"/standard/slex-conformance.json - conformance fixtures\", icon: \"check-circle\" },\n \"text:note\": { text: \"Raw docs use .md routes such as /docs/components/card.md. Do not add .mdx routes.\" }\n }\n }\n}\n```\n\nMinimal reading path:\n\n1. Start with [`/llms.txt`](/llms.txt) for the grouped index.\n2. Use [`/llms-full.txt`](/llms-full.txt) when the agent needs broad context.\n3. Use [`/llms-components.txt`](/llms-components.txt) and raw component `.md` pages when authoring UI.\n4. Use [`/llms-capabilities.txt`](/llms-capabilities.txt) for `std.*` and policy-gated `api.*`.\n5. Use [`/llms-runtime.txt`](/llms-runtime.txt) for host and secure runtime integration.\n6. Use [`/llms-toolhost.txt`](/llms-toolhost.txt) only when user input must return structured data to the host.\n7. Use [`/standard/slex-standard-manifest.json`](/standard/slex-standard-manifest.json), [`/standard/slex-logic-profile.json`](/standard/slex-logic-profile.json), and [`/standard/slex-component-catalog.json`](/standard/slex-component-catalog.json) when an agent needs machine-readable authoring or validation context.\n\nSlexKit raw docs are ordinary `.md` pages with explicit `slex` fences. There is no `.mdx` route — `slex` fences are the interactive layer.\n\n## Context Files\n\nAdd SlexKit context to `AGENTS.md`, `CLAUDE.md`, or `.cursorrules`:\n\n````md\n## SlexKit\n\nThis project uses SlexKit for Markdown-native interactive AI output.\n\nDocumentation: https://slexkit.dev/llms-full.txt\n\nKey patterns:\n- Display UI uses explicit `slex` fenced blocks plus Markdown fallback.\n- Slex source uses `{ slex, namespace, g, layout }`; use `slex: \"0.1\"` for the current public protocol.\n- Use `std.*` for common calculations, formatting, units, and small statistics.\n- Use `/standard/slex-logic-profile.json` and `/standard/slex-component-catalog.json` for machine-readable rules before generating Slex.\n- Run `slex validate --standard` to verify the current package against bundled standard fixtures.\n- ToolHost is only for structured user input flows.\n- Untrusted or agent-generated source should use the secure runtime.\n- Raw docs are `.md` files with `slex` fences, not `.mdx`.\n````\n\n## Skills\n\nThe `skills/` directory provides these task entry points:\n\n- `/slexkit`: overview, architecture, and positioning\n- `/author`: write display-oriented `slex` fences with Markdown fallback\n- `/host`: integrate Markdown, Streamdown, Obsidian, or custom hosts\n- `/toolhost`: build confirmations, choices, and structured forms\n- `/secure`: configure sandbox runtime and host policy\n- `/update`: regenerate AI docs after API, docs, or component changes\n\nUse `/author` for display UI. Use `/toolhost` when the host must receive a submitted result.\n\n## MCP\n\n`@slexkit/mcp` provides read-only access to SlexKit documentation, examples, standard artifacts, conformance reports, and Slex source validation. Keep the public surface small and natural: docs, examples, validate.\n\n```slex\n{\n namespace: \"ai_mcp_tools\",\n layout: {\n \"grid:tools\": {\n columns: 1,\n mdColumns: 3,\n \"card:docs\": {\n title: \"slexkitDocs\",\n icon: \"book-open-text\",\n \"text:body\": { text: \"Search or fetch Markdown docs, standard artifact JSON, or a conformance report.\" }\n },\n \"card:examples\": {\n title: \"slexkitExamples\",\n icon: \"code\",\n \"text:body\": { text: \"Browse component examples, ToolHost templates, and host integration snippets.\" }\n },\n \"card:validate\": {\n title: \"slexkitValidate\",\n icon: \"check-circle\",\n \"text:body\": { text: \"Parse Slex source and return diagnostics plus component usage.\" }\n }\n }\n }\n}\n```\n\n### Quick Install\n\n```sh\nnpx add-mcp @slexkit/mcp\n```\n\nOr specify an app:\n\n```sh\nnpx add-mcp @slexkit/mcp -a claude-code\nnpx add-mcp @slexkit/mcp -a codex\nnpx add-mcp @slexkit/mcp -a cursor\nnpx add-mcp @slexkit/mcp -a vscode\nnpx add-mcp @slexkit/mcp -a zed\n```\n\n### Manual Installation\n\n```slex\n{\n namespace: \"ai_manual_configs\",\n layout: {\n \"tabs:manualConfigs\": {\n value: \"cursor\",\n tabs: [\n {\n value: \"cursor\",\n label: \"Cursor\",\n content: {\n \"code-block:cursor\": {\n title: \".cursor/mcp.json\",\n language: \"json\",\n code: \"{\\n \\\"mcpServers\\\": {\\n \\\"slexkit\\\": {\\n \\\"command\\\": \\\"npx\\\",\\n \\\"args\\\": [\\\"-y\\\", \\\"@slexkit/mcp\\\"]\\n }\\n }\\n}\"\n }\n }\n },\n {\n value: \"codex\",\n label: \"Codex\",\n content: {\n \"code-block:codex\": {\n title: \"config.toml\",\n language: \"toml\",\n code: \"[mcp_servers.slexkit]\\ncommand = \\\"npx\\\"\\nargs = [\\\"-y\\\", \\\"@slexkit/mcp\\\"]\"\n }\n }\n },\n {\n value: \"vscode\",\n label: \"VS Code\",\n content: {\n \"code-block:vscode\": {\n title: \".vscode/mcp.json\",\n language: \"json\",\n code: \"{\\n \\\"servers\\\": {\\n \\\"slexkit\\\": {\\n \\\"command\\\": \\\"npx\\\",\\n \\\"args\\\": [\\\"-y\\\", \\\"@slexkit/mcp\\\"],\\n \\\"type\\\": \\\"stdio\\\"\\n }\\n }\\n}\"\n }\n }\n }\n ]\n }\n }\n}\n```\n\n## Troubleshooting\n\n- MCP server does not start: verify `npx` and MCP config JSON, then restart the IDE.\n- Tool calls fail: restart the MCP server and confirm `tools/list` exposes only `slexkitDocs`, `slexkitExamples`, and `slexkitValidate`.\n- Docs are stale: run `bun run ai:docs` or `bun run build:core`.\n- Wrong raw source route: use `.md` routes with `slex` fences. Do not request `.mdx`.", "hash": "0389431a" }, { "id": "examples/hello-slexkit", "group": "Examples", "title": "第一个 SlexKit 卡片", "summary": "静态 SlexKit 卡片示例，使用 section、grid、stat、table 和 callout 组织内容。", "href": "/zh-CN/examples/hello-slexkit", "rawHref": "/zh-CN/examples/hello-slexkit.md", "sourcePath": "content/examples/hello-slexkit/zh-CN.md", "body": "# 第一个 SlexKit 卡片\n\n该示例不使用 `g` 对象或交互，只用 `layout` 声明一张静态卡片。\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"learn_hello_slexkit\",\n layout: {\n \"section:hello\": {\n eyebrow: \"入门教程 · 1/4\",\n title: \"第一个 SlexKit 卡片\",\n subtitle: \"所有内容都是声明式的——数字、颜色、布局，全部来自 DSL。\",\n \"grid:top-stats\": {\n columns: 1, mdColumns: 3,\n \"stat:users\": { label: \"活跃用户\", value: \"12,847\", unit: \"人\" },\n \"stat:uptime\": { label: \"正常运行\", value: \"99.97\", unit: \"%\" },\n \"stat:latency\": { label: \"服务延迟\", value: \"42\", unit: \"ms\" }\n },\n \"table:pricing\": {\n columns: [\"功能\", \"免费版\", \"专业版\"],\n rows: [\n [\"可用组件\", \"全部\", \"全部\"],\n [\"自定义主题\", \"3 种\", \"无限\"],\n [\"数据导出\", \"JSON\", \"JSON / CSV / SQL\"]\n ]\n },\n \"callout:tip\": {\n tone: \"info\",\n text: \"标题、数值、表格和颜色都来自上面的 DSL 声明，不需要额外 HTML。Markdown 承载正文，DSL 承载交互结构。\"\n }\n }\n }\n}\n```\n\n先观察结构、组件 key 和嵌套方式。下一节会在同样的结构里加入响应式数据。\n\n---\n\n\n如果 `\"12,847\"` 需要动态计算，就需要把数据放进 `g` 对象，并用表达式读取。", "hash": "74ec82bd" }, { "id": "examples/first-interaction", "group": "Examples", "title": "第一个交互：滑块操控数据", "summary": "在 SlexKit 卡片中加入 g 对象、滑块输入和响应式表达式。", "href": "/zh-CN/examples/first-interaction", "rawHref": "/zh-CN/examples/first-interaction.md", "sourcePath": "content/examples/first-interaction/zh-CN.md", "body": "# 第一个交互：滑块操控数据\n\n从静态内容进入交互内容时，需要三样东西：\n\n1. **`g` 对象** — 响应式状态容器\n2. **`$value` / `$label` / `$tone`** — 读表达式（从 g 取值渲染）\n3. **`onchange`** — 写表达式（用户操作写入 g）\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"learn_first_interaction\",\n g: { count: 42 },\n layout: {\n \"section:interact\": {\n eyebrow: \"入门教程 · 2/4\",\n title: \"第一个交互：滑块操控数据\",\n subtitle: \"滑动下面的滑块，stat 和 callout 会随 g.count 更新。\",\n \"column:controls\": {\n \"slider:count\": {\n label: \"选择数值\",\n \"$value\": \"g.count\",\n min: 0,\n max: 100,\n step: 1,\n onchange: \"g.count = Number($event)\"\n },\n \"stat:countStat\": { label: \"当前数值\", \"$value\": \"g.count\" },\n \"badge:level\": {\n \"$label\": \"g.count < 30 ? '低' : g.count < 70 ? '中' : '高'\",\n \"$tone\": \"g.count < 30 ? 'success' : g.count < 70 ? 'warning' : 'danger'\"\n },\n \"callout:note\": {\n \"$tone\": \"g.count < 50 ? 'success' : 'info'\",\n \"$text\": \"g.count < 50 ? '当前值偏低，适合入门级负载。' : '当前值偏高，注意监控资源消耗。'\"\n }\n }\n }\n }\n}\n```\n\n核心公式：\n```\n用户操作 → onchange → g → SlexKit 检测变化 → 所有 $value/$tone/$text 自动重算 → UI 更新\n```\n\n这是一条单向数据流：用户操作写入 `g`，表达式读取 `g` 并触发重渲染。不需要手动 `setState` 或 DOM 操作。", "hash": "557f3235" }, { "id": "examples/multi-input-coordination", "group": "Examples", "title": "多输入协同：两个滑块联动", "summary": "两个 slider 相互影响，引入 g 方法、formula 组件和条件渲染。", "href": "/zh-CN/examples/multi-input-coordination", "rawHref": "/zh-CN/examples/multi-input-coordination.md", "sourcePath": "content/examples/multi-input-coordination/zh-CN.md", "body": "# 多输入协同：两个滑块联动\n\n多个输入变量相互影响时，可以把计算逻辑放进 `g.method()`，再用 `$if` 控制显示。\n1. **`g.method()`** — 依赖其他状态的计算值（类似 Vue computed）\n2. **`$if`** — 条件渲染（根据状态决定显示或隐藏组件）\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"learn_multi_coordination\",\n g: {\n width: 120,\n height: 80,\n area: function () { return this.width * this.height; },\n isLandscape: function () { return this.width > this.height; },\n ratio: function () { return (this.width / this.height).toFixed(2); }\n },\n layout: {\n \"section:coordinated\": {\n eyebrow: \"入门教程 · 3/4\",\n title: \"多输入协同：矩形尺寸联动\",\n subtitle: \"同时调整宽和高，面积和宽高比会自动重新计算。\",\n \"grid:params\": {\n columns: 1, mdColumns: 2,\n \"column:w\": {\n \"input:widthInput\": { label: \"宽度\", \"$value\": \"g.width\", type: \"number\", unit: \"px\", onchange: \"g.width = Number($event || 0)\" },\n \"slider:widthSlider\": { label: \"宽度\", \"$value\": \"g.width\", min: 20, max: 300, step: 5, unit: \"px\", onchange: \"g.width = Number($event)\" }\n },\n \"column:h\": {\n \"input:heightInput\": { label: \"高度\", \"$value\": \"g.height\", type: \"number\", unit: \"px\", onchange: \"g.height = Number($event || 0)\" },\n \"slider:heightSlider\": { label: \"高度\", \"$value\": \"g.height\", min: 20, max: 300, step: 5, unit: \"px\", onchange: \"g.height = Number($event)\" }\n }\n },\n \"grid:results\": {\n columns: 1, mdColumns: 3,\n \"stat:area\": { label: \"面积\", \"$value\": \"g.area()\", unit: \"px²\" },\n \"stat:ratio\": { label: \"宽高比\", \"$value\": \"g.ratio()\" },\n \"badge:orientation\": {\n \"$label\": \"g.isLandscape() ? '横向' : g.width === g.height ? '正方形' : '纵向'\",\n \"$tone\": \"g.isLandscape() ? 'info' : g.width === g.height ? 'success' : 'warning'\"\n }\n },\n \"formula:areaEq\": { \"$tex\": \"'\\\\\\\\text{面积} = ' + g.width + ' \\\\\\\\times ' + g.height + ' = ' + g.area() + '\\\\\\\\text{ px}^2'\" },\n \"callout:tip\": {\n \"$tone\": \"g.isLandscape() ? 'info' : 'warning'\",\n \"$text\": \"g.isLandscape() ? '当前为横向（Landscape）。横向更适用于宽屏展示。' : '当前为纵向（Portrait）。纵向更适用于移动端阅读。'\"\n },\n \"callout:squareTip\": {\n \"$if\": \"g.width === g.height\",\n tone: \"success\",\n text: \"这是一个正方形！宽高完全相等。\"\n }\n }\n }\n}\n```\n\n**三个新知识点：**\n\n| 概念 | 写法 | 含义 |\n|:---|:---|:---|\n| g 方法 | `area: function() { return this.width * this.height; }` | `this` 指向 g 对象本身，返回动态计算值 |\n| 动态公式 | `\"$tex\": \"'...' + g.width + '...'\"` | formula 组件可根据 g 值实时渲染 KaTeX |\n| 条件渲染 | `\"$if\": \"g.width === g.height\"` | 只有表达式返回 true 时该组件才渲染 |", "hash": "8c2e7fc3" }, { "id": "examples/tabs-and-branching", "group": "Examples", "title": "分支与切换：模式选择器", "summary": "用 select 切换 mode 状态，并根据当前模式渲染不同输入和结果。", "href": "/zh-CN/examples/tabs-and-branching", "rawHref": "/zh-CN/examples/tabs-and-branching.md", "sourcePath": "content/examples/tabs-and-branching/zh-CN.md", "body": "# 分支与切换：模式选择器\n\n该示例用 `select` 切换 `mode` 状态，并根据当前模式渲染不同输入和结果。\n\n模式切换遵循 `UI = f(state)`：更新 `mode` 后，视图区域随状态切换。\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"learn_tabs_branching\",\n g: {\n mode: \"length\",\n value: 100,\n convert: function () {\n if (this.mode === \"length\") return (this.value / 100).toFixed(2) + \" m\";\n if (this.mode === \"weight\") return (this.value * 2.20462).toFixed(2) + \" 磅 (lbs)\";\n if (this.mode === \"temp\") return (this.value * 9 / 5 + 32).toFixed(1) + \" °F\";\n return \"—\";\n },\n label: function () {\n if (this.mode === \"length\") return \"厘米转米\";\n if (this.mode === \"weight\") return \"公斤转磅\";\n return \"摄氏度转华氏度\";\n }\n },\n layout: {\n \"section:branching\": {\n eyebrow: \"入门教程 · 4/4\",\n title: \"分支与切换：模式选择器\",\n subtitle: \"切换下面的模式，输入的参数和计算结果会跟着变化。一种模式 = 一种 UI 状态。\",\n \"select:mode\": {\n label: \"转换模式\",\n \"$value\": \"g.mode\",\n options: [\n { label: \"长度 (cm → m)\", value: \"length\" },\n { label: \"重量 (kg → lbs)\", value: \"weight\" },\n { label: \"温度 (°C → °F)\", value: \"temp\" }\n ],\n onchange: \"g.mode = String($event)\"\n },\n \"input:value\": { label: \"输入值\", \"$value\": \"g.value\", type: \"number\", onchange: \"g.value = Number($event || 0)\" },\n \"stat:result\": { \"$label\": \"g.label()\", \"$value\": \"g.convert()\" },\n \"callout:guide\": {\n \"$tone\": \"g.mode === 'temp' ? 'warning' : 'info'\",\n \"$text\": \"g.mode === 'length' ? '1 米 = 100 厘米，除以 100 即可。' : g.mode === 'weight' ? '1 公斤 ≈ 2.20462 磅。' : '°F = °C × 9/5 + 32。华氏度范围更大，注意精度。'\"\n }\n }\n }\n}\n```", "hash": "d16eb743" }, { "id": "examples/salary-calculator", "group": "Examples", "title": "五险一金计算器", "summary": "输入工资基数和城市，计算五险一金明细，显示个人缴纳、单位缴纳和总计。", "href": "/zh-CN/examples/salary-calculator", "rawHref": "/zh-CN/examples/salary-calculator.md", "sourcePath": "content/examples/salary-calculator/zh-CN.md", "body": "# 五险一金计算器\n\n该示例按税前工资和缴纳城市计算五险一金明细，包括个人扣除、单位缴纳和到手工资。\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_salary_calculator\",\n g: {\n base: 20000,\n city: \"beijing\",\n rates: {\n beijing: { pensionP: 8, medicalP: 2, unemploymentP: 0.5, pensionC: 16, medicalC: 8, unemploymentC: 0.5, injury: 0.2, maternity: 0.8, housing: 12 },\n shanghai: { pensionP: 8, medicalP: 2, unemploymentP: 0.5, pensionC: 16, medicalC: 8, unemploymentC: 0.5, injury: 0.2, maternity: 0.8, housing: 7 },\n guangzhou: { pensionP: 8, medicalP: 2, unemploymentP: 0.5, pensionC: 16, medicalC: 8, unemploymentC: 0.5, injury: 0.2, maternity: 0.8, housing: 5 },\n shenzhen: { pensionP: 8, medicalP: 2, unemploymentP: 0.5, pensionC: 16, medicalC: 8, unemploymentC: 0.5, injury: 0.2, maternity: 0.8, housing: 5 }\n },\n currentRate: function () { return this.rates[this.city] || this.rates.beijing; },\n personalRate: function () { var r = this.currentRate(); return r.pensionP + r.medicalP + r.unemploymentP + r.housing; },\n companyRate: function () { var r = this.currentRate(); return r.pensionC + r.medicalC + r.unemploymentC + r.injury + r.maternity + r.housing; },\n personalTotal: function () { return this.base * this.personalRate() / 100; },\n companyTotal: function () { return this.base * this.companyRate() / 100; },\n total: function () { return this.personalTotal() + this.companyTotal(); },\n takeHome: function () { return this.base - this.personalTotal(); },\n cityLabel: function () { return { beijing: \"北京\", shanghai: \"上海\", guangzhou: \"广州\", shenzhen: \"深圳\" }[this.city] || this.city; }\n },\n layout: {\n \"section:salary\": {\n title: \"五险一金计算器\",\n subtitle: \"输入税前工资和城市，实时计算五险一金明细。\",\n \"grid:params\": {\n columns: 1, mdColumns: 2,\n \"column:baseField\": {\n \"input:baseInput\": { label: \"税前工资\", \"$value\": \"g.base\", type: \"number\", unit: \"元/月\", onchange: \"g.base = Number($event || 0)\" },\n \"slider:baseSlider\": { label: \"税前工资\", \"$value\": \"g.base\", min: 3000, max: 50000, step: 500, unit: \"元\", onchange: \"g.base = Number($event)\" }\n },\n \"column:cityField\": {\n \"select:city\": {\n label: \"缴纳城市\",\n \"$value\": \"g.city\",\n options: [\n { label: \"北京\", value: \"beijing\" },\n { label: \"上海\", value: \"shanghai\" },\n { label: \"广州\", value: \"guangzhou\" },\n { label: \"深圳\", value: \"shenzhen\" }\n ],\n onchange: \"g.city = String($event)\"\n }\n }\n },\n \"grid:summary\": {\n columns: 1, mdColumns: 3,\n \"stat:personal\": { label: \"个人扣除\", \"$value\": \"g.personalTotal().toFixed(0)\", unit: \"元\" },\n \"stat:company\": { label: \"公司缴纳\", \"$value\": \"g.companyTotal().toFixed(0)\", unit: \"元\" },\n \"stat:takehome\": { label: \"到手工资\", \"$value\": \"g.takeHome().toFixed(0)\", unit: \"元\" }\n }\n }\n }\n}\n```\n\n切换城市后，公积金比例变化会影响个人扣除和到手工资；示例中北京为 12%，上海为 7%。\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_salary_calculator\",\n layout: {\n \"card:detail\": {\n title: \"各项明细\",\n \"grid:personal\": {\n columns: 1, mdColumns: 4,\n \"stat:pension_p\": { label: \"养老（8%）\", \"$value\": \"(g.base * 0.08).toFixed(0)\", unit: \"元\" },\n \"stat:medical_p\": { label: \"医疗（2%）\", \"$value\": \"(g.base * 0.02).toFixed(0)\", unit: \"元\" },\n \"stat:unemployment_p\": { label: \"失业（0.5%）\", \"$value\": \"(g.base * 0.005).toFixed(0)\", unit: \"元\" },\n \"stat:housing_p\": { label: \"公积金\", \"$value\": \"(g.base * g.currentRate().housing / 100).toFixed(0)\", unit: \"元\" }\n },\n \"grid:company\": {\n columns: 1, mdColumns: 4,\n \"stat:pension_c\": { label: \"养老（16%）\", \"$value\": \"(g.base * 0.16).toFixed(0)\", unit: \"元\" },\n \"stat:medical_c\": { label: \"医疗（8%）\", \"$value\": \"(g.base * 0.08).toFixed(0)\", unit: \"元\" },\n \"stat:unemployment_c\": { label: \"失业（0.5%）\", \"$value\": \"(g.base * 0.005).toFixed(0)\", unit: \"元\" },\n \"stat:other_c\": { label: \"工伤+生育\", \"$value\": \"(g.base * 0.01).toFixed(0)\", unit: \"元\" }\n },\n \"callout:note\": {\n \"$tone\": \"g.personalTotal() > 3000 ? 'warning' : 'info'\",\n \"$text\": \"g.personalTotal() > 3000 ? '个人扣除超过3000元，到手工资可能低于预期。' : '公积金比例越高，到手工资越少，但公积金可以提取使用。'\"\n }\n }\n }\n}\n```\n\n| 城市 | 养老 | 医疗 | 失业 | 公积金 | 个人合计 |\n|------|------|------|------|--------|----------|\n| 北京 | 8% | 2% | 0.5% | 12% | 22.5% |\n| 上海 | 8% | 2% | 0.5% | 7% | 17.5% |\n| 广州 | 8% | 2% | 0.5% | 5% | 15.5% |\n| 深圳 | 8% | 2% | 0.5% | 5% | 15.5% |", "hash": "00b56061" }, { "id": "examples/project-cost-estimator", "group": "Examples", "title": "软件项目成本估算器", "summary": "输入团队规模、开发周期和人员成本，计算项目总成本和人均成本。", "href": "/zh-CN/examples/project-cost-estimator", "rawHref": "/zh-CN/examples/project-cost-estimator.md", "sourcePath": "content/examples/project-cost-estimator/zh-CN.md", "body": "# 软件项目成本估算器\n\n该示例根据团队规模、周期、人力单价和风险缓冲计算项目总成本、月均消耗和人均成本。\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_project_cost\",\n g: {\n frontend: 2, backend: 3, tester: 1, designer: 1,\n months: 6,\n salary: 15000,\n teamSize: function () { return this.frontend + this.backend + this.tester + this.designer; },\n laborCost: function () { return this.teamSize() * this.salary * this.months; },\n equipmentCost: function () { return this.teamSize() * 5000; },\n officeCost: function () { return this.teamSize() * 2000 * this.months; },\n subtotal: function () { return this.laborCost() + this.equipmentCost() + this.officeCost(); },\n riskBuffer: function () { return this.subtotal() * 0.15; },\n totalCost: function () { return this.subtotal() + this.riskBuffer(); },\n perPersonCost: function () { return this.teamSize() > 0 ? this.totalCost() / this.teamSize() : 0; },\n monthlyBurn: function () { return this.months > 0 ? this.totalCost() / this.months : 0; }\n },\n layout: {\n \"section:estimator\": {\n title: \"软件项目成本估算器\",\n subtitle: \"输入团队配置和周期，成本自动算出来。\",\n \"card:estimator\": {\n title: \"项目成本估算\",\n \"grid:team\": {\n columns: 1, mdColumns: 4,\n \"column:fe\": {\n \"input:frontend\": { label: \"前端\", \"$value\": \"g.frontend\", type: \"number\", unit: \"人\", onchange: \"g.frontend = Number($event || 0)\" }\n },\n \"column:be\": {\n \"input:backend\": { label: \"后端\", \"$value\": \"g.backend\", type: \"number\", unit: \"人\", onchange: \"g.backend = Number($event || 0)\" }\n },\n \"column:qa\": {\n \"input:tester\": { label: \"测试\", \"$value\": \"g.tester\", type: \"number\", unit: \"人\", onchange: \"g.tester = Number($event || 0)\" }\n },\n \"column:ui\": {\n \"input:designer\": { label: \"设计\", \"$value\": \"g.designer\", type: \"number\", unit: \"人\", onchange: \"g.designer = Number($event || 0)\" }\n }\n },\n \"grid:params\": {\n columns: 1, mdColumns: 2,\n \"column:period\": {\n \"input:monthsInput\": { label: \"开发周期\", \"$value\": \"g.months\", type: \"number\", unit: \"个月\", onchange: \"g.months = Number($event || 0)\" },\n \"slider:monthsSlider\": { label: \"开发周期\", \"$value\": \"g.months\", min: 1, max: 24, step: 1, unit: \"月\", onchange: \"g.months = Number($event)\" }\n },\n \"column:salaryField\": {\n \"input:salaryInput\": { label: \"人均月薪\", \"$value\": \"g.salary\", type: \"number\", unit: \"元\", onchange: \"g.salary = Number($event || 0)\" },\n \"slider:salarySlider\": { label: \"人均月薪\", \"$value\": \"g.salary\", min: 8000, max: 50000, step: 1000, unit: \"元\", onchange: \"g.salary = Number($event)\" }\n }\n },\n \"grid:results\": {\n columns: 1, mdColumns: 4,\n \"stat:team\": { label: \"团队\", \"$value\": \"g.teamSize()\", unit: \"人\" },\n \"stat:total\": { label: \"总成本\", \"$value\": \"g.totalCost().toFixed(0)\", unit: \"元\" },\n \"stat:perperson\": { label: \"人均成本\", \"$value\": \"g.perPersonCost().toFixed(0)\", unit: \"元\" },\n \"stat:monthly\": { label: \"月均消耗\", \"$value\": \"g.monthlyBurn().toFixed(0)\", unit: \"元\" }\n }\n }\n }\n }\n}\n```\n\n调整人数、周期或角色配置后，月均消耗和总成本会立即更新。\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_project_cost\",\n layout: {\n \"card:breakdown\": {\n title: \"成本构成\",\n \"grid:costs\": {\n columns: 1, mdColumns: 3,\n \"stat:labor\": { label: \"人力成本\", \"$value\": \"g.laborCost().toFixed(0)\", unit: \"元\" },\n \"stat:equipment\": { label: \"设备成本\", \"$value\": \"g.equipmentCost().toFixed(0)\", unit: \"元\" },\n \"stat:office\": { label: \"办公成本\", \"$value\": \"g.officeCost().toFixed(0)\", unit: \"元\" }\n },\n \"grid:extra\": {\n columns: 1, mdColumns: 2,\n \"stat:risk\": { label: \"风险缓冲（15%）\", \"$value\": \"g.riskBuffer().toFixed(0)\", unit: \"元\" },\n \"stat:total\": { label: \"总计\", \"$value\": \"g.totalCost().toFixed(0)\", unit: \"元\" }\n },\n \"callout:tip\": {\n \"$tone\": \"g.months > 12 ? 'warning' : 'info'\",\n \"$text\": \"g.months > 12 ? '项目周期超过1年，建议分阶段交付以降低风险。' : '风险缓冲15%是经验值，复杂项目可调高到20-25%。'\"\n }\n }\n }\n}\n```\n\n\n常见配置参考：\n\n| 团队 | 周期 | 月薪 | 总成本 |\n|------|------|------|--------|\n| 3人 | 3个月 | 15k | 196,650 |\n| 5人 | 6个月 | 15k | 655,500 |\n| 8人 | 9个月 | 20k | 1,989,000 |\n| 10人 | 12个月 | 25k | 4,140,000 |\n\n风险缓冲15%是经验值，复杂项目可以调到20-25%。设备和办公成本按人头估算，不含服务器和第三方服务。", "hash": "75ee0421" }, { "id": "examples/voltage-divider", "group": "Examples", "title": "分压器计算器", "summary": "输入电压和两个电阻值，计算分压输出，并评估负载效应带来的误差。", "href": "/zh-CN/examples/voltage-divider", "rawHref": "/zh-CN/examples/voltage-divider.md", "sourcePath": "content/examples/voltage-divider/zh-CN.md", "body": "# 分压器计算器\n\n两个电阻串联，从中间引出电压——模拟电路中最简单的信号调理手段。做 ADC 电平转换、设定阈值电压、生成偏置电压，处处都在用。\n\n## 核心公式\n\n空载分压：$V_{out} = V_{in} \\times \\frac{R_2}{R_1 + R_2}$\n\n带负载 $R_L$ 时：$V_{out,loaded} = V_{in} \\times \\frac{R_2 \\parallel R_L}{R_1 + R_2 \\parallel R_L}$\n\n**关键经验**：分压器阻抗（$R_1 \\parallel R_2$）应至少 < 后级输入阻抗的 1/10。\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_voltage_divider\",\n g: {\n vin: 5, r1: 10000, r2: 10000, rl: 100000,\n rParallel: function () { return this.r2 * this.rl / (this.r2 + this.rl); },\n vout: function () { return this.vin * this.r2 / (this.r1 + this.r2); },\n voutLoaded: function () { return this.vin * this.rParallel() / (this.r1 + this.rParallel()); },\n errorPercent: function () { return Math.abs((this.voutLoaded() - this.vout()) / this.vout() * 100); },\n impedanceRatio: function () { var zout = this.r1 * this.r2 / (this.r1 + this.r2); return this.rl / zout; },\n loadWarning: function () { return this.impedanceRatio() < 10 ? \"负载效应显著，增大 RL 或减小 R1/R2\" : \"分压器阻抗足够低\"; }\n },\n layout: {\n \"section:divider\": {\n title: \"分压器计算器\",\n subtitle: \"两个电阻串联，从中间引出电压。\",\n \"card:divider\": {\n title: \"分压器计算器\",\n \"grid:params\": {\n columns: 1, mdColumns: 2,\n \"column:r1Field\": { \"input:r1Input\": { label: \"R1\", \"$value\": \"std.units.si(g.r1, 'Ω', 1)\", type: \"engineering\", unit: \"Ω\", placeholder: \"10kΩ\", onchange: \"if ($event.valid && $event.number > 0) g.r1 = $event.number\" }, \"slider:r1Slider\": { label: \"R1\", \"$value\": \"g.r1\", min: 100, max: 1000000, step: 100, unit: \"Ω\", onchange: \"g.r1 = Number($event)\" } },\n \"column:r2Field\": { \"input:r2Input\": { label: \"R2\", \"$value\": \"std.units.si(g.r2, 'Ω', 1)\", type: \"engineering\", unit: \"Ω\", placeholder: \"10kΩ\", onchange: \"if ($event.valid && $event.number > 0) g.r2 = $event.number\" }, \"slider:r2Slider\": { label: \"R2\", \"$value\": \"g.r2\", min: 100, max: 1000000, step: 100, unit: \"Ω\", onchange: \"g.r2 = Number($event)\" } }\n },\n \"grid:params2\": {\n columns: 1, mdColumns: 2,\n \"column:vinField\": { \"input:vinInput\": { label: \"输入电压 Vin\", \"$value\": \"std.units.si(g.vin, 'V', 1)\", type: \"engineering\", unit: \"V\", placeholder: \"5V\", onchange: \"if ($event.valid && $event.number > 0) g.vin = $event.number\" }, \"slider:vinSlider\": { label: \"Vin\", \"$value\": \"g.vin\", min: 0.1, max: 48, step: 0.1, unit: \"V\", onchange: \"g.vin = Number($event)\" } },\n \"column:rlField\": { \"input:rlInput\": { label: \"负载电阻 RL\", \"$value\": \"std.units.si(g.rl, 'Ω', 1)\", type: \"engineering\", unit: \"Ω\", placeholder: \"100kΩ\", onchange: \"if ($event.valid && $event.number > 0) g.rl = $event.number\" }, \"slider:rlSlider\": { label: \"RL\", \"$value\": \"g.rl\", min: 1000, max: 10000000, step: 1000, unit: \"Ω\", onchange: \"g.rl = Number($event)\" } }\n },\n \"formula:eq1\": { \"$tex\": \"'V_{out} = ' + g.vin.toFixed(1) + ' \\\\\\\\times \\\\\\\\frac{' + (g.r2/1000).toFixed(1) + '\\\\\\\\text{k}}{' + (g.r1/1000).toFixed(1) + '\\\\\\\\text{k} + ' + (g.r2/1000).toFixed(1) + '\\\\\\\\text{k}} = ' + g.vout().toFixed(3) + '\\\\\\\\text{ V}'\" },\n \"grid:results\": {\n columns: 1, mdColumns: 4,\n \"stat:vout\": { label: \"空载 Vout\", \"$value\": \"g.vout().toFixed(3)\", unit: \"V\" },\n \"stat:voutLoaded\": { label: \"带载 Vout\", \"$value\": \"g.voutLoaded().toFixed(3)\", unit: \"V\" },\n \"stat:error\": { label: \"负载误差\", \"$value\": \"g.errorPercent().toFixed(2)\", unit: \"%\" },\n \"badge:ratio\": { \"$label\": \"g.impedanceRatio() < 10 ? '⚠ 负载效应' : '✓ 匹配良好'\", \"$tone\": \"g.impedanceRatio() < 10 ? 'warning' : 'success'\" }\n },\n \"callout:warning\": { \"$tone\": \"g.impedanceRatio() < 10 ? 'warning' : 'info'\", \"$text\": \"g.loadWarning()\" }\n }\n }\n }\n}\n```\n\n\n## 工程笔记\n\n| R1 | R2 | Vout/Vin | 阻抗 |\n|----|----|---------|------|\n| 10k | 10k | 0.50 | 5k |\n| 10k | 3.3k | 0.25 | 2.5k |\n| 10k | 1k | 0.09 | 909 |\n| 33k | 10k | 0.23 | 7.7k |\n\n- **ADC 应用**：分压器阻抗应 < ADC 输入阻抗的 1/10，必要时加缓冲运放\n- **高精度场景**：用 1% 精度电阻，R1 和 R2 用同一批次减少温漂差异\n- **功率限制**：$P = V^2/R$，小阻值分压器注意发热", "hash": "df047545" }, { "id": "examples/rc-low-pass-filter", "group": "Examples", "title": "RC 低通滤波器", "summary": "用电阻和电容搭建的频率选择电路，计算截止频率和任意频率下的增益衰减。", "href": "/zh-CN/examples/rc-low-pass-filter", "rawHref": "/zh-CN/examples/rc-low-pass-filter.md", "sourcePath": "content/examples/rc-low-pass-filter/zh-CN.md", "body": "# RC 低通滤波器\n\nRC 低通滤波器是模拟电路中最基础的无源滤波器——一个电阻加一个电容，就能把高频噪声从信号路径上滤掉。做 ADC 前端抗混叠、音频去嘶声、PWM 平滑输出，都会用到它。\n\n## 核心公式\n\n截止频率 $f_c$（-3dB 点）：\n\n$$f_c = \\frac{1}{2\\pi RC}$$\n\n对于任意频率 $f$ 的输入信号，输出幅度增益为：\n\n$$|H(f)| = \\frac{1}{\\sqrt{1 + (f/f_c)^2}}$$\n\n## 参数区\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_rc_low_pass_filter\",\n g: {\n r: 10000,\n c: 100,\n f: 1000,\n cLabel: function () { return String(Math.round(this.c * 1000) / 1000); },\n cutoff: function () { return 1 / (2 * Math.PI * this.r * this.c * 1e-9); },\n gain: function () { return 1 / Math.sqrt(1 + Math.pow(this.f / this.cutoff(), 2)); },\n gainDb: function () { return (20 * Math.log10(this.gain())).toFixed(1); },\n regimeLabel: function () { return this.f < this.cutoff() * 0.1 ? \"通带\" : this.f > this.cutoff() * 10 ? \"阻带\" : \"过渡带\"; }\n },\n layout: {\n \"section:params\": {\n title: \"RC 低通滤波器\",\n subtitle: \"一个电阻加一个电容，把高频噪声滤掉。\",\n \"card:params\": {\n title: \"参数输入\",\n \"grid:inputs\": {\n columns: 1, mdColumns: 3,\n \"column:rField\": { \"input:rInput\": { label: \"电阻 R\", \"$value\": \"std.units.si(g.r, 'Ω', 1)\", type: \"engineering\", unit: \"Ω\", placeholder: \"10kΩ\", onchange: \"if ($event.valid && $event.number > 0) g.r = $event.number\" }, \"slider:rSlider\": { label: \"R\", \"$value\": \"g.r\", min: 100, max: 100000, step: 100, unit: \"Ω\", onchange: \"g.r = Number($event)\" } },\n \"column:cField\": { \"input:cInput\": { label: \"电容 C\", \"$value\": \"g.cLabel() + 'nF'\", type: \"engineering\", unit: \"nF\", placeholder: \"100nF\", onchange: \"if ($event.valid && $event.number > 0) g.c = $event.unit ? $event.number * 1e9 : $event.number\" }, \"slider:cSlider\": { label: \"C\", \"$value\": \"g.c\", min: 1, max: 1000, step: 1, unit: \"nF\", onchange: \"g.c = Number($event)\" } },\n \"column:fField\": { \"input:fInput\": { label: \"输入频率 f\", \"$value\": \"std.units.si(g.f, 'Hz', 1)\", type: \"engineering\", unit: \"Hz\", placeholder: \"1kHz\", onchange: \"if ($event.valid && $event.number >= 0) g.f = $event.number\" }, \"slider:fSlider\": { label: \"f\", \"$value\": \"g.f\", min: 1, max: 100000, step: 1, unit: \"Hz\", onchange: \"g.f = Number($event)\" } }\n },\n \"stat:fc\": { label: \"截止频率\", \"$value\": \"g.cutoff().toFixed(1)\", unit: \"Hz\" },\n \"badge:regime\": { \"$label\": \"g.regimeLabel()\", \"$tone\": \"g.f < g.cutoff() * 0.1 ? 'success' : g.f > g.cutoff() * 10 ? 'danger' : 'warning'\" }\n }\n }\n }\n}\n```\n\n\n## 计算结果\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_rc_low_pass_filter\",\n layout: {\n \"column:results\": {\n \"formula:fc_eq\": { \"$tex\": \"'f_c = \\\\\\\\frac{1}{2\\\\\\\\pi \\\\\\\\times ' + (g.r/1000).toFixed(1) + 'k\\\\\\\\Omega \\\\\\\\times ' + g.cLabel() + '\\\\\\\\text{nF}} = ' + g.cutoff().toFixed(1) + '\\\\\\\\text{ Hz}'\" },\n \"row:metrics\": {\n \"stat:gain_val\": { label: \"幅值增益 |H(f)|\", \"$value\": \"g.gain().toFixed(4)\" },\n \"stat:gain_db\": { label: \"增益\", \"$value\": \"g.gainDb()\", unit: \"dB\", \"$tone\": \"g.f < g.cutoff() * 0.1 ? 'success' : g.f > g.cutoff() * 10 ? 'danger' : 'warning'\" }\n },\n \"callout:verdict\": { \"$tone\": \"g.f < g.cutoff() * 0.1 ? 'success' : g.f > g.cutoff() * 10 ? 'danger' : 'warning'\", \"$text\": \"g.f < g.cutoff() * 0.1 ? '信号完整通过，衰减 < 0.04 dB。' : g.f > g.cutoff() * 10 ? '信号被强烈衰减超过 20 dB，滤波器有效工作。' : '信号处于过渡带，衰减约 ' + (-20 * Math.log10(1 / Math.sqrt(1 + Math.pow(g.f / g.cutoff(), 2)))).toFixed(1) + ' dB。'\" }\n }\n }\n}\n```\n\n\n## 选型参考\n\n下表是常见场景下的经验参数组合。把截止频率设为目标信号最高频率的 5-10 倍，可以保证通带平坦。\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_rc_low_pass_filter\",\n layout: {\n \"card:selection\": {\n title: \"选型建议\",\n \"table:guide\": {\n columns: [\"R\", \"C\", \"fc\", \"典型用途\"],\n rows: [\n [\"1 kΩ\", \"100 nF\", \"1592 Hz\", \"音频低通\"],\n [\"10 kΩ\", \"100 nF\", \"159 Hz\", \"ADC 抗混叠\"],\n [\"100 kΩ\", \"10 nF\", \"159 Hz\", \"PWM 平滑\"],\n [\"1 kΩ\", \"1 µF\", \"159 Hz\", \"电源纹波滤波\"],\n [\"10 kΩ\", \"1 nF\", \"15915 Hz\", \"高频噪声抑制\"]\n ]\n },\n \"callout:tip\": { \"$tone\": \"g.cutoff() < 100 ? 'info' : g.cutoff() > 10000 ? 'warning' : 'success'\", \"$text\": \"g.cutoff() < 100 ? '低截止频率适合电源滤波和慢信号。' : g.cutoff() > 10000 ? '高截止频率可能无法有效滤除高频噪声。' : '当前截止频率适合大多数应用场景。'\" }\n }\n }\n}\n```\n\n\n## 工程笔记\n\n- **R 取值**：太大会增加输出阻抗和后级负载效应；太大会增大热噪声。1kΩ–100kΩ 是常用范围\n- **C 取值**：nF 级 NP0/C0G 陶瓷电容温漂小、精度高；超过 100nF 考虑薄膜电容\n- **负载效应**：后级输入阻抗应至少 > 10 × R，否则 $f_c$ 会偏移\n- **级联**：两级 RC 串联可得到 -40dB/dec 的二阶滚降，但截止频率会降低到约 $0.37f_c$\n\n| $f/f_c$ | 增益 | 衰减 |\n|:---:|:---:|:---:|\n| 0.1 | 0.995 | -0.04 dB |\n| 1.0 | 0.707 | -3 dB |\n| 5.0 | 0.196 | -14.2 dB |\n| 10.0 | 0.100 | -20 dB |", "hash": "faf25452" }, { "id": "examples/baud-rate-calculator", "group": "Examples", "title": "波特率误差计算器", "summary": "输入晶振频率和目标波特率，计算 UART 波特率误差百分比，判断通信可靠性。", "href": "/zh-CN/examples/baud-rate-calculator", "rawHref": "/zh-CN/examples/baud-rate-calculator.md", "sourcePath": "content/examples/baud-rate-calculator/zh-CN.md", "body": "# 波特率误差计算器\n\n嵌入式开发中，UART 波特率由系统时钟分频得到。晶振频率不能整除目标波特率时会产生误差，误差超过 ±2% 通信就可能丢帧。\n\n## 核心公式\n\n$$Error = \\frac{|BR_{actual} - BR_{target}|}{BR_{target}} \\times 100\\%$$\n\n实际波特率 $BR_{actual} = f_{osc} / (16 \\times N)$，其中 $N = \\text{round}(f_{osc} / (16 \\times BR_{target}))$ 为分频寄存器整数。\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_baud_rate_calculator\",\n g: {\n freq: 8,\n freqUnit: \"MHz\",\n baud: 115200,\n freqHz: function () { var m = { MHz: 1e6, kHz: 1e3, Hz: 1 }; return this.freq * (m[this.freqUnit] || 1e6); },\n divisor: function () { return this.freqHz() / (16 * this.baud); },\n regValue: function () { return Math.round(this.divisor()); },\n actualBaud: function () { return this.freqHz() / (16 * this.regValue()); },\n error: function () { return Math.abs((this.actualBaud() - this.baud) / this.baud * 100); },\n reliability: function () { var e = this.error(); return e < 0.5 ? \"优秀\" : e < 2 ? \"可接受\" : e < 5 ? \"有风险\" : \"不可用\"; },\n tone: function () { var e = this.error(); return e < 0.5 ? \"success\" : e < 2 ? \"info\" : e < 5 ? \"warning\" : \"danger\"; }\n },\n layout: {\n \"section:baudCalculator\": {\n title: \"波特率误差计算器\",\n subtitle: \"输入晶振频率和目标波特率，计算误差。\",\n \"card:baud\": {\n title: \"波特率误差计算器\",\n \"grid:params\": {\n columns: 1, mdColumns: 2,\n \"column:freqField\": {\n \"input:freq\": { label: \"晶振频率\", \"$value\": \"g.freq\", type: \"number\", unit: \"MHz\", onchange: \"g.freq = Number($event || 0)\" }\n },\n \"column:baudField\": {\n \"select:baud\": { label: \"目标波特率\", \"$value\": \"g.baud\", options: [{ label: \"9600\", value: 9600 }, { label: \"19200\", value: 19200 }, { label: \"38400\", value: 38400 }, { label: \"57600\", value: 57600 }, { label: \"115200\", value: 115200 }, { label: \"230400\", value: 230400 }, { label: \"460800\", value: 460800 }], onchange: \"g.baud = Number($event)\" }\n },\n \"column:unitField\": {\n \"select:unit\": { label: \"频率单位\", \"$value\": \"g.freqUnit\", options: [{ label: \"MHz\", value: \"MHz\" }, { label: \"kHz\", value: \"kHz\" }, { label: \"Hz\", value: \"Hz\" }], onchange: \"g.freqUnit = String($event)\" }\n },\n \"column:divField\": {\n \"stat:divisor\": { label: \"分频比\", \"$value\": \"g.divisor().toFixed(3)\" }\n }\n },\n \"formula:equation\": { \"$tex\": \"'\\\\\\\\text{Error} = \\\\\\\\frac{|' + g.actualBaud().toFixed(0) + ' - ' + g.baud + '|}{' + g.baud + '} \\\\\\\\times 100\\\\\\\\% = ' + g.error().toFixed(2) + '\\\\\\\\%'\" },\n \"grid:results\": {\n columns: 1, mdColumns: 4,\n \"stat:actualBaud\": { label: \"实际波特率\", \"$value\": \"g.actualBaud().toFixed(0)\", unit: \"bps\" },\n \"stat:error\": { label: \"误差\", \"$value\": \"g.error().toFixed(2)\", unit: \"%\" },\n \"stat:reliability\": { label: \"可靠性\", \"$value\": \"g.reliability()\", \"$tone\": \"g.tone()\" },\n \"stat:regValue\": { label: \"寄存器值\", \"$value\": \"g.regValue()\" }\n },\n \"callout:advice\": { \"$tone\": \"g.tone()\", \"$text\": \"g.error() < 0.5 ? '误差极小，通信可靠。' : g.error() < 2 ? '误差在可接受范围内（<2%），绝大多数场景可用。' : g.error() < 5 ? '误差偏大，长帧通信可能失败，建议更换晶振或降低波特率。' : '误差过大，通信不可靠。请选择能整除的晶振频率。'\" }\n }\n }\n }\n}\n```\n\n\n## 常用晶振频率与波特率误差表\n\n| 晶振 | 9600 | 19200 | 38400 | 57600 | 115200 |\n|------|------|-------|-------|-------|--------|\n| 1.8432 MHz | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 |\n| 3.6864 MHz | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 |\n| 4.0000 MHz | 8.51 | 8.51 | 8.51 | 8.51 | 8.51 |\n| 7.3728 MHz | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 |\n| 8.0000 MHz | 8.51 | 8.51 | 8.51 | 8.51 | 8.51 |\n| 11.0592 MHz | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 |\n| 14.7456 MHz | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 |\n| 16.0000 MHz | 8.51 | 8.51 | 8.51 | 8.51 | 8.51 |\n\n**工程笔记**：\n\n- 零误差的关键：晶振频率能被 $16 \\times BR$ 整除\n- **11.0592 MHz** 是 UART 最经典的选择，对所有标准波特率零误差\n- **7.3728 MHz** 和 **14.7456 MHz** 同样零误差\n- 错误 < 2% 在实际工程中通常可工作，但高速长帧场景建议 < 1%", "hash": "7ac3d2d9" }, { "id": "examples/search-filter-table", "group": "Examples", "title": "搜索与过滤表格", "summary": "搜索输入框实时过滤表格行，并用 collapsible 展开行详情。", "href": "/zh-CN/examples/search-filter-table", "rawHref": "/zh-CN/examples/search-filter-table.md", "sourcePath": "content/examples/search-filter-table/zh-CN.md", "body": "# 搜索与过滤表格\n\n该示例用 `input` 绑定搜索关键词，用动态 `table` 生成过滤后的行，并用 `collapsible` 展开行详情。\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_search_filter\",\n g: {\n query: \"\", selected: \"\", selectedItem: null,\n allItems: [\n { id: \"btn-1\", name: \"Button 按钮\", category: \"Action\", status: \"ready\", notes: \"支持 variant 和 size。\" },\n { id: \"card-1\", name: \"Card 卡片\", category: \"Layout\", status: \"ready\", notes: \"最常用的分组容器。\" },\n { id: \"input-1\", name: \"Input 输入框\", category: \"Input\", status: \"ready\", notes: \"支持 type、unit 和 placeholder。\" },\n { id: \"tabs-1\", name: \"Tabs 选项卡\", category: \"Navigation\", status: \"ready\", notes: \"支持水平和垂直方向。\" },\n { id: \"table-1\", name: \"Table 表格\", category: \"Display\", status: \"ready\", notes: \"columns 数组 + rows 数组。\" },\n { id: \"formula-1\", name: \"Formula 公式\", category: \"Display\", status: \"ready\", notes: \"依赖 KaTeX 渲染 LaTeX。\" },\n { id: \"toast-1\", name: \"Toast 通知\", category: \"Feedback\", status: \"preview\", notes: \"支持 type 变体。\" },\n { id: \"secure-1\", name: \"Secure 安全运行时\", category: \"Tooling\", status: \"beta\", notes: \"基于 iframe 沙箱。\" }\n ],\n filtered: function () {\n var q = this.query.toLowerCase();\n if (!q) return this.allItems;\n return this.allItems.filter(function (item) { return item.name.toLowerCase().includes(q) || item.category.toLowerCase().includes(q); });\n },\n matched: function () { return this.filtered().length; },\n select: function (id) { this.selected = this.selected === id ? \"\" : id; }\n },\n layout: {\n \"section:search\": {\n eyebrow: \"组件查询\",\n title: \"搜索与过滤表格\",\n subtitle: \"输入关键词实时过滤组件列表，点击任意行查看详情。\",\n \"input:query\": { label: \"搜索组件\", \"$value\": \"g.query\", type: \"text\", placeholder: \"输入名称或分类关键词...\", onchange: \"g.query = String($event || '')\" },\n \"stat:matched\": { \"$label\": \"'匹配结果'\", \"$value\": \"g.matched()\", \"$unit\": \"'/' + g.allItems.length + ' 项'\" },\n \"table:list\": {\n columns: [\"名称\", \"分类\", \"状态\", \"\"],\n \"$rows\": \"g.filtered().map(function(item) { return [item.name, item.category, item.status, item.id]; })\"\n },\n \"callout:empty\": {\n \"$if\": \"g.matched() === 0\",\n tone: \"warning\",\n \"$text\": \"'未找到匹配「' + g.query + '」的组件。'\"\n }\n }\n }\n}\n```\n\n**核心技巧：**\n\n- `input` 的 `onchange` 更新 `g.query` → 触发 `g.filtered()` 重新计算\n- `g.filtered()` 用 `filter` 过滤 `allItems` 数组\n- `\"$rows\"` 动态计算行的二维数组——每个 item 映射为一行\n- `g.matched()` 返回过滤后数量，用于 stat 和 callout 的条件显示\n- `$if` 在无匹配时显示空结果提示\n\n这是 `input` 驱动动态表格的基本模式。相比硬编码 rows，动态 rows 可以随输入实时变化。\n\n---\n\n## 进阶玩法：展开行详情\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_search_filter\",\n layout: {\n \"section:detail\": {\n eyebrow: \"组件详情\",\n title: \"选中查看详情\",\n \"accordion:faq\": {\n multiple: true,\n items: [\n { value: \"btn-1\", label: \"Button 按钮\", icon: \"cursor-click\", content: \"触发操作的基础组件。支持 variant (solid/outline/ghost) 和 size (sm/md/lg) 等变体。\" },\n { value: \"card-1\", label: \"Card 卡片\", icon: \"rectangle\", content: \"内容分组容器。最常用的布局组件之一，比 section 更轻量。\" },\n { value: \"input-1\", label: \"Input 输入框\", icon: \"textbox\", content: \"单行或数字输入。支持 type、unit、placeholder 等属性。\" }\n ]\n }\n }\n }\n}\n```\n\n## 为什么动态 rows 值得学？\n\n静态表格的 `rows` 是硬编码二维数组。数据量增加或需要条件筛选时，可以用 `\"$rows\"` 在 `g` 方法中动态生成行数据：\n\n- **文档内数据浏览**：目录、API 列表、配置项\n- **AI 输出展示**：大模型生成的表格结果需要可筛选\n- **知识库查询**：搜索内部组件/API/术语\n\n---", "hash": "f95b5103" }, { "id": "examples/project-dashboard", "group": "Examples", "title": "项目仪表盘", "summary": "用 section + grid 搭建信息仪表盘，覆盖 Sprint 进度、质量指标和团队健康度的多卡片联动。", "href": "/zh-CN/examples/project-dashboard", "rawHref": "/zh-CN/examples/project-dashboard.md", "sourcePath": "content/examples/project-dashboard/zh-CN.md", "body": "# 项目仪表盘\n\n该示例用 `section` 做区块分组，`grid` 做多列布局，并用多张 card 展示 Sprint 进度、质量指标和团队健康度。\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_dashboard\",\n g: {\n sprint: 8, team: 6, sprintProgress: 72, bugs: 12, resolved: 9,\n scope: \"on-track\",\n bugRate: function () { return this.resolved / this.bugs * 100; },\n teamLoad: function () { return Math.min(100, this.sprint / this.team * 20); },\n scopeStatus: function () { return this.scope === \"on-track\" ? \"正常\" : this.scope === \"at-risk\" ? \"有风险\" : \"已偏离\"; }\n },\n layout: {\n \"section:dashboard\": {\n eyebrow: \"Sprint 概览\",\n title: \"项目仪表盘 · Sprint 24\",\n subtitle: \"数据截止今日 10:00 AM。拖滑动条查看不同假想数据的效果。\",\n \"grid:row1\": {\n columns: 1, mdColumns: 3,\n \"card:sprint\": {\n title: \"Sprint 进度\",\n \"progress:sp\": { label: \"完成度\", \"$value\": \"g.sprintProgress\" },\n \"stat:scope\": { label: \"范围状态\", \"$value\": \"g.scopeStatus()\" },\n \"badge:flag\": { \"$label\": \"g.scope === 'on-track' ? '正常' : g.scope === 'at-risk' ? '⚠ 预警' : '🚨 偏离'\", \"$tone\": \"g.scope === 'on-track' ? 'success' : g.scope === 'at-risk' ? 'warning' : 'danger'\" }\n },\n \"card:quality\": {\n title: \"质量指标\",\n \"stat:bugs\": { label: \"剩余缺陷\", value: \"3\", unit: \"个\" },\n \"progress:bugFix\": { label: \"修复率\", \"$value\": \"g.bugRate()\" },\n \"badge:trend\": { label: \"趋势：改善中\", tone: \"success\" }\n },\n \"card:team\": {\n title: \"团队健康度\",\n \"stat:members\": { label: \"团队成员\", value: \"6\", unit: \"人\" },\n \"progress:load\": { label: \"负载指数\", \"$value\": \"g.teamLoad()\" },\n \"callout:note\": { \"$tone\": \"g.teamLoad() > 80 ? 'warning' : 'info'\", \"$text\": \"g.teamLoad() > 80 ? '负载偏高，建议调整任务分配。' : '团队负载在健康范围内。'\" }\n }\n },\n \"card:detail\": {\n title: \"详细数据\",\n \"table:tasks\": {\n columns: [\"任务\", \"负责人\", \"状态\", \"耗时\"],\n rows: [[\"API 重构\", \"张三\", \"已完成\", \"3d\"], [\"前端组件\", \"李四\", \"进行中\", \"2d\"], [\"集成测试\", \"王五\", \"代码审查\", \"1.5d\"], [\"性能优化\", \"赵六\", \"待开始\", \"—\"]]\n },\n \"callout:help\": { \"$tone\": \"g.bugRate() < 80 ? 'warning' : 'success'\", \"$text\": \"g.bugRate() < 80 ? '缺陷修复率低于80%，建议优先处理高优先级缺陷。' : '缺陷修复率良好，项目质量可控。'\" }\n }\n }\n }\n}\n```\n\n**仪表盘的设计思路：**\n\n- 用 `section` 做顶层分组（带 eyebrow 和 subtitle，语义清晰）\n- 用 `grid` 做多列布局，每个格子放一个 `card`\n- 每个 card 内放不同关注维度的 stat / progress / badge\n- 底部放一个详情 card，展示表格数据（任务列表）\n- 通过 `$text` 和 `$tone` 在 callout 中做条件提示\n\n\n类似结构可用于技术 Leader 周报面板、发布质检看板、团队 OKR 追踪和 SRE 服务大盘。", "hash": "54a689ed" }, { "id": "examples/form-wizard-steps", "group": "Examples", "title": "ToolHost 表单提问", "summary": "ToolHost 在对话中渲染表单卡片，收集项目信息并提交结构化结果。", "href": "/zh-CN/examples/form-wizard-steps", "rawHref": "/zh-CN/examples/form-wizard-steps.md", "sourcePath": "content/examples/form-wizard-steps/zh-CN.md", "body": "# ToolHost 表单提问\n\n当对话需要补齐项目信息、服务配置或工单字段时，ToolHost 可以渲染表单卡片。用户提交后，结果以结构化数据返回。\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_form_wizard\",\n g: {\n submitted: false,\n formData: null,\n fields: { name: \"\", description: \"\", type: \"web\", priority: \"medium\" },\n submit: function () {\n this.submitted = true;\n this.formData = { name: this.fields.name, description: this.fields.description, type: this.fields.type, priority: this.fields.priority, timestamp: new Date().toLocaleString() };\n }\n },\n layout: {\n \"section:toolhost\": {\n eyebrow: \"ToolHost · 表单提问\",\n title: \"收集项目信息\",\n subtitle: \"表单提交后，ToolHost 返回结构化结果。\",\n \"callout:context\": {\n tone: \"info\",\n text: \"需要创建一个新项目，请填写以下信息。\"\n },\n \"grid:fields\": {\n columns: 1, mdColumns: 2,\n \"input:name\": { label: \"项目名称\", \"$value\": \"g.fields.name\", placeholder: \"my-project\", onchange: \"g.fields.name = String($event || '')\" },\n \"input:description\": { label: \"项目描述\", \"$value\": \"g.fields.description\", placeholder: \"简短描述项目用途\", onchange: \"g.fields.description = String($event || '')\" },\n \"select:type\": {\n label: \"项目类型\",\n \"$value\": \"g.fields.type\",\n options: [\n { label: \"Web 应用\", value: \"web\" },\n { label: \"API 服务\", value: \"api\" },\n { label: \"CLI 工具\", value: \"cli\" }\n ],\n onchange: \"g.fields.type = String($event)\"\n },\n \"select:priority\": {\n label: \"优先级\",\n \"$value\": \"g.fields.priority\",\n options: [\n { label: \"低\", value: \"low\" },\n { label: \"中\", value: \"medium\" },\n { label: \"高\", value: \"high\" }\n ],\n onchange: \"g.fields.priority = String($event)\"\n }\n },\n \"grid:actions\": {\n columns: 2,\n \"button:submit\": { label: \"提交\", onclick: \"g.submit()\" },\n \"button:skip\": { label: \"跳过\" }\n },\n \"callout:result\": {\n \"$tone\": \"g.submitted ? 'success' : 'info'\",\n \"$text\": \"g.submitted ? '已提交：' + g.formData.name + '（' + g.formData.type + '）' : '等待用户填写...'\"\n },\n \"code-block:toolresult\": {\n title: \"返回给宿主的 ToolResult\",\n language: \"json\",\n \"$code\": \"g.submitted ? JSON.stringify({ toolCallId: 'call_abc123', toolName: 'create-project', status: 'submitted', value: g.formData }, null, 2) : '// 提交后显示 ToolResult'\"\n }\n }\n }\n}\n```\n\n---", "hash": "f5c1179f" }, { "id": "examples/toolhost-demo", "group": "Examples", "title": "ToolHost 工具调用 UI", "summary": "把 function_call 渲染成对话内工具卡片，再把提交结果写回 function_call_output。", "href": "/zh-CN/examples/toolhost-demo", "rawHref": "/zh-CN/examples/toolhost-demo.md", "sourcePath": "content/examples/toolhost-demo/zh-CN.md", "body": "# ToolHost 工具调用 UI\n\n当 Agent 发起 `function_call` 时，浏览器宿主可以把它渲染成对话里的 ToolHost 工具卡片；用户提交后，宿主按原 `call_id` 写回 `function_call_output`，并把结果记录留在轨迹里。本页只用发布窗口、负责人和回滚条件作为工具参数示例，不连接模型或后端。", "hash": "061ec72c" }, { "id": "examples/tech-selection-evaluator", "group": "Examples", "title": "技术选型评估", "summary": "评估不同技术方案的优劣，通过跨 fence 联动实现参数选择、评分分析和结论推荐。", "href": "/zh-CN/examples/tech-selection-evaluator", "rawHref": "/zh-CN/examples/tech-selection-evaluator.md", "sourcePath": "content/examples/tech-selection-evaluator/zh-CN.md", "body": "# 技术选型评估\n\n该示例把前端框架选型拆成四个可调维度：性能、生态、学习曲线和维护成本。选择技术栈后，下方评分和结论会自动更新。\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_tech_selection\",\n g: {\n tech: \"react\",\n performance: 85,\n ecosystem: 95,\n learning: 70,\n maintenance: 80,\n techLabel: function () { return { react: \"React\", vue: \"Vue\", svelte: \"Svelte\", angular: \"Angular\" }[this.tech] || this.tech; },\n totalScore: function () { return (this.performance * 0.3 + this.ecosystem * 0.25 + this.learning * 0.2 + this.maintenance * 0.25).toFixed(1); },\n recommendation: function () { var s = parseFloat(this.totalScore()); return s >= 85 ? \"强烈推荐\" : s >= 75 ? \"推荐\" : s >= 60 ? \"可以考虑\" : \"不推荐\"; },\n riskLevel: function () { var s = parseFloat(this.totalScore()); return s >= 85 ? \"低\" : s >= 75 ? \"中\" : \"高\"; },\n scores: function () {\n var data = {\n react: { performance: 85, ecosystem: 95, learning: 70, maintenance: 80 },\n vue: { performance: 80, ecosystem: 85, learning: 85, maintenance: 85 },\n svelte: { performance: 95, ecosystem: 70, learning: 90, maintenance: 90 },\n angular: { performance: 80, ecosystem: 80, learning: 60, maintenance: 75 }\n };\n return data[this.tech] || data.react;\n }\n },\n layout: {\n \"section:select\": {\n eyebrow: \"决策辅助\",\n title: \"技术选型评估\",\n subtitle: \"选一个技术栈，下面的评分和结论自动跟着变。\",\n \"card:select\": {\n title: \"选择技术栈\",\n \"select:tech\": {\n label: \"技术栈\",\n \"$value\": \"g.tech\",\n options: [\n { label: \"React\", value: \"react\" },\n { label: \"Vue\", value: \"vue\" },\n { label: \"Svelte\", value: \"svelte\" },\n { label: \"Angular\", value: \"angular\" }\n ],\n onchange: \"g.tech = String($event); var s = g.scores(); g.performance = s.performance; g.ecosystem = s.ecosystem; g.learning = s.learning; g.maintenance = s.maintenance;\"\n },\n \"badge:current\": {\n \"$label\": \"'当前：' + g.techLabel()\",\n tone: \"info\"\n }\n }\n }\n }\n}\n```\n\n拖动滑块后，推荐结果和风险等级会实时更新；三个独立代码块通过同一份状态联动。\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_tech_selection\",\n layout: {\n \"card:scoring\": {\n title: \"评分调整\",\n \"grid:sliders\": {\n columns: 1, mdColumns: 2,\n \"column:left\": {\n \"slider:performance\": { label: \"性能（30%）\", \"$value\": \"g.performance\", min: 0, max: 100, step: 5, onchange: \"g.performance = Number($event)\" },\n \"slider:ecosystem\": { label: \"生态系统（25%）\", \"$value\": \"g.ecosystem\", min: 0, max: 100, step: 5, onchange: \"g.ecosystem = Number($event)\" }\n },\n \"column:right\": {\n \"slider:learning\": { label: \"学习曲线（20%）\", \"$value\": \"g.learning\", min: 0, max: 100, step: 5, onchange: \"g.learning = Number($event)\" },\n \"slider:maintenance\": { label: \"维护成本（25%）\", \"$value\": \"g.maintenance\", min: 0, max: 100, step: 5, onchange: \"g.maintenance = Number($event)\" }\n }\n },\n \"grid:weights\": {\n columns: 1, mdColumns: 4,\n \"stat:perf\": { label: \"性能（30%）\", \"$value\": \"g.performance\", unit: \"分\" },\n \"stat:eco\": { label: \"生态（25%）\", \"$value\": \"g.ecosystem\", unit: \"分\" },\n \"stat:learn\": { label: \"学习（20%）\", \"$value\": \"g.learning\", unit: \"分\" },\n \"stat:maint\": { label: \"维护（25%）\", \"$value\": \"g.maintenance\", unit: \"分\" }\n }\n }\n }\n}\n```\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_tech_selection\",\n layout: {\n \"card:result\": {\n title: \"综合评估\",\n \"grid:scores\": {\n columns: 1, mdColumns: 3,\n \"stat:total\": { label: \"综合评分\", \"$value\": \"g.totalScore()\" },\n \"stat:recommendation\": { label: \"推荐程度\", \"$value\": \"g.recommendation()\", \"$tone\": \"parseFloat(g.totalScore()) >= 85 ? 'success' : parseFloat(g.totalScore()) >= 75 ? 'info' : 'warning'\" },\n \"stat:risk\": { label: \"风险等级\", \"$value\": \"g.riskLevel()\", \"$tone\": \"parseFloat(g.totalScore()) >= 85 ? 'success' : parseFloat(g.totalScore()) >= 75 ? 'warning' : 'danger'\" }\n },\n \"callout:advice\": {\n \"$tone\": \"parseFloat(g.totalScore()) >= 85 ? 'success' : parseFloat(g.totalScore()) >= 75 ? 'info' : 'warning'\",\n \"$text\": \"parseFloat(g.totalScore()) >= 85 ? g.techLabel() + ' 综合优秀，强烈推荐。' : parseFloat(g.totalScore()) >= 75 ? g.techLabel() + ' 综合良好，推荐采用。' : g.techLabel() + ' 综合一般，建议谨慎。'\"\n }\n }\n }\n}\n```\n\n\n默认评分参考：\n\n| 技术栈 | 性能 | 生态 | 学习 | 维护 | 综合 |\n|--------|------|------|------|------|------|\n| React | 85 | 95 | 70 | 80 | 82.5 |\n| Vue | 80 | 85 | 85 | 85 | 83.75 |\n| Svelte | 95 | 70 | 90 | 90 | 85.5 |\n| Angular | 80 | 80 | 60 | 75 | 73.75 |\n\n权重分配：性能30%、生态25%、学习曲线20%、维护成本25%。可以按团队实际情况调整。", "hash": "25ee1a84" }, { "id": "examples/roi-estimator", "group": "Examples", "title": "自建还是外购决策", "summary": "自建还是外购决策矩阵——功能覆盖、成本对比、时间线、风险四维度评估，自动推荐方案。", "href": "/zh-CN/examples/roi-estimator", "rawHref": "/zh-CN/examples/roi-estimator.md", "sourcePath": "content/examples/roi-estimator/zh-CN.md", "body": "# 自建还是外购决策\n\n该示例把自建/外购决策拆成四个维度：功能覆盖、成本、时间线和风险。调整评分后，结论会自动更新。\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_build_vs_buy\",\n g: {\n scope: \"core\",\n buildFit: 60, buildTime: 6, buildCost: 80,\n buyFit: 85, buyTime: 1, buyCost: 40, buyVendorLock: 30,\n buildTotal: function () { return (this.buildFit + (100 - this.buildCost) + (100 - this.buildTime * 10)) / 3; },\n buyTotal: function () { return (this.buyFit + (100 - this.buyCost) + (100 - this.buyTime * 10) - this.buyVendorLock * 0.5) / 3; },\n recommendation: function () {\n if (this.scope === \"core\") return this.buildTotal() >= this.buyTotal() ? \"自建\" : \"外购（但建议评估长期成本）\";\n return this.buyTotal() >= this.buildTotal() ? \"外购\" : \"自建（非核心功能自建需谨慎）\";\n },\n diff: function () { return Math.abs(this.buildTotal() - this.buyTotal()); }\n },\n layout: {\n \"section:decision\": {\n eyebrow: \"技术决策\",\n title: \"自建还是外购决策\",\n subtitle: \"对比两个方案的各维度评分，系统综合推荐。拖滑块调整评分看结论变化。\",\n \"select:scope\": {\n label: \"功能定位\",\n \"$value\": \"g.scope\",\n options: [\n { label: \"核心业务（差异化的关键）\", value: \"core\" },\n { label: \"辅助功能（非核心）\", value: \"non-core\" }\n ],\n onchange: \"g.scope = String($event)\"\n },\n \"table:comparison\": {\n columns: [\"维度\", \"自建方案\", \"外购方案\"],\n rows: [\n [\"功能匹配度\", \"g.buildFit + '%'\", \"g.buyFit + '%'\"],\n [\"上线时间\", \"g.buildTime + ' 个月'\", \"g.buyTime + ' 个月'\"],\n [\"成本评分\", \"g.buildCost + '/100'\", \"g.buyCost + '/100'\"],\n [\"供应商锁定\", \"—\", \"g.buyVendorLock + '/100'\"]\n ]\n },\n \"grid:sliders\": {\n columns: 1, mdColumns: 2,\n \"column:build\": {\n \"card:buildSliders\": {\n title: \"自建方案\",\n \"slider:buildFit\": { label: \"功能匹配度\", \"$value\": \"g.buildFit\", min: 0, max: 100, step: 5, onchange: \"g.buildFit = Number($event)\" },\n \"slider:buildTime\": { label: \"上线时间（月）\", \"$value\": \"g.buildTime\", min: 1, max: 24, step: 1, unit: \"月\", onchange: \"g.buildTime = Number($event)\" },\n \"slider:buildCost\": { label: \"成本评分\", \"$value\": \"g.buildCost\", min: 0, max: 100, step: 5, onchange: \"g.buildCost = Number($event)\" }\n }\n },\n \"column:buy\": {\n \"card:buySliders\": {\n title: \"外购方案\",\n \"slider:buyFit\": { label: \"功能匹配度\", \"$value\": \"g.buyFit\", min: 0, max: 100, step: 5, onchange: \"g.buyFit = Number($event)\" },\n \"slider:buyTime\": { label: \"上线时间（月）\", \"$value\": \"g.buyTime\", min: 1, max: 24, step: 1, unit: \"月\", onchange: \"g.buyTime = Number($event)\" },\n \"slider:buyCost\": { label: \"成本评分\", \"$value\": \"g.buyCost\", min: 0, max: 100, step: 5, onchange: \"g.buyCost = Number($event)\" },\n \"slider:lock\": { label: \"供应商锁定风险\", \"$value\": \"g.buyVendorLock\", min: 0, max: 100, step: 5, onchange: \"g.buyVendorLock = Number($event)\" }\n }\n }\n },\n \"grid:results\": {\n columns: 1, mdColumns: 3,\n \"stat:buildScore\": { label: \"自建综合得分\", \"$value\": \"g.buildTotal().toFixed(1)\" },\n \"stat:buyScore\": { label: \"外购综合得分\", \"$value\": \"g.buyTotal().toFixed(1)\" },\n \"badge:winner\": { \"$label\": \"g.recommendation().startsWith('自建') ? '建议自建' : '建议外购'\", \"$tone\": \"g.diff() < 10 ? 'warning' : g.recommendation().startsWith('自建') ? 'info' : 'success'\" }\n },\n \"callout:advice\": {\n \"$tone\": \"g.diff() < 10 ? 'warning' : 'info'\",\n \"$text\": \"g.diff() < 10 ? '两个方案得分非常接近——建议引入更多决策者参与讨论，或做小范围 POC。' : g.recommendation() + ' 方案的得分明显更高。但请结合团队实际能力和战略方向做最终决定。'\"\n },\n \"accordion:detail\": {\n multiple: true,\n items: [\n { value: \"cost\", label: \"成本说明\", content: \"成本评分越低越好（0 = 零成本，100 = 极高成本）。外购方案需额外考虑供应商锁定风险。\" },\n { value: \"scope\", label: \"核心 vs 非核心策略\", content: \"核心业务功能通常倾向自建以保持控制力和差异化。非核心功能外购可以释放团队精力。\" },\n { value: \"hybrid\", label: \"第三条路：混合方案\", content: \"也可以考虑先外购快速上线，同时内部规划自建替代方案，等自建成熟后迁移。\" }\n ]\n }\n }\n }\n}\n```\n\n\n**Build vs Buy 决策模型的要点：**\n\n- `select` 定义功能定位（核心/非核心），影响决策偏向\n- 两套 slider 独立调整各自评分\n- `buildTotal()` 和 `buyTotal()` 用加权公式计算综合得分\n- `recommendation()` 结合功能定位和得分给出建议\n- accordion 提供额外的决策指南（成本说明、策略建议、混合方案）\n\n这个框架把主观判断拆成可比较的评分项。", "hash": "41705803" }, { "id": "examples/cross-doc-state-lab", "group": "Examples", "title": "跨文档状态实验室", "summary": "多块 `slex` 代码使用同一个 namespace，共享同一份响应式 `g` 状态。", "href": "/zh-CN/examples/cross-doc-state-lab", "rawHref": "/zh-CN/examples/cross-doc-state-lab.md", "sourcePath": "content/examples/cross-doc-state-lab/zh-CN.md", "body": "# 跨文档状态实验室\n\n同一篇 Markdown 中的多个 `slex` 代码块可以通过相同 `namespace` 共享 `g` 状态。\n\n下面是三个独立的 ` ```slex ` fence——一个控制面板和两个观察面板。试试修改控制面板的值，看下方两个面板实时响应。\n\n## 主控面板\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_cross_doc_lab\",\n g: {\n color: \"blue\", size: 16, theme: \"light\",\n style: function () {\n return 'color: ' + this.color + '; font-size: ' + this.size + 'px;';\n }\n },\n layout: {\n \"section:control\": {\n eyebrow: \"平台能力\",\n title: \"跨文档状态实验室 · 主控面板\",\n subtitle: \"修改以下任何参数——下方两个独立 fence 块的卡片会同步更新。\",\n \"grid:controls\": {\n columns: 1, mdColumns: 3,\n \"select:color\": {\n label: \"文字颜色\",\n \"$value\": \"g.color\",\n options: [\n { label: \"蓝色\", value: \"blue\" },\n { label: \"绿色\", value: \"green\" },\n { label: \"橙色\", value: \"orange\" },\n { label: \"紫色\", value: \"purple\" }\n ],\n onchange: \"g.color = String($event)\"\n },\n \"slider:size\": { label: \"字体大小\", \"$value\": \"g.size\", min: 8, max: 48, step: 2, unit: \"px\", onchange: \"g.size = Number($event)\" },\n \"select:theme\": {\n label: \"卡片主题\",\n \"$value\": \"g.theme\",\n options: [\n { label: \"明亮\", value: \"light\" },\n { label: \"暗色\", value: \"dark\" },\n { label: \"信息\", value: \"info\" }\n ],\n onchange: \"g.theme = String($event)\"\n }\n },\n \"badge:note\": { \"$label\": \"'样式 ' + g.color + ' ' + g.size + 'px'\", tone: \"info\" }\n }\n }\n}\n```\n\n## 观察面板 A（同一 namespace，不同 fence 块）\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_cross_doc_lab\",\n layout: {\n \"card:a\": {\n title: \"观察面板 A — 纯文本样式\",\n \"column:stylePreview\": {\n \"text:styleMeta\": { \"$text\": \"'字体大小：' + g.size + 'px'\" },\n \"text:styledValue\": { \"$text\": \"g.color\", \"$color\": \"g.color\", \"$size\": \"g.size\" }\n },\n \"callout:preview\": {\n \"$tone\": \"g.theme === 'dark' ? 'danger' : g.theme === 'info' ? 'info' : 'success'\",\n \"$text\": \"g.theme === 'dark' ? '暗色模式：适合夜间阅读的配色方案。' : g.theme === 'info' ? '信息模式：用于强调技术细节。' : '明亮模式：默认的文档阅读配色。'\"\n }\n }\n }\n}\n```\n\n## 观察面板 B\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_cross_doc_lab\",\n layout: {\n \"card:b\": {\n title: \"观察面板 B — 参数详情\",\n \"grid:params\": {\n columns: 1, mdColumns: 3,\n \"stat:col\": { label: \"颜色\", \"$value\": \"g.color\" },\n \"stat:sz\": { label: \"字号\", \"$value\": \"g.size\", unit: \"px\" },\n \"stat:th\": { label: \"主题\", \"$value\": \"g.theme\" }\n },\n \"badge:sync\": { \"$label\": \"'已同步 ' + g.color\", \"$tone\": \"g.color === 'blue' ? 'info' : g.color === 'green' ? 'success' : g.color === 'orange' ? 'warning' : 'info'\" }\n }\n }\n}\n```\n\n**三个 fence 块**，同一个 `namespace: \"example_cross_doc_lab\"`，所有组件共享 `g` 对象。主控面板中的颜色和大小变化会同步到两个观察面板。\n\n---\n\n### 这意味着什么？\n\n在一篇长篇 Markdown 文档中：\n\n```\n[控制面板 — 选择行业/指标/时间范围]\n... 30 段 Markdown 叙事 ...\n[图表 A — 自动反映控制面板的选项]\n... 更多分析文字 ...\n[图表 B — 同一份状态的不同可视化]\n```\n\n每个 ` ```slex ` 块可以独立渲染；namespace 相同时，它们共享状态。常见用法包括：\n\n- **技术白皮书**：顶部选参数，中间分析，底部结论，全程联动\n- **项目协作文档**：状态跟踪表格在顶部，各团队任务卡片散布在正文中\n- **AI 输出增强**：模型生成的多个可视化节点共享同一份推理结果\n\n这些场景都依赖同一个机制：多块 fence 共享同一份状态，而不是把每块 UI 当成完全独立的组件。", "hash": "6ac00785" }, { "id": "examples/network-policy-fetch-card", "group": "Examples", "title": "JSONPlaceholder 网络请求实验台", "summary": "用 JSONPlaceholder 演示 secure runtime 如何把用户触发的网络请求交给 host policy 审核和代理。", "href": "/zh-CN/examples/network-policy-fetch-card", "rawHref": "/zh-CN/examples/network-policy-fetch-card.md", "sourcePath": "content/examples/network-policy-fetch-card/zh-CN.md", "body": "# JSONPlaceholder 网络请求实验台\n\n该示例让用户在 secure runtime 沙盒内选择网络任务：读取 posts、查看详情、拉取评论、按用户过滤，或向 JSONPlaceholder 发起演示 POST。请求不会从 iframe 直接出网，而是通过 `api.fetch()` 交给宿主，由宿主按 allowlist、方法、超时、请求体大小和响应类型决定是否代理。\n\n```slex\n{\n slex: \"0.1\",\n namespace: \"example_jsonplaceholder_network_lab\",\n g: {\n scenario: \"posts\",\n postId: 1,\n userId: 1,\n timeout: 3000,\n title: \"SlexKit network demo\",\n status: \"未请求\",\n statusCode: \"-\",\n elapsed: \"-\",\n response: \"选择一个网络任务，然后点击“发起请求”。\",\n lastUrl: \"https://jsonplaceholder.typicode.com/posts\",\n method: function () { return this.scenario === \"create\" ? \"POST\" : \"GET\"; },\n url: function () {\n if (this.scenario === \"detail\") return \"https://jsonplaceholder.typicode.com/posts/\" + this.postId;\n if (this.scenario === \"comments\") return \"https://jsonplaceholder.typicode.com/posts/\" + this.postId + \"/comments\";\n if (this.scenario === \"user-posts\") return \"https://jsonplaceholder.typicode.com/users/\" + this.userId + \"/posts\";\n if (this.scenario === \"create\") return \"https://jsonplaceholder.typicode.com/posts\";\n return \"https://jsonplaceholder.typicode.com/posts?_limit=5\";\n },\n requestBody: function () {\n if (this.scenario !== \"create\") return undefined;\n return {\n title: this.title,\n body: \"这是一条从 SlexKit secure runtime 发起、由宿主代理的演示请求。\",\n userId: this.userId\n };\n },\n description: function () {\n if (this.scenario === \"detail\") return \"读取单篇 post，适合详情页或引用卡片。\";\n if (this.scenario === \"comments\") return \"读取某篇 post 的评论，适合评论摘要、审阅流和证据面板。\";\n if (this.scenario === \"user-posts\") return \"按用户读取 posts，适合个人空间、作者档案或关联资源列表。\";\n if (this.scenario === \"create\") return \"提交一条演示 post。JSONPlaceholder 会返回假写入结果，不会持久化。\";\n return \"读取最新 posts 列表，适合 feed、任务列表和知识库索引。\";\n },\n riskText: function () {\n if (this.method() === \"POST\") return \"POST 已被限制为 JSONPlaceholder origin，且请求体大小受 policy 约束。\";\n return \"GET 请求仍然要经过 origin、超时、响应大小和 content-type 校验。\";\n },\n requestSnippet: function () {\n var body = this.requestBody();\n var lines = [\n \"await api.fetch('\" + this.url() + \"', {\",\n \" method: '\" + this.method() + \"',\",\n \" timeoutMs: \" + this.timeout + \",\"\n ];\n if (body) lines.push(\" body: \" + JSON.stringify(body, null, 2).replace(/\\n/g, \"\\n \") + \",\");\n lines.push(\" credentials: 'omit'\");\n lines.push(\"})\");\n return lines.join(\"\\n\");\n },\n policyRows: function () {\n return [\n { item: \"Origin\", value: \"https://jsonplaceholder.typicode.com\", reason: \"只允许演示 API\" },\n { item: \"Method\", value: \"GET, POST\", reason: \"读列表/详情和创建演示数据\" },\n { item: \"Credentials\", value: \"omit\", reason: \"不携带 cookie 或站点身份\" },\n { item: \"Content-Type\", value: \"application/json\", reason: \"拒绝非 JSON 响应进入沙盒\" },\n { item: \"Body\", value: \"<= 4096 bytes\", reason: \"避免大请求体被模型输出滥用\" }\n ];\n },\n async run(api) {\n var targetUrl = String(this.url());\n this.status = \"请求中\";\n this.statusCode = \"-\";\n this.elapsed = \"-\";\n this.lastUrl = targetUrl;\n this.response = \"等待宿主代理 \" + this.method() + \" \" + targetUrl;\n try {\n var result = await api.fetch(targetUrl, {\n method: this.method(),\n timeoutMs: this.timeout,\n body: this.requestBody(),\n credentials: \"omit\"\n });\n this.status = result.ok ? \"成功\" : \"HTTP 错误\";\n this.statusCode = String(result.status) + \" \" + result.statusText;\n this.elapsed = Math.round(result.elapsedMs) + \" ms\";\n this.response = JSON.stringify(result.data === undefined ? result.text : result.data, null, 2).slice(0, 2400);\n } catch (error) {\n this.status = api.isPolicyError(error) ? \"Policy 拦截\" : api.isTimeoutError(error) ? \"超时\" : \"网络失败\";\n this.statusCode = api.isPolicyError(error) ? \"policy\" : api.isTimeoutError(error) ? \"timeout\" : \"network\";\n var elapsedMs = error && typeof error === \"object\" && typeof error.elapsedMs === \"number\" ? error.elapsedMs : undefined;\n this.elapsed = elapsedMs === undefined ? \"-\" : Math.round(elapsedMs) + \" ms\";\n this.response = targetUrl + \"\\n\" + api.errorMessage(error);\n }\n },\n async runBlocked(api) {\n var targetUrl = \"https://example.com/posts/1\";\n this.status = \"请求中\";\n this.statusCode = \"-\";\n this.elapsed = \"-\";\n this.lastUrl = targetUrl;\n this.response = \"这次请求故意访问 allowlist 外的 origin，应该被 host policy 拦截。\";\n try {\n await api.get(targetUrl, { timeoutMs: this.timeout, credentials: \"omit\" });\n this.status = \"异常通过\";\n this.statusCode = \"unexpected\";\n this.response = \"如果看到这行，说明 policy 没有按预期拦截。\";\n } catch (error) {\n this.status = api.isPolicyError(error) ? \"Policy 拦截\" : \"失败\";\n this.statusCode = api.isPolicyError(error) ? \"origin_blocked\" : \"network\";\n this.response = targetUrl + \"\\n\" + api.errorMessage(error);\n }\n }\n },\n layout: {\n \"section:network\": {\n eyebrow: \"平台能力\",\n title: \"JSONPlaceholder 网络请求实验台\",\n subtitle: \"在沙盒内选择网络任务，请求通过 host policy 代理。\",\n \"card:network\": {\n title: \"JSONPlaceholder 请求实验台\",\n \"callout:intent\": { tone: \"info\", \"$text\": \"g.description()\" },\n \"grid:controls\": {\n columns: 1,\n mdColumns: 2,\n \"select:scenario\": {\n label: \"网络任务\",\n \"$value\": \"g.scenario\",\n options: [\n { label: \"Posts 列表 GET /posts\", value: \"posts\" },\n { label: \"Post 详情 GET /posts/:id\", value: \"detail\" },\n { label: \"评论列表 GET /posts/:id/comments\", value: \"comments\" },\n { label: \"用户 posts GET /users/:id/posts\", value: \"user-posts\" },\n { label: \"创建 post POST /posts\", value: \"create\" }\n ],\n onchange: \"g.scenario = String($event)\"\n },\n \"slider:postId\": { label: \"Post ID\", \"$value\": \"g.postId\", min: 1, max: 10, step: 1, onchange: \"g.postId = Number($event)\" },\n \"slider:userId\": { label: \"User ID\", \"$value\": \"g.userId\", min: 1, max: 10, step: 1, onchange: \"g.userId = Number($event)\" },\n \"slider:timeout\": { label: \"超时上限\", \"$value\": \"g.timeout\", min: 500, max: 8000, step: 500, unit: \"ms\", onchange: \"g.timeout = Number($event)\" }\n },\n \"row:actions\": {\n \"button:run\": { label: \"发起请求\", icon: \"paper-plane-tilt\", onclick: \"g.run(api)\" },\n \"button:block\": { label: \"测试拦截\", variant: \"secondary\", icon: \"shield-warning\", onclick: \"g.runBlocked(api)\" }\n },\n \"grid:status\": {\n columns: 1,\n mdColumns: 3,\n \"stat:method\": { label: \"方法\", \"$value\": \"g.method()\" },\n \"stat:status\": { label: \"状态\", \"$value\": \"g.status\" },\n \"stat:elapsed\": { label: \"耗时\", \"$value\": \"g.elapsed\" }\n },\n \"code-block:request\": { title: \"沙盒内请求代码\", language: \"ts\", \"$code\": \"g.requestSnippet()\" },\n \"code-block:response\": { title: \"宿主代理响应\", language: \"json\", \"$code\": \"g.response\" },\n \"table:policy_matrix\": {\n columns: [\n { key: \"item\", label: \"Policy 项\" },\n { key: \"value\", label: \"允许值\" },\n { key: \"reason\", label: \"原因\" }\n ],\n \"$rows\": \"g.policyRows()\"\n },\n \"callout:policy_note\": { \"$tone\": \"g.status === 'Policy 拦截' ? 'warning' : 'success'\", \"$text\": \"g.riskText()\" }\n }\n }\n }\n}\n```", "hash": "205fe07c" }, { "id": "examples/assistant-ui-host", "group": "Examples", "title": "assistant-ui 接入", "summary": "在 assistant-ui 的 Streamdown text message parts 中渲染显式 slex fences。", "href": "/zh-CN/examples/assistant-ui-host", "rawHref": "/zh-CN/examples/assistant-ui-host.md", "sourcePath": "content/examples/assistant-ui-host/zh-CN.md", "body": "# assistant-ui 接入\n\nassistant-ui 项目已经用 `@assistant-ui/react-streamdown` 渲染文本消息时，可以用 `@slexkit/assistant-ui` 替换 text part 里的 `slex` language block。thread、composer、message parts、runtime 和 tool UI 仍由 assistant-ui 处理。\n\n下面的可运行演示是一个静态 assistant-ui transcript，用于验证 adapter 在 assistant-ui message-part 上下文中的渲染行为；它不连接模型、API key 或 ToolHost 流程。\n\n```sh\nbun run --filter @slexkit/assistant-ui build\nbun examples/dev-server.mjs assistant-ui\n```\n\n源码位于 [`examples/assistant-ui`](https://github.com/slexkit/slexkit/tree/main/examples/assistant-ui)。页面用 `useExternalStoreRuntime` 和 `AssistantRuntimeProvider` 构造 thread，再通过 `SlexKitAssistantStreamdownText` 渲染 text parts。\n\n\n\n[打开集成指南](/zh-CN/docs/guides/integration) · [查看可运行源码](https://github.com/slexkit/slexkit/tree/main/examples/assistant-ui)\n\n安装：\n\n```sh\nnpm install slexkit @slexkit/theme-shadcn @slexkit/streamdown @slexkit/assistant-ui @assistant-ui/react @assistant-ui/react-streamdown streamdown react react-dom\n```\n\n导入样式：\n\n```ts\nimport \"@slexkit/theme-shadcn/style.css\";\nimport \"@slexkit/assistant-ui/style.css\";\n```\n\n接到 assistant message：\n\n```tsx\nimport { MessagePrimitive } from \"@assistant-ui/react\";\nimport { SlexKitAssistantStreamdownText } from \"@slexkit/assistant-ui\";\n\nexport function AssistantMessage() {\n return (\n \n \n {({ part }) =>\n part.type === \"text\" ? (\n \n ) : null\n }\n \n \n );\n}\n```\n\n模型输出示例：\n\n````md\n```slex\n{\n namespace: \"assistant_status\",\n g: {},\n layout: {\n \"text:status\": { text: \"Rendered inside assistant-ui.\" }\n }\n}\n```\n````\n\n## 处理范围\n\n| 项目 | 约定 |\n| --- | --- |\n| Fence language | `slex` |\n| Runtime | 默认 `secure` |\n| Markdown host | `@assistant-ui/react-streamdown` |\n| ToolHost | 不处理 |\n\nToolHost/tool-call 渲染需要单独接入。这个 adapter 只处理 assistant-ui text message parts 里的 Markdown fence runtime。\n\n项目已有 `StreamdownTextPrimitive` 包装时，可以用 `createSlexKitAssistantStreamdownComponents()` 只合并 `slex` language override。", "hash": "de3db31d" }, { "id": "examples/streamdown-host", "group": "Examples", "title": "Streamdown 接入", "summary": "React/Streamdown 适配器示例，在 Markdown 页面中渲染显式 `slex` 代码块。", "href": "/zh-CN/examples/streamdown-host", "rawHref": "/zh-CN/examples/streamdown-host.md", "sourcePath": "content/examples/streamdown-host/zh-CN.md", "body": "# Streamdown 接入\n\n如果 React 页面已经使用 Streamdown 渲染 Markdown，可以用 `@slexkit/streamdown` 接入 SlexKit。该示例复用官网的 RC 低通滤波器内容，演示 SlexKit 组件在 Streamdown 页面中的渲染方式。\n\n本地运行：\n\n```sh\nbun run build:core\nbun run --filter @slexkit/streamdown build\nbun examples/dev-server.mjs streamdown\n```\n\n源码位于 [`examples/streamdown`](https://github.com/slexkit/slexkit/tree/main/examples/streamdown)。Streamdown 与 Tiptap 示例使用同一份 RC 低通滤波器内容，便于对照两种宿主的接入方式。\n\n\n\n[打开集成指南](/zh-CN/docs/guides/integration) · [查看可运行源码](https://github.com/slexkit/slexkit/tree/main/examples/streamdown)\n\n## 接入方式\n\n| 项目 | 约定 |\n| --- | --- |\n| Fence language | `slex` |\n| Runtime | `trusted` 或 `secure` |\n| Markdown 宿主 | Streamdown |\n\n普通 Markdown、公式、表格和非 `slex` 代码块继续由 Streamdown 渲染。只写状态的 `slex` fence 不渲染独立 UI，但会写入同一 artifact state，供后续可渲染 fence 读取。\n\n最小配置：\n\n```tsx\nimport { Streamdown } from \"streamdown\";\nimport { createSlexKitRenderer } from \"@slexkit/streamdown\";\nimport \"@slexkit/theme-shadcn/style.css\";\nimport \"@slexkit/streamdown/style.css\";\n\nconst slexkitRenderer = createSlexKitRenderer({\n domain: \"message-1\",\n showChrome: false\n});\n\nexport function Message({ markdown }: { markdown: string }) {\n return (\n \n {markdown}\n \n );\n}\n```\n\n如果项目已经以 Streamdown 作为 Markdown 渲染层，使用 `@slexkit/streamdown`。如果宿主有自己的 Markdown parser 或 renderer，直接接入自定义 Markdown host API。", "hash": "51b6d16c" }, { "id": "examples/tiptap-host", "group": "Examples", "title": "Tiptap 编辑器接入", "summary": "Tiptap CodeBlock 适配器：只把显式 slex 代码块渲染为预览，普通代码块和 Markdown 导入/导出保持 Tiptap 行为。", "href": "/zh-CN/examples/tiptap-host", "rawHref": "/zh-CN/examples/tiptap-host.md", "sourcePath": "content/examples/tiptap-host/zh-CN.md", "body": "# Tiptap 编辑器接入\n\n需要在编辑器中预览 SlexKit 组件时，使用 `@slexkit/tiptap`。该示例复用官网的 RC 低通滤波器内容，演示 SlexKit 组件在 Tiptap 编辑器中的预览方式。\n\n本地运行：\n\n```sh\nbun run build:core\nbun run --filter @slexkit/tiptap build\nbun examples/dev-server.mjs tiptap\n```\n\n源码位于 [`examples/tiptap`](https://github.com/slexkit/slexkit/tree/main/examples/tiptap)。Tiptap 与 Streamdown 示例使用同一份 RC 低通滤波器内容，便于对照编辑器宿主和只读渲染宿主的接入方式。\n\n\n\n[打开集成指南](/zh-CN/docs/guides/integration) · [查看可运行源码](https://github.com/slexkit/slexkit/tree/main/examples/tiptap)\n\n## 接入方式\n\n| 项目 | 约定 |\n| --- | --- |\n| Block type | `codeBlock` |\n| Fence language | `slex` |\n| Runtime | `trusted` |\n\nTiptap 负责文档编辑和 Markdown 导入/导出。只写状态的 `slex` fence 与后续预览块共享 artifact runtime；非 `slex` code block 保持 Tiptap 原生行为。\n\n最小配置：\n\n```ts\nimport { Editor } from \"@tiptap/core\";\nimport StarterKit from \"@tiptap/starter-kit\";\nimport { Markdown } from \"@tiptap/markdown\";\nimport { createSlexKitTiptapExtension } from \"@slexkit/tiptap\";\nimport \"@slexkit/theme-shadcn/style.css\";\nimport \"@slexkit/tiptap/style.css\";\n\nconst editor = new Editor({\n element: document.querySelector(\"#editor\"),\n extensions: [\n StarterKit.configure({ codeBlock: false }),\n Markdown,\n createSlexKitTiptapExtension({ artifactId: \"doc-1\" })\n ],\n content: markdown,\n contentType: \"markdown\"\n});\n```\n\n需要编辑器内预览时使用 `@slexkit/tiptap`。只读 Markdown 输出通常使用 Streamdown 或自定义 Markdown host API。", "hash": "fbd49479" }, { "id": "components/accordion", "group": "Components", "title": "Accordion", "summary": "Expandable grouped panels.", "href": "/docs/components/accordion", "rawHref": "/docs/components/accordion.md", "sourcePath": "site/content/components/accordion/en-US.md", "body": "---\ntitle: \"Accordion\"\ncategory: Disclosure\nstatus: ready\norder: 10\nsummary: \"Multi-panel collapse for FAQs or grouped details.\"\n---\n# Accordion\n\nManages multiple collapsible panels, with one or more open at a time.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_accordion_typical\",\n \"layout\": {\n \"accordion:faq\": {\n \"multiple\": true,\n \"value\": [\n \"install\"\n ],\n \"items\": [\n {\n \"value\": \"install\",\n \"label\": \"Install\",\n \"icon\": \"download-simple\",\n \"content\": \"Prepare dependencies.\"\n },\n {\n \"value\": \"review\",\n \"label\": \"Review\",\n \"icon\": \"check-circle\",\n \"content\": \"Check the result.\"\n },\n {\n \"value\": \"ship\",\n \"label\": \"Ship\",\n \"icon\": \"rocket-launch\",\n \"content\": \"Publish the change.\"\n }\n ]\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for FAQs, grouped details, and collapsible setting lists.\n- Not suitable for a single expandable area (use `collapsible`).\n- Related components: `collapsible` for single expandable regions.\n- Use `$value` and `onchange` for controlled expansion.\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `value` | string \\| string[] | No | Yes | | Current expanded item value; use an array when multiple is true. |\n| `multiple` | boolean | No | No | `false` | Allow multiple items to be expanded at the same time. |\n| `items` | array | No | No | | Panel definitions with value, label, content, and optional icon. |\n| `items[].icon` | string | No | No | | Icon name shown before an item trigger label. |\n| `onchange` | write-expression | No | No | | Write expression invoked when expanded items change. |\n", "hash": "d2b3dd28" }, { "id": "components/badge", "group": "Components", "title": "Badge", "summary": "Compact label for status or classification.", "href": "/docs/components/badge", "rawHref": "/docs/components/badge.md", "sourcePath": "site/content/components/badge/en-US.md", "body": "---\ntitle: \"Badge\"\ncategory: Content\nstatus: ready\norder: 10\nsummary: \"Compact label for status or classification.\"\n---\n# Badge\n\nCompact status label component with semantic tone colors.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_badge_typical\",\n \"layout\": {\n \"row:badges\": {\n \"badge:ready\": {\n \"label\": \"ready\",\n \"icon\": \"check-circle\",\n \"tone\": \"success\"\n },\n \"badge:pending\": {\n \"label\": \"pending\",\n \"tone\": \"warning\"\n },\n \"badge:info\": {\n \"label\": \"info\",\n \"tone\": \"info\"\n }\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for status indicators (success / warning / error), classification labels, and count markers.\n- Not suitable for long text labels (use `callout`) or interactive triggers (use `button`).\n- Related components: `callout` for titled message blocks, `stat` for numeric metrics.\n- Multiple badges are typically placed inside a `row`.\n- Use `tone` only for semantic state, not as an arbitrary style picker.\n\n### Tone variants\n\n```slex\n{\n namespace: \"doc_badge_tone_diff\",\n layout: {\n \"row:tones\": {\n \"badge:info\": {\n label: \"info\",\n tone: \"info\"\n },\n \"badge:success\": {\n label: \"success\",\n tone: \"success\"\n },\n \"badge:warning\": {\n label: \"warning\",\n tone: \"warning\"\n },\n \"badge:danger\": {\n label: \"danger\",\n tone: \"danger\"\n },\n \"badge:muted\": {\n label: \"muted\",\n tone: \"muted\"\n }\n }\n }\n}\n```\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `label` | string | No | Yes | | Badge text. |\n| `text` | string | No | Yes | | Alias for label. |\n| `content` | string | No | Yes | | Alias for label. |\n| `icon` | string | No | No | | Icon name shown before the badge label. |\n| `tone` | string: info, success, warning, danger, muted | No | No | `\"info\"` | Semantic tone applied to the badge. |\n| `variant` | string: info, success, warning, danger, muted | No | No | | Alias for tone. |\n", "hash": "8d717464" }, { "id": "components/button", "group": "Components", "title": "Button", "summary": "Action trigger.", "href": "/docs/components/button", "rawHref": "/docs/components/button.md", "sourcePath": "site/content/components/button/en-US.md", "body": "---\ntitle: \"Button\"\ncategory: Action\nstatus: ready\norder: 10\nsummary: \"Action trigger button.\"\n---\n# Button\n\nTriggers actions in interactive SlexKit layouts.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_button_typical\",\n \"layout\": {\n \"row:actions\": {\n \"button:save\": {\n \"label\": \"Save\",\n \"icon\": \"floppy-disk\",\n \"variant\": \"primary\"\n },\n \"button:cancel\": {\n \"label\": \"Cancel\",\n \"variant\": \"secondary\"\n },\n \"button:delete\": {\n \"label\": \"Delete\",\n \"variant\": \"danger\"\n }\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for form submission, confirmation actions, and command triggers.\n- When `href` is present, the button renders as a button-styled link action; use `link` for ordinary inline navigation.\n- `selected`, `active`, and `pressed` describe the visual state of the button icon and pressed metadata.\n- Related components: `link` for navigation instead of actions, `submit` for ToolHost submission flows.\n- Multiple buttons are typically placed inside a `row`.\n- Use `variant` only for semantic action types, not as a general style picker.\n\n### Variants\n\n```slex\n{\n namespace: \"doc_button_variant_diff\",\n layout: {\n \"row:variants\": {\n \"button:primary\": {\n label: \"Primary\",\n variant: \"primary\"\n },\n \"button:secondary\": {\n label: \"Secondary\",\n variant: \"secondary\"\n },\n \"button:danger\": {\n label: \"Danger\",\n variant: \"danger\"\n },\n \"button:ghost\": {\n label: \"Ghost\",\n variant: \"ghost\"\n }\n }\n }\n}\n```\n\n### Disabled state\n\n```slex\n{\n namespace: \"doc_button_disabled_diff\",\n layout: {\n \"row:disabled\": {\n \"button:enabled\": {\n label: \"Enabled\"\n },\n \"button:disabled\": {\n label: \"Disabled\",\n disabled: true\n }\n }\n }\n}\n```\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `label` | string | No | Yes | | Visible button text and accessible name. |\n| `icon` | string | No | No | | Icon name shown before the label. |\n| `iconOnly` | boolean | No | No | `false` | Show only the icon while retaining label as the accessible name. |\n| `variant` | string: primary, secondary, danger, ghost | No | No | `\"primary\"` | Semantic action variant. |\n| `disabled` | boolean | No | Yes | `false` | Disable the action. |\n| `href` | string | No | Yes | | Render the button surface as a link to this URL. |\n| `target` | string | No | No | | Link target used when href is present. |\n| `title` | string | No | Yes | | Tooltip and accessible-label fallback. |\n| `selected` | boolean | No | Yes | | Render the icon in its selected visual state. |\n| `active` | boolean | No | Yes | | Render the icon in its active visual state. |\n| `pressed` | boolean | No | Yes | | Expose pressed state and render the selected icon style. |\n| `onclick` | write-expression | No | No | | Write expression invoked when the button is clicked. |\n", "hash": "cf794d03" }, { "id": "components/callout", "group": "Components", "title": "Callout", "summary": "Highlighted contextual message.", "href": "/docs/components/callout", "rawHref": "/docs/components/callout.md", "sourcePath": "site/content/components/callout/en-US.md", "body": "---\ntitle: \"Callout\"\ncategory: Content\nstatus: ready\norder: 40\nsummary: \"Highlighted contextual message for notes, warnings, and tips.\"\n---\n# Callout\n\nProminent notice block with title, body text, and semantic tone.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_callout_typical\",\n \"layout\": {\n \"callout:notice\": {\n \"tone\": \"info\",\n \"title\": \"Notice\",\n \"icon\": \"info\",\n \"text\": \"Use callout for information that should stand out.\"\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for operation instructions, caution warnings, success prompts, and informational messages.\n- Not suitable for pure status labels (use `badge`) or interactive content that needs its own flow.\n- Related components: `badge` for compact labels, `toast` for transient feedback.\n- Child components can be nested inside a callout to extend the body area.\n- Use `tone` only for semantic state, not as an arbitrary style picker.\n\n### Tone variants\n\n```slex\n{\n namespace: \"doc_callout_tone_diff\",\n layout: {\n \"column:tones\": {\n \"callout:info\": {\n tone: \"info\",\n title: \"Info\",\n text: \"This is an informational message.\"\n },\n \"callout:success\": {\n tone: \"success\",\n title: \"Success\",\n text: \"Operation completed successfully.\"\n },\n \"callout:warning\": {\n tone: \"warning\",\n title: \"Warning\",\n text: \"Please review before proceeding.\"\n },\n \"callout:danger\": {\n tone: \"danger\",\n title: \"Danger\",\n text: \"This action cannot be undone.\"\n }\n }\n }\n}\n```\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `title` | string | No | Yes | | Callout title. |\n| `heading` | string | No | Yes | | Alias for title. |\n| `label` | string | No | Yes | | Alias for title. |\n| `icon` | string | No | No | | Icon name shown before the title. |\n| `text` | string | No | Yes | | Callout body text. |\n| `message` | string | No | Yes | | Alias for text. |\n| `content` | string | No | Yes | | Alias for text. |\n| `tone` | string: info, success, warning, danger | No | No | `\"info\"` | Semantic tone for the callout. |\n| child components | object | No | No | | Nested component fields are rendered as child content in field order. |\n", "hash": "4cf1b5a5" }, { "id": "components/card", "group": "Components", "title": "Card", "summary": "Grouping container for related content.", "href": "/docs/components/card", "rawHref": "/docs/components/card.md", "sourcePath": "site/content/components/card/en-US.md", "body": "---\ntitle: \"Card\"\ncategory: Layout\nstatus: ready\norder: 50\nsummary: \"Grouping container for related content.\"\n---\n# Card\n\nCard-style container with optional title and semantic tone.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_card_typical\",\n \"layout\": {\n \"card:metrics\": {\n \"title\": \"Metrics\",\n \"icon\": \"chart-bar\",\n \"grid:items\": {\n \"columns\": 2,\n \"stat:requests\": {\n \"label\": \"Requests\",\n \"value\": \"1.2k\",\n \"unit\": \"/min\"\n },\n \"stat:latency\": {\n \"label\": \"Latency\",\n \"value\": \"42\",\n \"unit\": \"ms\"\n }\n }\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for grouped metrics, settings blocks, and information summaries.\n- Not suitable for page-level section headers (use `section`) or pure layout containers (use `column` or `grid`).\n- Related components: `section` provides a complete page block structure (title + subtitle + action), while `card` is more lightweight.\n- Child components arrange naturally inside a card; nest `row`, `column`, or `grid`.\n- Use `tone` only for semantic state, not as an arbitrary style picker.\n\n### Tone variants\n\n```slex\n{\n namespace: \"doc_card_tone_diff\",\n layout: {\n \"row:tones\": {\n \"card:info\": {\n title: \"Info\",\n tone: \"info\",\n \"text:body\": {\n text: \"Information card.\"\n }\n },\n \"card:success\": {\n title: \"Success\",\n tone: \"success\",\n \"text:body\": {\n text: \"Success card.\"\n }\n },\n \"card:warning\": {\n title: \"Warning\",\n tone: \"warning\",\n \"text:body\": {\n text: \"Warning card.\"\n }\n }\n }\n }\n}\n```\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `title` | string | No | Yes | | Card title. |\n| `icon` | string | No | No | | Icon name shown before the title. |\n| `tone` | string: info, success, warning, danger, muted | No | No | | Optional semantic tone for the card surface. |\n| `variant` | string: tool | No | No | | Use tool for ToolHost input cards with compact chrome. |\n| child components | object | No | No | | Nested component fields are rendered as child content in field order. |\n", "hash": "d27a7e63" }, { "id": "components/checkbox", "group": "Components", "title": "Checkbox", "summary": "Boolean checkbox input.", "href": "/docs/components/checkbox", "rawHref": "/docs/components/checkbox.md", "sourcePath": "site/content/components/checkbox/en-US.md", "body": "---\ntitle: \"Checkbox\"\ncategory: Input\nstatus: ready\norder: 30\nsummary: \"Boolean checkbox for confirmations and multi-select.\"\n---\n# Checkbox\n\nBoolean toggle for confirmation or multi-select scenarios.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_checkbox_typical\",\n \"layout\": {\n \"checkbox:agree\": {\n \"checked\": true,\n \"label\": \"I agree\",\n \"icon\": \"handshake\"\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for terms agreement, multi-select settings, and per-item enable/disable.\n- Not suitable for instant-activation toggles (use `switch`) or mutually exclusive options (use `radio-group`).\n- Related components: `switch` for instant effect toggles, `radio-group` for exclusive options.\n- Multiple options are typically arranged vertically inside a `column`.\n- Use `$checked` and `onchange` for state binding.\n\n### Checked / disabled states\n\n```slex\n{\n namespace: \"doc_checkbox_state_diff\",\n layout: {\n \"column:diff\": {\n \"checkbox:checked\": {\n label: \"Checked\",\n checked: true\n },\n \"checkbox:unchecked\": {\n label: \"Unchecked\"\n },\n \"checkbox:disabled-checked\": {\n label: \"Disabled checked\",\n checked: true,\n disabled: true\n },\n \"checkbox:disabled\": {\n label: \"Disabled\",\n disabled: true\n }\n }\n }\n}\n```\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `checked` | boolean | No | Yes | `false` | Checked state. |\n| `label` | string | No | Yes | | Checkbox label. |\n| `icon` | string | No | No | | Icon name shown before the visible label. |\n| `disabled` | boolean | No | Yes | `false` | Disable the checkbox. |\n| `haptic` | boolean | No | No | `true` | Enable vibration feedback on supported devices. |\n| `haptics` | boolean | No | No | `true` | Alias for haptic. |\n| `onchange` | write-expression | No | No | | Write expression invoked when checked state changes. |\n", "hash": "2a5fedb7" }, { "id": "components/code-block", "group": "Components", "title": "Code Block", "summary": "Formatted code or log block.", "href": "/docs/components/code-block", "rawHref": "/docs/components/code-block.md", "sourcePath": "site/content/components/code-block/en-US.md", "body": "---\ntitle: \"Code Block\"\ncategory: Content\nstatus: ready\norder: 50\nsummary: \"Code or configuration snippet display.\"\n---\n# Code Block\n\nDisplay code, configuration, or source snippets with a language label and optional title.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_code_block_typical\",\n \"layout\": {\n \"code-block:config\": {\n \"title\": \"Config\",\n \"icon\": \"code\",\n \"language\": \"js\",\n \"code\": \"export const enabled = true;\"\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for code samples, JSON config, CLI snippets, and log output.\n- Not suitable for runnable SlexKit examples (use `slex` fence or `playground`).\n- Related components: `playground` for editable interactive previews.\n- Code content is display-only; editing is not supported.\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `code` | string | No | Yes | | Code text content. |\n| `source` | string | No | Yes | | Alias for code. |\n| `content` | string | No | Yes | | Alias for code. |\n| `language` | string | No | No | | Language label. |\n| `title` | string | No | No | | Code block title. |\n| `icon` | string | No | No | | Icon name shown before the title. |\n| `lineNumbers` | boolean | No | No | `true` | Show line numbers. |\n", "hash": "91ed4e50" }, { "id": "components/collapsible", "group": "Components", "title": "Collapsible", "summary": "Single expandable region.", "href": "/docs/components/collapsible", "rawHref": "/docs/components/collapsible.md", "sourcePath": "site/content/components/collapsible/en-US.md", "body": "---\ntitle: \"Collapsible\"\ncategory: Disclosure\nstatus: ready\norder: 20\nsummary: \"Single expandable content area.\"\n---\n# Collapsible\n\nManages a single expand/collapse region for supplementary details or secondary information.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_collapsible_typical\",\n \"layout\": {\n \"collapsible:more\": {\n \"open\": true,\n \"trigger\": \"Details\",\n \"icon\": \"caret-circle-down\",\n \"content\": \"This secondary content can be collapsed.\"\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for expandable details, supplementary notes, and collapsible secondary info.\n- Not suitable for multi-panel lists (use `accordion`).\n- Related components: `accordion` for multi-panel collapse.\n- Child components extend the default body content area.\n- Use `$value` and `onchange` for controlled expansion.\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `open` | boolean | No | Yes | `false` | Expanded state. |\n| `trigger` | string | No | Yes | | Trigger button text. |\n| `icon` | string | No | No | | Icon name shown before trigger text. |\n| `content` | string | No | Yes | | Static body content. |\n| `onchange` | write-expression | No | No | | Write expression invoked when open state changes. |\n| child components | object | No | No | | Nested component fields are rendered as child content in field order. |\n", "hash": "3e81e611" }, { "id": "components/column", "group": "Components", "title": "Column", "summary": "Vertical layout container.", "href": "/docs/components/column", "rawHref": "/docs/components/column.md", "sourcePath": "site/content/components/column/en-US.md", "body": "---\ntitle: \"Column\"\ncategory: Layout\nstatus: ready\norder: 20\nsummary: \"Vertical layout container for forms, text, and control groups.\"\n---\n# Column\n\nBasic vertical layout container.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_column_typical\",\n \"layout\": {\n \"column:form\": {\n \"input:name\": {\n \"placeholder\": \"Name\"\n },\n \"input:email\": {\n \"placeholder\": \"Email\"\n },\n \"button:save\": {\n \"label\": \"Save\"\n }\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for form field groups, settings panels, description text, and sequences of actions.\n- Not suitable for horizontal layouts (use `row`) or equal-width card grids (use `grid`).\n- Related components: `row` for horizontal layout, `grid` for two-dimensional equal-width layout.\n- Place child components as fields, stacked top-to-bottom.\n- Default width fills the parent container; height is content-driven.\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| child components | object | No | No | | Nested component fields are rendered as child content in field order. |\n", "hash": "07c93372" }, { "id": "components/divider", "group": "Components", "title": "Divider", "summary": "Visual separator.", "href": "/docs/components/divider", "rawHref": "/docs/components/divider.md", "sourcePath": "site/content/components/divider/en-US.md", "body": "---\ntitle: \"Divider\"\ncategory: Content\nstatus: ready\norder: 35\nsummary: \"Separator line, optionally with label.\"\n---\n# Divider\n\nHorizontal separator, optionally with a centered text label.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_divider_typical\",\n \"layout\": {\n \"column:content\": {\n \"text:top\": {\n \"text\": \"Above\"\n },\n \"divider:line\": {\n \"label\": \"Divider\",\n \"icon\": \"flag\"\n },\n \"text:bottom\": {\n \"text\": \"Below\"\n }\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for form sections, settings groups, and visual separation between content paragraphs.\n- Not suitable as a spacing mechanism (use layout container `gap`).\n- Related components: `section` for more structured block separation.\n- Place inside a `column` to separate upper and lower content areas.\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `label` | string | No | Yes | | Text shown in the divider. |\n| `icon` | string | No | No | | Icon name shown before the label. |\n", "hash": "8e8e2811" }, { "id": "components/formula", "group": "Components", "title": "Formula", "summary": "Reactive KaTeX formula display.", "href": "/docs/components/formula", "rawHref": "/docs/components/formula.md", "sourcePath": "site/content/components/formula/en-US.md", "body": "---\ntitle: \"Formula\"\ncategory: Display\nstatus: ready\norder: 11\nsummary: \"Reactive KaTeX formula display.\"\n---\n# Formula\n\nRender SlexKit state and computed values through KaTeX. Use it when Markdown explains the model and the interactive block needs the formula itself to update.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_formula_typical\",\n \"g\": {\n \"r\": 10000,\n \"c\": 100,\n \"fc\": 159.15\n },\n \"layout\": {\n \"formula:cutoff\": {\n \"$tex\": \"'f_c = \\\\\\\\frac{1}{2\\\\\\\\pi RC} = ' + g.fc + '\\\\\\\\text{ Hz}'\"\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for formulas whose variables come from SlexKit state.\n- Keep the explanatory derivation in Markdown and use `formula` for the live expression.\n- Use `displayMode: false` for inline formula fragments.\n- Invalid TeX is rendered by KaTeX as an error expression instead of throwing.\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `tex` | string | No | Yes | | KaTeX source to render. |\n| `formula` | string | No | Yes | | Alias for tex. |\n| `value` | string | No | Yes | | Alias for tex. |\n| `displayMode` | boolean | No | No | `true` | Render as display math when true; inline math when false. |\n| `display` | boolean | No | No | `true` | Alias for displayMode. |\n| `block` | boolean | No | No | `true` | Alias for displayMode. |\n", "hash": "e2634f4f" }, { "id": "components/grid", "group": "Components", "title": "Grid", "summary": "Responsive grid container.", "href": "/docs/components/grid", "rawHref": "/docs/components/grid.md", "sourcePath": "site/content/components/grid/en-US.md", "body": "---\ntitle: \"Grid\"\ncategory: Layout\nstatus: ready\norder: 40\nsummary: \"Responsive equal-width grid for sibling cards, metrics, and field groups.\"\n---\n# Grid\n\nResponsive equal-width column layout with breakpoint-prefixed column count.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_grid_typical\",\n \"layout\": {\n \"grid:stats\": {\n \"columns\": 1,\n \"mdColumns\": 3,\n \"stat:a\": {\n \"label\": \"Requests\",\n \"value\": \"1.2k\"\n },\n \"stat:b\": {\n \"label\": \"Success\",\n \"value\": \"98%\"\n },\n \"stat:c\": {\n \"label\": \"Errors\",\n \"value\": \"3\"\n }\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for metric dashboards, card lists, and horizontal equal-width groups of form fields.\n- Not suitable for mixed-width layouts (use `row` + `column` combinations) or single-column arrangements (use `column`).\n- Related components: `row` for horizontal layout without equal-width guarantees, `column` for vertical layout.\n- Child components are automatically equal-width — best for same-level content.\n- Use `gap` to override the spacing; when omitted, the grid keeps its theme CSS default.\n\n### Column variants\n\n```slex\n{\n namespace: \"doc_grid_columns_diff\",\n layout: {\n \"column:demo\": {\n \"text:cols2\": {\n text: \"columns: 2\"\n },\n \"grid:cols2\": {\n columns: 2,\n \"stat:a\": {\n label: \"A\",\n value: \"1\"\n },\n \"stat:b\": {\n label: \"B\",\n value: \"2\"\n },\n \"stat:c\": {\n label: \"C\",\n value: \"3\"\n }\n },\n \"text:cols3\": {\n text: \"columns: 3\"\n },\n \"grid:cols3\": {\n columns: 3,\n \"stat:a\": {\n label: \"A\",\n value: \"1\"\n },\n \"stat:b\": {\n label: \"B\",\n value: \"2\"\n },\n \"stat:c\": {\n label: \"C\",\n value: \"3\"\n }\n }\n }\n }\n}\n```\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `columns` | number | No | Yes | `1` | Base column count. |\n| `smColumns` | number | No | Yes | | Column count at the small breakpoint. |\n| `mdColumns` | number | No | Yes | | Column count at the medium breakpoint. |\n| `lgColumns` | number | No | Yes | | Column count at the large breakpoint. |\n| `xlColumns` | number | No | Yes | | Column count at the extra-large breakpoint. |\n| `gap` | string | No | Yes | | Spacing between grid items. |\n| child components | object | No | No | | Nested component fields are rendered as child content in field order. |\n", "hash": "bcc17fb2" }, { "id": "components/icon", "group": "Components", "title": "Icon", "summary": "Shared icon field capability.", "href": "/docs/components/icon", "rawHref": "/docs/components/icon.md", "sourcePath": "site/content/components/icon/en-US.md", "body": "---\ntitle: \"Icon\"\ncategory: Component\nstatus: ready\norder: 10\nsummary: \"Shared icon field capability used by all icon-supporting components.\"\n---\n# Icon\n\nIcon is not a standalone layout component — it is a component field capability. Components that support the `icon` field resolve icon names through the global icon manager and place the resulting SVG in their own visual position.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"spec_button_basic\",\n \"layout\": {\n \"button:demo\": {\n \"label\": \"Settings\",\n \"icon\": \"gear-six\",\n \"iconOnly\": true,\n \"variant\": \"ghost\"\n }\n }\n}\n```\n\n\n## Supported components\n\n| Component | Field | Description |\n| --- | --- | --- |\n| accordion | `items[].icon` | Icon before each accordion item trigger label. |\n| badge | `icon` | Icon before the badge text. |\n| button | `icon`, `iconOnly` | Icon before the button label; `iconOnly: true` shows only the icon while still requiring `label`. |\n| callout | `icon` | Icon before the callout title. |\n| card | `icon` | Icon before the card title. |\n| checkbox | `icon` | Icon before the visible checkbox label. |\n| code-block | `icon` | Icon before the code block title. |\n| collapsible | `icon` | Icon before the collapsible trigger text. |\n| divider | `icon` | Icon before the divider label text. |\n| link | `icon` | Icon before the link text. |\n| progress | `icon` | Icon before the progress label. |\n| radio-group | `icon`, `options[].icon` | Icon before the group label and each option label. |\n| section | `icon` | Icon before the section title. |\n| select | `icon`, `options[].icon` | `icon` decorates the top label; `options[].icon` decorates menu options and the selected value. |\n| slider | `icon` | Icon before the slider label. |\n| stat | `icon` | Icon before the metric label. |\n| switch | `icon` | Icon before the visible switch label. |\n| table | `columns[].icon` | Icon before each table column header label. |\n| tabs | `tabs[].icon`, `tabs[].iconOnly` | Icon in each tab trigger; selected tab may request an active variant. |\n| toast | `icon` | Replaces the default left semantic marker with an icon while retaining tone color. |\n\n`playground` internally reuses button for its toolbar actions, so it benefits from the same icon manager, but it does not expose a public `icon` field. `select`'s dropdown arrow is a fixed control indicator; `select.icon` only decorates the top label, not the dropdown arrow.\n\n## Name resolution\n\nUnprefixed icon names default to Iconify's `ph` collection (Phosphor icons).\n\n```slex\n{\n namespace: \"doc_icon_names\",\n layout: {\n \"row:icons\": {\n \"button:chart\": {\n label: \"Chart\",\n icon: \"ChartBar\"\n },\n \"button:copy\": {\n label: \"Copy\",\n icon: \"lucide:copy\",\n variant: \"secondary\"\n },\n \"button:settings\": {\n label: \"Settings\",\n icon: \"gear-six\",\n iconOnly: true,\n variant: \"ghost\"\n }\n }\n }\n}\n```\n\nCommon syntax:\n\n| Syntax | Resolves to |\n| ----------------- | ---------------------------------------- |\n| `ChartBar` | `ph:chart-bar` |\n| `chart-bar` | `ph:chart-bar` |\n| `ph:chart-bar` | Phosphor / Iconify `ph` collection |\n| `lucide:copy` | Iconify `lucide` collection |\n| `brand:logo-mark` | Custom icon registered by the host via `registerIcon` |\n\n## Tabs with icons\n\n```slex\n{\n namespace: \"doc_icon_tabs\",\n layout: {\n \"tabs:main\": {\n value: \"overview\",\n tabs: [\n {\n value: \"overview\",\n label: \"Overview\",\n icon: \"ChartBar\"\n },\n {\n value: \"activity\",\n label: \"Activity\",\n icon: \"pulse\"\n },\n {\n value: \"settings\",\n label: \"Settings\",\n icon: \"Gear\",\n iconOnly: true\n }\n ]\n }\n }\n}\n```\n\n## Label and title icons\n\n```slex\n{\n namespace: \"doc_icon_labels\",\n layout: {\n \"column:demo\": {\n \"callout:notice\": {\n title: \"Notice\",\n icon: \"info\",\n text: \"Title-bearing components can use the same icon field.\"\n },\n \"accordion:faq\": {\n value: \"install\",\n items: [\n {\n value: \"install\",\n label: \"Install\",\n icon: \"download-simple\",\n content: \"Prepare dependencies.\"\n },\n {\n value: \"review\",\n label: \"Review\",\n icon: \"check-circle\",\n content: \"Verify the result.\"\n }\n ]\n },\n \"select:env\": {\n label: \"Environment\",\n icon: \"server\",\n value: \"prod\",\n options: [\n { label: \"Development\", value: \"dev\", icon: \"code\" },\n { label: \"Production\", value: \"prod\", icon: \"rocket-launch\" }\n ]\n },\n \"radio-group:mode\": {\n label: \"Mode\",\n icon: \"sliders-horizontal\",\n value: \"auto\",\n options: [\n { label: \"Auto\", value: \"auto\", icon: \"sparkle\" },\n { label: \"Manual\", value: \"manual\", icon: \"wrench\" }\n ]\n }\n }\n }\n}\n```\n\n## Custom icons\n\nHosts can register their own SVG icons before mounting content. Once registered, all components that support the `icon` field can use them by name.\n\n```js\nimport { registerIcon, registerIcons } from \"slexkit\";\n\nregisterIcon(\n \"brand:logo-mark\",\n '',\n { aliases: [\"logo-mark\"] },\n);\n\nregisterIcons({\n \"status:healthy\":\n '',\n});\n```\n\n## Usage rules\n\n- `iconOnly` is supported on `button` and `tabs` only; titles, labels, and column headers never hide text.\n- `iconOnly` must be paired with `label`, `title`, or `aria-label` — assistive technology needs a readable name.\n- Without a prefix, prefer Phosphor semantic names; use an explicit prefix such as `lucide:copy` for cross-icon-set usage.\n- The runtime does not accept arbitrary URLs as icon sources. Remote icons are fetched via the Iconify API and the returned SVG passes through basic filtering.\n- Bundled icons display synchronously on first paint; unbundled icons load asynchronously. When the network is unavailable, components retain their text content.\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `icon` | string | No | No | | Icon name resolved through the global icon manager. |\n| `iconOnly` | boolean | No | No | | Render only the icon while retaining an accessible label where supported. |\n| `items[].icon` | string | No | No | | Accordion item trigger icon. |\n| `options[].icon` | string | No | No | | Select or radio option icon. |\n| `columns[].icon` | string | No | No | | Table column header icon. |\n| `tabs[].icon` | string | No | No | | Tab trigger icon. |\n| `tabs[].iconOnly` | boolean | No | No | | Tab trigger icon-only mode. |\n", "hash": "3acd3fea" }, { "id": "components/input", "group": "Components", "title": "Input", "summary": "Text or engineering-value input.", "href": "/docs/components/input", "rawHref": "/docs/components/input.md", "sourcePath": "site/content/components/input/en-US.md", "body": "---\ntitle: \"Input\"\ncategory: Input\nstatus: ready\norder: 10\nsummary: \"Single-line text or engineering value input.\"\n---\n# Input\n\nSingle-line text input with controlled value, placeholder, label, description, native types, engineering input, and disabled state.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_input_typical\",\n \"layout\": {\n \"input:name\": {\n \"label\": \"Project\",\n \"value\": \"SlexKit\",\n \"placeholder\": \"Enter name\",\n \"description\": \"Visible labels keep form fields scannable.\"\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for name input, search boxes, email/password, and other single-line text.\n- Use `type: \"engineering\"` for values such as `4.7k`, `2.2uF`, or `1e-3`.\n- Not suitable for numeric range selection (use `slider`).\n- Related components: `select` for option selection, `slider` for numeric ranges.\n- Typically placed inside a `column` to compose forms.\n- Use `$value` and `onchange` for state binding.\n- Numeric and engineering inputs render only the native input. Use `slider` for range adjustment; SlexKit no longer adds custom decrement or increment buttons.\n- `onchange` fires when the user edits the value.\n- `type: \"number\"` still emits a string value. Convert with `Number($event)` or use `type: \"engineering\"` to read parsed results.\n- Use `invalid` plus `error` for validation feedback. Error text is linked through `aria-describedby`.\n\n### Label and unit\n\n`label` renders as a clickable native label; `unit` renders as trailing text, suitable for voltage, resistance, frequency, etc.\n\n```slex\n{\n namespace: \"doc_input_label_unit\",\n layout: {\n \"input:voltage\": {\n label: \"Voltage\",\n value: \"3.3\",\n unit: \"V\",\n description: \"Supply rail\"\n }\n }\n}\n```\n\n### Disabled state\n\n```slex\n{\n namespace: \"doc_input_disabled_diff\",\n layout: {\n \"row:diff\": {\n \"input:enabled\": {\n value: \"Editable\",\n placeholder: \"Type here\"\n },\n \"input:disabled\": {\n value: \"Disabled\",\n disabled: true\n }\n }\n }\n}\n```\n\n### Engineering input\n\n`type: \"engineering\"` uses a text input (not the native number type). Component state retains the raw string and additionally exposes parsed results:\n\n```slex\n{\n namespace: \"doc_input_engineering\",\n layout: {\n \"input:resistance\": {\n type: \"engineering\",\n value: \"4.7kΩ\"\n },\n \"stat:parsed\": {\n label: \"Parsed value\",\n $value: \"resistance.valid ? resistance.number : 'Invalid'\",\n $unit: \"resistance.unit\"\n }\n }\n}\n```\n\nSupports scientific notation and SI prefixes: `p`, `n`, `u`, `µ`, `m`, `k`, `K`, `M`, `meg`, `G`, `T`. Units are captured but not converted across physical dimensions.\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `value` | string | No | Yes | | Current input value. |\n| `label` | string | No | Yes | | Input label. |\n| `unit` | string | No | Yes | | Trailing unit text. |\n| `description` | string | No | Yes | | Assistive description below the input. |\n| `help` | string | No | Yes | | Alias for description. |\n| `hint` | string | No | Yes | | Alias for description. |\n| `error` | string | No | Yes | | Error text shown below the input and linked with aria-describedby. |\n| `errorMessage` | string | No | Yes | | Alias for error. |\n| `invalid` | boolean | No | Yes | `false` | Mark the input as invalid with aria-invalid and error styling. |\n| `placeholder` | string | No | No | | Placeholder text for empty values. |\n| `type` | string | No | No | `\"text\"` | Input value kind; use engineering for parsed engineering values. |\n| `disabled` | boolean | No | Yes | `false` | Disable editing. |\n| `readonly` | boolean | No | Yes | `false` | Make the input read-only. |\n| `readOnly` | boolean | No | Yes | `false` | Alias for readonly. |\n| `required` | boolean | No | Yes | `false` | Mark the input as required. |\n| `id` | string | No | No | | Native input id; defaults to a stable id derived from the component name. |\n| `name` | string | No | No | | Native input name attribute. |\n| `min` | string \\| number | No | Yes | | Minimum value used by numeric input controls. |\n| `max` | string \\| number | No | Yes | | Maximum value used by numeric input controls. |\n| `step` | string \\| number | No | Yes | | Step size used by numeric input controls. |\n| `onchange` | write-expression | No | No | | Write expression invoked when the value changes. |\n", "hash": "7f8d50f2" }, { "id": "components/link", "group": "Components", "title": "Link", "summary": "Inline navigation link.", "href": "/docs/components/link", "rawHref": "/docs/components/link.md", "sourcePath": "site/content/components/link/en-US.md", "body": "---\ntitle: \"Link\"\ncategory: Content\nstatus: ready\norder: 25\nsummary: \"Navigation or lightweight jump action.\"\n---\n# Link\n\nText link navigation.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_link_typical\",\n \"layout\": {\n \"column:links\": {\n \"link:docs\": {\n \"href\": \"/components\",\n \"icon\": \"arrow-square-out\",\n \"text\": \"View components\"\n }\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for page navigation, external links, and inline text links.\n- Not suitable for primary action buttons (use `button`).\n- Related components: `button` for explicit action triggers.\n- Keep link text short.\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `href` | string | No | No | | Target URL. |\n| `text` | string | No | Yes | | Visible link text. |\n| `label` | string | No | Yes | | Alias for text. |\n| `content` | string | No | Yes | | Alias for text. |\n| `icon` | string | No | No | | Icon name shown before link text. |\n| `target` | string | No | No | | Native link target attribute. |\n| `variant` | string: default, muted | No | No | `\"default\"` | Link visual variant. |\n", "hash": "44699ab4" }, { "id": "components/playground", "group": "Components", "title": "Playground", "summary": "Interactive source preview.", "href": "/docs/components/playground", "rawHref": "/docs/components/playground.md", "sourcePath": "site/content/components/playground/en-US.md", "body": "---\ntitle: \"Playground\"\ncategory: Tooling\nstatus: ready\norder: 10\nsummary: \"Interactive preview and editor for SlexKit / Markdown source.\"\n---\n# Playground\n\nInteractive preview component that embeds editable, runnable SlexKit or Markdown source previews inside a page.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_playground_typical\",\n \"layout\": {\n \"playground:demo\": {\n \"title\": \"Stat Playground\",\n \"previewMinHeight\": \"180px\",\n \"source\": {\n \"namespace\": \"inner_stat_demo\",\n \"layout\": {\n \"stat:value\": {\n \"label\": \"Requests\",\n \"value\": \"1.2k\",\n \"unit\": \"/min\"\n }\n }\n }\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for runnable examples in documentation, interactive demos, and source code teaching.\n- Not suitable for ordinary component rendering (use layout components directly).\n- Related components: `code-block` for read-only code display.\n- Nested source is rendered in an isolated scope — it does not conflict with the parent namespace.\n- Use Playground for documentation and teaching surfaces, not product UI.\n- Public fields cover source parsing, preview placement, theme toggle controls, labels, and open/copy URLs.\n- `domain`, `pluginVersion`, and `version` are host integration metadata, not public component fields.\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `source` | object \\| string | No | No | | SlexKit or Markdown source to preview. |\n| `sourceType` | string: slex, markdown, auto-markdown | No | No | `\"slex\"` | Source parser mode. |\n| `title` | string | No | No | | Playground title. |\n| `previewAlign` | string: center, start | No | No | `\"center\"` | Vertical preview alignment in render mode. |\n| `alignPreview` | string: center, start | No | No | | Alias for previewAlign. |\n| `previewPlacement` | string: center, start | No | No | | Alias for previewAlign. |\n| `previewMinHeight` | string | No | No | | Minimum preview area height. |\n| `previewMaxWidth` | string | No | No | | Maximum preview content width. |\n| `themeToggle` | boolean | No | No | `false` | Show the theme toggle action. |\n| `showThemeToggle` | boolean | No | No | `false` | Alias for themeToggle. |\n| `enableThemeToggle` | boolean | No | No | `false` | Alias for themeToggle. |\n| `themeLabel` | string | No | No | | Accessible label for the theme toggle action. |\n| `themeToggleLabel` | string | No | No | | Alias for themeLabel. |\n| `sourceTypeLabel` | string | No | No | | Accessible label for the source type selector. |\n| `copyLabel` | string | No | No | | Accessible label for the copy source action. |\n| `openWebLabel` | string | No | No | | Accessible label for opening the source in the standalone playground. |\n| `webUrl` | string | No | No | | Standalone playground URL used by the open action. |\n| `playgroundUrl` | string | No | No | | Alias for webUrl. |\n", "hash": "1ed71de1" }, { "id": "components/progress", "group": "Components", "title": "Progress", "summary": "Progress bar.", "href": "/docs/components/progress", "rawHref": "/docs/components/progress.md", "sourcePath": "site/content/components/progress/en-US.md", "body": "---\ntitle: \"Progress\"\ncategory: Feedback\nstatus: ready\norder: 10\nsummary: \"Progress bar.\"\n---\n# Progress\n\nDisplay task completion progress controlled by value.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_progress_typical\",\n \"layout\": {\n \"progress:build\": {\n \"label\": \"Build progress\",\n \"icon\": \"gear-six\",\n \"value\": 64\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for build progress, upload progress, and task completion.\n- Not suitable for indeterminate waiting states.\n- Related components: `stat` for numeric metric display.\n- Value range is 0-100.\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `value` | number | No | Yes | `0` | Progress percentage from 0 to 100. |\n| `label` | string | No | Yes | | Progress label. |\n| `icon` | string | No | No | | Icon name shown before the label. |\n| `indeterminate` | boolean | No | Yes | `false` | Render an indeterminate progress state without aria-valuenow. |\n", "hash": "b751fd4e" }, { "id": "components/radio-group", "group": "Components", "title": "Radio Group", "summary": "Single-choice option group.", "href": "/docs/components/radio-group", "rawHref": "/docs/components/radio-group.md", "sourcePath": "site/content/components/radio-group/en-US.md", "body": "---\ntitle: \"Radio Group\"\ncategory: Input\nstatus: ready\norder: 70\nsummary: \"Mutually exclusive radio selection.\"\n---\n# Radio Group\n\nMutually exclusive option selection for small choice sets.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_radio_group_typical\",\n \"layout\": {\n \"radio-group:mode\": {\n \"label\": \"Mode\",\n \"icon\": \"sliders-horizontal\",\n \"value\": \"auto\",\n \"options\": [\n {\n \"label\": \"Auto\",\n \"value\": \"auto\",\n \"icon\": \"sparkle\"\n },\n {\n \"label\": \"Manual\",\n \"value\": \"manual\",\n \"icon\": \"wrench\"\n }\n ]\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for mode selection, small enum choices, and mutually exclusive config items.\n- Not suitable for many options (use `select`).\n- Related components: `select` for dropdown single selection with more options.\n- Keep options between 2-5 items.\n- Use `$value` and `onchange` for state binding.\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `value` | string | No | Yes | | Current selected value. |\n| `label` | string | No | Yes | | Group label. |\n| `icon` | string | No | No | | Icon name shown before the group label. |\n| `options` | array | No | No | | Options with label, value, and optional icon. |\n| `options[].icon` | string | No | No | | Icon name shown before a single option label. |\n| `options[].description` | string | No | No | | Secondary text shown below the option label. |\n| `disabled` | boolean | No | Yes | `false` | Disable every radio option in the group. |\n| `orientation` | string: vertical, horizontal | No | No | `\"vertical\"` | Radio option layout direction. |\n| `variant` | string: list | No | No | | Use list for full-row option surfaces in ToolHost decision cards. |\n| `haptic` | boolean | No | No | `true` | Enable vibration feedback on supported devices. |\n| `haptics` | boolean | No | No | `true` | Alias for haptic. |\n| `name` | string | No | No | | Native radio group name shared by options. |\n| `onchange` | write-expression | No | No | | Write expression invoked when selection changes. |\n", "hash": "c212d43a" }, { "id": "components/row", "group": "Components", "title": "Row", "summary": "Horizontal layout container.", "href": "/docs/components/row", "rawHref": "/docs/components/row.md", "sourcePath": "site/content/components/row/en-US.md", "body": "---\ntitle: \"Row\"\ncategory: Layout\nstatus: ready\norder: 30\nsummary: \"Horizontal layout container for toolbars, status lines, and button groups.\"\n---\n# Row\n\nBasic horizontal layout container.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_row_typical\",\n \"layout\": {\n \"row:toolbar\": {\n \"justify\": \"space-between\",\n \"text:title\": {\n \"text\": \"Runtime status\"\n },\n \"button:refresh\": {\n \"label\": \"Refresh\"\n }\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for button groups, toolbars, status indicator lines, and table header actions.\n- Not suitable for vertical form fields (use `column`) or equal-width card grids (use `grid`).\n- Related components: `column` for vertical layout, `grid` for two-dimensional equal-width layout.\n- Children arrange at natural width; use `justify` to control distribution.\n- Use `gap` to override the spacing between children; when omitted, the row keeps its theme CSS default.\n\n### Justify variants\n\n```slex\n{\n namespace: \"doc_row_justify_diff\",\n layout: {\n \"column:demo\": {\n \"text:start\": {\n text: \"justify: start\"\n },\n \"row:justify-start\": {\n justify: \"start\",\n \"badge:a\": {\n label: \"A\"\n },\n \"badge:b\": {\n label: \"B\"\n }\n },\n \"text:center\": {\n text: \"justify: center\"\n },\n \"row:justify-center\": {\n justify: \"center\",\n \"badge:a\": {\n label: \"A\"\n },\n \"badge:b\": {\n label: \"B\"\n }\n },\n \"text:end\": {\n text: \"justify: end\"\n },\n \"row:justify-end\": {\n justify: \"end\",\n \"badge:a\": {\n label: \"A\"\n },\n \"badge:b\": {\n label: \"B\"\n }\n },\n \"text:space-between\": {\n text: \"justify: space-between\"\n },\n \"row:justify-between\": {\n justify: \"space-between\",\n \"badge:a\": {\n label: \"A\"\n },\n \"badge:b\": {\n label: \"B\"\n }\n }\n }\n }\n}\n```\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `justify` | string: start, center, end, space-between, space-around | No | No | `\"start\"` | Main-axis distribution. |\n| `align` | string: start, center, end, baseline, stretch | No | No | `\"center\"` | Cross-axis alignment. |\n| `gap` | string | No | Yes | | Spacing between children. |\n| `variant` | string: actions | No | No | | Use actions for compact ToolHost action rows. |\n| child components | object | No | No | | Nested component fields are rendered as child content in field order. |\n", "hash": "520a712d" }, { "id": "components/section", "group": "Components", "title": "Section", "summary": "Page section with optional heading chrome.", "href": "/docs/components/section", "rawHref": "/docs/components/section.md", "sourcePath": "site/content/components/section/en-US.md", "body": "---\ntitle: \"Section\"\ncategory: Layout\nstatus: ready\norder: 60\nsummary: \"Page section with title, subtitle, optional action, and content area.\"\n---\n# Section\n\nPage-level block container with title, subtitle, optional action link, and content area.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_section_typical\",\n \"layout\": {\n \"section:overview\": {\n \"eyebrow\": \"Dashboard\",\n \"title\": \"Runtime overview\",\n \"icon\": \"chart-bar\",\n \"subtitle\": \"This section groups the most important state.\",\n \"stat:latency\": {\n \"label\": \"Latency\",\n \"value\": \"42\",\n \"unit\": \"ms\"\n }\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for dashboard blocks, settings groups, and categorized content areas.\n- Not suitable for purely visual cards (use `card`) or untitled containers (use `column`).\n- Related components: `card` is a lighter grouping container, while `section` provides a more complete heading structure.\n- The heading area and content area are distinct; nest any layout component inside the content area.\n\n### Eyebrow / subtitle variants\n\n```slex\n{\n namespace: \"doc_section_eyebrow_diff\",\n layout: {\n \"column:demo\": {\n \"section:with-eyebrow\": {\n eyebrow: \"Overview\",\n title: \"With eyebrow\",\n \"text:body\": {\n text: \"Eyebrow appears above the title.\"\n }\n },\n \"section:with-subtitle\": {\n title: \"With subtitle\",\n subtitle: \"Additional context below the title.\",\n \"text:body\": {\n text: \"Subtitle provides extra context.\"\n }\n }\n }\n }\n}\n```\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `title` | string | No | Yes | | Section title. |\n| `icon` | string | No | No | | Icon name shown before the title. |\n| `eyebrow` | string | No | Yes | | Small label above the title. |\n| `subtitle` | string | No | Yes | | Subtitle text below the title. |\n| `actionLabel` | string | No | Yes | | Optional action link label. |\n| `actionHref` | string | No | No | | Optional action link target. |\n| child components | object | No | No | | Nested component fields are rendered as child content in field order. |\n", "hash": "ef71717e" }, { "id": "components/select", "group": "Components", "title": "Select", "summary": "Dropdown selection input.", "href": "/docs/components/select", "rawHref": "/docs/components/select.md", "sourcePath": "site/content/components/select/en-US.md", "body": "---\ntitle: \"Select\"\ncategory: Input\nstatus: ready\norder: 20\nsummary: \"Single-select dropdown.\"\n---\n# Select\n\nSingle-select dropdown with options defined as an array and the current value controlled via value.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_select_typical\",\n \"layout\": {\n \"select:env\": {\n \"label\": \"Environment\",\n \"icon\": \"server\",\n \"value\": \"prod\",\n \"options\": [\n {\n \"label\": \"Development\",\n \"value\": \"dev\",\n \"icon\": \"code\"\n },\n {\n \"label\": \"Production\",\n \"value\": \"prod\",\n \"icon\": \"rocket-launch\"\n }\n ]\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for enum selection, config items, and environment choice.\n- Not suitable for small mutually exclusive groups (use `radio-group`).\n- Related components: `radio-group` for smaller option sets.\n- Combine with `column` to compose forms.\n- Use `$value` and `onchange` for state binding.\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `label` | string | No | Yes | | Select label. |\n| `icon` | string | No | No | | Icon name shown before the top label. |\n| `value` | string | No | Yes | | Current selected value. |\n| `options` | array | No | No | | Options with label, value, and optional icon. |\n| `options[].icon` | string | No | No | | Icon name shown before an option label. |\n| `placeholder` | string | No | No | | Placeholder shown when no value is selected. |\n| `disabled` | boolean | No | Yes | `false` | Disable the select trigger and native select. |\n| `required` | boolean | No | Yes | `false` | Require a non-placeholder value in the native select. |\n| `variant` | string: default, toolbar | No | No | `\"default\"` | Select surface variant. |\n| `onchange` | write-expression | No | No | | Write expression invoked when selection changes. |\n", "hash": "ec31def5" }, { "id": "components/slider", "group": "Components", "title": "Slider", "summary": "Numeric range input.", "href": "/docs/components/slider", "rawHref": "/docs/components/slider.md", "sourcePath": "site/content/components/slider/en-US.md", "body": "---\ntitle: \"Slider\"\ncategory: Input\nstatus: ready\norder: 60\nsummary: \"Numeric range input.\"\n---\n# Slider\n\nNumeric range selection with min, max, step control and unit display.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_slider_typical\",\n \"layout\": {\n \"slider:volume\": {\n \"label\": \"Volume\",\n \"icon\": \"speaker-high\",\n \"value\": 42,\n \"min\": 0,\n \"max\": 100,\n \"step\": 1,\n \"unit\": \"%\"\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for volume, brightness, threshold, and percentage adjustments.\n- Not suitable for precise text entry (use `input`).\n- Related components: `input` for text input.\n- Use `$value` and `onchange` for state binding.\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `label` | string | No | Yes | | Slider label. |\n| `icon` | string | No | No | | Icon name shown before the label. |\n| `value` | number | No | Yes | `0` | Current numeric value. |\n| `min` | number | No | Yes | `0` | Minimum value. |\n| `max` | number | No | Yes | `100` | Maximum value. |\n| `step` | number | No | Yes | `1` | Step interval. |\n| `unit` | string | No | Yes | | Unit shown after the value. |\n| `disabled` | boolean | No | Yes | `false` | Disable the range input. |\n| `orientation` | string: horizontal, vertical | No | No | `\"horizontal\"` | Slider orientation metadata used for styling. |\n| `haptic` | boolean | No | No | `true` | Enable vibration feedback on supported devices. |\n| `haptics` | boolean | No | No | `true` | Alias for haptic. |\n| `onchange` | write-expression | No | No | | Write expression invoked when the value changes. |\n", "hash": "e2775052" }, { "id": "components/stat", "group": "Components", "title": "Stat", "summary": "Metric display.", "href": "/docs/components/stat", "rawHref": "/docs/components/stat.md", "sourcePath": "site/content/components/stat/en-US.md", "body": "---\ntitle: \"Stat\"\ncategory: Display\nstatus: ready\norder: 10\nsummary: \"Metric display with label, value, unit, and semantic tone.\"\n---\n# Stat\n\nPresent a labeled metric value with optional unit and semantic tone.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_stat_typical\",\n \"layout\": {\n \"grid:stats\": {\n \"columns\": 2,\n \"stat:requests\": {\n \"label\": \"Requests\",\n \"icon\": \"activity\",\n \"value\": \"1.2k\",\n \"unit\": \"/min\"\n },\n \"stat:success\": {\n \"label\": \"Success\",\n \"icon\": \"check-circle\",\n \"value\": \"98.4\",\n \"unit\": \"%\",\n \"tone\": \"success\"\n }\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for data dashboards, metric overviews, and key indicator displays.\n- Not suitable for long text (use `text`) or interactive input (use `input`).\n- Related components: `text` for text output, `badge` for label status.\n- Stats are typically used inside a `grid` or `row`.\n- Use `tone` only for semantic state, not as an arbitrary style picker.\n\n### Tone variants\n\n```slex\n{\n namespace: \"doc_stat_tone_diff\",\n layout: {\n \"row:tones\": {\n \"stat:info\": {\n label: \"Info\",\n value: \"42\",\n tone: \"info\"\n },\n \"stat:success\": {\n label: \"Success\",\n value: \"98%\",\n tone: \"success\"\n },\n \"stat:warning\": {\n label: \"Warning\",\n value: \"73\",\n tone: \"warning\"\n },\n \"stat:danger\": {\n label: \"Danger\",\n value: \"5\",\n tone: \"danger\"\n },\n \"stat:muted\": {\n label: \"Muted\",\n value: \"0\",\n tone: \"muted\"\n }\n }\n }\n}\n```\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `label` | string | No | Yes | | Metric label. |\n| `icon` | string | No | No | | Icon name shown before the label. |\n| `value` | string \\| number | No | Yes | | Metric value. |\n| `unit` | string | No | Yes | | Unit shown after the value. |\n| `tone` | string: info, success, warning, danger, muted | No | No | | Optional semantic tone. |\n| `animateInitial` | boolean | No | No | `false` | Animate the initial rendered value. |\n", "hash": "1e2d909d" }, { "id": "components/switch", "group": "Components", "title": "Switch", "summary": "Boolean switch input.", "href": "/docs/components/switch", "rawHref": "/docs/components/switch.md", "sourcePath": "site/content/components/switch/en-US.md", "body": "---\ntitle: \"Switch\"\ncategory: Input\nstatus: ready\norder: 40\nsummary: \"Boolean toggle input for instant settings.\"\n---\n# Switch\n\nBoolean toggle for instant-activation settings.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_switch_typical\",\n \"layout\": {\n \"switch:feature\": {\n \"enabled\": true,\n \"label\": \"Enable sync\",\n \"icon\": \"arrows-clockwise\"\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for feature toggles, preference enable/disable, and instant-effect settings.\n- Not suitable for confirmation-style toggles (use `checkbox`).\n- Related components: `checkbox` for confirmations or multi-select.\n- Typically placed inside a `row` or `column`.\n- Use `$enabled` and `onchange` for state binding.\n\n### Enabled / disabled variants\n\n```slex\n{\n namespace: \"doc_switch_state_diff\",\n layout: {\n \"row:diff\": {\n \"switch:enabled\": {\n label: \"Enabled\",\n enabled: true\n },\n \"switch:disabled\": {\n label: \"Disabled\"\n },\n \"switch:enabled-not-available\": {\n label: \"Enabled (not available)\",\n enabled: true,\n disabled: true\n },\n \"switch:disabled-not-available\": {\n label: \"Disabled (not available)\",\n disabled: true\n }\n }\n }\n}\n```\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `enabled` | boolean | No | Yes | `false` | Enabled state. |\n| `label` | string | No | Yes | | Switch label. |\n| `icon` | string | No | No | | Icon name shown before the visible label. |\n| `disabled` | boolean | No | Yes | `false` | Disable the switch. |\n| `haptic` | boolean | No | No | `true` | Enable vibration feedback on supported devices. |\n| `haptics` | boolean | No | No | `true` | Alias for haptic. |\n| `onchange` | write-expression | No | No | | Write expression invoked when enabled state changes. |\n", "hash": "00350940" }, { "id": "components/table", "group": "Components", "title": "Table", "summary": "Simple data table.", "href": "/docs/components/table", "rawHref": "/docs/components/table.md", "sourcePath": "site/content/components/table/en-US.md", "body": "---\ntitle: \"Table\"\ncategory: Data\nstatus: ready\norder: 10\nsummary: \"Structured table with columns and rows.\"\n---\n# Table\n\nStructured row-column data display with column headers and data rows.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_table_typical\",\n \"layout\": {\n \"table:routes\": {\n \"columns\": [\n {\n \"key\": \"name\",\n \"label\": \"Name\",\n \"icon\": \"text-t\"\n },\n {\n \"key\": \"status\",\n \"label\": \"Status\",\n \"icon\": \"check-circle\"\n }\n ],\n \"rows\": [\n {\n \"name\": \"Parse\",\n \"status\": \"ready\"\n },\n {\n \"name\": \"Publish\",\n \"status\": \"pending\"\n }\n ]\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for data lists, configuration tables, and structured information display.\n- Not suitable for card-style layouts (use `grid`).\n- Related components: `grid` for equal-width card layouts.\n- Column `key` values correspond to field names in each row.\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `columns` | array | No | No | | Column definitions with key, label, and optional icon. |\n| `columns[].icon` | string | No | No | | Icon name shown before a column label. |\n| `rows` | array | No | No | | Row data objects keyed by column key. |\n| `items` | array | No | No | | Alias for rows. |\n", "hash": "04a3e110" }, { "id": "components/tabs", "group": "Components", "title": "Tabs", "summary": "Tabbed view switcher.", "href": "/docs/components/tabs", "rawHref": "/docs/components/tabs.md", "sourcePath": "site/content/components/tabs/en-US.md", "body": "---\ntitle: \"Tabs\"\ncategory: Navigation\nstatus: ready\norder: 10\nsummary: \"Tabbed view switcher.\"\n---\n# Tabs\n\nSwitch between named content panels.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_tabs_typical\",\n \"layout\": {\n \"tabs:main\": {\n \"value\": \"overview\",\n \"tabs\": [\n {\n \"value\": \"overview\",\n \"label\": \"Overview\"\n },\n {\n \"value\": \"settings\",\n \"label\": \"Settings\"\n }\n ]\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for settings panel sections, content category switching, and configuration groups.\n- Not suitable for multi-page wizards — use explicit page state and navigation.\n- Related components: `button` for submit actions, `link` for cross-page navigation.\n- Use `$value` and `onchange` for controlled switching.\n\n### Orientation variants\n\n```slex\n{\n namespace: \"doc_tabs_orientation_diff\",\n layout: {\n \"row:orientations\": {\n \"column:h\": {\n \"text:horiz\": {\n text: \"horizontal (default)\"\n },\n \"tabs:horizontal\": {\n value: \"a\",\n orientation: \"horizontal\",\n tabs: [\n {\n value: \"a\",\n label: \"Tab A\"\n },\n {\n value: \"b\",\n label: \"Tab B\"\n }\n ]\n }\n },\n \"column:v\": {\n \"text:vert\": {\n text: \"vertical\"\n },\n \"tabs:vertical\": {\n value: \"a\",\n orientation: \"vertical\",\n tabs: [\n {\n value: \"a\",\n label: \"Tab A\"\n },\n {\n value: \"b\",\n label: \"Tab B\"\n }\n ]\n }\n }\n }\n }\n}\n```\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `value` | string | No | Yes | | Current active tab value. |\n| `tabs` | array | No | No | | Tab definitions with value, label, content, icon, and iconOnly. |\n| `tabs[].icon` | string | No | No | | Icon name shown before a tab trigger label. |\n| `tabs[].iconOnly` | boolean | No | No | | Show only the tab icon while retaining label as accessible text. |\n| `orientation` | string: horizontal, vertical | No | No | `\"horizontal\"` | Tab list orientation. |\n| `onchange` | write-expression | No | No | | Write expression invoked when the active tab changes. |\n", "hash": "a21ec3e7" }, { "id": "components/text", "group": "Components", "title": "Text", "summary": "Plain text display.", "href": "/docs/components/text", "rawHref": "/docs/components/text.md", "sourcePath": "site/content/components/text/en-US.md", "body": "---\ntitle: \"Text\"\ncategory: Display\nstatus: ready\norder: 20\nsummary: \"Short text output for status, description, and results.\"\n---\n# Text\n\nOutput text content for status messages, descriptions, and result display.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_text_typical\",\n \"layout\": {\n \"text:status\": {\n \"text\": \"System is healthy\"\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for status text, short descriptions, label values, and lightweight output.\n- Not suitable for long paragraphs or structured data (use `table`).\n- Related components: `stat` for numeric metrics, `badge` for status labels.\n- Keep text short; use multiple `text` nodes for longer content.\n- Typically placed inside `row`, `column`, or `card`.\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `text` | string | No | Yes | | Displayed text. |\n| `content` | string | No | Yes | | Alias for text. |\n| `label` | string | No | Yes | | Alias for text. |\n| `variant` | string: default, muted | No | No | `\"default\"` | Text visual variant. |\n| `color` | string | No | Yes | | Optional CSS color for controlled previews. |\n| `size` | string \\| number | No | Yes | | Optional font size. Numbers are treated as px. |\n| `class` | string | No | No | | Additional host-controlled CSS class. |\n", "hash": "29b8adc2" }, { "id": "components/toast", "group": "Components", "title": "Toast", "summary": "Transient notification.", "href": "/docs/components/toast", "rawHref": "/docs/components/toast.md", "sourcePath": "site/content/components/toast/en-US.md", "body": "---\ntitle: \"Toast\"\ncategory: Feedback\nstatus: ready\norder: 20\nsummary: \"Transient notification with semantic type.\"\n---\n# Toast\n\nInline notification with semantic type and optional icon.\n\n\n```slex\n{\n \"slex\": \"0.1\",\n \"namespace\": \"doc_toast_typical\",\n \"layout\": {\n \"toast:saved\": {\n \"type\": \"success\",\n \"title\": \"Saved\",\n \"icon\": \"check-circle\",\n \"description\": \"Changes have been written.\"\n }\n }\n}\n```\n\n\n## Usage Notes\n\n- Use for save confirmations, operation errors, and status change notifications.\n- Not suitable for messages that require user response or long-term visibility — use an inline form or `callout` instead.\n- Related components: `callout` for in-page prompt blocks, `badge` for compact status.\n- Set `duration` for auto-hide behavior; without it, the toast renders as an inline notification card.\n- Use `type` only for semantic message purpose.\n\n### Type variants\n\n```slex\n{\n namespace: \"doc_toast_type_diff\",\n layout: {\n \"column:types\": {\n \"toast:info\": {\n type: \"info\",\n title: \"Info\",\n description: \"A new update is available.\"\n },\n \"toast:success\": {\n type: \"success\",\n title: \"Success\",\n description: \"Operation completed.\"\n },\n \"toast:warning\": {\n type: \"warning\",\n title: \"Warning\",\n description: \"Review before proceeding.\"\n },\n \"toast:danger\": {\n type: \"danger\",\n title: \"Error\",\n description: \"Something went wrong.\"\n }\n }\n }\n}\n```\n\n## API Reference {#api}\n\n\n| Field | Type | Required | Dynamic | Default | Description |\n|---|---|---|---|---|---|\n| `title` | string | No | Yes | | Toast title. |\n| `heading` | string | No | Yes | | Alias for title. |\n| `label` | string | No | Yes | | Alias for title. |\n| `icon` | string | No | No | | Icon name shown at the left of the toast. |\n| `description` | string | No | Yes | | Toast body text. |\n| `text` | string | No | Yes | | Alias for description. |\n| `message` | string | No | Yes | | Alias for description. |\n| `content` | string | No | Yes | | Alias for description. |\n| `type` | string: info, success, warning, danger | No | No | `\"info\"` | Semantic notification type. |\n| `tone` | string: info, success, warning, danger | No | No | `\"info\"` | Alias for type. |\n| `duration` | number | No | No | | Auto-hide delay in milliseconds. |\n| `dismissable` | boolean | No | No | `true` | Show a close button. |\n| `dismissible` | boolean | No | No | `true` | Alias for dismissable. |\n| `closeLabel` | string | No | No | `\"Close notification\"` | Accessible close button label. |\n| `closeAriaLabel` | string | No | No | | Alias for closeLabel. |\n", "hash": "f8f87dbe" }, { "id": "reference/spec", "group": "Reference", "title": "Slex Specification", "summary": "Public Slex expression envelope, component keys, props, directives, and lifecycle.", "href": "/docs/reference/spec", "rawHref": "/docs/reference/spec.md", "sourcePath": "site/content/reference/spec/en-US.md", "body": "---\ntitle: Slex Specification v0.1\ncategory: Reference\nstatus: ready\norder: 10\nsummary: \"Public Slex expression envelope, component keys, props, directives, lifecycle, and runtime API contract.\"\nslexkitRenderMode: component\n---\n\n# Slex Specification v0.1\n\nSlex 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.\n\n**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.\n\n## 1. Slex expression envelope\n\nThe canonical Slex expression is an object. Slex source is the JavaScript object literal string form of that expression:\n\n```ts\ntype SlexExpression = {\n slex?: \"0.1\";\n namespace: string;\n g: Record;\n layout: Record;\n};\n```\n\n`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:\n\n```js\n{ namespace: \"default\", g: {}, layout: }\n```\n\n## 2. Layout key\n\nComponent keys use the format:\n\n```\nComponentKey = ComponentType \":\" Identifier\n```\n\n- `ComponentType` maps to a type in the component registry.\n- `Identifier` may be empty (e.g. `\"box:\"`).\n- Named components use `Identifier` for instance state and lifecycle hooks.\n- Keys without `:` are not rendered as component nodes.\n\nReserved context names: `g`, `std`, `api`, `$event`, `$item`, `$index`, `$key`.\n\n## 3. Props classification\n\n### Static props\n\nPassed to the component unchanged:\n\n```js\n\"text:title\": { text: \"Hello\" }\n```\n\n### `$` read-pipes\n\nA 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:\n\n```js\n\"text:value\": { \"$content\": \"'Count: ' + g.count\" }\n// Resolves to: content = \"Count: \"\n```\n\n### `on*` write-pipes\n\nA string value on an `on*`-prefixed key is executed as a JavaScript statement:\n\n```js\n\"button:add\": { onclick: \"g.count++\" }\n\"input:name\": { onchange: \"g.name = String($event || '')\" }\n```\n\nThe handler receives `$event` as the event data.\n\n### Structural directives\n\n`$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.\n\n## 4. `g` merge\n\nWhen the same namespace is mounted or ingested again, the new `g` is merged into the existing store:\n\n| Value type | Merge behavior |\n| ------------------- | ------------------------ |\n| Function | Overwrites the old value |\n| Array | Replaces entirely |\n| Plain object | Recursively deep-merges |\n| Other scalar | Overwrites the old value |\n| Keys not in new `g` | Preserved from old `g` |\n\nThe new `layout` always replaces the current layout. Layout is never deep-merged.\n\n## 5. Expression context\n\nExpressions can access these variables:\n\n| Variable | Type | Scope |\n| ------------------ | ----------------------------- | ------------------------ |\n| `g` | Reactive state proxy | Always |\n| `std` | Pure SlexKit standard library | Always |\n| Component state | e.g. `slider.value` | Named components |\n| `api` | Host-injected object | If `api` option provided |\n| `$event` | Event data | `on*` handlers only |\n| `$item` | Current array item | `$for` context only |\n| `$index` | Current array index | `$for` context only |\n| `$key` | Current item key | `$for` context only |\n| Named `$for` alias | e.g. `user` for `\"card:user\"` | `$for` context only |\n\n`std` contains deterministic helpers for math, formatting, units, and small statistics. Sensitive capabilities stay under host-injected `api.*` and may require secure runtime policy.\n\nExpression evaluation errors are caught and produce a warning with namespace and path information. The last known value is returned as a fallback.\n\n## 6. Component instance state\n\nComponent registration declares a state mode:\n\n```ts\nregister(type, renderer, { state: \"value\" | \"checked\" | \"enabled\" | \"readable\" | \"none\" });\n```\n\n| Mode | Writable | Behavior |\n| ---------- | ------------------ | ------------------------------------------------------------- |\n| `value` | `value` | Input component; `value` writable from expressions and events |\n| `checked` | `checked`, `value` | Checkbox-like boolean component; both synced and writable |\n| `enabled` | `enabled` | Switch-like boolean component; enabled state is writable |\n| `readable` | (none) | Readable from expressions; write emits console warning |\n| `none` | (none) | No instance state exposed |\n\nInput components (`value`/`checked`/`enabled` modes) sync `change` events to instance state automatically. Duplicate-named components share one namespace-level state instance.\n\n`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.\n\n## 7. `$if`\n\n`$if` controls component existence:\n\n```js\n\"card:panel\": {\n \"$if\": \"g.visible\",\n \"text:body\": { text: \"Visible\" }\n}\n```\n\n- **Truthy** -mounts the component and its subtree with enter animation if `$enter` is defined.\n- **Falsy** -unmounts the component and subtree with leave animation if `$leave` is defined, then fires lifecycle hooks, disposers, and subtree cleanup.\n\n## 8. `$for`\n\n`$for` renders a component for each array element:\n\n```js\n\"text:item\": {\n \"$for\": \"g.items\",\n \"$key\": \"id\",\n \"$content\": \"$item.label\"\n}\n```\n\nContext variables: `$item`, `$index`, `$key`. Named components inject the current item as a same-name variable.\n\n### `$key` strategy\n\n| `$key` value | Behavior |\n| ------------------------ | ------------------------------------------------------------------------------- |\n| `\"$value\"` | Use the primitive item itself |\n| `\"id\"` or other property | Read that property from object items |\n| Omitted | Use `item.id` if available; otherwise fall back to index with a console warning |\n\nPrimitive arrays should always specify `$key: \"$value\"`.\n\n### $for phases\n\n1. **Delete** -Remove items whose keys are absent from the new array (with leave animation).\n2. **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_`.\n3. **Trim** -Defensively remove excess children.\n\n## 9. Lifecycle and cleanup\n\nConvention hooks on `g`:\n\n```\ng.onMount_() -after component is appended to DOM\ng.onUnmount_() -before component is removed from DOM\ng.onUpdate_() -after $for item changes (index or item reference)\n```\n\nComponent implementations can register resource cleanup:\n\n```ts\nattachComponentDisposer(el, dispose);\n```\n\nComponent disposal is triggered by normal unmount, `$if` toggle-off, `$for` item removal, root cleanup, and `disposeNamespace()`.\n\n## 10. Public runtime API\n\n| Function | Signature | Description |\n| ----------------------------------- | ------------------------------------------- | -------------------------------------------------------------------- |\n| `mount` | `(input, container, options?) => Cleanup` | Parse, merge state, render component tree |\n| `ingest` | `(input) => boolean` | Ingest state-only Slex, no rendering |\n| `boot` | `(options?) => void` | Enhance static page code blocks |\n| `disposeNamespace` | `(namespace) => void` | Release namespace roots, store, and cache |\n| `register` | `(type, renderer, options?) => void` | Register component type |\n| `getRenderer` | `(type) => ComponentRenderer \\| undefined` | Look up a registered renderer |\n| `getIcon` | `(name, state?) => string` | Resolve a registered or bundled icon synchronously |\n| `loadIcon` | `(name, state?) => Promise` | Resolve an icon, using Iconify fallback when not bundled |\n| `registerIcon` | `(name, svg, options?) => void` | Register one global SVG icon for all components with an `icon` field |\n| `registerIcons` | `(icons, options?) => void` | Register multiple global SVG icons |\n| `clearRegisteredIcons` | `() => void` | Clear all custom registered icons |\n| `getRegisteredIcon` | `(name, state?) => string` | Look up only registered icons (no Phosphor fallback) |\n| `normalizeIconName` | `(name) => string` | Normalize icon name to kebab-case with set prefix |\n| `resolveIconWeight` | `(state?) => IconWeight` | Resolve icon weight from component state |\n| `resolveIconifyIcon` | `(name, state?) => {prefix, name}` | Resolve to Iconify-compatible name pair |\n| `iconifySvgUrl` | `(name, state?) => string` | Build full Iconify API SVG URL |\n| `configureComponentScope` | `(options) => void` | Configure framework adapter flush |\n| `attachComponentDisposer` | `(el, dispose) => void` | Bind cleanup to element lifecycle |\n| `createSecureRuntime` | `(policy, adapter?) => SecureRuntimeHandle` | Create gated runtime instance |\n| `mountSecureArtifact` | `(input, container, options) => Cleanup` | Mount in secure sandbox |\n| `createSlexKitMarkdownRuntimeHost` | `(options?) => MarkdownRuntimeHost` | Create Markdown host instance |\n| `getSlexKitMarkdownRuntimeHost` | `() => MarkdownRuntimeHost` | Get or create global Markdown host |\n| `installSlexKitMarkdownRuntimeHost` | `(options?) => MarkdownRuntimeHost` | Install and return global Markdown host |\n| `getSlexKitRuntimeUrl` | `() => string \\| undefined` | Get default sandbox runtime URL |\n| `setSlexKitRuntimeUrl` | `(url) => void` | Set default sandbox runtime URL |\n| `diagnoseSlexKitSource` | `(source, error) => Diagnostic` | Locate syntax error in source |\n| `parseSlexSource` | `(source) => ParseResult` | Parse Slex source to object |\n| `validateSlexSource` | `(source, options?) => ValidationResult` | Parse-first validation with versions, usage, and stable warning codes |\n| `runSlexConformance` | `(options?) => ConformanceReport` | Run bundled standard conformance fixtures |\n| `formatSlexKitDiagnostic` | `(diagnostic) => string` | Format diagnostic to readable string |\n\nFor full runtime behavior, see [Runtime Model](/docs/reference/runtime).\n\n## 11. Error types\n\n### SlexKitSyntaxError\n\nThrown when Slex source parsing fails. Includes a `diagnostic` property with `message`, `line`, `column`, `detail`, and `excerpt`.\n\n### SlexKitRuntimeError\n\nThrown when a runtime operation violates policy or encounters a runtime failure. Has properties: `kind` (`\"policy\"` | `\"network\"` | `\"timeout\"`), `code` (specific error code string), `message`, `elapsedMs`.\n\n## 12. Markdown language handling\n\nSlexKit hosts must only process explicit fence language tags:\n\n- `slex`\n\nPlain JavaScript, JSON, or untagged code blocks must not be scanned or executed.\n\n## 13. Secure runtime types\n\n```ts\ntype SecureRuntimeHandle = {\n api: SlexKitRuntimeApi;\n dispose: () => void;\n};\n```\n\nFor full secure runtime types (`HostRuntimePolicy`, `HostRuntimeAdapter`, `SlexKitRuntimeApi`, `SecureFrameOptions`, `SecureMountOptions`, sandbox message types), see the [security runtime contract](/docs/reference/security).\n\n## 14. ToolHost\n\nToolHost bridges AI tool calls to interactive UI that returns structured user input. It is separate from display-oriented `slex` fences.\n\n**Public API:**\n\n| Function | Signature | Description |\n|----------|-----------|-------------|\n| `renderToolCall` | `(call, container) => ToolRenderHandle` | Compile and mount tool UI, return promise |\n| `registerToolTemplate` | `(name, compiler) => void` | Register a custom tool template compiler |\n\n**Result type:**\n\n```ts\ntype ToolResult =\n | { toolCallId?: string; toolName: string; status: \"submitted\"; value: Record }\n | { toolCallId?: string; toolName: string; status: \"ignored\"; value: null };\n```\n\n**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.\n\nFor full template reference, arguments, type definitions, and custom template development, see [ToolHost documentation](/docs/reference/toolhost).\n\n## 15. Icon system\n\nSlexKit includes a built-in icon system with Phosphor Icons, a custom registration API, and Iconify fallback support.\n\n**Public API (10 functions):** `registerIcon`, `registerIcons`, `clearRegisteredIcons`, `getIcon`, `getRegisteredIcon`, `loadIcon`, `normalizeIconName`, `resolveIconWeight`, `resolveIconifyIcon`, `iconifySvgUrl`.\n\nIcons 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.\n\nFor the full API reference, icon list, naming conventions, and custom icon registration, see [Icon system documentation](/docs/reference/icons).\n\n## 16. Non-goals\n\n- No public stable compatibility commitment (v0/beta).\n- Not a pure JSON cross-platform protocol.\n- No automatic security hardening of arbitrary browser APIs.\n- No heuristic scanning of code blocks to guess whether to render.\n- No implicit wrapping of display UI as function calls.", "hash": "2e0c71cd" }, { "id": "reference/usage", "group": "Reference", "title": "Slex Usage Reference", "summary": "Slex source structure, props, directives, events, theming, custom components, and ToolHost boundaries.", "href": "/docs/reference/usage", "rawHref": "/docs/reference/usage.md", "sourcePath": "site/content/reference/usage/en-US.md", "body": "---\ntitle: Slex Usage Reference\ncategory: Reference\nstatus: ready\norder: 20\nsummary: \"Slex source structure, props, directives, events, theming, custom components, and ToolHost usage.\"\nslexkitRenderMode: component\n---\n\n# Slex Usage Reference\n\nSlex 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).\n\n## Installation\n\nMost hosts install the root package:\n\n```sh\nnpm install slexkit\n```\n\n```js\nimport { mount } from \"slexkit\";\nimport \"slexkit/style.css\";\n```\n\nComponent-free bare runtime:\n\n```sh\nnpm install slexkit @slexkit/runtime\n```\n\n```js\nimport { mount, register } from \"@slexkit/runtime\";\n```\n\nThis 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.\n\nFor package roles and host-specific install commands, see [Packages](/docs/reference/packages).\n\n## Slex source structure\n\nA Slex source is a JavaScript object literal:\n\n```js\n{\n slex: \"0.1\",\n namespace: \"demo\",\n g: { count: 0 },\n layout: {\n \"button:add\": { text: \"Add\", onclick: \"g.count++\" },\n \"text:value\": { \"$content\": \"'Count: ' + g.count\" }\n }\n}\n```\n\n- `slex` - optional Slex protocol marker; use `\"0.1\"` for the current public protocol.\n- `namespace` - state domain identifier (defaults to `\"default\"`).\n- `g` - reactive state and logic (functions, data).\n- `layout` - component tree.\n\nAs a convenience, a bare component tree (keys containing `:`) is normalized to `{ namespace: \"default\", g: {}, layout: }`. If the bare tree includes `slex: \"0.1\"`, that marker is preserved while component keys move under `layout`.\n\n## Props\n\n### Static props\n\nPassed to the component as-is:\n\n```js\n\"text:title\": { text: \"Hello World\" }\n```\n\n### Dynamic read-pipes (`$`)\n\nA string value on a `$`-prefixed key is evaluated as a JavaScript expression. The result replaces the key stripped of the `$` prefix:\n\n```js\n\"text:value\": { \"$content\": \"'Count: ' + g.count\" }\n```\n\nThe `$` prefix is removed. The prop passed to the component is `content`. Re-evaluation is triggered automatically when any reactive dependency changes.\n\n### Write-pipes (`on*`)\n\nA string value on an `on*`-prefixed key is executed as a JavaScript statement:\n\n```js\n\"button:add\": { onclick: \"g.count++\" }\n\"input:name\": { onchange: \"g.name = String($event || '')\" }\n```\n\nThe handler receives `$event` as the event data.\n\n### Structural directives\n\n`$if`, `$for`, and `$key` are structural directives - they are not passed to the component as props.\n\n## `$if` - conditional rendering\n\nControls whether the component and its subtree are mounted:\n\n```js\n\"card:panel\": {\n \"$if\": \"g.visible\",\n \"text:body\": { text: \"I am visible\" }\n}\n```\n\nWhen 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).\n\n## `$for` - array iteration\n\nRenders a component for each item in an array:\n\n```js\n\"text:item\": {\n \"$for\": \"g.items\",\n \"$key\": \"id\",\n \"$content\": \"$item.label\"\n}\n```\n\nContext 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).\n\n### Key strategy\n\n`$key` supports:\n- `\"$value\"` - use the primitive item itself as key.\n- `\"id\"` (or any property name) - read that property from object items.\n- Omitted - uses `item.id` if available, otherwise falls back to index with a console warning.\n\nPrimitive array items should always specify `$key: \"$value\"`.\n\n### $for update algorithm\n\n1. **Delete phase** - remove items whose keys are no longer in the array (with leave animation).\n2. **Add/update/reorder phase** - create new items, update retained items' context (index, item reference), and reorder DOM nodes to match the array.\n3. **Trim phase** - defensively remove any excess children.\n\nWhen an item's index or item reference changes, `onUpdate_` is called.\n\n## Events\n\nEvent handlers are defined as `on*` write-pipes. The component's native change/input events are automatically wired to component instance state for writable components:\n\n```js\n\"input:name\": { onchange: \"g.name = String($event || '')\" }\n```\n\nThe `$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.\n\n## Trusted vs secure mode\n\n### Trusted mode (default)\n\nSlex source executes in the host page realm. Use for application-generated content, repository-maintained Slex source, or already-reviewed snippets.\n\n```js\nimport { mount } from \"slexkit\";\n\nmount(script, container, { theme: \"host-shadcn\" });\n```\n\n### Secure mode\n\nUntrusted or agent-generated Slex source runs in a sandbox iframe with opaque origin. Sensitive capabilities are gated behind host policy:\n\n```js\nimport { mountSecureArtifact } from \"slexkit\";\n\nmountSecureArtifact(script, container, {\n policy: {},\n frame: { runtimeUrl: \"/slexkit.runtime.js\" },\n});\n```\n\nUse [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.\n\n## Theming\n\nTheme mode is resolved from the `theme` option:\n\n| Value | Behavior |\n|-------|----------|\n| `\"auto\"` | Checks container for known theme classes; falls back to `\"uno\"` |\n| `\"host-shadcn\"` | shadcn/ui compatible |\n| `\"uno\"` | Uno/Flowbite compatible |\n| `\"flowbite\"` | Flowbite compatible |\n\nDirection (`ltr`, `rtl`, `auto`) is resolved from the inherited `dir` attribute or the document element.\n\n```js\nmount(script, container, { theme: \"host-shadcn\", dir: \"auto\" });\n```\n\n## Custom components\n\nRegister a component type with a render function:\n\n```ts\nimport { register } from \"slexkit\";\n\nregister(\"custom\", (props, name, ctx) => {\n const el = ctx.document.createElement(\"div\");\n el.textContent = String(props.label ?? name);\n return el;\n}, { state: \"value\" });\n```\n\nThe `RenderContext` provides:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `g` | reactive proxy | Global state |\n| `std` | `SlexKitStdlib` | Pure deterministic helpers |\n| `api` | `Record` | Host-injected capabilities |\n| `dir` | `\"ltr\"` or `\"rtl\"` | Resolved direction |\n| `labels` | `Partial>` | Runtime labels |\n| `id` | `string \\| null` | Component name |\n| `emit` | `(event, data?) => void` | Event emitter |\n| `children` | `Record` | Nested component tree |\n| `document` | `Document` | Owner document |\n| `renderTree` | function | Recursive render helper |\n\nUse `attachComponentDisposer(el, fn)` to bind cleanup to the component's DOM lifecycle.\n\n## ToolHost\n\nToolHost handles UI that must return structured user input (confirmations, selections, forms). It is separate from display-oriented `slex` fences.\n\nBuilt-in templates:\n- `confirm-action` - yes/no confirmation\n- `choose-options` - single or multi-select\n- `option-list` - scrollable option list\n- `fill-form` - structured form with submit\n\nTemplates compile to standard Slex source. The `submit` component submits the result; only tool templates use it, not display fences.", "hash": "869ad84f" }, { "id": "reference/runtime", "group": "Reference", "title": "Runtime Model", "summary": "Mounting, ingestion, boot, namespace store, lifecycle, and runtime APIs.", "href": "/docs/reference/runtime", "rawHref": "/docs/reference/runtime.md", "sourcePath": "site/content/reference/runtime/en-US.md", "body": "---\ntitle: Runtime Model\ncategory: Reference\nstatus: ready\norder: 30\nsummary: \"Mounting, ingestion, boot, namespace store, lifecycle hooks, component state, and runtime APIs.\"\nslexkitRenderMode: component\n---\n\n# Runtime Model\n\nThe core SlexKit runtime: entry points, namespace store, component state, lifecycle hooks, and expression evaluation.\n\nSlex source syntax is covered in the [protocol specification](/docs/reference/spec). Secure mode isolation is covered in the [security runtime contract](/docs/reference/security).\n\n## Entry points\n\n### `mount(input, container, options)`\n\nParses Slex source object or source string, merges state into the namespace store, renders the component tree into `container`, returns a root cleanup function.\n\n```ts\nfunction mount(\n input: SlexExpression | string,\n container: HTMLElement,\n options?: MountOptions\n): () => void;\n\ntype MountOptions = {\n theme?: \"auto\" | \"host-shadcn\" | \"uno\" | \"flowbite\";\n dir?: \"ltr\" | \"rtl\" | \"auto\";\n labels?: Partial>;\n api?: Record;\n};\n```\n\nCalling `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.\n\nEvery 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.\n\n### `ingest(input)`\n\nIngests state-only Slex: updates `g` without rendering UI. Used by the Markdown runtime host for state-only fences. Returns `true` if parsing succeeded.\n\n```ts\nfunction ingest(input: SlexExpression | string): boolean;\n```\n\n### `disposeNamespace(namespace)`\n\nPermanently 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.\n\n```ts\nfunction disposeNamespace(namespace: string): void;\n```\n\n### `boot(options)`\n\nEnhances static pages by auto-discovering explicitly marked Slex blocks (`
`) and mounting live previews.\n\n```ts\nfunction boot(options?: BootOptions): void;\n\ntype BootOptions = {\n  selector?: string;\n  sourceControls?: boolean;\n  theme?: ThemeMode;\n  dir?: MountOptions[\"dir\"];\n  labels?: MountOptions[\"labels\"];\n};\n```\n\nDefault selector covers: `language-slex`.\n\nHosts like React/Streamdown or Obsidian should typically use the Markdown runtime host directly rather than `boot()`.\n\n### `register(type, renderer, options)`\n\nRegisters a component type with a render function and state mode.\n\n```ts\nfunction register(\n  type: string,\n  renderer: ComponentRenderer,\n  options?: ComponentRegistrationOptions\n): void;\n\ntype ComponentRenderer = (\n  props: Record,\n  name: string,\n  ctx: RenderContext\n) => HTMLElement | void;\n\ntype ComponentRegistrationOptions = {\n  state?: \"value\" | \"checked\" | \"enabled\" | \"readable\" | \"none\";\n};\n```\n\n### `configureComponentScope(options)`\n\nConfigures a flush function for component scope. Framework adapters use it to synchronize DOM after reactive updates.\n\n```ts\nfunction configureComponentScope(options: { flush?: () => void }): void;\n```\n\n## Validation and conformance\n\n### `validateSlexSource(source, options)`\n\nValidates Slex source after parsing. The result includes `schemaVersion`, `protocolVersion`, `logicProfileVersion`, usage lists, and warning codes. Syntax failures return a diagnostic.\n\n```ts\nfunction validateSlexSource(\n  source: string,\n  options?: { mode?: \"trusted\" | \"secure\" }\n): ValidationResult;\n```\n\n### `runSlexConformance(options)`\n\nRuns the bundled standard fixtures against the current validator. Pass `fixtureId` to run one fixture.\n\n```ts\nfunction runSlexConformance(options?: { fixtureId?: string }): ConformanceReport;\n```\n\n## Namespace store\n\n`namespace` is the state domain. Multiple mounts with the same namespace share one store:\n\n- New `g` is deep-merged into the old `g` (functions overwrite, objects recursively merge, arrays replace, scalars overwrite).\n- New `layout` replaces the current layout (no deep merge for layout).\n- Component instance state is persisted within the namespace.\n- Expression caches are managed per namespace.\n\nThis allows a document, message domain, or tool panel to update its UI incrementally while preserving state.\n\n## Component instance state\n\nNamed components can expose instance state. Which prop is writable depends on the component's registered state mode:\n\n| Mode | Writable prop | Behavior |\n|------|---------------|----------|\n| `value` | `value` | Writable from expressions and events |\n| `checked` | `checked`, `value` | Both synced, writable |\n| `enabled` | `enabled` | Switch enabled state, writable |\n| `readable` | (none) | Readable from expressions, write emits a console warning |\n| `none` | (none) | No state exposed |\n\n```js\n{\n  layout: {\n    \"slider:threshold\": { value: 42 },\n    \"text:preview\": { \"$content\": \"'Threshold: ' + threshold.value\" }\n  }\n}\n```\n\nRepeatedly named components share namespace-level state. `$for` items with the same component name also share one state instance.\n\n## Lifecycle hooks\n\nThe runtime calls convention-based hooks on the `g` object:\n\n```\ng.onMount_()      // after component is appended to DOM\ng.onUnmount_()    // before component is removed from DOM\ng.onUpdate_()     // after $for item index or item reference changes\n```\n\nThese hooks fire for normal components, `$if` branches, and `$for` slots. Root cleanup and `disposeNamespace()` trigger `onUnmount`.\n\n## Component disposer\n\nFramework components, event listeners, subscriptions, and external resources should bind their cleanup to the component DOM element:\n\n```ts\nimport { register, attachComponentDisposer } from \"slexkit/runtime\";\n\nregister(\"custom\", (props, name, ctx) => {\n  const el = ctx.document.createElement(\"div\");\n  const stop = subscribeSomething();\n  attachComponentDisposer(el, stop);\n  return el;\n});\n```\n\nThe runtime calls the disposer when the element is unmounted. The official Svelte adapter uses this mechanism to destroy Svelte component instances.\n\n## Expression evaluation context\n\nExpressions in `$` read-pipes and statements in `on*` write-pipes can access these variables:\n\n| Variable | Type | Availability |\n|----------|------|--------------|\n| `g` | reactive state proxy | always |\n| `api` | host-injected capabilities | if `api` option passed to `mount()` |\n| `$event` | event data | `on*` handlers only |\n| `$item` | current array item | `$for` context only |\n| `$index` | current array index | `$for` context only |\n| `$key` | current item key | `$for` context only |\n| named component state | e.g. `threshold.value` | named components |\n\nExpression 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.",
      "hash": "51870f25"
    },
    {
      "id": "reference/integration",
      "group": "Reference",
      "title": "Host Integration",
      "summary": "Markdown renderers, Svelte custom hosts, Streamdown, Tiptap, Obsidian, and artifact lifecycle.",
      "href": "/docs/reference/integration",
      "rawHref": "/docs/reference/integration.md",
      "sourcePath": "site/content/reference/integration/en-US.md",
      "body": "---\ntitle: Host Integration\ncategory: Reference\nstatus: ready\norder: 40\nsummary: \"MarkdownRuntimeHost, trusted and secure host integrations, Svelte custom hosts, Streamdown, Tiptap, Obsidian, and custom adapters.\"\nslexkitRenderMode: component\n---\n\n# Host Integration\n\nHow to integrate SlexKit into Markdown renderers, chat hosts, document viewers, and custom platforms.\n\n## Core concepts\n\n### Artifact\n\nAn 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.\n\nIn **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.\n\nIn **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.\n\n### Block\n\nA block is a single Slex block: one renderable unit. It has:\n- A source (Slex expression object or source string).\n- A container element (where the rendered output goes).\n- An optional `artifactId` (for grouping into an artifact).\n\n### Cleanup\n\nEvery 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()`.\n\n## MarkdownRuntimeHost\n\nThe `SlexKitMarkdownRuntimeHost` is the recommended API for Markdown-based hosts. It handles mode selection, artifact management, and block lifecycle.\n\n```ts\nimport {\n  createSlexKitMarkdownRuntimeHost,\n  getSlexKitMarkdownRuntimeHost,\n  installSlexKitMarkdownRuntimeHost\n} from \"slexkit\";\n```\n\n### Interface\n\n```ts\ntype SlexKitMarkdownRuntimeHost = {\n  configure(options: Partial): void;\n  getMode(): \"trusted\" | \"secure\";\n  mountBlock(block: SlexKitMarkdownBlock): () => void;\n  disposeBlock(container: HTMLElement): void;\n  disposeArtifact(artifactId: string): void;\n  disposeAll(): void;\n};\n\ntype SlexKitMarkdownBlock = {\n  artifactId?: string;\n  blockId?: string;\n  source: SlexExpression | string;\n  container: HTMLElement;\n  stateOnly?: boolean;\n  theme?: ThemeMode;\n  dir?: MountOptions[\"dir\"];\n  labels?: MountOptions[\"labels\"];\n  executionMode?: MountOptions[\"executionMode\"];\n};\n\ntype SlexKitMarkdownRuntimeOptions = {\n  mode?: \"trusted\" | \"secure\";\n  policy?: HostRuntimePolicy;\n  hostAdapter?: HostRuntimeAdapter;\n  secureFrame?: boolean | SecureFrameOptions;\n  theme?: ThemeMode;\n  dir?: MountOptions[\"dir\"];\n  labels?: MountOptions[\"labels\"];\n  executionMode?: MountOptions[\"executionMode\"];\n};\n```\n\n`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()`.\n\n### Global singleton\n\nThe module provides a global singleton for convenience:\n\n```ts\n// Install explicitly\nconst runtime = installSlexKitMarkdownRuntimeHost({\n  mode: \"secure\",\n  policy: { execution: { maxUnresponsiveMs: 30000 } },\n  secureFrame: { runtimeUrl: \"/slexkit.runtime.js\" }\n});\n\n// Or use lazy global (auto-creates with defaults on first call)\nconst runtime = getSlexKitMarkdownRuntimeHost();\n```\n\nUse the singleton when the entire application shares one runtime configuration. Avoid it when different host contexts need different policies.\n\n## Trusted mode integration\n\nTrusted mode runs Slex source in the host page realm. Use for local documents, application-generated content, or reviewed Slex source.\n\n```ts\nconst runtime = createSlexKitMarkdownRuntimeHost({\n  mode: \"trusted\",\n  theme: \"host-shadcn\"\n});\n\n// Detect a slex fence at position \nconst cleanup = runtime.mountBlock({\n  artifactId: \"doc-1\",\n  source: fenceSource,\n  container: fenceContainer\n});\n\n// When the fence container is removed\nruntime.disposeBlock(fenceContainer);\n\n// When the document is closed\nruntime.disposeArtifact(\"doc-1\");\n\n// When the plugin or page unloads\nruntime.disposeAll();\n```\n\nIn trusted mode, the runtime automatically scopes namespaces by artifact ID (`::`) to prevent different documents from polluting each other's state.\n\nState-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.\n\n## Secure mode integration\n\nSecure mode runs Slex source in a sandbox iframe. Use for untrusted or agent-generated Markdown.\n\n```ts\nconst runtime = createSlexKitMarkdownRuntimeHost({\n  mode: \"secure\",\n  policy: {\n    execution: { maxUnresponsiveMs: 30000 }\n  },\n  secureFrame: {\n    runtimeUrl: \"/slexkit.runtime.js\"\n  },\n  theme: \"host-shadcn\"\n});\n\nconst cleanup = runtime.mountBlock({\n  artifactId: \"agent-msg-1\",\n  source: agentGeneratedDsl,\n  container: fenceContainer\n});\n```\n\nOmitted capability policies deny access by default. Add `network`, `timer`, `animation`, or `canvas` policy objects only when the host intentionally enables those capabilities.\n\n### Artifact slot bridge\n\nWhen 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.\n\n```html\n\n
\n
\n
\n```\n\nThis allows state sharing across fences within one artifact while keeping all execution confined to one sandbox.\n\n### `runtimeUrl` requirements\n\nThe `runtimeUrl` must serve the SlexKit runtime as an ES module with:\n\n```\nAccess-Control-Allow-Origin: *\nContent-Type: text/javascript\n```\n\nThe 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.\n\n## Svelte custom Markdown host\n\nThe 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.\n\n```js\nimport { mount, unmount } from \"svelte\";\nimport { createSlexKitMarkdownRuntimeHost } from \"slexkit\";\nimport MarkdownRenderer from \"./MarkdownRenderer.svelte\";\n\nexport function renderMarkdown(content, container, options = {}) {\n  const runtimeHost = options.slexkitRuntimeHost ?? createSlexKitMarkdownRuntimeHost({\n    mode: options.runtimeMode ?? \"trusted\",\n    theme: \"host-shadcn\"\n  });\n\n  const app = mount(MarkdownRenderer, {\n    target: container,\n    props: {\n      content,\n      runtimeHost,\n      artifactId: options.artifactId,\n      slexkitRenderMode: options.slexkitRenderMode ?? \"component\"\n    }\n  });\n\n  return () => unmount(app);\n}\n```\n\nUse 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.\n\n## Streamdown / React integration\n\nThe `@slexkit/streamdown` package provides a React/Streamdown custom renderer:\n\n```tsx\nimport { Streamdown } from \"streamdown\";\nimport { slexkitRenderer } from \"@slexkit/streamdown\";\nimport \"@slexkit/theme-shadcn/style.css\";\nimport \"@slexkit/streamdown/style.css\";\n\nexport function Message({ markdown }: { markdown: string }) {\n  return (\n    \n      {markdown}\n    \n  );\n}\n```\n\nThe renderer handles `slex` fences. It supports both trusted and secure runtime modes and can delegate to a shared Markdown runtime host instance.\n\nDuring 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.\n\n## Tiptap integration\n\nThe `@slexkit/tiptap` package provides a framework-free Tiptap `CodeBlock` extension:\n\n```ts\nimport StarterKit from \"@tiptap/starter-kit\";\nimport { Markdown } from \"@tiptap/markdown\";\nimport { createSlexKitTiptapExtension } from \"@slexkit/tiptap\";\nimport \"@slexkit/theme-shadcn/style.css\";\nimport \"@slexkit/tiptap/style.css\";\n\nconst extensions = [\n  StarterKit.configure({ codeBlock: false }),\n  Markdown,\n  createSlexKitTiptapExtension({ artifactId: \"doc-1\" })\n];\n```\n\nThe 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.\n\nEach 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.\n\n## Obsidian integration\n\nThe official Obsidian plugin is available at  and registers the `slex` fenced code block processor:\n\n```ts\n// In the plugin:\nregisterMarkdownCodeBlockProcessor(\"slex\", (source, el, ctx) => { ... });\n```\n\nThe 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.\n\n**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.\n\n## Writing a custom host adapter\n\nTo integrate SlexKit into a custom Markdown renderer or chat host:\n\n### 1. Detect fence language\n\nOnly process fences tagged with `slex`. Never scan plain JavaScript, JSON, or untagged code blocks.\n\n### 2. Create a runtime host\n\n```ts\nimport { createSlexKitMarkdownRuntimeHost } from \"slexkit\";\n\nconst runtime = createSlexKitMarkdownRuntimeHost({\n  mode: \"trusted\",   // or \"secure\"\n  theme: \"host-shadcn\"\n});\n```\n\n### 3. Mount blocks\n\nFor each detected fence, create a container element and mount:\n\n```ts\nfunction processFence(source: string, fenceIndex: number) {\n  const container = document.createElement(\"div\");\n  // Insert container at the fence position in the document\n\n  const cleanup = runtime.mountBlock({\n    artifactId: \"message-42\",\n    source,\n    container\n  });\n\n  return cleanup;\n}\n```\n\n### 4. Manage lifecycle\n\n```ts\n// When a single block is removed\nruntime.disposeBlock(container);\n\n// When the entire artifact (message/document) is removed\nruntime.disposeArtifact(\"message-42\");\n\n// When the plugin/page unloads\nruntime.disposeAll();\n```\n\n### 5. Handle secure mode\n\nIf using secure mode, serve `slexkit.runtime.js` as a public ES module with the correct CORS headers, and configure `secureFrame.runtimeUrl`.\n\n## Fallback rendering\n\nSlexKit-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.",
      "hash": "d239c5cf"
    },
    {
      "id": "reference/security",
      "group": "Reference",
      "title": "Security Runtime",
      "summary": "Threat model, sandbox iframe, postMessage bridge, policy, and fail-closed behavior.",
      "href": "/docs/reference/security",
      "rawHref": "/docs/reference/security.md",
      "sourcePath": "site/content/reference/security/en-US.md",
      "body": "---\ntitle: Security Runtime Contract\ncategory: Reference\nstatus: ready\norder: 50\nsummary: \"Threat model, sandbox iframe deployment, host policy, postMessage bridge, and fail-closed behavior.\"\nslexkitRenderMode: component\n---\n\n# Security Runtime Contract\n\nThe secure runtime defines what untrusted Slex source can and cannot do, how the host authorizes capabilities, and how sandbox isolation works.\n\n## Threat model\n\n- The host page and host application are trusted.\n- Slex source may be untrusted.\n- Secure artifacts run inside a sandbox iframe.\n- The iframe uses an opaque origin by default (no `allow-same-origin`).\n- Slex source must not access the host DOM, cookies, `localStorage`, `IndexedDB`, or host global objects.\n\nSecure mode confines expression execution to an isolated environment and consolidates sensitive capabilities under the host `policy` and `api.*`.\n\n## Authorization source\n\nThe 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.\n\nAll capabilities are accessed through `api.*`:\n\n```\napi.get(url, options)\napi.post(url, body, options)\napi.fetch(url, options)\n\napi.setTimeout(fn, ms)\napi.clearTimeout(id)\napi.setInterval(fn, ms)\napi.clearInterval(id)\n\napi.raf(fn)\napi.cancelRaf(id)\n\napi.createCanvas(width, height)\napi.getCanvasContext(canvas, contextId, options)\n\napi.onDispose(fn)\napi.now()\n\napi.isTimeoutError(error)\napi.isNetworkError(error)\napi.isPolicyError(error)\napi.errorMessage(error)\n```\n\nCapabilities not exposed through `api.*` are unsupported.\n\n## HostRuntimePolicy\n\n```ts\ntype HostRuntimePolicy = {\n  network?: {\n    enabled: boolean;\n    methods: (\"GET\" | \"POST\")[];\n    allowOrigins: string[];\n    allowHeaders?: string[];\n    allowContentTypes?: string[];\n    credentials: \"omit\" | \"same-origin\" | \"include\";\n    timeoutMs: number;\n    maxBodyBytes: number;\n    maxResponseBytes?: number;\n  };\n  timer?: {\n    enabled: boolean;\n    maxTimers: number;\n    minIntervalMs: number;\n  };\n  animation?: {\n    enabled: boolean;\n  };\n  canvas?: {\n    enabled: boolean;\n    maxCanvases?: number;\n    maxPixels?: number;\n    allowedContexts?: (\"2d\" | \"webgl\" | \"webgl2\" | \"bitmaprenderer\")[];\n  };\n  execution?: {\n    heartbeatIntervalMs?: number;\n    maxUnresponsiveMs?: number;\n  };\n};\n```\n\n### Network policy\n\nNetwork is denied by default unless `policy.network.enabled` is `true`. The policy constrains:\n- HTTP method (only listed methods allowed)\n- Origin (supports `*`, exact match, `protocol://*` protocol wildcard, and `protocol://*.domain` subdomain wildcard)\n- Request headers (only listed headers pass; `Authorization`, `Cookie`, `Proxy-Authorization`, `Set-Cookie`, and Sec-Fetch headers are always blocked)\n- Credentials mode\n- Request body size\n- Request timeout\n- Response body size\n- Response content-type\n\n`hostAdapter.fetch` can replace the actual request implementation. `hostAdapter.onNetworkLog` is observational only; it must not alter runtime behavior.\n\n### Timer, animation, and canvas\n\n- **Timer**: denied by default. When enabled, subject to `maxTimers` (total concurrent) and `minIntervalMs` (minimum delay). All timers and intervals are cleaned up on dispose.\n- **Animation**: denied by default. Controlled via `animation.enabled`; `api.raf` is the only animation primitive.\n- **Canvas**: denied by default. When enabled, subject to `maxCanvases`, `maxPixels`, and `allowedContexts`.\n\n### Execution monitoring\n\n`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.\n\n## HostRuntimeAdapter\n\nThe adapter allows the host to override or observe runtime behavior:\n\n```ts\ntype HostRuntimeAdapter = {\n  fetch?: (request: HostFetchRequest) => Promise;\n  onNetworkLog?: (event: RuntimeNetworkLogEvent) => void;\n  onRuntimeError?: (event: RuntimeErrorEvent) => void;\n  now?: () => number;\n  setTimeout?: (fn: () => void, ms: number) => TimerId;\n  clearTimeout?: (id: TimerId) => void;\n  setInterval?: (fn: () => void, ms: number) => TimerId;\n  clearInterval?: (id: TimerId) => void;\n  requestAnimationFrame?: (fn: (time: number) => void) => RafId;\n  cancelAnimationFrame?: (id: RafId) => void;\n};\n```\n\n`onNetworkLog` and `onRuntimeError` are audit hooks; they must not change runtime behavior. Errors thrown within them are silently caught.\n\n## Sandbox iframe deployment\n\nThe secure frame imports the main runtime module from a `runtimeUrl`:\n\n```ts\nmountSecureArtifact(script, container, {\n  frame: {\n    runtimeUrl: \"/slexkit.runtime.js\"\n  }\n});\n```\n\nThis URL must serve as a public ES module and return:\n\n```\nAccess-Control-Allow-Origin: *\nContent-Type: text/javascript\n```\n\nThis is server or deployment layer configuration; it cannot be set from frontend JavaScript.\n\n### CSP\n\nThe sandbox iframe is served via `srcdoc` with a strict Content-Security-Policy:\n\n```\ndefault-src 'none'\nscript-src 'nonce-{random}' 'unsafe-eval' {runtimeOrigin}\nconnect-src 'none'\nimg-src data: blob:\nstyle-src 'unsafe-inline'\nfont-src data:\nform-action 'none'\nbase-uri 'none'\n```\n\nA random nonce is generated for each frame instance. `unsafe-eval` is required because Slex source expression evaluation uses `eval()` inside the sandbox.\n\n### Sandbox attribute\n\nThe 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:\n\n```ts\nframe: {\n  unsafeAllowSameOrigin: true,  // only with explicit host acceptance\n  sandbox: \"allow-scripts allow-same-origin\"\n}\n```\n\nDo not add `allow-same-origin` to fix CORS or debugging issues.\n\n## postMessage bridge protocol\n\nThe host and sandbox communicate via `window.postMessage`. All messages are tagged with `channel: \"slexkit-secure\"`.\n\n### Host -Sandbox messages\n\n| Type | Purpose |\n|------|---------|\n| `mount` | Sends Slex source, policy, theme to render |\n| `dispose` | Tells sandbox to tear down |\n| `fetch-result` | Returns fetch response or error |\n| `slots` | Synchronizes artifact slot positions |\n\n### Sandbox -Host messages\n\n| Type | Purpose |\n|------|---------|\n| `ready` | Runner module loaded and listening |\n| `mounted` | Artifact render confirmed |\n| `disposed` | Sandbox teardown acknowledged |\n| `heartbeat` | Periodic liveness signal |\n| `error` | Mount or runtime error |\n| `fetch` | Proxied network request |\n| `slot-size` | Artifact slot height report |\n\nEvery 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.\n\nMessages are verified: the sandbox checks `event.source === window.parent`; the host checks `event.source === iframe.contentWindow`.\n\n## Artifact slot bridge\n\nMultiple 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.\n\nA `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.\n\n## Heartbeat watchdog\n\nWhen `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.\n\n## Fail-closed behavior\n\nIf the iframe cannot load the runtime, does not send a ready/mounted message, or the heartbeat times out, SlexKit:\n\n1. Removes the unresponsive iframe.\n2. Renders a `role=\"alert\"` diagnostic element with a description of the failure.\n3. Emits the same information via `console.error`.\n\nLoad timeout is configurable via `frame.loadTimeoutMs` (default: 8000ms).\n\n## Escape hatches\n\n### `unsafeInlineExecution`\n\nAllows 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.\n\n```ts\nmountSecureArtifact(script, container, {\n  policy,\n  hostAdapter,\n  unsafeInlineExecution: true\n});\n```\n\n### `unsafeAllowSameOrigin`\n\nAllows `allow-same-origin` in the sandbox attribute. **Reduces isolation strength**; only use when the host explicitly accepts the risk.\n\n```ts\nframe: {\n  sandbox: \"allow-scripts allow-same-origin\",\n  unsafeAllowSameOrigin: true\n}\n```\n\n## Sandbox hardening\n\nWhen the sandbox runner starts, it hardens the global scope:\n\n**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.\n\n**Blocked scheduling globals** -`setTimeout`, `setInterval`, `requestAnimationFrame` are replaced with functions that throw, directing code to `api.setTimeout()`, `api.setInterval()`, and `api.raf()`.\n\n**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.\n\n## Maintenance principles\n\n- New capabilities must define a policy field first, then an `api.*` method, then the bridge.\n- Slex source declarations are never an authorization source.\n- Default to opaque origin.\n- Always fail closed.\n- Log and error hooks are observational; they must not alter runtime behavior.",
      "hash": "6c5f7fb6"
    },
    {
      "id": "reference/packages",
      "group": "Reference",
      "title": "Packages",
      "summary": "Package roles, installation matrix, and packaging strategy.",
      "href": "/docs/reference/packages",
      "rawHref": "/docs/reference/packages.md",
      "sourcePath": "site/content/reference/packages/en-US.md",
      "body": "---\ntitle: Packages\ncategory: Reference\nstatus: ready\norder: 60\nsummary: \"SlexKit npm package roles, install combinations, publish contents, and release checks.\"\nslexkitRenderMode: component\n---\n\n# Packages\n\nSlexKit v0/beta package references list npm packages, install commands, and release checks.\n\n## Package Map\n\n```\nslexkit (root package)\n ├── runtime entry\n ├── Svelte component registrations\n ├── ToolHost\n ├── default styles\n └── secure iframe runner\n\n @slexkit/runtime ─── re-exports slexkit/runtime\n @slexkit/components-svelte ─── re-exports slexkit/components-svelte\n @slexkit/theme-shadcn ─── CSS only\n @slexkit/streamdown ─── React/Streamdown renderer\n @slexkit/assistant-ui ─── assistant-ui Streamdown text wrapper\n @slexkit/tiptap ─── framework-free Tiptap NodeView adapter\n @slexkit/mcp ─── read-only MCP server for AI agents\n```\n\n`@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.\n\n## slexkit (root)\n\nThe main implementation package. It contains the runtime engine, official Svelte components, ToolHost, and styles.\n\n```sh\nnpm install slexkit\n```\n\n```js\nimport { mount, disposeNamespace, boot } from \"slexkit\";\nimport \"slexkit/style.css\";       // default styles (includes all component CSS)\n```\n\n`slexkit/dist/style.css` is a compatibility alias for the same distributed CSS bundle; do not import both paths.\n\nVersion helpers are exported from both the root and runtime entries:\n\n```js\nimport { SLEXKIT_VERSION, SLEX_PROTOCOL_VERSION, getSlexKitInfo } from \"slexkit\";\n```\n\nThe root package also ships the `slex` CLI:\n\n```sh\nslex copy-runtime public/slexkit.runtime.js\nslex validate ./artifact.slex --mode secure\nslex validate --standard\n```\n\n`slex validate --standard` runs the bundled Slex conformance fixtures against the validator shipped with the package. Use `--json` for CI or agent consumption.\n\n## @slexkit/runtime\n\nComponent-free runtime entry point. Does not auto-register any official Svelte components.\n\n```sh\nnpm install slexkit @slexkit/runtime\n```\n\n```js\nimport { mount, register, createSecureRuntime } from \"@slexkit/runtime\";\n```\n\nUse this to register a custom component set instead of the bundled Svelte components.\n\n## @slexkit/components-svelte\n\nSide-effect import that registers all official Svelte components into the runtime registry.\n\n```sh\nnpm install slexkit @slexkit/runtime @slexkit/components-svelte\n```\n\n```js\nimport { mount } from \"@slexkit/runtime\";\nimport \"@slexkit/components-svelte\";\n```\n\nPublic component specs: action (1), component (1), content (6), data (1), disclosure (2), display (3), feedback (2), input (6), layout (4), navigation (1), tooling (3).\n\n## @slexkit/theme-shadcn\n\nCSS theme bundle (shadcn/ui compatible).\n\n```sh\nnpm install @slexkit/theme-shadcn\n```\n\n```js\nimport \"@slexkit/theme-shadcn/style.css\";\n```\n\n## @slexkit/streamdown\n\nReact/Streamdown custom renderer for Markdown-hosted SlexKit fences.\n\n```sh\nnpm install slexkit @slexkit/theme-shadcn @slexkit/streamdown streamdown react react-dom\n```\n\n```tsx\nimport { Streamdown } from \"streamdown\";\nimport { slexkitRenderer } from \"@slexkit/streamdown\";\nimport \"@slexkit/theme-shadcn/style.css\";\nimport \"@slexkit/streamdown/style.css\";\n\nexport function Message({ markdown }: { markdown: string }) {\n  return (\n    \n      {markdown}\n    \n  );\n}\n```\n\nProcesses `slex` fences. Supports both trusted and secure runtime modes.\n\n## @slexkit/assistant-ui\n\nassistant-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`.\n\n```sh\nnpm install slexkit @slexkit/theme-shadcn @slexkit/streamdown @slexkit/assistant-ui @assistant-ui/react @assistant-ui/react-streamdown streamdown react react-dom\n```\n\n```tsx\nimport { MessagePrimitive } from \"@assistant-ui/react\";\nimport { SlexKitAssistantStreamdownText } from \"@slexkit/assistant-ui\";\nimport \"@slexkit/theme-shadcn/style.css\";\nimport \"@slexkit/assistant-ui/style.css\";\n\nexport function AssistantMessage() {\n  return (\n    \n      {({ part }) =>\n        part.type === \"text\" ? (\n          \n        ) : null\n      }\n    \n  );\n}\n```\n\nThe runtime defaults to secure. assistant-ui tool calls and ToolHost flows still use their own integration layers.\n\n## @slexkit/tiptap\n\nTiptap extension for rendering explicit `slex` code blocks as SlexKit previews while preserving normal fenced code block Markdown roundtrip.\n\n```sh\nnpm install slexkit @slexkit/theme-shadcn @slexkit/tiptap @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extension-code-block @tiptap/markdown\n```\n\n```ts\nimport StarterKit from \"@tiptap/starter-kit\";\nimport { createSlexKitTiptapExtension } from \"@slexkit/tiptap\";\nimport \"@slexkit/theme-shadcn/style.css\";\nimport \"@slexkit/tiptap/style.css\";\n\nconst extensions = [\n  StarterKit.configure({ codeBlock: false }),\n  createSlexKitTiptapExtension({ artifactId: \"doc-1\" })\n];\n```\n\nThe 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.\n\n## Obsidian plugin\n\nThe official Obsidian plugin lives in a separate release repository: .\n\nInstall **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`.\n\nThe community plugin is marked desktop-only and compatible with Obsidian 1.5.0+.\n\nThe 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.\n\n## @slexkit/mcp\n\nRead-only MCP server for AI agents. It serves generated LLM docs, component metadata, examples, runtime docs, ToolHost docs, and Slex source validation.\n\n```sh\nnpx -y @slexkit/mcp\n```\n\nThe server does not modify project files. Use it when an agent needs SlexKit component or runtime context.\n\n## Installation matrix\n\n| Use case | Install command |\n|----------|----------------|\n| Quick start, everything included | `npm install slexkit` |\n| Component-free, custom components | `npm install slexkit @slexkit/runtime` |\n| With Svelte components | `npm install slexkit @slexkit/runtime @slexkit/components-svelte` |\n| Add shadcn theme | `npm install @slexkit/theme-shadcn` |\n| React/Streamdown host | `npm install slexkit @slexkit/theme-shadcn @slexkit/streamdown streamdown react react-dom` |\n| 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` |\n| Tiptap editor host | `npm install slexkit @slexkit/theme-shadcn @slexkit/tiptap @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extension-code-block @tiptap/markdown` |\n| Obsidian plugin | Install **SlexKit** from Obsidian Community Plugins |\n| AI agent MCP server | `npx -y @slexkit/mcp` |\n\n## v0 Package Layout\n\nIn 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.\n\n## Release Check\n\nCheck all scoped packages together before publishing:\n\n```sh\nbun run build\nbun run test\nbun run lint\nbun run smoke:release\nnpm pack --dry-run --json\nslex validate --standard --json\n```\n\nThe 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`.\n\nBefore 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.",
      "hash": "874bcece"
    },
    {
      "id": "reference/standard",
      "group": "Reference",
      "title": "Slex Standard Artifacts",
      "summary": "JSON Schema, component catalog, logic profile, capabilities catalog, conformance fixtures, and manifest.",
      "href": "/docs/reference/standard",
      "rawHref": "/docs/reference/standard.md",
      "sourcePath": "site/content/reference/standard/en-US.md",
      "body": "---\ntitle: Slex Standard Artifacts\ncategory: Reference\nstatus: ready\norder: 65\nsummary: \"JSON artifacts for the Slex envelope, component catalog, logic profile, capabilities, conformance fixtures, and manifest.\"\nslexkitRenderMode: component\n---\n\n# Slex Standard Artifacts\n\nSlexKit 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.\n\nThe JSON files are generated from the TypeScript runtime registry, component specs, runtime version constants, expression capability metadata, and conformance fixtures.\n\n## Files\n\n- [`/standard/slex-standard-manifest.json`](/standard/slex-standard-manifest.json): version, protocol, logic profile, artifact paths, and hashes.\n- [`/standard/slex-expression.schema.json`](/standard/slex-expression.schema.json): JSON Schema for the Slex envelope, `namespace`, `g`, `layout`, component keys, and directive fields.\n- [`/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.\n- [`/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.\n- [`/standard/slex-capabilities.catalog.json`](/standard/slex-capabilities.catalog.json): deterministic `std.*` functions and policy-gated `api.*` secure runtime capabilities.\n- [`/standard/slex-conformance.json`](/standard/slex-conformance.json): valid, warning, and invalid fixtures with stable expected diagnostic codes, paths, and values.\n\n## Validation Model\n\nValidation is parse-first:\n\n1. Parse the JavaScript object literal source.\n2. Validate the Slex envelope and component-key shape.\n3. Compare component names and props against the generated component catalog.\n4. Scan logic strings and source text against the logic profile.\n5. Return stable diagnostic and warning codes.\n\n`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.\n\nWarnings 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.\n\n## Run Conformance\n\nUse the bundled conformance runner to verify that SlexKit's validator still matches the published standard fixtures:\n\n```sh\nslex validate --standard\nslex validate --standard --json\nslex validate --standard --fixture valid-full-envelope\n```\n\nUse file validation for a single Slex source:\n\n```sh\nslex validate ./artifact.slex --mode secure\nslex validate ./artifact.slex --mode trusted --strict\n```\n\nConformance validates source shape, logic profile diagnostics, capability checks, and warning stability. It is not a visual renderer screenshot test.\n\n## Diagnostic Codes\n\nClients use `code`, `path`, and `value` for program logic. `message` is for display.\n\n| Code | Severity | Meaning |\n|---|---|---|\n| `syntax` | error | JavaScript object literal parsing failed. Returned as `diagnostic.code`, not a warning. |\n| `unsupported_protocol` | warning | The optional `slex` marker does not match the supported protocol version. |\n| `invalid_component_key` | warning | A component key does not match the `type:identifier` shape. |\n| `invalid_directive_type` | warning | A structural directive such as `$if`, `$for`, or `$key` has an invalid value type. |\n| `unknown_component` | warning | The component type is not present in the generated component catalog. |\n| `unknown_prop` | warning | A component prop is not declared by that component's public spec. |\n| `unknown_std_member` | warning | A logic expression references a `std.*` helper outside the published capability catalog. |\n| `unknown_api_member` | warning | A logic expression references an `api.*` member outside the secure runtime capability catalog. |\n| `native_secure_capability` | warning | Secure mode source uses native browser capability names such as `fetch`, timers, or `WebSocket`; use policy-gated `api.*` instead. |\n| `reserved_context_shadowing` | warning | `g` keys or component identifiers shadow reserved expression context names. |\n\nPaths 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.\n\n## Conformance Fixture Contract\n\n`slex-conformance.json` contains `valid`, `warning`, and `invalid` fixtures. Each fixture has an `id`, `mode`, source text, and an `expected` object.\n\n- `expected.ok` is the validator success state.\n- `expected.warnings` is the warning set for the fixture. The runner fails if an expected warning is missing or if an extra warning appears.\n- Warning matching uses `code`, and when present also `path` and `value`.\n- `expected.diagnostic` is the expected parse diagnostic code for invalid fixtures.\n- Fixture IDs stay stable. If behavior changes, add a new fixture ID.\n\nThe conformance suite checks source validation semantics only. It does not assert component screenshots, browser layout, CSS output, or host adapter lifecycle behavior.\n\n## Versioning Policy\n\nSlexKit exposes separate version fields:\n\n- `packageVersion`: npm package version, from `package.json`.\n- `protocolVersion`: accepted Slex source protocol marker, `0.1`.\n- `schemaVersion`: generated artifact schema generation, using date-style values.\n- `logicProfileVersion`: expression, context, stdlib, and secure capability profile version.\n\nCompatible package releases may update catalog hashes, add components or props, add examples, or improve messages without changing `protocolVersion`.\n\nChanges 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.\n\n## Difference From A2UI\n\nA2UI describes cross-platform declarative UI. SlexKit describes Markdown-embedded, stateful, executable UI artifacts; the host chooses trusted runtime or secure runtime.\n\nJSON 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.",
      "hash": "5dac0efd"
    },
    {
      "id": "reference/toolhost",
      "group": "Reference",
      "title": "ToolHost",
      "summary": "Tool call rendering, built-in templates, custom templates, and submit boundaries.",
      "href": "/docs/reference/toolhost",
      "rawHref": "/docs/reference/toolhost.md",
      "sourcePath": "site/content/reference/toolhost/en-US.md",
      "body": "---\ntitle: ToolHost\ncategory: Reference\nstatus: ready\norder: 70\nsummary: \"Structured user-input UI for confirmations, choices, forms, and templates.\"\nslexkitRenderMode: component\n---\n\n# ToolHost\n\nToolHost bridges tool calls to interactive UI. When a model asks for confirmation, a choice, or form input, ToolHost renders the structured UI in the browser and returns the user's response as a `ToolResult`.\n\n## Concepts\n\nWhen a model emits a tool call such as `confirm-action` or `fill-form`, ToolHost compiles it into a standard `SlexExpression` and mounts it using the core runtime. The mounted UI uses `submit:actions` to submit the user's input and settle a Promise.\n\nToolHost is **separate from display-oriented `slex` fences**. Display components render information; ToolHost components collect structured user input and return it programmatically.\n\n### Submit\n\n`submit:actions` reads the fields listed in `returnKeys`, calls the ToolHost runtime, and resolves the `ToolRenderHandle.promise` with a `ToolResult`.\n\nDo not use `submit` in display fences or component demos. Use `button` for ordinary interactions; use `submit:actions` only when the host is waiting for a structured tool result.\n\n## Public API\n\n### `renderToolCall(call, container) → ToolRenderHandle`\n\nCompiles a tool call into a SlexExpression, mounts it, and returns a handle.\n\n```ts\nfunction renderToolCall(call: ToolCall, container: HTMLElement): ToolRenderHandle;\n```\n\n```ts\ntype ToolRenderHandle = {\n  promise: Promise;  // Resolves when user submits or ignores\n  dispose: () => void;           // Clean up the rendered UI\n};\n\ntype ToolResult =\n  | { toolCallId?: string; toolName: string; status: \"submitted\"; value: Record }\n  | { toolCallId?: string; toolName: string; status: \"ignored\"; value: null };\n```\n\n**Usage:**\n\n```js\nimport { renderToolCall } from \"slexkit\";\n\nconst handle = renderToolCall(\n  {\n    id: \"call_001\",\n    name: \"confirm-action\",\n    arguments: {\n      title: \"Delete file?\",\n      description: \"This action cannot be undone.\",\n      confirmLabel: \"Delete\",\n      requireReason: true,\n    },\n  },\n  document.getElementById(\"tool-container\"),\n);\n\nhandle.promise.then((result) => {\n  console.log(result.status); // \"submitted\" or \"ignored\"\n  console.log(result.value);  // { confirmed: true, reason: \"Obsolete file\" }\n  handle.dispose();\n});\n```\n\n### `registerToolTemplate(name, compiler)`\n\nRegister a custom tool template. The compiler function receives the tool arguments and returns a `SlexExpression`.\n\n```ts\nfunction registerToolTemplate(name: string, compiler: ToolTemplateCompiler): void;\n\ntype ToolTemplateCompiler> = (\n  args: TArgs,\n  runtime: ToolRuntime,\n  call: ToolCall,\n) => SlexExpression;\n\ntype ToolRuntime = {\n  submit: (value: Record) => void;\n  ignore: () => void;\n};\n```\n\n## Built-in templates\n\n### `confirm-action`\n\nYes/no confirmation dialog. Supports an optional reason field.\n\n**Arguments (`ConfirmActionArguments`):**\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `title` | `string` | `\"Confirm action\"` | Dialog title |\n| `description` | `string` | — | Optional explanation text |\n| `confirmLabel` | `string` | `\"Confirm\"` | Submit button label |\n| `ignoreLabel` | `string` | `\"Ignore\"` | Cancel button label |\n| `requireReason` | `boolean` | `false` | Show a reason text input |\n| `reasonLabel` | `string` | `\"Reason\"` | Label for the reason input |\n| `reasonPlaceholder` | `string` | `\"Add a reason\"` | Placeholder for the reason input |\n\n**Result value:**\n\n| Key | Type | Description |\n|-----|------|-------------|\n| `confirmed` | `boolean` | Always `true` when submitted |\n| `reason` | `string` | User's reason text (only if `requireReason: true`) |\n\n**Example:**\n\n```js\nrenderToolCall({\n  name: \"confirm-action\",\n  arguments: {\n    title: \"Delete project?\",\n    description: \"This will permanently delete all files.\",\n    confirmLabel: \"Delete\",\n    requireReason: true,\n  },\n}, container);\n```\n\n### `choose-options` / `option-list`\n\nSingle or multi-select option list. `option-list` is an alias for `choose-options` — behavior is identical.\n\n**Arguments (`ChooseOptionsArguments` / `OptionListArguments`):**\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `title` | `string` | `\"Choose options\"` | Dialog title |\n| `description` | `string` | — | Optional explanation text |\n| `options` / `items` | `OptionListItem[]` | `[]` | List of selectable items |\n| `multiple` | `boolean` | `true` | Allow multiple selection |\n| `selected` | `string[]` | auto | Pre-selected item IDs |\n| `minSelected` | `number` | `0` | Minimum required selections |\n| `maxSelected` | `number` | `Infinity` | Maximum allowed selections |\n| `submitLabel` | `string` | `\"Submit\"` | Submit button label |\n| `ignoreLabel` | `string` | `\"Ignore\"` | Cancel button label |\n\n**OptionListItem:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `label` | `string` | Display text (required) |\n| `id` | `string` | Unique identifier (defaults to `value` or index) |\n| `value` | `string` | Submitted value (defaults to `id`) |\n| `description` | `string` | Secondary text shown after label |\n| `selected` | `boolean` | Pre-selected state |\n| `disabled` | `boolean` | Disabled state |\n\n**Rendering:**\n- When `multiple: true` (default): renders **checkboxes**\n- When `multiple: false`: renders a **radio group**\n\n**Result value:**\n\n| Key | Type | Description |\n|-----|------|-------------|\n| `selected` | `string[]` | IDs of selected items |\n\n**Example:**\n\n```js\nrenderToolCall({\n  name: \"choose-options\",\n  arguments: {\n    title: \"Select dependencies\",\n    options: [\n      { id: \"react\", label: \"React\", description: \"UI library\" },\n      { id: \"vue\", label: \"Vue\", description: \"Progressive framework\" },\n      { id: \"svelte\", label: \"Svelte\", description: \"Compiled framework\", selected: true },\n    ],\n    multiple: true,\n    minSelected: 1,\n    maxSelected: 2,\n  },\n}, container);\n```\n\n### `fill-form`\n\nMulti-field form with various field types.\n\n**Arguments (`FillFormArguments`):**\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `title` | `string` | `\"Fill form\"` | Form title |\n| `description` | `string` | — | Optional explanation text |\n| `fields` | `FormField[]` | `[]` | Form field definitions |\n| `values` | `Record` | — | Initial field values |\n| `submitLabel` | `string` | `\"Submit\"` | Submit button label |\n| `ignoreLabel` | `string` | `\"Ignore\"` | Cancel button label |\n\n**FormField:**\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `name` | `string` | (required) | Field name (used as key in result value) |\n| `type` | `FormFieldType` | `\"text\"` | Field type |\n| `label` | `string` | `name` | Display label |\n| `description` | `string` | — | Help text below the field |\n| `placeholder` | `string` | — | Input placeholder |\n| `required` | `boolean` | `false` | Require non-empty value to submit |\n| `disabled` | `boolean` | `false` | Disable the field |\n| `value` | `unknown` | — | Initial value |\n| `options` | `Array<{label, value}>` | — | Options for `select` type |\n\n**FormFieldType:**\n\n| Type | Renders | Description |\n|------|---------|-------------|\n| `text` | `` | Free-form text |\n| `number` | `` | Numeric input, value is `number \\| null` |\n| `engineering` | `` with SI prefix parsing | Accepts values like `\"10kΩ\"`, `\"100nF\"`, `\"1.5MegHz\"`. Parsed with `parseEngineeringNumber()`. State includes `raw`, `number`, `valid`, `prefix`, `unit`, `normalized` |\n| `select` | `