@hienlh/ppm 0.22.2 → 0.22.4

package/src/web/components/editor/code-editor.tsx

@@ -5,6 +5,8 @@ import { api, projectUrl } from "@/lib/api-client";
 import { useShallow } from "zustand/react/shallow";
 import { useTabStore } from "@/stores/tab-store";
 import { usePanelStore } from "@/stores/panel-store";
+import { emitOnboardingEvidence } from "@/lib/onboarding/onboarding-types";
+import { OnboardingRunDocumentPreview } from "@/components/onboarding/onboarding-run-document-preview";
 import { useSettingsStore } from "@/stores/settings-store";
 import { basename } from "@/lib/utils";
 import { useMonacoTheme } from "@/lib/use-monaco-theme";
@@ -18,6 +20,8 @@ import { LspStatus } from "./lsp-status";
 import { Loader2, FileWarning, Play, Database, ExternalLink, X, GripHorizontal, ShieldCheck, ShieldOff } from "@/lib/icons";
 import { EditorBreadcrumb } from "./editor-breadcrumb";
 import { EditorToolbar } from "./editor-toolbar";
+import { HtmlPreview } from "./html-preview";
+import { HtmlPreviewToolbar } from "./html-preview-toolbar";
 import { EditorLanguagePicker } from "./editor-language-picker";
 import { SaveAsDialog } from "./save-as-dialog";
 import { EditorMobileToolbar } from "./editor-mobile-toolbar";
@@ -87,6 +91,14 @@ export const CodeEditor = memo(function CodeEditor({ metadata, tabId }: CodeEdit
   const [encoding, setEncoding] = useState<string>("utf-8");
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
+  const [loadedFile, setLoadedFile] = useState<string | null>(null);
+  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);
+  }, []);
   const [unsaved, setUnsaved] = useState(false);
   const saveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const latestContentRef = useRef<string>("");
@@ -136,6 +148,11 @@ export const CodeEditor = memo(function CodeEditor({ metadata, tabId }: CodeEdit
   const isAudio = AUDIO_EXTS.has(ext);
   const isSqlite = SQLITE_EXTS.has(ext);
   const isMarkdown = ext === "md" || ext === "mdx";
+  const isHtml = (ext === "html" || ext === "htm") && !isUntitled && inlineContent == null;
+  const [htmlMode, setHtmlMode] = useState<"edit" | "preview">("preview");
+  const [htmlRevision, setHtmlRevision] = useState(0);
+  const [htmlCodeOpened, setHtmlCodeOpened] = useState(false);
+  const htmlPreviewVisible = isHtml && htmlMode === "preview";
   const isCsv = ext === "csv";
   // Explicit language override (from language picker / New DB Query); falls back to file extension.
   const langOverride = metadata?.language as string | undefined;
@@ -322,6 +339,17 @@ export const CodeEditor = memo(function CodeEditor({ metadata, tabId }: CodeEdit
   // Detect external (absolute) file path — not relative to project
   const isExternalFile = filePath ? /^(\/|[A-Za-z]:[/\\])/.test(filePath) : false;
 
+  useEffect(() => {
+    if (!projectName || !filePath || !tabId || activeTabId !== tabId || loading || error || !mounted ||
+      loadedFile !== `${projectName}:${filePath}` || inlineContent != null || isUntitled || isSqlite || encoding === "base64" ||
+      htmlPreviewVisible || isImage || isPdf || isDocx || isVideo || isAudio || (isMarkdown && mdMode === "preview") || (isCsv && csvMode === "table")) return;
+    const node = mounted.editor.getDomNode();
+    const visible = !!node?.isConnected && !!node.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true });
+    if (visible) emitOnboardingEvidence({ type: "file-ready", projectName, tabId, visible,
+      isRunDocument: /^(readme(?:\..*)?|package\.json)$/i.test(basename(filePath)) });
+  }, [onboardingRefresh, projectName, filePath, tabId, activeTabId, loading, error, mounted, loadedFile, inlineContent, isUntitled,
+    isSqlite, encoding, isImage, isPdf, isDocx, isVideo, isAudio, isMarkdown, mdMode, isCsv, csvMode, htmlPreviewVisible]);
+
   // Load file content
   useEffect(() => {
     if (inlineContent != null) { setLoading(false); return; }
@@ -338,6 +366,8 @@ export const CodeEditor = memo(function CodeEditor({ metadata, tabId }: CodeEdit
 
     setLoading(true);
     setError(null);
+    setLoadedFile(null);
+    let cancelled = false;
 
     const readUrl = isExternalFile
       ? `/api/fs/read?path=${encodeURIComponent(filePath)}`
@@ -346,17 +376,20 @@ export const CodeEditor = memo(function CodeEditor({ metadata, tabId }: CodeEdit
     api
       .get<{ content: string; encoding?: string }>(readUrl)
       .then((data) => {
+        if (cancelled) return;
         setContent(data.content);
-        if (data.encoding) setEncoding(data.encoding);
+        setEncoding(data.encoding ?? "utf-8");
+        setLoadedFile(`${projectName}:${filePath}`);
         latestContentRef.current = data.content;
         setLoading(false);
       })
       .catch((err) => {
+        if (cancelled) return;
         setError(err instanceof Error ? err.message : "Failed to load file");
         setLoading(false);
       });
 
-    return () => { if (saveTimerRef.current) clearTimeout(saveTimerRef.current); };
+    return () => { cancelled = true; if (saveTimerRef.current) clearTimeout(saveTimerRef.current); };
   }, [filePath, projectName, isImage, isPdf, isDocx, isExternalFile, isUntitled]);
 
   // Manual reload: re-fetch content from disk (fallback when fs watch misses a change)
@@ -448,7 +481,7 @@ export const CodeEditor = memo(function CodeEditor({ metadata, tabId }: CodeEdit
   // buffer no server can serve must not switch the built-in worker back on underneath the
   // project file in the next tab.
   const lspWanted = lspEnabled && !isTouchOnly;
-  const lspOn = lspWanted && lspServable;
+  const lspOn = lspWanted && lspServable && !htmlPreviewVisible;
   const [lsp, setLsp] = useState<EditorLspState>({ status: null, diagnostics: [] });
   const handleLspState = useCallback((next: EditorLspState) => setLsp(next), []);
 
@@ -782,6 +815,7 @@ export const CodeEditor = memo(function CodeEditor({ metadata, tabId }: CodeEdit
   return (
     <div
       ref={containerRef}
+      data-onboarding="file"
       className="flex flex-col h-full w-full overflow-hidden"
       style={mobileHeight ? { height: `${mobileHeight}px`, maxHeight: `${mobileHeight}px` } : undefined}
     >
@@ -807,7 +841,7 @@ export const CodeEditor = memo(function CodeEditor({ metadata, tabId }: CodeEdit
         </div>
       )}
       {/* Breadcrumb + Toolbar bar — desktop only */}
-      {filePath && projectName && tabId && (
+      {!isHtml && filePath && projectName && tabId && (
         <div className="hidden md:flex items-center h-7 border-b border-border bg-background shrink-0">
           <EditorBreadcrumb
             filePath={filePath}
@@ -850,7 +884,7 @@ export const CodeEditor = memo(function CodeEditor({ metadata, tabId }: CodeEdit
       )}
 
       {/* Language + SQL toolbar for untitled / external files (no project breadcrumb) */}
-      {inlineContent == null && tabId && (isUntitled || (filePath && !projectName)) && (
+      {!isHtml && inlineContent == null && tabId && (isUntitled || (filePath && !projectName)) && (
         <div className="hidden md:flex items-center h-7 border-b border-border bg-background shrink-0 px-2">
           <span className="text-xs text-muted-foreground truncate flex-1">
             {isUntitled ? `Untitled-${metadata?.untitledNumber ?? 1}` : (filePath ? basename(filePath) : "Untitled")}
@@ -860,15 +894,33 @@ export const CodeEditor = memo(function CodeEditor({ metadata, tabId }: CodeEdit
         </div>
       )}
 
+      {isHtml && filePath && (
+        <HtmlPreviewToolbar mode={htmlMode} onModeChange={(mode) => {
+          if (mode === "edit") setHtmlCodeOpened(true);
+          setHtmlMode(mode);
+        }}
+          onRefresh={() => { setHtmlMode("preview"); setHtmlRevision((value) => value + 1); }} unsaved={unsaved}
+          onReloadCode={reloadFile} refreshing={refreshing}
+          breadcrumb={projectName && tabId ? <EditorBreadcrumb filePath={filePath} projectName={projectName} tabId={tabId} className="flex items-center min-w-0 overflow-x-auto scrollbar-none gap-0.5" /> : <span className="truncate text-xs text-muted-foreground">{basename(filePath)}</span>}
+          filePath={filePath} projectName={projectName} wordWrap={wrapOn} onToggleWordWrap={toggleWrap}
+          inlineBlame={inlineBlame} onToggleInlineBlame={canBlame ? toggleInlineBlame : undefined}
+          language={effectiveLanguage} onLanguageChange={handleLanguageChange}
+          lspEnabled={lspWanted} onToggleLsp={lspServable && !isTouchOnly ? setLspEnabled : undefined} />
+      )}
+
       {/* Content area */}
-      {isCsv && csvMode === "table" ? (
+      {htmlPreviewVisible && filePath && (
+        <HtmlPreview filePath={filePath} projectName={projectName} revision={htmlRevision} />
+      )}
+      {htmlPreviewVisible && !htmlCodeOpened ? null : isCsv && csvMode === "table" ? (
         <Suspense fallback={<div className="flex items-center justify-center h-full"><Loader2 className="size-5 animate-spin text-text-subtle" /></div>}>
           <CsvPreview content={content ?? ""} onContentChange={handleChange} wordWrap={wrapOn} />
         </Suspense>
       ) : isMarkdown && mdMode === "preview" ? (
-        <MarkdownPreview content={content ?? ""} />
+        <MarkdownPreview content={content ?? ""} projectName={projectName} filePath={filePath} tabId={tabId}
+          ready={!loading && !error && loadedFile === `${projectName}:${filePath}` && inlineContent == null && !isUntitled} />
       ) : (
-        <div className="flex-1 overflow-hidden min-h-0">
+        <div className={htmlPreviewVisible ? "hidden" : "flex-1 overflow-hidden min-h-0"}>
           <Editor
             height="100%"
             key={effectiveLanguage}
@@ -930,7 +982,7 @@ export const CodeEditor = memo(function CodeEditor({ metadata, tabId }: CodeEdit
       )}
 
       {/* Mobile toolbar — bottom, like terminal */}
-      {isMobile && (
+      {isMobile && !htmlPreviewVisible && (
         <EditorMobileToolbar
           editorRef={editorRef}
           readOnly={inlineContent != null}
@@ -1047,11 +1099,12 @@ function LoadingSpinner() {
   return <div className="flex items-center justify-center h-full"><Loader2 className="size-5 animate-spin text-text-subtle" /></div>;
 }
 
-function MarkdownPreview({ content }: { content: string }) {
+function MarkdownPreview({ content, ...context }: { content: string; projectName?: string; filePath?: string; tabId?: string; ready: boolean }) {
   return (
     <Suspense fallback={<div className="animate-pulse h-4 bg-muted rounded m-4" />}>
-      <MarkdownRenderer content={content} className="flex-1 overflow-auto p-4" />
+      <OnboardingRunDocumentPreview {...context}>
+        <MarkdownRenderer content={content} className="flex-1 overflow-auto p-4" />
+      </OnboardingRunDocumentPreview>
     </Suspense>
   );
 }
-

package/src/web/components/editor/html-preview-toolbar.tsx

@@ -0,0 +1,80 @@
+import type { ReactNode } from "react";
+import { Code, Eye, MoreHorizontal, RefreshCw, Download, WrapText, UserRound, Zap, FileCode } from "@/lib/icons";
+import { downloadFile } from "@/lib/file-download";
+import { EDITOR_LANGUAGES } from "./editor-language-picker";
+import {
+  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem,
+  DropdownMenuCheckboxItem, DropdownMenuSeparator, DropdownMenuSub,
+  DropdownMenuSubTrigger, DropdownMenuSubContent, DropdownMenuRadioGroup, DropdownMenuRadioItem,
+} from "@/components/ui/dropdown-menu";
+
+interface Props {
+  mode: "edit" | "preview";
+  onModeChange: (mode: "edit" | "preview") => void;
+  onRefresh: () => void;
+  onReloadCode: () => void;
+  refreshing: boolean;
+  unsaved: boolean;
+  breadcrumb?: ReactNode;
+  filePath: string;
+  projectName?: string;
+  wordWrap: boolean;
+  onToggleWordWrap: () => void;
+  inlineBlame: boolean;
+  onToggleInlineBlame?: () => void;
+  language: string;
+  onLanguageChange: (language: string) => void;
+  lspEnabled: boolean;
+  onToggleLsp?: (enabled: boolean) => void;
+}
+
+const actionClass = "flex items-center justify-center gap-1.5 rounded px-2 min-h-11 min-w-11 md:min-h-7 md:min-w-7 text-xs text-muted-foreground hover:text-foreground hover:bg-muted";
+// Keep action icons near the edge; checked states occupy the trailing slot.
+const menuClass = "min-h-11 md:min-h-8 px-2";
+const checkboxClass = `${menuClass} pr-8 [&>span]:left-auto [&>span]:right-2`;
+
+/** One row shared by code and preview; auxiliary editor actions live in the menu. */
+export function HtmlPreviewToolbar(props: Props) {
+  const { mode, onModeChange, onRefresh, unsaved, breadcrumb } = props;
+  return (
+    <div className="flex items-center gap-2 md:gap-1 border-b border-border bg-background px-2 shrink-0 h-12 md:h-8"
+      role="toolbar" aria-label="HTML preview">
+      <div className="hidden md:flex flex-1 min-w-0 overflow-hidden">{breadcrumb}</div>
+      {mode === "preview" && (
+        <button type="button" onClick={onRefresh} title="Reload the original HTML file" aria-label="Refresh preview" className={actionClass}>
+          <RefreshCw className="size-4" />
+        </button>
+      )}
+      {([["edit", "Code", Code], ["preview", "Preview", Eye]] as const).map(([value, label, Icon]) => (
+        <button key={value} type="button" aria-pressed={mode === value} onClick={() => onModeChange(value)}
+          className={`${actionClass} ${mode === value ? "bg-muted text-foreground" : ""}`}>
+          <Icon className="size-3.5" />{label}
+        </button>
+      ))}
+      {unsaved && <span role="status" title="Preview uses the saved file" aria-label="Preview uses the saved file" className="text-amber-500 text-xs">●</span>}
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <button type="button" title="More HTML actions" aria-label="More HTML actions" className={`${actionClass} ml-auto md:ml-0`}>
+            <MoreHorizontal className="size-4" />
+          </button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end" className="w-52">
+          {mode === "edit" && <DropdownMenuItem className={menuClass} disabled={unsaved || props.refreshing} onSelect={props.onReloadCode}><RefreshCw />Reload code from disk</DropdownMenuItem>}
+          <DropdownMenuItem className={menuClass} onSelect={() => void downloadFile(props.projectName ?? "", props.filePath)}><Download />Download</DropdownMenuItem>
+          <DropdownMenuSeparator />
+          <DropdownMenuCheckboxItem className={checkboxClass} checked={props.wordWrap} onCheckedChange={props.onToggleWordWrap}><WrapText className="size-4 text-muted-foreground" />Word wrap</DropdownMenuCheckboxItem>
+          {props.onToggleInlineBlame && <DropdownMenuCheckboxItem className={checkboxClass} checked={props.inlineBlame} onCheckedChange={props.onToggleInlineBlame}><UserRound className="size-4 text-muted-foreground" />Inline blame</DropdownMenuCheckboxItem>}
+          {props.onToggleLsp && <DropdownMenuCheckboxItem className={checkboxClass} checked={props.lspEnabled} onCheckedChange={props.onToggleLsp}><Zap className="size-4 text-muted-foreground" />Language server</DropdownMenuCheckboxItem>}
+          <DropdownMenuSub>
+            <DropdownMenuSubTrigger className={`${menuClass} gap-2`}><FileCode className="size-4 text-muted-foreground" />Editor language</DropdownMenuSubTrigger>
+            <DropdownMenuSubContent className="max-h-80 overflow-y-auto">
+              <DropdownMenuRadioGroup value={props.language} onValueChange={props.onLanguageChange}>
+                {EDITOR_LANGUAGES.map((language) => <DropdownMenuRadioItem key={language.id} className="min-h-11 md:min-h-8" value={language.id}>{language.label}</DropdownMenuRadioItem>)}
+              </DropdownMenuRadioGroup>
+            </DropdownMenuSubContent>
+          </DropdownMenuSub>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  );
+}

package/src/web/components/editor/html-preview.tsx

@@ -0,0 +1,30 @@
+import { useEffect, useState } from "react";
+import { api } from "@/lib/api-client";
+import { Loader2 } from "@/lib/icons";
+
+/** The server also enforces the sandbox, including when a preview URL is opened directly. */
+export function HtmlPreview({ filePath, projectName, revision }: {
+  filePath: string;
+  projectName?: string;
+  revision: number;
+}) {
+  const [url, setUrl] = useState<string>();
+  const [error, setError] = useState<string>();
+  useEffect(() => {
+    const controller = new AbortController();
+    setUrl(undefined);
+    setError(undefined);
+    const timeout = setTimeout(() => controller.abort(new Error("Preview request timed out. Try Refresh.")), 30_000);
+    let active = true;
+    api.post<{ url: string }>("/api/html-preview", { filePath, projectName }, { signal: controller.signal })
+      .then((data) => { if (active) setUrl(data.url); })
+      .catch((reason: unknown) => { if (active) setError(reason instanceof Error ? reason.message : "Could not open HTML preview"); })
+      .finally(() => clearTimeout(timeout));
+    return () => { active = false; clearTimeout(timeout); controller.abort(); };
+  }, [filePath, projectName, revision]);
+
+  if (error) return <div role="alert" className="p-4 text-sm text-destructive">{error}. Use Refresh to retry.</div>;
+  if (!url) return <div role="status" className="flex flex-1 items-center justify-center gap-2 text-sm text-muted-foreground"><Loader2 className="size-5 animate-spin" />Loading preview…</div>;
+  return <iframe title="HTML preview" src={url} sandbox="allow-scripts" referrerPolicy="no-referrer"
+    className="flex-1 min-h-0 w-full border-0 bg-white" />;
+}

package/src/web/components/explorer/search-panel.tsx

@@ -6,6 +6,7 @@ import { useTabStore } from "@/stores/tab-store";
 import { projectUrl, api } from "@/lib/api-client";
 import { cn } from "@/lib/utils";
 import { FileIcon } from "@/lib/file-icons";
+import { emitOnboardingEvidence } from "@/lib/onboarding/onboarding-types";
 
 interface SearchMatch {
   lineNum: number;
@@ -63,7 +64,7 @@ function OptionButton({ active, onClick, title, children }: { active: boolean; o
   );
 }
 
-export function SearchPanel() {
+export function SearchPanel({ onNavigate }: { onNavigate?: () => void } = {}) {
   const { activeProject } = useProjectStore(useShallow((s) => ({ activeProject: s.activeProject })));
   const openTab = useTabStore((s) => s.openTab);
 
@@ -82,8 +83,25 @@ export function SearchPanel() {
   const [collapsed, setCollapsed] = useState<Set<string>>(new Set());
   const inputRef = useRef<HTMLInputElement>(null);
   const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const requestId = useRef(0);
+  const [searchError, setSearchError] = useState<string | null>(null);
+  const [searched, setSearched] = useState(false);
+  // Invalidate synchronously during render, including the debounce gap.
+  const signature = JSON.stringify([activeProject?.name, query, caseSensitive, wholeWord, useRegex, filesFilter]);
+  const currentSignature = useRef(signature);
+  if (currentSignature.current !== signature) {
+    currentSignature.current = signature;
+    requestId.current++;
+  }
 
   const doSearch = useCallback(async (q: string, cs: boolean, ww: boolean, rx: boolean, ff: string) => {
+    const id = ++requestId.current;
+    setSearchError(null);
+    setSearched(false);
+    setLoading(false);
+    setResults([]);
+    setTotal(0);
     setRegexError(false);
     if (!activeProject || (!rx && q.length < 2) || (rx && q.length < 1)) {
       setResults([]);
@@ -100,19 +118,30 @@ export function SearchPanel() {
       const data = await api.get<{ results: SearchResult[]; total: number }>(
         `${projectUrl(activeProject.name)}/files/search?${params}`
       );
+      if (id !== requestId.current) return;
       setResults(data.results);
       setTotal(data.total);
-    } catch {
+      setSearched(true);
+      const visible = !!panelRef.current?.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true });
+      if (visible) emitOnboardingEvidence({ type: "search-succeeded", projectName: activeProject.name, requestId: String(id), visible });
+    } catch (error) {
+      if (id !== requestId.current) return;
       setResults([]);
+      setSearchError(error instanceof Error ? error.message : "Unable to search this project.");
     } finally {
-      setLoading(false);
+      if (id === requestId.current) setLoading(false);
     }
   }, [activeProject]);
 
   useEffect(() => {
     if (debounceRef.current) clearTimeout(debounceRef.current);
+    setSearched(false);
+    setSearchError(null);
+    setResults([]);
+    setTotal(0);
+    setLoading(false);
     debounceRef.current = setTimeout(() => doSearch(query, caseSensitive, wholeWord, useRegex, filesFilter), 300);
-    return () => { if (debounceRef.current) clearTimeout(debounceRef.current); };
+    return () => { requestId.current++; if (debounceRef.current) clearTimeout(debounceRef.current); };
   }, [query, caseSensitive, wholeWord, useRegex, filesFilter, doSearch]);
 
   useEffect(() => { inputRef.current?.focus(); }, []);
@@ -129,6 +158,7 @@ export function SearchPanel() {
       projectId: activeProject.name,
       closable: true,
     });
+    onNavigate?.();
   }
 
   function toggleCollapse(file: string) {
@@ -169,7 +199,7 @@ export function SearchPanel() {
   }
 
   return (
-    <div className="flex flex-col h-full">
+    <div ref={panelRef} data-onboarding="search" className="flex flex-col h-full">
       {/* Search input + options */}
       <div className="p-2 border-b border-border space-y-1.5">
         {/* Search row */}
@@ -265,7 +295,8 @@ export function SearchPanel() {
           {!loading && !replacing && replaceCount !== null && (
             <span className="text-success">{replaceCount} replacement{replaceCount !== 1 ? "s" : ""} made</span>
           )}
-          {!loading && !replacing && replaceCount === null && !regexError && query.length >= 2 && results.length === 0 && <span>No results</span>}
+          {searchError && <span role="alert" className="text-destructive">Search failed: {searchError} <button className="underline" onClick={() => void doSearch(query, caseSensitive, wholeWord, useRegex, filesFilter)}>Retry search</button></span>}
+          {!loading && !replacing && !searchError && searched && replaceCount === null && !regexError && results.length === 0 && <span>No results</span>}
           {!loading && !replacing && replaceCount === null && total > 0 && (
             <span>{total} result{total !== 1 ? "s" : ""} in {results.length} file{results.length !== 1 ? "s" : ""}</span>
           )}

package/src/web/components/git/git-status-panel.tsx

@@ -1,4 +1,5 @@
-import { useEffect, useState, useCallback, useMemo } from "react";
+import { useEffect, useState, useCallback, useMemo, useRef } from "react";
+import { emitOnboardingEvidence } from "@/lib/onboarding/onboarding-types";
 import {
   Plus,
   Minus,
@@ -134,6 +135,29 @@ export function GitStatusPanel({ metadata, tabId, onNavigate }: GitStatusPanelPr
   // whose children are. This resolves which one every call below talks to.
   const gitRepo = useGitRepo(projectName);
   const gitRoot = gitRepo.repo?.path ?? activeProjectPath;
+  const panelRef = useRef<HTMLDivElement>(null);
+  const requestId = useRef(0);
+  const repoKey = `${projectName}:${gitRepo.repo?.path ?? ""}`;
+  const currentRepoKey = useRef(repoKey);
+  if (currentRepoKey.current !== repoKey) {
+    currentRepoKey.current = repoKey;
+    requestId.current++;
+  }
+  const [loadedRepoKey, setLoadedRepoKey] = useState<string | null>(null);
+  const activeProjectName = useProjectStore((s) => s.activeProject?.name);
+  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 || projectName !== activeProjectName || (tabId && tabId !== activeTabId) ||
+      !gitRepo.repo || loading || error || !status || loadedRepoKey !== repoKey) return;
+    const visible = !!panelRef.current?.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true });
+    if (visible) emitOnboardingEvidence({ type: "git-ready", projectName, visible });
+  }, [onboardingRefresh, projectName, activeProjectName, tabId, activeTabId, gitRepo.repo, loading, error, status, loadedRepoKey, repoKey]);
   // Git Graph extension is available when it has registered its command.
   const gitGraphAvailable = useExtensionStore(
     (s) => s.contributions?.commands?.some((c) => c.command === "git-graph.view") ?? false,
@@ -143,12 +167,15 @@ export function GitStatusPanel({ metadata, tabId, onNavigate }: GitStatusPanelPr
     // No repository resolved yet: the panel is showing the picker, and asking
     // git in the container folder is what produced the error this replaced.
     if (!projectName || !gitRepo.repo) return;
+    const id = ++requestId.current;
     try {
       setLoading(true);
       const data = await api.get<GitStatus>(
         gitRepo.gitUrl("/status"),
       );
+      if (id !== requestId.current) return;
       setStatus(data);
+      setLoadedRepoKey(`${projectName}:${gitRepo.repo.path}`);
       setGitChangesCount(
         projectName,
         data.staged.length + data.unstaged.length + data.untracked.length,
@@ -156,9 +183,10 @@ export function GitStatusPanel({ metadata, tabId, onNavigate }: GitStatusPanelPr
       useGitStatusStore.getState().setMeta(projectName, data);
       setError(null);
     } catch (e) {
+      if (id !== requestId.current) return;
       setError(e instanceof Error ? e.message : "Failed to fetch status");
     } finally {
-      setLoading(false);
+      if (id === requestId.current) setLoading(false);
     }
   }, [projectName, gitRepo, setGitChangesCount]);
 
@@ -166,7 +194,7 @@ export function GitStatusPanel({ metadata, tabId, onNavigate }: GitStatusPanelPr
     fetchStatus();
     // Auto-reload every 5 seconds
     const interval = setInterval(fetchStatus, 5000);
-    return () => clearInterval(interval);
+    return () => { requestId.current++; clearInterval(interval); };
   }, [fetchStatus]);
 
   const stageFiles = async (files: string[]) => {
@@ -460,7 +488,7 @@ export function GitStatusPanel({ metadata, tabId, onNavigate }: GitStatusPanelPr
   );
 
   return (
-    <div className="flex flex-col h-full overflow-hidden">
+    <div ref={panelRef} data-onboarding="git" className="flex flex-col h-full overflow-hidden">
       <SidebarHeader icon={GitBranch} title={status?.current ? `On: ${status.current}` : "Source Control"}>
         <Button
           variant={viewMode === "flat" ? "secondary" : "ghost"}

package/src/web/components/layout/mobile-drawer.tsx

@@ -5,6 +5,7 @@ import { useProjectStore } from "@/stores/project-store";
 import { useSettingsStore, type SidebarActiveTab } from "@/stores/settings-store";
 import { useExtensionStore } from "@/stores/extension-store";
 import { FileTree } from "@/components/explorer/file-tree";
+import { SearchPanel } from "@/components/explorer/search-panel";
 import { GitStatusPanel } from "@/components/git/git-status-panel";
 import { DatabaseSidebar } from "@/components/database/database-sidebar";
 import { JiraPanel } from "@/components/jira/jira-panel";
@@ -29,10 +30,10 @@ import { FeatureBadge } from "@/components/ui/feature-badge";
 import type { FeatureBadgeId } from "@/lib/feature-badges";
 import { cn } from "@/lib/utils";
 
-// Tab ids the mobile drawer can render content for. `search` is desktop-only for now;
+// Tab ids the mobile drawer can render content for;
 // ext views are supported via the `ext:` prefix.
 const MOBILE_SUPPORTED = new Set<string>([
-  "history", "teams", "explorer", "git", "database", "tunnels", "ai-resources", "jira",
+  "history", "teams", "explorer", "search", "git", "database", "tunnels", "ai-resources", "jira",
 ]);
 const isMobileSupported = (id: SidebarActiveTab) => MOBILE_SUPPORTED.has(id) || id.startsWith("ext:");
 
@@ -137,13 +138,14 @@ export function MobileDrawer({ isOpen, onClose, initialTab }: MobileDrawerProps)
         </div>
 
         {/* Tab content — scrollable */}
-        <div className="flex-1 overflow-y-auto min-h-0">
+        <div data-onboarding={isOpen ? activeTab : undefined} className="flex-1 overflow-y-auto min-h-0">
           {activeTab === "history" && (activeProject
             ? <SessionHistoryList variant="sidebar" projectName={activeProject.name} onNavigate={onClose} />
             : noProject)}
           {activeTab === "teams" && (activeProject ? <GroupList /> : noProject)}
           {activeTab === "explorer" && (activeProject ? <FileTree onFileOpen={onClose} /> : noProject)}
-          {activeTab === "git" && <GitStatusPanel metadata={{ projectName: activeProject?.name }} onNavigate={onClose} />}
+          {isOpen && activeTab === "search" && <SearchPanel onNavigate={onClose} />}
+          {isOpen && activeTab === "git" && <GitStatusPanel metadata={{ projectName: activeProject?.name }} onNavigate={onClose} />}
           {activeTab === "database" && <DatabaseSidebar />}
           {activeTab === "tunnels" && <TunnelManagerTab />}
           {activeTab === "jira" && <JiraPanel />}

package/src/web/components/layout/project-switcher.tsx

@@ -206,6 +206,7 @@ export const ProjectSwitcher = memo(function ProjectSwitcher() {
       <input ref={fileInputRef} type="file" accept="image/*" className="hidden" onChange={onFilePicked} />
       <button
         ref={btnRef}
+        data-onboarding="project"
         onClick={toggleFlyout}
         title="Switch project"
         className={cn(

package/src/web/components/layout/sidebar.tsx

@@ -108,7 +108,7 @@ export const Sidebar = memo(function Sidebar() {
 
         <div className="flex-1 min-w-0 flex flex-col">
           {/* Panel content */}
-          <div className="flex-1 overflow-y-auto min-h-0">
+          <div className="flex-1 overflow-y-auto min-h-0" data-onboarding={sidebarActiveTab === "explorer" ? "explorer" : undefined}>
             {sidebarActiveTab === "explorer" && (
               activeProject ? (
                 <FileTree />

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

@@ -0,0 +1,15 @@
+import { Sparkles } from "@/lib/icons";
+import { Button } from "@/components/ui/button";
+import { useOnboardingStore } from "@/stores/onboarding-store";
+import { useProjectStore } from "@/stores/project-store";
+import { openQuickOrientation } from "./onboarding-quick-orientation";
+
+/** Reopening guidance never changes the workspace or the user's drafts. */
+export function OnboardingEntry({ compact = false }: { compact?: boolean }) {
+  const state = useOnboardingStore();
+  const projectName = useProjectStore((s) => s.activeProject?.name);
+  const canResume = state.goal && state.familiarity && state.status !== "finished";
+  return <div className={compact ? "flex flex-wrap items-center gap-2" : "grid gap-2"}><Button variant="outline" className={compact ? "min-h-11" : "min-h-11 w-full"}
+    onClick={() => canResume ? state.resume(projectName) : state.status === "finished" ? state.replay() : state.begin()}><Sparkles className="size-4" />{canResume ? "Resume guided tour" : state.status === "unseen" ? "Get started with PPM" : "Open guided tour"}</Button>
+    <Button variant="link" className="min-h-11" onClick={openQuickOrientation}>Quick orientation</Button></div>;
+}

package/src/web/components/onboarding/onboarding-file-help.tsx

@@ -0,0 +1,31 @@
+import { useEffect, useState } from "react";
+import { api, projectUrl } from "@/lib/api-client";
+import { Button } from "@/components/ui/button";
+import { useOnboardingStore } from "@/stores/onboarding-store";
+import type { FileDirEntry } from "../../../types/project";
+
+export function OnboardingFileHelp() {
+  const projectName = useOnboardingStore((state) => state.projectName);
+  const skip = useOnboardingStore((state) => state.skip);
+  const [empty, setEmpty] = useState(false);
+  useEffect(() => {
+    let cancelled = false;
+    let requestId = 0;
+    setEmpty(false);
+    if (!projectName) return;
+    const check = () => {
+      const id = ++requestId;
+      void api.get<FileDirEntry[]>(`${projectUrl(projectName)}/files/list`).then((entries) => {
+        if (!cancelled && id === requestId) setEmpty(entries.length === 0);
+      }).catch(() => { if (!cancelled && id === requestId) setEmpty(false); });
+    };
+    check();
+    window.addEventListener("ppm:onboarding-refresh", check);
+    return () => { cancelled = true; window.removeEventListener("ppm:onboarding-refresh", check); };
+  }, [projectName]);
+  return empty ? <div className="mt-3 rounded-lg border border-border p-3" role="status">
+    <p className="text-sm text-text-secondary">No files are visible in this project yet. You can create your own files later or choose another project. Nothing needs to be created for this tour.</p>
+    <Button variant="outline" className="w-full min-h-11 mt-2" onClick={skip}>Skip empty project step</Button>
+    <p className="text-xs text-text-secondary mt-2">This step will be marked skipped, not completed.</p>
+  </div> : <p className="text-xs text-text-secondary mt-2">Choose any text file, such as .txt, .js, .py or .md. No README or package.json is required. Markdown Preview counts too. If there is no readable file, use Skip step.</p>;
+}

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

@@ -0,0 +1,45 @@
+import { useState } from "react";
+import { Check, ChevronDown, ChevronUp, X } from "@/lib/icons";
+import { Button } from "@/components/ui/button";
+import { useOnboardingStore } from "@/stores/onboarding-store";
+import { getOnboardingCopy } from "@/lib/onboarding/onboarding-copy";
+import { getOnboardingSteps } from "@/lib/onboarding/onboarding-steps";
+import type { OnboardingStepId } from "@/lib/onboarding/onboarding-types";
+import { openQuickOrientation } from "./onboarding-quick-orientation";
+import { OnboardingFileHelp } from "./onboarding-file-help";
+
+export function OnboardingGuide({ collapsed, setCollapsed, onAction, onSettings }: {
+  collapsed: boolean; setCollapsed: (value: boolean) => void; onAction: (step: OnboardingStepId) => void; onSettings: () => void;
+}) {
+  const state = useOnboardingStore();
+  const [more, setMore] = useState(false);
+  const steps = getOnboardingSteps(state.goal);
+  const step = state.currentStep;
+  if (!step) return null;
+  const copy = getOnboardingCopy(step, state.familiarity ?? "beginner");
+  const index = steps.indexOf(step);
+  return <div className="p-4">
+    <div className="flex items-center gap-2">
+      <div className="flex-1 min-w-0"><p className="text-[11px] uppercase tracking-widest text-primary font-medium">Guided tour · {index + 1} of {steps.length}</p><h2 className="font-semibold text-sm mt-1" aria-live="polite">{copy.title}</h2></div>
+      <Button variant="ghost" className="min-h-11 min-w-11" aria-label={collapsed ? "Expand guide" : "Collapse guide"} onClick={() => setCollapsed(!collapsed)}>{collapsed ? <ChevronUp /> : <ChevronDown />}</Button>
+      <Button variant="ghost" className="min-h-11 min-w-11" aria-label="Pause tour" onClick={state.pause}><X /></Button>
+    </div>
+    {!collapsed && <>
+      <div className="flex gap-1 mt-3 mb-4" aria-label="Tour progress">{steps.map((id) => <span key={id} className={`h-1 flex-1 rounded-full ${state.completed.includes(id) ? "bg-primary" : state.skipped.includes(id) ? "bg-text-subtle" : "bg-border"}`} />)}</div>
+      <p className="text-sm text-text-secondary leading-relaxed">{copy.body}</p>
+      {step === "file" && <OnboardingFileHelp />}
+      {step === "run" && <p className="text-xs text-text-secondary mt-2">Open README directly, or package.json if no README is available. README Preview counts too.</p>}
+      {step === "run" && state.runDocumentReady && <p className="text-sm text-primary mt-2 flex items-center gap-1"><Check className="size-4" />Run instructions opened</p>}
+      <Button className="w-full mt-4 min-h-11" onClick={() => onAction(step)}>{step === "run" && state.runDocumentReady ? "I know where to run commands" : copy.action}</Button>
+      {(step === "chat" || step === "send") && <Button variant="ghost" className="w-full min-h-11 mt-1" onClick={onSettings}>AI settings</Button>}
+      <button className="text-xs text-primary py-3 min-h-11" onClick={() => setMore(!more)} aria-expanded={more}>{more ? "Less explanation" : "Explain this step"}</button>
+      {more && <p className="text-sm text-text-secondary leading-relaxed mb-3">{copy.more}</p>}
+      <Button variant="link" className="w-full min-h-11" onClick={openQuickOrientation}>Quick orientation</Button>
+      <div className="flex items-center justify-between border-t border-border pt-2">
+        <Button variant="ghost" className="min-h-11 px-2" disabled={index === 0} onClick={state.back}>Back</Button>
+        <Button variant="ghost" className="min-h-11 px-2" onClick={state.changeChoices}>Change guide</Button>
+        <Button variant="ghost" className="min-h-11 px-2" onClick={state.skip}>Skip step</Button>
+      </div>
+    </>}
+  </div>;
+}