slexkit 0.2.0

package/package.json

@@ -0,0 +1,136 @@
+{
+  "name": "slexkit",
+  "version": "0.2.0",
+  "description": "Zero-build, Markdown-friendly reactive UI runtime for AI output.",
+  "author": "SlexKit contributors",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/slexkit/slexkit.git"
+  },
+  "homepage": "https://github.com/slexkit/slexkit#readme",
+  "bugs": {
+    "url": "https://github.com/slexkit/slexkit/issues"
+  },
+  "main": "./dist/slexkit.cjs",
+  "module": "./dist/slexkit.js",
+  "types": "./dist/types/index.d.ts",
+  "bin": {
+    "slex": "./scripts/cli.mjs"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "sideEffects": [
+    "**/*.css",
+    "dist/tooling.js",
+    "dist/components/*.js",
+    "dist/components/*.cjs"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/slexkit.js",
+      "require": "./dist/slexkit.cjs"
+    },
+    "./runtime": {
+      "types": "./dist/types/runtime.d.ts",
+      "import": "./dist/runtime.js",
+      "require": "./dist/runtime.cjs"
+    },
+    "./components": {
+      "types": "./dist/types/components/index.d.ts",
+      "import": "./dist/components/index.js"
+    },
+    "./components/*": {
+      "types": "./dist/types/components/*.d.ts",
+      "import": "./dist/components/*.js"
+    },
+    "./tooling": {
+      "types": "./dist/types/components/tooling.d.ts",
+      "import": "./dist/tooling.js"
+    },
+    "./style.css": "./dist/slexkit.css",
+    "./base.css": "./dist/base.css",
+    "./components/*.css": "./dist/components/*.css",
+    "./dist/slexkit.js": "./dist/slexkit.js",
+    "./dist/runtime.js": "./dist/runtime.js",
+    "./dist/style.css": "./dist/slexkit.css",
+    "./dist/base.css": "./dist/base.css",
+    "./dist/components/*.css": "./dist/components/*.css",
+    "./styles/*": {
+      "import": "./src/styles/*.css"
+    },
+    "./src-components/*": {
+      "import": "./src/components/svelte/*"
+    }
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "scripts/cli.mjs",
+    "src/styles/*.css",
+    "src/styles/components/*.css",
+    "src/components/svelte/**/*.svelte",
+    "src/components/svelte/**/*.ts",
+    "AGENTS.slexkit.md",
+    "CHANGELOG.md",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "bun run site/server.ts",
+    "build": "bun run build:core && bun run --filter @slexkit/streamdown build && bun run --filter @slexkit/obsidian build && bun run --filter @slexkit/mcp build",
+    "build:core": "bun run scripts/build-core.ts",
+    "ai:docs": "bun run scripts/generate-ai-docs.ts",
+    "version:sync": "bun run scripts/sync-version.ts",
+    "changelog:sync": "bun run scripts/sync-changelog.ts",
+    "docs:sync-spec": "bun run site/scripts/sync-doc-spec-blocks.ts",
+    "site:export": "bun run build:core && bun run site/scripts/export-static.ts",
+    "site:preview-static": "bunx serve site-static",
+    "copy-runtime": "node scripts/cli.mjs copy-runtime",
+    "preview": "bun run site/server.ts",
+    "smoke:release": "node scripts/release-smoke.mjs",
+    "test": "bun test --conditions browser --isolate --preload ./tests/setup.ts tests packages",
+    "test:watch": "bun test --conditions browser --isolate --watch --preload ./tests/setup.ts tests packages",
+    "lint": "eslint src/",
+    "format": "prettier --write src/",
+    "publish:npm": "node scripts/publish-npm.mjs"
+  },
+  "keywords": [
+    "reactive",
+    "ui",
+    "slex",
+    "expression",
+    "assembly",
+    "streaming",
+    "svelte"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/lang-markdown": "^6.5.0",
+    "@codemirror/state": "^6.6.0",
+    "@codemirror/view": "^6.43.0",
+    "@humanspeak/svelte-markdown": "^1.5.2",
+    "@phosphor-icons/core": "^2.1.1",
+    "codemirror": "^6.0.2",
+    "flowbite": "^4.0.2",
+    "flowbite-svelte": "^1.33.1",
+    "katex": "^0.17.0",
+    "svelte": "^5.55.9",
+    "svelte-highlight": "^7.9.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.4",
+    "@unocss/cli": "^66.7.0",
+    "@unocss/preset-wind4": "^66.7.0",
+    "eslint": "^9.0.0",
+    "jsdom": "^25.0.0",
+    "prettier": "^3.4.0",
+    "tailwindcss": "^4.3.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.59.3"
+  }
+}

package/scripts/cli.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { copyFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function help() {
+  console.log(`SlexKit CLI
+
+Usage:
+  slex copy-runtime [target]
+
+Commands:
+  copy-runtime  Copy dist/runtime.js to a public static path.
+
+Example:
+  slex copy-runtime public/slexkit.runtime.js
+`);
+}
+
+function copyRuntime(target = "public/slexkit.runtime.js") {
+  const source = resolve(packageRoot, "dist", "runtime.js");
+  const destination = resolve(process.cwd(), target);
+  mkdirSync(dirname(destination), { recursive: true });
+  copyFileSync(source, destination);
+  console.log(`Copied SlexKit runtime to ${destination}`);
+  console.log("Serve this file with:");
+  console.log("  Access-Control-Allow-Origin: *");
+  console.log("  Content-Type: text/javascript");
+}
+
+const command = process.argv[2];
+
+if (!command || command === "--help" || command === "-h") {
+  help();
+  process.exit(0);
+}
+
+if (command === "copy-runtime") {
+  copyRuntime(process.argv[3]);
+  process.exit(0);
+}
+
+console.error(`Unknown SlexKit command: ${command}`);
+help();
+process.exit(1);

package/skills/slexkit/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: slexkit
+description: Slash-command style `/slexkit` skill for SlexKit architecture, positioning, package boundaries, and display UI versus ToolHost decisions.
+---
+
+# SlexKit
+
+Use this skill as `/slexkit` for project overview and boundary decisions.
+
+## Core Position
+
+SlexKit is a zero-build, Markdown-friendly reactive UI runtime for AI output. It renders small interactive fragments in chat messages, documents, agent panels, and tool dashboards.
+
+## Boundaries
+
+- Display UI goes through Markdown `slex` fences or direct runtime mounting.
+- Structured user input goes through ToolHost.
+- Untrusted or agent-generated source uses secure runtime mode.
+- SlexKit raw docs are `.md` files with `slex` fences, not `.mdx`.
+- SlexKit is not a full app framework and not a React JSX generator.
+
+## Workflow
+
+1. Read `/llms.txt` first for navigation.
+2. Use `slexkitDocs` from `@slexkit/mcp` when available.
+3. Use `slexkitExamples` for component examples or host snippets.
+4. Use `slexkitValidate` before presenting generated Slex source.

package/skills/slexkit-author/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: slexkit-author
+description: Slash-command style `/author` skill for writing SlexKit display-oriented interactive UI as explicit Markdown `slex` fences with readable fallback.
+---
+
+# SlexKit Author
+
+Use this skill as `/author` when creating display-oriented SlexKit output.
+
+## Workflow
+
+1. Prefer the `@slexkit/mcp` tools when available: call `slexkitDocs`, `slexkitExamples`, and `slexkitValidate`.
+2. Read `/llms-authoring.txt` for authoring rules and `/llms-components.txt` for component props when MCP is unavailable.
+3. Emit a fenced Markdown block tagged `slex`.
+4. Use the envelope `{ namespace, g, layout }`.
+5. Put state and helper logic in `g`; put component tree fields in `layout`.
+6. Add Markdown fallback immediately after the fence.
+
+## Rules
+
+- Use display UI for summaries, status cards, metrics, calculators, progress, tables, and dashboards.
+- Component keys must be `type:identifier`.
+- Dynamic props use `$` read-pipes, for example `"$text": "g.done + ' done'"`.
+- Event handlers use `on*` write-pipes, for example `onclick: "g.count++"`.
+- Do not emit imports, JSX, Svelte, Vue, or app scaffolding.
+- Do not ask hosts to scan plain JavaScript or JSON blocks.
+- Do not use ToolHost unless the UI must return submitted or ignored structured data.
+- Do not request `.mdx`; SlexKit raw docs are `.md` files with `slex` fences.
+
+## Output Shape
+
+````md
+```slex
+{
+  namespace: "status",
+  g: { done: 3, total: 4 },
+  layout: {
+    "card:summary": {
+      title: "Status",
+      "text:count": { "$text": "g.done + '/' + g.total + ' complete'" },
+      "progress:bar": { "$value": "g.done / g.total * 100" }
+    }
+  }
+}
+```
+
+**Status:** 3/4 complete.
+````
+
+Validate generated source before presenting it when a local parser or MCP tool is available.

package/skills/slexkit-host-integration/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: slexkit-host-integration
+description: Slash-command style `/host` skill for integrating SlexKit into Markdown renderers, chat hosts, Streamdown, Obsidian, or custom host adapters.
+---
+
+# SlexKit Host Integration
+
+Use this skill as `/host` when adding SlexKit to a host application or documentation renderer.
+
+## Workflow
+
+1. Read `/llms-runtime.txt` or call `slexkitDocs` through `@slexkit/mcp` with `group: "Runtime"`.
+2. Determine the trust boundary:
+   - Trusted content: use `mount()` or trusted Markdown runtime mode.
+   - Untrusted or agent-generated content: use `mountSecureArtifact()` or secure Markdown runtime mode.
+3. Process only explicitly tagged `slex` fences.
+4. Preserve fallback Markdown in unsupported environments.
+5. Serve `slexkit.runtime.js` as a public ES module for secure iframe mode.
+
+## Integration Paths
+
+- Vanilla host: `createSlexKitMarkdownRuntimeHost`.
+- React/Streamdown: `@slexkit/streamdown`.
+- Obsidian: `@slexkit/obsidian`, readonly fenced block rendering.
+- Custom host: detect the `slex` code fence, pass source plus artifact id to the runtime host, dispose when the block is removed.
+
+## Rules
+
+- Do not scan arbitrary JavaScript, JSON, or untagged code blocks.
+- Do not add `.mdx` handling; use Markdown `.md` sources with explicit `slex` fences.
+- Do not bypass secure mode for untrusted model output.
+- Keep ToolHost separate from ordinary display fence rendering.
+- Use `runtimeHost`, `securePolicy`, `hostAdapter`, and `secureFrame` options instead of inventing a second lifecycle.

package/skills/slexkit-secure-runtime/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: slexkit-secure-runtime
+description: Slash-command style `/secure` skill for configuring SlexKit secure runtime, sandbox iframe isolation, host policy, and fail-closed behavior.
+---
+
+# SlexKit Secure Runtime
+
+Use this skill as `/secure` when rendering untrusted or agent-generated Slex source.
+
+## Workflow
+
+1. Read `/llms-runtime.txt` or call `slexkitDocs` through `@slexkit/mcp` with `group: "Security"` or `group: "Runtime"`.
+2. Use secure runtime mode for untrusted source.
+3. Serve `slexkit.runtime.js` as a public ES module.
+4. Configure host policy for sensitive capabilities.
+5. Keep the iframe sandboxed with an opaque origin.
+6. Dispose runtime artifacts when the owning Markdown block or message is removed.
+
+## Rules
+
+- Do not run untrusted source in the host realm.
+- Do not grant network, timers, canvas, or host APIs unless the host policy explicitly allows them.
+- Do not use security as a parser substitute: still process only explicit `slex` fences.
+- Keep fail-closed behavior. If runtime boot, heartbeat, policy, or parse validation fails, show fallback or diagnostics instead of executing in trusted mode.
+
+## Checks
+
+- `runtimeUrl` points to the built runtime module.
+- CORS and content type are correct for ES module loading.
+- Host policy is minimal.
+- Fallback Markdown remains readable if secure rendering fails.

package/skills/slexkit-toolhost/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: slexkit-toolhost
+description: Slash-command style `/toolhost` skill for SlexKit confirmations, choices, and forms that return structured submitted or ignored results.
+---
+
+# SlexKit ToolHost
+
+Use this skill as `/toolhost` when UI must return structured user input to the host.
+
+## When To Use
+
+Use ToolHost for:
+
+- confirmations and approvals
+- single or multi-choice option lists
+- forms
+- flows that must resolve a Promise with `submitted` or `ignored`
+
+Do not use ToolHost for ordinary display-only status cards, dashboards, calculators, summaries, or metrics. Those should be `slex` fences.
+
+## Workflow
+
+1. Read `/llms-toolhost.txt` or call `slexkitDocs` through `@slexkit/mcp` with `group: "ToolHost"`.
+2. Prefer built-in templates: `confirm-action`, `choose-options`, `option-list`, `fill-form`.
+3. Use `renderToolCall(call, container)` for host rendering.
+4. Await `handle.promise` and dispose the handle after completion.
+5. For custom templates, compile a `ToolCall` into a `SlexExpression` and include a `submit:actions` boundary.
+
+## Result Contract
+
+Tool results resolve to:
+
+```ts
+{ toolName: string; status: "submitted"; value: Record<string, unknown> }
+{ toolName: string; status: "ignored"; value: null }
+```
+
+Keep returned values small, explicit, and host-readable.

package/skills/slexkit-update/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: slexkit-update
+description: Slash-command style `/update` skill for regenerating SlexKit AI docs, MCP data, skills, and tests after docs, component, or public API changes.
+---
+
+# SlexKit Update
+
+Use this skill as `/update` after SlexKit docs, component specs, examples, or public APIs change.
+
+## Workflow
+
+1. Regenerate AI docs with `bun run ai:docs` or as part of `bun run build:core`.
+2. Rebuild the MCP package with `bun run --filter @slexkit/mcp build`.
+3. Verify `/llms.txt` remains a `.md` documentation index and contains no `.mdx`.
+4. Verify `slexkit-ai-manifest.json` page entries have `rawHref` values ending in `.md`.
+5. Run targeted AI tooling tests, then the normal project test gate.
+
+## Checks
+
+- `llms.txt` is navigable and grouped.
+- `llms-full.txt` preserves Markdown `slex` fences.
+- MCP exposes `slexkitDocs`, `slexkitExamples`, and `slexkitValidate`.
+- Skills still describe `/slexkit`, `/author`, `/host`, `/toolhost`, `/secure`, and `/update`.

package/src/components/svelte/InlineIcon.svelte

@@ -0,0 +1,66 @@
+<script lang="ts">
+  import { getIcon, iconCacheKey, loadIcon } from "../../icons/manager";
+  import type { IconState, IconWeight } from "../../icons/manager";
+  import { text } from "./helpers";
+
+  let {
+    name,
+    selected = false,
+    active = false,
+    pressed = false,
+    current = false,
+    weight,
+    className = "",
+    onIconLoad,
+  }: {
+    name?: unknown;
+    selected?: unknown;
+    active?: unknown;
+    pressed?: unknown;
+    current?: unknown;
+    weight?: IconWeight | null;
+    className?: string;
+    onIconLoad?: () => void;
+  } = $props();
+
+  let loadedIcons = $state<Record<string, string>>({});
+  let iconRequest = 0;
+  const iconName = $derived(text(name));
+
+  function iconState(): IconState {
+    return { selected, active, pressed, current, weight };
+  }
+
+  function hasStateVariant(): boolean {
+    return !!(selected || active || pressed || current || (weight && weight !== "regular"));
+  }
+
+  function icon(): string {
+    if (!iconName) return "";
+    const nextState = iconState();
+    const variantIcon = getIcon(iconName, nextState) || loadedIcons[iconCacheKey(iconName, nextState)] || "";
+    if (variantIcon) return variantIcon;
+    return hasStateVariant()
+      ? getIcon(iconName) || loadedIcons[iconCacheKey(iconName)] || ""
+      : "";
+  }
+
+  $effect(() => {
+    const nextName = iconName;
+    if (!nextName) return;
+    const nextState = iconState();
+    const key = iconCacheKey(nextName, nextState);
+    if (getIcon(nextName, nextState) || loadedIcons[key]) return;
+
+    const request = ++iconRequest;
+    void loadIcon(nextName, nextState).then((svg) => {
+      if (request !== iconRequest || !svg) return;
+      loadedIcons = { ...loadedIcons, [key]: svg };
+      onIconLoad?.();
+    });
+  });
+</script>
+
+{#if icon()}
+  <span class={`slex-icon ${className}`.trim()} aria-hidden="true">{@html icon()}</span>
+{/if}

package/src/components/svelte/adapter.ts

@@ -0,0 +1,76 @@
+import { flushSync, mount as mountSvelte, unmount } from "svelte";
+import type { ComponentRenderer } from "../../engine/types";
+import { attachComponentDisposer, configureComponentScope } from "../../engine/component-scope";
+import type { PropStore, PropValues, SvelteBuiltinComponent } from "./types";
+
+type Readable<T = unknown> = {
+  subscribe(run: (value: T) => void): () => void;
+};
+
+configureComponentScope({ flush: () => flushSync() });
+
+function isReadable(value: unknown): value is Readable {
+  return !!value &&
+    (typeof value === "object" || typeof value === "function") &&
+    typeof (value as Readable).subscribe === "function";
+}
+
+function createPropsStore(
+  props: Record<string, unknown>,
+): PropStore {
+  return {
+    subscribe(run) {
+      const current: PropValues = {};
+      const cleanups: Array<() => void> = [];
+      let ready = false;
+
+      const emit = () => {
+        if (ready) run({ ...current });
+      };
+
+      for (const [key, value] of Object.entries(props)) {
+        if (key.startsWith("on") && typeof value === "function") continue;
+        const propName = key.startsWith("$") ? key.slice(1) : key;
+        if (isReadable(value)) {
+          cleanups.push(value.subscribe((next) => {
+            current[propName] = next;
+            emit();
+          }));
+        } else {
+          current[propName] = value;
+        }
+      }
+
+      ready = true;
+      run({ ...current });
+      return () => {
+        for (const cleanup of cleanups) cleanup();
+      };
+    }
+  };
+}
+
+export function createSvelteRenderer(type: string, Component: SvelteBuiltinComponent): ComponentRenderer {
+  return (props, name, ctx) => {
+    const host = (ctx.document || document).createElement("div");
+    const instance = mountSvelte(Component, {
+      target: host,
+      props: {
+        componentName: name,
+        ctx,
+        props: createPropsStore(props),
+      },
+    });
+    flushSync();
+    const root = host.firstElementChild as HTMLElement | null;
+    if (!root) {
+      void unmount(instance);
+      return undefined;
+    }
+    root.remove();
+    attachComponentDisposer(root, () => {
+      void unmount(instance);
+    });
+    return root;
+  };
+}

package/src/components/svelte/bindProps.ts

@@ -0,0 +1,9 @@
+import type { PropStore, PropValues } from "./types";
+
+export function bindPropStore(
+  store: PropStore,
+  set: (value: PropValues) => void,
+): () => void {
+  return store.subscribe((next) => set(next));
+}
+

package/src/components/svelte/content/Badge.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+  import { bindPropStore } from "../bindProps";
+  import { text } from "../helpers";
+  import InlineIcon from "../InlineIcon.svelte";
+  import type { PropValues, SvelteComponentProps } from "../types";
+
+  let { props, componentName }: SvelteComponentProps = $props();
+  let p = $state<PropValues>({});
+  $effect(() => bindPropStore(props, (next) => (p = next)));
+
+  function tone(): string {
+    const raw = text(p.tone ?? p.type ?? p.variant, "neutral").toLowerCase();
+    if (raw === "danger" || raw === "error") return "destructive";
+    if (raw === "muted" || raw === "neutral" || raw === "default") return "neutral";
+    return raw;
+  }
+</script>
+
+<span class="slex-badge" data-tone={tone()}>{#if p.icon}<InlineIcon name={p.icon} className="slex-badge-icon" />{/if}<span class="slex-badge-label">{text(p.label ?? p.text ?? p.content ?? componentName)}</span></span>

package/src/components/svelte/content/Callout.svelte

@@ -0,0 +1,57 @@
+<script lang="ts">
+  import FlowbiteToast from "../../../../node_modules/flowbite-svelte/dist/toast/Toast.svelte";
+  import { bindPropStore } from "../bindProps";
+  import { renderChildren, text } from "../helpers";
+  import InlineIcon from "../InlineIcon.svelte";
+  import type { PropValues, SvelteComponentProps } from "../types";
+
+  let { props, ctx }: SvelteComponentProps = $props();
+  let p = $state<PropValues>({});
+  $effect(() => bindPropStore(props, (next) => (p = next)));
+
+  function tone(): string {
+    const raw = text(p.tone ?? p.type, "info").toLowerCase();
+    if (raw === "error" || raw === "destructive") return "danger";
+    if (raw === "neutral" || raw === "default" || raw === "muted") return "info";
+    return raw;
+  }
+
+  function titleText(): string {
+    return text(p.title ?? p.label ?? p.heading);
+  }
+
+  function descriptionText(): string {
+    return text(p.text ?? p.content ?? p.description ?? p.message);
+  }
+
+  function role(): "alert" | "note" {
+    return tone() === "danger" ? "alert" : "note";
+  }
+
+  function color(): "blue" | "green" | "yellow" | "red" | "gray" {
+    const kind = tone();
+    if (kind === "success") return "green";
+    if (kind === "warning") return "yellow";
+    if (kind === "danger") return "red";
+    if (kind === "muted" || kind === "neutral") return "gray";
+    return "blue";
+  }
+</script>
+
+<FlowbiteToast
+  class="slex-callout"
+  data-scope="callout"
+  data-tone={tone()}
+  color={color()}
+  role={role()}
+  aria-live={role() === "alert" ? "assertive" : "polite"}
+  dismissable={false}
+  align={false}
+  classes={{ icon: "slex-callout-mark", content: "slex-callout-content" }}
+>
+  {#snippet icon()}
+    <span aria-hidden="true"></span>
+  {/snippet}
+  {#if titleText()}<div class="slex-callout-title">{#if p.icon}<InlineIcon name={p.icon} className="slex-callout-icon" />{/if}<span>{titleText()}</span></div>{/if}
+  <div class="slex-callout-body" use:renderChildren={ctx}>{descriptionText()}</div>
+</FlowbiteToast>