@hienlh/ppm 0.22.1 → 0.22.3

package/src/web/components/chat/message-input.tsx

@@ -1,3 +1,4 @@
+import { usePanelStore } from "@/stores/panel-store";
 import { useState, useRef, useCallback, useEffect, memo, type KeyboardEvent, type DragEvent, type ClipboardEvent } from "react";
 import { ArrowUp, Square, Paperclip, Loader2, Mic, MicOff, Zap, ListOrdered, Clock, Bot, X } from "@/lib/icons";
 import { useVoiceInput } from "@/hooks/use-voice-input";
@@ -68,6 +69,7 @@ export interface ChatAttachment {
 export type MessagePriority = 'now' | 'next' | 'later';
 
 interface MessageInputProps {
+  draftReady?: boolean;
   /** Tab id of the owning chat tab — addresses "Send to Chat" at this tab only. */
   tabId?: string;
   onSend: (content: string, attachments: ChatAttachment[], priority?: MessagePriority) => void;
@@ -95,6 +97,13 @@ interface MessageInputProps {
   initialValue?: string;
   /** Bumping this counter clears the textarea (e.g. parent cancels an edit). */
   clearSignal?: number;
+  /**
+   * A message that could not be sent, handed back. A fresh `nonce` applies it even
+   * when `text` equals the last one — `initialValue` cannot do this, because it only
+   * reacts to a *changed* value, and the text of a failed send is often exactly the
+   * draft the composer was already prefilled with.
+   */
+  restore?: { text: string; nonce: number } | null;
   /** Called on content change for draft auto-save */
   onContentChange?: (content: string, attachments?: Array<{ name: string; path: string }>) => void;
   /** Returns this session's user messages, oldest first — powers ArrowUp/Down recall */
@@ -128,6 +137,7 @@ interface MessageInputProps {
 
 export const MessageInput = memo(function MessageInput({
   tabId,
+  draftReady = true,
   onSend,
   isStreaming,
   onCancel,
@@ -144,6 +154,7 @@ export const MessageInput = memo(function MessageInput({
   onExternalPathsConsumed,
   initialValue,
   clearSignal,
+  restore,
   onContentChange,
   getUserHistory,
   autoFocus,
@@ -312,11 +323,46 @@ export const MessageInput = memo(function MessageInput({
     }
   }, [initialValue]); // eslint-disable-line react-hooks/exhaustive-deps
 
+  // A tour suggestion is an explicit user action. Hydrated or typed drafts always win.
+  useEffect(() => {
+    const suggest = (event: Event) => {
+      const detail = (event as CustomEvent).detail;
+      if (!draftReady || disabled || isStreaming || valueRef.current || attachments.length || agentTag || !tabId) return;
+      if (detail?.projectName !== projectName || (detail.tabId && detail.tabId !== tabId) || typeof detail.text !== "string") return;
+      const panels = usePanelStore.getState();
+      const active = detail.tabId
+        ? Object.values(panels.panels).some((panel) => panel.activeTabId === tabId)
+        : panels.panels[panels.focusedPanelId]?.activeTabId === tabId;
+      if (!active || document.hidden) return;
+      writeTextareas(detail.text);
+      onContentChange?.(detail.text);
+      getVisibleTextarea()?.focus();
+    };
+    window.addEventListener("ppm:onboarding-prompt", suggest);
+    return () => window.removeEventListener("ppm:onboarding-prompt", suggest);
+  }, [draftReady, disabled, isStreaming, attachments.length, agentTag, tabId, projectName, onContentChange, writeTextareas, getVisibleTextarea]);
+
   // Parent-driven clear (e.g. cancelling an edit) — skip initial mount (0).
   useEffect(() => {
     if (clearSignal) writeTextareas("");
   }, [clearSignal]); // eslint-disable-line react-hooks/exhaustive-deps
 
+  // An unsent message coming back. The send can fail up to ~45 s after Enter, by which
+  // time the user may be typing something new — so the text goes AFTER what is there
+  // rather than over it. Reported as a content change so it is saved as the draft
+  // again; `writeTextareas` alone tells nobody.
+  useEffect(() => {
+    if (!restore?.nonce || !restore.text) return;
+    const current = valueRef.current;
+    const next = current.trim() ? `${current}\n\n${restore.text}` : restore.text;
+    writeTextareas(next);
+    onContentChange?.(next, attachments.filter((a) => a.status === "ready" && a.serverPath).map((a) => ({ name: a.name, path: a.serverPath! })));
+    setTimeout(() => {
+      const ta = getVisibleTextarea();
+      if (ta) { ta.focus(); ta.selectionStart = ta.selectionEnd = ta.value.length; }
+    }, 50);
+  }, [restore?.nonce]); // eslint-disable-line react-hooks/exhaustive-deps
+
   // Auto-focus on mount when requested
   useEffect(() => {
     if (!autoFocus) return;
@@ -826,7 +872,7 @@ export const MessageInput = memo(function MessageInput({
   const showCancel = isStreaming && !hasContent;
 
   return (
-    <div className="p-2 md:p-3">
+    <div data-onboarding="chat-input" className="p-2 md:p-3">
       {/* Rounded input container */}
       <div
         className="border border-border rounded-[var(--rad)] bg-panel shadow-[var(--shadow-float)] cursor-text"

package/src/web/components/chat/model-thinking-selector.tsx

@@ -10,6 +10,10 @@ interface ModelOption {
   label: string;
 }
 
+// Shared by chat tabs; keep successful lists visible while refreshing an old entry.
+const modelCache = new Map<string, { models: ModelOption[]; expiry: number }>();
+const MODEL_CACHE_TTL = 5 * 60 * 1000;
+
 interface ModelThinkingSelectorProps {
   model: string | null;
   effort: string | null;
@@ -46,18 +50,44 @@ export function ModelThinkingSelector({
   providerId,
   disabled,
 }: ModelThinkingSelectorProps) {
-  const [models, setModels] = useState<ModelOption[]>([]);
+  const cacheKey = JSON.stringify([projectName, providerId]);
+  const cached = modelCache.get(cacheKey);
+  const [modelResult, setModelResult] = useState<{
+    projectName: string;
+    providerId: string;
+    models: ModelOption[];
+    error?: boolean;
+  } | null>(null);
+  // Never render another provider/project's options, even before effects run.
+  const result = modelResult?.projectName === projectName && modelResult.providerId === providerId
+    ? modelResult : cached ? { ...cached, error: false } : null;
+  const models = result?.models ?? [];
+  const loading = Boolean(projectName && providerId && !result);
+  const modelStatus = loading ? "Loading models..." : result?.error
+    ? "Unable to load models" : models.length === 0 ? "No models available" : null;
   const [open, setOpen] = useState(false);
   const panelRef = useRef<HTMLDivElement>(null);
   const isMobile = useIsMobile();
 
   useEffect(() => {
+    let active = true;
+    setModelResult(null);
     if (!projectName || !providerId) return;
+    const entry = modelCache.get(cacheKey);
+    if (entry && Date.now() < entry.expiry) return;
     api
       .get<ModelOption[]>(`${projectUrl(projectName)}/chat/providers/${providerId}/models`)
-      .then(setModels)
-      .catch(() => {});
-  }, [projectName, providerId]);
+      .then((models) => {
+        // The backend also returns [] on discovery failure. Don't replace a usable list.
+        const usable = models.length > 0 ? models : entry?.models ?? models;
+        if (active && models.length > 0) modelCache.set(cacheKey, { models, expiry: Date.now() + MODEL_CACHE_TTL });
+        if (active) setModelResult({ projectName, providerId, models: usable });
+      })
+      .catch(() => {
+        if (active) setModelResult({ projectName, providerId, models: entry?.models ?? [], error: !entry });
+      });
+    return () => { active = false; };
+  }, [projectName, providerId, cacheKey]);
 
   useEffect(() => {
     if (disabled) setOpen(false);
@@ -77,9 +107,9 @@ export function ModelThinkingSelector({
   }, [open, isMobile]);
 
   const current = models.find((m) => m.value === model);
-  const modelDisplay = current ? shortLabel(current.label) : model ? shortLabel(model) : "Model";
+  const modelDisplay = loading ? "Loading models..." : current ? shortLabel(current.label) : "Model";
   const effortValue = effort ?? DEFAULT_EFFORT;
-  const showModelList = models.length > 1;
+  const showModelList = models.length > 0 || Boolean(modelStatus);
   const chipText = chipLabel(modelDisplay, effortValue);
 
   const pick = (fn: () => void) => {
@@ -93,6 +123,7 @@ export function ModelThinkingSelector({
       {showModelList && (
         <div className="flex-1 min-w-0 py-1">
           <SectionLabel>Model</SectionLabel>
+          {modelStatus && <div role="status" className="px-3 py-2 text-xs text-text-secondary">{modelStatus}</div>}
           {models.map((m) => (
             <OptionRow key={m.value} active={m.value === model} onClick={() => pick(() => onModelChange(m.value))}>
               <span className="flex-1 truncate">{shortLabel(m.label)}</span>

package/src/web/components/chat/new-chat-provider-gate.tsx

@@ -0,0 +1,68 @@
+import { useEffect, useState, type ReactNode } from "react";
+import { getAISettings, type AISettings } from "@/lib/api-settings";
+import { api, projectUrl } from "@/lib/api-client";
+import { resolveNewChatProvider } from "@/lib/new-chat-provider";
+import { usePanelStore } from "@/stores/panel-store";
+
+/** Do not mount chat (or claim an account) until its initial provider is known. */
+export function NewChatProviderGate({ tabId, metadata, children }: {
+  tabId: string;
+  metadata: Record<string, unknown>;
+  children: ReactNode;
+}) {
+  const [error, setError] = useState(false);
+  const [attempt, setAttempt] = useState(0);
+  const [unavailable, setUnavailable] = useState<{
+    provider: string; settings: AISettings; alternatives: Array<{ id: string; name: string }>;
+  } | null>(null);
+  const pending = metadata.providerPending === true;
+  const source = metadata.focusedProviderOnOpen as string | undefined;
+  const projectName = metadata.projectName as string | undefined;
+
+  function selectProvider(providerId: string, settings: AISettings) {
+    const store = usePanelStore.getState();
+    const tab = store.getPanelForTab(tabId)?.tabs.find((t) => t.id === tabId);
+    if (!tab?.metadata?.providerPending) return;
+    store.updateTab(tabId, { metadata: {
+      ...tab.metadata,
+      providerId,
+      providerPending: undefined,
+      focusedProviderOnOpen: undefined,
+      permissionMode: tab.metadata.permissionMode ?? settings.providers[providerId]?.permission_mode ?? "bypassPermissions",
+    } });
+  }
+
+  useEffect(() => {
+    if (!pending) return;
+    let cancelled = false;
+    setError(false);
+    setUnavailable(null);
+    Promise.all([
+      getAISettings(),
+      projectName ? api.get<Array<{ id: string; name: string }>>(`${projectUrl(projectName)}/chat/providers`) : Promise.resolve(null),
+    ]).then(([settings, providers]) => {
+      if (cancelled) return;
+      const providerId = resolveNewChatProvider(settings, source);
+      if (providers && !providers.some((p) => p.id === providerId)) {
+        setUnavailable({ provider: providerId, settings, alternatives: providers });
+        return;
+      }
+      selectProvider(providerId, settings);
+    }).catch(() => { if (!cancelled) setError(true); });
+    return () => { cancelled = true; };
+  }, [pending, source, projectName, tabId, attempt]);
+
+  if (!pending) return children;
+  if (unavailable) return <div className="flex h-full flex-col items-center justify-center gap-3 p-4 text-sm text-muted-foreground" role="status">
+    <p>{unavailable.provider} is not available. Choose a provider for this chat.</p>
+    {unavailable.alternatives.map((p) => <button key={p.id} className="text-primary underline"
+      onClick={() => selectProvider(p.id, unavailable.settings)}>Use {p.name}</button>)}
+    <button className="text-primary underline" onClick={() => setAttempt((n) => n + 1)}>Check again</button>
+  </div>;
+  return <div className="flex h-full items-center justify-center gap-2 text-sm text-muted-foreground" role="status">
+    {error ? <>
+      Could not load chat settings.
+      <button className="text-primary underline" onClick={() => setAttempt((n) => n + 1)}>Retry</button>
+    </> : "Preparing chat…"}
+  </div>;
+}

package/src/web/components/chat/session-list-panel.tsx

@@ -8,7 +8,7 @@ import { SessionContextMenu } from "./session-context-menu";
 import { ProviderBadge } from "./provider-selector";
 import { useNotificationStore, notificationTint } from "@/stores/notification-store";
 import { cn } from "@/lib/utils";
-import type { SessionInfo, ProjectTag } from "../../../types/chat";
+import { compareSessionsByActivity, type SessionInfo, type ProjectTag } from "../../../types/chat";
 
 const MAX_RECENT_SESSIONS = 5;
 const FETCH_SESSIONS_LIMIT = 20;
@@ -62,11 +62,7 @@ export function SessionListPanel({ projectName, onSelectSession, className }: Se
       }
       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 {
       // silently ignore

package/src/web/components/chat/session-picker.tsx

@@ -3,7 +3,7 @@ import { api, projectUrl } from "@/lib/api-client";
 import { Plus, Trash2, MessageSquare, ChevronDown, Pin, PinOff, Search, X } from "@/lib/icons";
 import { useDebouncedValue } from "@/hooks/use-debounced-value";
 import { ProviderBadge } from "./provider-selector";
-import type { SessionInfo } from "../../../types/chat";
+import { compareSessionsByActivity, type SessionInfo } from "../../../types/chat";
 
 interface SessionPickerProps {
   currentSessionId: string | null;
@@ -81,11 +81,7 @@ export function SessionPicker({
       }
       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 {
       // Silently fail

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" />;
+}