@danieltmn/tamnora 0.21.1 → 0.22.0

package/harness/packages/server/public/commands.js

@@ -0,0 +1,403 @@
+import {
+  INIT_PROMPT,
+  activePane,
+  addCompactCard,
+  addMessage,
+  basename,
+  chatInput,
+  finishCompactCard,
+  refreshSessions,
+  scrollMessages,
+  sendMessage,
+} from './chat.js';
+import {
+  activateTab,
+  createSessionIn,
+  cycleTheme,
+  openAppearance,
+  openFolderPicker,
+  openSettingsModal,
+  setSidebarOpen,
+  toggleMode,
+} from './chrome.js';
+import { $, api, clear, el, state } from './core.js';
+import { setExplorerOpen } from './explorer.js';
+import { renderMarkdown } from './markdown.js';
+import { openTab, syncInterruptBtn } from './sessions.js';
+import { reproducirVoz } from './voice.js';
+
+/* --- command palette (Ctrl/Cmd+K) ----------------------------------------- */
+
+export const PALETTE_COMMANDS = [
+  { id: 'new', label: 'Nueva sesión en otra carpeta', hint: '/new', run: () => openFolderPicker() },
+  { id: 'init', label: 'Analizar el proyecto y crear AGENTS.md', hint: '/init', run: () => runSlash('init') },
+  { id: 'resumen', label: 'Resumir la conversación', hint: '/resumen', run: () => runSlash('resumen') },
+  { id: 'audioresumen', label: 'Resumen como audio', hint: '/audioresumen', run: () => runSlash('audioresumen') },
+  { id: 'compact', label: 'Compactar la conversación', hint: '/compact', run: () => runSlash('compact') },
+  { id: 'clear', label: 'Limpiar la conversación', hint: '/clear', run: () => runSlash('clear') },
+  { id: 'mode', label: 'Cambiar Plan / Build', hint: 'Ctrl+.', run: () => toggleMode() },
+  { id: 'settings', label: 'Ajustes del agente (modelo, modo, auto)', run: () => openSettingsModal() },
+  { id: 'providers', label: 'Gestionar proveedores', run: () => activateTab('providers') },
+  { id: 'ajustes', label: 'MCP y Skills (ajustes)', run: () => activateTab('ajustes') },
+  { id: 'explorer', label: 'Mostrar u ocultar archivos', run: () => setExplorerOpen(!state.explorerOpen) },
+  { id: 'sidebar', label: 'Mostrar u ocultar sesiones', run: () => setSidebarOpen(!state.sidebarOpen) },
+  { id: 'theme', label: 'Cambiar tema', run: () => cycleTheme() },
+  { id: 'apariencia', label: 'Apariencia (tema, tipografía, tamaño)', run: () => openAppearance() },
+];
+
+export const palette = {
+  modal: $('#palette-modal'),
+  input: $('#palette-input'),
+  list: $('#palette-list'),
+  items: [],
+  index: 0,
+  timer: null,
+  results: { sessions: [], messages: [] },
+};
+
+export function runSlash(name) {
+  chatInput.value = `/${name}`;
+  sendMessage();
+}
+
+export function paletteItems(query) {
+  const q = query.trim().toLowerCase();
+  const items = PALETTE_COMMANDS.filter(
+    (c) => !q || c.label.toLowerCase().includes(q) || c.id.includes(q) || (c.hint ?? '').toLowerCase().includes(q)
+  ).map((c) => ({ label: c.label, hint: c.hint || 'comando', run: c.run }));
+
+  for (const session of palette.results.sessions) {
+    items.push({
+      label: session.title || '(sin título)',
+      hint: session.cwd ? basename(session.cwd) : 'sesión',
+      run: () => openTab(session.id),
+    });
+  }
+  for (const message of palette.results.messages) {
+    items.push({
+      label: message.snippet || '(mensaje)',
+      hint: `${message.role} · ${message.title || ''}`,
+      run: () => {
+        openTab(message.sessionId);
+        setTimeout(() => document.getElementById(message.id)?.scrollIntoView({ block: 'center' }), 450);
+      },
+    });
+  }
+  return items;
+}
+
+export function setPaletteIndex(index) {
+  const count = palette.items.length;
+  if (!count) {
+    palette.index = 0;
+    return;
+  }
+  palette.index = ((index % count) + count) % count;
+  [...palette.list.children].forEach((child, i) => child.classList.toggle('active', i === palette.index));
+  palette.list.children[palette.index]?.scrollIntoView({ block: 'nearest' });
+}
+
+export function renderPalette(query) {
+  palette.items = paletteItems(query);
+  palette.list.replaceChildren();
+  if (!palette.items.length) {
+    palette.list.appendChild(el('li', 'palette-empty', 'sin resultados'));
+    return;
+  }
+  palette.items.forEach((item, i) => {
+    const li = el('li', 'palette-item');
+    const main = el('div', 'palette-item-main');
+    main.appendChild(el('span', 'palette-item-label', item.label));
+    if (item.hint) main.appendChild(el('span', 'palette-item-hint', item.hint));
+    li.appendChild(main);
+    li.addEventListener('mousemove', () => setPaletteIndex(i));
+    li.addEventListener('click', () => runPaletteItem(item));
+    palette.list.appendChild(li);
+  });
+  setPaletteIndex(0);
+}
+
+export function runPaletteItem(item) {
+  palette.modal?.close();
+  setTimeout(() => item.run(), 0);
+}
+
+export function openPalette() {
+  if (!palette.modal) return;
+  palette.input.value = '';
+  palette.results = { sessions: [], messages: [] };
+  renderPalette('');
+  palette.modal.showModal();
+  palette.input.focus();
+}
+
+/* --- slash commands ------------------------------------------------------- */
+
+export const COMMANDS = [
+  ['/new', 'nueva sesión (elegís carpeta)'],
+  ['/init', 'analizar el proyecto y crear/actualizar AGENTS.md'],
+  ['/goal <texto>', 'fijar el objetivo de la sesión'],
+  ['/resumen', 'resumir la conversación (sin borrarla)'],
+  ['/audioresumen', 'el resumen como audio'],
+  ['/compact', 'resumir la conversación y liberar contexto'],
+  ['/clear', 'borrar los mensajes de esta sesión'],
+  ['/cwd', 'mostrar la carpeta de trabajo'],
+  ['/port <puerto>', 'ver si un puerto está activo (y qué PID lo usa)'],
+  ['/portkill <puerto>', 'matar el proceso que escucha en un puerto'],
+  ['/help', 'mostrar esta ayuda'],
+];
+
+export function notify(markdown, kind = 'notice') {
+  const message = addMessage('assistant', '');
+  // `kind` puede traer varias clases ("notice err"): classList.add no acepta
+  // espacios, asi que se agregan una por una.
+  for (const cls of String(kind).split(/\s+/).filter(Boolean)) message.textEl.classList.add(cls);
+  message.textEl.innerHTML = renderMarkdown(markdown);
+  scrollMessages();
+  return message;
+}
+
+/**
+ * Aviso flotante para eventos de fondo (un permiso en otra pestana, un run que
+ * arranco desde el celular).
+ *
+ * NO usar `notify` para esto: esa escribe un mensaje en la conversacion del pane
+ * activo, asi que un permiso caido en otra pestana terminaba-chatrandeando en
+ * el chat que estabas leyendo.
+ */
+export function toast(text) {
+  const host = $('#toasts');
+  if (!host) return;
+  const item = el('div', 'toast', text);
+  host.appendChild(item);
+  const timer = setTimeout(() => item.remove(), 6000);
+  item.addEventListener('click', () => {
+    clearTimeout(timer);
+    item.remove();
+  });
+}
+
+export function needSession() {
+  notify('Abrí o creá una sesión primero (`/new`).', 'notice err');
+  return { handled: true };
+}
+
+export async function runCommand(name, arg) {
+  switch (name) {
+    case 'help':
+    case 'ayuda':
+      notify(`### Comandos\n${COMMANDS.map(([cmd, desc]) => `- \`${cmd}\` — ${desc}`).join('\n')}`);
+      return { handled: true };
+    case 'new':
+    case 'nueva': {
+      const cwd = state.sessionId ? state.cwd : '';
+      if (cwd) {
+        const created = await createSessionIn(cwd);
+        if (created?.error) notify(`No se pudo crear la sesión: ${created.error}`, 'notice err');
+      } else {
+        openFolderPicker();
+      }
+      return { handled: true };
+    }
+    case 'init':
+      return { handled: false, input: INIT_PROMPT };
+    case 'cwd': {
+      const cwd = $('#rail-cwd').textContent;
+      notify(`Carpeta de trabajo: \`${cwd}\``);
+      return { handled: true };
+    }
+    case 'portkill':
+    case 'kill': {
+      const port = Number(arg);
+      if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        notify('Uso: `/portkill <puerto>`, por ejemplo `/portkill 3000`.', 'notice err');
+        return { handled: true };
+      }
+      const out = await api('/api/ports/kill', { method: 'POST', body: { port } }).catch((error) => ({
+        error: error.message,
+      }));
+      if (out.error) notify(`No se pudo matar el puerto ${port}: ${out.error}`, 'notice err');
+      else if (!out.pids.length) notify(`No hay ningún proceso escuchando en el puerto ${port}.`);
+      else if (out.killed.length) notify(`Puerto ${port}: maté el PID ${out.killed.join(', ')}.`);
+      else notify(`Puerto ${port}: no se pudo matar (PID ${out.errors.join(', ')}).`, 'notice err');
+      return { handled: true };
+    }
+    case 'port': {
+      const port = Number(arg);
+      if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        notify('Uso: `/port <puerto>`, por ejemplo `/port 3000`.', 'notice err');
+        return { handled: true };
+      }
+      const out = await api(`/api/ports/${port}`).catch((error) => ({ error: error.message }));
+      if (out.error) notify(`No se pudo consultar el puerto ${port}: ${out.error}`, 'notice err');
+      else if (out.listening) notify(`Puerto ${port}: **activo** (PID ${out.pids.join(', ')}).`);
+      else notify(`Puerto ${port}: nada escuchando.`);
+      return { handled: true };
+    }
+    case 'clear':
+    case 'limpiar': {
+      if (!state.sessionId) return needSession();
+      await api(`/api/sessions/${state.sessionId}/messages`, { method: 'DELETE' }).catch(() => null);
+      clear(activePane);
+      activePane.appendChild(el('div', 'empty', 'Sesión vacía.'));
+      return { handled: true };
+    }
+    case 'goal': {
+      if (!state.sessionId) return needSession();
+      if (!arg) {
+        const data = await api(`/api/sessions/${state.sessionId}`).catch(() => null);
+        notify(data?.session?.goal ? `Objetivo actual: **${data.session.goal}**` : 'No hay objetivo fijado.');
+        return { handled: true };
+      }
+      await api(`/api/sessions/${state.sessionId}`, { method: 'PUT', body: { goal: arg } }).catch(() => null);
+      notify(`Objetivo de la sesión: **${arg}**`);
+      return { handled: true };
+    }
+    case 'resumen':
+    case 'resume': {
+      if (!state.sessionId) return needSession();
+      notify('Resumiendo la conversación…');
+      const out = await api(`/api/sessions/${state.sessionId}/summary`, { method: 'POST' }).catch((error) => ({
+        error: error.message,
+      }));
+      if (out.error) notify(`No se pudo resumir: ${out.error}`, 'notice err');
+      else notify(`**Resumen**\n\n${out.summary}`);
+      return { handled: true };
+    }
+    case 'audioresumen':
+    case 'audio-resumen': {
+      if (!state.sessionId) return needSession();
+      notify('Preparando el resumen…');
+      const out = await api(`/api/sessions/${state.sessionId}/summary`, { method: 'POST' }).catch((error) => ({
+        error: error.message,
+      }));
+      if (out.error) {
+        notify(`No se pudo resumir: ${out.error}`, 'notice err');
+        return { handled: true };
+      }
+      notify(`**Resumen**\n\n${out.summary}`);
+      reproducirVoz(out.summary, { label: 'resumen' }).catch((error) => notify(`No se pudo reproducir el audio: ${error.message}`, 'notice err'));
+      return { handled: true };
+    }
+    case 'compact': {
+      if (!state.sessionId) return needSession();
+      // Animación en el pane: el corte queda a la vista con un loader mientras
+      // el modelo resume (puede tardar), y se completa con el resumen.
+      const card = addCompactCard(activePane, { running: true });
+      scrollMessages();
+      const out = await api(`/api/sessions/${state.sessionId}/compact`, { method: 'POST' }).catch((error) => ({
+        error: error.message,
+      }));
+      if (out.error) {
+        card?.remove();
+        notify(`No se pudo compactar: ${out.error}`, 'notice err');
+        return { handled: true };
+      }
+      // No borramos el pane: el historial queda a la vista y marcamos el corte
+      // con la línea + el resumen que ahora ve el modelo.
+      finishCompactCard(card, out.summary);
+      scrollMessages();
+      refreshSessions();
+      return { handled: true };
+    }
+    default:
+      notify(`Comando desconocido: \`/${name}\`. Probá \`/help\`.`, 'notice err');
+      return { handled: true };
+  }
+}
+
+/* --- menú de comandos "/" ------------------------------------------------- */
+
+export const slashMenuEl = $('#slash-menu');
+export let slashMatches = [];
+export let slashIndex = 0;
+
+export function slashCommandEntries() {
+  return COMMANDS.map(([cmd, desc]) => {
+    const name = cmd.split(' ')[0];
+    const takesArgs = cmd.includes(' ');
+    return { name, desc, insert: takesArgs ? `${name} ` : name, takesArgs };
+  });
+}
+
+export function hideSlashMenu() {
+  if (!slashMenuEl) return;
+  slashMenuEl.hidden = true;
+  slashMenuEl.replaceChildren();
+  slashMatches = [];
+  slashIndex = 0;
+}
+
+export function renderSlashMenu() {
+  if (!slashMenuEl) return;
+  slashMenuEl.replaceChildren();
+  slashMatches.forEach((entry, index) => {
+    const item = el('button', `slash-item${index === slashIndex ? ' active' : ''}`);
+    item.type = 'button';
+    item.append(el('span', 'slash-cmd', entry.name), el('span', 'slash-desc', entry.desc));
+    // mousedown (no click) para no perder el foco del textarea antes de elegir.
+    item.addEventListener('mousedown', (event) => {
+      event.preventDefault();
+      chooseSlash(index);
+    });
+    slashMenuEl.appendChild(item);
+  });
+  slashMenuEl.hidden = false;
+}
+
+export function updateSlashMenu() {
+  if (!slashMenuEl) return;
+  const value = chatInput.value;
+  if (!value.startsWith('/') || /\s/.test(value)) return hideSlashMenu();
+  const query = value.slice(1).toLowerCase();
+  slashMatches = slashCommandEntries().filter(
+    (entry) =>
+      entry.name.slice(1).toLowerCase().startsWith(query) || entry.desc.toLowerCase().includes(query)
+  );
+  if (!slashMatches.length) return hideSlashMenu();
+  if (slashIndex >= slashMatches.length) slashIndex = 0;
+  renderSlashMenu();
+}
+
+export function chooseSlash(index) {
+  const entry = slashMatches[index];
+  if (!entry) return;
+  chatInput.value = entry.insert;
+  chatInput.focus();
+  hideSlashMenu();
+  if (!entry.takesArgs) sendMessage();
+}
+
+export function handleSlashKey(event) {
+  if (!slashMenuEl || slashMenuEl.hidden || !slashMatches.length) return false;
+  if (event.key === 'ArrowDown') {
+    event.preventDefault();
+    slashIndex = (slashIndex + 1) % slashMatches.length;
+    renderSlashMenu();
+    return true;
+  }
+  if (event.key === 'ArrowUp') {
+    event.preventDefault();
+    slashIndex = (slashIndex - 1 + slashMatches.length) % slashMatches.length;
+    renderSlashMenu();
+    return true;
+  }
+  if (event.key === 'Escape') {
+    event.preventDefault();
+    hideSlashMenu();
+    return true;
+  }
+  if (event.key === 'Enter' || event.key === 'Tab') {
+    event.preventDefault();
+    chooseSlash(slashIndex);
+    return true;
+  }
+  return false;
+}
+
+export function onChatInputChanged() {
+  slashIndex = 0;
+  updateSlashMenu();
+  syncInterruptBtn();
+}
+

package/harness/packages/server/public/core.js

@@ -0,0 +1,209 @@
+import { streamSse } from './runStream.js';
+
+let csrfToken = '';
+
+/** El token CSRF lo fija `boot()` tras leer `/api/auth/me`. */
+export function setCsrfToken(token) {
+  csrfToken = token || '';
+}
+
+export const $ = (sel) => document.querySelector(sel);
+
+export const state = {
+  sessionId: null,
+  streaming: false,
+  providers: [],
+  active: { provider: '', model: '' },
+  pendingInput: null,
+  permissionCards: new Map(),
+  questionCards: new Map(),
+  attachments: [],
+  home: null,
+  cwd: '',
+  explorerOpen: false,
+  sidebarOpen: true,
+  panes: new Map(),
+  tabOrder: [],
+  activeTab: null,
+  queues: new Map(),
+  // Grupos de sesiones abiertos a mano. Arranca vacio y NO se persiste: el
+  // sidebar siempre empieza con todas las carpetas sin expandir.
+  expandedGroups: new Set(),
+  // Sesiones con un run vivo segun el canal global de eventos. El sidebar lo
+  // usa para el punto de actividad antes de abrir la sesion.
+  remoteActive: new Set(),
+  // Permisos esperando decision: askId -> { sessionId, name, args }. Vive fuera
+  // del stream a proposito: un cliente sin stream abierto igual tiene que poder
+  // ver que la IA esta esperando una autorizacion suya.
+  pendingAsks: new Map(),
+  // Formularios interactivos (`ask_user`) esperando respuesta: askId -> { sessionId }.
+  pendingQuestions: new Map(),
+  // Ponerlo en cola para reconciliar apenas termine la que esta en curso.
+  reconcileAgain: false,
+};
+
+/* --- DOM helpers --------------------------------------------------------- */
+
+export function el(tag, className = '', text = '') {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text) node.textContent = text;
+  return node;
+}
+
+export function button(label, onClick, className = 'btn') {
+  const node = el('button', className, label);
+  node.type = 'button';
+  node.addEventListener('click', onClick);
+  return node;
+}
+
+export function clear(node) {
+  node.replaceChildren();
+}
+
+export const ICON_PATHS = {
+  x: ['M18 6 6 18', 'm6 6 12 12'],
+  'chevron-right': ['m9 18 6-6-6-6'],
+  'chevron-down': ['m6 9 6 6 6-6'],
+  folder: ['M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z'],
+  'folder-open': ['m6 14 1.45-2.9A2 2 0 0 1 9.24 10H20a2 2 0 0 1 1.94 2.5l-1.55 6a2 2 0 0 1-1.94 1.5H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h3.9a2 2 0 0 1 1.69.9l.81 1.2a2 2 0 0 0 1.67.9H18a2 2 0 0 1 2 2v2'],
+  file: ['M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z', 'M14 2v4a2 2 0 0 0 2 2h4'],
+  'refresh-cw': ['M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8', 'M21 3v5h-5', 'M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16', 'M8 16H3v5'],
+  undo: ['M3 7v6h6', 'M3 13a9 9 0 1 1 2.64 6.36'],
+  trash: ['M3 6h18', 'M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6', 'M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2', 'M10 11v6', 'M14 11v6'],
+  'dots-vertical': ['M12 5h.01', 'M12 12h.01', 'M12 19h.01'],
+  'dots-horizontal': ['M5 12h.01', 'M12 12h.01', 'M19 12h.01'],
+  play: ['m6 4 14 8-14 8z'],
+  pause: ['M8 5v14', 'M16 5v14'],
+  square: ['M6 6h12v12H6z'],
+  copy: ['M8 8V5a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2h-3', 'M5 8h9a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-9a2 2 0 0 1 2-2Z'],
+  pencil: ['M17 3a2.85 2.83 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5Z', 'm15 5 4 4'],
+};
+
+export function icon(name, size = 16, className = '') {
+  const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+  if (className) svg.setAttribute('class', className);
+  for (const [key, value] of Object.entries({ viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', 'stroke-width': '1.8', 'stroke-linecap': 'round', 'stroke-linejoin': 'round', width: String(size), height: String(size), 'aria-hidden': 'true' })) {
+    svg.setAttribute(key, value);
+  }
+  for (const d of ICON_PATHS[name] ?? []) {
+    const node = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+    node.setAttribute('d', d);
+    svg.appendChild(node);
+  }
+  return svg;
+}
+
+/**
+ * Confirmacion accesible (reemplaza `window.confirm`): `<dialog>` modal con
+ * Escape, foco inicial en cancelar y respuesta booleana.
+ */
+export function showConfirm(
+  message,
+  { title = 'Confirmar', confirmLabel = 'aceptar', cancelLabel = 'cancelar', danger = false } = {}
+) {
+  return new Promise((resolve) => {
+    const dialog = document.createElement('dialog');
+    dialog.className = 'modal confirm-modal';
+    dialog.setAttribute('aria-label', title);
+    const card = el('div', 'modal-card');
+    card.append(el('h3', '', title), el('p', 'confirm-text', message));
+    const actions = el('div', 'confirm-actions');
+    const cancel = button(cancelLabel, () => dialog.close('cancel'), 'btn');
+    const ok = button(confirmLabel, () => dialog.close('confirm'), danger ? 'btn danger' : 'btn primary');
+    actions.append(cancel, ok);
+    card.append(actions);
+    dialog.append(card);
+    dialog.addEventListener('close', () => {
+      resolve(dialog.returnValue === 'confirm');
+      dialog.remove();
+    });
+    document.body.append(dialog);
+    dialog.showModal();
+    cancel.focus();
+  });
+}
+
+/* --- HTTP / SSE ---------------------------------------------------------- */
+
+// La cookie de sesion puede vencer con la pestana abierta: sin este interceptor
+// la UI mostraba tostadas genericas en cada accion. Un 401 = a la pantalla de
+// acceso, una sola vez.
+let sessionExpired = false;
+
+export async function api(path, { method = 'GET', body, headers = {} } = {}) {
+  const init = {};
+  if (body) init['Content-Type'] = 'application/json';
+  if (method !== 'GET' && csrfToken) init['x-csrf'] = csrfToken;
+  const res = await fetch(path, {
+    method,
+    headers: { ...init, ...headers },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) {
+    let message = res.statusText;
+    try {
+      message = (await res.json()).error ?? message;
+    } catch {
+      // keep statusText
+    }
+    const error = new Error(message);
+    // El status importa: un 409 significa que otro cliente tiene el turno.
+    error.status = res.status;
+    if (res.status === 401 && !sessionExpired) {
+      sessionExpired = true;
+      location.assign('/landing');
+    }
+    throw error;
+  }
+  return res.json();
+}
+
+export const streamPost = (url, body, onEvent, signal) =>
+  streamSse(url, { method: 'POST', body, csrf: csrfToken, signal }, onEvent);
+
+/** SSE GET de la consola (/api/sessions/:id/stream, /api/events). */
+export const openStream = (url, opts, onEvent) => streamSse(url, opts, onEvent);
+
+/* --- localStorage (todas las lecturas/escrituras pasan por aca) ------------ */
+
+export const storage = {
+  get(key, fallback = null) {
+    try {
+      const raw = localStorage.getItem(key);
+      return raw === null ? fallback : raw;
+    } catch {
+      return fallback;
+    }
+  },
+  getJson(key, fallback) {
+    try {
+      const raw = localStorage.getItem(key);
+      return raw === null ? fallback : JSON.parse(raw);
+    } catch {
+      return fallback;
+    }
+  },
+  set(key, value) {
+    try {
+      localStorage.setItem(key, value);
+    } catch {
+      // storage unavailable
+    }
+  },
+  setJson(key, value) {
+    try {
+      localStorage.setItem(key, JSON.stringify(value));
+    } catch {
+      // storage unavailable
+    }
+  },
+  remove(key) {
+    try {
+      localStorage.removeItem(key);
+    } catch {
+      // storage unavailable
+    }
+  },
+};