slexkit 0.2.0

package/AGENTS.slexkit.md

@@ -0,0 +1,29 @@
+# SlexKit Agent Rules
+
+Use these rules when an AI agent writes or integrates SlexKit.
+
+## Output Shape
+
+- Use explicit `slex` fenced code blocks for display-oriented interactive UI.
+- Include a readable Markdown fallback after every generated fence.
+- Use the Slex envelope `{ namespace, g, layout }`.
+- Keep state, derived values, and helper functions in `g`.
+- Keep component structure in `layout`.
+- Use component keys in `type:identifier` form.
+- Use `$` read-pipes for dynamic props and `on*` write-pipes for event handlers.
+
+## Boundaries
+
+- Do not emit React, JSX, Svelte, Vue, imports, or build scaffolding inside `slex` fences.
+- Do not ask a host to scan plain JavaScript, JSON, or untagged code blocks.
+- Use ToolHost only for structured user input that must resolve to a submitted or ignored result.
+- Use ordinary `slex` fences for status cards, dashboards, calculators, metrics, and summaries.
+- Use the secure runtime for untrusted or agent-generated source.
+
+## Discovery
+
+- Read `/llms.txt` first for the short index.
+- Read `/llms-components.txt` before choosing component props.
+- Read `/llms-runtime.txt` before host integration.
+- Read `/llms-toolhost.txt` before building confirmations, choices, or forms.
+- Prefer the `@slexkit/mcp` read-only MCP server when available.

package/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to SlexKit.
+
+## v0.2.0 - First public release
+
+### Added
+- `@slexkit/mcp`: AI Agent Model Context Protocol server with `slexkitDocs`, `slexkitExamples`, `slexkitValidate` tools
+- Protocol marker: `"slex": "0.1"` required on all Slex expressions and ToolHost templates
+- SPEC contract validation: component specs are now validated against the runtime contract
+- Version sync automation (`scripts/sync-version.ts`) and changelog sync (`scripts/sync-changelog.ts`)
+- AI documentation generation pipeline with structured LLM-friendly output
+- Static site export with SEO metadata engine (`site/data/seo.js`, `site/scripts/export-static.ts`)
+- Chinese documentation for all reference and guide pages
+- Enhanced component state management with lifecycle hooks (`onMount`, `onUnmount`, `onUpdate`)
+
+### Changed
+- Switch component migrated from `checked` to `enabled` state mode
+- Documentation: restructured site content, synced en-US with zh-CN, added reference section
+- Theme: refined select styling, dropdown shadows, footer and info tone polish
+- AI docs generation enhanced with Chinese/English locale awareness
+
+### Fixed
+- Component spec alignment with documentation across all 28 components
+- Site routing and code block highlighting
+- Introduction and quick-start guide wording for clarity
+- Broken links and factual errors in component and reference documentation
+
+## v0.1.9
+
+### Added
+- Icon manager with Phosphor icon system (`registerIcon`, `registerIcons`, `getIcon`, `loadIcon`)
+- Expanded icon support across labeled components (badge, button, callout, etc.)
+- Icon docs page with registration API reference
+
+### Fixed
+- Refined component interactions in static site export
+- Tabs indicator animation restored
+- Callout and toast icon placement in titles
+- Numeric value display formatting
+
+### Changed
+- Site docs shell refactored for static export
+- Site navigation and theme controls alignment
+- Slex naming standardized across codebase
+
+## v0.1.8
+
+### Added
+- CSP-hardened secure runtime sandbox with heartbeat watchdog
+- `mountSecureArtifact()` for isolated iframe rendering
+- `createSlexKitMarkdownRuntimeHost()` for Markdown-hosted SlexKit blocks
+- Streamdown React renderer (`@slexkit/streamdown`)
+- Obsidian plugin adapter (`@slexkit/obsidian`)
+- Shadcn-compatible CSS theme (`@slexkit/theme-shadcn`)
+- Package boundary wrappers (`@slexkit/runtime`, `@slexkit/components-svelte`)
+- ToolHost with built-in templates: `confirm-action`, `choose-options`, `fill-form`
+
+### Changed
+- Component registration model: side-effect import registers all components
+- Styles reorganized into per-component CSS files
+- Build system: Bun.build with Svelte plugin, split ESM entries
+
+## v0.1.7
+
+### Added
+- `$for` list rendering with keyed reconciliation (delete / add-update-reorder / trim phases)
+- `$if` conditional rendering with enter/leave animation support
+- `$key` strategy: `$value`, property-based, or fallback to index
+- Component instance state modes: `value`, `checked`, `enabled`, `readable`, `none`
+- Lifecycle hooks: `g.onMount_<name>()`, `g.onUnmount_<name>()`, `g.onUpdate_<name>()`
+- Engineering number input with SI prefix parsing
+- Rich error diagnostics with line/column/excerpt display
+
+### Changed
+- Expression evaluation: `new Function()` compilation with reactive dependency tracking
+- Layout tree renderer now supports three rendering paths (normal, `$if`, `$for`)
+- `g` deep-merge preserves keys not present in the new state
+
+## v0.1.6 and earlier
+
+### Added
+- Reactive `g`/`layout` split with expression pipes (`$` read-pipes, `on*` write-pipes)
+- Custom fine-grained reactivity system (~280 lines, no external dependency)
+- Component registry with extensible renderer interface
+- Svelte 5 component adapter (creates stores from props, flushSync DOM)
+- `mount()`, `ingest()`, `boot()` entry points
+- 28 built-in Svelte components across 8 categories
+- `parseSlexSource()` DSL parser with `diagnoseSlexKitSource()` error reporting
+- Documentation site with interactive playground

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SlexKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+<div align="center">
+  <p>
+    <img src="site/assets/logo.svg" alt="SlexKit" width="84" height="84" />
+  </p>
+  <h1>SlexKit</h1>
+  <p><strong>Streaming Live EXpressions Kit</strong></p>
+  <p>
+    "Docs as tools, tools as docs." Give Markdown interactive power and make every AI output come alive.
+  </p>
+  <p>
+    <a href="site/content/guides/intro/en-US.md">Documentation</a> ·
+    <a href="site/content/components/accordion/en-US.md">Components</a> ·
+    <a href="site/content/reference/spec/en-US.md">Specification</a> ·
+    <a href="site/content/guides/ai-agents/en-US.md">AI / Agents</a> ·
+    <a href="README.zh-CN.md">简体中文</a>
+  </p>
+  <p>
+    <img alt="version" src="https://img.shields.io/badge/version-0.2.0-18181b">
+    <img alt="script" src="https://img.shields.io/badge/Slex-v0.1-18181b">
+    <img alt="TypeScript" src="https://img.shields.io/badge/runtime-TypeScript-3178c6">
+    <img alt="Svelte 5" src="https://img.shields.io/badge/components-Svelte_5-ff3e00">
+    <img alt="license" src="https://img.shields.io/badge/license-MIT-16a34a">
+  </p>
+</div>
+
+## Live interface blocks inside Markdown
+
+**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.
+
+It is built for chat messages, documents, agent panels, tool results, and AI-authored dashboards. It is not a full application framework.
+
+## Installation
+
+```sh
+npm install slexkit
+```
+
+```ts
+import { mount } from "slexkit";
+import "slexkit/style.css";
+```
+
+## Usage
+
+```html
+<div id="app"></div>
+
+<script type="module">
+  import { mount } from "slexkit";
+  import "slexkit/style.css";
+
+  mount(
+    {
+      slex: "0.1",
+      namespace: "hello",
+      g: { name: "World", count: 0 },
+      layout: {
+        "card:greeting": {
+          title: "Greeting",
+          "text:message": {
+            "$text": "'Hello, ' + g.name + '! Count: ' + g.count"
+          },
+          "button:add": {
+            label: "+1",
+            onclick: "g.count++"
+          }
+        }
+      }
+    },
+    document.getElementById("app")
+  );
+</script>
+```
+
+## Markdown Native
+
+SlexKit-capable hosts process explicit `slex` fences only. Plain `js`, `json`, and unlabeled code blocks stay inert.
+
+````md
+```slex
+{
+  slex: "0.1",
+  namespace: "status",
+  g: { done: 3, total: 4 },
+  layout: {
+    "badge:state": { label: "Ready", tone: "success" },
+    "text:summary": { "$text": "g.done + '/' + g.total + ' complete'" }
+  }
+}
+```
+
+**Status:** Ready. 3/4 complete.
+````
+
+Markdown platforms without SlexKit support show the fallback text. Hosts with SlexKit render the interactive UI.
+
+## What You Get
+
+- **Zero-build Slex source**: object literals with no imports, scaffolding, or component bundling in the generated output.
+- **Reactive `g` / `layout` model**: centralized state and logic with declarative component trees.
+- **Expression pipes**: `$` read expressions for dynamic props and `on*` write expressions for events.
+- **Directives**: `$if` and `$for` for conditional rendering and keyed list reconciliation.
+- **Official Svelte components**: 40+ layout, input, content, display, disclosure, feedback, and tooling components.
+- **Extensible registry**: custom component types, Svelte renderers, and component state modes.
+- **Trusted and secure runtimes**: host-realm rendering for trusted content, sandbox iframe rendering for untrusted source.
+- **ToolHost**: confirm, choose, and fill-form templates for structured AI tool-call UX.
+- **AI-friendly docs surface**: `llms.txt`, skills, and the `@slexkit/mcp` read-only MCP server.
+
+## Packages
+
+| Package | Install | Contents |
+| --- | --- | --- |
+| `slexkit` | `npm install slexkit` | Runtime, Svelte components, ToolHost, styles |
+| `@slexkit/runtime` | `npm install slexkit @slexkit/runtime` | Component-free runtime wrapper |
+| `@slexkit/components-svelte` | `npm install slexkit @slexkit/runtime @slexkit/components-svelte` | Svelte component registration |
+| `@slexkit/theme-shadcn` | `npm install @slexkit/theme-shadcn` | CSS theme tokens |
+| `@slexkit/streamdown` | `npm install slexkit @slexkit/theme-shadcn @slexkit/streamdown streamdown react react-dom` | React / Streamdown Markdown renderer |
+| `@slexkit/obsidian` | `npm install slexkit @slexkit/obsidian` | Obsidian plugin adapter |
+| `@slexkit/mcp` | `npx -y @slexkit/mcp` | Read-only MCP server for docs, examples, and source validation |
+
+See [Package Boundaries](site/content/reference/packages/en-US.md) for details.
+
+## Integrations
+
+| Host | Path |
+| --- | --- |
+| Browser DOM | `mount()`, `ingest()`, `boot()`, `disposeNamespace()` |
+| Markdown renderers | `createSlexKitMarkdownRuntimeHost()` |
+| React / Streamdown | `@slexkit/streamdown` |
+| Obsidian | `@slexkit/obsidian` |
+| AI agents | `@slexkit/mcp`, `llms.txt`, SlexKit skill docs |
+| Custom components | `register()`, `registerSvelteComponent()`, `registerSubset()` |
+
+## Security Runtime
+
+Trusted 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.
+
+Read the [Security Runtime](site/content/reference/security/en-US.md) docs before rendering unreviewed user or model output.
+
+## Documentation
+
+| Document | Topic |
+| --- | --- |
+| [Getting Started](site/content/guides/quick-start/en-US.md) | Install and render a first Markdown-friendly Slex source |
+| [Integration](site/content/guides/integration/en-US.md) | Streamdown, Obsidian, and custom host paths |
+| [Runtime model](site/content/reference/runtime/en-US.md) | Mounting, updates, namespace store, lifecycle |
+| [Slex usage reference](site/content/reference/usage/en-US.md) | Source structure, directives, expressions, events, custom components |
+| [Security runtime](site/content/reference/security/en-US.md) | Threat model, sandbox iframe, policy, postMessage bridge |
+| [Slex Specification](site/content/reference/spec/en-US.md) | Protocol v0.1, types, merge rules, lifecycle hooks |
+| [ToolHost](site/content/reference/toolhost/en-US.md) | Tool-call rendering and custom templates |
+| [Icon system](site/content/reference/icons/en-US.md) | Phosphor icons, custom registration, Iconify fallback |
+| [AI / Agents](site/content/guides/ai-agents/en-US.md) | `llms.txt`, MCP server, skills, and authoring rules |
+| [Changelog](CHANGELOG.md) | Release notes and notable changes |
+
+## Version Information
+
+```ts
+import { SLEXKIT_VERSION, SLEX_PROTOCOL_VERSION, getSlexKitInfo } from "slexkit";
+```
+
+The npm package version, component implementation version, and Slex protocol version are exposed separately. The current public protocol is `v0.1`.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,165 @@
+<div align="center">
+  <p>
+    <img src="site/assets/logo.svg" alt="SlexKit" width="84" height="84" />
+  </p>
+  <h1>SlexKit</h1>
+  <p><strong>Streaming Live EXpressions Kit</strong></p>
+  <p>
+    “文档即工具，工具即文档”，赋予 Markdown 可交互的能力，让 AI 的每一次输出都变得生动。
+  </p>
+  <p>
+    <a href="site/content/guides/intro/zh-CN.md">简介</a> ·
+    <a href="site/content/components/accordion/zh-CN.md">组件</a> ·
+    <a href="site/content/reference/spec/zh-CN.md">规范</a> ·
+    <a href="site/content/guides/ai-agents/zh-CN.md">AI / Agents</a> ·
+    <a href="README.md">English</a>
+  </p>
+  <p>
+    <img alt="version" src="https://img.shields.io/badge/version-0.2.0-18181b">
+    <img alt="script" src="https://img.shields.io/badge/Slex-v0.1-18181b">
+    <img alt="TypeScript" src="https://img.shields.io/badge/runtime-TypeScript-3178c6">
+    <img alt="Svelte 5" src="https://img.shields.io/badge/components-Svelte_5-ff3e00">
+    <img alt="license" src="https://img.shields.io/badge/license-MIT-16a34a">
+  </p>
+</div>
+
+## 把 Markdown 变成实时交互块
+
+**SlexKit** 会把显式 `slex` Markdown fence 变成带状态的实时 UI 块。Slex 源码只是一个 JavaScript 对象字面量：`g` 保存状态和逻辑，`layout` 描述组件树，浏览器运行时在原位置渲染结果。
+
+它适合聊天消息、文档、Agent 面板、工具结果和 AI 生成的仪表盘。它不是完整应用框架。
+
+## 安装
+
+```sh
+npm install slexkit
+```
+
+```ts
+import { mount } from "slexkit";
+import "slexkit/style.css";
+```
+
+## 使用
+
+```html
+<div id="app"></div>
+
+<script type="module">
+  import { mount } from "slexkit";
+  import "slexkit/style.css";
+
+  mount(
+    {
+      slex: "0.1",
+      namespace: "hello",
+      g: { name: "World", count: 0 },
+      layout: {
+        "card:greeting": {
+          title: "Greeting",
+          "text:message": {
+            "$text": "'Hello, ' + g.name + '! Count: ' + g.count"
+          },
+          "button:add": {
+            label: "+1",
+            onclick: "g.count++"
+          }
+        }
+      }
+    },
+    document.getElementById("app")
+  );
+</script>
+```
+
+## Markdown 原生输出
+
+支持 SlexKit 的宿主只处理显式 `slex` fence。普通 `js`、`json` 和未标记代码块都保持惰性，不会被猜测执行。
+
+````md
+```slex
+{
+  slex: "0.1",
+  namespace: "status",
+  g: { done: 3, total: 4 },
+  layout: {
+    "badge:state": { label: "Ready", tone: "success" },
+    "text:summary": { "$text": "g.done + '/' + g.total + ' complete'" }
+  }
+}
+```
+
+**状态：** Ready。3/4 complete.
+````
+
+不支持 SlexKit 的 Markdown 平台会显示 fallback 文本；支持 SlexKit 的宿主会渲染交互 UI。
+
+## 能力概览
+
+- **零构建 Slex 源码**：生成结果是对象字面量，不需要 imports、脚手架或组件打包。
+- **响应式 `g` / `layout` 模型**：状态和逻辑集中在 `g`，UI 结构由组件树声明。
+- **表达式管道**：`$` 读表达式用于动态属性，`on*` 写表达式用于事件。
+- **指令系统**：`$if` 和 `$for` 支持条件渲染和带 key 的列表协调。
+- **官方 Svelte 组件**：40+ 个 layout、input、content、display、disclosure、feedback、tooling 组件。
+- **可扩展注册表**：支持自定义组件类型、Svelte renderer 和组件状态模式。
+- **可信与安全双运行时**：可信内容在宿主域渲染，不可信源码在 sandbox iframe 中隔离渲染。
+- **ToolHost**：为 AI tool-call 提供确认、选择、填表等结构化交互模板。
+- **AI 友好文档面**：提供 `llms.txt`、skills 和只读 `@slexkit/mcp` MCP 服务。
+
+## 包
+
+| 包 | 安装 | 内容 |
+| --- | --- | --- |
+| `slexkit` | `npm install slexkit` | Runtime、Svelte 组件、ToolHost、样式 |
+| `@slexkit/runtime` | `npm install slexkit @slexkit/runtime` | 无组件运行时封装 |
+| `@slexkit/components-svelte` | `npm install slexkit @slexkit/runtime @slexkit/components-svelte` | Svelte 组件注册 |
+| `@slexkit/theme-shadcn` | `npm install @slexkit/theme-shadcn` | CSS 主题 token |
+| `@slexkit/streamdown` | `npm install slexkit @slexkit/theme-shadcn @slexkit/streamdown streamdown react react-dom` | React / Streamdown Markdown 渲染器 |
+| `@slexkit/obsidian` | `npm install slexkit @slexkit/obsidian` | Obsidian 插件适配器 |
+| `@slexkit/mcp` | `npx -y @slexkit/mcp` | 面向文档、示例和源码校验的只读 MCP 服务 |
+
+更多说明见 [Package Boundaries](site/content/reference/packages/zh-CN.md)。
+
+## 集成
+
+| 宿主 | 路径 |
+| --- | --- |
+| 浏览器 DOM | `mount()`、`ingest()`、`boot()`、`disposeNamespace()` |
+| Markdown 渲染器 | `createSlexKitMarkdownRuntimeHost()` |
+| React / Streamdown | `@slexkit/streamdown` |
+| Obsidian | `@slexkit/obsidian` |
+| AI Agents | `@slexkit/mcp`、`llms.txt`、SlexKit skill 文档 |
+| 自定义组件 | `register()`、`registerSvelteComponent()`、`registerSubset()` |
+
+## 安全运行时
+
+可信模式在宿主域内运行，适合应用自己生成或经过审核的源码。安全模式会把不可信 Slex 源码隔离到 sandbox iframe 中，并使用 opaque origin、基于 nonce 的 CSP、锁定全局变量、宿主代理网络访问和心跳 watchdog。
+
+渲染未审核的用户输入或模型输出前，请先阅读 [Security Runtime](site/content/reference/security/zh-CN.md)。
+
+## 文档
+
+| 文档 | 主题 |
+| --- | --- |
+| [快速开始](site/content/guides/quick-start/zh-CN.md) | 安装并渲染第一个 Markdown 友好的 Slex 源码 |
+| [集成指南](site/content/guides/integration/zh-CN.md) | Streamdown、Obsidian 和自定义宿主路径 |
+| [运行时模型](site/content/reference/runtime/zh-CN.md) | 挂载、更新、命名空间存储、生命周期 |
+| [Slex 用法参考](site/content/reference/usage/zh-CN.md) | 源码结构、指令、表达式、事件、自定义组件 |
+| [安全运行时](site/content/reference/security/zh-CN.md) | 威胁模型、sandbox iframe、策略、postMessage 桥接 |
+| [Slex 规范](site/content/reference/spec/zh-CN.md) | 协议 v0.1、类型、合并规则、生命周期钩子 |
+| [ToolHost](site/content/reference/toolhost/zh-CN.md) | Tool-call 渲染和自定义模板 |
+| [图标系统](site/content/reference/icons/zh-CN.md) | Phosphor 图标、自定义注册、Iconify fallback |
+| [AI / Agents](site/content/guides/ai-agents/zh-CN.md) | `llms.txt`、MCP 服务、skills 和创作规则 |
+| [更新日志](CHANGELOG.md) | 发布说明和重要变更 |
+
+## 版本信息
+
+```ts
+import { SLEXKIT_VERSION, SLEX_PROTOCOL_VERSION, getSlexKitInfo } from "slexkit";
+```
+
+npm 包版本、组件实现版本和 Slex 协议版本会分别暴露。当前公开协议是 `v0.1`。
+
+## 许可协议
+
+MIT

package/dist/ai/llms-authoring.txt

@@ -0,0 +1,44 @@
+# SlexKit Authoring Rules for LLMs
+
+SlexKit's agent-readable source is Markdown with explicit `slex` fences. Do not use `.mdx`; `slex` fences are the interactive layer.
+
+## Always Do
+
+- Emit explicit `slex` fenced code blocks for display-oriented interactive UI.
+- Use a Slex expression envelope: `slex`, `namespace`, `g`, and `layout`.
+- Put mutable state and helper functions in `g`; put component structure in `layout`.
+- Use component keys in `type:identifier` form, such as `card:summary`.
+- Use `$` read-pipes for dynamic props and `on*` write-pipes for event handlers.
+- Include readable Markdown fallback text after the fence.
+- Use secure runtime integration for untrusted or agent-generated source.
+
+## Do Not
+
+- Do not emit imports, JSX, Svelte, Vue, or project scaffolding inside `slex` fences.
+- Do not ask hosts to scan plain JavaScript, JSON, or untagged code blocks.
+- Do not wrap ordinary status cards or summaries in ToolHost.
+- Do not bypass the sandbox for untrusted source.
+- Do not invent `.mdx` routes for SlexKit docs.
+
+## Display UI Example
+
+```slex
+{
+  slex: "0.1",
+  namespace: "release_status",
+  g: { done: 3, total: 4 },
+  layout: {
+    "card:summary": {
+      title: "Release status",
+      "text:count": { "$text": "g.done + '/' + g.total + ' complete'" },
+      "progress:bar": { "$value": "g.done / g.total * 100" }
+    }
+  }
+}
+```
+
+**Fallback:** Release status: 3/4 complete.
+
+## ToolHost Boundary
+
+Use ToolHost only when the UI must return structured user input to the host, such as confirmations, option lists, or forms. Display-only dashboards, metrics, and status blocks should stay as `slex` fences.