slexkit 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,76 @@
 
 All notable changes to SlexKit.
 
+## v0.3.1 - Host stability and control rendering hardening
+
+### Added
+- Runtime style safety tests that block broad `:has()` selectors, `clip-path`, and slider track regressions in shipped CSS.
+- Regression coverage for disabled Switch, Checkbox, and Radio state attributes.
+
+### Changed
+- CI now installs dependencies with `bun install --frozen-lockfile` and runs lint before tests.
+- Disabled Switch, Checkbox, and Radio styling now uses explicit `data-disabled` attributes instead of broad relational selectors.
+- Select and sr-only helper styles avoid `clip-path` for better host and Obsidian CSS compatibility.
+
+### Fixed
+- Slider thumb rendering artifacts caused by painting the range track on the native input box.
+- Input focus visibility after removing custom engineering steppers.
+- Home RC example input labels now use native Input component labels instead of separate text labels.
+- Stat cards no longer clip updated text during cross-document state examples.
+- Markdown calculator examples no longer render duplicate section labels.
+
+## v0.3.0 - Examples overhaul with component audit and i18n
+
+### Added
+- Example gallery: 17 high-quality examples organized by usage scenario (Getting Started, Calculators, Data Browsing, Dashboards, Config Wizards, Decision Support, Platform Features)
+- English translations for all 17 example pages
+- `toolhost-demo`: real `renderToolCall` API with chat-style conversation UI
+- Example rendering infrastructure: `site/routes/examples.js`, `site/pages/examples.slex.js`, `site/data/examples.js`
+- Content discovery: `site/data/content-discovery.js` with locale fallback and allowed-slug filtering
+- `site/data/content-discovery.js`: `discoverExampleMarkdown()` with per-locale discovery
+- SEO metadata for example pages
+- `examples/minimal-cdn/index.html`: zero-build CDN usage example
+- Formula component (`src/components/svelte/content/Formula.svelte`) with KaTeX rendering
+- `src/engine/capabilities.ts`: structured capability docs for AI agents
+- `src/engine/validation.ts`: SPEC contract validation for component specs
+- `src/engine/stdlib.ts`: standard library with `math.clamp`, `math.safeDivide`, and other utilities
+- `src/engine/sandbox-runner.ts`: sandbox runner for secure runtime
+- Component state eval context shadowing test suite (`component-state-shadowing.test.ts`)
+- Collapsible and Callout double-rendering regression tests
+- Slider component name shadowing regression test
+- Tests for content, playground, select, tabs, slider, disclosure, feedback, policy-api
+
+### Changed
+- Examples reduced from 64 to 17 high-quality examples, organized by user story
+- Example source locale: `zh-CN` (with `en-US` translations)
+- `renderChildren` (`helpers.ts`) now clears existing content when children are present
+- Switch component now accepts `checked`/`value` props for initialization consistency with Checkbox
+- Site UI: DocsShell, DocRail, router, shell improvements
+- Components: Input, Select, Tabs, Table, PlaygroundMarkdown refinements
+- CSS: theme-shadcn, text-input, docs-shell styling updates
+- MCP: enhanced with structured capability docs
+
+### Fixed
+- Eval context shadowing: component names `g` and `api` no longer overwrite reserved context keys
+- `renderChildren` double rendering in Collapsible and Callout
+- Voltage divider summary typo ("输入输入电压")
+- Salary calculator fallback numbers to match actual calculator output
+- Tabs-and-branching: title and length conversion mismatch
+- 4 pre-existing test failures (ai-docs, page-structure, theme, markdown-content)
+- Toolhost test: added setup import to fix `document is not defined`
+- Badge stretching in grid layout
+- Project-dashboard syntax error
+- Salary-calculator rate configuration
+
+### Removed
+- 47 low-quality/duplicate examples (reduced from 64 to 17)
+- Dead "Fallback" copywriting from all example files
+- Post-slex explanatory text from example files
+- Unused `DialogShell.svelte` component
+- Orphaned `test-if` example directory
+- Agent-generated `docs/compose` planning files
+- Temporary `screenshot-*.png` files
+
 ## v0.2.0 - First public release
 
 ### Added

package/LICENSE

@@ -1,21 +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.
+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

@@ -15,7 +15,7 @@
     <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="version" src="https://img.shields.io/badge/version-0.3.1-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">
@@ -31,6 +31,8 @@ It is built for chat messages, documents, agent panels, tool results, and AI-aut
 
 ## Installation
 
+> 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.
+
 ```sh
 npm install slexkit
 ```
@@ -115,7 +117,6 @@ Markdown platforms without SlexKit support show the fallback text. Hosts with Sl
 | `@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.
@@ -127,7 +128,7 @@ See [Package Boundaries](site/content/reference/packages/en-US.md) for details.
 | Browser DOM | `mount()`, `ingest()`, `boot()`, `disposeNamespace()` |
 | Markdown renderers | `createSlexKitMarkdownRuntimeHost()` |
 | React / Streamdown | `@slexkit/streamdown` |
-| Obsidian | `@slexkit/obsidian` |
+| Obsidian | Install **SlexKit** from Community Plugins; release repo: <https://github.com/slexkit/obsidian-slexkit> |
 | AI agents | `@slexkit/mcp`, `llms.txt`, SlexKit skill docs |
 | Custom components | `register()`, `registerSvelteComponent()`, `registerSubset()` |
 

package/README.zh-CN.md

@@ -15,7 +15,7 @@
     <a href="README.md">English</a>
   </p>
   <p>
-    <img alt="version" src="https://img.shields.io/badge/version-0.2.0-18181b">
+    <img alt="version" src="https://img.shields.io/badge/version-0.3.1-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">
@@ -31,6 +31,8 @@
 
 ## 安装
 
+> 只想在 Obsidian 里使用 SlexKit？打开 **Settings -> Community plugins**，搜索 **SlexKit**，安装并启用即可。下面的 npm 安装方式主要面向需要把 SlexKit 接入网页、Markdown renderer、Streamdown 或自定义宿主的开发者。
+
 ```sh
 npm install slexkit
 ```
@@ -115,7 +117,6 @@ import "slexkit/style.css";
 | `@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)。
@@ -127,7 +128,7 @@ import "slexkit/style.css";
 | 浏览器 DOM | `mount()`、`ingest()`、`boot()`、`disposeNamespace()` |
 | Markdown 渲染器 | `createSlexKitMarkdownRuntimeHost()` |
 | React / Streamdown | `@slexkit/streamdown` |
-| Obsidian | `@slexkit/obsidian` |
+| Obsidian | 从 Community Plugins 安装 **SlexKit**；发布仓库：<https://github.com/slexkit/obsidian-slexkit> |
 | AI Agents | `@slexkit/mcp`、`llms.txt`、SlexKit skill 文档 |
 | 自定义组件 | `register()`、`registerSvelteComponent()`、`registerSubset()` |
 

package/dist/ai/llms-authoring.txt

@@ -7,6 +7,7 @@ SlexKit's agent-readable source is Markdown with explicit `slex` fences. Do not
 - 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 `std.*` for common calculations, formatting, units, and small statistics.
 - 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.
@@ -18,6 +19,7 @@ SlexKit's agent-readable source is Markdown with explicit `slex` fences. Do not
 - 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 use native `fetch`, `XMLHttpRequest`, `WebSocket`, `setTimeout`, or `requestAnimationFrame` in secure mode; use policy-gated `api.*` instead.
 - Do not invent `.mdx` routes for SlexKit docs.
 
 ## Display UI Example

package/dist/ai/llms-capabilities.txt

@@ -0,0 +1,126 @@
+# SlexKit Capabilities for LLMs
+
+Use `std.*` for pure deterministic calculations and formatting. Use `api.*` only for host-injected or secure-runtime capabilities that may require policy.
+
+## Expression Context
+
+- `g` (always): Reactive state proxy.
+- `std` (always): Pure deterministic SlexKit standard library.
+- `api` (host-injected): Host or secure runtime capability object.
+- `$event` (event handlers): Event payload for on* handlers.
+- `$item` ($for): Current array item.
+- `$index` ($for): Current item index.
+- `$key` ($for): Current item key.
+
+## std.math
+
+Small numeric helpers for common interactive calculations.
+
+- `std.math.clamp(value, min, max)`: Clamp a number into a range. Example: `std.math.clamp(g.score, 0, 100)`
+- `std.math.round(value, digits = 0)`: Round with a fixed number of decimal digits. Example: `std.math.round(g.latency, 1)`
+- `std.math.safeDivide(numerator, denominator, fallback = 0)`: Divide with a fallback for zero or invalid denominators. Example: `std.math.safeDivide(g.used, g.total, 0)`
+- `std.math.percent(part, total, digits = 1)`: Return part / total as a percentage number. Example: `std.math.percent(g.done, g.total, 1)`
+- `std.math.lerp(start, end, t)`: Linear interpolation. Example: `std.math.lerp(0, 100, g.progress)`
+
+## std.stats
+
+Finite-number aggregations for arrays.
+
+- `std.stats.sum(values)`: Sum finite numeric values. Empty arrays return 0. Example: `std.stats.sum(g.samples)`
+- `std.stats.mean(values)`: Average finite numeric values. Empty arrays return NaN. Example: `std.stats.mean(g.samples)`
+- `std.stats.min(values)`: Minimum finite numeric value. Empty arrays return NaN. Example: `std.stats.min(g.samples)`
+- `std.stats.max(values)`: Maximum finite numeric value. Empty arrays return NaN. Example: `std.stats.max(g.samples)`
+- `std.stats.median(values)`: Median finite numeric value. Empty arrays return NaN. Example: `std.stats.median(g.samples)`
+
+## std.format
+
+Deterministic display formatting with en-US defaults.
+
+- `std.format.fixed(value, digits = 2)`: Format a number with fixed decimal places. Example: `std.format.fixed(g.voltage, 3)`
+- `std.format.number(value, digits = 0, locale = 'en-US')`: Locale number formatting. Example: `std.format.number(g.requests)`
+- `std.format.compact(value, digits = 1, locale = 'en-US')`: Compact number formatting. Example: `std.format.compact(g.users)`
+- `std.format.percent(ratio, digits = 1)`: Format a ratio as a percentage string. Example: `std.format.percent(g.done / g.total, 1)`
+- `std.format.currency(value, currency = 'USD', locale = 'en-US')`: Format a currency value. Example: `std.format.currency(g.revenue, 'USD')`
+
+## std.units
+
+Small unit display helpers for common dashboards.
+
+- `std.units.withUnit(value, unit, digits = 2)`: Format a value with a unit suffix. Example: `std.units.withUnit(g.power, 'W', 1)`
+- `std.units.bytes(value, digits = 1)`: Format bytes as B, KB, MB, GB, TB, or PB. Example: `std.units.bytes(g.payloadBytes)`
+- `std.units.duration(ms, digits = 1)`: Format milliseconds as ms, s, min, or h. Example: `std.units.duration(g.elapsedMs)`
+- `std.units.si(value, unit = '', digits = 2)`: Format with SI prefixes. Example: `std.units.si(g.frequency, 'Hz', 2)`
+
+## Policy-Gated Runtime API
+
+- `api.get(url, options)` (network, secure default: denied): Policy-gated GET request.
+- `api.post(url, body, options)` (network, secure default: denied): Policy-gated POST request.
+- `api.fetch(url, options)` (network, secure default: denied): Policy-gated GET or POST request.
+- `api.setTimeout(fn, ms)` (timer, secure default: denied): Policy-gated timeout.
+- `api.clearTimeout(id)` (timer, secure default: denied): Clear a policy-gated timeout.
+- `api.setInterval(fn, ms)` (timer, secure default: denied): Policy-gated interval.
+- `api.clearInterval(id)` (timer, secure default: denied): Clear a policy-gated interval.
+- `api.raf(fn)` (animation, secure default: denied): Policy-gated animation frame.
+- `api.cancelRaf(id)` (animation, secure default: denied): Cancel a policy-gated animation frame.
+- `api.createCanvas(width, height)` (canvas, secure default: denied): Create a policy-counted canvas.
+- `api.getCanvasContext(canvas, contextId, options)` (canvas, secure default: denied): Get a policy-checked canvas context.
+- `api.onDispose(fn)` (lifecycle, secure default: available): Register runtime cleanup.
+- `api.now()` (lifecycle, secure default: available): Runtime clock.
+- `api.isTimeoutError(error)` (diagnostics, secure default: available): Check timeout errors.
+- `api.isNetworkError(error)` (diagnostics, secure default: available): Check network errors.
+- `api.isPolicyError(error)` (diagnostics, secure default: available): Check policy errors.
+- `api.errorMessage(error)` (diagnostics, secure default: available): Extract a displayable error message.
+
+Secure mode blocks native `fetch`, `XMLHttpRequest`, `WebSocket`, `setTimeout`, `setInterval`, and `requestAnimationFrame`. Use `api.get`, `api.post`, `api.fetch`, `api.setTimeout`, `api.setInterval`, and `api.raf` when host policy enables them.
+
+## Recipe: Std Calculator
+
+```slex
+{
+  slex: "0.1",
+  namespace: "std_calculator",
+  g: { done: 7, total: 12, samples: [120, 95, 143, 110], bytes: 1536000 },
+  layout: {
+    "card:summary": {
+      title: "Stdlib calculator",
+      "stat:progress": { label: "Progress", "$value": "std.format.percent(std.math.safeDivide(g.done, g.total), 1)" },
+      "stat:average": { label: "Average", "$value": "std.format.fixed(std.stats.mean(g.samples), 1)", unit: "ms" },
+      "stat:payload": { label: "Payload", "$value": "std.units.bytes(g.bytes)" }
+    }
+  }
+}
+```
+
+## Recipe: Secure Network Card
+
+```slex
+{
+  slex: "0.1",
+  namespace: "secure_network_card",
+  g: {
+    status: "idle",
+    async load() {
+      this.status = "loading";
+      try {
+        var result = await api.get("https://api.example.com/status", { credentials: "omit" });
+        this.status = "HTTP " + result.status;
+      } catch (error) {
+        this.status = api.isPolicyError(error) ? "blocked by policy" : api.errorMessage(error);
+      }
+    }
+  },
+  layout: {
+    "card:network": {
+      title: "Secure network card",
+      "button:load": { label: "Load", onclick: "g.load()" },
+      "text:status": { "$text": "g.status" }
+    }
+  }
+}
+```
+
+## Recipe: Timer and Animation Policy
+
+- Timers are disabled in secure mode unless `policy.timer.enabled` is true.
+- Use `api.setTimeout` and `api.setInterval`; do not use native scheduling globals.
+- Animation is disabled unless `policy.animation.enabled` is true; use `api.raf`.

package/dist/ai/llms-components.txt

@@ -2,7 +2,7 @@
 
 Use these components inside Markdown `slex` fences. Raw component docs are ordinary `.md` pages that preserve `slex` examples.
 
-Public component count: 28
+Public component count: 29
 
 ## Disclosure
 
@@ -39,6 +39,12 @@ Public component count: 28
 - [Slider](/docs/components/slider.md): `slider` - Numeric range input.
 - [Switch](/docs/components/switch.md): `switch` - Boolean switch input.
 
+## Display
+
+- [Formula](/docs/components/formula.md): `formula` - Reactive KaTeX formula display.
+- [Stat](/docs/components/stat.md): `stat` - Metric display.
+- [Text](/docs/components/text.md): `text` - Plain text display.
+
 ## Component
 
 - [Icon](/docs/components/icon.md): `icon` - Shared icon field capability.
@@ -52,11 +58,6 @@ Public component count: 28
 - [Progress](/docs/components/progress.md): `progress` - Progress bar.
 - [Toast](/docs/components/toast.md): `toast` - Transient notification.
 
-## Display
-
-- [Stat](/docs/components/stat.md): `stat` - Metric display.
-- [Text](/docs/components/text.md): `text` - Plain text display.
-
 ## Data
 
 - [Table](/docs/components/table.md): `table` - Simple data table.
@@ -265,6 +266,26 @@ No child components.
 
 ---
 
+## Formula API (`formula`)
+
+Category: Display
+Status: ready
+State mode: none
+Since: 0.1.0
+
+### Props
+- `tex` (string; optional; dynamic): KaTeX source to render.
+- `formula` (string; optional; dynamic): Alias for tex.
+- `value` (string; optional; dynamic): Alias for tex.
+- `displayMode` (boolean; optional; static; default: true): Render as display math when true; inline math when false.
+- `display` (boolean; optional; static; default: true): Alias for displayMode.
+- `block` (boolean; optional; static; default: true): Alias for displayMode.
+
+### Children
+No child components.
+
+---
+
 ## Grid API (`grid`)
 
 Category: Layout
@@ -334,7 +355,6 @@ Since: 0.1.0
 - `min` (string | number; optional; dynamic): Minimum value used by numeric input controls.
 - `max` (string | number; optional; dynamic): Maximum value used by numeric input controls.
 - `step` (string | number; optional; dynamic): Step size used by numeric input controls.
-- `controls` (boolean; optional; dynamic; default: true): Show decrement and increment buttons for numeric inputs.
 - `onchange` (write-expression; optional; static): Write expression invoked when the value changes.
 
 ### Children
@@ -634,6 +654,8 @@ Since: 0.1.0
 - `content` (string; optional; dynamic): Alias for text.
 - `label` (string; optional; dynamic): Alias for text.
 - `variant` (string; optional; static; default: "default"; values: default, muted): Text visual variant.
+- `color` (string; optional; dynamic): Optional CSS color for controlled previews.
+- `size` (string | number; optional; dynamic): Optional font size. Numbers are treated as px.
 - `class` (string; optional; static): Additional host-controlled CSS class.
 
 ### Children