@hienlh/ppm 0.22.2 → 0.22.4

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());
@@ -193,6 +199,12 @@ export function useChat(
   const turnFinalizedRef = useRef(false);
   const historyRequestRef = useRef<AbortController | null>(null);
   const queuedReplayMessagesRef = useRef<MessageEvent[]>([]);
+  /** Highest streamed event sequence received from the server for this session. */
+  const streamSeqRef = useRef(0);
+  /** A full replay is already on its way; do not flood snapshots for one gap. */
+  const resyncInFlightRef = useRef(false);
+  /** The bounded server replay omitted an old prefix; idle history reload repairs it. */
+  const replayTruncatedRef = useRef(false);
   const handleMessageRef = useRef<((event: MessageEvent) => void) | null>(null);
   /** True while replaying turn_events — suppresses setPendingApproval */
   const isReplayingRef = useRef(false);
@@ -609,6 +621,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 +716,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) {
@@ -769,14 +783,41 @@ export function useChat(
       return;
     }
 
-    // Ignore keepalive pings
-    if ((data as any).type === "ping") return;
-
     if (isReplayingRef.current) {
       queuedReplayMessagesRef.current.push(event);
       return;
     }
 
+    // A ping carries the latest stream sequence. If it is ahead of what the tab
+    // has seen, request the server's in-flight buffer immediately. This catches
+    // a tunnel that keeps heartbeats alive while dropping content frames.
+    if ((data as any).type === "ping") {
+      const serverSeq = (data as any).streamSeq;
+      if (typeof serverSeq === "number" && serverSeq > streamSeqRef.current
+        && !resyncInFlightRef.current && !replayTruncatedRef.current) {
+        resyncInFlightRef.current = true;
+        sendRef.current(JSON.stringify({ type: "resync" }));
+      }
+      return;
+    }
+
+    // Live stream frames must be contiguous. A higher number is evidence that
+    // a tunnel/proxy skipped a content frame; request one full snapshot and let
+    // the replay establish the authoritative cursor below.
+    const streamSeq = (data as any).streamSeq;
+    if (typeof streamSeq === "number") {
+      if (replayTruncatedRef.current) {
+        // The prefix is unavailable from the bounded buffer. Continue showing
+        // fresh frames and let the normal idle transcript reload fill the gap.
+        streamSeqRef.current = Math.max(streamSeqRef.current, streamSeq);
+      } else if (streamSeq === streamSeqRef.current + 1) {
+        streamSeqRef.current = streamSeq;
+      } else if (streamSeq > streamSeqRef.current && !resyncInFlightRef.current) {
+        resyncInFlightRef.current = true;
+        sendRef.current(JSON.stringify({ type: "resync" }));
+      }
+    }
+
     // file:changed, session:unread_changed and jira:* are app-wide and now arrive
     // on the global bus (`use-global-events.ts`) instead of here — a chat socket is
     // not guaranteed to exist since chat tabs mount lazily.
@@ -815,6 +856,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;
@@ -851,11 +893,14 @@ export function useChat(
       // Safety: idle phase means no turn running — ensure compact indicator does not linger.
       // BE should broadcast compact_status=done too, but this is a belt-and-braces clear.
       if (p === "idle") {
+        const replayWasTruncated = replayTruncatedRef.current;
+        resyncInFlightRef.current = false;
+        replayTruncatedRef.current = false;
         setCompactStatus(null);
         setStatusMessage(null);
         // Completion can arrive after lost content/done frames. Reconcile once
         // the turn is idle so the answer appears without a manual reload.
-        if (wasActive && !turnFinalizedRef.current) refetchRef.current?.();
+        if (replayWasTruncated || (wasActive && !turnFinalizedRef.current)) refetchRef.current?.();
       }
       return;
     }
@@ -912,8 +957,11 @@ export function useChat(
       // connects right after the mount fetch and this refetch would re-download
       // the entire history (and remount every transcript image) for no reason.
       if (p === "idle") {
+        const replayWasTruncated = replayTruncatedRef.current;
+        resyncInFlightRef.current = false;
+        replayTruncatedRef.current = false;
         const historyFresh = Date.now() - historyLoadedAtRef.current < 5000;
-        if (!(wasIdle && historyFresh)) refetchRef.current?.();
+        if (replayWasTruncated || !(wasIdle && historyFresh)) refetchRef.current?.();
         setIsReconnecting(false);
       }
       // If streaming, turn_events message will follow
@@ -988,6 +1036,13 @@ export function useChat(
         } else {
           replayRafRef.current = 0;
           isReplayingRef.current = false;
+          const snapshotSeq = (data as any).streamSeq;
+          const truncated = (data as any).truncated === true;
+          replayTruncatedRef.current = truncated;
+          if (!truncated && typeof snapshotSeq === "number") {
+            streamSeqRef.current = snapshotSeq;
+          }
+          resyncInFlightRef.current = false;
           setIsReconnecting(false);
           // Preserve websocket order: live text/done must follow the snapshot,
           // even when rebuilding a large snapshot takes several frames.
@@ -1012,9 +1067,10 @@ export function useChat(
     url: wsUrl,
     onMessage: handleMessage,
     autoConnect: !!sessionId && !!projectName,
-    idleTimeoutMs: 45_000, // Server sends a heartbeat every 15 seconds.
+    idleTimeoutMs: 45_000, // Server sends a heartbeat every 5 seconds.
     onConnectionChange: (connected) => {
       if (!connected) {
+        attemptRef.current?.fail();
         setIsConnected(false);
         setIsReconnecting(true);
       }
@@ -1028,9 +1084,13 @@ 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++;
+    streamSeqRef.current = 0;
+    resyncInFlightRef.current = false;
+    replayTruncatedRef.current = false;
 
     // Keep the user's unconfirmed model/thinking picks across the draft→real transition
     // (null → id), but drop them when switching between two existing sessions so one
@@ -1170,6 +1230,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 +1288,7 @@ export function useChat(
         ...(thinkingRef.current !== null && { thinking: thinkingRef.current }),
       }));
     },
-    [send],
+    [send, isConnected, connectedSessionId],
   );
 
   const setModel = useCallback(
@@ -1294,6 +1355,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-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/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 });
+  }
+}

package/src/web/lib/onboarding/onboarding-copy.ts

@@ -0,0 +1,57 @@
+import type { OnboardingFamiliarity, OnboardingStepId } from "./onboarding-types";
+
+interface StepCopy { title: string; body: string; more: string; action: string }
+const copy: Record<OnboardingStepId, { title: string; action: string; bodies: [string, string, string]; more: string }> = {
+  project: {
+    title: "Choose a project", action: "Choose project",
+    bodies: ["A project is a folder with the files you want to work on. Choose one on the computer running PPM, which may be different from your phone.", "Choose or add a project to begin.", "Select the workspace for this walkthrough."],
+    more: "Use the project picker to select an existing folder or add one. The tour never creates files or changes your project.",
+  },
+  chat: {
+    title: "Open AI chat", action: "Open chat",
+    bodies: ["Chat lets you ask an AI assistant about your project. Open a chat and choose an available AI provider.", "Open a chat with your preferred available provider.", "Open a provider-backed chat tab."],
+    more: "If no provider is ready, use the existing setup or retry controls, or open AI Settings. You can pause this guide and return after setup.",
+  },
+  send: {
+    title: "Ask about your project", action: "Use suggested question",
+    bodies: ["Ask AI to explain your project. You can use our suggested question or write your own, then press Send yourself.", "Send a question and wait for a successful answer.", "Complete one AI turn in this project."],
+    more: "The suggestion requests reading only; your provider's existing permissions still apply. Your draft is never replaced and nothing is sent automatically. Errors or interrupted replies do not complete this step.",
+  },
+  history: {
+    title: "Find your conversation", action: "Show conversation history",
+    bodies: ["Use the chat history menu to open the conversation you just had. This is how you return to your work later.", "Reopen this conversation from the chat history menu.", "Select the completed session in chat history."],
+    more: "Choose the conversation from the history menu above the chat, even if it is already open. If you skipped sending a message, you can skip this step too.",
+  },
+  file: {
+    title: "Read a project file", action: "Open files",
+    bodies: ["The file explorer shows your project's folders and files. Open any text file that you want to read.", "Open any text file from the explorer.", "Open any source, text or Markdown file."],
+    more: "This step completes when a text editor or Markdown Preview loads successfully. The filename does not matter. Images and databases are not part of this reading exercise. If the project is empty or has no readable files, skip this step or choose another project; no sample file is created automatically.",
+  },
+  search: {
+    title: "Search your project", action: "Open search",
+    bodies: ["Search helps you find words inside project files. Type at least two characters and look at the results.", "Search file contents using at least two characters.", "Run a project content search."],
+    more: "A successful search with no matches still counts. A failed request does not. Try a different word, retry an error, or open a result to read its file.",
+  },
+  terminal: {
+    title: "Open the terminal", action: "Open terminal",
+    bodies: ["A terminal runs commands on the computer hosting PPM. Open one and wait for it to connect; you do not need to type a command yet.", "Open a terminal and wait for the shell to become ready.", "Connect a terminal for this project."],
+    more: "The tour never types or executes commands. If connection fails, retry using the terminal controls or skip this step.",
+  },
+  git: {
+    title: "View project changes", action: "Open Git changes",
+    bodies: ["Git tracks changes in a project. Open its changes view to see whether files have changed.", "Inspect the project's Git status.", "Load the working-tree status."],
+    more: "A clean repository counts too. If the folder does not use Git, skip this step or choose another project. The tour never initializes a repository or commits changes.",
+  },
+  run: {
+    title: "Find how to run the project", action: "Find run instructions",
+    bodies: ["Open README or a package manifest and look for instructions to start the project. You can use those instructions in the terminal when you are ready.", "Find the documented run instructions in README or a package manifest.", "Inspect README or package scripts for the run command."],
+    more: "Find run instructions opens a README in the project root, or package.json if there is no readable README. README Preview counts too. After reading, confirm that you know where to find the instructions. This does not run the project. If no file is found, browse Files or skip this step.",
+  },
+};
+
+export const ONBOARDING_SUGGESTED_PROMPT = "Summarize this project and explain how to run it. Only read; do not edit files.";
+export function getOnboardingCopy(step: OnboardingStepId, familiarity: OnboardingFamiliarity | null): StepCopy {
+  const item = copy[step];
+  const index = familiarity === "advanced" ? 2 : familiarity === "familiar" ? 1 : 0;
+  return { title: item.title, body: item.bodies[index], more: item.more, action: item.action };
+}

package/src/web/lib/onboarding/onboarding-state.ts

@@ -0,0 +1,77 @@
+import { getOnboardingSteps } from "./onboarding-steps";
+import type { OnboardingEvent, OnboardingState, OnboardingStepId } from "./onboarding-types";
+
+export function initialOnboardingState(): OnboardingState {
+  return { version: 1, status: "unseen", familiarity: null, goal: null, currentStep: null,
+    completed: [], skipped: [], projectName: null, sessionId: null, attempt: null, runDocumentReady: false };
+}
+
+export function advanceOnboarding(state: OnboardingState, skipped = false): OnboardingState {
+  if (state.status !== "active" || !state.currentStep) return state;
+  const completed = state.completed.filter((id) => id !== state.currentStep);
+  const omitted = state.skipped.filter((id) => id !== state.currentStep);
+  (skipped ? omitted : completed).push(state.currentStep);
+  const route = getOnboardingSteps(state.goal);
+  const next = route.slice(route.indexOf(state.currentStep) + 1).find((id) => !completed.includes(id) && !omitted.includes(id));
+  return { ...state, completed, skipped: omitted, currentStep: next ?? state.currentStep, status: next ? "active" : "finished" };
+}
+
+export function observeOnboarding(state: OnboardingState, event: OnboardingEvent): OnboardingState {
+  // Failure invalidates an already tracked turn even if its tab just became hidden.
+  if (event.type === "chat-failed" && event.projectName === state.projectName && state.attempt?.id === event.attemptId &&
+      state.attempt.tabId === event.tabId && state.attempt.sessionId === event.sessionId) {
+    return { ...state, attempt: { ...state.attempt, failed: true } };
+  }
+  if (state.status !== "active" || !event.visible || event.projectName !== state.projectName) return state;
+  const step = state.currentStep;
+  if (event.type === "run-document-ready" && step === "run") return { ...state, runDocumentReady: true };
+  if (event.type === "chat-opened" && step === "chat") return advanceOnboarding(state);
+  if (event.type === "chat-started" && step === "send") {
+    if (state.attempt?.id === event.attemptId) return state;
+    return { ...state, sessionId: event.sessionId, attempt: { id: event.attemptId, tabId: event.tabId, sessionId: event.sessionId, failed: false } };
+  }
+  if (event.type === "chat-session" && state.attempt?.id === event.attemptId && state.attempt.tabId === event.tabId && state.attempt.sessionId === event.previousSessionId) {
+    return { ...state, sessionId: event.sessionId, attempt: { ...state.attempt, sessionId: event.sessionId } };
+  }
+  if (event.type === "chat-failed" || event.type === "chat-succeeded") {
+    const attempt = state.attempt;
+    if (!attempt || attempt.id !== event.attemptId || attempt.tabId !== event.tabId || attempt.sessionId !== event.sessionId) return state;
+    if (event.type === "chat-failed") return { ...state, attempt: { ...attempt, failed: true } };
+    return step === "send" && !attempt.failed && event.hasContent ? advanceOnboarding(state) : state;
+  }
+  if (event.type === "history-opened" && step === "history" && state.completed.includes("send") && event.sessionId === state.sessionId) return advanceOnboarding(state);
+  if (event.type === "file-ready") {
+    if (step === "file") return advanceOnboarding(state);
+    if (step === "run" && event.isRunDocument) return { ...state, runDocumentReady: true };
+  }
+  if ((event.type === "search-succeeded" && step === "search") ||
+      (event.type === "terminal-ready" && step === "terminal") ||
+      (event.type === "git-ready" && step === "git") ||
+      (event.type === "run-acknowledged" && step === "run" && state.runDocumentReady)) return advanceOnboarding(state);
+  return state;
+}
+
+/** Select only durable fields: no paths, drafts, queries or runtime evidence. */
+export function serializeOnboarding(state: OnboardingState): string {
+  const { version, status, familiarity, goal, currentStep, completed, skipped, projectName, sessionId } = state;
+  return JSON.stringify({ version, status, familiarity, goal, currentStep, completed, skipped, projectName, sessionId });
+}
+
+export function hydrateOnboarding(raw: string | null): OnboardingState {
+  const initial = initialOnboardingState();
+  if (!raw) return initial;
+  try {
+    const value = JSON.parse(raw);
+    if (!value || value.version !== 1 || !["unseen", "choosing", "active", "paused", "dismissed", "finished"].includes(value.status) ||
+        ![null, "beginner", "familiar", "advanced"].includes(value.familiarity) || ![null, "ai", "explore", "developer"].includes(value.goal)) return initial;
+    const route = getOnboardingSteps(value.goal);
+    if (value.currentStep !== null && !route.includes(value.currentStep)) return initial;
+    if (![value.completed, value.skipped].every((list) => Array.isArray(list) && list.every((id) => route.includes(id)))) return initial;
+    if (![value.projectName, value.sessionId].every((id) => id === null || typeof id === "string")) return initial;
+    if (["active", "finished"].includes(value.status) && (!value.familiarity || !value.goal || !value.currentStep)) return initial;
+    const completed = [...new Set<OnboardingStepId>(value.completed)];
+    const skipped = [...new Set<OnboardingStepId>(value.skipped)].filter((id) => !completed.includes(id));
+    return { ...initial, status: value.status === "active" ? "paused" : value.status, familiarity: value.familiarity,
+      goal: value.goal, currentStep: value.currentStep, completed, skipped, projectName: value.projectName, sessionId: value.sessionId };
+  } catch { return initial; }
+}

package/src/web/lib/onboarding/onboarding-steps.ts

@@ -0,0 +1,16 @@
+import type { OnboardingGoal, OnboardingStepId } from "./onboarding-types";
+
+const routes: Record<OnboardingGoal, readonly OnboardingStepId[]> = {
+  ai: ["project", "chat", "send", "history"],
+  explore: ["project", "file", "search"],
+  developer: ["project", "terminal", "git", "run"],
+};
+
+export function getOnboardingSteps(goal: OnboardingGoal | null): readonly OnboardingStepId[] {
+  return goal ? routes[goal] : [];
+}
+
+export const ONBOARDING_TARGETS: Record<OnboardingStepId, string> = {
+  project: "project", chat: "chat", send: "chat-input", history: "chat-history",
+  file: "explorer", search: "search", terminal: "terminal", git: "git", run: "explorer",
+};

package/src/web/lib/onboarding/onboarding-types.ts

@@ -0,0 +1,39 @@
+export type OnboardingFamiliarity = "beginner" | "familiar" | "advanced";
+export type OnboardingGoal = "ai" | "explore" | "developer";
+export type OnboardingStatus = "unseen" | "choosing" | "active" | "paused" | "dismissed" | "finished";
+export type OnboardingStepId = "project" | "chat" | "send" | "history" | "file" | "search" | "terminal" | "git" | "run";
+
+type Scope = { projectName: string; visible: boolean };
+type ChatScope = Scope & { tabId: string; sessionId: string; attemptId: string };
+export type OnboardingEvent =
+  | (Scope & { type: "chat-opened"; tabId: string; sessionId?: string | null })
+  | (ChatScope & { type: "chat-started" })
+  | (ChatScope & { type: "chat-failed" })
+  | (ChatScope & { type: "chat-succeeded"; hasContent: boolean })
+  | (ChatScope & { type: "chat-session"; previousSessionId: string })
+  | (Scope & { type: "history-opened"; tabId: string; sessionId: string })
+  | (Scope & { type: "file-ready"; tabId: string; isRunDocument?: boolean })
+  | (Scope & { type: "run-document-ready"; tabId: string })
+  | (Scope & { type: "search-succeeded"; requestId: string })
+  | (Scope & { type: "terminal-ready"; tabId: string })
+  | (Scope & { type: "git-ready" | "run-acknowledged" });
+
+export interface OnboardingState {
+  version: 1;
+  status: OnboardingStatus;
+  familiarity: OnboardingFamiliarity | null;
+  goal: OnboardingGoal | null;
+  currentStep: OnboardingStepId | null;
+  completed: OnboardingStepId[];
+  skipped: OnboardingStepId[];
+  projectName: string | null;
+  sessionId: string | null;
+  /** Transient evidence is deliberately excluded from persistence. */
+  attempt: { id: string; tabId: string; sessionId: string; failed: boolean } | null;
+  runDocumentReady: boolean;
+}
+
+export const ONBOARDING_EVENT = "ppm:onboarding-evidence";
+export function emitOnboardingEvidence(event: OnboardingEvent): void {
+  if (typeof window !== "undefined") window.dispatchEvent(new CustomEvent(ONBOARDING_EVENT, { detail: event }));
+}

package/src/web/lib/onboarding/run-instructions.ts

@@ -0,0 +1,22 @@
+import { api, projectUrl } from "@/lib/api-client";
+import { useTabStore } from "@/stores/tab-store";
+import type { FileDirEntry } from "../../../types/project";
+
+export function chooseRunInstructions(entries: FileDirEntry[]): string | undefined {
+  const names = entries.filter((entry) => entry.type === "file").map((entry) => entry.name);
+  const priorities = ["readme.md", "readme.markdown", "readme.txt", "readme", "readme.rst", "package.json"];
+  return priorities.map((name) => names.find((candidate) => candidate.toLowerCase() === name)).find(Boolean);
+}
+
+/** Navigation only. Readiness comes from the actual editor/preview after loading. */
+export async function openRunInstructions(projectName: string, stillCurrent: () => boolean): Promise<"opened" | "missing" | "stale"> {
+  const entries = await api.get<FileDirEntry[]>(`${projectUrl(projectName)}/files/list`);
+  if (!stillCurrent()) return "stale";
+  const filePath = chooseRunInstructions(entries);
+  if (!filePath) return "missing";
+  useTabStore.getState().openTab({ type: "editor", title: filePath, projectId: projectName,
+    metadata: { projectName, filePath }, closable: true });
+  // Re-check already-open previews as well as newly mounted editors.
+  requestAnimationFrame(() => window.dispatchEvent(new Event("ppm:onboarding-refresh")));
+  return "opened";
+}

package/src/web/stores/onboarding-store.ts

@@ -0,0 +1,74 @@
+import { create } from "zustand";
+import { advanceOnboarding, hydrateOnboarding, initialOnboardingState, observeOnboarding, serializeOnboarding } from "../lib/onboarding/onboarding-state";
+import { getOnboardingSteps } from "../lib/onboarding/onboarding-steps";
+import type { OnboardingEvent, OnboardingFamiliarity, OnboardingGoal, OnboardingState } from "../lib/onboarding/onboarding-types";
+
+export const ONBOARDING_STORAGE_KEY = "ppm-onboarding-v1";
+interface OnboardingActions {
+  begin: () => void;
+  chooseFamiliarity: (value: OnboardingFamiliarity) => void;
+  chooseGoal: (value: OnboardingGoal) => void;
+  start: (projectName?: string | null) => void;
+  pause: () => void;
+  dismiss: () => void;
+  resume: (projectName?: string | null) => void;
+  replay: () => void;
+  skip: () => void;
+  back: () => void;
+  changeChoices: () => void;
+  observe: (event: OnboardingEvent) => void;
+  setProjectContext: (name: string | null) => void;
+}
+
+function readState(): OnboardingState {
+  try { return hydrateOnboarding(typeof localStorage === "undefined" ? null : localStorage.getItem(ONBOARDING_STORAGE_KEY)); }
+  catch { return initialOnboardingState(); }
+}
+
+export const useOnboardingStore = create<OnboardingState & OnboardingActions>((set, get) => {
+  const activate = (name?: string | null) => set((state) => {
+    if (!state.goal || !state.familiarity) return { status: "choosing" as const };
+    const projectName = name === undefined ? state.projectName : name;
+    const changed = projectName !== state.projectName;
+    const next: OnboardingState = { ...state, status: "active", projectName,
+      currentStep: changed || !state.currentStep ? "project" : state.currentStep,
+      completed: changed ? [] : state.completed, skipped: changed ? [] : state.skipped,
+      attempt: changed ? null : state.attempt, sessionId: changed ? null : state.sessionId,
+      runDocumentReady: changed ? false : state.runDocumentReady };
+    return next.currentStep === "project" && projectName ? advanceOnboarding(next) : next;
+  });
+  return {
+    ...readState(),
+    begin: () => set({ status: "choosing" }),
+    chooseFamiliarity: (familiarity) => set({ familiarity }),
+    chooseGoal: (goal) => set((state) => state.goal === goal ? { goal } : {
+      goal, currentStep: "project", completed: state.completed.includes("project") && state.projectName ? ["project"] : [],
+      skipped: [], sessionId: null, attempt: null, runDocumentReady: false,
+    }),
+    start: activate,
+    pause: () => set((state) => state.status === "active" || state.status === "choosing" ? { status: "paused", attempt: null } : {}),
+    dismiss: () => set({ status: "dismissed", attempt: null }),
+    resume: activate,
+    replay: () => set({ ...initialOnboardingState(), status: "choosing" }),
+    skip: () => set((state) => advanceOnboarding(state, true)),
+    back: () => set((state) => {
+      const route = getOnboardingSteps(state.goal);
+      const index = state.currentStep ? route.indexOf(state.currentStep) : -1;
+      return index > 0 ? { currentStep: route[index - 1], status: "active" } : {};
+    }),
+    changeChoices: () => set({ status: "choosing", attempt: null }),
+    observe: (event) => set((state) => observeOnboarding(state, event)),
+    setProjectContext: (name) => {
+      const state = get();
+      if (state.status !== "active") return;
+      if (state.currentStep === "project" && name) {
+        set(advanceOnboarding({ ...state, projectName: name }));
+      } else if (name !== state.projectName) set({ status: "paused", attempt: null, runDocumentReady: false });
+    },
+  };
+});
+
+useOnboardingStore.subscribe((state) => {
+  try { if (typeof localStorage !== "undefined") localStorage.setItem(ONBOARDING_STORAGE_KEY, serializeOnboarding(state)); }
+  catch { /* Guidance remains usable when browser storage is unavailable. */ }
+});

package/vite.config.ts

@@ -86,7 +86,11 @@ export default defineConfig({
     port: 5173,
     allowedHosts: true,
     proxy: {
-      "/api": process.env.PPM_DEV_API ?? "http://localhost:8081",
+      "/api": {
+        target: process.env.PPM_DEV_API ?? "http://localhost:8081",
+        // HTML preview CSP must refer to the browser-facing authority.
+        changeOrigin: false,
+      },
       "/ws": {
         target: process.env.PPM_DEV_API ?? "http://localhost:8081",
         ws: true,