claude-code-kanban 4.14.1 → 4.17.0

package/public/app.js

@@ -1,13 +1,17 @@
 //#region STATE
+// The baseline "nothing is filtered" state: what resetState() returns to, what updateUrl() omits
+// from the query string, and what decides whether a control tints ember in the header summary.
+const FILTER_DEFAULTS = { project: '__recent__', session: 'active', limit: '20' };
+
 let sessions = [];
 let currentSessionId = null;
 let currentTasks = [];
 let viewMode = 'session';
-let sessionFilter = 'active';
+let sessionFilter = FILTER_DEFAULTS.session;
 // Only meaningful while sessionFilter === 'active' (filterBySessions clears it otherwise)
 const activityFilter = new Set(); // kinds: 'waiting' | 'active'
-let sessionLimit = '20';
-let filterProject = '__recent__'; // null = all, '__recent__' = last 24h, or project path
+let sessionLimit = FILTER_DEFAULTS.limit;
+let filterProject = FILTER_DEFAULTS.project; // null = all, '__recent__' = last 24h, or project path
 let recentProjects = new Set();
 let projectsCacheDirty = true;
 const collapsedProjectGroups = new Set();
@@ -75,9 +79,9 @@ function updateUrl() {
   if (viewMode === 'all') params.set('view', 'all');
   if (viewMode === 'project' && currentProjectPath) params.set('projectView', btoa(currentProjectPath));
   if (currentSessionId) params.set('session', currentSessionId);
-  if (sessionFilter !== 'active') params.set('filter', sessionFilter);
-  if (sessionLimit !== '20') params.set('limit', sessionLimit);
-  if (filterProject && filterProject !== '__recent__') params.set('project', filterProject);
+  if (sessionFilter !== FILTER_DEFAULTS.session) params.set('filter', sessionFilter);
+  if (sessionLimit !== FILTER_DEFAULTS.limit) params.set('limit', sessionLimit);
+  if (filterProject && filterProject !== FILTER_DEFAULTS.project) params.set('project', filterProject);
   if (ownerFilter) params.set('owner', ownerFilter);
   if (searchQuery) params.set('search', searchQuery);
   if (messagePanelOpen) params.set('messages', '1');
@@ -94,6 +98,9 @@ function persistLastView() {
       view: viewMode,
       session: currentSessionId,
       projectPath: viewMode === 'project' ? currentProjectPath : null,
+      // The project filter also lives in the URL, but the hub recreates each iframe at the app's
+      // base URL on reload, so the query string alone doesn't survive a hub refresh.
+      project: filterProject,
     };
     localStorage.setItem(LAST_VIEW_KEY, JSON.stringify(data));
   } catch (_) {}
@@ -112,9 +119,9 @@ function resetState() {
   try {
     localStorage.removeItem(LAST_VIEW_KEY);
   } catch (_) {}
-  sessionFilter = 'active';
-  sessionLimit = '20';
-  filterProject = '__recent__';
+  sessionFilter = FILTER_DEFAULTS.session;
+  sessionLimit = FILTER_DEFAULTS.limit;
+  filterProject = FILTER_DEFAULTS.project;
   ownerFilter = '';
   searchQuery = '';
   viewMode = 'all';
@@ -126,7 +133,7 @@ function resetState() {
   const searchInput = document.getElementById('search-input');
   if (searchInput) searchInput.value = '';
   document.getElementById('search-clear-btn')?.classList.remove('visible');
-  loadPreferences();
+  renderFilterState();
   fetchSessions().then(() => showAllTasks());
 }
 
@@ -1328,6 +1335,8 @@ const ICON_COPY =
   '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>';
 const ICON_CHECKMARK =
   '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" width="16" height="16"><path d="M20 6L9 17l-5-5"/></svg>';
+const ICON_PLAN =
+  '<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="16" y1="13" x2="8" y2="13"/><line x1="16" y1="17" x2="8" y2="17"/></svg>';
 const ICON_AGENT_WAITING =
   '<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>';
 const ICON_AGENT_ACTIVE =
@@ -2940,15 +2949,15 @@ function renderSessions() {
             <div class="session-progress">
               <span class="session-indicators">
                 ${isTeam ? `<span class="team-badge" title="${memberCount} team members"><svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"/><circle cx="9" cy="7" r="4"/><path d="M23 21v-2a4 4 0 0 0-3-3.87"/><path d="M16 3.13a4 4 0 0 1 0 7.75"/></svg>${memberCount}</span>` : ''}
-                ${session.sharedTaskList ? `<span class="shared-tasklist-badge" title="Shared task list: ${escapeHtml(session.sharedTaskList)}">${linkSvg(12)}</span>` : ''}
                 ${isTeam || session.project || showCtx ? `<span class="team-info-btn" onclick="event.stopPropagation(); showSessionInfoModal('${session.id}')" title="View session info"><svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg></span>` : ''}
-                ${session.hasPlan && !session.planSourceSessionId ? `<span class="plan-indicator" onclick="event.stopPropagation(); openPlanForSession('${session.id}')" title="View plan"><svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="16" y1="13" x2="8" y2="13"/><line x1="16" y1="17" x2="8" y2="17"/></svg></span>` : ''}
-                ${renderLoopBadge(session)}
                 ${renderWorkflowBadge(session)}
-                ${linkedDocsCount > 0 ? `<span class="linked-docs-badge" onclick="event.stopPropagation(); showSessionInfoModal('${session.id}')" title="${linkedDocsCount} linked document${linkedDocsCount > 1 ? 's' : ''}">${linkSvg(10)}${linkedDocsCount}</span>` : ''}
-                ${bookmarksCount > 0 ? `<span class="bookmarks-badge" onclick="event.stopPropagation(); openSessionWithBookmarks('${session.id}')" title="${bookmarksCount} bookmarked message${bookmarksCount > 1 ? 's' : ''}"><svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z"/></svg>${bookmarksCount}</span>` : ''}
+                ${renderLoopBadge(session)}
                 ${hasScratchpad ? `<span class="scratchpad-badge" onclick="event.stopPropagation(); openSessionScratchpad('${session.id}')" title="Open scratchpad"><svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7"/><path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z"/></svg></span>` : ''}
-                ${session.planSourceSessionId ? `<span class="plan-indicator" title="Implements plan — click to reveal plan session" onclick="event.stopPropagation(); revealPlanSession('${escapeHtml(session.planSourceSessionId)}')"><svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="16" y1="13" x2="8" y2="13"/><line x1="16" y1="17" x2="8" y2="17"/></svg></span>` : ''}
+                ${bookmarksCount > 0 ? `<span class="bookmarks-badge" onclick="event.stopPropagation(); openSessionWithBookmarks('${session.id}')" title="${bookmarksCount} bookmarked message${bookmarksCount > 1 ? 's' : ''}"><svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z"/></svg>${bookmarksCount}</span>` : ''}
+                ${linkedDocsCount > 0 ? `<span class="linked-docs-badge" onclick="event.stopPropagation(); showSessionInfoModal('${session.id}')" title="${linkedDocsCount} linked document${linkedDocsCount > 1 ? 's' : ''}">${linkSvg(10)}${linkedDocsCount}</span>` : ''}
+                ${session.hasPlan && !session.planSourceSessionId ? `<span class="plan-indicator" onclick="event.stopPropagation(); openPlanForSession('${session.id}')" title="View plan">${ICON_PLAN}</span>` : ''}
+                ${session.planSourceSessionId ? `<span class="plan-indicator" title="Implements plan — click to reveal plan session" onclick="event.stopPropagation(); revealPlanSession('${escapeHtml(session.planSourceSessionId)}')">${ICON_PLAN}</span>` : ''}
+                ${session.sharedTaskList ? `<span class="shared-tasklist-badge" title="Shared task list: ${escapeHtml(session.sharedTaskList)}">${linkSvg(12)}</span>` : ''}
                 ${session.hasWaitingForUser ? `<span class="agent-badge agent-badge-waiting" title="Waiting for user">${ICON_AGENT_WAITING}</span>` : ''}
                 ${session.hasRunningAgents && !session.hasWaitingForUser ? `<span class="agent-badge agent-badge-active" title="Agents running">${ICON_AGENT_ACTIVE}</span>` : ''}
                 ${isLive || session.hasRunningAgents ? `<span class="pulse" title="${isLive ? 'Live' : 'Active agents'}"></span>` : ''}
@@ -4204,8 +4213,8 @@ function showStorageManager() {
   document.querySelectorAll('.storage-tab').forEach((t) => {
     t.classList.toggle('active', t.dataset.tab === 'sessions');
   });
-  _renderStorageTab();
   document.getElementById('storage-modal').classList.add('visible');
+  _renderStorageTab();
 }
 
 function closeStorageManager() {
@@ -4221,6 +4230,8 @@ function switchStorageTab(tab) {
 }
 
 function _renderStorageTab() {
+  const modal = document.getElementById('storage-modal');
+  if (!modal?.classList.contains('visible')) return;
   const body = document.getElementById('storage-modal-body');
   const tab = document.querySelector('.storage-tab.active')?.dataset.tab || 'sessions';
   if (tab === 'sessions') body.innerHTML = _renderStorageSessions();
@@ -4513,19 +4524,12 @@ function _storagePreviewLinkedDoc(path) {
 }
 
 function _storageUnlinkDoc(sessionId, path) {
-  removeSessionPreviewPath(sessionId, path);
-  if (sessionId === _infoModalSessionId) refreshInfoModalLinkedDocs();
-  renderSessions();
-  _renderStorageTab();
-  _updateStorageTotal();
+  setSessionDocLink(sessionId, path, true);
 }
 
 function _storageClearLinkedDocs(sessionId) {
   localStorage.removeItem(PREVIEW_STORAGE_PREFIX + sessionId);
-  if (sessionId === _infoModalSessionId) refreshInfoModalLinkedDocs();
-  renderSessions();
-  _renderStorageTab();
-  _updateStorageTotal();
+  afterLinkedDocsChanged(sessionId);
 }
 
 function _findOrphanedKeys() {
@@ -4946,6 +4950,25 @@ function removeSessionPreviewPath(sessionId, filePath) {
   else localStorage.removeItem(PREVIEW_STORAGE_PREFIX + sessionId);
 }
 
+// Every surface that shows linked docs — info modal, session card badge, preview
+// toolbar toggle, storage manager — refreshes from one place, so a new mutator
+// can never forget one of them.
+// The one mutator: link/unlink plus the refresh, so no caller can do half of it.
+function setSessionDocLink(sessionId, filePath, unlink) {
+  if (!sessionId || !filePath) return;
+  if (unlink) removeSessionPreviewPath(sessionId, filePath);
+  else addSessionPreviewPath(sessionId, filePath);
+  afterLinkedDocsChanged(sessionId);
+}
+
+function afterLinkedDocsChanged(sessionId) {
+  if (_infoModalSessionId === sessionId) refreshInfoModalLinkedDocs();
+  renderSessions();
+  updatePreviewLinkBtn();
+  _renderStorageTab();
+  _updateStorageTotal();
+}
+
 function splitFrontmatter(text) {
   const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
   if (!m) return { fm: null, body: text };
@@ -4967,27 +4990,50 @@ function renderFrontmatterBlock(fm) {
   return `<details class="preview-fm" open><summary>frontmatter</summary><div class="fm-grid">${rows}</div></details>`;
 }
 
-function openPreviewModal(filePath, content) {
+// Previewed HTML is rendered as authored, not sanitized: the sandbox without
+// allow-same-origin puts it on an opaque origin, so it cannot touch this app's
+// storage, DOM or API. Sibling local assets don't load — srcdoc has no base URL.
+function renderHtmlPreview(bodyEl, content) {
+  bodyEl.innerHTML = '';
+  const frame = document.createElement('iframe');
+  frame.className = 'preview-html-frame';
+  frame.setAttribute('sandbox', 'allow-scripts allow-popups');
+  frame.setAttribute('referrerpolicy', 'no-referrer');
+  frame.srcdoc = content;
+  bodyEl.appendChild(frame);
+}
+
+function bindPreviewRelativeLinks(bodyEl) {
+  if (bodyEl.dataset.relLinkBound) return;
+  bodyEl.addEventListener('click', (e) => {
+    const a = e.target.closest('a[href]');
+    if (!a) return;
+    const href = a.getAttribute('href');
+    if (!href || href.startsWith('#')) return;
+    const isAbsoluteUrl = /^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('//');
+    const isAbsolutePath = href.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(href);
+    if (isAbsoluteUrl) return;
+    const cleanHref = href.replace(/#.*$/, '');
+    if (!isPreviewablePath(cleanHref)) return;
+    e.preventDefault();
+    openPreviewByPath(cleanHref, isAbsolutePath ? undefined : currentPreviewPath);
+  });
+  bodyEl.dataset.relLinkBound = '1';
+}
+
+// `kind` comes from the server, which is the only place that decides what is previewable.
+function openPreviewModal(filePath, content, kind) {
   currentPreviewPath = filePath;
   document.getElementById('preview-modal-title').textContent = filePath.split(/[\\/]/).pop();
-  const { fm, body } = /\.(md|markdown)$/i.test(filePath) ? splitFrontmatter(content) : { fm: null, body: content };
   const bodyEl = document.getElementById('preview-modal-body');
-  bodyEl.innerHTML = (fm ? renderFrontmatterBlock(fm) : '') + renderMarkdown(body);
-  if (!bodyEl.dataset.relLinkBound) {
-    bodyEl.addEventListener('click', (e) => {
-      const a = e.target.closest('a[href]');
-      if (!a) return;
-      const href = a.getAttribute('href');
-      if (!href || href.startsWith('#')) return;
-      const isAbsoluteUrl = /^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('//');
-      const isAbsolutePath = href.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(href);
-      if (isAbsoluteUrl) return;
-      if (!/\.(md|markdown)(#.*)?$/i.test(href)) return;
-      e.preventDefault();
-      const cleanHref = href.replace(/#.*$/, '');
-      openPreviewByPath(cleanHref, isAbsolutePath ? undefined : currentPreviewPath);
-    });
-    bodyEl.dataset.relLinkBound = '1';
+  const isHtml = kind === 'html';
+  document.querySelector('#preview-modal .modal').classList.toggle('preview-html', isHtml);
+  bindPreviewRelativeLinks(bodyEl);
+  if (isHtml) {
+    renderHtmlPreview(bodyEl, content);
+  } else {
+    const { fm, body } = splitFrontmatter(content);
+    bodyEl.innerHTML = (fm ? renderFrontmatterBlock(fm) : '') + renderMarkdown(body);
   }
   document.getElementById('preview-modal-meta').textContent = filePath;
   document.getElementById('preview-modal').classList.add('visible');
@@ -5018,49 +5064,32 @@ function togglePreviewSessionLink() {
     showToast('Select a session first');
     return;
   }
-  if (isPreviewLinkedToCurrentSession()) {
-    removeSessionPreviewPath(currentSessionId, currentPreviewPath);
-    showToast('Unlinked from session');
-  } else {
-    addSessionPreviewPath(currentSessionId, currentPreviewPath);
-    showToast('Linked to session');
-  }
-  updatePreviewLinkBtn();
-  if (_infoModalSessionId === currentSessionId) {
-    refreshInfoModalLinkedDocs();
-  }
-  renderSessions();
+  const unlink = isPreviewLinkedToCurrentSession();
+  setSessionDocLink(currentSessionId, currentPreviewPath, unlink);
+  showToast(unlink ? 'Unlinked from session' : 'Linked to session');
 }
 
 function refreshInfoModalLinkedDocs() {
   const bodyEl = document.getElementById('team-modal-body');
   if (!bodyEl) return;
   const existing = bodyEl.querySelector('.linked-docs-section');
-  const html = renderLinkedDocsHtml(_infoModalSessionId);
-  if (!existing) {
-    if (!html) return;
+  const wrap = document.createElement('div');
+  wrap.innerHTML = renderLinkedDocsHtml(_infoModalSessionId);
+  const node = wrap.firstElementChild;
+  if (existing) {
+    existing.replaceWith(node);
+  } else {
     const planCard = bodyEl.querySelector('[data-plan-card]');
-    const wrap = document.createElement('div');
-    wrap.innerHTML = html;
-    const node = wrap.firstElementChild;
     if (planCard?.nextSibling) planCard.parentNode.insertBefore(node, planCard.nextSibling);
     else bodyEl.appendChild(node);
-    bindLinkedDocsHandlers(node, _infoModalSessionId);
-    return;
-  }
-  if (!html) {
-    existing.remove();
-    return;
   }
-  const wrap = document.createElement('div');
-  wrap.innerHTML = html;
-  const node = wrap.firstElementChild;
-  existing.replaceWith(node);
   bindLinkedDocsHandlers(node, _infoModalSessionId);
 }
 
 function closePreviewModal() {
   resetModalFullscreen('preview-modal');
+  // Empty the body so an iframe preview is destroyed and its scripts/timers stop.
+  document.getElementById('preview-modal-body').innerHTML = '';
   currentPreviewPath = null;
 }
 
@@ -5081,7 +5110,7 @@ async function openPreviewByPath(filePath, base) {
       return;
     }
     const data = await r.json();
-    openPreviewModal(data.path, data.content);
+    openPreviewModal(data.path, data.content, data.kind);
   } catch {
     showToast('Failed to load preview');
   }
@@ -5108,7 +5137,7 @@ function handleSessionOpenEvent(data) {
 }
 
 async function handlePreviewOpenEvent(data) {
-  const { path: filePath, content, sessionId } = data;
+  const { path: filePath, sessionId } = data;
   if (sessionId && sessionId !== currentSessionId) {
     if (sessions.find((s) => s.id === sessionId)) {
       await fetchTasks(sessionId);
@@ -5116,7 +5145,17 @@ async function handlePreviewOpenEvent(data) {
       showToast(`Preview received for unknown session ${sessionId.slice(0, 8)}`);
     }
   }
-  openPreviewModal(filePath, content);
+  // The broadcast carries the path only — each tab fetches the document itself.
+  openPreviewByPath(filePath);
+}
+
+// Linked docs live in localStorage, so the CLI can only reach them through a tab:
+// the server broadcasts the resolved path and every tab applies it idempotently.
+function handleDocumentLinkEvent(data) {
+  const { path: filePath, sessionId, unlink } = data;
+  if (!filePath || !sessionId) return;
+  setSessionDocLink(sessionId, filePath, unlink);
+  showToast(`${unlink ? 'Unlinked' : 'Linked'} ${filePath.split(/[\\/]/).pop()}`);
 }
 
 function getSessionBaseDir(sessionId) {
@@ -5124,42 +5163,123 @@ function getSessionBaseDir(sessionId) {
   return s?.cwd || s?.project || '';
 }
 
+// Linked paths are stored as bare strings, so previewability is re-derived from the
+// extension on every render instead of being remembered alongside the path.
+function isPreviewablePath(p) {
+  return /\.(md|markdown|html?)$/i.test(p);
+}
+
 function renderLinkedDocsHtml(sessionId) {
   const paths = getSessionPreviewPaths(sessionId);
-  if (!paths.length) return '';
   const baseDir = getSessionBaseDir(sessionId);
   const items = paths
-    .map((p, i) => {
+    .map((p) => {
       const name = p.split(/[\\/]/).pop();
       const rel = baseDir ? toRelativeIfUnder(p, baseDir) : null;
+      const previewable = isPreviewablePath(p);
+      const title = previewable ? p : `${p} — opens in editor`;
       const pathSpan = rel ? `<span class="linked-doc-path" title="${escapeHtml(p)}">${escapeHtml(rel)}</span>` : '';
-      return `<li class="linked-doc-item">
-        <a href="#" class="linked-doc-link" data-idx="${i}" title="${escapeHtml(p)}">${escapeHtml(name)}</a>
-        ${pathSpan}
+      const attr = escapeHtml(p);
+      return `<li class="linked-doc-item${previewable ? '' : ' is-editor'}">
+        <a href="#" class="linked-doc-link" data-path="${attr}" title="${escapeHtml(title)}">${escapeHtml(name)}</a>
+        ${pathSpan}${previewable ? '' : '<span class="linked-doc-path">(editor)</span>'}
+        <button type="button" class="linked-doc-remove" data-path="${attr}" title="Unlink" aria-label="Unlink ${escapeHtml(name)}">&times;</button>
       </li>`;
     })
     .join('');
+  // Rendered even when empty — the add button has to stay reachable.
+  const body = paths.length
+    ? `<ul class="linked-doc-list">${items}</ul>`
+    : '<div class="linked-docs-empty">No linked files yet</div>';
   return `<div class="linked-docs-section" style="margin-bottom:16px;font-size:12px;">
     <div style="font-size:11px;font-weight:500;color:var(--text-muted);text-transform:uppercase;letter-spacing:0.5px;margin-bottom:6px;display:flex;align-items:center;gap:6px;">
       ${linkSvg(12)}
       <span>Linked documents</span>
       <span style="background:var(--bg-elevated);border:1px solid var(--border);border-radius:10px;padding:0 6px;font-size:10px;color:var(--text-secondary);">${paths.length}</span>
+      <button type="button" class="linked-docs-add-btn" title="Link a file" aria-label="Link a file">+</button>
     </div>
-    <ul class="linked-doc-list">${items}</ul>
+    <div class="linked-doc-editor-slot"></div>
+    ${body}
   </div>`;
 }
 
+// One delegated listener per section: the list is re-rendered on every change, so
+// per-row handlers would only be rebound each time anyway.
 function bindLinkedDocsHandlers(container, sessionId) {
   if (!container) return;
-  const links = container.querySelectorAll('.linked-doc-link');
-  if (!links.length) return;
-  const paths = getSessionPreviewPaths(sessionId);
-  const base = getSessionBaseDir(sessionId);
-  for (const link of links) {
-    link.addEventListener('click', (e) => {
+  container.addEventListener('click', (e) => {
+    const hit = e.target.closest('.linked-doc-link, .linked-doc-remove, .linked-docs-add-btn');
+    if (!hit) return;
+    e.preventDefault();
+    if (hit.classList.contains('linked-docs-add-btn')) {
+      startLinkedDocInput(container, sessionId);
+    } else if (hit.classList.contains('linked-doc-remove')) {
+      removeSessionPreviewPath(sessionId, hit.dataset.path);
+      afterLinkedDocsChanged(sessionId);
+    } else if (isPreviewablePath(hit.dataset.path)) {
+      openPreviewByPath(hit.dataset.path, getSessionBaseDir(sessionId));
+    } else {
+      postAndToast('/api/open-in-editor', { file: hit.dataset.path }, 'in editor');
+    }
+  });
+}
+
+function startLinkedDocInput(container, sessionId) {
+  const slot = container.querySelector('.linked-doc-editor-slot');
+  if (!slot) return;
+  slot.innerHTML = `<input class="linked-doc-input" type="text" spellcheck="false" placeholder="Absolute path, or relative to the session cwd">
+    <div class="linked-doc-hint">${escapeHtml(getSessionBaseDir(sessionId) || 'no session cwd — absolute paths only')}</div>
+    <div class="linked-doc-error"></div>
+    <div class="edit-actions">
+      <button type="button" class="edit-cancel">Cancel</button>
+      <button type="button" class="edit-save">Link</button>
+    </div>`;
+  const input = slot.querySelector('.linked-doc-input');
+  const save = () => linkFileByPath(sessionId, input.value, slot);
+  const cancel = () => {
+    slot.innerHTML = '';
+  };
+  slot.querySelector('.edit-save').addEventListener('click', save);
+  slot.querySelector('.edit-cancel').addEventListener('click', cancel);
+  input.addEventListener('keydown', (e) => {
+    if (e.key === 'Enter') {
       e.preventDefault();
-      openPreviewByPath(paths[+link.dataset.idx], base);
-    });
+      save();
+    } else if (e.key === 'Escape') {
+      e.preventDefault();
+      cancel();
+    }
+  });
+  input.focus();
+}
+
+async function linkFileByPath(sessionId, raw, slot) {
+  // Paths pasted from Explorer or a shell often arrive quoted.
+  const value = (raw || '').trim().replace(/^["']|["']$/g, '');
+  // Reported inline so the input stays open and the path can be corrected in place.
+  const fail = (msg) => {
+    const err = slot?.querySelector('.linked-doc-error');
+    if (err) err.textContent = msg;
+    else showToast(msg, 'error');
+  };
+  if (!value) {
+    fail('Enter a file path');
+    return;
+  }
+  try {
+    const qs = new URLSearchParams({ path: value });
+    const base = getSessionBaseDir(sessionId);
+    if (base) qs.set('base', base);
+    const r = await fetch(`/api/file/resolve?${qs}`);
+    const data = await r.json().catch(() => ({}));
+    if (!r.ok) {
+      fail(data.error || 'File not found');
+      return;
+    }
+    setSessionDocLink(sessionId, data.path, false);
+    showToast('Linked to session', 'success');
+  } catch {
+    fail('Failed to resolve file');
   }
 }
 //#endregion
@@ -5281,6 +5401,10 @@ function setupEventSource() {
         handlePreviewOpenEvent(data);
       }
 
+      if (data.type === 'document:link') {
+        handleDocumentLinkEvent(data);
+      }
+
       if (data.type === 'session:open') {
         handleSessionOpenEvent(data);
       }
@@ -5702,10 +5826,95 @@ function getOwnerColor(name) {
 //#endregion
 
 //#region FILTERS
+// biome-ignore lint/correctness/noUnusedVariables: used in HTML
+function toggleFilterMenu(e) {
+  // Stops the click reaching .section-header (which would collapse the section) *and*
+  // document (which would immediately close the menu we are opening).
+  e?.stopPropagation();
+  if (closeFilterMenu()) return;
+  document.getElementById('filter-menu').classList.add('open');
+  document.getElementById('filter-menu-btn')?.setAttribute('aria-expanded', 'true');
+  renderFilterState();
+  document.addEventListener('click', closeFilterMenu, { once: true });
+  // Capture phase: the global keydown handler bails out on SELECT targets, and every
+  // focusable thing in this popover is a select — Escape would never reach it otherwise.
+  document.addEventListener('keydown', filterMenuKeydown, true);
+  document.getElementById('project-filter')?.focus();
+}
+
+function filterMenuKeydown(e) {
+  if (e.key !== 'Escape') return;
+  e.stopPropagation();
+  if (closeFilterMenu()) document.getElementById('filter-menu-btn')?.focus();
+}
+
+function closeFilterMenu() {
+  const menu = document.getElementById('filter-menu');
+  if (!menu?.classList.contains('open')) return false;
+  menu.classList.remove('open');
+  document.getElementById('filter-menu-btn')?.setAttribute('aria-expanded', 'false');
+  document.removeEventListener('keydown', filterMenuKeydown, true);
+  return true;
+}
+
+// One row per filter control: the select it mirrors, its value, whether it differs from the
+// default, and two label forms — terse tokens for the header strip (which has ~15 characters
+// before the sidebar's width ellipsises it) and long form for its tooltip.
+const FILTERS = [
+  {
+    id: 'project-filter',
+    value: () => filterProject ?? '',
+    active: () => filterProject !== FILTER_DEFAULTS.project,
+    short: () => (filterProject ? filterProject.split(/[/\\]/).pop() : 'all proj'),
+    long: () => (filterProject ? `project ${filterProject}` : 'all projects'),
+  },
+  {
+    id: 'session-filter',
+    value: () => sessionFilter,
+    active: () => sessionFilter !== FILTER_DEFAULTS.session,
+    short: () => 'inactive',
+    long: () => 'including inactive sessions',
+  },
+  {
+    id: 'session-limit',
+    value: () => sessionLimit,
+    active: () => sessionLimit !== FILTER_DEFAULTS.limit,
+    short: () => (sessionLimit === 'all' ? 'n=∞' : `n=${sessionLimit}`),
+    long: () => (sessionLimit === 'all' ? 'no session limit' : `showing ${sessionLimit}`),
+  },
+];
+
+// Keeps the header (summary + funnel tint) and the popover's selects in sync with state.
+// Safe to call on every filter change — it only touches classes, values, and text.
+function renderFilterState() {
+  const short = [];
+  const long = [];
+  for (const f of FILTERS) {
+    const active = f.active();
+    if (active) {
+      short.push(f.short());
+      long.push(f.long());
+    }
+    const el = document.getElementById(f.id);
+    if (!el) continue;
+    const value = String(f.value());
+    if (el.value !== value) el.value = value;
+    el.classList.toggle('non-default', active);
+  }
+
+  const summary = document.getElementById('filter-summary');
+  if (summary) {
+    summary.textContent = short.join(' · ');
+    summary.title = long.length ? `Active filters: ${long.join(', ')}` : '';
+  }
+  document.getElementById('filter-menu-btn')?.classList.toggle('has-filters', short.length > 0);
+}
+
 // biome-ignore lint/correctness/noUnusedVariables: used in HTML
 function filterBySessions(value) {
   sessionFilter = value;
   if (value !== 'active') activityFilter.clear();
+  renderFilterState();
   updateUrl();
   // Instant feedback from cached data, then refetch — the cached list was fetched
   // with the previous filter's server params (e.g. filter=active), so "All Sessions"
@@ -5718,6 +5927,7 @@ function filterBySessions(value) {
 // biome-ignore lint/correctness/noUnusedVariables: used in HTML
 function changeSessionLimit(value) {
   sessionLimit = value;
+  renderFilterState();
   updateUrl();
   fetchSessions();
 }
@@ -5731,6 +5941,31 @@ function matchesProjectFilter(project) {
 //#endregion
 
 //#region EVENT_DELEGATION
+// Selecting text inside a dialog and releasing past its edge puts the mouseup on the
+// backdrop, so the synthesized click targets the overlay and the `onclick="close…()"`
+// on every .modal-overlay would dismiss it. Only a press that *started* on the
+// backdrop counts as a dismissal.
+let _overlayPressTarget = null;
+document.addEventListener(
+  'mousedown',
+  (e) => {
+    // Only an overlay is ever compared below, so don't hold a reference to any other node —
+    // that would keep the last-pressed element (and a detached subtree, after a re-render)
+    // alive until the next mousedown anywhere.
+    _overlayPressTarget = e.target.classList?.contains('modal-overlay') ? e.target : null;
+  },
+  true,
+);
+document.addEventListener(
+  'click',
+  (e) => {
+    if (!e.target.classList?.contains('modal-overlay')) return;
+    if (_overlayPressTarget === e.target) return;
+    e.stopPropagation();
+  },
+  true,
+);
+
 document.addEventListener('click', (e) => {
   const pathToggle = e.target.closest('[data-group-action="toggle-path"]');
   if (pathToggle) {
@@ -5783,9 +6018,10 @@ document.addEventListener('click', (e) => {
   }
 });
 
-// biome-ignore lint/correctness/noUnusedVariables: used in HTML
+// Used in HTML; also called by the hub project shim, so no biome suppression is needed.
 function filterByProject(project) {
   filterProject = project || null;
+  renderFilterState();
   updateUrl();
   fetchSessions(false);
   showAllTasks();
@@ -5831,16 +6067,24 @@ async function updateProjectDropdown() {
 
 function renderProjectDropdown(dropdown, projects) {
   const recentSelected = filterProject === '__recent__' ? ' selected' : '';
+  // A hub-pushed project with no session history isn't in /api/projects, so synthesize its
+  // option here rather than in the hub shim — this also survives the SSE re-render below.
+  const list =
+    filterProject && filterProject !== '__recent__' && !projects.some((p) => p.path === filterProject)
+      ? [...projects, { path: filterProject, modifiedAt: null }]
+      : projects;
   dropdown.innerHTML =
     '<option value="">All Projects</option>' +
     `<option value="__recent__"${recentSelected}>Recent (24h)</option>` +
-    projects
+    list
       .map((p) => {
         const name = p.path.split(/[/\\]/).pop();
         const selected = p.path === filterProject ? ' selected' : '';
         return `<option value="${escapeHtml(p.path)}"${selected} title="${escapeHtml(p.path)}">${escapeHtml(name)}</option>`;
       })
       .join('');
+  // The option list just changed under the select — re-assert tint and header summary.
+  renderFilterState();
 }
 
 function updateThemeColor(isLight) {
@@ -5926,7 +6170,7 @@ function buildThemeMenu() {
   const menu = document.getElementById('themeMenu');
   menu.innerHTML = COLOR_THEMES.map(
     ([id, label]) =>
-      `<button type="button" class="theme-menu-item" data-theme-id="${id}"
+      `<button type="button" class="theme-menu-item theme-swatch-${id}" data-theme-id="${id}"
          onclick="event.stopPropagation(); setColorTheme('${id}'); toggleThemeMenu()">
          <span class="theme-swatch theme-swatch-${id}"><i class="sw-bg"></i><i class="sw-accent"></i><i class="sw-ink"></i></span>${label}
        </button>`,
@@ -6064,14 +6308,6 @@ function loadPanelWidths() {
 
 //#endregion
 
-//#region PREFERENCES
-function loadPreferences() {
-  document.getElementById('session-filter').value = sessionFilter;
-  document.getElementById('session-limit').value = sessionLimit;
-}
-
-//#endregion
-
 //#region SESSION_INFO
 async function showSessionInfoModal(sessionId) {
   const session = sessions.find((s) => s.id === sessionId);
@@ -6316,6 +6552,8 @@ function showInfoModal(session, teamConfig, tasks, planContent, parentInfo) {
 
   const keyHandler = (e) => {
     if (e.key === 'Escape') {
+      // An inline editor inside the modal owns Escape first — it reverts itself.
+      if (['INPUT', 'TEXTAREA', 'SELECT'].includes(e.target.tagName)) return;
       if (document.getElementById('plan-modal').classList.contains('visible')) return;
       if (document.getElementById('tool-stats-modal').classList.contains('visible')) return;
       e.preventDefault();
@@ -7115,13 +7353,16 @@ fetch('/api/version')
   .catch(() => {});
 
 const urlState = getUrlState();
-sessionFilter = urlState.filter || 'active';
-sessionLimit = urlState.limit || '20';
-filterProject = urlState.project || '__recent__';
+const lastView = loadLastView();
+sessionFilter = urlState.filter || FILTER_DEFAULTS.session;
+sessionLimit = urlState.limit || FILTER_DEFAULTS.limit;
+// The URL wins; the persisted view only fills in when it carries a project key, so 'all' (null)
+// restores as 'all' and pre-existing blobs without the key still default to '__recent__'.
+filterProject = urlState.project || (lastView && 'project' in lastView ? lastView.project : FILTER_DEFAULTS.project);
 ownerFilter = urlState.owner || '';
 searchQuery = urlState.search || '';
 
-loadPreferences();
+renderFilterState();
 pinnedSessionIds = loadPinnedSessions();
 stickySessionIds = loadStickySessions();
 setupEventSource();
@@ -7183,12 +7424,12 @@ Promise.all([
 
 window.addEventListener('popstate', () => {
   const s = getUrlState();
-  sessionFilter = s.filter || 'active';
-  sessionLimit = s.limit || '20';
-  filterProject = s.project || '__recent__';
+  sessionFilter = s.filter || FILTER_DEFAULTS.session;
+  sessionLimit = s.limit || FILTER_DEFAULTS.limit;
+  filterProject = s.project || FILTER_DEFAULTS.project;
   ownerFilter = s.owner || '';
   searchQuery = s.search || '';
-  loadPreferences();
+  renderFilterState();
   // fetchSessions derives query params from the globals set above — refetch so
   // back/forward across a filter change doesn't render a stale server-filtered list.
   fetchSessions(false);
@@ -7207,13 +7448,19 @@ window.addEventListener('popstate', () => {
 // #region HUB_INTEGRATION
 document.addEventListener('keydown', (e) => {
   if (!window.__HUB__?.enabled) return;
-  if (e.ctrlKey && e.altKey && (e.key === 'ArrowLeft' || e.key === 'ArrowRight')) {
+  const fwd = (key) => {
     e.preventDefault();
-    window.parent?.postMessage({ type: 'hub:keydown', key: e.key }, '*');
+    window.parent?.postMessage({ type: 'hub:keydown', key, ctrl: e.ctrlKey, alt: e.altKey, shift: e.shiftKey }, '*');
+  };
+  if (e.ctrlKey && e.altKey && (e.key === 'ArrowLeft' || e.key === 'ArrowRight')) {
+    fwd(e.key);
+  }
+  // Its own branch: the Alt+digit case below requires !ctrlKey.
+  if (e.ctrlKey && e.altKey && !e.shiftKey && !e.metaKey && e.key.toLowerCase() === 'p') {
+    fwd(e.key);
   }
   if (e.altKey && !e.ctrlKey && !e.shiftKey && !e.metaKey && /^[1-9]$/.test(e.key)) {
-    e.preventDefault();
-    window.parent?.postMessage({ type: 'hub:keydown', key: e.key }, '*');
+    fwd(e.key);
   }
 });
 
@@ -7241,10 +7488,12 @@ window.hubNavigate = function hubNavigate(app, url) {
   window.parent?.postMessage({ type: 'hub:navigate', app, url }, '*');
 };
 
+// Hoisted out of initHubTheme so initHubProject can share it.
+const hubOrigin = () => (window.__HUB__?.url ? new URL(window.__HUB__.url).origin : null);
+
 (function initHubTheme() {
   const getTheme = () => (document.body.classList.contains('light') ? 'light' : 'dark');
   const getColorTheme = () => document.body.dataset.colorTheme || 'ember';
-  const hubOrigin = () => (window.__HUB__?.url ? new URL(window.__HUB__.url).origin : null);
   // lastTheme/lastColorTheme are updated synchronously when applying a hub
   // message, so the (async) observer sees no diff and doesn't echo it back.
   let lastTheme = getTheme();
@@ -7274,4 +7523,15 @@ window.hubNavigate = function hubNavigate(app, url) {
     attributeFilter: ['class', 'data-color-theme'],
   });
 })();
+
+(function initHubProject() {
+  window.addEventListener('message', (e) => {
+    if (e.source !== window.parent || e.origin !== hubOrigin()) return;
+    if (e.data?.type !== 'hub:project') return;
+    const dirPath = e.data.project;
+    if (typeof dirPath !== 'string' || !dirPath || dirPath === filterProject) return;
+    filterByProject(dirPath);
+    updateProjectDropdown();
+  });
+})();
 // #endregion HUB_INTEGRATION