claude-code-hub 1.27.2 → 1.28.0

package/lib/ext.js

@@ -3,11 +3,13 @@
 const { execFileSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
+const tty = require('node:tty');
 const { parseArgs } = require('node:util');
 const { APPS, HUB_ROOT, ID_RE, selectApps, appRoot, readApp } = require('./apps');
 const { isContained } = require('./contain');
 const { readConfig, writeConfigFile } = require('./hub-config');
 const { claudeEnv, hasClaude, installPlugin, reinstallPlugin, uninstallPlugin, report, run } = require('./install');
+const { BUNDLED, bundledRoot, entryRoot, modJsHash, readMod } = require('./mods');
 const { pluginChecker } = require('./plugin-status');
 const { isNewer } = require('./update-check');
 
@@ -27,7 +29,14 @@ const USAGE = `Usage: claude-code-hub ext <command>
 
   A feature the hub ships (voice) is turned on by ext install <id> and off by ext remove <id>.
 
+  A mod (mod.json) adds CSS and JS to the hub page and the apps, and can bring color themes.
+  The hub ships some mods (xmas): ext install <id> finds them before the registry.
+  A mod with JS runs only when you type y, at install and when ext update changes its code.
+  Open the hub at /?nomods to load it with no mod. "modsEnabled": false in config.json
+  or --no-mods turns every mod off.
+
   --hub-dir <path>       The hub dir (default CLAUDE_HUB_DIR, else ~/.claude-hub)
+  --yes                  Let a mod run code without asking
   --dir <path>           The config dir for plugin and dock steps (default CLAUDE_CONFIG_DIR, else ~/.claude)`;
 
 const RESTART = '  Restart the hub to load the change.';
@@ -67,11 +76,14 @@ function managedEntry(config, id, verb) {
   const found = extEntry(config, id);
   const [entry] = found;
   const { source } = entry;
-  if (source !== 'local' && !isGithub(entry)) throw new Error(`${id} has source "${source}": only a local or GitHub extension can ${verb}.`);
+  if (source === 'bundled' && verb === 'update') throw new Error(`${id} ships with the hub: it updates when the hub does.`);
+  if (source !== 'local' && source !== 'bundled' && !isGithub(entry)) {
+    throw new Error(`${id} has source "${source}": only a local, bundled or GitHub extension can ${verb}.`);
+  }
   return found;
 }
 
-const rootOf = (ctx, entry) => path.resolve(ctx.hubDir, entry.path);
+const rootOf = (ctx, entry) => entryRoot(entry, ctx.hubDir, ctx.bundled);
 
 const GITHUB_RE = /^github:([\w.-]+)\/([\w.-]+)((?:\/[\w.-]+)*)(?:@(\w[\w./-]*))?$/;
 
@@ -257,9 +269,83 @@ const KINDS = {
     updated: 'Restart its server (Ctrl+R on its row in the app launcher) to load the new code.',
     noPlugin: 'dock add-on',
   },
+  mod: {
+    list: 'mods',
+    file: 'mod.json',
+    read: readMod,
+    step: modStep,
+    stepName: 'Checking the mod',
+    removeName: 'Removing the mod',
+    unread: 'It is removed by its id.',
+    installed: RESTART,
+    removed: RESTART,
+    updated: 'Restart the hub to load the new code.',
+    noPlugin: 'mod',
+  },
 };
 
-const kindOf = (root) => (fs.existsSync(path.join(root, 'addon.json')) ? KINDS.addon : KINDS.app);
+const kindOf = (root) => {
+  if (fs.existsSync(path.join(root, 'mod.json'))) return KINDS.mod;
+  return fs.existsSync(path.join(root, 'addon.json')) ? KINDS.addon : KINDS.app;
+};
+
+const jsTargets = (manifest) => Object.keys(manifest.targets).filter((t) => manifest.targets[t].js?.length);
+
+// The answer typed on the terminal, or null when there is no terminal to ask on. isatty, not
+// process.stdin.isTTY: that getter opens a tty.ReadStream, which on macOS and Linux makes fd 0
+// non-blocking, and readSync then throws EAGAIN.
+function askTerminal(question) {
+  if (!tty.isatty(0)) return null;
+  process.stdout.write(question);
+  const buf = Buffer.alloc(256);
+  try {
+    return buf.toString('utf8', 0, fs.readSync(0, buf, 0, buf.length, null)).trim();
+  } catch {
+    return null;
+  }
+}
+
+// A mod's JS runs in the page's own origin, with the same trust as a patch: in Kanban's origin it can
+// read the terminal token and type into sessions. So it runs only when the user types yes.
+function allowJs(ctx, id, js, refused) {
+  if (ctx.yes) return true;
+  const answer = (ctx.ask ?? askTerminal)(`  Let ${id} run code in ${js.join(', ')}? [y/N] `);
+  if (answer === null) {
+    console.log(`\n  There is no terminal to ask on. Pass --yes to let ${id} run code.`);
+    return false;
+  }
+  if (/^y(es)?$/i.test(answer)) return true;
+  console.log(`\n  ${refused}`);
+  return false;
+}
+
+// Asks only at install. Update asks itself, and only when the code changes.
+function modStep(ctx, id, ext, step) {
+  if (step !== 'install' || !ext) return true;
+  const { targets } = ext.manifest;
+  console.log(`\n  Mod ${id} changes: ${Object.keys(targets).join(', ')}`);
+  const js = jsTargets(ext.manifest);
+  if (!js.length) return true;
+  console.log(`  It runs code in ${js.join(', ')}, with the same access as the app's own code.`);
+  return allowJs(ctx, id, js, `${id} is not installed.`);
+}
+
+function jsHashOf(root, id) {
+  try {
+    return modJsHash(root, readMod(root, id).manifest);
+  } catch {
+    return null;
+  }
+}
+
+function updateAllowed(ctx, id, kind, root, before) {
+  if (kind !== KINDS.mod) return true;
+  const { manifest } = readMod(root, id);
+  const js = jsTargets(manifest);
+  if (!js.length || modJsHash(root, manifest) === before) return true;
+  console.log(`\n  The new version of ${id} changes the code it runs in ${js.join(', ')}.`);
+  return allowJs(ctx, id, js, `${id} keeps the code it had.`);
+}
 
 // An id the hub runs gets its plugin installed. A folder is added to the hub, with its plugin, unless the
 // hub already runs it from there; then only the plugin is installed. Any other name is looked up in the registry.
@@ -274,6 +360,8 @@ function install(ctx, target) {
   if (addon) return dockStep(ctx, target, null, 'install', rootOf(ctx, addon), config);
   const feature = readFeature(target, ctx.features);
   if (feature) return setFeature(ctx, feature, true, file, config);
+  const bundled = !fs.existsSync(target) && bundledRoot(target, ctx.bundled);
+  if (bundled) return installBundled(ctx, target, bundled, file, config);
   if (!fs.existsSync(target) && ID_RE.test(target)) return installRegistry(ctx, target, file, config);
   return installFolder(ctx, target, file, config);
 }
@@ -415,6 +503,21 @@ function installGithub(ctx, target, file, config, name) {
   return true;
 }
 
+function installBundled(ctx, id, root, file, config) {
+  const kind = kindOf(root);
+  const ext = kind.read(root, id);
+  const entry = claimId(id, config, file, kind, (e) => e.source === 'bundled');
+  checkRequires(ctx, ext.manifest, config);
+  if (entry) {
+    if (!kind.step(ctx, id, ext, 'install', root, config)) return false;
+    console.log(`\n  ${id} is already in the hub.`);
+    return true;
+  }
+  if (!addExtension(ctx, root, file, config, { source: 'bundled' }, kind)) return false;
+  console.log(`\n  Installed ${id}, which ships with the hub.\n${kind.installed}`);
+  return true;
+}
+
 function installAppPlugin(ctx, app) {
   const { root, plugin: p } = appPlugin(app);
   if (!p) throw new Error(`${app.id} ships no plugin.`);
@@ -477,16 +580,20 @@ function update(ctx, id) {
   let sha;
   if (isGithub(entry)) {
     const clone = cloneOf(ctx, entry);
+    const before = kind === KINDS.mod ? jsHashOf(root, id) : null;
+    const was = git(['rev-parse', 'HEAD'], clone);
     git(['fetch', '--quiet', 'origin'], clone);
     sha = checkout(clone, entry.ref);
-    const back = () => entry.sha && entry.sha !== sha && checkout(clone, entry.sha);
+    const back = () => was !== sha && checkout(clone, was);
+    let allowed;
     try {
       checkRequires(ctx, kind.read(root, id).manifest, config);
+      allowed = updateAllowed(ctx, id, kind, root, before);
     } catch (e) {
       back();
       throw e;
     }
-    if (!installDeps(ctx, root)) {
+    if (!allowed || !installDeps(ctx, root)) {
       back();
       return false;
     }
@@ -523,7 +630,8 @@ function remove(ctx, id) {
     if (removeDir(clone)) console.log(`\n  Removed ${id} and its clone.\n${kind.removed}`);
     return true;
   }
-  console.log(`\n  Removed ${id}. ${entry.path} is left in place.\n${kind.removed}`);
+  const kept = entry.path ? ` ${entry.path} is left in place.` : '';
+  console.log(`\n  Removed ${id}.${kept}\n${kind.removed}`);
   return true;
 }
 
@@ -560,18 +668,19 @@ const COMMANDS = { install, list, update, remove };
 // ctx: {hubDir, configDir: () => dir for plugin steps, hubVersion, nodeVersion?, exec?, githubBase?, registry?: URL or file}.
 function runExt(argv, ctx) {
   const registry = process.env.CLAUDE_HUB_REGISTRY || REGISTRY;
-  const full = { nodeVersion: process.versions.node, exec: run, githubBase: 'https://github.com', registry, ...ctx };
+  const full = { nodeVersion: process.versions.node, exec: run, githubBase: 'https://github.com', registry, bundled: BUNDLED, ...ctx };
   let parsed;
   try {
     parsed = parseArgs({
       args: argv,
       allowPositionals: true,
-      options: { dir: { type: 'string' }, 'hub-dir': { type: 'string' }, help: { type: 'boolean', short: 'h' } },
+      options: { dir: { type: 'string' }, 'hub-dir': { type: 'string' }, yes: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
     });
   } catch (e) {
     console.error(`${e.message}\n\n${USAGE}`);
     return false;
   }
+  full.yes = parsed.values.yes === true;
   const [name, target] = parsed.positionals;
   const command = COMMANDS[name];
   if (!command || parsed.values.help) {

package/lib/mods.js

@@ -0,0 +1,156 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { HUB_ROOT, ID_RE } = require('./apps');
+const { isContained } = require('./contain');
+
+// Extensions the hub ships. `ext install <id>` finds them before the registry.
+const BUNDLED = path.join(HUB_ROOT, 'extensions');
+
+// A mod file is served at /mods/<id>/<file>, so its name must be a plain relative URL path.
+const FILE_RE = /^[\w-][\w.-]*(\/[\w-][\w.-]*)*$/;
+const TYPES = { css: '.css', js: '.js' };
+
+function modProblem(m, root) {
+  if (m?.kind !== 'mod' || !ID_RE.test(m.id ?? '')) return 'a mod manifest needs "kind": "mod" and an id of lowercase letters, digits and dashes';
+  if (m.themes !== undefined && !Array.isArray(m.themes)) return 'themes must be a list of themes';
+  if (!m.targets || typeof m.targets !== 'object' || Array.isArray(m.targets)) return 'targets must be an object keyed by "hub" or an app id';
+  for (const [target, parts] of Object.entries(m.targets)) {
+    if (!ID_RE.test(target)) return `targets.${target} is not "hub" or an app id`;
+    if (!parts || typeof parts !== 'object') return `targets.${target} must be an object of css and js lists`;
+    if (!Number.isInteger(parts.surface) || parts.surface < 1) {
+      return `targets.${target}.surface must be the version of the ${target} mod surface its files are written for`;
+    }
+    for (const [type, files] of Object.entries(parts)) {
+      if (type === 'surface') continue;
+      const where = `targets.${target}.${type}`;
+      if (!TYPES[type]) return `${where}: a target takes css and js only`;
+      if (!Array.isArray(files)) return `${where} must be a list of files`;
+      for (const f of files) {
+        if (typeof f !== 'string' || !FILE_RE.test(f) || !f.endsWith(TYPES[type])) return `${where}: "${f}" is not a relative ${TYPES[type]} path`;
+        const abs = path.join(root, f);
+        if (!isContained(abs, root)) return `${where}: ${f} is outside the mod folder`;
+        if (!fs.statSync(abs, { throwIfNoEntry: false })?.isFile()) return `${where}: ${f} is not found`;
+      }
+    }
+  }
+  return null;
+}
+
+function readMod(root, id) {
+  const file = path.join(root, 'mod.json');
+  let raw;
+  let manifest;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+    manifest = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`${file}: ${e.code === 'ENOENT' ? 'not found' : e.message}`);
+  }
+  const problem = modProblem(manifest, root);
+  if (problem) throw new Error(`${file}: ${problem}`);
+  if (id && manifest.id !== id) throw new Error(`${file}: its id is ${manifest.id}, not ${id}`);
+  return { manifest, raw };
+}
+
+// A bundled entry has no path: it follows the hub's own copy, so it moves with each hub upgrade.
+const entryRoot = (entry, hubDir, bundled = BUNDLED) =>
+  entry.source === 'bundled' ? path.join(bundled, entry.id) : path.resolve(hubDir, entry.path);
+
+const bundledRoot = (id, bundled = BUNDLED) => {
+  if (!ID_RE.test(id ?? '')) return null;
+  const root = path.join(bundled, id);
+  return fs.existsSync(root) ? root : null;
+};
+
+// The `surface` number in <root>/mod-surface.json: the version of the names a mod may use on that
+// page. Null when the file is missing or has none.
+function readSurface(root) {
+  try {
+    const { surface } = JSON.parse(fs.readFileSync(path.join(root, 'mod-surface.json'), 'utf8'));
+    return Number.isInteger(surface) ? surface : null;
+  } catch {
+    return null;
+  }
+}
+
+// Changes with any JS file of the mod, and with the page each one runs in. `ext update` asks again when it does.
+function modJsHash(root, manifest) {
+  const hash = crypto.createHash('sha1');
+  for (const [target, parts] of Object.entries(manifest.targets))
+    for (const f of parts.js ?? []) hash.update(`${target}\0${f}\0`).update(fs.readFileSync(path.join(root, f))).update('\0');
+  return hash.digest('hex');
+}
+
+// The mods of `config.mods`, read once at hub start. `version` changes with any file of the mod,
+// so the browser fetches the new files after a hub restart and caches them until then.
+// `surfaces` maps "hub" and each enabled app id to its surface version, or null when it has none.
+// A target whose page is not running is left out; one written for another surface is left out with a log line.
+function resolveMods(config, hubDir, { warn, surfaces, bundled = BUNDLED, off = false }) {
+  if (off) return [];
+  const out = [];
+  for (const entry of config.mods ?? []) {
+    if (typeof entry?.id !== 'string' || entry.enabled === false) continue;
+    const root = entryRoot(entry, hubDir, bundled);
+    let manifest;
+    let raw;
+    try {
+      ({ manifest, raw } = readMod(root, entry.id));
+    } catch (e) {
+      warn(`[mods] skipped ${entry.id}: ${e.message}`);
+      continue;
+    }
+    const hash = crypto.createHash('sha1').update(raw);
+    const targets = {};
+    for (const [target, parts] of Object.entries(manifest.targets)) {
+      const have = surfaces[target];
+      if (have === undefined) continue;
+      if (have !== parts.surface) {
+        const why = have === null ? `${target} has no mod surface` : `${target} has surface ${have}`;
+        warn(`[mods] ${entry.id}: skipped its ${target} files: they are written for surface ${parts.surface}, and ${why}`);
+        continue;
+      }
+      targets[target] = { css: parts.css ?? [], js: parts.js ?? [] };
+      for (const f of [...targets[target].css, ...targets[target].js]) hash.update(f).update(fs.readFileSync(path.join(root, f)));
+    }
+    out.push({ id: manifest.id, root, version: hash.digest('hex').slice(0, 10), themes: manifest.themes ?? [], targets });
+  }
+  return out;
+}
+
+// What one page loads: its mods, the URLs of their CSS and JS in mod order then file order, and the
+// `/<id>/<file>` → path map of the only files its /mods route serves.
+function modAssets(mods, target) {
+  const mine = mods.filter((m) => m.targets[target]);
+  const pick = (type) => mine.flatMap((m) => (m.targets[target][type] ?? []).map((f) => [m, f]));
+  const url = ([m, f]) => `/mods/${m.id}/${f}?v=${m.version}`;
+  const css = pick('css');
+  const js = pick('js');
+  const files = new Map([...css, ...js].map(([m, f]) => [`/${m.id}/${f}`, path.join(m.root, f)]));
+  return { mods: mine.map((m) => ({ id: m.id, version: m.version })), css: css.map(url), js: js.map(url), files };
+}
+
+// HUB_MODS for an app: the page's list as the client reads it, and the files the SDK's mount()
+// serves. The SDK uses both as given, so the URL format lives only here. Null when the app has no mod.
+function appModEnv(mods, app) {
+  const { files, ...assets } = modAssets(mods, app);
+  return assets.mods.length ? JSON.stringify({ assets, files: Object.fromEntries(files) }) : null;
+}
+
+const MOD_KIT = path.join(HUB_ROOT, 'packages', 'claude-hub-sdk', 'src', 'mods.js');
+
+// /mods/hub.js: the SDK's mod runtime as ClaudeHub.mod on the hub page, which then loads the mod
+// scripts. Empty when no mod has JS for the hub page.
+function hubModScript(assets) {
+  if (!assets.js.length) return '';
+  return [
+    `self.ClaudeHubMods = ${JSON.stringify({ mods: assets.mods, js: assets.js })};`,
+    fs.readFileSync(MOD_KIT, 'utf8'),
+    'self.ClaudeHub = { mod: ClaudeHubModKit.createMods(self).mod };',
+    '',
+  ].join('\n');
+}
+
+module.exports = { BUNDLED, readMod, readSurface, modJsHash, entryRoot, bundledRoot, resolveMods, modAssets, appModEnv, hubModScript };

package/lib/themes.js

@@ -54,7 +54,7 @@ const isObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 function themeProblem(e, builtins, seen) {
   if (!isObject(e)) return 'not an object';
   if (typeof e.id !== 'string' || !THEME_ID.test(e.id)) return 'id must match ^[a-z0-9-]{1,32}$';
-  if (seen.has(e.id)) return 'an earlier theme in the file has this id';
+  if (seen.has(e.id)) return seen.get(e.id) ? 'an installed mod has a theme with this id' : 'an earlier theme in the file has this id';
   if (e.label !== undefined && typeof e.label !== 'string') return 'label must be a string';
   if (e.extends !== undefined) {
     if (builtins.has(e.id)) return 'a built-in id cannot take extends';
@@ -76,17 +76,31 @@ function themeProblem(e, builtins, seen) {
 
 // The built-in list with the user's themes applied: a built-in id changes that theme in place, a
 // new id is added at the end. A theme that breaks a rule is skipped, and `warn` says why.
-function withUserThemes(themes, entries, warn) {
+// The themes of the installed mods. A mod adds themes and never replaces one: not a built-in, which
+// the user's themes.json may tune, and not another mod's. Checked once at hub start.
+function modThemes(registry, mods, warn) {
+  const taken = new Set((registry ?? []).map((t) => t.id));
+  return mods.flatMap((m) =>
+    (m.themes ?? []).filter((t) => {
+      if (!taken.has(t?.id)) return taken.add(t?.id);
+      warn(`[mods] ${m.id}: skipped its theme "${t?.id}": another theme has this id`);
+      return false;
+    }),
+  );
+}
+
+// The first `fromMods` entries are mod themes, which modThemes has checked against each other.
+function withUserThemes(themes, entries, warn, fromMods = 0) {
   const builtins = new Map(themes.map((t) => [t.id, t]));
   const out = new Map(builtins);
-  const seen = new Set();
+  const seen = new Map();
   entries.forEach((e, i) => {
     const problem = themeProblem(e, builtins, seen);
     if (problem) {
       warn(`[themes] skipped ${typeof e?.id === 'string' ? `"${e.id}"` : `entry ${i + 1}`}: ${problem}`);
       return;
     }
-    seen.add(e.id);
+    seen.set(e.id, i < fromMods);
     const base = builtins.get(e.id) ?? builtins.get(e.extends);
     out.set(e.id, {
       id: e.id,
@@ -121,14 +135,16 @@ function readRegistry(file = THEMES_FILE) {
 
 // What /api/config carries. An unreadable registry gives empty maps: the hub keeps index.html's
 // colors and sends no vars, so each app uses its own theme CSS. `userFile` is the user's
-// <hub-dir>/themes.json, read on each call.
-function themeConfig(registry = readRegistry(), { userFile, warn = console.warn } = {}) {
+// <hub-dir>/themes.json, read on each call. `extra` holds the themes of installed mods, which go
+// before the user's, so a user theme cannot take a mod theme's id.
+function themeConfig(registry = readRegistry(), { userFile, extra = [], warn = console.warn } = {}) {
   if (!registry) return { themes: [], themeVars: {} };
-  const themes = userFile ? withUserThemes(registry, readUserThemes(userFile, warn), warn) : registry;
+  const entries = [...extra, ...(userFile ? readUserThemes(userFile, warn) : [])];
+  const themes = entries.length ? withUserThemes(registry, entries, warn, extra.length) : registry;
   return {
     themes: themes.map((t) => ({ id: t.id, label: t.label, swatch: modes(t, swatch) })),
     themeVars: Object.fromEntries(themes.map((t) => [t.id, modes(t, coreVars)])),
   };
 }
 
-module.exports = { readThemes, readRegistry, coreVars, swatch, themeConfig, ROLES };
+module.exports = { readThemes, readRegistry, coreVars, swatch, themeConfig, modThemes, ROLES };

package/lib/voice/grammar.js

@@ -14,9 +14,11 @@ const PREFIX = /^\s*(?:hub|hob|hab)\b[\s,.:;!?-]*/i;
 const TAIL = '\\b[\\s,.:;!?-]*([\\s\\S]*?)\\s*$';
 const phrase = (verbs, noun) =>
   new RegExp(`^(?:(?:${verbs})\\s+(?:(?:a|the)\\s+)?(?:new\\s+)?)?${noun}${TAIL}`, 'i');
+const words = (alts) => new RegExp(`^(?:${alts})${TAIL}`, 'i');
 const dropEndPunct = (s) => s.replace(/[.!?]+$/, '');
 
-// `param` takes the words after the phrase; `tidy` cleans them. `say` and `help` feed the page's help panel.
+// `param` takes the words after the phrase; a row without one matches only when no words follow, so
+// "approve, but not that file" never approves. `tidy` cleans them. `say` and `help` feed the page's help panel.
 // `live` names the app's dialog action that the page fills as the user speaks, and the param that takes
 // the words so far.
 const COMMANDS = [
@@ -31,10 +33,10 @@ const COMMANDS = [
   {
     action: 'session.find',
     label: 'Open session',
-    phrase: new RegExp(`^(?:open|switch\\s+to|go\\s+to|show)\\s+(?:(?:the|my)\\s+)?session${TAIL}`, 'i'),
+    phrase: words('(?:open|go\\s+to|show)\\s+(?:(?:the|my)\\s+)?session|switch(?:\\s+to)?(?:\\s+(?:the|my))?(?:\\s+session)?'),
     param: 'name',
     tidy: dropEndPunct,
-    say: 'open session',
+    say: 'switch to',
     help: 'Opens the session that matches',
   },
   {
@@ -47,6 +49,29 @@ const COMMANDS = [
     help: 'Opens Add task with your words',
     live: { action: 'task.live', param: 'description' },
   },
+  {
+    action: 'session.approve',
+    label: 'Approve',
+    phrase: words('approve|allow|accept|yes'),
+    say: 'approve',
+    help: 'Allows what this session asks',
+  },
+  {
+    action: 'session.deny',
+    label: 'Deny',
+    phrase: words('deny|reject|decline|no'),
+    param: 'message',
+    tidy: dropEndPunct,
+    say: 'deny',
+    help: 'Denies it, with your reason if you add one',
+  },
+  {
+    action: 'session.next',
+    label: 'Next',
+    phrase: words('next(?:\\s+(?:waiting|session|one))?'),
+    say: 'next',
+    help: 'Opens the next session that needs you',
+  },
 ];
 
 const commandList = () =>
@@ -62,7 +87,9 @@ function matchCommand(text, can = () => true) {
   for (const c of COMMANDS) {
     const m = c.phrase.exec(body);
     if (!m || !can(c.action)) continue;
-    return { action: c.action, label: c.label, param: c.param, live: c.live, rest: c.tidy ? c.tidy(m[1]) : m[1] };
+    const rest = c.tidy ? c.tidy(m[1]) : m[1];
+    if (!c.param && rest) continue;
+    return { action: c.action, label: c.label, param: c.param, live: c.live, rest };
   }
   return { action: null, label: 'Hub', rest: body.trim() };
 }

package/mod-surface.json

@@ -0,0 +1,10 @@
+{
+  "surface": 1,
+  "functions": {},
+  "events": {
+    "<mod id>:<name>": "A message from the same mod's code in an app page, sent there with mod.send(topic, data). The detail is {app, data}: the app id and the data as sent."
+  },
+  "parts": {},
+  "states": {},
+  "page": "The hub page holds one iframe per app and its own chrome. A mod may draw over it, such as a fixed canvas with pointer-events: none at a z-index from 11 to 14: over the app frames and the loading screen (10), under the hub's toasts (15 and up) and the palette (20)."
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-hub",
-  "version": "1.27.2",
+  "version": "1.28.0",
   "description": "Unified hub for Claude Code tools — Marketplace + Kanban in one PWA",
   "main": "server.js",
   "bin": {
@@ -47,7 +47,7 @@
   "homepage": "https://github.com/NikiforovAll/claude-code-hub#readme",
   "dependencies": {
     "claude-code-cost": "1.6.1",
-    "claude-code-kanban": "7.24.0",
+    "claude-code-kanban": "7.26.0",
     "claude-code-marketplace": "1.7.2",
     "claude-code-memory-explorer": "1.3.5",
     "express": "^4.21.0",
@@ -61,6 +61,8 @@
     "public/**/*",
     "lib/**/*",
     "features/**/*",
+    "extensions/**/*",
+    "mod-surface.json",
     "plugin/**/*",
     "tray/**/*",
     "packages/claude-hub-sdk/src/**/*"

package/packages/claude-hub-sdk/src/client.js

@@ -14,6 +14,7 @@
 
   // keys.js comes first in the served file. Required as a module, client.js loads it itself.
   const { comboOf, keyParts, keySigs } = typeof ClaudeHubKeys === 'object' ? ClaudeHubKeys : require('./keys');
+  const { createMods } = typeof ClaudeHubModKit === 'object' ? ClaudeHubModKit : require('./mods');
 
   function isVars(v) {
     return (
@@ -41,11 +42,24 @@
         : [],
     );
 
+  // The page's light or dark, for mod CSS: [data-hub-mode="light"]. Cached so it is set before the hub answers.
+  const MODE_KEY = 'claude-hub:mode';
+
   function createClaudeHub(win) {
     const doc = win.document;
     const framed = win.top !== win;
     let appliedVars = null;
     let hub = null;
+    const mods = createMods(win);
+    const { mod } = mods;
+
+    function setMode(mode) {
+      if (mode !== 'light' && mode !== 'dark') return;
+      if (doc.documentElement) doc.documentElement.dataset.hubMode = mode;
+      try {
+        win.localStorage.setItem(MODE_KEY, mode);
+      } catch (_) {}
+    }
 
     function setVars(vars) {
       const body = doc.body;
@@ -82,6 +96,9 @@
     if (framed) {
       const cache = readCache();
       if (cache && hubOnTop(cache.origin)) setVars(cache.vars);
+      try {
+        setMode(win.localStorage.getItem(MODE_KEY));
+      } catch (_) {}
     }
 
     function connect({ standalone = {} } = {}) {
@@ -151,6 +168,7 @@
         if (isVars(p.vars)) adoptVars(p.vars, origin);
         else if (!waiting()) adoptVars(null);
         lastTheme = p;
+        setMode(p.theme);
         applyMode(p);
         emit('theme.changed', p);
       }
@@ -188,6 +206,11 @@
           actions: strings(m.actions),
           keys: comboMap(m.keys),
           themes: Array.isArray(m.themes) ? m.themes : [],
+          voice: Array.isArray(m.voice)
+            ? m.voice
+                .filter((c) => typeof c?.say === 'string' && typeof c?.help === 'string')
+                .map(({ say, help }) => ({ say, help }))
+            : [],
         };
         forward = strings(m.forward);
         appOrigins = strings(m.origins);
@@ -351,6 +374,7 @@
       Promise.all([config, loaded]).then(() => {
         if (!origin) return;
         post({ type: 'hub:hello', protocol: [1], subscribes: [...topics.keys()] });
+        mods.connectSender(post);
         setStatus('waiting');
         // A hub older than protocol v1 never answers. The app then runs as if alone, with no hub calls.
         win.setTimeout(() => {
@@ -463,6 +487,8 @@
           while (n < all[0].length - 1 && all.every((p) => p.length - 1 > n && p[n] === all[0][n])) n++;
           return [...all[0].slice(0, n), all.map((p) => p.slice(n).join('+')).join('/')];
         },
+        // The voice commands this app handles, [{say, help}], for its help. [] with voice off, before welcome, or standalone.
+        voiceCommands: () => (welcome ? welcome.voice.map((c) => ({ ...c })) : []),
         closeGuard(on) {
           post({ type: 'hub:closeGuard', on: !!on });
         },
@@ -493,7 +519,7 @@
       return hub;
     }
 
-    return { connect, comboOf };
+    return { connect, comboOf, mod };
   }
 
   if (typeof module === 'object' && module.exports) module.exports = { createClaudeHub, comboOf };