synabun 2.0.0 → 2.0.5

package/neural-interface/public/shared/ocp-v2/ocp-v2-panel.js

@@ -43,13 +43,17 @@ import { mountChangesBar } from './ocp-v2-changes.js';
 import { mountEnvironmentPopover } from './ocp-v2-status.js';
 import { watchWorktree, newSessionPlan, checkoutOutcome } from './ocp-v2-changes-logic.js';
 import { mountRenderer } from './ocp-v2-render.js';
+import { offerGreeting } from './ocp-v2-greeting.js';
 import { mountCompose, focusCompose, appendPathToCompose } from './ocp-v2-send.js';
 import { mountProjectBar, unmountProjectBar } from './ocp-v2-projectbar.js';
 import { registerSidepanel, syncSidepanelLayout, focusSidepanel, openAnotherSidepanelSession, isHostedSessionFocused } from '../ui-sidepanel-windows.js';
 import { nativeLoopWindowId } from '../ui-native-window-id.js';
 import { requestGeneratedSessionTitle } from '../session-title.js';
+import { wireFileLinks } from '../ui-file-links.js';
+import { backToAssistant, buildWorkerEndCard, endWorkerRunOnClose, forgetWorkerEnd, trackWorkerEnd } from '../ui-worker-end.js';
+import { isDispatchedRun } from '../worker-end.js';
 import {
-  registerAutomationSession, unregisterAutomationSession, stopAutomationRun,
+  registerAutomationSession, unregisterAutomationSession, stopAutomationRun, isAutomationSession,
 } from './ocp-v2-automation-ownership.js';
 import {
   registerPrimaryPanel, bindPrimarySession, isChildPanelOpen, getVisibleChildPanel, openChildSession,
@@ -92,6 +96,8 @@ const _automationRunning = new Set();
 const _automationContinuedManually = new Set();
 const _automationManualSendInFlight = new Set();
 const _foreignActiveAutomationSessions = new Set();
+const _workerEnds = new Map(); // sessionId -> end card of the dispatched worker it belongs to (ui-worker-end.js)
+let _renderer = null;
 let _visible = false;
 let _booted = false;
 let _bootPromise = null;
@@ -420,6 +426,9 @@ function buildPanel() {
   messages.className = 'ocpv2-messages';
   messagesContainer.appendChild(messages);
   panel.appendChild(messagesContainer);
+  // A link to a file the code editor can open opens it there (shared with the other panels). A relative
+  // path is a path in the session's directory.
+  wireFileLinks(messagesContainer, { cwd: () => getState().cwd || '' });
 
   // ── What the session changed on disk (session.diff) ─────────────────────
   mountChangesBar(panel, getDefaultStore());
@@ -445,7 +454,17 @@ function buildPanel() {
   });
 
   let composer = null;
-  const renderer = mountRenderer(messages, getDefaultStore(), {
+  const renderer = _renderer = mountRenderer(messages, getDefaultStore(), {
+    // A dispatched worker's end: the last card of its session's transcript.
+    endCard: (s) => workerEndCard(s?.sessionId),
+    // SynaBun's greeting for a person who comes back to a new session: never for an automation run's.
+    onEmpty: (host, s) => offerGreeting(host, {
+      sessionId: s?.sessionId || null,
+      cwd: s?.cwd || '',
+      automation: !!s?.sessionId && (_automationRunIds.has(s.sessionId) || isAutomationSession(s.sessionId)),
+      onOpenMemory: (id) => { if (id) emit('memory:open', { id }); },
+      isCurrent: () => (getState().sessionId || null) === (s?.sessionId || null) && getState().messageOrder.length === 0,
+    }),
     onOpenSession: (session, extra) => openCreatedSession(session, extra),
     // Fork is a navigation: its intent begins at the click, and the fork takes
     // the panel only while that click is still the user's latest choice.
@@ -504,7 +523,18 @@ function buildPanel() {
       const sessionId = session?.sessionId;
       if (phase === 'started') requestOpenCodeSessionTitle(session, meta);
       if (!sessionId || !_automationRunIds.has(sessionId) || _automationRunning.has(sessionId)) return;
-      if (phase === 'started') _automationManualSendInFlight.add(sessionId);
+      if (phase === 'started') {
+        const first = !_automationContinuedManually.has(sessionId) && !_automationManualSendInFlight.has(sessionId);
+        _automationManualSendInFlight.add(sessionId);
+        if (first) {
+          // The tab is the user's from here on (Codex's releaseAutomationForManualUse): the run's
+          // end card goes, and the router leaves the run alone, so nothing of it comes back here.
+          const runId = _automationRunIds.get(sessionId);
+          forgetWorkerEnd(runId);
+          showWorkerEnd(sessionId, null);
+          window.dispatchEvent(new CustomEvent('native-loop:dismissed', { detail: { runId } }));
+        }
+      }
       if (phase === 'failed') _automationManualSendInFlight.delete(sessionId);
       if (phase === 'succeeded') {
         _automationManualSendInFlight.delete(sessionId);
@@ -2238,11 +2268,12 @@ function dismissAutomationSession(sessionId) {
   if (!runId) return false;
   window.dispatchEvent(new CustomEvent('native-loop:dismissed', { detail: { runId } }));
   if (_automationRunning.has(sessionId)) {
-    fetch('/api/loop/stop', {
+    // A worker that finished its task is completed; any other run is stopped.
+    endWorkerRunOnClose(runId, () => fetch('/api/loop/stop', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ runId }),
-    }).catch(() => {});
+    }).catch(() => {}));
   }
   return true;
 }
@@ -2317,6 +2348,8 @@ function removeTab(sessionId, { byUser = false } = {}) {
   const titleTimer = _titleReassertTimers.get(sessionId);
   if (titleTimer) clearTimeout(titleTimer);
   _titleReassertTimers.delete(sessionId);
+  forgetWorkerEnd(_automationRunIds.get(sessionId));
+  _workerEnds.delete(sessionId);
   _automationRunIds.delete(sessionId);
   unregisterAutomationSession(sessionId);
   _automationRunning.delete(sessionId);
@@ -2354,22 +2387,56 @@ function createTabPill(sessionId) {
     if (event.target.closest('.term-minimized-pill-close')) return;
     handlePillClick(sessionId);
   });
-  pill.querySelector('.term-minimized-pill-close')?.addEventListener('click', async (event) => {
+  pill.querySelector('.term-minimized-pill-close')?.addEventListener('click', (event) => {
     event.stopPropagation();
-    // Mirror header X. Native transcripts are preserved unless the user has
-    // continued the terminal automation manually; backend cleanup is best-effort.
-    // Asked first when prompts are still waiting in that session; declined:
-    // the tab stays and nothing is deleted.
-    if (!(await mayCloseTab(sessionId))) return;
-    const wasRunning = sessionId === getState().sessionId && !!getState().running;
-    closeSessionBackend(sessionId, { wasRunning, context: 'pill close' }).catch(() => {});
-    try { await handlePillClose(sessionId, { byUser: true }); }
-    catch (err) { console.warn('[ocp-v2-panel] local pill close failed', err); }
+    closeTabByUser(sessionId, 'pill close');
   });
   tray.appendChild(pill);
   return pill;
 }
 
+// Mirror header X. Native transcripts are preserved unless the user has
+// continued the terminal automation manually; backend cleanup is best-effort.
+// Asked first when prompts are still waiting in that session; declined: the
+// tab stays, nothing is deleted, and this resolves false.
+async function closeTabByUser(sessionId, context) {
+  if (!(await mayCloseTab(sessionId))) return false;
+  const wasRunning = sessionId === getState().sessionId && !!getState().running;
+  closeSessionBackend(sessionId, { wasRunning, context }).catch(() => {});
+  try { await handlePillClose(sessionId, { byUser: true }); }
+  catch (err) { console.warn(`[ocp-v2-panel] local ${context} failed`, err); }
+  return true;
+}
+
+// The end of a worker the Assistant dispatched: its button closes the tab the
+// way the tab's X does (a warm worker that finished its task is completed, one
+// still at work is stopped; its record stays for the Assistant) and shows the
+// Assistant session that dispatched it.
+function workerEndCard(sessionId) {
+  const view = sessionId ? _workerEnds.get(sessionId) : null;
+  if (!view) return null;
+  return {
+    sig: view.sig,
+    build: () => buildWorkerEndCard(view, {
+      classes: {
+        card: 'ocpv2-post-plan-card ocpv2-worker-end', title: 'ocpv2-post-plan-header', detail: 'ocpv2-post-plan-body',
+        meta: 'ocpv2-post-plan-saved', note: 'ocpv2-post-plan-note', actions: 'ocpv2-post-plan-actions', button: 'ocpv2-post-plan-btn primary',
+      },
+      onBack: async () => {
+        if (!(await closeTabByUser(sessionId, 'worker end close'))) return false;
+        backToAssistant(view.assistantSessionId);
+        return true;
+      },
+    }),
+  };
+}
+
+function showWorkerEnd(sessionId, view) {
+  if (view) _workerEnds.set(sessionId, view);
+  else if (!_workerEnds.delete(sessionId)) return;
+  _renderer?.render();
+}
+
 function escapeHtml(s) {
   return String(s || '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 }
@@ -2539,9 +2606,12 @@ export async function attachOpenCodeAutomation(run, { focus = !!run?.focus, isCa
   // Establish ownership before connect()/boot(): native provider events use a
   // separate socket and may report a Task child while this attach is awaiting.
   const previousRunId = _automationRunIds.get(sessionId);
+  const running = run.status === 'starting' || run.status === 'running';
+  // The user continued this run's session by hand after the run ended: the tab stays theirs.
+  const released = !running && previousRunId === run.runId
+    && (_automationContinuedManually.has(sessionId) || _automationManualSendInFlight.has(sessionId));
   _automationRunIds.set(sessionId, run.runId);
   registerAutomationSession(sessionId, run.runId);
-  const running = run.status === 'starting' || run.status === 'running';
   if (running || previousRunId !== run.runId) {
     _automationContinuedManually.delete(sessionId);
     _automationManualSendInFlight.delete(sessionId);
@@ -2565,6 +2635,16 @@ export async function attachOpenCodeAutomation(run, { focus = !!run?.focus, isCa
     await handlePillClose(sessionId).catch(() => {});
     return { ok: false, reason: 'dismissed' };
   }
+  if (released) {
+    // The dock's Focus raises it; the run is let go again, and nothing in the tab changes.
+    window.dispatchEvent(new CustomEvent('native-loop:dismissed', { detail: { runId: run.runId } }));
+    if (focus && _nav.latest() === attachBegan && _tabSessionIds.includes(sessionId)) {
+      const nav = _nav.observe();
+      if (!_visible) await showPrimaryOpencodePanel();
+      await switchToSession(sessionId, _tabInfoCache.get(sessionId) || null, { nav });
+    }
+    return { ok: true, sessionId, released: true };
+  }
   ensureTab(sessionId, info);
   if (focus && _nav.latest() === attachBegan) {
     // (Its own navigation, observed after boot landed: a click made while the
@@ -2577,13 +2657,15 @@ export async function attachOpenCodeAutomation(run, { focus = !!run?.focus, isCa
     await rehydrateActiveSession().catch(() => {});
   }
   if (getState().sessionId === sessionId) setRunning(running);
-  if (run.status === 'failed' && run.error && getState().sessionId === sessionId
+  // (A dispatched worker's failure, with its reason, is on its end card.)
+  if (run.status === 'failed' && run.error && !isDispatchedRun(run) && getState().sessionId === sessionId
     && _tabInfoCache.get(sessionId)?._automationLifecycleError !== run.error) {
     const cachedInfo = _tabInfoCache.get(sessionId) || info;
     cachedInfo._automationLifecycleError = run.error;
     _tabInfoCache.set(sessionId, _stoppedShares.clean(cachedInfo));
     pushError({ message: run.error });
   }
+  trackWorkerEnd(run, { apply: (view) => showWorkerEnd(sessionId, view) });
   renderPill();
   return { ok: true, sessionId };
 }

package/neural-interface/public/shared/ocp-v2/ocp-v2-render.js

@@ -212,9 +212,13 @@ function render(_container, store, opts = {}) {
   );
   const questions = requestsVisibleIn(s.pendingQuestions, s.sessionId, isKnownDescendantSession);
   const retry = retryBannerView(s.sessionStatus);
-  const hasInteractiveCards = permissions.length > 0 || questions.length > 0 || !!s.showPostPlanActions;
+  // The panel's last card for the session on screen (a dispatched worker's end): { sig, build } or null.
+  const endCard = typeof opts.endCard === 'function' ? opts.endCard(s) : null;
+  const hasInteractiveCards = permissions.length > 0 || questions.length > 0 || !!s.showPostPlanActions || !!endCard;
   if (s.messageOrder.length === 0 && !hasInteractiveCards && !s.errors.length && !retry && !revertBanner) {
     _reconcile(_container, [{ key: '__empty__', sig: 'empty', build: _buildEmpty }]);
+    // The panel may put SynaBun's greeting in it (ocp-v2-greeting.js).
+    try { opts.onEmpty?.(_container.querySelector(':scope > .ocpv2-empty'), s); } catch { /* the empty state stands on its own */ }
     return;
   }
 
@@ -346,6 +350,8 @@ function render(_container, store, opts = {}) {
     });
   }
 
+  if (endCard) desired.push({ key: 'end', sig: `end:${endCard.sig}`, build: endCard.build });
+
   _reconcile(_container, desired);
 }
 

package/neural-interface/public/shared/ocp-v2/ocp-v2-send.js

@@ -33,6 +33,7 @@ import {
 } from './ocp-v2-send-logic.js';
 import { hydrateTranscript } from './ocp-v2-rehydrate.js';
 import { captureBinding, trackBinding, isBindingToken, searchOnBinding } from './ocp-v2-binding.js';
+import { takeGreetingId } from './ocp-v2-greeting.js';
 
 const STOR_MODE = 'opencode-v2-mode';   // the last agent picked (build / plan / a custom one)
 const STOR_HISTORY = 'ocp-v2-prompt-history';
@@ -1449,6 +1450,10 @@ export function mountCompose(rootEl, store = getDefaultStore(), opts = {}) {
         variant: turn.variant || undefined,
         cwd: options.cwd || turn.cwd || undefined,
         mcpProfile: turn.mcpProfile || undefined,
+        // A person's own message (the greeting engine keeps when they were last here), and the
+        // greeting this session opened with, told to the model once.
+        human: true,
+        greetingId: takeGreetingId(turnSessionId) || undefined,
       });
       if (res?.error) return failSend(shouldSuppressAbortError(res.error) ? '' : res.error);
       // Delivered: that stands, whatever the panel shows by now.

package/neural-interface/public/shared/ocp-v2/ocp-v2-styles.js

@@ -1097,6 +1097,46 @@ const CSS = `
   cursor: default;
 }
 
+/* A dispatched worker's end (ui-worker-end.js): the post-plan card's frame. Complete keeps its
+   green; the other ends take the panel's own amber, error red or neutral. The title says the state. */
+.ocpv2-worker-end .ocpv2-post-plan-body { overflow-wrap: anywhere; }
+.ocpv2-worker-end .ocpv2-post-plan-btn:focus-visible { outline: 2px solid rgba(255,255,255,0.7); outline-offset: 2px; }
+.ocpv2-worker-end[data-tone="warn"] {
+  border-color: rgba(232,180,80,0.32);
+  background: rgba(232,180,80,0.04);
+  box-shadow: 0 12px 32px rgba(0,0,0,0.22), 0 0 0 1px rgba(232,180,80,0.08) inset;
+}
+.ocpv2-worker-end[data-tone="warn"] .ocpv2-post-plan-header {
+  color: rgba(255,200,120,0.95);
+  background: rgba(232,180,80,0.14);
+  border-color: rgba(232,180,80,0.28);
+}
+.ocpv2-worker-end[data-tone="err"] {
+  border-color: rgba(220,100,100,0.32);
+  background: rgba(220,100,100,0.05);
+  box-shadow: 0 12px 32px rgba(0,0,0,0.22), 0 0 0 1px rgba(220,100,100,0.08) inset;
+}
+.ocpv2-worker-end[data-tone="err"] .ocpv2-post-plan-header {
+  color: rgba(255,166,166,0.92);
+  background: rgba(220,100,100,0.12);
+  border-color: rgba(220,100,100,0.28);
+}
+.ocpv2-worker-end[data-tone="off"] {
+  border-color: rgba(255,255,255,0.12);
+  background: rgba(255,255,255,0.03);
+  box-shadow: 0 12px 32px rgba(0,0,0,0.22);
+}
+.ocpv2-worker-end[data-tone="off"] .ocpv2-post-plan-header {
+  color: rgba(255,255,255,0.7);
+  background: rgba(255,255,255,0.06);
+  border-color: rgba(255,255,255,0.12);
+}
+.ocpv2-worker-end:not([data-tone="ok"]) .ocpv2-post-plan-saved { color: rgba(255,255,255,0.45); }
+.ocpv2-worker-end:not([data-tone="ok"]) .ocpv2-post-plan-btn.primary {
+  background: rgba(255,255,255,0.085);
+  border-color: rgba(255,255,255,0.2);
+}
+
 /* Stub shown in place of raw question-tool JSON while the AskUser card handles it */
 .ocpv2-part-question-stub {
   font-size: 10.5px;

package/neural-interface/public/shared/ocp-v2/ocp-v2-ws.js

@@ -486,8 +486,9 @@ export const api = {
   sessionDelete:  (sessionId)     => request({ type: 'session:delete', sessionId }),
   sessionMessages:(sessionId)     => request({ type: 'session:messages', sessionId }),
   sessionContext: ({ sessionId, cwd } = {}) => request({ type: 'session:context', sessionId, cwd }),
-  send: ({ sessionId, parts, model, agent, mode, variant, cwd, mcpProfile, noAbortPrev }) =>
-    request({ type: 'message:send', sessionId, parts, model, agent, mode, variant, cwd, mcpProfile, noAbortPrev: !!noAbortPrev }, 30 * 60 * 1000),
+  // `human` / `greetingId`: lib/greeting/ (a server that does not know them ignores them).
+  send: ({ sessionId, parts, model, agent, mode, variant, cwd, mcpProfile, noAbortPrev, human, greetingId }) =>
+    request({ type: 'message:send', sessionId, parts, model, agent, mode, variant, cwd, mcpProfile, noAbortPrev: !!noAbortPrev, ...(human ? { human: true } : {}), ...(greetingId ? { greetingId } : {}) }, 30 * 60 * 1000),
   abort: (sessionId) => request({ type: 'message:abort', sessionId }),
   compact: ({ sessionId, cwd, mcpProfile, model } = {}) => request({ type: 'session:compact', sessionId, cwd, mcpProfile, model }, 5 * 60 * 1000),
   permissionReply: ({ sessionId, permissionId, response, cwd, message }) =>

package/neural-interface/public/shared/pwa-install-page.js

@@ -1,4 +1,16 @@
-import { initPwaInstall, isStandalone, requestPwaInstall } from './pwa-install.js';
+import { canPromptPwaInstall, initPwaInstall, installGuideMode, installGuideRequested, isStandalone,
+  leavePwaInstallHandoff, requestPwaInstall } from './pwa-install.js';
+
+// The wizard (first run) and the main UI (setup done) open the browser's dialog from a press the user makes
+// anyway, so a browser that has one shows this page only when Apps > Install as App asked for it. true, false,
+// or null for a read that did not answer: only an answer sends the user on, null keeps the guide.
+async function setupComplete() {
+  try {
+    const res = await fetch('/api/setup/onboarding', { signal: AbortSignal.timeout(3000) });
+    const { setupComplete: done } = res.ok ? await res.json() : {};
+    return typeof done === 'boolean' ? done : null;
+  } catch { return null; }
+}
 
 if (isStandalone()) location.replace('/');
 else {
@@ -8,6 +20,7 @@ else {
     'install-intro': 'O servidor está rodando em segundo plano. Confirme a instalação uma vez no navegador para abrir o SynaBun em sua própria janela.',
     'install-chromium': 'Chrome ou Edge: escolha Instalar como app abaixo ou a opção Instalar app no menu do navegador.',
     'install-safari': 'Safari no macOS: escolha Arquivo → Adicionar ao Dock. Mantenha o nome SynaBun.',
+    'install-other': 'O SynaBun é instalado como app pelo Chrome, pelo Edge ou pelo Safari no macOS. Abra-o em um deles para instalar.',
     'install-later': 'Após instalar, abra novamente o iniciador nativo do SynaBun. Ele inicia ou reutiliza o servidor e abre o PWA instalado. Fechar a janela mantém o servidor ativo. Use Apps → Stop Server para pará-lo.',
     'install-button': 'Instalar como app', 'install-continue': 'Continuar para o SynaBun',
   } : {};
@@ -17,6 +30,7 @@ else {
   const instructions = pt
     ? 'Use a opção Instalar app do Chrome/Edge ou Arquivo → Adicionar ao Dock no Safari. A instalação exige sua confirmação no navegador.'
     : 'Use Chrome/Edge’s Install app menu or Safari’s File → Add to Dock. Installation requires your browser confirmation.';
+  // Before the read below: the event can arrive while it is on its way.
   initPwaInstall({ changed: value => {
     status.textContent = value === 'installed'
       ? (pt ? 'Instalado. Abra novamente o iniciador do SynaBun para usar o PWA.' : 'Installed. Reopen the SynaBun launcher to use the PWA.')
@@ -31,4 +45,18 @@ else {
     } catch { status.textContent = instructions; }
   });
   if ('serviceWorker' in navigator) navigator.serviceWorker.register('/sw.js').catch(() => {});
+
+  // One plain action or one plain instruction, never both: the button only where the browser has a dialog to open.
+  const canPrompt = canPromptPwaInstall();
+  const show = done => {
+    let mode = installGuideMode({ canPrompt, setupComplete: done, requested: installGuideRequested(location.search), vendor: navigator.vendor });
+    // The main UI opens the dialog only for the mark this leaves: where it cannot be left, the button stays.
+    if (mode === 'handoff' && !leavePwaInstallHandoff()) mode = 'button';
+    if (mode === 'wizard' || mode === 'handoff') return location.replace('/');
+    document.getElementById(mode === 'button' ? 'install-chromium' : `install-${mode}`).hidden = false;
+    document.getElementById('install-button').hidden = mode !== 'button';
+    document.querySelector('main').hidden = false;
+  };
+  if (canPrompt) setupComplete().then(show);
+  else show(null);
 }

package/neural-interface/public/shared/pwa-install.css

@@ -2,9 +2,9 @@
 #pwa-install { display: grid; place-items: center; overflow: auto; padding: 24px; color: var(--t-bright); }
 #pwa-install main { width: min(560px, 100%); padding: 24px; background: var(--s-panel); border: 1px solid var(--b-light); border-radius: var(--r-card); }
 #pwa-install h1 { font-family: var(--ff-heading); font-size: calc(28px * var(--font-scale)); font-weight: 600; line-height: 1.2; margin: 16px 0; }
-#pwa-install p, #pwa-install li { font-size: var(--fs-sm); line-height: 1.5; }
-#pwa-install ol { padding-left: 24px; margin: 16px 0; }
-#pwa-install li + li { margin-top: 8px; }
+#pwa-install [hidden] { display: none !important; }
+#pwa-install p { font-size: var(--fs-sm); line-height: 1.5; }
+#pwa-install p + p { margin-top: 16px; }
 #pwa-install .actions { display: flex; flex-wrap: wrap; align-items: center; gap: 16px; margin-top: 24px; }
 #pwa-install button { background: var(--s-active); border: 1px solid var(--b-visible); border-radius: var(--r-small); color: var(--t-bright); font: inherit; padding: 8px 12px; cursor: pointer; }
 #pwa-install button:hover { background: var(--s-hover); }

package/neural-interface/public/shared/pwa-install.js

@@ -1,9 +1,14 @@
-/** Shared by the existing Install as App menu and the native launcher's first-run page. */
+/** Shared by the Install as App menu, the first-run wizard, the native launcher's guide page and the main UI it hands over to. */
 export function isStandalone(win = window, nav = navigator) {
   return win.matchMedia('(display-mode: standalone)').matches
     || win.matchMedia('(display-mode: window-controls-overlay)').matches || !!nav.standalone;
 }
 
+/** Chromium only: Safari and Firefox have no install event, so there is nothing a page can open there. */
+export function canPromptPwaInstall(win = window) {
+  return 'onbeforeinstallprompt' in win;
+}
+
 export function initPwaInstall({ win = window, nav = navigator, changed = () => {} } = {}) {
   win.addEventListener('beforeinstallprompt', event => {
     event.preventDefault();
@@ -26,3 +31,97 @@ export async function requestPwaInstall(win = window) {
   win._pwaInstallPrompt = null; // Browser install events are single-use, including dismissal.
   return outcome;
 }
+
+const OFFERED_KEY = 'synabun-pwa-install-offered';
+
+function wasOffered(win) {
+  if (win._pwaInstallOffered) return true;
+  try { return win.sessionStorage.getItem(OFFERED_KEY) === '1'; } catch { return false; }
+}
+
+/**
+ * The first-run wizard asks nothing itself: it opens the browser's own install dialog once, from a click the
+ * user makes anyway. Call this synchronously in that click, before any await: prompt() needs the click's user
+ * activation and uses it up, so never call it from a click that opens a popup, the clipboard or a file picker.
+ * Nobody waits for the answer. Without an event it does nothing and the next click tries again; once the dialog
+ * has opened, this tab never opens it again (sessionStorage: a reload of the wizard does not ask twice).
+ */
+export function offerPwaInstallOnce({ win = window, nav = navigator } = {}) {
+  const prompt = win._pwaInstallPrompt;
+  if (!prompt || isStandalone(win, nav) || wasOffered(win)) return false;
+  if (nav.userActivation && !nav.userActivation.isActive) return false; // A scripted click: keep the event for a real one.
+  win._pwaInstallPrompt = null; // Single-use, whatever the user answers.
+  try { Promise.resolve(prompt.prompt()).catch(() => {}); } catch { return false; }
+  win._pwaInstallOffered = true;
+  try { win.sessionStorage.setItem(OFFERED_KEY, '1'); } catch {}
+  return true;
+}
+
+const HANDOFF_KEY = 'synabun-pwa-install-handoff';
+
+/**
+ * The guide page's half of the handoff: it leaves a mark for the main UI and goes there instead of asking.
+ * sessionStorage, so the mark is this tab's alone. False when it could not be left: the guide stays then.
+ */
+export function leavePwaInstallHandoff(win = window) {
+  try { win.sessionStorage.setItem(HANDOFF_KEY, '1'); return true; } catch { return false; }
+}
+
+// A press that follows a link, or belongs to a shortcut (reload, new tab, DevTools), would spend the one dialog
+// on a page that is leaving or busy. The next press gets it.
+function keepsItsPress(event) {
+  return !!(event.ctrlKey || event.metaKey || event.altKey) || /^F\d+$/.test(event.key || '')
+    || !!event.target?.closest?.('a[href]');
+}
+
+/**
+ * The main UI's half. It takes the mark, so only the one page load the guide handed over is armed: not a
+ * reload, and never a normal tab. Armed, the first click or key press anywhere opens the browser's dialog
+ * through offerPwaInstallOnce(), in the capture phase because prompt() must run inside the press and the UI
+ * stops many of its events. Without an event yet the next press tries. `leave` names presses to keep out of
+ * it (the menu item that opens the dialog itself). Returns the function that disarms it.
+ */
+export function armPwaInstallHandoff({ win = window, nav = navigator, leave = () => false } = {}) {
+  let marked = false;
+  try {
+    marked = win.sessionStorage.getItem(HANDOFF_KEY) === '1';
+    win.sessionStorage.removeItem(HANDOFF_KEY);
+  } catch {}
+  if (!marked || isStandalone(win, nav) || wasOffered(win)) return () => {};
+  const disarm = () => ['click', 'keydown'].forEach(type => win.removeEventListener(type, press, true));
+  const press = event => {
+    if (keepsItsPress(event) || leave(event)) return;
+    if (offerPwaInstallOnce({ win, nav })) disarm();
+  };
+  ['click', 'keydown'].forEach(type => win.addEventListener(type, press, true));
+  return disarm;
+}
+
+const GUIDE_URL = '/install-app.html';
+
+/**
+ * Where Apps > Install as App goes when the browser has no dialog ready. The mark says the user asked for the
+ * page, so it shows instead of handing over. Safari can add the page it is on to the Dock and the launcher
+ * matches that URL without a query, so only a browser with the install event gets the mark.
+ */
+export function installGuideUrl(win = window) {
+  return canPromptPwaInstall(win) ? `${GUIDE_URL}?from=menu` : GUIDE_URL;
+}
+
+export function installGuideRequested(search = '') {
+  return new URLSearchParams(search).get('from') === 'menu';
+}
+
+/**
+ * What the launcher's guide page is, for this browser and this install:
+ * 'app' (already the installed app: leave), 'wizard' (first run where the wizard opens the dialog: leave),
+ * 'handoff' (setup done and nobody asked for the page: leave, the main UI opens the dialog),
+ * 'button' (one button that opens the browser's dialog: the page was asked for, or the setup read did not
+ * answer), 'safari' or 'other' (plain instructions).
+ */
+export function installGuideMode({ standalone = false, canPrompt = false, setupComplete = null, requested = false, vendor = '' } = {}) {
+  if (standalone) return 'app';
+  if (!canPrompt) return /apple/i.test(vendor) ? 'safari' : 'other';
+  if (setupComplete === false) return 'wizard';
+  return setupComplete === true && !requested ? 'handoff' : 'button';
+}