@webmcp-auto-ui/sdk 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# @webmcp-auto-ui/sdk
+
+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:
+
+```
+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.
+
+```ts
+import { encodeHyperSkill, decodeHyperSkill, computeHash, diffSkills } 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']
+```
+
+## Skills registry
+
+In-memory CRUD store with change listeners.
+
+```ts
+import { createSkill, updateSkill, deleteSkill, listSkills, loadDemoSkills, onSkillsChange } from '@webmcp-auto-ui/sdk';
+
+loadDemoSkills(); // loads 3 built-in demo skills
+
+const skill = createSkill({
+  name: 'my-dashboard',
+  mcp: 'https://mcp.example.com/mcp',
+  mcpName: 'example',
+  llm: 'haiku',
+  blocks: [{ type: 'stat', data: { label: 'KPI', value: '42' } }],
+  tags: ['dashboard'],
+});
+
+const unsub = onSkillsChange(() => console.log('skills changed'));
+```
+
+Each skill stores the MCP server URL and name it was designed for. Apps use this to warn the user if they load a skill while connected to a different server.
+
+## Canvas store
+
+Svelte 5 runes state for the composer canvas. Import from the `/canvas` subpath to avoid issues with server-side rendering:
+
+```ts
+import { canvas } from '@webmcp-auto-ui/sdk/canvas';
+
+canvas.addBlock('stat', { label: 'Revenue', value: '€142K' });
+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.
+
+## Install
+
+```bash
+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.
+
+## License
+
+AGPL-3.0-or-later

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@webmcp-auto-ui/sdk",
+  "version": "0.1.0",
+  "description": "Skills CRUD, HyperSkill format, Svelte 5 stores",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "svelte": "./src/index.ts",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": {
+      "svelte": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./canvas": {
+      "svelte": "./src/canvas.ts",
+      "import": "./src/canvas.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "svelte-check --tsconfig ./tsconfig.json",
+    "build": "svelte-package -i src"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "^2.3.0",
+    "svelte": "^5.0.0",
+    "svelte-check": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/Index.svelte

@@ -0,0 +1,5 @@
+<!-- @webmcp-auto-ui/sdk — browser components stub -->
+<script lang="ts">
+  // This file exists to satisfy svelte-check tooling.
+  // Import canvas store via: import { canvas } from '@webmcp-auto-ui/sdk/canvas'
+</script>

package/src/canvas.ts

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

package/src/hyperskill/format.ts

@@ -0,0 +1,129 @@
+/**
+ * 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;
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+// @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';
+
+// Skills registry
+export {
+  createSkill,
+  updateSkill,
+  deleteSkill,
+  getSkill,
+  listSkills,
+  clearSkills,
+  loadSkills,
+  loadDemoSkills,
+  onSkillsChange,
+} from './skills/registry.js';
+export type { Skill, SkillBlock } from './skills/registry.js';
+
+// Canvas store — browser-only (Svelte 5 runes), import directly from src:
+// import { canvas } from '@webmcp-auto-ui/sdk/canvas'

package/src/skills/registry.ts

@@ -0,0 +1,131 @@
+/**
+ * Skills registry — in-memory CRUD for UI recipes/skills.
+ * Each skill describes how to compose a UI from a set of blocks.
+ */
+
+export interface SkillBlock {
+  type: string;
+  data: Record<string, unknown>;
+}
+
+export interface Skill {
+  id: string;
+  name: string;
+  description?: string;
+  mcp?: string;
+  mcpName?: string;
+  llm?: string;
+  tags?: string[];
+  blocks: SkillBlock[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+const _skills = new Map<string, Skill>();
+const _listeners = new Set<() => void>();
+
+function notify() {
+  _listeners.forEach((fn) => fn());
+}
+
+export function onSkillsChange(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => _listeners.delete(fn);
+}
+
+export function createSkill(
+  data: Omit<Skill, 'id' | 'createdAt' | 'updatedAt'>
+): Skill {
+  const id = 'sk_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+  const skill: Skill = {
+    ...data,
+    id,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  };
+  _skills.set(id, skill);
+  notify();
+  return skill;
+}
+
+export function updateSkill(id: string, patch: Partial<Omit<Skill, 'id' | 'createdAt'>>): Skill | null {
+  const existing = _skills.get(id);
+  if (!existing) return null;
+  const updated = { ...existing, ...patch, id, updatedAt: Date.now() };
+  _skills.set(id, updated);
+  notify();
+  return updated;
+}
+
+export function deleteSkill(id: string): boolean {
+  if (!_skills.has(id)) return false;
+  _skills.delete(id);
+  notify();
+  return true;
+}
+
+export function getSkill(id: string): Skill | undefined {
+  return _skills.get(id);
+}
+
+export function listSkills(): Skill[] {
+  return Array.from(_skills.values()).sort((a, b) => b.createdAt - a.createdAt);
+}
+
+export function clearSkills(): void {
+  _skills.clear();
+  notify();
+}
+
+/** Load a list of skills (e.g. from a HyperSkill URL) — replaces all */
+export function loadSkills(skills: Skill[]): void {
+  _skills.clear();
+  for (const s of skills) _skills.set(s.id, s);
+  notify();
+}
+
+// Built-in demo skills
+const DEMO_SKILLS: Omit<Skill, 'id' | 'createdAt' | 'updatedAt'>[] = [
+  {
+    name: 'weather-dashboard',
+    mcp: 'https://mcp.code4code.eu/mcp',
+    mcpName: 'code4code',
+    description: 'Météo locale avec température, conditions et prévisions',
+    tags: ['météo', 'dashboard'],
+    blocks: [
+      { type: 'stat', data: { label: 'Température', value: '14°C', trend: '+2°', trendDir: 'up' } },
+      { type: 'kv', data: { title: 'Conditions', rows: [['Humidité','72%'],['Vent','18 km/h'],['UV','3']] } },
+      { type: 'chart', data: { title: 'Prévisions 7j', bars: [['L',12],['M',14],['M',11],['J',15],['V',13],['S',16],['D',14]] } },
+    ],
+  },
+  {
+    name: 'kpi-overview',
+    mcp: 'https://mcp.code4code.eu/mcp',
+    mcpName: 'code4code',
+    description: 'Vue KPIs : revenus, utilisateurs, churn',
+    tags: ['kpi', 'dashboard'],
+    blocks: [
+      { type: 'stat', data: { label: 'Revenus', value: '€142K', trend: '+12.4%', trendDir: 'up' } },
+      { type: 'stat', data: { label: 'Utilisateurs', value: '8 204', trend: '+3.2%', trendDir: 'up' } },
+      { type: 'stat', data: { label: 'Churn', value: '2.1%', trend: '-0.4%', trendDir: 'down' } },
+      { type: 'chart', data: { title: 'Revenus Q1-Q4', bars: [['Q1',98],['Q2',112],['Q3',128],['Q4',142]] } },
+    ],
+  },
+  {
+    name: 'status-monitor',
+    mcp: 'https://mcp.code4code.eu/mcp',
+    mcpName: 'code4code',
+    description: 'Monitoring état des services',
+    tags: ['ops', 'monitoring'],
+    blocks: [
+      { type: 'alert', data: { title: 'DB degraded', message: 'Latence élevée sur primary-eu.', level: 'warn' } },
+      { type: 'kv', data: { title: 'État services', rows: [['API','✓ OK'],['DB','⚠ degraded'],['CDN','✓ OK'],['Queue','⚠ warning']] } },
+      { type: 'tags', data: { label: 'Actif', tags: [{ text:'prod', active:true},{ text:'eu-west'},{ text:'v2.4.1',active:true}] } },
+    ],
+  },
+];
+
+export function loadDemoSkills(): void {
+  if (_skills.size > 0) return; // don't overwrite user skills
+  for (const s of DEMO_SKILLS) createSkill(s);
+}

package/src/stores/canvas.svelte.ts

@@ -0,0 +1,214 @@
+/**
+ * Canvas state store — Svelte 5 runes
+ * Manages blocks on the canvas, mode, MCP connection, chat history
+ */
+
+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';
+
+export type Mode = 'auto' | 'drag' | 'chat';
+export type LLMId = 'haiku' | 'sonnet' | 'gemma-e2b';
+
+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);
+}
+
+function createCanvas() {
+  // ── State ────────────────────────────────────────────────────────────────
+  let blocks = $state<Block[]>([]);
+  let mode = $state<Mode>('auto');
+  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 ──────────────────────────────────────────────────────────────
+  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.slice(0, 40)}`;
+    statusColor = 'text-red-400';
+  }
+
+  // ── HyperSkill ───────────────────────────────────────────────────────────
+  function buildSkillJSON() {
+    return {
+      version: '1.0',
+      name: 'skill-' + Date.now(),
+      created: new Date().toISOString(),
+      mcp: mcpUrl,
+      llm,
+      blocks: blocks.map((b) => ({ type: b.type, data: b.data })),
+    };
+  }
+
+  function buildHyperskillParam(): string {
+    const json = JSON.stringify(buildSkillJSON());
+    return btoa(unescape(encodeURIComponent(json)));
+  }
+
+  function loadFromParam(param: string): boolean {
+    try {
+      const json = decodeURIComponent(escape(atob(param)));
+      const skill = JSON.parse(json) as {
+        mcp?: string; llm?: LLMId;
+        blocks?: { type: BlockType; data: Record<string, unknown> }[];
+      };
+      if (skill.mcp) mcpUrl = skill.mcp;
+      if (skill.llm) llm = skill.llm;
+      if (skill.blocks) {
+        blocks = skill.blocks.map((b) => ({ id: uuid(), type: b.type, data: b.data }));
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // ── Return public API ────────────────────────────────────────────────────
+  return {
+    // State getters (reactive)
+    get blocks() { return blocks; },
+    get mode() { return mode; },
+    get llm() { return llm; },
+    get mcpUrl() { return mcpUrl; },
+    get mcpConnected() { return mcpConnected; },
+    get mcpConnecting() { return mcpConnecting; },
+    get mcpName() { return mcpName; },
+    get mcpTools() { return mcpTools; },
+    get messages() { return messages; },
+    get generating() { return generating; },
+    get statusText() { return statusText; },
+    get statusColor() { return statusColor; },
+    get blockCount() { return blockCount; },
+    get isEmpty() { return isEmpty; },
+
+    // Setters
+    setMode(m: Mode) { mode = m; },
+    setLlm(l: LLMId) { llm = l; },
+    setMcpUrl(u: string) { mcpUrl = u; },
+    setGenerating(g: boolean) { generating = g; },
+
+    // Block actions
+    addBlock, removeBlock, updateBlock, moveBlock, clearBlocks, setBlocks,
+
+    // Chat
+    addMsg, updateMsg, clearMessages,
+
+    // MCP
+    setMcpConnecting, setMcpConnected, setMcpError,
+
+    // HyperSkill
+    buildSkillJSON, buildHyperskillParam, loadFromParam,
+  };
+}
+
+export const canvas = createCanvas();

package/tests/hyperskill.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest';
+import { computeHash, diffSkills, decodeHyperSkill, encodeHyperSkill } from '../src/hyperskill/format.js';
+
+describe('computeHash', () => {
+  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}$/);
+  });
+
+  it('is deterministic', async () => {
+    const a = await computeHash('https://x.com', { n: 1 });
+    const b = await computeHash('https://x.com', { 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 });
+    expect(a).not.toBe(b);
+  });
+});
+
+describe('diffSkills', () => {
+  it('returns empty for identical objects', () => {
+    expect(diffSkills({ a: 1, b: 'x' }, { a: 1, b: 'x' })).toEqual([]);
+  });
+
+  it('detects changed keys', () => {
+    const changed = diffSkills({ 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 });
+    expect(changed).toContain('b');
+  });
+
+  it('detects removed keys', () => {
+    const changed = diffSkills({ 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)');
+  });
+});
+
+describe('encodeHyperSkill / decodeHyperSkill', () => {
+  // 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');
+    expect(url).toContain('?hs=');
+
+    const decoded = await decodeHyperSkill(url);
+    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');
+  });
+
+  it('decodes from raw base64 param', async () => {
+    const skill = { meta: { title: 'raw' }, content: { x: 1 } };
+    const url = await encodeHyperSkill(skill, 'https://example.com');
+    const param = new URL(url).searchParams.get('hs')!;
+    const decoded = await decodeHyperSkill(param);
+    expect(decoded.meta.title).toBe('raw');
+  });
+});

package/tests/registry.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  createSkill, updateSkill, deleteSkill, getSkill, listSkills,
+  clearSkills, loadSkills, loadDemoSkills, onSkillsChange,
+} from '../src/skills/registry.js';
+
+beforeEach(() => clearSkills());
+
+describe('createSkill', () => {
+  it('creates a skill with generated id', () => {
+    const s = createSkill({ name: 'test', blocks: [], tags: [] });
+    expect(s.id).toMatch(/^sk_/);
+    expect(s.name).toBe('test');
+    expect(s.createdAt).toBeGreaterThan(0);
+  });
+
+  it('stores mcp and mcpName', () => {
+    const s = createSkill({ name: 'x', mcp: 'https://mcp.example.com', mcpName: 'example', blocks: [], tags: [] });
+    expect(s.mcp).toBe('https://mcp.example.com');
+    expect(s.mcpName).toBe('example');
+  });
+});
+
+describe('updateSkill', () => {
+  it('updates an existing skill', () => {
+    const s = createSkill({ name: 'old', blocks: [], tags: [] });
+    const updated = updateSkill(s.id, { name: 'new' });
+    expect(updated?.name).toBe('new');
+    expect(updated?.updatedAt).toBeGreaterThanOrEqual(s.createdAt);
+  });
+
+  it('returns null for unknown id', () => {
+    expect(updateSkill('nonexistent', { name: 'x' })).toBeNull();
+  });
+});
+
+describe('deleteSkill', () => {
+  it('removes a skill', () => {
+    const s = createSkill({ name: 'del', blocks: [], tags: [] });
+    expect(deleteSkill(s.id)).toBe(true);
+    expect(getSkill(s.id)).toBeUndefined();
+  });
+
+  it('returns false for unknown id', () => {
+    expect(deleteSkill('ghost')).toBe(false);
+  });
+});
+
+describe('listSkills', () => {
+  it('returns skills sorted by createdAt desc', async () => {
+    createSkill({ name: 'a', blocks: [], tags: [] });
+    await new Promise(r => setTimeout(r, 2));
+    createSkill({ name: 'b', blocks: [], tags: [] });
+    const list = listSkills();
+    expect(list[0].name).toBe('b');
+    expect(list[1].name).toBe('a');
+  });
+});
+
+describe('onSkillsChange', () => {
+  it('fires callback on create', () => {
+    let count = 0;
+    const unsub = onSkillsChange(() => count++);
+    createSkill({ name: 'x', blocks: [], tags: [] });
+    expect(count).toBe(1);
+    unsub();
+    createSkill({ name: 'y', blocks: [], tags: [] });
+    expect(count).toBe(1); // unsubscribed
+  });
+});
+
+describe('loadDemoSkills', () => {
+  it('loads 3 demo skills with mcp/mcpName', () => {
+    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);
+  });
+
+  it('does not overwrite existing skills', () => {
+    createSkill({ name: 'mine', blocks: [], tags: [] });
+    loadDemoSkills();
+    expect(listSkills().length).toBe(1);
+  });
+});
+
+describe('loadSkills', () => {
+  it('replaces all skills', () => {
+    createSkill({ name: 'old', blocks: [], tags: [] });
+    const now = Date.now();
+    loadSkills([{ id: 'sk_x', name: 'new', blocks: [], tags: [], createdAt: now, updatedAt: now }]);
+    const list = listSkills();
+    expect(list.length).toBe(1);
+    expect(list[0].name).toBe('new');
+  });
+});

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "strict": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.svelte"
+  ]
+}