claude-code-hub 0.42.0 → 1.0.0

package/public/app.js

@@ -1,8 +1,16 @@
 let apps = {};
 let activeApp = null;
+// The app launcher's cursor starts here, so Ctrl+Alt+A then Enter goes back to the last tab.
+let previousApp = null;
 const iframes = {};
 const loadedApps = new Set();
 const guardedApps = new Set();
+// App id → the topics its hub:hello subscribes to. An app is live from its hello until the next
+// iframe load: e.source is the same WindowProxy across reloads, so a new document starts unknown.
+const liveApps = new Map();
+// Apps whose next document the hub loads from an action URL.
+const linkLoads = new Set();
+const HUB_PROTOCOLS = [1];
 // {theme: 'dark'|'light', colorTheme: '<id>', colorThemes: {<configDir>: '<id>'}} — survives hub
 // reloads so late-loading iframes and fresh sessions get the last chosen theme. Light/dark is
 // global; the color theme is per config dir, and colorTheme is the last one picked anywhere, which
@@ -14,9 +22,14 @@ let activeConfigDir = null;
 // hub-theme: starting unset means there is nothing to race against each sub-app's own
 // project self-restore on boot. Once set it never returns to null.
 let projectState = null;
+// Topic → {from, payload}: the last value of each topic an app published. Cleared with projectState.
+const published = new Map();
+// App id → the published topics it missed while hidden. It gets their last value when it comes on screen.
+const missed = new Map();
+const MAX_EVENT_CHARS = 16 * 1024;
 // The config dir the hub falls back to (~/.claude). Stays out of the window title.
 let defaultConfigDir = null;
-// mode: 'project' (Ctrl+Alt+P) or 'configDir' (Ctrl+Alt+W). One widget, two row sources.
+// mode: 'project' (Ctrl+Alt+P), 'configDir' (Ctrl+Alt+W) or 'app' (Ctrl+Alt+A). One widget, three row sources.
 const palette = {
   open: false,
   mode: 'project',
@@ -25,6 +38,7 @@ const palette = {
   rows: [],
   sel: 0,
   query: '',
+  confirmRestart: null,
 };
 
 function loadThemeState() {
@@ -39,8 +53,10 @@ function loadThemeState() {
 }
 
 // The color theme of the active config dir, falling back to the last one picked anywhere.
+// An id the registry lacks shows as Ember everywhere, so the hub page and every app agree.
 function activeColorTheme() {
-  return themeState.colorThemes[activeConfigDir] ?? themeState.colorTheme;
+  const id = themeState.colorThemes[activeConfigDir] ?? themeState.colorTheme;
+  return id && hubThemes.length && !themeVars[id] ? 'ember' : id;
 }
 
 function osTheme() {
@@ -49,14 +65,36 @@ function osTheme() {
 
 // Sub-apps disagree on their first-run default (marketplace follows the OS, the rest start dark),
 // so an unset theme resolves to the OS preference here and reaches every iframe on load.
-function themeMessage() {
-  return { type: 'hub:theme', theme: themeState.theme ?? osTheme(), colorTheme: activeColorTheme() };
+function themePayload() {
+  return { theme: themeState.theme ?? osTheme(), colorTheme: activeColorTheme() };
 }
 
-// {<themeId>: {dark, light}}, each a map of CSS variables, from /api/config, which derives it from
-// lib/themes.json — the same registry that generates each sub-app's themes.css. Empty until
-// config arrives, and empty if the registry is unreadable; then the hub keeps index.html's colors.
-let themePalettes = {};
+function sendTheme(appId) {
+  const payload = themePayload();
+  const vars = themeVars[payload.colorTheme ?? 'ember']?.[payload.theme];
+  sendTopic(appId, 'theme.changed', vars ? { ...payload, vars } : payload);
+}
+
+// {<themeId>: {dark, light}}, each a map of the apps' core CSS variables, from /api/config, which
+// derives it from lib/themes.json — the same registry that generates each sub-app's themes.css.
+// Empty until config arrives, and empty if the registry is unreadable; then the hub keeps
+// index.html's colors.
+let themeVars = {};
+// The picker list that welcome carries.
+let hubThemes = [];
+// {<action>: {app, params, url, mode}} from the manifests, one handler each, from /api/config.
+let actions = {};
+// The hub page's names for the core variables. --bg is the apps' --bg-deep, so the loading screen
+// hands off to an iframe without a flash of another color.
+const HUB_VARS = {
+  '--accent': '--accent',
+  '--bg': '--bg-deep',
+  '--surface': '--bg-surface',
+  '--surface-hover': '--bg-hover',
+  '--border': '--border',
+  '--text': '--text-primary',
+  '--text-dim': '--text-muted',
+};
 // The last applied variables, so the loading screen paints in the theme before /api/config lands.
 const PALETTE_KEY = 'hub-palette';
 
@@ -67,7 +105,8 @@ function applyHubTheme() {
   const root = document.documentElement;
   root.classList.toggle('light', mode === 'light');
   const key = `${activeColorTheme()}/${mode}`;
-  let vars = themePalettes[activeColorTheme()]?.[mode];
+  const core = themeVars[activeColorTheme()]?.[mode];
+  let vars = core && Object.fromEntries(Object.entries(HUB_VARS).map(([hub, name]) => [hub, core[name]]));
   try {
     if (vars) localStorage.setItem(PALETTE_KEY, JSON.stringify({ key, vars }));
     else {
@@ -94,15 +133,6 @@ function parentOf(p) {
   return i <= 0 ? '' : p.slice(0, i);
 }
 
-function projectMessage() {
-  return {
-    type: 'hub:project',
-    project: projectState.project,
-    encoded: projectState.encoded,
-    name: projectState.name,
-  };
-}
-
 function originOf(appId) {
   return new URL(apps[appId].url).origin;
 }
@@ -110,7 +140,7 @@ function originOf(appId) {
 function postTo(appId, message) {
   // Before the iframe commits its src its contentWindow is still on the hub's own
   // origin, so a send addressed to the sub-app origin is refused and logged. The
-  // load handler posts the current state anyway, so skipping here loses nothing.
+  // app's hello brings the current state anyway, so skipping here loses nothing.
   if (!loadedApps.has(appId)) return;
   iframes[appId]?.contentWindow?.postMessage(message, originOf(appId));
 }
@@ -119,28 +149,62 @@ function appIdOf(source) {
   return Object.keys(iframes).find((id) => iframes[id].contentWindow === source);
 }
 
-// exceptWindow lets an echo of a sub-app's own message skip that sub-app.
-function broadcast(message, exceptWindow) {
-  for (const [id, iframe] of Object.entries(iframes)) {
-    if (exceptWindow && iframe.contentWindow === exceptWindow) continue;
-    postTo(id, message);
-  }
+// The last value lives in themeState and projectState, so a replay after welcome is a send.
+function sendTopic(appId, topic, payload) {
+  if (liveApps.get(appId)?.has(topic)) postTo(appId, { type: 'hub:event', topic, payload });
 }
 
 function setProject(absPath) {
   projectState = { project: absPath, encoded: encodeProjectPath(absPath), name: basename(absPath) };
-  broadcast(projectMessage());
+  for (const id of Object.keys(iframes)) sendProject(id);
 }
 
-function postProjectTo(appId) {
+function sendProject(appId) {
   if (!projectState) return;
-  postTo(appId, projectMessage());
+  sendTopic(appId, 'project.changed', projectState);
+}
+
+// Protocol §10. A payload with a string `project` gets the hub's encoded form and short name, as in project.changed.
+function onPublish(appId, { topic, payload }) {
+  if (!apps[appId].publishes.includes(topic)) return;
+  if (payload !== null && !isPlainObject(payload)) return;
+  try {
+    if (JSON.stringify(payload).length > MAX_EVENT_CHARS) return;
+  } catch {
+    return;
+  }
+  const event =
+    typeof payload?.project === 'string'
+      ? { ...payload, encoded: encodeProjectPath(payload.project), projectName: basename(payload.project) }
+      : payload;
+  published.set(topic, { from: appId, payload: event });
+  for (const id of Object.keys(iframes)) {
+    if (id === appId) continue;
+    if (id === activeApp) sendTopic(id, topic, event);
+    else if (liveApps.get(id)?.has(topic)) missed.set(id, (missed.get(id) ?? new Set()).add(topic));
+  }
+}
+
+function sendPublished(appId) {
+  missed.delete(appId);
+  for (const [topic, { from, payload }] of published) if (from !== appId) sendTopic(appId, topic, payload);
+}
+
+function sendMissed(appId) {
+  for (const topic of missed.get(appId) ?? []) {
+    const last = published.get(topic);
+    if (last && last.from !== appId) sendTopic(appId, topic, last.payload);
+  }
+  missed.delete(appId);
 }
 
 // Sub-apps can't detect this themselves: inactive iframes are display:none, and a nested
 // document's visibilityState still follows the top-level tab. Used for polling/auto-refresh.
 function postActiveTo(appId) {
-  postTo(appId, { type: 'hub:active', active: appId === activeApp });
+  if (!liveApps.has(appId)) return;
+  const active = appId === activeApp;
+  if (active) sendMissed(appId);
+  postTo(appId, { type: 'hub:active', active });
 }
 
 async function init() {
@@ -154,10 +218,13 @@ async function init() {
   defaultConfigDir = config.defaultConfigDir ?? null;
   activeConfigDir = config.activeConfigDir ?? null;
   applyTitle(config.activeConfigDir);
-  themePalettes = config.themePalettes ?? {};
+  themeVars = config.themeVars ?? {};
+  hubThemes = config.themes ?? [];
+  actions = config.actions ?? {};
   applyHubTheme();
   buildIframes();
-  switchTab(Object.keys(apps)[0]);
+  const saved = storedTab();
+  switchTab(apps[saved] ? saved : Object.keys(apps)[0]);
   listenMessages();
   listenKeys();
   bindPalette();
@@ -177,8 +244,33 @@ function applyTitle(dir) {
 function reloadIframes() {
   loadedApps.clear();
   projectState = null;
-  // Assigning src navigates even when the URL is unchanged.
-  for (const [id, iframe] of Object.entries(iframes)) iframe.src = appSrc(id);
+  published.clear();
+  missed.clear();
+  // A new element, because assigning src is only a fragment navigation when the app's URL
+  // differs from the new one by the #t= fragment alone, and the old dir's document stays.
+  for (const id of Object.keys(iframes)) replaceIframe(id);
+}
+
+function replaceIframe(id) {
+  const old = iframes[id];
+  liveApps.delete(id);
+  linkLoads.delete(id);
+  loadedApps.delete(id);
+  const fresh = makeIframe(id);
+  fresh.className = old.className;
+  fresh.inert = old.inert;
+  const focused = document.activeElement === old;
+  old.replaceWith(fresh);
+  iframes[id] = fresh;
+  if (focused) fresh.focus();
+}
+
+// The old document stays live until the new one fires load, and a hub:action sent to it in between is lost.
+function loadApp(id, src, { link = false } = {}) {
+  liveApps.delete(id);
+  if (link) linkLoads.add(id);
+  else linkLoads.delete(id);
+  iframes[id].src = src;
 }
 
 // The terminal token rides in the fragment so it never reaches a server log or a Referer.
@@ -187,57 +279,17 @@ function appSrc(id, path = '') {
   return apps[id].url + path + (token ? `#t=${token}` : '');
 }
 
-const LOADING_VERBS = {
-  kanban: [
-    'Shuffling cards…',
-    'Herding tasks…',
-    'Waking sessions…',
-    'Sorting the board…',
-    'Pinning sticky notes…',
-    'Moving cards to done…',
-    'Nudging agents…',
-    'Drawing columns…',
-    'Reading the backlog…',
-  ],
-  cost: [
-    'Counting tokens…',
-    'Tallying the bill…',
-    'Stacking bars…',
-    'Crunching numbers…',
-    'Checking the cache hits…',
-    'Adding up the days…',
-    'Balancing the books…',
-    'Plotting the trend…',
-    'Weighing the models…',
-  ],
-  memory: [
-    'Recalling memories…',
-    'Walking the tree…',
-    'Dusting off notes…',
-    'Reading CLAUDE.md…',
-    'Following imports…',
-    'Tracing the context…',
-    'Flipping through pages…',
-    'Connecting the dots…',
-    'Checking what sticks…',
-  ],
-  marketplace: [
-    'Unpacking plugins…',
-    'Polishing skills…',
-    'Dusting off agents…',
-    'Wiring up hooks…',
-    'Fetching manifests…',
-    'Reading SKILL.md files…',
-    'Listing commands…',
-    'Scanning MCP servers…',
-    'Gathering plugins…',
-  ],
-};
+// From each app's manifest. Before /api/config lands there are none, and the first line is generic.
+function loadingVerbs() {
+  const own = apps[activeApp]?.loading?.verbs ?? [];
+  const verbs = own.length ? own : Object.values(apps).flatMap((a) => a.loading?.verbs ?? []);
+  return verbs.length ? verbs : ['Loading…'];
+}
 
 let loadingTimer = null;
 
 function showLoading() {
-  const verbs = LOADING_VERBS[activeApp] ?? Object.values(LOADING_VERBS).flat();
+  const verbs = loadingVerbs();
   const text = document.getElementById('loading-text');
   let i = Math.floor(Math.random() * verbs.length);
   text.textContent = verbs[i];
@@ -255,23 +307,41 @@ function hideLoading() {
   document.getElementById('loading-overlay').classList.add('fade-out');
 }
 
+function makeIframe(id) {
+  const iframe = document.createElement('iframe');
+  iframe.id = `iframe-${id}`;
+  iframe.src = appSrc(id);
+  iframe.className = 'hidden';
+  iframe.allow = 'clipboard-write; microphone';
+  iframe.addEventListener('load', () => onIframeLoad(id));
+  return iframe;
+}
+
 function buildIframes() {
   const container = document.getElementById('iframe-container');
   for (const id of Object.keys(apps)) {
-    const iframe = document.createElement('iframe');
-    iframe.id = `iframe-${id}`;
-    iframe.src = appSrc(id);
-    iframe.className = 'hidden';
-    iframe.allow = 'clipboard-write; microphone';
-    iframe.addEventListener('load', () => onIframeLoad(id));
-    container.appendChild(iframe);
-    iframes[id] = iframe;
+    iframes[id] = makeIframe(id);
+    container.appendChild(iframes[id]);
+  }
+}
+
+const TAB_KEY = 'hub-tab';
+
+function storedTab() {
+  try {
+    return localStorage.getItem(TAB_KEY);
+  } catch {
+    return null;
   }
 }
 
 function switchTab(appId) {
   if (!apps[appId]) return;
+  if (appId !== activeApp) previousApp = activeApp;
   activeApp = appId;
+  try {
+    localStorage.setItem(TAB_KEY, appId);
+  } catch {}
 
   for (const [id, iframe] of Object.entries(iframes)) {
     iframe.classList.toggle('hidden', id !== appId);
@@ -285,20 +355,73 @@ function switchTab(appId) {
 }
 
 function onIframeLoad(appId) {
+  liveApps.delete(appId);
   loadedApps.add(appId);
   guardedApps.delete(appId);
   if (appId === activeApp) hideLoading();
-  const postState = () => {
-    postTo(appId, themeMessage());
-    postProjectTo(appId);
-    postActiveTo(appId);
-    postTo(appId, { type: 'hub:keys', keys: Object.keys(bindings()) });
-  };
-  postState();
-  // Posted twice: the shims gate their origin check on window.__HUB__, which they populate from
-  // an async /hub-config fetch that resolves after this load event, so the first post can be
-  // dropped. Safe to repeat — every shim's apply is idempotent.
-  setTimeout(postState, 400);
+}
+
+function onHello(appId, data) {
+  const common = Array.isArray(data.protocol) ? HUB_PROTOCOLS.filter((v) => data.protocol.includes(v)) : [];
+  if (!common.length) return;
+  liveApps.set(appId, new Set(Array.isArray(data.subscribes) ? data.subscribes : []));
+  postTo(appId, {
+    type: 'hub:welcome',
+    protocol: Math.max(...common),
+    forward: Object.keys(bindings()),
+    themes: hubThemes,
+    actions: Object.keys(actions),
+  });
+  sendTheme(appId);
+  // A document the hub loaded from an action URL got its project from that URL. The hub's own
+  // project would undo the link, so it goes out only with the next change.
+  if (!linkLoads.delete(appId)) sendProject(appId);
+  sendPublished(appId);
+  postActiveTo(appId);
+}
+
+// A url such as '@evil.example/' turns the app host into userinfo, and the token rides in the fragment.
+function navigateApp(appId, url) {
+  const src = appSrc(appId, url);
+  if (!URL.canParse(src) || new URL(src).origin !== originOf(appId)) return;
+  loadApp(appId, src, { link: true });
+}
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function badParams(declared, params) {
+  if (!isPlainObject(params)) return true;
+  const given = Object.entries(params);
+  if (given.some(([name, value]) => !Object.hasOwn(declared, name) || typeof value !== 'string')) return true;
+  return Object.entries(declared).some(([name, type]) => type === 'string' && !Object.hasOwn(params, name));
+}
+
+// Null when the template names a param the call left out.
+function fillUrl(template, params) {
+  const slot = /\{([^}]+)\}/g;
+  if ([...template.matchAll(slot)].some(([, name]) => !Object.hasOwn(params, name))) return null;
+  return template.replace(slot, (_, name) => encodeURIComponent(params[name]));
+}
+
+// Protocol §7. The result does not wait for the handler: the hub queues nothing.
+function onInvoke(appId, { id, action, params = {} }) {
+  if (typeof id !== 'string') return;
+  const reply = (result) => postTo(appId, { type: 'hub:result', id, ...result });
+  const spec = typeof action === 'string' && Object.hasOwn(actions, action) ? actions[action] : null;
+  if (!spec) return reply({ ok: false, reason: 'unhandled' });
+  if (badParams(spec.params, params)) return reply({ ok: false, reason: 'bad-params' });
+  const { app: handler, mode, url: template } = spec;
+  switchTab(handler);
+  if (mode === 'message' && liveApps.has(handler)) {
+    postTo(handler, { type: 'hub:action', id, action, params });
+  } else {
+    // Setting src reloads the app, so a guarded app only gets the switch.
+    const url = template && fillUrl(template, params);
+    if (url && !guardedApps.has(handler)) navigateApp(handler, url);
+  }
+  reply({ ok: true, handledBy: handler });
 }
 
 function listenMessages() {
@@ -309,13 +432,12 @@ function listenMessages() {
     const appId = appIdOf(e.source);
     if (!appId || e.origin !== originOf(appId)) return;
     const data = e.data ?? {};
-    if (data.type === 'hub:navigate') {
-      if (!apps[data.app]) return;
-      switchTab(data.app);
-      if (typeof data.url !== 'string' || !data.url) return;
-      // A url such as '@evil.example/' turns the app host into userinfo, and the token rides in the fragment.
-      const src = appSrc(data.app, data.url);
-      if (URL.canParse(src) && new URL(src).origin === originOf(data.app)) iframes[data.app].src = src;
+    if (data.type === 'hub:hello') {
+      onHello(appId, data);
+    } else if (data.type === 'hub:invoke') {
+      onInvoke(appId, data);
+    } else if (data.type === 'hub:publish') {
+      onPublish(appId, data);
     } else if (data.type === 'hub:keydown') {
       handleForwardedKey(data);
     } else if (data.type === 'hub:closeGuard') {
@@ -333,7 +455,7 @@ function listenMessages() {
         .catch(() => {});
     } else if (data.type === 'hub:openExternal') {
       // In the installed PWA window a framed sub-app's own target=_blank opens
-      // nothing, so the shims hand external links up to the top frame instead.
+      // nothing, so the SDK hands external links up to the top frame instead.
       let url;
       try {
         url = new URL(String(data.url));
@@ -343,7 +465,7 @@ function listenMessages() {
       if (url.protocol !== 'http:' && url.protocol !== 'https:') return;
       window.open(url.href, '_blank', 'noopener');
     } else if (data.type === 'hub:theme') {
-      // Legacy senders pass only {theme}; colorTheme is optional and sticky.
+      // colorTheme is optional and sticky.
       if (data.theme !== 'light' && data.theme !== 'dark') return;
       const hasColor = typeof data.colorTheme === 'string' && /^[a-z0-9-]{0,32}$/.test(data.colorTheme);
       const changed = data.theme !== themeState.theme || (hasColor && data.colorTheme !== activeColorTheme());
@@ -355,32 +477,31 @@ function listenMessages() {
       }
       localStorage.setItem('hub-theme', JSON.stringify(themeState));
       applyHubTheme();
-      broadcast(themeMessage(), e.source);
+      // The sender gets the echo too, for the vars.
+      for (const id of Object.keys(iframes)) sendTheme(id);
     }
   });
 }
 
 function handleForwardedKey(d) {
-  // The modifier fields are new. A sub-app running an older service-worker-cached bundle sends
-  // {key} only; it forwards nothing but the pre-existing bindings, and each of those is
-  // unambiguous from the key alone, so normalize instead of dispatching twice.
-  const legacy = typeof d.alt !== 'boolean';
   const e = {
     key: d.key,
     code: d.code,
-    altKey: legacy || d.alt,
-    ctrlKey: legacy ? d.key.startsWith('Arrow') : d.ctrl,
+    ctrlKey: d.ctrl === true,
+    altKey: d.alt === true,
     shiftKey: d.shift === true,
+    metaKey: d.meta === true,
   };
   bindings()[comboOf(e)]?.run();
 }
 
-// The one keymap. Its combo names are what the hub:keys message lists for the shims.
+// The one keymap. Its combo names are what welcome.forward lists for the apps.
 // inPalette: the binding still fires while the palette is open.
 function bindings() {
   const map = {
     'ctrl+alt+p': { run: () => togglePalette('project'), inPalette: true },
     'ctrl+alt+w': { run: () => togglePalette('configDir'), inPalette: true },
+    'ctrl+alt+a': { run: () => togglePalette('app'), inPalette: true },
     'ctrl+alt+ArrowLeft': { run: () => cycleTab(-1) },
     'ctrl+alt+ArrowRight': { run: () => cycleTab(1) },
   };
@@ -392,7 +513,7 @@ function bindings() {
   return map;
 }
 
-// Each shim's hubCombo() is a copy of this: modifiers in ctrl, alt, shift, meta order, joined by
+// The SDK's comboOf() is a copy of this: modifiers in ctrl, alt, shift, meta order, joined by
 // '+' to the key as bindingKey() names it.
 function comboOf(e) {
   const mods = [e.ctrlKey && 'ctrl', e.altKey && 'alt', e.shiftKey && 'shift', e.metaKey && 'meta'];
@@ -569,6 +690,114 @@ async function removeConfigDir(dirPath) {
   if (palette.open && palette.mode === 'configDir') renderPalette();
 }
 
+// Lucide icons (ISC license) for the names the built-in apps and the Inspector use. Any other
+// manifest icon shows the app's first letter.
+const APP_ICONS = {
+  columns: [
+    ['rect', { width: 18, height: 18, x: 3, y: 3, rx: 2 }],
+    ['path', { d: 'M12 3v18' }],
+  ],
+  store: [
+    ['path', { d: 'm2 7 4.41-4.41A2 2 0 0 1 7.83 2h8.34a2 2 0 0 1 1.42.59L22 7' }],
+    ['path', { d: 'M4 12v8a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-8' }],
+    ['path', { d: 'M15 22v-4a2 2 0 0 0-2-2h-2a2 2 0 0 0-2 2v4' }],
+    ['path', { d: 'M2 7h20' }],
+    [
+      'path',
+      {
+        d: 'M22 7v3a2 2 0 0 1-2 2a2.7 2.7 0 0 1-1.59-.63.7.7 0 0 0-.82 0A2.7 2.7 0 0 1 16 12a2.7 2.7 0 0 1-1.59-.63.7.7 0 0 0-.82 0A2.7 2.7 0 0 1 12 12a2.7 2.7 0 0 1-1.59-.63.7.7 0 0 0-.82 0A2.7 2.7 0 0 1 8 12a2.7 2.7 0 0 1-1.59-.63.7.7 0 0 0-.82 0A2.7 2.7 0 0 1 4 12a2 2 0 0 1-2-2V7',
+      },
+    ],
+  ],
+  'dollar-sign': [
+    ['line', { x1: 12, x2: 12, y1: 2, y2: 22 }],
+    ['path', { d: 'M17 5H9.5a3.5 3.5 0 0 0 0 7h5a3.5 3.5 0 0 1 0 7H6' }],
+  ],
+  database: [
+    ['ellipse', { cx: 12, cy: 5, rx: 9, ry: 3 }],
+    ['path', { d: 'M3 5V19A9 3 0 0 0 21 19V5' }],
+    ['path', { d: 'M3 12A9 3 0 0 0 21 12' }],
+  ],
+  'scan-search': [
+    ['path', { d: 'M3 7V5a2 2 0 0 1 2-2h2' }],
+    ['path', { d: 'M17 3h2a2 2 0 0 1 2 2v2' }],
+    ['path', { d: 'M21 17v2a2 2 0 0 1-2 2h-2' }],
+    ['path', { d: 'M7 21H5a2 2 0 0 1-2-2v-2' }],
+    ['circle', { cx: 12, cy: 12, r: 3 }],
+    ['path', { d: 'm16 16-1.9-1.9' }],
+  ],
+};
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+function svgNode(tag, attrs) {
+  const node = document.createElementNS(SVG_NS, tag);
+  for (const [k, v] of Object.entries(attrs)) node.setAttribute(k, String(v));
+  return node;
+}
+
+function appIcon(app) {
+  const shapes = APP_ICONS[app.icon];
+  if (!shapes) return el('span', 'palette-icon letter', (app.name || '?').slice(0, 1).toUpperCase());
+  const svg = svgNode('svg', {
+    viewBox: '0 0 24 24',
+    fill: 'none',
+    stroke: 'currentColor',
+    'stroke-width': 2,
+    'stroke-linecap': 'round',
+    'stroke-linejoin': 'round',
+    'aria-hidden': 'true',
+  });
+  svg.append(...shapes.map(([tag, attrs]) => svgNode(tag, attrs)));
+  const box = el('span', 'palette-icon');
+  box.append(svg);
+  return box;
+}
+
+function appRows(q) {
+  const list = Object.entries(apps).map(([id, a], i) => ({ kind: 'app', id, app: a, index: i }));
+  if (!q) return list;
+  const hit = list.filter((r) => r.app.name.toLowerCase().includes(q) || r.id.includes(q));
+  return hit.length ? hit : list.filter((r) => subseq(r.app.name.toLowerCase(), q));
+}
+
+// A click on the button runs the mode's rowKeys entry for `key`, the same as Ctrl+<key>.
+function rowButton(className, glyph, key, title, label) {
+  const btn = el('button', className, glyph);
+  btn.type = 'button';
+  btn.title = title;
+  btn.setAttribute('aria-label', label);
+  btn.dataset.rowKey = key;
+  return btn;
+}
+
+function setPaletteHint(text) {
+  document.getElementById('palette-hint').textContent = text;
+}
+
+// The terminal provider answers 409 with a terminal count; the second Ctrl+R on the same app sends force.
+async function restartFromPalette(id) {
+  const name = apps[id]?.name ?? id;
+  const force = palette.confirmRestart === id;
+  palette.confirmRestart = null;
+  setPaletteHint(`Restarting ${name}…`);
+  try {
+    await withPaletteBusy(() => sendJson('POST', `/api/apps/${encodeURIComponent(id)}/restart`, { force }));
+  } catch (err) {
+    if (err.status === 409 && err.data?.terminals) {
+      palette.confirmRestart = id;
+      const n = err.data.terminals;
+      setPaletteHint(
+        `${name} has ${n} live terminal${n === 1 ? '' : 's'}. A restart ends ${n === 1 ? 'it' : 'them'}. Press Ctrl+R again to restart.`,
+      );
+    } else setPaletteHint(`${name} did not restart: ${err.message}`);
+    return;
+  }
+  closePalette();
+  replaceIframe(id);
+  switchTab(id);
+}
+
 // `typed` is the trimmed query, `q` its lowercase form for matching.
 const PALETTE_MODES = {
   project: {
@@ -626,14 +855,33 @@ const PALETTE_MODES = {
         li.append(el('span', 'age', 'active'));
         return;
       }
-      const remove = el('button', 'palette-remove', '×');
-      remove.type = 'button';
-      remove.title = 'Remove from list (Ctrl+D)';
-      remove.dataset.remove = row.path;
-      li.append(remove);
+      li.append(rowButton('palette-remove', '×', 'd', 'Remove from list (Ctrl+D)', `Remove ${row.path}`));
     },
+    rowKeys: { d: (row) => removeConfigDir(row.path) },
     commit: commitConfigDir,
   },
+  app: {
+    placeholder: 'Search apps...',
+    label: 'Switch app',
+    hint: 'Enter switch · Ctrl+R restart the app',
+    empty: 'No matching app',
+    rows: (_typed, q) => appRows(q),
+    initialSel(rows) {
+      const prev = rows.findIndex((r) => r.id === previousApp);
+      return prev < 0 ? 0 : prev;
+    },
+    fillRow(li, row, q) {
+      li.append(appIcon(row.app), markedSpan('name', row.app.name, q));
+      const key = row.id === activeApp ? 'active' : row.index < 9 ? `Alt+${row.index + 1}` : '';
+      li.append(el('span', 'age', key));
+      li.append(rowButton('palette-restart', '↻', 'r', 'Restart the app (Ctrl+R)', `Restart ${row.app.name}`));
+    },
+    rowKeys: { r: (row) => restartFromPalette(row.id) },
+    commit(row) {
+      closePalette();
+      switchTab(row.id);
+    },
+  },
 };
 
 function renderPalette() {
@@ -686,10 +934,11 @@ function openPalette(mode) {
   palette.mode = mode;
   palette.query = '';
   palette.sel = null;
+  palette.confirmRestart = null;
   input.value = '';
   input.placeholder = spec.placeholder;
   document.querySelector('#palette .palette-box').setAttribute('aria-label', spec.label);
-  document.getElementById('palette-hint').textContent = spec.hint ?? '';
+  setPaletteHint(spec.hint ?? '');
   document.getElementById('palette').hidden = false;
   // Ctrl+Alt+P usually arrives forwarded from a focused iframe. Without inert the sub-app can keep
   // or take focus back, and then Escape is handled inside it — the palette stays open and only the
@@ -698,8 +947,7 @@ function openPalette(mode) {
   renderPalette();
   input.focus();
   // Stale-while-revalidate: the cached list renders instantly, recency refreshes when this lands.
-  spec
-    .load()
+  Promise.resolve(spec.load?.())
     .then(() => {
       if (palette.open && palette.mode === mode) renderPalette();
     })
@@ -745,7 +993,7 @@ async function sendJson(method, url, body) {
     body: body === undefined ? undefined : JSON.stringify(body),
   });
   const data = await res.json().catch(() => ({}));
-  if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
+  if (!res.ok) throw Object.assign(new Error(data.error || `HTTP ${res.status}`), { status: res.status, data });
   return data;
 }
 
@@ -823,22 +1071,24 @@ function bindPalette() {
     } else if (e.key === 'ArrowUp' || (e.key === 'Tab' && e.shiftKey)) {
       e.preventDefault();
       movePaletteSel(-1);
-    } else if (e.ctrlKey && !e.altKey && !e.shiftKey && !e.metaKey && e.key.toLowerCase() === 'd') {
+    } else if (e.ctrlKey && !e.altKey && !e.shiftKey && !e.metaKey && ['d', 'r'].includes(e.key.toLowerCase())) {
       // Ctrl+D would otherwise bookmark the page in Chrome and Firefox.
+      // Ctrl+R would otherwise reload the hub page.
       e.preventDefault();
+      const run = PALETTE_MODES[palette.mode].rowKeys?.[e.key.toLowerCase()];
       const row = palette.rows[palette.sel];
-      if (row?.kind === 'dir') removeConfigDir(row.path);
+      if (run && row && row.kind !== 'literal') run(row);
     }
   });
   document.getElementById('palette-list').addEventListener('click', (e) => {
-    const remove = e.target.closest('.palette-remove');
-    if (remove) {
+    const btn = e.target.closest('[data-row-key]');
+    const li = e.target.closest('.palette-row');
+    if (btn) {
       e.stopPropagation();
-      removeConfigDir(remove.dataset.remove);
+      PALETTE_MODES[palette.mode].rowKeys[btn.dataset.rowKey](palette.rows[Number(li.dataset.idx)]);
       document.getElementById('palette-input').focus();
       return;
     }
-    const li = e.target.closest('.palette-row');
     if (!li) return;
     palette.sel = Number(li.dataset.idx);
     commitPalette();