@webmcp-auto-ui/sdk 0.4.0 → 2.5.0

package/README.md

@@ -54,12 +54,55 @@ Svelte 5 runes state for the composer canvas. Import from the `/canvas` subpath
 ```ts
 import { canvas } from '@webmcp-auto-ui/sdk/canvas';
 
-canvas.addBlock('stat', { label: 'Revenue', value: '€142K' });
+canvas.addWidget('stat', { label: 'Revenue', value: '€142K' });
+// → returns widget with id prefixed 'w_'
 canvas.setMcpConnected(true, 'my-server', tools);
 const param = canvas.buildHyperskillParam(); // base64 for ?hs=
 ```
 
-The canvas store manages blocks, mode (`auto` | `drag` | `chat`), MCP connection state, chat messages, and generating flag.
+The canvas store manages widgets, mode (`auto` | `drag` | `chat`), MCP connection state, chat messages, and generating flag.
+
+### Types
+
+- **`Widget`** — a rendered UI element with `id` (prefixed `w_`), `type`, and `data`
+- **`WidgetType`** — union of all supported widget type strings
+
+> **Migration**: `Block`, `BlockType`, and `addBlock()` are still exported as deprecated aliases. New code should use `Widget`, `WidgetType`, and `addWidget()`. Widget IDs use the `w_` prefix (previously `b_`).
+
+## MCP Demo Servers
+
+A built-in registry of 7 demo MCP server endpoints for testing and showcasing:
+
+```ts
+import { MCP_DEMO_SERVERS } from '@webmcp-auto-ui/sdk';
+
+// MCP_DEMO_SERVERS: Array<{ url: string; name: string; description: string }>
+// Includes: tricoteuses, weather, finance, etc.
+```
+
+Used by the `RemoteMCPserversDemo` component in `@webmcp-auto-ui/ui` to let users discover and connect to available servers.
+
+## HyperSkillMeta extensions
+
+Two new fields in `HyperSkillMeta`:
+
+- **`chatSummary`** — anonymized summary of the chat that produced the skill (generated via `summarizeChat()` from `@webmcp-auto-ui/agent`)
+- **`provenance`** — records the LLM model, MCP server, and timestamp that created the skill
+
+These fields enable traceability without exposing raw chat history.
+
+## Vanilla canvas store
+
+A framework-agnostic canvas store for non-Svelte environments:
+
+```ts
+import { canvas } from '@webmcp-auto-ui/sdk/canvas-vanilla';
+
+canvas.addBlock('stat', { label: 'Revenue', value: '$142K' });
+canvas.subscribe(() => console.log('state changed'));
+```
+
+Same API as the Svelte 5 store but uses plain callbacks instead of runes. Useful for vanilla JS, React, or Vue integrations.
 
 ## Install
 
@@ -67,7 +110,7 @@ The canvas store manages blocks, mode (`auto` | `drag` | `chat`), MCP connection
 npm install @webmcp-auto-ui/sdk
 ```
 
-Requires Svelte 5 for the canvas store. The HyperSkill utilities and registry are plain TypeScript with no framework dependency.
+The Svelte 5 canvas store requires Svelte 5. The vanilla canvas store, HyperSkill utilities, skills registry, and MCP demo servers are plain TypeScript with no framework dependency.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webmcp-auto-ui/sdk",
-  "version": "0.4.0",
+  "version": "2.5.0",
   "description": "Skills CRUD, HyperSkill format, Svelte 5 stores",
   "license": "AGPL-3.0-or-later",
   "type": "module",
@@ -27,7 +27,7 @@
     "build": "svelte-package -i src"
   },
   "dependencies": {
-    "hyperskills": "^0.1.0"
+    "hyperskills": "^0.1.4"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"

package/src/canvas-vanilla.ts

@@ -1,3 +1,3 @@
 // Canvas store — Vanilla (framework-agnostic), no Svelte dependency
 export { canvasVanilla } from './stores/canvas.js';
-export type { Block, BlockType, Mode, LLMId, ChatMsg, McpToolInfo, CanvasSnapshot } from './stores/canvas.js';
+export type { Widget, WidgetType, Block, BlockType, Mode, LLMId, ChatMsg, McpToolInfo, CanvasSnapshot } from './stores/canvas.js';

package/src/canvas.ts

@@ -1,3 +1,3 @@
 // Canvas store — Svelte 5 runes (browser-only, must be imported in Svelte components)
 export { canvas } from './stores/canvas.svelte.js';
-export type { Block, BlockType, Mode, LLMId, ChatMsg, McpToolInfo } from './stores/canvas.svelte.js';
+export type { Widget, WidgetType, Block, BlockType, Mode, LLMId, ChatMsg, McpToolInfo } from './stores/canvas.svelte.js';

package/src/hyperskills.ts

@@ -0,0 +1,47 @@
+/**
+ * Typed wrapper around the pure-JS `hyperskills` package.
+ * This avoids "no declaration file" errors in strict TS
+ * without requiring hyperskills to ship its own types.
+ */
+
+// @ts-ignore — hyperskills is intentionally pure JS
+import * as hs from 'hyperskills';
+
+export const encode: (
+  sourceUrl: string,
+  content: string,
+  options?: { compress?: 'gz' | 'br' },
+) => Promise<string> = hs.encode;
+
+export const decode: (
+  urlOrParam: string,
+) => Promise<{ sourceUrl: string; content: string }> = hs.decode;
+
+export const hash: (
+  sourceUrl: string,
+  content: string,
+  previousHash?: string,
+) => Promise<string> = hs.hash;
+
+export const diff: (prev: unknown, next: unknown) => unknown = hs.diff;
+
+export const getHsParam: () => string | null = hs.getHsParam;
+
+export const createVersion: (
+  sourceUrl: string,
+  content: string,
+  previousHash?: string,
+) => Promise<{ hash: string; content: string }> = hs.createVersion;
+
+export const sign: (hashHex: string, privateKey: CryptoKey) => Promise<string> = hs.sign;
+
+export const verify: (
+  hashHex: string,
+  signatureB64: string,
+  publicKey: CryptoKey,
+) => Promise<boolean> = hs.verify;
+
+export const generateKeyPair: () => Promise<{
+  publicKey: CryptoKey;
+  privateKey: CryptoKey;
+}> = hs.generateKeyPair;

package/src/index.ts

@@ -36,10 +36,10 @@ export interface HyperSkillVersion {
 
 // HyperSkill encoding — powered by the `hyperskills` NPM package.
 // Raw functions re-exported for direct access:
-export { encode, decode, hash, diff, getHsParam } from 'hyperskills';
+export { encode, decode, hash, diff, getHsParam } from './hyperskills.js';
 
 // Typed convenience wrappers — prefer these in apps:
-import { encode, decode, hash } from 'hyperskills';
+import { encode, decode, hash, diff } from './hyperskills.js';
 
 export async function encodeHyperSkill(skill: HyperSkill, sourceUrl?: string): Promise<string> {
   const base = sourceUrl ?? (typeof window !== 'undefined' ? window.location.href.split('?')[0] : 'https://example.com');

package/src/mcp-demo-servers.ts

@@ -11,13 +11,13 @@ export interface McpDemoServer {
 
 /**
  * MCP demo servers available for webmcp-auto-ui demos.
- * code4code has its own domain; others follow the pattern
+ * tricoteuses has its own domain; others follow the pattern
  * https://demos.hyperskills.net/<id>/mcp
  */
 export const MCP_DEMO_SERVERS: McpDemoServer[] = [
   {
-    id: 'code4code',
-    name: 'Code4Code',
+    id: 'tricoteuses',
+    name: 'Tricoteuses',
     description: 'Base de données parlementaire française — amendements, scrutins, députés, groupes politiques.',
     url: 'https://mcp.code4code.eu/mcp',
     tags: ['politique', 'france', 'parlement', 'open-data'],
@@ -64,4 +64,10 @@ export const MCP_DEMO_SERVERS: McpDemoServer[] = [
     url: 'https://demos.hyperskills.net/mcp-datagouv/mcp',
     tags: ['open-data', 'france', 'gouvernement', 'statistiques'],
   },
+  {
+    id: 'nasa',
+    name: 'NASA',
+    description: 'NASA — images spatiales, données astronomiques, rovers Mars, astéroïdes.',
+    url: 'https://demos.hyperskills.net/mcp-nasa/mcp',
+  },
 ];

package/src/skills/registry.ts

@@ -22,6 +22,12 @@ export interface Skill {
   tags?: string[];
   theme?: ThemeOverrides;
   blocks: SkillBlock[];
+  /** Target Svelte component (from former Core SkillDef) */
+  component?: string;
+  /** Presentation hints for the component */
+  presentation?: string;
+  /** Expected block types this skill can produce */
+  expectedBlockTypes?: string[];
   createdAt: number;
   updatedAt: number;
 }
@@ -94,7 +100,7 @@ const DEMO_SKILLS: Omit<Skill, 'id' | 'createdAt' | 'updatedAt'>[] = [
   {
     name: 'weather-dashboard',
     mcp: 'https://mcp.code4code.eu/mcp',
-    mcpName: 'code4code',
+    mcpName: 'tricoteuses',
     description: 'Météo locale avec température, conditions et prévisions',
     tags: ['météo', 'dashboard'],
     blocks: [
@@ -106,7 +112,7 @@ const DEMO_SKILLS: Omit<Skill, 'id' | 'createdAt' | 'updatedAt'>[] = [
   {
     name: 'kpi-overview',
     mcp: 'https://mcp.code4code.eu/mcp',
-    mcpName: 'code4code',
+    mcpName: 'tricoteuses',
     description: 'Vue KPIs : revenus, utilisateurs, churn',
     tags: ['kpi', 'dashboard'],
     blocks: [
@@ -119,7 +125,7 @@ const DEMO_SKILLS: Omit<Skill, 'id' | 'createdAt' | 'updatedAt'>[] = [
   {
     name: 'status-monitor',
     mcp: 'https://mcp.code4code.eu/mcp',
-    mcpName: 'code4code',
+    mcpName: 'tricoteuses',
     description: 'Monitoring état des services',
     tags: ['ops', 'monitoring'],
     blocks: [

package/src/stores/canvas.svelte.ts

@@ -1,282 +1,116 @@
 /**
- * Canvas state store — Svelte 5 runes
- * Manages blocks on the canvas, mode, MCP connection, chat history
+ * Canvas state store — Svelte 5 runes wrapper
+ * Thin reactive wrapper around the framework-agnostic canvas store (canvas.ts).
+ *
+ * All state mutations go through the vanilla store; this file only adds
+ * Svelte 5 $state/$derived reactivity via subscribe().
  */
 
-import { decode } from 'hyperskills';
+import { canvasVanilla } from './canvas.js';
+import type { Widget, WidgetType, Mode, LLMId, ChatMsg, McpToolInfo } from './canvas.js';
 
-export type BlockType =
-  | 'stat' | 'kv' | 'list' | 'chart' | 'alert' | 'code' | 'text' | 'actions' | 'tags'
-  | 'stat-card' | 'data-table' | 'timeline' | 'profile' | 'trombinoscope' | 'json-viewer'
-  | 'hemicycle' | 'chart-rich' | 'cards' | 'grid-data' | 'sankey' | 'map' | 'log'
-  | 'gallery' | 'carousel' | 'd3';
-
-export type Mode = 'auto' | 'drag' | 'chat';
-export type LLMId = 'haiku' | 'sonnet' | 'gemma-e2b' | 'gemma-e4b';
-
-export interface Block {
-  id: string;
-  type: BlockType;
-  data: Record<string, unknown>;
-}
-
-export interface ChatMsg {
-  id: string;
-  role: 'user' | 'assistant' | 'system';
-  content: string;
-  thinking?: boolean;
-}
-
-export interface McpToolInfo {
-  name: string;
-  description: string;
-  inputSchema?: Record<string, unknown>;
-}
-
-function uuid() {
-  return 'b_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 5);
-}
-
-function msgId() {
-  return 'm_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 5);
-}
+// Re-export types (including deprecated aliases)
+export type { Widget, WidgetType, Mode, LLMId, ChatMsg, McpToolInfo };
+export type { Block, BlockType, CanvasSnapshot } from './canvas.js';
 
 function createCanvas() {
-  // ── State ────────────────────────────────────────────────────────────────
-  let blocks = $state<Block[]>([]);
-  let mode = $state<Mode>('drag');
-  let llm = $state<LLMId>('haiku');
-  let mcpUrl = $state('');
-  let mcpConnected = $state(false);
-  let mcpConnecting = $state(false);
-  let mcpName = $state('');
-  let mcpTools = $state<McpToolInfo[]>([]);
-  let messages = $state<ChatMsg[]>([]);
-  let generating = $state(false);
-  let statusText = $state('● aucun MCP connecté');
-  let statusColor = $state('text-zinc-600');
-
-  // ── Derived ──────────────────────────────────────────────────────────────
+  // ── Reactive mirror of vanilla state ────────────────────────────────────
+  let blocks = $state<Widget[]>(canvasVanilla.blocks);
+  let mode = $state<Mode>(canvasVanilla.mode);
+  let llm = $state<LLMId>(canvasVanilla.llm);
+  let mcpUrl = $state(canvasVanilla.mcpUrl);
+  let mcpConnected = $state(canvasVanilla.mcpConnected);
+  let mcpConnecting = $state(canvasVanilla.mcpConnecting);
+  let mcpName = $state(canvasVanilla.mcpName);
+  let mcpTools = $state<McpToolInfo[]>(canvasVanilla.mcpTools);
+  let messages = $state<ChatMsg[]>(canvasVanilla.messages);
+  let generating = $state(canvasVanilla.generating);
+  let statusText = $state(canvasVanilla.statusText);
+  let statusColor = $state(canvasVanilla.statusColor);
+  let themeOverrides = $state<Record<string, string>>(canvasVanilla.themeOverrides);
+
+  // ── Derived ─────────────────────────────────────────────────────────────
   const blockCount = $derived(blocks.length);
   const isEmpty = $derived(blocks.length === 0);
 
-  // ── Block actions ────────────────────────────────────────────────────────
-  function addBlock(type: BlockType, data: Record<string, unknown> = {}): Block {
-    const block: Block = { id: uuid(), type, data };
-    blocks = [...blocks, block];
-    return block;
-  }
-
-  function removeBlock(id: string) {
-    blocks = blocks.filter((b) => b.id !== id);
-  }
-
-  function updateBlock(id: string, data: Partial<Record<string, unknown>>) {
-    blocks = blocks.map((b) => b.id === id ? { ...b, data: { ...b.data, ...data } } : b);
-  }
-
-  function moveBlock(fromId: string, toId: string) {
-    const fi = blocks.findIndex((b) => b.id === fromId);
-    const ti = blocks.findIndex((b) => b.id === toId);
-    if (fi < 0 || ti < 0 || fi === ti) return;
-    const next = [...blocks];
-    const [moved] = next.splice(fi, 1);
-    next.splice(ti, 0, moved);
-    blocks = next;
-  }
-
-  function clearBlocks() {
-    blocks = [];
-  }
-
-  function setBlocks(newBlocks: Block[]) {
-    blocks = newBlocks;
-  }
-
-  // ── Chat ─────────────────────────────────────────────────────────────────
-  function addMsg(role: ChatMsg['role'], content: string, thinking = false): ChatMsg {
-    const msg: ChatMsg = { id: msgId(), role, content, thinking };
-    messages = [...messages, msg];
-    return msg;
-  }
-
-  function updateMsg(id: string, content: string, thinking = false) {
-    messages = messages.map((m) => m.id === id ? { ...m, content, thinking } : m);
-  }
-
-  function clearMessages() {
-    messages = [];
-  }
-
-  // ── MCP ──────────────────────────────────────────────────────────────────
-  function setMcpConnecting(connecting: boolean) {
-    mcpConnecting = connecting;
-    if (connecting) {
-      statusText = '● connexion…';
-      statusColor = 'text-amber-400';
-    }
-  }
-
-  function setMcpConnected(
-    connected: boolean,
-    name?: string,
-    tools?: McpToolInfo[]
-  ) {
-    mcpConnected = connected;
-    if (name) mcpName = name;
-    if (tools) mcpTools = tools;
-    if (connected) {
-      statusText = `● ${name} · ${tools?.length ?? 0} tools`;
-      statusColor = 'text-teal-400';
-    } else {
-      statusText = '● aucun MCP connecté';
-      statusColor = 'text-zinc-600';
-    }
-  }
-
-  function setMcpError(err: string) {
-    mcpConnected = false;
-    mcpConnecting = false;
-    statusText = `● erreur: ${err}`;
-    statusColor = 'text-red-400';
-  }
-
-  // ── Theme ────────────────────────────────────────────────────────────────
-  let themeOverrides = $state<Record<string, string>>({});
-
-  function setThemeOverrides(overrides: Record<string, string>) {
-    themeOverrides = overrides;
-  }
-
-  // ── HyperSkill ───────────────────────────────────────────────────────────
-  function buildSkillJSON() {
-    const skill: Record<string, unknown> = {
-      version: '1.0',
-      name: 'skill-' + Date.now(),
-      created: new Date().toISOString(),
-      mcp: mcpUrl,
-      llm,
-      blocks: blocks.map((b) => ({ type: b.type, data: b.data })),
-    };
-    if (Object.keys(themeOverrides).length > 0) skill.theme = themeOverrides;
-    return skill;
-  }
-
-  async function buildHyperskillParam(): Promise<string> {
-    const json = JSON.stringify(buildSkillJSON());
-    const bytes = new TextEncoder().encode(json);
-    // Auto-compress with gzip when payload exceeds 6 KB to keep URLs under nginx limits
-    if (bytes.length > 6144) {
-      const cs = new CompressionStream('gzip');
-      const writer = cs.writable.getWriter();
-      writer.write(bytes);
-      writer.close();
-      const compressed = new Uint8Array(await new Response(cs.readable).arrayBuffer());
-      const b64 = btoa(String.fromCharCode(...compressed))
-        .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-      return 'gz.' + b64;
-    }
-    // Small payloads: plain base64url
-    return btoa(unescape(encodeURIComponent(json)))
-      .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-  }
-
-  async function loadFromParam(param: string): Promise<boolean> {
-    try {
-      let json: string;
-
-      if (param.startsWith('gz.')) {
-        // Compressed: gz.<base64url-encoded gzip data>
-        let b64 = param.slice(3).replace(/-/g, '+').replace(/_/g, '/');
-        while (b64.length % 4) b64 += '=';
-        const compressed = Uint8Array.from(atob(b64), c => c.charCodeAt(0));
-        const ds = new DecompressionStream('gzip');
-        const writer = ds.writable.getWriter();
-        writer.write(compressed);
-        writer.close();
-        json = await new Response(ds.readable).text();
-      } else {
-        // Plain base64url
-        let b64 = param.replace(/ /g, '+').replace(/-/g, '+').replace(/_/g, '/');
-        while (b64.length % 4) b64 += '=';
-        json = decodeURIComponent(escape(atob(b64)));
-      }
-
-      const skill = JSON.parse(json) as {
-        mcp?: string; llm?: LLMId;
-        theme?: Record<string, string>;
-        blocks?: { type: BlockType; data: Record<string, unknown> }[];
-      };
-      if (skill.mcp) mcpUrl = skill.mcp;
-      if (skill.llm) llm = skill.llm;
-      if (skill.theme) themeOverrides = skill.theme;
-      if (skill.blocks) {
-        blocks = skill.blocks.map((b) => ({ id: uuid(), type: b.type, data: b.data }));
-      }
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  // ── loadFromUrl ──────────────────────────────────────────────────────────
-  async function loadFromUrl(url: string): Promise<boolean> {
-    try {
-      const { content: raw } = await decode(url);
-      const decoded = JSON.parse(raw) as { meta?: Record<string, unknown>; content?: { blocks?: { type: BlockType; data: Record<string, unknown> }[] } };
-      if (decoded.meta?.mcp) mcpUrl = decoded.meta.mcp as string;
-      if (decoded.meta?.llm) llm = decoded.meta.llm as LLMId;
-      if (decoded.meta?.theme) themeOverrides = decoded.meta.theme as Record<string, string>;
-      if (decoded.content?.blocks) blocks = decoded.content.blocks.map((b) => ({ id: uuid(), type: b.type, data: b.data }));
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  // ── Return public API ────────────────────────────────────────────────────
+  // ── Sync from vanilla store on every change ─────────────────────────────
+  canvasVanilla.subscribe(() => {
+    const s = canvasVanilla.getSnapshot();
+    blocks = s.blocks;
+    mode = s.mode;
+    llm = s.llm;
+    mcpUrl = s.mcpUrl;
+    mcpConnected = s.mcpConnected;
+    mcpConnecting = s.mcpConnecting;
+    mcpName = s.mcpName;
+    mcpTools = s.mcpTools;
+    messages = s.messages;
+    generating = s.generating;
+    statusText = s.statusText;
+    statusColor = s.statusColor;
+    themeOverrides = s.themeOverrides;
+  });
+
+  // ── Return public API ───────────────────────────────────────────────────
   return {
     // State getters + setters (reactive — supports bind:)
     get blocks() { return blocks; },
     get mode() { return mode; },
-    set mode(v: Mode) { mode = v; },
+    set mode(v: Mode) { canvasVanilla.mode = v; },
     get llm() { return llm; },
-    set llm(v: LLMId) { llm = v; },
+    set llm(v: LLMId) { canvasVanilla.llm = v; },
     get mcpUrl() { return mcpUrl; },
-    set mcpUrl(v: string) { mcpUrl = v; },
+    set mcpUrl(v: string) { canvasVanilla.mcpUrl = v; },
     get mcpConnected() { return mcpConnected; },
     get mcpConnecting() { return mcpConnecting; },
     get mcpName() { return mcpName; },
     get mcpTools() { return mcpTools; },
     get messages() { return messages; },
     get generating() { return generating; },
-    set generating(v: boolean) { generating = v; },
+    set generating(v: boolean) { canvasVanilla.generating = v; },
     get statusText() { return statusText; },
     get statusColor() { return statusColor; },
     get blockCount() { return blockCount; },
     get isEmpty() { return isEmpty; },
 
     // Setters (kept for backward compat)
-    setMode(m: Mode) { mode = m; },
-    setLlm(l: LLMId) { llm = l; },
-    setMcpUrl(u: string) { mcpUrl = u; },
-    setGenerating(g: boolean) { generating = g; },
+    setMode(m: Mode) { canvasVanilla.setMode(m); },
+    setLlm(l: LLMId) { canvasVanilla.setLlm(l); },
+    setMcpUrl(u: string) { canvasVanilla.setMcpUrl(u); },
+    setGenerating(g: boolean) { canvasVanilla.setGenerating(g); },
+
+    // Widget actions (primary name)
+    addWidget: canvasVanilla.addWidget.bind(canvasVanilla),
+
+    // Backward compat alias
+    addBlock: canvasVanilla.addBlock.bind(canvasVanilla),
 
-    // Block actions
-    addBlock, removeBlock, updateBlock, moveBlock, clearBlocks, setBlocks,
+    // Block actions (kept as-is)
+    removeBlock: canvasVanilla.removeBlock.bind(canvasVanilla),
+    updateBlock: canvasVanilla.updateBlock.bind(canvasVanilla),
+    moveBlock: canvasVanilla.moveBlock.bind(canvasVanilla),
+    clearBlocks: canvasVanilla.clearBlocks.bind(canvasVanilla),
+    setBlocks: canvasVanilla.setBlocks.bind(canvasVanilla),
 
     // Chat
-    addMsg, updateMsg, clearMessages,
+    addMsg: canvasVanilla.addMsg.bind(canvasVanilla),
+    updateMsg: canvasVanilla.updateMsg.bind(canvasVanilla),
+    clearMessages: canvasVanilla.clearMessages.bind(canvasVanilla),
 
     // MCP
-    setMcpConnecting, setMcpConnected, setMcpError,
+    setMcpConnecting: canvasVanilla.setMcpConnecting.bind(canvasVanilla),
+    setMcpConnected: canvasVanilla.setMcpConnected.bind(canvasVanilla),
+    setMcpError: canvasVanilla.setMcpError.bind(canvasVanilla),
 
     // Theme
     get themeOverrides() { return themeOverrides; },
-    setThemeOverrides,
+    setThemeOverrides: canvasVanilla.setThemeOverrides.bind(canvasVanilla),
 
     // HyperSkill
-    buildSkillJSON, buildHyperskillParam, loadFromParam, loadFromUrl,
+    buildSkillJSON: canvasVanilla.buildSkillJSON.bind(canvasVanilla),
+    buildHyperskillParam: canvasVanilla.buildHyperskillParam.bind(canvasVanilla),
+    loadFromParam: canvasVanilla.loadFromParam.bind(canvasVanilla),
+    loadFromUrl: canvasVanilla.loadFromUrl.bind(canvasVanilla),
   };
 }
 

package/src/stores/canvas.ts

@@ -1,29 +1,38 @@
 /**
  * Canvas state store — Vanilla (framework-agnostic)
- * Manages blocks on the canvas, mode, MCP connection, chat history
+ * Manages widgets on the canvas, mode, MCP connection, chat history
  *
- * This is the framework-agnostic version of the canvas store.
- * For Svelte 5 reactivity, use @webmcp-auto-ui/sdk/canvas (Svelte runes)
- * or @webmcp-auto-ui/ui/canvas (adapter).
+ * This is the canonical, framework-agnostic version of the canvas store.
+ * For Svelte 5 reactivity, use the Svelte wrapper (canvas.svelte.ts)
+ * which re-exports this store with $state/$derived reactivity.
+ *
+ * Reactivity: subscribe(fn) / getSnapshot() pattern (useSyncExternalStore compatible).
  */
 
-import { decode } from 'hyperskills';
+import { encode, decode } from '../hyperskills.js';
 
-export type BlockType =
+export type WidgetType =
   | 'stat' | 'kv' | 'list' | 'chart' | 'alert' | 'code' | 'text' | 'actions' | 'tags'
   | 'stat-card' | 'data-table' | 'timeline' | 'profile' | 'trombinoscope' | 'json-viewer'
   | 'hemicycle' | 'chart-rich' | 'cards' | 'grid-data' | 'sankey' | 'map' | 'log'
-  | 'gallery' | 'carousel' | 'd3';
+  | 'gallery' | 'carousel' | 'd3' | 'js-sandbox'
+  | (string & {}); // accept arbitrary widget types from widget packs while keeping autocompletion
+
+/** @deprecated Use WidgetType */
+export type BlockType = WidgetType;
 
 export type Mode = 'auto' | 'drag' | 'chat';
 export type LLMId = 'haiku' | 'sonnet' | 'gemma-e2b' | 'gemma-e4b';
 
-export interface Block {
+export interface Widget {
   id: string;
-  type: BlockType;
+  type: WidgetType;
   data: Record<string, unknown>;
 }
 
+/** @deprecated Use Widget */
+export type Block = Widget;
+
 export interface ChatMsg {
   id: string;
   role: 'user' | 'assistant' | 'system';
@@ -38,7 +47,7 @@ export interface McpToolInfo {
 }
 
 export interface CanvasSnapshot {
-  blocks: Block[];
+  blocks: Widget[];
   mode: Mode;
   llm: LLMId;
   mcpUrl: string;
@@ -58,7 +67,7 @@ export interface CanvasSnapshot {
 type Listener = () => void;
 
 function uuid() {
-  return 'b_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 5);
+  return 'w_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 5);
 }
 
 function msgId() {
@@ -71,7 +80,7 @@ function createCanvasVanilla() {
   function notify() { listeners.forEach(fn => fn()); }
 
   // ── State ──────────────────────────────────────────────────────────────
-  let _blocks: Block[] = [];
+  let _blocks: Widget[] = [];
   let _mode: Mode = 'drag';
   let _llm: LLMId = 'haiku';
   let _mcpUrl = '';
@@ -85,14 +94,17 @@ function createCanvasVanilla() {
   let _statusColor = 'text-zinc-600';
   let _themeOverrides: Record<string, string> = {};
 
-  // ── Block actions ──────────────────────────────────────────────────────
-  function addBlock(type: BlockType, data: Record<string, unknown> = {}): Block {
-    const block: Block = { id: uuid(), type, data };
-    _blocks = [..._blocks, block];
+  // ── Widget actions ─────────────────────────────────────────────────────
+  function addWidget(type: WidgetType, data: Record<string, unknown> = {}): Widget {
+    const widget: Widget = { id: uuid(), type, data };
+    _blocks = [..._blocks, widget];
     notify();
-    return block;
+    return widget;
   }
 
+  /** @deprecated Use addWidget */
+  const addBlock = addWidget;
+
   function removeBlock(id: string) {
     _blocks = _blocks.filter((b) => b.id !== id);
     notify();
@@ -119,7 +131,7 @@ function createCanvasVanilla() {
     notify();
   }
 
-  function setBlocks(newBlocks: Block[]) {
+  function setBlocks(newBlocks: Widget[]) {
     _blocks = newBlocks;
     notify();
   }
@@ -200,47 +212,17 @@ function createCanvasVanilla() {
 
   async function buildHyperskillParam(): Promise<string> {
     const json = JSON.stringify(buildSkillJSON());
-    const bytes = new TextEncoder().encode(json);
-    // Auto-compress with gzip when payload exceeds 6 KB to keep URLs under nginx limits
-    if (bytes.length > 6144) {
-      const cs = new CompressionStream('gzip');
-      const writer = cs.writable.getWriter();
-      writer.write(bytes);
-      writer.close();
-      const compressed = new Uint8Array(await new Response(cs.readable).arrayBuffer());
-      const b64 = btoa(String.fromCharCode(...compressed))
-        .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-      return 'gz.' + b64;
-    }
-    // Small payloads: plain base64url
-    return btoa(unescape(encodeURIComponent(json)))
-      .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    const compress = json.length > 6144 ? 'gz' as const : undefined;
+    const url = await encode('https://x.local', json, compress ? { compress } : {});
+    return new URL(url).searchParams.get('hs')!;
   }
 
   async function loadFromParam(param: string): Promise<boolean> {
-    try {
-      let json: string;
-
-      if (param.startsWith('gz.')) {
-        let b64 = param.slice(3).replace(/-/g, '+').replace(/_/g, '/');
-        while (b64.length % 4) b64 += '=';
-        const compressed = Uint8Array.from(atob(b64), c => c.charCodeAt(0));
-        const ds = new DecompressionStream('gzip');
-        const writer = ds.writable.getWriter();
-        writer.write(compressed);
-        writer.close();
-        json = await new Response(ds.readable).text();
-      } else {
-        let b64 = param.replace(/ /g, '+').replace(/-/g, '+').replace(/_/g, '/');
-        while (b64.length % 4) b64 += '=';
-        json = decodeURIComponent(escape(atob(b64)));
-      }
-
-      const skill = JSON.parse(json) as {
-        mcp?: string; llm?: LLMId;
-        theme?: Record<string, string>;
-        blocks?: { type: BlockType; data: Record<string, unknown> }[];
-      };
+    function applySkill(skill: {
+      mcp?: string; llm?: LLMId;
+      theme?: Record<string, string>;
+      blocks?: { type: WidgetType; data: Record<string, unknown> }[];
+    }) {
       if (skill.mcp) _mcpUrl = skill.mcp;
       if (skill.llm) _llm = skill.llm;
       if (skill.theme) _themeOverrides = skill.theme;
@@ -248,6 +230,21 @@ function createCanvasVanilla() {
         _blocks = skill.blocks.map((b) => ({ id: uuid(), type: b.type, data: b.data }));
       }
       notify();
+    }
+
+    // Try hyperskills NPM decode (handles gz., br., and plain base64)
+    try {
+      const { content: json } = await decode(param);
+      applySkill(JSON.parse(json));
+      return true;
+    } catch { /* fall through to legacy */ }
+
+    // Fallback: legacy format (plain base64 with escape/unescape)
+    try {
+      let b64 = param.replace(/ /g, '+').replace(/-/g, '+').replace(/_/g, '/');
+      while (b64.length % 4) b64 += '=';
+      const json = decodeURIComponent(escape(atob(b64)));
+      applySkill(JSON.parse(json));
       return true;
     } catch {
       return false;
@@ -258,7 +255,7 @@ function createCanvasVanilla() {
   async function loadFromUrl(url: string): Promise<boolean> {
     try {
       const { content: raw } = await decode(url);
-      const decoded = JSON.parse(raw) as { meta?: Record<string, unknown>; content?: { blocks?: { type: BlockType; data: Record<string, unknown> }[] } };
+      const decoded = JSON.parse(raw) as { meta?: Record<string, unknown>; content?: { blocks?: { type: WidgetType; data: Record<string, unknown> }[] } };
       if (decoded.meta?.mcp) _mcpUrl = decoded.meta.mcp as string;
       if (decoded.meta?.llm) _llm = decoded.meta.llm as LLMId;
       if (decoded.meta?.theme) _themeOverrides = decoded.meta.theme as Record<string, string>;
@@ -325,8 +322,14 @@ function createCanvasVanilla() {
     setMcpUrl(u: string) { _mcpUrl = u; notify(); },
     setGenerating(g: boolean) { _generating = g; notify(); },
 
-    // Block actions
-    addBlock, removeBlock, updateBlock, moveBlock, clearBlocks, setBlocks,
+    // Widget actions (primary name)
+    addWidget,
+
+    // Backward compat alias
+    addBlock,
+
+    // Block actions (kept as-is)
+    removeBlock, updateBlock, moveBlock, clearBlocks, setBlocks,
 
     // Chat
     addMsg, updateMsg, clearMessages,

package/tests/registry.test.ts

@@ -75,7 +75,7 @@ describe('loadDemoSkills', () => {
     const skills = listSkills();
     expect(skills.length).toBe(3);
     expect(skills.every(s => s.mcp === 'https://mcp.code4code.eu/mcp')).toBe(true);
-    expect(skills.every(s => s.mcpName === 'code4code')).toBe(true);
+    expect(skills.every(s => s.mcpName === 'tricoteuses')).toBe(true);
   });
 
   it('does not overwrite existing skills', () => {