@oar-sh/oar 0.9.8 → 0.9.10

package/server/public/app/explorer-edit-state.mjs

@@ -0,0 +1,68 @@
+// Path arithmetic for the explorer's edits (new folder, rename, delete), on
+// the path forms the explorer already uses: workspace paths are relative and
+// `/`-joined with `''` for the root; drive paths are absolute (`/x/y` or
+// `C:/x/y`, `C:` for a drive root). Pure, so it runs under node in tests.
+
+/** The name part of a path. */
+export function entryNameOf(pathValue) {
+  const value = String(pathValue || '');
+  const trimmed = value.endsWith('/') && value.length > 1 ? value.slice(0, -1) : value;
+  const index = trimmed.lastIndexOf('/');
+  return index === -1 ? trimmed : trimmed.slice(index + 1);
+}
+
+/** The parent of a path: `''` above a top-level workspace entry or a drive root, `/` above `/x`. */
+export function parentPathOf(pathValue) {
+  const value = String(pathValue || '');
+  const index = value.lastIndexOf('/');
+  if (index === -1) return '';
+  if (index === 0) return '/';
+  return value.slice(0, index);
+}
+
+/** The path of `name` inside `parentPath`. */
+export function childPathOf(parentPath, name) {
+  const parent = String(parentPath || '');
+  const child = String(name || '');
+  if (!parent) return child;
+  return parent.endsWith('/') ? `${parent}${child}` : `${parent}/${child}`;
+}
+
+/** True when `pathValue` is `prefix` or lies below it. */
+export function isSameOrBelow(pathValue, prefix) {
+  const value = String(pathValue || '');
+  const base = String(prefix || '');
+  if (value === base) return true;
+  if (!base) return value !== '';
+  return value.startsWith(base.endsWith('/') ? base : `${base}/`);
+}
+
+/** `pathValue` with `oldPrefix` replaced by `newPrefix` when it lies at or below it; otherwise unchanged. */
+export function rewritePathPrefix(pathValue, oldPrefix, newPrefix) {
+  const value = String(pathValue || '');
+  if (!isSameOrBelow(value, oldPrefix) || oldPrefix === '') return value;
+  return `${newPrefix}${value.slice(String(oldPrefix).length)}`;
+}
+
+/** A new Set with every member rewritten through `rewritePathPrefix`. */
+export function rewritePathSet(paths, oldPrefix, newPrefix) {
+  const out = new Set();
+  for (const value of paths || []) out.add(rewritePathPrefix(value, oldPrefix, newPrefix));
+  return out;
+}
+
+/** A new Set without the members at or below `prefix`. */
+export function dropPathsBelow(paths, prefix) {
+  const out = new Set();
+  for (const value of paths || []) {
+    if (prefix === '' || !isSameOrBelow(value, prefix)) out.add(value);
+  }
+  return out;
+}
+
+/** The descendants of `dirPath` among `paths`, shallowest first, for a re-expansion walk. */
+export function descendantsOf(paths, dirPath) {
+  return [...(paths || [])]
+    .filter((value) => value && value !== dirPath && isSameOrBelow(value, dirPath))
+    .sort((a, b) => a.length - b.length);
+}

package/server/public/app/external-link-policy.mjs

@@ -57,7 +57,10 @@ export function installExternalLinkPolicy({ documentRef = document, onFallback =
   documentRef.addEventListener('click', (event) => {
     const target = event.target instanceof Element ? event.target : event.target?.parentElement;
     const anchor = target?.closest?.('a[href]');
-    if (!anchor || isInAppLink(anchor)) return;
+    // A download link is left to the browser: opened in a new tab instead, it
+    // lost its `download` name, and a phone showed or saved the file under
+    // the plain name, next to (or instead of) an older copy.
+    if (!anchor || anchor.hasAttribute('download') || isInAppLink(anchor)) return;
     secureExternalLink(anchor, documentRef.baseURI, onFallback);
     if (!isExternalNavigationHref(anchor.getAttribute('href'), documentRef.baseURI)) return;
     if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;

package/server/public/app/file-version.mjs

@@ -0,0 +1,58 @@
+// A download link has to change when the file behind it changes. The address
+// and the name a file is saved under both carry the file's version, so nothing
+// between the relay and the Downloads folder can hand back an older copy:
+// not a download manager or a proxy keyed on the URL, and not a phone that
+// keeps `name.pdf`, `name (1).pdf`, `name (2).pdf` side by side and opens the
+// first.
+
+export function appendUrlParam(url, key, value) {
+  const base = String(url || '');
+  const text = String(value ?? '');
+  if (!base || !text) return base;
+  return `${base}${base.includes('?') ? '&' : '?'}${key}=${encodeURIComponent(text)}`;
+}
+
+/** `href` with the file's version token (`v=…`) appended; unchanged when there is none or it has one. */
+export function versionedFileHref(href, version) {
+  const base = String(href || '');
+  if (/[?&]v=/.test(base)) return base;
+  return appendUrlParam(base, 'v', version);
+}
+
+function twoDigits(value) {
+  return String(value).padStart(2, '0');
+}
+
+/**
+ * The name to save a download under: the file's own name with the time it was
+ * last changed, `report.pdf` → `report (1005-0719).pdf` (month, day, hour,
+ * minute, local time). Two versions of a file get two names, and the name
+ * says which one is open. Without a known time the name stays as it is.
+ */
+export function stampedDownloadName(name, mtimeMs) {
+  const plain = String(name || '').trim();
+  const time = Number(mtimeMs);
+  if (!plain || !Number.isFinite(time) || time <= 0) return plain;
+  const date = new Date(time);
+  if (Number.isNaN(date.getTime())) return plain;
+  const stamp = `${twoDigits(date.getMonth() + 1)}${twoDigits(date.getDate())}-${twoDigits(date.getHours())}${twoDigits(date.getMinutes())}`;
+  const dot = plain.lastIndexOf('.');
+  // A leading dot is part of the name (`.env`), not the start of an extension.
+  if (dot <= 0) return `${plain} (${stamp})`;
+  return `${plain.slice(0, dot)} (${stamp})${plain.slice(dot)}`;
+}
+
+/**
+ * The download link of a previewed file: versioned address, and the stamped
+ * name both as the link's `download` name and as `as=…`, which the relay puts
+ * into the `Content-Disposition` header (a browser prefers that header over
+ * the link's own name).
+ */
+export function buildDownloadLink({ href, name, version, mtimeMs } = {}) {
+  const downloadName = stampedDownloadName(name, mtimeMs);
+  let url = versionedFileHref(href, version);
+  if (url && downloadName && downloadName !== String(name || '').trim()) {
+    url = appendUrlParam(url, 'as', downloadName);
+  }
+  return { href: url, downloadName };
+}

package/server/public/app/host-suspend-ui.js

@@ -103,10 +103,13 @@ export function relayShutdownBannerText(state) {
   if (String(state.status || '') === 'shutting_down') {
     return `${icon} Relay ${action === 'restart' ? 'restarting' : 'shutting down'} now…`;
   }
+  // Only the processing turns hold it; queued messages wait for the restart.
   const queue = state.queue || {};
-  const turns = Number(queue.pendingCount || 0) + Number(queue.processingCount || 0) + Number(queue.parkedCount || 0);
-  const waiting = turns > 0 ? `waiting for ${turns} turn${turns === 1 ? '' : 's'} to finish` : 'queue is idle, going down now';
-  return `${icon} Relay ${action} queued — ${waiting}`;
+  const turns = Number(queue.processingCount || 0);
+  const held = Number(queue.pendingCount || 0) + Number(queue.parkedCount || 0);
+  const waiting = turns > 0 ? `waiting for ${turns} running turn${turns === 1 ? '' : 's'} to finish` : 'nothing is running, going down now';
+  const queued = held > 0 ? `; ${held} queued message${held === 1 ? '' : 's'} wait${held === 1 ? 's' : ''} for it` : '';
+  return `${icon} Relay ${action} queued — ${waiting}${queued}`;
 }
 
 function ensureBanner() {

package/server/public/app/journal-view.js

@@ -23,7 +23,11 @@ import {
   loadConversationLoadedMessageCount,
   saveConversationScrollTop,
   IS_SHARED_VIEW,
+  openSummaryModal,
+  closeSummaryModal,
+  setSummaryModalLeaveHandler,
 } from './store.js';
+import { archiveConfirmationFor } from './archive-confirm.mjs';
 import {
   loadConversations as loadConversationsApi,
   loadConversation,
@@ -42,9 +46,13 @@ import {
   loadGrokSettings,
   loadOpenAISettings,
 } from './api-client.js';
-import { renderMessages, restoreInFlightThinking, focusConversationMessageById, flushConversationDraft, hydrateConversationDraft, beginConversationDraftSwitch, openStopTurnConfirmationForConversation, conversationHasActiveTurn } from './conversation-view.js';
+import { isSetupRequired, updateProviderReadinessInputs } from './provider-readiness.mjs';
+import { SETUP_TEXT } from './no-conversation-state.mjs';
+import { openSettingsModal } from './settings-modal.js';
+import { renderMessages, renderNoConversationState, restoreInFlightThinking, focusConversationMessageById, noteTranscriptJump, flushConversationDraft, hydrateConversationDraft, beginConversationDraftSwitch, openStopTurnConfirmationForConversation, conversationHasActiveTurn } from './conversation-view.js';
 import { MENU_SEPARATOR, bindLongPress, closeContextMenu, openContextMenu } from './context-menu.mjs';
 import { setBackgroundTasksConversation, setConversationBackgroundTasks } from './background-tasks-view.mjs';
+import { setConversationPins, setPinsConversation } from './pinned-messages-view.mjs';
 import { setUsageLimitConversation } from './usage-limit-ui.js';
 import { mergeConversationPreviews } from './preview-cards.mjs';
 import { loadRelayQuestions, getPendingQuestionCountsByConversation } from './ask-user-view.js';
@@ -84,6 +92,7 @@ import {
   validateCloudSourceInputs,
 } from './claude-cloud-ui.mjs';
 import { renderConversationOriginMarkerHtml } from './remote-relay-origin-view.mjs';
+import { relayEventWatchedMarkerHtml } from './relay-event-subscriptions-ui.js';
 import {
   normalizeConversationFilter,
   filterConversations,
@@ -336,6 +345,8 @@ export async function refreshConversations(options = {}) {
     preserveProgress: preservePagination,
   });
   renderConvList();
+  // With nothing open the transcript's screen depends on whether chats exist.
+  if (!currentConvId) renderNoConversationState();
   updateCompactButton();
   // A reset bumps the loader version, which aborts any in-flight filter drain;
   // restart it so an active filter keeps covering the unloaded pages.
@@ -344,6 +355,19 @@ export async function refreshConversations(options = {}) {
   }
 }
 
+/** A sidebar row's state: its colour (green is 'ready') and whether its dots run. */
+function conversationRowState(conversation, pendingByConversation = getPendingQuestionCountsByConversation()) {
+  const pendingCount = Number(pendingByConversation[conversation?.id] || 0);
+  const sdkSessionId = String(conversation?.sdkSessionId || '').trim();
+  const workerState = sdkSessionId ? getSessionWorkerState(sdkSessionId) : null;
+  const visualState = resolveConversationUiState({
+    conversation,
+    workerState,
+    hasPendingQuestion: pendingCount > 0,
+  });
+  return { visualState, processing: isConversationProcessing(conversation, workerState) };
+}
+
 export function renderConvList() {
   const list = document.getElementById('conv-list');
   const sorted = Object.values(conversations).sort((a, b) => {
@@ -385,17 +409,9 @@ export function renderConvList() {
     return;
   }
   const conversationView = (conversation) => {
-    const pendingCount = Number(pendingByConversation[conversation?.id] || 0);
-    const sdkSessionId = String(conversation?.sdkSessionId || '').trim();
-    const workerState = sdkSessionId ? getSessionWorkerState(sdkSessionId) : null;
-    const visualState = resolveConversationUiState({
-      conversation,
-      workerState,
-      hasPendingQuestion: pendingCount > 0,
-    });
-    const processing = isConversationProcessing(conversation, workerState);
-    if (processing) hasProcessingConversation = true;
-    return { visualState, processing };
+    const view = conversationRowState(conversation, pendingByConversation);
+    if (view.processing) hasProcessingConversation = true;
+    return view;
   };
   const listHtml = `${visible.map((c) => {
     const view = conversationView(c);
@@ -408,10 +424,12 @@ export function renderConvList() {
     // "↗ win-test": another relay's agent created this conversation.
     // "via agent · “title”": an agent in that conversation on this relay did.
     const originMarkerHtml = renderConversationOriginMarkerHtml(c, { conversations });
+    // "watched": a session another conversation watches by id (relay events).
+    const watchedMarkerHtml = relayEventWatchedMarkerHtml(c.id);
     return `
     <div class="conv-item worker-ui-${view.visualState}${c.id === currentConvId ? ' active' : ''}${c.archived ? ' archived' : ''}" data-conversation-id="${c.id}" onclick="openConversation('${c.id}')">
       <div class="conv-title">${escHtml(c.title)}${processingDots ? `<span class="conv-processing-dots">${escHtml(` ${processingDots}`)}</span>` : ''}${pendingByConversation[c.id] ? ` <span class="conv-open-questions">${pendingByConversation[c.id]} open</span>` : ''}</div>
-      <div class="conv-meta"><span class="conv-meta-primary">${fmtDate(c.updatedAt)} · ${c.messageCount} msg${c.messageCount !== 1 ? 's' : ''}</span>${originMarkerHtml}${providerIndicatorHtml}</div>
+      <div class="conv-meta"><span class="conv-meta-primary">${fmtDate(c.updatedAt)} · ${c.messageCount} msg${c.messageCount !== 1 ? 's' : ''}</span>${originMarkerHtml}${watchedMarkerHtml}${providerIndicatorHtml}</div>
       ${c.archived
         ? `<button class="conv-archive" onclick="unarchiveConv(event,'${c.id}')" title="Unarchive" aria-label="Unarchive">📂</button>`
         : `<button class="conv-archive" onclick="archiveConv(event,'${c.id}')" title="Archive" aria-label="Archive">🗄</button>`}
@@ -428,10 +446,14 @@ export function renderConvList() {
   scheduleConversationListBoundaryCheck();
 }
 
+// keepTranscript: the page shows a window this payload must not replace (the
+// user jumped into the history; the payload is the end of the conversation).
+// Everything but the messages still applies.
 export function applyLoadedConversationState(id, response, {
   restoreScroll = false,
   savedScrollTop = null,
   followLiveUpdates = !restoreScroll,
+  keepTranscript = false,
 } = {}) {
   if (!response) {
     setRepoBrowserSessionInfo('', '');
@@ -478,6 +500,9 @@ export function applyLoadedConversationState(id, response, {
     messageCount: Array.isArray(response.messages)
       ? Math.max(existingConversation.messageCount || 0, response.messages.length)
       : (existingConversation.messageCount || 0),
+    // This payload's verdict only: the record's copy can predate the turn the
+    // socket has since reported running, and would end it on the page.
+    activeTurn: response.activeTurn,
   });
   renderConvList();
   window.applyConversationPreferences?.(id, {
@@ -490,7 +515,13 @@ export function applyLoadedConversationState(id, response, {
   // live poll, and the bare loadRepoBrowserTree path resets loaded folders and
   // deep selections. The end-of-turn message_status handler refreshes the tree
   // through the restoring path instead.
-  const didRenderMessages = renderMessages(response.messages, !restoreScroll, response);
+  // Before the messages: their bubbles take Pin / Unpin from this list.
+  // Absent from an older relay's payload: keep what the socket said.
+  if ('pins' in response) setConversationPins(id, response.pins, response.pinsRevision);
+  setPinsConversation(id);
+  const didRenderMessages = keepTranscript
+    ? false
+    : renderMessages(response.messages, !restoreScroll, response);
   hydrateConversationDraft(id, {
     draftText: response.draftText,
     draftAttachments: response.draftAttachments,
@@ -544,7 +575,10 @@ export async function openConversation(id, options = {}) {
   const previousConversationId = String(currentConvId || '').trim();
   const nextConversationId = String(id || '').trim();
   if (previousConversationId && nextConversationId && previousConversationId !== nextConversationId) {
-    await flushConversationDraft(previousConversationId);
+    // Reads the composer now, before it changes hands below, and saves in the
+    // background: a switch that waited for the save would take over the view
+    // when the save returns, after any click the user made meanwhile.
+    void flushConversationDraft(previousConversationId);
     window.clearImageEditTarget?.();
   }
   const switchingConversation = !!nextConversationId && previousConversationId !== nextConversationId;
@@ -605,6 +639,9 @@ export async function openConversation(id, options = {}) {
     return;
   }
   if (r) {
+    // Counted when the window is put on the page, not when it is asked for:
+    // a reload of the end that is still on its way must see the change.
+    if (forceFreshWindow) noteTranscriptJump();
     applyLoadedConversationState(id, r, { restoreScroll, savedScrollTop });
     if (focusMessageId) {
       requestAnimationFrame(() => {
@@ -1475,6 +1512,31 @@ function populateNewConversationCwdSelect() {
   syncNewConversationCwdControls();
 }
 
+// The New Chat modal with no provider known to be ready: a note above the
+// buttons, Open Settings → Providers as the main button, and the usual Start
+// (same id, same handler) as a secondary "Start a Copilot chat anyway".
+function applyNewConversationSetupState(setupRequired) {
+  const note = document.getElementById('new-conversation-setup-note');
+  const openSettings = document.getElementById('new-conversation-open-settings');
+  const confirm = document.getElementById('new-conversation-model-confirm');
+  if (note) {
+    note.hidden = !setupRequired;
+    note.textContent = setupRequired ? SETUP_TEXT : '';
+  }
+  if (openSettings) {
+    openSettings.hidden = !setupRequired;
+    if (openSettings.dataset.bound !== '1') {
+      openSettings.dataset.bound = '1';
+      openSettings.addEventListener('click', (event) => {
+        event.preventDefault();
+        closeNewConversationModelModal();
+        openSettingsModal('providers');
+      });
+    }
+  }
+  if (confirm) confirm.textContent = setupRequired ? 'Start a Copilot chat anyway' : 'Start chat';
+}
+
 async function openNewConversationModelModal() {
   const [catalog, settings, claudeSettings, cursorSettings, grokSettings, claudeCloudSettings] = await Promise.all([
     loadModelCatalog(),
@@ -1491,6 +1553,18 @@ async function openNewConversationModelModal() {
   newConversationCursorSettingsCache = cursorSettings || null;
   newConversationGrokSettingsCache = grokSettings || null;
   newConversationClaudeCloudSettingsCache = claudeCloudSettings || null;
+  // Fresh answers for the readiness question, shared with the empty screen
+  // and the composer. With no provider known to be ready the modal opens in
+  // its setup state: Settings is the main button, Start stays as "anyway".
+  const readiness = updateProviderReadinessInputs({
+    openai: settings || null,
+    claude: claudeSettings || null,
+    claudeCloud: claudeCloudSettings || null,
+    cursor: cursorSettings || null,
+    grok: grokSettings || null,
+    catalog: catalog || null,
+  });
+  applyNewConversationSetupState(isSetupRequired(readiness));
   // Every open starts from empty cloud fields; the folder lookup refills them.
   resetNewConversationCloudState();
   bindNewConversationCloudInputs();
@@ -1903,9 +1977,61 @@ async function setConversationArchived(id, archived) {
   return true;
 }
 
+const ARCHIVE_CONFIRM_KIND = 'archive-confirm';
+
+/** Resolves true when the user confirms; Cancel, Escape, the backdrop or × keep the chat. */
+function askBeforeArchive(id, confirmation) {
+  const title = String(conversations[id]?.title || '').trim();
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    openSummaryModal({
+      title: 'Archive session',
+      subtitle: title,
+      kind: ARCHIVE_CONFIRM_KIND,
+      bodyHtml: `
+        <p>${escHtml(confirmation.message)}</p>
+        <p>${escHtml(confirmation.detail)}</p>
+        <div class="summary-modal-actions">
+          <button class="chat-title-action-btn" type="button" data-archive-confirm="1">🗄 Archive</button>
+          <button class="chat-title-action-btn" type="button" data-archive-cancel="1">Cancel</button>
+        </div>
+      `,
+    });
+    // Runs on every way out of the modal, another modal replacing it included.
+    setSummaryModalLeaveHandler(ARCHIVE_CONFIRM_KIND, () => settle(false));
+    const body = document.getElementById('summary-modal-body');
+    body?.querySelector('[data-archive-confirm]')?.addEventListener('click', (event) => {
+      event.preventDefault();
+      settle(true);
+      closeSummaryModal();
+    }, { once: true });
+    const cancel = body?.querySelector('[data-archive-cancel]');
+    cancel?.addEventListener('click', (event) => {
+      event.preventDefault();
+      closeSummaryModal();
+    }, { once: true });
+    cancel?.focus?.();
+  });
+}
+
 export async function archiveConv(e, id) {
   e?.stopPropagation?.();
   closeContextMenu();
+  // A chat whose process is live (green, idle or not) asks first: archiving
+  // stops that process. The relay still refuses a chat with a running turn.
+  const conversation = conversations[id];
+  const view = conversation ? conversationRowState(conversation) : null;
+  const confirmation = archiveConfirmationFor({
+    archived: conversation?.archived === true,
+    visualState: view?.visualState,
+    running: conversationHasActiveTurn(id) || conversation?.activeTurn === true || view?.processing === true,
+  });
+  if (confirmation && !(await askBeforeArchive(id, confirmation))) return;
   await setConversationArchived(id, true);
 }
 
@@ -1971,16 +2097,24 @@ export async function deleteConv(e, id) {
   }
   delete conversations[id];
   renderConvList();
-  if (currentConvId === id) {
-    setCurrentConv(null);
-    clearAttachments();
-    setRepoBrowserSessionInfo('', '');
-    restoreInFlightThinking(null);
-    renderMessages([]);
-    document.getElementById('chat-title').textContent = 'Select or start a conversation';
-    window.syncChatTitleControls?.();
-    updateSessionPill(null, null);
-    updateCompactButton();
-    scheduleContextUsageRefresh(null);
-  }
+  if (currentConvId === id) clearOpenConversation();
+}
+
+/**
+ * The conversation on screen is gone (deleted here or from another device):
+ * nothing is open, the header says so, the transcript shows the empty state
+ * and the ⋯ menu keeps its relay-wide entries. One place for both callers.
+ */
+export function clearOpenConversation() {
+  setCurrentConv(null);
+  clearAttachments();
+  setRepoBrowserSessionInfo('', '');
+  restoreInFlightThinking(null);
+  renderMessages([]);
+  const title = document.getElementById('chat-title');
+  if (title) title.textContent = 'Select or start a conversation';
+  window.syncChatTitleControls?.();
+  updateSessionPill(null, null);
+  updateCompactButton();
+  scheduleContextUsageRefresh(null);
 }

package/server/public/app/no-conversation-state.mjs

@@ -0,0 +1,58 @@
+// What the transcript shows while no conversation is open. No DOM here;
+// conversation-view.js draws the result into the `.empty-state` node.
+//
+// Three variants: `setup` when the relay has no provider known to be ready
+// (the fresh-install case: point to Settings → Providers, do not pretend
+// Copilot is set up), `first-chat` when a provider is ready and there are no
+// conversations yet, and `pick` when conversations exist but none is open.
+// A readiness answer that is unknown counts as ready, as everywhere else.
+
+import { isSetupRequired } from './provider-readiness.mjs';
+
+export const SETUP_HEADING = 'Set up a provider';
+export const SETUP_TEXT = 'Turn on Claude, Cursor, OpenAI or Grok in Settings → Providers, or sign in to the Copilot CLI on the relay host.';
+
+const ACTIONS = Object.freeze({
+  openSettings: (primary) => ({ id: 'empty-state-open-settings', action: 'open-settings', label: primary ? 'Open Settings' : 'Settings', primary, link: !primary }),
+  newChat: (primary) => ({ id: 'empty-state-new-chat', action: 'new-chat', label: '+ New chat', primary, link: false }),
+  showConversations: () => ({ id: 'empty-state-show-conversations', action: 'show-conversations', label: 'Show conversations', primary: false, link: false }),
+});
+
+/**
+ * @param {object} input
+ * @param {object|null} [input.readiness] resolveProviderReadiness()'s answer
+ * @param {number} [input.conversationCount] live conversations the client knows
+ * @param {boolean} [input.mobile] the sidebar is an off-canvas drawer
+ * @returns {{ variant: 'setup' | 'first-chat' | 'pick', icon: string, heading: string, text: string, actions: Array<{ id: string, action: string, label: string, primary: boolean, link: boolean }> }}
+ */
+export function resolveNoConversationState({ readiness = null, conversationCount = 0, mobile = false } = {}) {
+  if (isSetupRequired(readiness)) {
+    return {
+      variant: 'setup',
+      icon: '⚙️',
+      heading: SETUP_HEADING,
+      text: SETUP_TEXT,
+      actions: [ACTIONS.openSettings(true), ACTIONS.newChat(false)],
+    };
+  }
+  const count = Math.max(0, Number(conversationCount) || 0);
+  if (count === 0) {
+    return {
+      variant: 'first-chat',
+      icon: '🚀',
+      heading: 'Start your first chat',
+      text: 'Pick a model and a folder, and go.',
+      actions: [ACTIONS.newChat(true), ACTIONS.openSettings(false)],
+    };
+  }
+  const actions = [ACTIONS.newChat(true)];
+  if (mobile) actions.push(ACTIONS.showConversations());
+  actions.push(ACTIONS.openSettings(false));
+  return {
+    variant: 'pick',
+    icon: '💬',
+    heading: 'No conversation open',
+    text: 'Pick one from the list or start a new one.',
+    actions,
+  };
+}