@webmcp-auto-ui/sdk 0.1.1 → 0.4.0

package/README.md

@@ -4,7 +4,7 @@ HyperSkill URL format, skills CRUD registry, and Svelte 5 canvas store.
 
 ## HyperSkill format
 
-A skill is a serialised UI state — a list of blocks with their data, plus metadata (MCP server, LLM, tags). It encodes to a URL parameter:
+A skill is a serialised UI state -- a list of blocks with their data, plus metadata (MCP server, LLM, tags). It encodes to a URL parameter:
 
 ```
 https://example.com/viewer?hs=base64(JSON)
@@ -12,13 +12,16 @@ https://example.com/viewer?hs=base64(JSON)
 
 Skills above 6 KB are compressed with `CompressionStream` (`gz.` prefix). Each version carries a SHA-256 hash of `source_url + content` for traceability. Hashes are chainable: each version can reference the hash of the previous one.
 
+The SDK re-exports `encode`, `decode`, `hash`, `diff`, and `getHsParam` from the [`hyperskills`](https://www.npmjs.com/package/hyperskills) NPM package:
+
 ```ts
-import { encodeHyperSkill, decodeHyperSkill, computeHash, diffSkills } from '@webmcp-auto-ui/sdk';
+import { encode, decode, hash, diff, getHsParam } from '@webmcp-auto-ui/sdk';
 
-const url = await encodeHyperSkill(skill, 'https://example.com/viewer');
-const skill = await decodeHyperSkill(url); // or pass raw ?hs= param
-const hash = await computeHash(sourceUrl, skill.content);
-const changed = diffSkills(prev.content, next.content); // ['blocks', 'meta']
+const url = await encode('https://example.com/viewer', JSON.stringify(skill));
+const { content } = await decode(url); // or pass raw ?hs= param
+const parsed = JSON.parse(content);
+const h = await hash(sourceUrl, JSON.stringify(parsed.content));
+const changed = diff(prev.content, next.content); // ['blocks', 'meta']
 ```
 
 ## Skills registry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webmcp-auto-ui/sdk",
-  "version": "0.1.1",
+  "version": "0.4.0",
   "description": "Skills CRUD, HyperSkill format, Svelte 5 stores",
   "license": "AGPL-3.0-or-later",
   "type": "module",
@@ -14,6 +14,9 @@
     "./canvas": {
       "svelte": "./src/canvas.ts",
       "import": "./src/canvas.ts"
+    },
+    "./canvas-vanilla": {
+      "import": "./src/canvas-vanilla.ts"
     }
   },
   "publishConfig": {
@@ -23,6 +26,9 @@
     "check": "svelte-check --tsconfig ./tsconfig.json",
     "build": "svelte-package -i src"
   },
+  "dependencies": {
+    "hyperskills": "^0.1.0"
+  },
   "peerDependencies": {
     "svelte": "^5.0.0"
   },

package/src/canvas-vanilla.ts

@@ -0,0 +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';

package/src/index.ts

@@ -1,19 +1,74 @@
 // @webmcp-auto-ui/sdk — public API
 
-// HyperSkill format
-export {
-  encodeHyperSkill,
-  decodeHyperSkill,
-  computeHash,
-  createVersion,
-  getHsParam,
-  diffSkills,
-} from './hyperskill/format.js';
-export type {
-  HyperSkill,
-  HyperSkillMeta,
-  HyperSkillVersion,
-} from './hyperskill/format.js';
+// HyperSkill types — project-specific vocabulary for skill serialization
+export interface HyperSkillMeta {
+  title?: string;
+  description?: string;
+  version?: string;
+  created?: string;
+  mcp?: string;
+  mcpName?: string;
+  llm?: string;
+  tags?: string[];
+  theme?: Record<string, string>;
+  hash?: string;
+  previousHash?: string;
+  chatSummary?: string;
+  provenance?: {
+    mcpServers?: string[];
+    toolsUsed?: string[];
+    toolCallCount?: number;
+    skillsReferenced?: string[];
+    llm?: string;
+    exportedAt?: string;
+  };
+}
+export interface HyperSkill {
+  meta: HyperSkillMeta;
+  content: unknown;
+}
+export interface HyperSkillVersion {
+  hash: string;
+  previousHash?: string;
+  timestamp: number;
+  skill: HyperSkill;
+}
+
+// HyperSkill encoding — powered by the `hyperskills` NPM package.
+// Raw functions re-exported for direct access:
+export { encode, decode, hash, diff, getHsParam } from 'hyperskills';
+
+// Typed convenience wrappers — prefer these in apps:
+import { encode, decode, hash } from 'hyperskills';
+
+export async function encodeHyperSkill(skill: HyperSkill, sourceUrl?: string): Promise<string> {
+  const base = sourceUrl ?? (typeof window !== 'undefined' ? window.location.href.split('?')[0] : 'https://example.com');
+  const json = JSON.stringify(skill);
+  // Auto-compress with gzip when payload exceeds 6 KB to keep URLs under nginx limits
+  const compress = json.length > 6144 ? 'gz' as const : undefined;
+  return encode(base, json, compress ? { compress } : {});
+}
+
+export async function decodeHyperSkill(urlOrParam: string): Promise<HyperSkill> {
+  const { content } = await decode(urlOrParam);
+  return JSON.parse(content) as HyperSkill;
+}
+
+export async function computeHash(sourceUrl: string, content: unknown): Promise<string> {
+  return hash(sourceUrl, JSON.stringify(content));
+}
+
+export async function createVersion(skill: HyperSkill, sourceUrl: string, previousHash?: string): Promise<HyperSkillVersion> {
+  const h = await computeHash(sourceUrl, skill.content);
+  return {
+    hash: h,
+    previousHash,
+    timestamp: Date.now(),
+    skill: { ...skill, meta: { ...skill.meta, hash: h, previousHash } },
+  };
+}
+
+export const diffSkills = diff;
 
 // Skills registry
 export {
@@ -29,5 +84,9 @@ export {
 } from './skills/registry.js';
 export type { Skill, SkillBlock } from './skills/registry.js';
 
+// MCP demo servers
+export { MCP_DEMO_SERVERS } from './mcp-demo-servers.js';
+export type { McpDemoServer } from './mcp-demo-servers.js';
+
 // Canvas store — browser-only (Svelte 5 runes), import directly from src:
 // import { canvas } from '@webmcp-auto-ui/sdk/canvas'

package/src/mcp-demo-servers.ts

@@ -0,0 +1,67 @@
+// @webmcp-auto-ui/sdk — MCP demo servers registry
+// Lists all MCP servers available on the production VM (demos.hyperskills.net)
+
+export interface McpDemoServer {
+  id: string;
+  name: string;
+  description: string;
+  url: string;
+  tags?: string[];
+}
+
+/**
+ * MCP demo servers available for webmcp-auto-ui demos.
+ * code4code has its own domain; others follow the pattern
+ * https://demos.hyperskills.net/<id>/mcp
+ */
+export const MCP_DEMO_SERVERS: McpDemoServer[] = [
+  {
+    id: 'code4code',
+    name: 'Code4Code',
+    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'],
+  },
+  {
+    id: 'hackernews',
+    name: 'Hacker News',
+    description: 'Hacker News stories, commentaires et classements.',
+    url: 'https://demos.hyperskills.net/mcp-hackernews/mcp',
+    tags: ['tech', 'news', 'communauté'],
+  },
+  {
+    id: 'metmuseum',
+    name: 'Met Museum',
+    description: 'Metropolitan Museum of Art — collections, œuvres, artistes.',
+    url: 'https://demos.hyperskills.net/mcp-metmuseum/mcp',
+    tags: ['art', 'musée', 'culture', 'collections'],
+  },
+  {
+    id: 'openmeteo',
+    name: 'Open-Meteo',
+    description: 'Données météorologiques — prévisions, historique, géolocalisation.',
+    url: 'https://demos.hyperskills.net/mcp-openmeteo/mcp',
+    tags: ['météo', 'climat', 'prévisions', 'géo'],
+  },
+  {
+    id: 'wikipedia',
+    name: 'Wikipedia',
+    description: 'Recherche et contenu Wikipedia — articles, résumés, catégories.',
+    url: 'https://demos.hyperskills.net/mcp-wikipedia/mcp',
+    tags: ['encyclopédie', 'savoir', 'recherche'],
+  },
+  {
+    id: 'inaturalist',
+    name: 'iNaturalist',
+    description: 'Observations naturalistes — espèces, taxons, statistiques biodiversité.',
+    url: 'https://demos.hyperskills.net/mcp-inaturalist/mcp',
+    tags: ['nature', 'biodiversité', 'observations', 'science-participative'],
+  },
+  {
+    id: 'datagouv',
+    name: 'data.gouv.fr',
+    description: 'Open data français — jeux de données publics, statistiques, référentiels.',
+    url: 'https://demos.hyperskills.net/mcp-datagouv/mcp',
+    tags: ['open-data', 'france', 'gouvernement', 'statistiques'],
+  },
+];

package/src/skills/registry.ts

@@ -1,6 +1,6 @@
 /**
- * Skills registry — in-memory CRUD for UI recipes/skills.
- * Each skill describes how to compose a UI from a set of blocks.
+ * Skills registry — in-memory CRUD for skills.
+ * Each skill is a set of instructions that help an agent use tools.
  */
 
 export interface SkillBlock {
@@ -8,6 +8,10 @@ export interface SkillBlock {
   data: Record<string, unknown>;
 }
 
+export interface ThemeOverrides {
+  [key: string]: string;
+}
+
 export interface Skill {
   id: string;
   name: string;
@@ -16,6 +20,7 @@ export interface Skill {
   mcpName?: string;
   llm?: string;
   tags?: string[];
+  theme?: ThemeOverrides;
   blocks: SkillBlock[];
   createdAt: number;
   updatedAt: number;

package/src/stores/canvas.svelte.ts

@@ -3,13 +3,16 @@
  * Manages blocks on the canvas, mode, MCP connection, chat history
  */
 
+import { decode } from 'hyperskills';
+
 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';
+  | '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';
+export type LLMId = 'haiku' | 'sonnet' | 'gemma-e2b' | 'gemma-e4b';
 
 export interface Block {
   id: string;
@@ -41,7 +44,7 @@ function msgId() {
 function createCanvas() {
   // ── State ────────────────────────────────────────────────────────────────
   let blocks = $state<Block[]>([]);
-  let mode = $state<Mode>('auto');
+  let mode = $state<Mode>('drag');
   let llm = $state<LLMId>('haiku');
   let mcpUrl = $state('');
   let mcpConnected = $state(false);
@@ -134,13 +137,20 @@ function createCanvas() {
   function setMcpError(err: string) {
     mcpConnected = false;
     mcpConnecting = false;
-    statusText = `● erreur: ${err.slice(0, 40)}`;
+    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() {
-    return {
+    const skill: Record<string, unknown> = {
       version: '1.0',
       name: 'skill-' + Date.now(),
       created: new Date().toISOString(),
@@ -148,22 +158,58 @@ function createCanvas() {
       llm,
       blocks: blocks.map((b) => ({ type: b.type, data: b.data })),
     };
+    if (Object.keys(themeOverrides).length > 0) skill.theme = themeOverrides;
+    return skill;
   }
 
-  function buildHyperskillParam(): string {
+  async function buildHyperskillParam(): Promise<string> {
     const json = JSON.stringify(buildSkillJSON());
-    return btoa(unescape(encodeURIComponent(json)));
+    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(/=+$/, '');
   }
 
-  function loadFromParam(param: string): boolean {
+  async function loadFromParam(param: string): Promise<boolean> {
     try {
-      const json = decodeURIComponent(escape(atob(param)));
+      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 }));
       }
@@ -173,25 +219,44 @@ function createCanvas() {
     }
   }
 
+  // ── 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 ────────────────────────────────────────────────────
   return {
-    // State getters (reactive)
+    // State getters + setters (reactive — supports bind:)
     get blocks() { return blocks; },
     get mode() { return mode; },
+    set mode(v: Mode) { mode = v; },
     get llm() { return llm; },
+    set llm(v: LLMId) { llm = v; },
     get mcpUrl() { return mcpUrl; },
+    set mcpUrl(v: string) { 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; },
     get statusText() { return statusText; },
     get statusColor() { return statusColor; },
     get blockCount() { return blockCount; },
     get isEmpty() { return isEmpty; },
 
-    // Setters
+    // Setters (kept for backward compat)
     setMode(m: Mode) { mode = m; },
     setLlm(l: LLMId) { llm = l; },
     setMcpUrl(u: string) { mcpUrl = u; },
@@ -206,8 +271,12 @@ function createCanvas() {
     // MCP
     setMcpConnecting, setMcpConnected, setMcpError,
 
+    // Theme
+    get themeOverrides() { return themeOverrides; },
+    setThemeOverrides,
+
     // HyperSkill
-    buildSkillJSON, buildHyperskillParam, loadFromParam,
+    buildSkillJSON, buildHyperskillParam, loadFromParam, loadFromUrl,
   };
 }
 

package/src/stores/canvas.ts

@@ -0,0 +1,350 @@
+/**
+ * Canvas state store — Vanilla (framework-agnostic)
+ * Manages blocks 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).
+ */
+
+import { decode } from 'hyperskills';
+
+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>;
+}
+
+export interface CanvasSnapshot {
+  blocks: Block[];
+  mode: Mode;
+  llm: LLMId;
+  mcpUrl: string;
+  mcpConnected: boolean;
+  mcpConnecting: boolean;
+  mcpName: string;
+  mcpTools: McpToolInfo[];
+  messages: ChatMsg[];
+  generating: boolean;
+  statusText: string;
+  statusColor: string;
+  themeOverrides: Record<string, string>;
+  blockCount: number;
+  isEmpty: boolean;
+}
+
+type Listener = () => void;
+
+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);
+}
+
+function createCanvasVanilla() {
+  // ── Subscribers ────────────────────────────────────────────────────────
+  const listeners = new Set<Listener>();
+  function notify() { listeners.forEach(fn => fn()); }
+
+  // ── State ──────────────────────────────────────────────────────────────
+  let _blocks: Block[] = [];
+  let _mode: Mode = 'drag';
+  let _llm: LLMId = 'haiku';
+  let _mcpUrl = '';
+  let _mcpConnected = false;
+  let _mcpConnecting = false;
+  let _mcpName = '';
+  let _mcpTools: McpToolInfo[] = [];
+  let _messages: ChatMsg[] = [];
+  let _generating = false;
+  let _statusText = '● aucun MCP connecté';
+  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];
+    notify();
+    return block;
+  }
+
+  function removeBlock(id: string) {
+    _blocks = _blocks.filter((b) => b.id !== id);
+    notify();
+  }
+
+  function updateBlock(id: string, data: Partial<Record<string, unknown>>) {
+    _blocks = _blocks.map((b) => b.id === id ? { ...b, data: { ...b.data, ...data } } : b);
+    notify();
+  }
+
+  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;
+    notify();
+  }
+
+  function clearBlocks() {
+    _blocks = [];
+    notify();
+  }
+
+  function setBlocks(newBlocks: Block[]) {
+    _blocks = newBlocks;
+    notify();
+  }
+
+  // ── Chat ───────────────────────────────────────────────────────────────
+  function addMsg(role: ChatMsg['role'], content: string, thinking = false): ChatMsg {
+    const msg: ChatMsg = { id: msgId(), role, content, thinking };
+    _messages = [..._messages, msg];
+    notify();
+    return msg;
+  }
+
+  function updateMsg(id: string, content: string, thinking = false) {
+    _messages = _messages.map((m) => m.id === id ? { ...m, content, thinking } : m);
+    notify();
+  }
+
+  function clearMessages() {
+    _messages = [];
+    notify();
+  }
+
+  // ── MCP ────────────────────────────────────────────────────────────────
+  function setMcpConnecting(connecting: boolean) {
+    _mcpConnecting = connecting;
+    if (connecting) {
+      _statusText = '● connexion…';
+      _statusColor = 'text-amber-400';
+    }
+    notify();
+  }
+
+  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';
+    }
+    notify();
+  }
+
+  function setMcpError(err: string) {
+    _mcpConnected = false;
+    _mcpConnecting = false;
+    _statusText = `● erreur: ${err}`;
+    _statusColor = 'text-red-400';
+    notify();
+  }
+
+  // ── Theme ──────────────────────────────────────────────────────────────
+  function setThemeOverrides(overrides: Record<string, string>) {
+    _themeOverrides = overrides;
+    notify();
+  }
+
+  // ── HyperSkill ─────────────────────────────────────────────────────────
+  function buildSkillJSON() {
+    const skill: Record<string, unknown> = {
+      version: '1.0',
+      name: 'skill-' + Date.now(),
+      created: new Date().toISOString(),
+      mcp: _mcpUrl,
+      llm: _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.')) {
+        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> }[];
+      };
+      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 }));
+      }
+      notify();
+      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 }));
+      notify();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // ── Snapshot ────────────────────────────────────────────────────────────
+  function getSnapshot(): CanvasSnapshot {
+    return {
+      blocks: _blocks,
+      mode: _mode,
+      llm: _llm,
+      mcpUrl: _mcpUrl,
+      mcpConnected: _mcpConnected,
+      mcpConnecting: _mcpConnecting,
+      mcpName: _mcpName,
+      mcpTools: _mcpTools,
+      messages: _messages,
+      generating: _generating,
+      statusText: _statusText,
+      statusColor: _statusColor,
+      themeOverrides: _themeOverrides,
+      blockCount: _blocks.length,
+      isEmpty: _blocks.length === 0,
+    };
+  }
+
+  // ── Subscribe ──────────────────────────────────────────────────────────
+  function subscribe(fn: Listener): () => void {
+    listeners.add(fn);
+    return () => { listeners.delete(fn); };
+  }
+
+  // ── Return public API ──────────────────────────────────────────────────
+  return {
+    // State getters + setters
+    get blocks() { return _blocks; },
+    get mode() { return _mode; },
+    set mode(v: Mode) { _mode = v; notify(); },
+    get llm() { return _llm; },
+    set llm(v: LLMId) { _llm = v; notify(); },
+    get mcpUrl() { return _mcpUrl; },
+    set mcpUrl(v: string) { _mcpUrl = v; notify(); },
+    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; notify(); },
+    get statusText() { return _statusText; },
+    get statusColor() { return _statusColor; },
+    get blockCount() { return _blocks.length; },
+    get isEmpty() { return _blocks.length === 0; },
+
+    // Setters (kept for backward compat)
+    setMode(m: Mode) { _mode = m; notify(); },
+    setLlm(l: LLMId) { _llm = l; notify(); },
+    setMcpUrl(u: string) { _mcpUrl = u; notify(); },
+    setGenerating(g: boolean) { _generating = g; notify(); },
+
+    // Block actions
+    addBlock, removeBlock, updateBlock, moveBlock, clearBlocks, setBlocks,
+
+    // Chat
+    addMsg, updateMsg, clearMessages,
+
+    // MCP
+    setMcpConnecting, setMcpConnected, setMcpError,
+
+    // Theme
+    get themeOverrides() { return _themeOverrides; },
+    setThemeOverrides,
+
+    // HyperSkill
+    buildSkillJSON, buildHyperskillParam, loadFromParam, loadFromUrl,
+
+    // Framework-agnostic reactivity
+    subscribe,
+    getSnapshot,
+  };
+}
+
+export const canvasVanilla = createCanvasVanilla();

package/tests/hyperskill.test.ts

@@ -1,74 +1,75 @@
 import { describe, it, expect } from 'vitest';
-import { computeHash, diffSkills, decodeHyperSkill, encodeHyperSkill } from '../src/hyperskill/format.js';
+import { hash, diff, decode, encode } from '../src/index.js';
 
-describe('computeHash', () => {
+describe('hash', () => {
   it('returns a 64-char hex SHA-256', async () => {
-    const hash = await computeHash('https://example.com', { foo: 'bar' });
-    expect(hash).toMatch(/^[0-9a-f]{64}$/);
+    const h = await hash('https://example.com', JSON.stringify({ foo: 'bar' }));
+    expect(h).toMatch(/^[0-9a-f]{64}$/);
   });
 
   it('is deterministic', async () => {
-    const a = await computeHash('https://x.com', { n: 1 });
-    const b = await computeHash('https://x.com', { n: 1 });
+    const a = await hash('https://x.com', JSON.stringify({ n: 1 }));
+    const b = await hash('https://x.com', JSON.stringify({ n: 1 }));
     expect(a).toBe(b);
   });
 
   it('differs for different inputs', async () => {
-    const a = await computeHash('https://x.com', { n: 1 });
-    const b = await computeHash('https://x.com', { n: 2 });
+    const a = await hash('https://x.com', JSON.stringify({ n: 1 }));
+    const b = await hash('https://x.com', JSON.stringify({ n: 2 }));
     expect(a).not.toBe(b);
   });
 });
 
-describe('diffSkills', () => {
+describe('diff', () => {
   it('returns empty for identical objects', () => {
-    expect(diffSkills({ a: 1, b: 'x' }, { a: 1, b: 'x' })).toEqual([]);
+    expect(diff({ a: 1, b: 'x' }, { a: 1, b: 'x' })).toEqual([]);
   });
 
   it('detects changed keys', () => {
-    const changed = diffSkills({ a: 1, b: 2 }, { a: 1, b: 3 });
+    const changed = diff({ a: 1, b: 2 }, { a: 1, b: 3 });
     expect(changed).toContain('b');
     expect(changed).not.toContain('a');
   });
 
   it('detects added keys', () => {
-    const changed = diffSkills({ a: 1 }, { a: 1, b: 2 });
+    const changed = diff({ a: 1 }, { a: 1, b: 2 });
     expect(changed).toContain('b');
   });
 
   it('detects removed keys', () => {
-    const changed = diffSkills({ a: 1, b: 2 }, { a: 1 });
+    const changed = diff({ a: 1, b: 2 }, { a: 1 });
     expect(changed).toContain('b');
   });
 
   it('handles non-object inputs', () => {
-    expect(diffSkills('x', 'x')).toEqual([]);
-    expect(diffSkills('x', 'y')).toContain('(root)');
+    expect(diff('x', 'x')).toEqual([]);
+    expect(diff('x', 'y')).toContain('(root)');
   });
 });
 
-describe('encodeHyperSkill / decodeHyperSkill', () => {
+describe('encode / decode', () => {
   // jsdom provides TextEncoder/TextDecoder and crypto.subtle
   it('round-trips a skill', async () => {
     const skill = {
       meta: { title: 'test', mcp: 'https://mcp.example.com', mcpName: 'example' },
       content: { blocks: [{ type: 'stat', data: { label: 'KPI', value: '42' } }] },
     };
-    const url = await encodeHyperSkill(skill, 'https://example.com/viewer');
+    const url = await encode('https://example.com/viewer', JSON.stringify(skill));
     expect(url).toContain('?hs=');
 
-    const decoded = await decodeHyperSkill(url);
+    const { content: raw } = await decode(url);
+    const decoded = JSON.parse(raw);
     expect(decoded.meta.title).toBe('test');
     expect(decoded.meta.mcp).toBe('https://mcp.example.com');
-    const content = decoded.content as typeof skill.content;
-    expect(content.blocks[0].type).toBe('stat');
+    expect(decoded.content.blocks[0].type).toBe('stat');
   });
 
   it('decodes from raw base64 param', async () => {
     const skill = { meta: { title: 'raw' }, content: { x: 1 } };
-    const url = await encodeHyperSkill(skill, 'https://example.com');
+    const url = await encode('https://example.com', JSON.stringify(skill));
     const param = new URL(url).searchParams.get('hs')!;
-    const decoded = await decodeHyperSkill(param);
+    const { content: raw } = await decode(param);
+    const decoded = JSON.parse(raw);
     expect(decoded.meta.title).toBe('raw');
   });
 });

package/src/hyperskill/format.ts

@@ -1,129 +0,0 @@
-/**
- * HyperSkill format — spec: https://hyperskills.net/
- * URL: https://example.com/page?hs=base64(content)
- * Compression: prefix "gz." for skills > 6KB
- * Traceability: SHA-256(source_url + content), chainable
- */
-
-export interface HyperSkillMeta {
-  title?: string;
-  description?: string;
-  version?: string;
-  created?: string;
-  mcp?: string;
-  mcpName?: string;
-  llm?: string;
-  tags?: string[];
-  hash?: string;
-  previousHash?: string;
-}
-
-export interface HyperSkill {
-  meta: HyperSkillMeta;
-  content: unknown;
-}
-
-export interface HyperSkillVersion {
-  hash: string;
-  previousHash?: string;
-  timestamp: number;
-  skill: HyperSkill;
-}
-
-export async function encodeHyperSkill(
-  skill: HyperSkill,
-  sourceUrl?: string
-): Promise<string> {
-  const base = sourceUrl ?? (typeof window !== 'undefined' ? window.location.href.split('?')[0] : 'https://example.com');
-  const json = JSON.stringify(skill);
-  const bytes = new TextEncoder().encode(json);
-  let param: string;
-
-  if (bytes.length > 6144 && typeof CompressionStream !== 'undefined') {
-    try {
-      const cs = new CompressionStream('gzip');
-      const writer = cs.writable.getWriter();
-      writer.write(bytes);
-      writer.close();
-      const compressed = await new Response(cs.readable).arrayBuffer();
-      const b64 = btoa(String.fromCharCode(...new Uint8Array(compressed)));
-      param = 'gz.' + b64;
-    } catch {
-      param = btoa(unescape(encodeURIComponent(json)));
-    }
-  } else {
-    param = btoa(unescape(encodeURIComponent(json)));
-  }
-
-  const url = new URL(base);
-  url.searchParams.set('hs', param);
-  return url.toString();
-}
-
-export async function decodeHyperSkill(urlOrParam: string): Promise<HyperSkill> {
-  let param: string;
-  if (urlOrParam.includes('=') || urlOrParam.includes('://') || urlOrParam.includes('?')) {
-    try {
-      const url = new URL(urlOrParam, typeof window !== 'undefined' ? window.location.href : 'https://example.com');
-      param = url.searchParams.get('hs') ?? urlOrParam;
-    } catch {
-      param = urlOrParam;
-    }
-  } else {
-    param = urlOrParam;
-  }
-
-  if (param.startsWith('gz.') && typeof DecompressionStream !== 'undefined') {
-    const b64 = param.slice(3);
-    const binary = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
-    const ds = new DecompressionStream('gzip');
-    const writer = ds.writable.getWriter();
-    writer.write(binary);
-    writer.close();
-    const json = await new Response(ds.readable).text();
-    return JSON.parse(json) as HyperSkill;
-  }
-
-  const json = decodeURIComponent(escape(atob(param)));
-  return JSON.parse(json) as HyperSkill;
-}
-
-export async function computeHash(sourceUrl: string, content: unknown): Promise<string> {
-  const text = sourceUrl + JSON.stringify(content);
-  const bytes = new TextEncoder().encode(text);
-  const buf = await crypto.subtle.digest('SHA-256', bytes);
-  return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, '0')).join('');
-}
-
-export async function createVersion(
-  skill: HyperSkill,
-  sourceUrl: string,
-  previousHash?: string
-): Promise<HyperSkillVersion> {
-  const hash = await computeHash(sourceUrl, skill.content);
-  return {
-    hash,
-    previousHash,
-    timestamp: Date.now(),
-    skill: { ...skill, meta: { ...skill.meta, hash, previousHash } },
-  };
-}
-
-export function getHsParam(): string | null {
-  if (typeof window === 'undefined') return null;
-  return new URLSearchParams(window.location.search).get('hs');
-}
-
-export function diffSkills(prev: unknown, next: unknown): string[] {
-  if (typeof prev !== 'object' || typeof next !== 'object' || !prev || !next) {
-    return prev !== next ? ['(root)'] : [];
-  }
-  const p = prev as Record<string, unknown>;
-  const n = next as Record<string, unknown>;
-  const keys = new Set([...Object.keys(p), ...Object.keys(n)]);
-  const changed: string[] = [];
-  for (const k of keys) {
-    if (JSON.stringify(p[k]) !== JSON.stringify(n[k])) changed.push(k);
-  }
-  return changed;
-}