@hienlh/ppm 0.22.1 → 0.22.3

package/src/web/components/onboarding/onboarding-root.tsx

@@ -0,0 +1,137 @@
+import { useEffect, useState } from "react";
+import { Sparkles } from "@/lib/icons";
+import { Button } from "@/components/ui/button";
+import { useOnboardingStore } from "@/stores/onboarding-store";
+import { useProjectStore } from "@/stores/project-store";
+import { useTabStore } from "@/stores/tab-store";
+import { useSettingsStore, type SidebarActiveTab } from "@/stores/settings-store";
+import { useIsMobile } from "@/hooks/use-is-mobile";
+import { openSettings } from "@/components/settings/open-settings";
+import { ONBOARDING_EVENT, type OnboardingEvent, type OnboardingStepId } from "@/lib/onboarding/onboarding-types";
+import { ONBOARDING_TARGETS, getOnboardingSteps } from "@/lib/onboarding/onboarding-steps";
+import { OnboardingStepTransition } from "./onboarding-step-transition";
+import { ONBOARDING_SUGGESTED_PROMPT } from "@/lib/onboarding/onboarding-copy";
+import { OnboardingSetup } from "./onboarding-setup";
+import { OnboardingGuide } from "./onboarding-guide";
+import { findTourTarget, OnboardingHint } from "./onboarding-hint";
+import { useOnboardingSessionCheck } from "./use-onboarding-session-check";
+import { OPEN_QUICK_ORIENTATION, OnboardingQuickOrientation } from "./onboarding-quick-orientation";
+import { openCommandPalette } from "@/hooks/use-global-keybindings";
+import { openRunInstructions } from "@/lib/onboarding/run-instructions";
+
+export function OnboardingRoot({ openProjects, openNavigation, closeNavigation, paletteOpen = false, navigationOpen = false }: {
+  openProjects: () => void; openNavigation: (tab: SidebarActiveTab) => void; closeNavigation: () => void; paletteOpen?: boolean; navigationOpen?: boolean;
+}) {
+  const state = useOnboardingStore();
+  const project = useProjectStore((s) => s.activeProject);
+  const mobile = useIsMobile();
+  const [collapsed, setCollapsed] = useState(false);
+  const [notice, setNotice] = useState("");
+  const [orientationOpen, setOrientationOpen] = useState(false);
+  useEffect(() => {
+    const open = () => setOrientationOpen(true);
+    window.addEventListener(OPEN_QUICK_ORIENTATION, open);
+    return () => window.removeEventListener(OPEN_QUICK_ORIENTATION, open);
+  }, []);
+  useOnboardingSessionCheck(setNotice);
+  useEffect(() => {
+    const receive = (event: Event) => useOnboardingStore.getState().observe((event as CustomEvent<OnboardingEvent>).detail);
+    window.addEventListener(ONBOARDING_EVENT, receive);
+    return () => window.removeEventListener(ONBOARDING_EVENT, receive);
+  }, []);
+  useEffect(() => { state.setProjectContext(project?.name ?? null); }, [project?.name, state.setProjectContext]);
+  useEffect(() => {
+    if (state.status !== "active") return;
+    setNotice("");
+    setCollapsed(false);
+    const timer = window.setTimeout(() => window.dispatchEvent(new Event("ppm:onboarding-refresh")), 50);
+    return () => clearTimeout(timer);
+  }, [state.status, state.currentStep]);
+  useEffect(() => {
+    if (state.status !== "active" || orientationOpen || paletteOpen) return;
+    const escape = (event: KeyboardEvent) => { if (event.key === "Escape" && !event.defaultPrevented) useOnboardingStore.getState().pause(); };
+    window.addEventListener("keydown", escape);
+    return () => window.removeEventListener("keydown", escape);
+  }, [state.status, orientationOpen, paletteOpen]);
+
+  function navigate(tab: SidebarActiveTab) {
+    if (mobile) { openNavigation(tab); setCollapsed(true); }
+    else {
+      const settings = useSettingsStore.getState();
+      if (settings.sidebarCollapsed) settings.toggleSidebar();
+      settings.setSidebarActiveTab(tab);
+    }
+  }
+  function openWorkTab(type: "chat" | "terminal") {
+    if (!project) { state.setProjectContext(null); return; }
+    closeNavigation();
+    const tabs = useTabStore.getState();
+    const active = tabs.tabs.find((tab) => tab.id === tabs.activeTabId && tab.type === type && tab.projectId === project.name);
+    if (!active) tabs.openTab({ type, title: type === "chat" ? "New Chat" : `Terminal - ${project.name}`, projectId: project.name, metadata: { projectName: project.name }, closable: true });
+    window.setTimeout(() => window.dispatchEvent(new Event("ppm:onboarding-refresh")), 50);
+    if (mobile) setCollapsed(true);
+  }
+  function action(step: OnboardingStepId) {
+    if (step === "project") {
+      if (mobile) { openProjects(); setCollapsed(true); }
+      else {
+        const settings = useSettingsStore.getState();
+        if (settings.sidebarCollapsed) settings.toggleSidebar();
+        window.setTimeout(() => findTourTarget("project")?.click(), 0);
+      }
+    } else if (step === "run") {
+      if (!project) { setNotice("Choose a project first, or skip this step."); return; }
+      if (state.runDocumentReady) { state.observe({ type: "run-acknowledged", projectName: project.name, visible: true }); return; }
+      const projectName = project.name;
+      const stillCurrent = () => {
+        const current = useOnboardingStore.getState();
+        return current.status === "active" && current.currentStep === "run" && current.projectName === projectName && useProjectStore.getState().activeProject?.name === projectName;
+      };
+      setNotice("Looking for README or package.json…");
+      void openRunInstructions(projectName, stillCurrent).then((result) => {
+        if (!stillCurrent()) return;
+        if (result === "missing") setNotice("No README or package.json found in the project root. Browse Files to find other documentation, or skip this step.");
+        else if (result === "opened") { closeNavigation(); setCollapsed(true); setNotice(""); }
+      }).catch(() => { if (stillCurrent()) setNotice("Could not find run instructions. Click Find run instructions to retry, or skip this step."); });
+    } else if (step === "file") {
+      navigate("explorer");
+    } else if (step === "search" || step === "git") navigate(step);
+    else if (step === "chat" || step === "terminal") openWorkTab(step);
+    else if (step === "send" && project) {
+      window.dispatchEvent(new CustomEvent("ppm:onboarding-prompt", { detail: { projectName: project.name, text: ONBOARDING_SUGGESTED_PROMPT } }));
+      setNotice("Review the question in chat, then send it yourself. If you already have a draft, it stays unchanged.");
+      setCollapsed(true);
+    } else if (step === "history") {
+      const target = findTourTarget("chat-history");
+      if (target) { target.click(); setCollapsed(true); }
+      else setNotice("Open the chat you used, then choose its history menu. You can skip if no conversation was created.");
+    }
+  }
+  if (paletteOpen) return null;
+  // Keep every drawer row reachable, including the first file under the header.
+  // Closing the drawer restores the guide; completed tours still show their summary.
+  if (mobile && navigationOpen && collapsed && state.status === "active") return null;
+  if (orientationOpen) return <OnboardingQuickOrientation onClose={() => setOrientationOpen(false)} onTryPalette={() => {
+    setOrientationOpen(false);
+    setCollapsed(true);
+    requestAnimationFrame(() => openCommandPalette());
+  }} />;
+  if (state.status === "dismissed") return null;
+  if (state.status === "choosing") return <OnboardingSetup projectName={project?.name} />;
+  return <OnboardingHint collapsed={collapsed} target={state.status === "active" && state.currentStep ? ONBOARDING_TARGETS[state.currentStep] : undefined}>
+    <OnboardingStepTransition stepKey={state.status === "active" ? state.currentStep ?? "project" : state.status}
+      order={state.status === "finished" ? 100 : state.status === "active" ? getOnboardingSteps(state.goal).indexOf(state.currentStep!) + 1 : 0}>
+    {state.status === "active" ? <>
+      <OnboardingGuide collapsed={collapsed} setCollapsed={setCollapsed} onAction={action} onSettings={() => { openSettings("ai-provider"); setCollapsed(true); }} />
+      {notice && !collapsed && <p role="status" className="px-4 pb-4 text-xs text-text-secondary">{notice}</p>}
+    </> : <div className="p-5">
+      <div className="flex items-center gap-2 text-primary text-xs uppercase tracking-widest"><Sparkles className="size-4" />Your first steps</div>
+      <h2 className="font-semibold text-lg mt-2">{state.status === "finished" ? "Your walkthrough is complete" : state.status === "paused" ? "Continue when you're ready" : "Get started with PPM"}</h2>
+      <p className="text-sm text-text-secondary leading-relaxed mt-2">{state.status === "finished" ? `${state.completed.length} steps completed${state.skipped.length ? ` · ${state.skipped.length} skipped` : ""}. Choose another path, or keep exploring.` : state.status === "paused" ? "Your progress is saved in this browser. Resume here or choose a different guide." : "Choose a guide that fits your experience, then try your first task."}</p>
+      <Button className="w-full min-h-11 mt-4" onClick={() => { setCollapsed(false); state.status === "paused" ? state.resume(project?.name ?? null) : state.status === "finished" ? state.replay() : state.begin(); }}>{state.status === "paused" ? "Resume tour" : state.status === "finished" ? "Try another guide" : "Start guided tour"}</Button>
+      <Button variant="ghost" className="w-full min-h-11 mt-1" onClick={state.dismiss}>{state.status === "finished" ? "Keep exploring" : "Maybe later"}</Button>
+      <Button variant="link" className="w-full min-h-11" onClick={() => setOrientationOpen(true)}>Quick orientation</Button>
+    </div>}
+    </OnboardingStepTransition>
+  </OnboardingHint>;
+}

package/src/web/components/onboarding/onboarding-run-document-preview.tsx

@@ -0,0 +1,23 @@
+import { useEffect, useRef, type ReactNode } from "react";
+import { useTabStore } from "@/stores/tab-store";
+import { emitOnboardingEvidence } from "@/lib/onboarding/onboarding-types";
+
+/** Loaded Markdown is readable in Preview too; a Suspense fallback never counts. */
+export function OnboardingRunDocumentPreview({ projectName, filePath, tabId, ready, children }: {
+  projectName?: string; filePath?: string; tabId?: string; ready: boolean; children: ReactNode;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const activeTabId = useTabStore((state) => state.activeTabId);
+  useEffect(() => {
+    const report = () => {
+      if (!ready || !projectName || !filePath || !tabId || activeTabId !== tabId) return;
+      const visible = !!ref.current?.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true });
+      if (visible) emitOnboardingEvidence({ type: "file-ready", projectName, tabId, visible,
+        isRunDocument: /^readme(?:\.[^/\\]+)?$/i.test(filePath.split(/[/\\]/).pop() ?? "") });
+    };
+    report();
+    window.addEventListener("ppm:onboarding-refresh", report);
+    return () => window.removeEventListener("ppm:onboarding-refresh", report);
+  }, [projectName, filePath, tabId, ready, activeTabId]);
+  return <div ref={ref} className="flex flex-1 min-h-0 flex-col">{children}</div>;
+}

package/src/web/components/onboarding/onboarding-setup.tsx

@@ -0,0 +1,50 @@
+import { useRef, useState } from "react";
+import { Sparkles, Code, MessageSquare, ArrowLeft } from "@/lib/icons";
+import { Dialog, DialogContent, DialogDescription, DialogTitle } from "@/components/ui/dialog";
+import { Button } from "@/components/ui/button";
+import { useOnboardingStore } from "@/stores/onboarding-store";
+import type { OnboardingFamiliarity, OnboardingGoal } from "@/lib/onboarding/onboarding-types";
+import { OnboardingStepTransition } from "./onboarding-step-transition";
+
+const levels: Array<{ id: OnboardingFamiliarity; title: string; body: string; icon: typeof Sparkles }> = [
+  { id: "beginner", title: "I'm just getting started", body: "One step at a time, with the basics explained.", icon: Sparkles },
+  { id: "familiar", title: "I've used similar tools", body: "A quick introduction to finding your way around PPM.", icon: Sparkles },
+  { id: "advanced", title: "I'm a developer / advanced user", body: "Go straight to the workspace and tools.", icon: Code },
+];
+const goals: Array<{ id: OnboardingGoal; title: string; body: string; icon: typeof Sparkles }> = [
+  { id: "ai", title: "Work with AI", body: "Ask about a project and find your conversation again.", icon: MessageSquare },
+  { id: "explore", title: "Explore a project", body: "Open a file and search through your project.", icon: Sparkles },
+  { id: "developer", title: "Use development tools", body: "Find the terminal, Git changes and run instructions.", icon: Code },
+];
+
+export function OnboardingSetup({ projectName }: { projectName?: string }) {
+  const store = useOnboardingStore();
+  const opener = useRef(document.activeElement as HTMLElement | null);
+  const [screen, setScreen] = useState<"level" | "goal">("level");
+  return <Dialog open onOpenChange={(open) => { if (!open) store.dismiss(); }}>
+    <DialogContent onCloseAutoFocus={(event) => {
+      event.preventDefault();
+      const target = opener.current?.isConnected ? opener.current : document.querySelector<HTMLElement>('aside[aria-label="PPM guided tour"] button');
+      target?.focus();
+    }} className="max-h-[90dvh] overflow-y-auto sm:max-w-[520px] p-5 sm:p-7">
+      <OnboardingStepTransition stepKey={screen} order={screen === "level" ? 0 : 1} className="grid gap-4">
+      <div className="text-xs font-medium tracking-widest uppercase text-primary">Your first steps · {screen === "level" ? "1" : "2"} of 2</div>
+      <DialogTitle className="text-2xl leading-tight">{screen === "level" ? "Make PPM feel familiar" : "What would you like to do first?"}</DialogTitle>
+      <DialogDescription>{screen === "level" ? "Choose the amount of guidance that suits you. You can change this anytime." : "Every path is available to you. Start with something useful."}</DialogDescription>
+      <div className="grid gap-3 mt-1">
+        {screen === "level" ? levels.map(({ id, title, body, icon: Icon }) =>
+          <button key={id} onClick={() => { store.chooseFamiliarity(id); setScreen("goal"); }} className="flex items-start gap-4 rounded-lg border border-border bg-surface p-4 text-left hover:border-primary focus-visible:outline-2 focus-visible:outline-primary">
+            <Icon className="size-5 shrink-0 text-primary mt-0.5" /><span><span className="block font-medium text-sm">{title}</span><span className="block mt-1 text-sm text-text-secondary">{body}</span></span>
+          </button>) : goals.map(({ id, title, body, icon: Icon }) =>
+          <button key={id} onClick={() => { store.chooseGoal(id); store.start(projectName); }} className="flex items-start gap-4 rounded-lg border border-border bg-surface p-4 text-left hover:border-primary focus-visible:outline-2 focus-visible:outline-primary">
+            <Icon className="size-5 shrink-0 text-primary mt-0.5" /><span><span className="block font-medium text-sm">{title}{id === "ai" && <span className="ml-2 text-xs text-primary">Suggested</span>}</span><span className="block mt-1 text-sm text-text-secondary">{body}</span></span>
+          </button>)}
+      </div>
+      <div className="flex items-center justify-between">
+        {screen === "goal" ? <Button variant="ghost" className="min-h-11" onClick={() => setScreen("level")}><ArrowLeft />Back</Button> : <span />}
+        <Button variant="ghost" className="min-h-11 text-text-secondary" onClick={store.dismiss}>I'll explore on my own</Button>
+      </div>
+      </OnboardingStepTransition>
+    </DialogContent>
+  </Dialog>;
+}

package/src/web/components/onboarding/onboarding-step-transition.tsx

@@ -0,0 +1,27 @@
+import { useLayoutEffect, useRef, type ReactNode } from "react";
+
+/** Animate the existing content node: no delayed state updates or duplicate controls. */
+export function OnboardingStepTransition({ stepKey, order, className, children }: {
+  stepKey: string; order: number; className?: string; children: ReactNode;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const previous = useRef({ stepKey, order });
+  useLayoutEffect(() => {
+    const before = previous.current;
+    previous.current = { stepKey, order };
+    const node = ref.current;
+    if (before.stepKey === stepKey || !node?.animate) return;
+    const preference = window.matchMedia("(prefers-reduced-motion: reduce)");
+    if (preference.matches) return;
+    const animation = node.animate([
+      { opacity: 0.35, transform: `translateX(${order < before.order ? -12 : 12}px)` },
+      { opacity: 1, transform: "translateX(0)" },
+    ], { duration: 200, easing: "cubic-bezier(0.2, 0, 0, 1)" });
+    // Canceling on rapid navigation/unmount rejects finished; that is expected.
+    void animation.finished.catch(() => {});
+    const stop = () => { if (preference.matches) animation.cancel(); };
+    preference.addEventListener("change", stop);
+    return () => { animation.cancel(); preference.removeEventListener("change", stop); };
+  }, [stepKey, order]);
+  return <div ref={ref} data-onboarding-transition={stepKey} className={className}>{children}</div>;
+}

package/src/web/components/onboarding/use-onboarding-session-check.ts

@@ -0,0 +1,32 @@
+import { useEffect } from "react";
+import { api, projectUrl } from "@/lib/api-client";
+import { useOnboardingStore } from "@/stores/onboarding-store";
+import type { SessionListResponse } from "../../../types/chat";
+
+/** Revalidate a restored history target without opening or sending any chat. */
+export function useOnboardingSessionCheck(setNotice: (message: string) => void): void {
+  const { status, currentStep, projectName, sessionId } = useOnboardingStore();
+  useEffect(() => {
+    if (status !== "active" || currentStep !== "history" || !projectName || !sessionId) return;
+    let cancelled = false;
+    const check = async () => {
+      let offset = 0;
+      for (let page = 0; page < 10; page++) {
+        const result = await api.get<SessionListResponse>(`${projectUrl(projectName)}/chat/sessions?limit=100&offset=${offset}`);
+        if (cancelled || result.sessions.some((session) => session.id === sessionId)) return;
+        if (!result.hasMore) {
+          useOnboardingStore.setState((state) => state.status === "active" && state.sessionId === sessionId && state.currentStep === "history" ? {
+            currentStep: "chat", sessionId: null, attempt: null,
+            completed: state.completed.filter((id) => id === "project"), skipped: [],
+          } : {});
+          setNotice("That conversation is no longer available. Open a chat to try again, or skip this step.");
+          return;
+        }
+        offset += result.sessions.filter((session) => !session.pinned).length;
+      }
+      if (!cancelled) setNotice("Open chat history to find the conversation, or skip this step.");
+    };
+    void check().catch(() => { if (!cancelled) setNotice("History could not be checked. Try the history menu again when connected, or pause the tour."); });
+    return () => { cancelled = true; };
+  }, [status, currentStep, projectName, sessionId, setNotice]);
+}

package/src/web/components/settings/ai-settings-section.tsx

@@ -120,6 +120,42 @@ export function AISettingsSection({ compact }: { compact?: boolean } = {}) {
     <div className={gapSize}>
       <h3 className={`${headingSize} font-medium text-text-secondary`}>AI Settings</h3>
 
+      <div className={fieldGap}>
+        <Label htmlFor="ai-new-chat-provider" className={compact ? labelSize : undefined}>New chat provider</Label>
+        <Select
+          value={settings.new_chat_provider_mode ?? "default"}
+          disabled={saving}
+          onValueChange={(value) => handleSettingsSave({ new_chat_provider_mode: value as "default" | "follow-focus" })}
+        >
+          <SelectTrigger id="ai-new-chat-provider" className={`w-full ${compact ? "h-7 text-[11px]" : ""}`}><SelectValue /></SelectTrigger>
+          <SelectContent>
+            <SelectItem value="follow-focus">Follow last focused chat</SelectItem>
+            <SelectItem value="default">Always use default provider</SelectItem>
+          </SelectContent>
+        </Select>
+        <p className={`${compact ? "text-[9px]" : "text-[11px]"} text-muted-foreground`}>
+          {settings.new_chat_provider_mode === "follow-focus"
+            ? "New tabs follow the last chat you focused in this project, across panels. Existing tabs keep their provider."
+            : "New tabs always use the default provider. Existing tabs keep their provider."}
+        </p>
+      </div>
+
+      <div className={fieldGap}>
+        <Label htmlFor="ai-default-provider" className={compact ? labelSize : undefined}>Default provider</Label>
+        <Select value={settings.default_provider} disabled={saving}
+          onValueChange={(default_provider) => handleSettingsSave({ default_provider })}>
+          <SelectTrigger id="ai-default-provider" className={`w-full ${compact ? "h-7 text-[11px]" : ""}`}><SelectValue /></SelectTrigger>
+          <SelectContent>
+            {providerTabs.map((p) => <SelectItem key={p.id} value={p.id}>{p.name}</SelectItem>)}
+          </SelectContent>
+        </Select>
+        {settings.new_chat_provider_mode === "follow-focus" && (
+          <p className={`${compact ? "text-[9px]" : "text-[11px]"} text-muted-foreground`}>
+            Used when no chat has been focused in this project yet.
+          </p>
+        )}
+      </div>
+
       <div className="flex items-start justify-between gap-3 rounded-md border border-border p-3">
         <div className={fieldGap}>
           <Label htmlFor="ai-share-provider-context" className={compact ? labelSize : undefined}>

package/src/web/components/settings/general-settings-section.tsx

@@ -16,6 +16,7 @@ import { Switch } from "@/components/ui/switch";
 import { useSettingsStore } from "@/stores/settings-store";
 import { wakeLockSupport } from "@/hooks/use-wake-lock";
 import { ChangePasswordSection } from "./change-password-section";
+import { OnboardingEntry } from "@/components/onboarding/onboarding-entry";
 
 export function GeneralSettingsSection() {
   const { deviceName, setDeviceName, version, keepScreenAwake, setKeepScreenAwake } = useSettingsStore(
@@ -51,6 +52,12 @@ export function GeneralSettingsSection() {
 
   return (
     <div className="space-y-6">
+      <section className="space-y-2">
+        <h3 className="text-sm font-medium">Learn PPM</h3>
+        <p className="text-sm text-muted-foreground">Choose your experience and a task. Guidance is saved in this browser.</p>
+        <OnboardingEntry compact />
+      </section>
+      <Separator />
       <section className="space-y-2">
         <Label htmlFor="device-name">Device Name</Label>
         <div className="flex gap-2">

package/src/web/components/terminal/terminal-tab.tsx

@@ -8,6 +8,8 @@ import { copyToClipboard } from "@/lib/clipboard";
 import { RotateCcw, MessageSquare } from "@/lib/icons";
 import "@xterm/xterm/css/xterm.css";
 import { toast } from "sonner";
+import { useTabStore } from "@/stores/tab-store";
+import { emitOnboardingEvidence } from "@/lib/onboarding/onboarding-types";
 
 import { TerminalMobileToolbar } from "./terminal-mobile-toolbar";
 import { TerminalLinksSheet } from "./terminal-links-sheet";
@@ -27,6 +29,18 @@ export const TerminalTab = memo(function TerminalTab({ metadata, tabId }: Termin
   const [ctrlMode, setCtrlMode] = useState(false);
   const [selectMode, setSelectMode] = useState(false);
   const [linksOpen, setLinksOpen] = useState(false);
+  const activeTabId = useTabStore((s) => s.activeTabId);
+  const [onboardingRefresh, setOnboardingRefresh] = useState(0);
+  useEffect(() => {
+    const refresh = () => setOnboardingRefresh((n) => n + 1);
+    window.addEventListener("ppm:onboarding-refresh", refresh);
+    return () => window.removeEventListener("ppm:onboarding-refresh", refresh);
+  }, []);
+  useEffect(() => {
+    if (!projectName || !tabId || activeTabId !== tabId || !connected || !shellReady || reconnecting || exited) return;
+    const visible = !!containerRef.current?.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true });
+    if (visible) emitOnboardingEvidence({ type: "terminal-ready", projectName, tabId, visible });
+  }, [onboardingRefresh, projectName, tabId, activeTabId, connected, shellReady, reconnecting, exited]);
 
   useTerminalTouchSelection(containerRef, selectMode);
 
@@ -125,7 +139,7 @@ export const TerminalTab = memo(function TerminalTab({ metadata, tabId }: Termin
   const isMobile = typeof window !== "undefined" && "ontouchstart" in window;
 
   return (
-    <div className="flex flex-col h-full min-h-0">
+    <div data-onboarding="terminal" className="flex flex-col h-full min-h-0">
       {/* Status bar */}
       <div className="flex items-center gap-2 px-3 py-1 bg-surface border-b border-border text-xs">
         <span

package/src/web/hooks/use-chat.ts

@@ -1,4 +1,5 @@
 import { useState, useCallback, useRef, useEffect, useMemo, startTransition } from "react";
+import { ChatAttemptLifecycle, type ChatAttemptEvent } from "@/lib/chat-attempt-lifecycle";
 import { useWebSocket } from "./use-websocket";
 import { api, projectUrl } from "@/lib/api-client";
 import { flattenWithExpansions, prefixPreCompactIds } from "@/lib/flatten-expansions";
@@ -130,7 +131,12 @@ export function useChat(
    * empty even though the conversation is on disk under the new id.
    */
   onSessionMigrated?: (newSessionId: string) => void,
+  onAttempt?: (event: ChatAttemptEvent) => void,
 ): UseChatReturn {
+  const attemptObserverRef = useRef(onAttempt);
+  attemptObserverRef.current = onAttempt;
+  const attemptRef = useRef<ChatAttemptLifecycle | null>(null);
+  if (!attemptRef.current) attemptRef.current = new ChatAttemptLifecycle((event) => attemptObserverRef.current?.(event));
   const [messages, setMessages] = useState<ChatMessage[]>([]);
   /** Map of compactMessageId → pre-compact messages (already ID-prefixed). Ephemeral. */
   const [expansions, setExpansions] = useState<Map<string, ChatMessage[]>>(new Map());
@@ -609,6 +615,7 @@ export function useChat(
       }
 
       case "error": {
+        if (!isReplayingRef.current) attemptRef.current?.fail();
         setMessages((prev) => {
           const last = prev[prev.length - 1];
           if (last?.role === "assistant") {
@@ -703,6 +710,7 @@ export function useChat(
       }
 
       case "done": {
+        if (!isReplayingRef.current) attemptRef.current?.finish(!!streamingContentRef.current.trim());
         // Idempotent: may receive duplicate done (provider + stream loop finally)
         if (phaseRef.current === "idle") break;
         if (ev.contextWindowPct != null) {
@@ -815,6 +823,7 @@ export function useChat(
     if ((data as any).type === "session_migrated") {
       const migratedTo = (data as any).newSessionId as string | undefined;
       if (migratedTo && migratedTo !== sessionIdRef.current) {
+        attemptRef.current?.migrate(migratedTo);
         onSessionMigratedRef.current?.(migratedTo);
       }
       return;
@@ -1015,6 +1024,7 @@ export function useChat(
     idleTimeoutMs: 45_000, // Server sends a heartbeat every 15 seconds.
     onConnectionChange: (connected) => {
       if (!connected) {
+        attemptRef.current?.fail();
         setIsConnected(false);
         setIsReconnecting(true);
       }
@@ -1028,6 +1038,7 @@ export function useChat(
   // Load history and reset state when session changes
   useEffect(() => {
     let cancelled = false;
+    attemptRef.current?.select(sessionId);
     const historyReconciled = historyReconciledRef.current;
     turnFinalizedRef.current = false;
     historyActivityRef.current++;
@@ -1170,6 +1181,7 @@ export function useChat(
       historyActivityRef.current++;
 
       const isFollowUp = phaseRef.current !== "idle";
+      if (sessionIdRef.current) attemptRef.current?.start(sessionIdRef.current, !isFollowUp, isConnected && connectedSessionId === sessionIdRef.current);
       turnFinalizedRef.current = false;
 
       if (isFollowUp) {
@@ -1227,7 +1239,7 @@ export function useChat(
         ...(thinkingRef.current !== null && { thinking: thinkingRef.current }),
       }));
     },
-    [send],
+    [send, isConnected, connectedSessionId],
   );
 
   const setModel = useCallback(
@@ -1294,6 +1306,7 @@ export function useChat(
   );
 
   const cancelStreaming = useCallback(() => {
+    attemptRef.current?.fail();
     if (phaseRef.current === "idle") return;
     send(JSON.stringify({ type: "cancel" }));
     const finalContent = streamingContentRef.current;

package/src/web/hooks/use-draft.ts

@@ -86,11 +86,32 @@ export function useDraft(projectName: string, sessionId: string | null) {
     [projectName],
   );
 
-  // Clear draft (on send)
-  const clear = useCallback(() => {
+  /**
+   * Drop a save that is still waiting on the debounce, without touching the server.
+   *
+   * Called at Enter. The save runs against whatever session the tab is on when the
+   * timer fires — and the first send of a new tab swaps the tab onto its new session
+   * within that second, so a save left armed would write the message just sent as the
+   * new session's draft, to reappear in the composer on the next mount as if unsent.
+   */
+  const cancelPendingSave = useCallback(() => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    timerRef.current = undefined;
+  }, []);
+
+  /**
+   * Clear the draft once its message has actually been handed to the socket.
+   *
+   * `draftId` names the draft the message was composed under. The first send of a
+   * new tab creates the session and only then sends, so by the time the send
+   * happens `sessionRef` already points at the new session while the draft still
+   * lives under `__new__` — deleting by the current session id would leave it
+   * behind and restore it into the next new tab.
+   */
+  const clear = useCallback((draftId?: string) => {
     if (!projectName) return;
     if (timerRef.current) clearTimeout(timerRef.current);
-    const id = sessionRef.current ?? "__new__";
+    const id = draftId ?? sessionRef.current ?? "__new__";
     api
       .del(`${projectUrl(projectName)}/chat/drafts/${encodeURIComponent(id)}`)
       .catch(() => {});
@@ -104,5 +125,5 @@ export function useDraft(projectName: string, sessionId: string | null) {
     };
   }, []);
 
-  return { draft, draftLoading: loading, saveDraft: save, clearDraft: clear };
+  return { draft, draftLoading: loading, saveDraft: save, clearDraft: clear, cancelPendingSave };
 }

package/src/web/hooks/use-session-history.ts

@@ -2,7 +2,7 @@ import { useState, useEffect, useCallback, useRef } from "react";
 import { api, projectUrl } from "@/lib/api-client";
 import { useTabStore } from "@/stores/tab-store";
 import { useDebouncedValue } from "@/hooks/use-debounced-value";
-import type { SessionInfo, SessionListResponse, ProjectTag } from "../../types/chat";
+import { compareSessionsByActivity, type SessionInfo, type SessionListResponse, type ProjectTag } from "../../types/chat";
 
 const PAGE_SIZE = 50;
 
@@ -145,11 +145,7 @@ export function useSessionHistory({
       }
       setSessions((prev) => {
         const updated = prev.map((s) => s.id === session.id ? { ...s, pinned: !s.pinned } : s);
-        return updated.sort((a, b) => {
-          if (a.pinned && !b.pinned) return -1;
-          if (!a.pinned && b.pinned) return 1;
-          return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
-        });
+        return updated.sort(compareSessionsByActivity);
       });
     } catch { /* silent */ }
   }, [projectName]);

package/src/web/hooks/use-usage.ts

@@ -26,8 +26,9 @@ interface UseUsageReturn {
  * `sessionId` scopes the reported account to this session's binding. Without it the header
  * shows whichever account ran last across every open session, which is wrong for all but one.
  */
-export function useUsage(projectName: string, providerId = "claude", sessionId?: string): UseUsageReturn {
-  const scope = JSON.stringify([projectName, providerId, sessionId]);
+export function useUsage(projectName: string, providerId = "claude", sessionId?: string, pickedAccountId?: string): UseUsageReturn {
+  const previewAccountId = providerId === "codex" && !sessionId ? pickedAccountId : undefined;
+  const scope = JSON.stringify([projectName, providerId, sessionId, previewAccountId]);
   const [snapshot, setSnapshot] = useState<{ scope: string; usage: UsageInfo; fetchedAt: string | null } | null>(null);
   const [usageLoading, setUsageLoading] = useState(false);
   const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
@@ -39,11 +40,12 @@ export function useUsage(projectName: string, providerId = "claude", sessionId?:
     setUsageLoading(true);
     const qs = forceRefresh ? "&refresh=1" : "";
     const sessionQs = sessionId ? `&session=${encodeURIComponent(sessionId)}` : "";
+    const accountQs = previewAccountId ? `&accountId=${encodeURIComponent(previewAccountId)}` : "";
     // Via api.get, not raw fetch: the toolbar's loading state is gated on this
     // settling, and a raw fetch has no timeout to stop it stalling forever.
     return api
       .get<(UsageInfo & { lastFetchedAt?: string }) | null>(
-        `${projectUrl(projectName)}/chat/usage?providerId=${providerId}${sessionQs}${qs}`,
+        `${projectUrl(projectName)}/chat/usage?providerId=${providerId}${sessionQs}${accountQs}${qs}`,
       )
       .then((data) => {
         if (request !== requestRef.current) return;
@@ -55,7 +57,7 @@ export function useUsage(projectName: string, providerId = "claude", sessionId?:
       .finally(() => {
         if (request === requestRef.current) setUsageLoading(false);
       });
-  }, [projectName, providerId, sessionId, scope]);
+  }, [projectName, providerId, sessionId, previewAccountId, scope]);
 
   // Read cache on mount + auto-read every POLL_INTERVAL
   useEffect(() => {

package/src/web/lib/api-client.ts

@@ -122,11 +122,17 @@ export class ApiClient {
     }
   }
 
-  async post<T>(path: string, body?: unknown): Promise<T> {
+  /**
+   * No default timeout, unlike `get`: a POST is not idempotent, so cutting one off
+   * mid-flight can leave the server having done the work with nobody to tell. A
+   * caller that would rather fail loudly than wait passes its own `signal`.
+   */
+  async post<T>(path: string, body?: unknown, options?: { signal?: AbortSignal }): Promise<T> {
     const res = await fetch(`${this.baseUrl}${path}`, {
       method: "POST",
       headers: this.headers(),
       body: body != null ? JSON.stringify(body) : undefined,
+      signal: options?.signal,
     });
     return this.handleResponse<T>(res);
   }

package/src/web/lib/api-settings.ts

@@ -212,6 +212,7 @@ export interface AIProviderSettings {
 
 export interface AISettings {
   default_provider: string;
+  new_chat_provider_mode?: "default" | "follow-focus";
   share_provider_context?: boolean;
   providers: Record<string, AIProviderSettings>;
 }

package/src/web/lib/chat-attempt-lifecycle.ts

@@ -0,0 +1,46 @@
+/** Local dispatch evidence, deliberately independent of tour state and server turn IDs. */
+export interface ChatAttemptEvent {
+  type: "started" | "succeeded" | "failed" | "session";
+  attemptId: string;
+  sessionId: string;
+  previousSessionId?: string;
+  hasContent?: boolean;
+}
+
+export class ChatAttemptLifecycle {
+  private attempt: { attemptId: string; sessionId: string } | null = null;
+  constructor(private emit: (event: ChatAttemptEvent) => void) {}
+
+  start(sessionId: string, idle: boolean, connected: boolean) {
+    // A follow-up can overlap an earlier done frame: never attribute it as success.
+    this.fail();
+    if (!idle || !connected) return;
+    this.attempt = { sessionId, attemptId: crypto.randomUUID() };
+    this.emit({ type: "started", ...this.attempt });
+  }
+
+  migrate(sessionId: string) {
+    if (!this.attempt || this.attempt.sessionId === sessionId) return;
+    const previousSessionId = this.attempt.sessionId;
+    this.attempt.sessionId = sessionId;
+    this.emit({ type: "session", ...this.attempt, previousSessionId });
+  }
+
+  select(sessionId: string | null) {
+    if (this.attempt && this.attempt.sessionId !== sessionId) this.fail();
+  }
+
+  fail() {
+    if (!this.attempt) return;
+    const attempt = this.attempt;
+    this.attempt = null;
+    this.emit({ type: "failed", ...attempt });
+  }
+
+  finish(hasContent: boolean) {
+    if (!this.attempt) return;
+    const attempt = this.attempt;
+    this.attempt = null;
+    this.emit({ type: hasContent ? "succeeded" : "failed", ...attempt, hasContent });
+  }
+}