@ashwin-pc/pi-web 0.1.2

package/docs/frontend-architecture.md

@@ -0,0 +1,72 @@
+# Frontend architecture
+
+The frontend is intentionally plain TypeScript on top of Vite. It is organized as small feature controllers instead of a framework component tree.
+
+## Entry point
+
+`src/main.ts` should stay a composition/bootstrap file. It is responsible for:
+
+1. importing global CSS;
+2. creating shared objects (`elements`, `state`, `api`);
+3. constructing feature controllers;
+4. wiring cross-controller callbacks; and
+5. starting the initial state refresh and WebSocket connection.
+
+Avoid adding feature logic directly to `main.ts`. If a change needs more than a small wiring callback, put it in the feature module that owns the behavior.
+
+## Shared app objects
+
+- `src/app/elements.ts` - all required DOM lookups and viewport-height syncing.
+- `src/app/types.ts` - shared frontend state and API/event types.
+- `src/app/api.ts` - auth headers and WebSocket URL construction.
+- `src/app/icons.ts` - shared Lucide icon helpers.
+
+Feature modules receive the pieces they need explicitly. Prefer passing `state`, `elements`, `api`, and callbacks over importing another feature module's internals.
+
+## Feature modules
+
+- `src/composer/composer.ts` - prompt form, slash commands, image attachments, queue mode, stop/send buttons, token form, editor expansion.
+- `src/messages/messageList.ts` - chat message rendering, streaming assistant deltas, message history refresh.
+- `src/messages/content.ts` - raw Pi message content parsing helpers.
+- `src/markdown/render.ts` - Markdown sanitizing, syntax highlighting, lazy rendering, copy buttons.
+- `src/components/imageActions.ts` - image fullscreen/download/open controls used by messages and Markdown.
+- `src/tools/toolCards.ts` - running and historical tool cards.
+- `src/models/modelSettings.ts` - model/reasoning popover and model selection API calls.
+- `src/status/statusBar.ts` - session title/path display, title rename flow, WebSocket connection status UI.
+- `src/sessions/sessionDrawer.ts` - sessions drawer, cwd grouping, new/open session flows, folder picker, empty-cwd chooser.
+- `src/realtime/realtime.ts` - WebSocket lifecycle and Pi event dispatch.
+- `src/git/*` - Git panel API, state, and views.
+
+## State and data flow
+
+`AppState` in `src/app/types.ts` contains the shared mutable UI state. Controllers update it directly when they own the relevant interaction, then call the smallest UI update function needed.
+
+Common shared callbacks are defined in `main.ts`:
+
+- `updateMeta(data)` updates model/session/cwd metadata and delegates summary/status rendering.
+- `refreshMessages()` reloads history and asks the tool-card controller to clear active cards.
+- `refreshState()` reloads server state, model metadata, messages, and the session title.
+
+When adding a new feature, keep ownership clear:
+
+- rendering for a UI area should live with that area's controller;
+- server calls should live in the controller that owns the user interaction;
+- cross-feature updates should go through narrow callbacks passed from `main.ts`.
+
+## Testing expectations
+
+After TypeScript or frontend behavior changes, run:
+
+```bash
+npm run typecheck
+npm run build
+```
+
+For behavior changes, also run the relevant tests or the full suite:
+
+```bash
+npm run test:unit
+npm run test:e2e
+# or
+npm test
+```

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@ashwin-pc/pi-web",
+  "version": "0.1.2",
+  "description": "Local/Tailscale web UI for pi coding agent.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "pi-web": "./bin/pi-web.js"
+  },
+  "files": [
+    ".pi/extensions/",
+    "bin/",
+    "contexts/",
+    "dist/",
+    "docs/",
+    "server/",
+    "server.ts",
+    "supervisor.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "PI_WEB_DEV=1 node --import tsx supervisor.ts",
+    "dev:server": "PI_WEB_DEV=1 node --import tsx --watch server.ts",
+    "build": "vite build",
+    "start": "node --import tsx server.ts",
+    "start:supervised": "node --import tsx supervisor.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run typecheck && vitest run && playwright test",
+    "test:unit": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
+    "release:pack": "rm -rf release && npm run build && mkdir -p release && npm pack --pack-destination release",
+    "test:all": "npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@mariozechner/pi-coding-agent": "^0.73.0",
+    "highlight.js": "^11.11.1",
+    "lucide": "^1.14.0",
+    "marked": "^15.0.12",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "vite": "^7.2.7",
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.59.1",
+    "@types/node": "^24.10.1",
+    "@types/ws": "^8.5.14",
+    "vite-plugin-pwa": "^1.3.0",
+    "vitest": "^4.1.5"
+  }
+}

package/server/extensions.ts

@@ -0,0 +1,121 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+type BundledExtensionPathOptions = {
+  piCwd: string;
+  appDir: string;
+  bundledExtensionsDir: string;
+};
+
+function isExtensionFile(name: string) {
+  return name.endsWith(".ts") || name.endsWith(".js");
+}
+
+function dedupePaths(paths: string[]) {
+  const seen = new Set<string>();
+  return paths.filter((path) => {
+    const key = resolve(path);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function readManifestExtensionEntries(dir: string, seenDirs: Set<string>) {
+  const packageJsonPath = join(dir, "package.json");
+  if (!existsSync(packageJsonPath)) return [];
+
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as { pi?: { extensions?: unknown } };
+    if (!Array.isArray(pkg.pi?.extensions)) return [];
+
+    return pkg.pi.extensions.flatMap((entry) => {
+      if (typeof entry !== "string") return [];
+      const entryPath = resolve(dir, entry);
+      if (!existsSync(entryPath)) return [];
+
+      try {
+        const stats = statSync(entryPath);
+        if (stats.isFile()) return [entryPath];
+        if (stats.isDirectory()) return discoverExtensionEntryPaths(entryPath, seenDirs);
+      } catch {
+        // Ignore invalid manifest entries.
+      }
+      return [];
+    });
+  } catch {
+    return [];
+  }
+}
+
+function resolveExtensionEntries(dir: string, seenDirs: Set<string>) {
+  const manifestEntries = readManifestExtensionEntries(dir, seenDirs);
+  if (manifestEntries.length > 0) return manifestEntries;
+
+  const indexTs = join(dir, "index.ts");
+  if (existsSync(indexTs)) return [indexTs];
+
+  const indexJs = join(dir, "index.js");
+  if (existsSync(indexJs)) return [indexJs];
+
+  return null;
+}
+
+export function discoverExtensionEntryPaths(dir: string, seenDirs = new Set<string>()): string[] {
+  if (!existsSync(dir)) return [];
+
+  const dirKey = resolve(dir);
+  if (seenDirs.has(dirKey)) return [];
+  seenDirs.add(dirKey);
+
+  const rootEntries = resolveExtensionEntries(dir, seenDirs);
+  if (rootEntries) return dedupePaths(rootEntries);
+
+  const discovered: string[] = [];
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+
+      const entryPath = join(dir, entry.name);
+      let isFile = entry.isFile();
+      let isDirectory = entry.isDirectory();
+
+      if (entry.isSymbolicLink()) {
+        try {
+          const stats = statSync(entryPath);
+          isFile = stats.isFile();
+          isDirectory = stats.isDirectory();
+        } catch {
+          continue;
+        }
+      }
+
+      if (isFile && isExtensionFile(entry.name)) {
+        discovered.push(entryPath);
+        continue;
+      }
+
+      if (isDirectory) {
+        const nestedEntries = resolveExtensionEntries(entryPath, seenDirs);
+        if (nestedEntries) discovered.push(...nestedEntries);
+      }
+    }
+  } catch {
+    return [];
+  }
+
+  return dedupePaths(discovered);
+}
+
+export function resolveBundledExtensionPaths(options: BundledExtensionPathOptions) {
+  // When developing pi-web from this repo, the same directory is already loaded
+  // by pi as the project-local .pi/extensions path. For other PI_WEB_CWD values
+  // and packaged installs, add pi-web's bundled extensions explicitly.
+  if (resolve(options.piCwd) === resolve(options.appDir) || !existsSync(options.bundledExtensionsDir)) return [];
+
+  // DefaultResourceLoader resolves additionalExtensionPaths as package sources.
+  // Passing the extensions directory itself can produce the directory as a single
+  // extension path, so expand it to concrete entry files before handing it to pi.
+  return discoverExtensionEntryPaths(options.bundledExtensionsDir);
+}

package/server/mock.ts

@@ -0,0 +1,402 @@
+import { join } from "node:path";
+import type { PiWebSession, PiWebSessionInfo } from "./types.js";
+
+interface MockSessionOptions {
+  piCwd: string;
+  broadcast(value: unknown): void;
+  isCurrentSession(session: PiWebSession): boolean;
+  currentState(): unknown;
+}
+
+export function createMockHarness(options: MockSessionOptions) {
+  const { piCwd, broadcast, isCurrentSession, currentState } = options;
+  const mockModel = { provider: "mock", id: "model", name: "Mock Model", reasoning: true, contextWindow: 128000, maxTokens: 4096 };
+
+  function initialMockSessions(): PiWebSessionInfo[] {
+    return [
+      {
+        id: "mock-current",
+        path: join(piCwd, ".mock-sessions/current.jsonl"),
+        name: "Current mock session",
+        firstMessage: "Can you add image attachments?",
+        created: new Date("2026-05-01T10:00:00Z"),
+        modified: new Date("2026-05-07T10:00:00Z"),
+        messageCount: 2,
+        allMessagesText: "Can you add image attachments?",
+        cwd: piCwd,
+      },
+      {
+        id: "mock-older",
+        path: join(piCwd, ".mock-sessions/older.jsonl"),
+        name: "Older mock session",
+        firstMessage: "Review the mobile composer layout",
+        created: new Date("2026-05-01T09:00:00Z"),
+        modified: new Date("2026-05-06T09:00:00Z"),
+        messageCount: 4,
+        allMessagesText: "Review the mobile composer layout",
+        cwd: piCwd,
+      },
+    ];
+  }
+
+  const mockSessions: PiWebSessionInfo[] = initialMockSessions();
+
+  function resetMockSessions() {
+    mockSessions.splice(0, mockSessions.length, ...initialMockSessions());
+  }
+
+  function initialMessages(path: string): unknown[] {
+    return path === mockSessions[1].path
+      ? [
+        { role: "user", content: "Review the mobile composer layout", timestamp: "2026-05-06T09:00:00Z" },
+        { role: "assistant", content: "Resumed older session.", usage: { input: 4200, output: 320, cacheRead: 1200, cacheWrite: 0, cost: { total: 0.018 } }, timestamp: "2026-05-06T09:01:00Z" },
+      ]
+      : [
+        { role: "user", content: "Can you add image attachments?", timestamp: "2026-05-07T10:00:00Z" },
+        { role: "assistant", content: ("## Image attachment support\n\nImage attachment support is **enabled**.\n\n- Upload images\n- Preview images\n\n```ts\nconst enabled = true;\n```\n\n").repeat(18), usage: { input: 18600, output: 3400, cacheRead: 9200, cacheWrite: 800, cost: { total: 0.092 } }, timestamp: "2026-05-07T10:01:00Z" },
+      ];
+  }
+
+  function textFromMockContent(content: unknown): string {
+    if (typeof content === "string") return content;
+    if (!Array.isArray(content)) return "";
+    return content.map((part) => {
+      if (!part || typeof part !== "object") return "";
+      const value = part as Record<string, unknown>;
+      return value.type === "text" && typeof value.text === "string" ? value.text : "";
+    }).filter(Boolean).join("\n");
+  }
+
+  function createInitialEntries(path: string) {
+    const [first, second] = initialMessages(path) as Array<Record<string, unknown>>;
+    const entries = [
+      { type: "message", id: "mock-u1", parentId: null, timestamp: String(first.timestamp), message: first },
+      { type: "message", id: "mock-a1", parentId: "mock-u1", timestamp: String(second.timestamp), message: second },
+    ];
+    if (path === mockSessions[0].path) {
+      entries.push(
+        { type: "message", id: "mock-u-alt", parentId: "mock-u1", timestamp: "2026-05-07T10:02:00Z", message: { role: "user", content: "Actually, make the attachment picker mobile-first.", timestamp: "2026-05-07T10:02:00Z" } },
+        { type: "message", id: "mock-a-alt", parentId: "mock-u-alt", timestamp: "2026-05-07T10:03:00Z", message: { role: "assistant", content: "Use a bottom sheet with large tap targets for image actions.", timestamp: "2026-05-07T10:03:00Z" } },
+      );
+    }
+    return entries;
+  }
+
+  function createMockSession(path = mockSessions[0].path): PiWebSession {
+    let mockEntries = createInitialEntries(path);
+    let mockLeafId: string | null = "mock-a1";
+    let entrySequence = 2;
+    const labelsById = new Map<string, string>();
+    const mockMessages: unknown[] = [];
+
+    function entryById(id: string) {
+      return mockEntries.find((entry) => entry.id === id);
+    }
+
+    function getBranch(fromId = mockLeafId): any[] {
+      if (!fromId) return [];
+      const branch = [];
+      let current: string | null = fromId;
+      while (current) {
+        const entry = entryById(current);
+        if (!entry) break;
+        branch.unshift(entry);
+        current = entry.parentId;
+      }
+      return branch;
+    }
+
+    function syncMessagesToLeaf() {
+      mockMessages.length = 0;
+      mockMessages.push(...getBranch().filter((entry) => entry.type === "message").map((entry) => entry.message));
+    }
+
+    function buildTree(parentId: string | null): any[] {
+      return mockEntries
+        .filter((entry) => entry.parentId === parentId)
+        .map((entry) => ({
+          entry,
+          label: labelsById.get(entry.id),
+          children: buildTree(entry.id),
+        }));
+    }
+
+    function appendMockMessage(message: Record<string, unknown>) {
+      const timestamp = String(message.timestamp || new Date().toISOString());
+      message.timestamp = timestamp;
+      const id = `mock-e${++entrySequence}`;
+      mockEntries.push({ type: "message", id, parentId: mockLeafId, timestamp, message });
+      mockLeafId = id;
+      syncMessagesToLeaf();
+      return id;
+    }
+
+    function resetMockEntries(nextPath: string) {
+      mockEntries = createInitialEntries(nextPath);
+      mockLeafId = "mock-a1";
+      entrySequence = 2;
+      labelsById.clear();
+      syncMessagesToLeaf();
+    }
+
+    syncMessagesToLeaf();
+    let mockSession: PiWebSession;
+    let compactionAbortRequested = false;
+
+    async function runMockCompaction(customInstructions?: string, slow = false) {
+      mockSession.isCompacting = true;
+      compactionAbortRequested = false;
+      broadcastRuntimeChanged();
+      broadcast({ type: "pi_event", sessionId: mockSession.sessionId, sessionFile: mockSession.sessionFile, event: { type: "compaction_start", reason: "manual" } });
+      if (isCurrentSession(mockSession)) broadcast({ type: "state_changed", ...currentState() as object });
+      const deadline = Date.now() + (slow ? 5_000 : 1_000);
+      while (!compactionAbortRequested && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 50));
+      mockSession.isCompacting = false;
+      if (compactionAbortRequested) {
+        broadcastRuntimeChanged();
+        broadcast({ type: "pi_event", sessionId: mockSession.sessionId, sessionFile: mockSession.sessionFile, event: { type: "compaction_end", reason: "manual", aborted: true } });
+        if (isCurrentSession(mockSession)) broadcast({ type: "state_changed", ...currentState() as object });
+        return undefined;
+      }
+      const result = {
+        tokensBefore: 12345,
+        summary: customInstructions ? `Mock compacted context summary. Instructions: ${customInstructions}` : "Mock compacted context summary.",
+      };
+      appendMockMessage({ role: "compactionSummary", content: result.summary, tokensBefore: result.tokensBefore, summary: result.summary, timestamp: new Date().toISOString() } as any);
+      broadcastRuntimeChanged();
+      broadcast({ type: "pi_event", sessionId: mockSession.sessionId, sessionFile: mockSession.sessionFile, event: { type: "compaction_end", reason: "manual", result } });
+      if (isCurrentSession(mockSession)) broadcast({ type: "state_changed", ...currentState() as object });
+      return result;
+    }
+
+    const mockSessionManager = {
+      newSession() {
+        mockSession.sessionId = `mock-${Date.now()}`;
+        mockSession.sessionFile = join(piCwd, `.mock-sessions/${mockSession.sessionId}.jsonl`);
+        mockEntries = [];
+        mockLeafId = null;
+        labelsById.clear();
+        syncMessagesToLeaf();
+      },
+      setSessionFile(path: string) {
+        mockSession.sessionFile = path;
+        mockSession.sessionId = mockSessions.find((info) => info.path === path)?.id || "mock-opened";
+        resetMockEntries(path);
+      },
+      buildSessionContext() { return { messages: mockMessages }; },
+      getSessionDir() { return join(piCwd, ".mock-sessions"); },
+      getLeafId() { return mockLeafId; },
+      getEntry(id: string) { return entryById(id); },
+      getBranch,
+      getTree() { return buildTree(null); },
+      getLabel(id: string) { return labelsById.get(id); },
+      branch(entryId: string) {
+        if (!entryById(entryId)) throw new Error("Entry not found");
+        mockLeafId = entryId;
+        syncMessagesToLeaf();
+      },
+      resetLeaf() {
+        mockLeafId = null;
+        syncMessagesToLeaf();
+      },
+      appendLabelChange(targetId: string, label: string | undefined) {
+        if (label) labelsById.set(targetId, label);
+        else labelsById.delete(targetId);
+        return `mock-label-${Date.now()}`;
+      },
+    };
+
+    function broadcastRuntimeChanged() {
+      broadcast({
+        type: "session_runtime_changed",
+        sessionId: mockSession.sessionId,
+        sessionFile: mockSession.sessionFile,
+        runtime: {
+          loaded: true,
+          isRunning: Boolean(mockSession.isStreaming) || Boolean(mockSession.isCompacting),
+          isStreaming: Boolean(mockSession.isStreaming),
+          isCompacting: Boolean(mockSession.isCompacting),
+          pendingMessageCount: 0,
+        },
+      });
+    }
+
+    mockSession = {
+      sessionId: mockSessions.find((info) => info.path === path)?.id || "mock-current",
+      sessionFile: path,
+      isStreaming: false,
+      model: mockModel,
+      thinkingLevel: "medium",
+      messages: mockMessages,
+      agent: { state: { messages: mockMessages } },
+      sessionManager: mockSessionManager,
+      modelRegistry: {
+        getAvailable: () => [mockModel],
+        find: (provider: string, id: string) => provider === mockModel.provider && id === mockModel.id ? mockModel : undefined,
+      },
+      extensionRunner: {
+        getRegisteredCommands: () => [{
+          invocationName: "mock-extension",
+          description: "Mock extension command",
+          sourceInfo: { path: "<mock-extension>", source: "mock", scope: "temporary", origin: "top-level" },
+        }],
+      },
+      promptTemplates: [{
+        name: "mock-prompt",
+        description: "Mock prompt template",
+        sourceInfo: { path: "<mock-prompt>", source: "mock", scope: "temporary", origin: "top-level" },
+      }],
+      resourceLoader: {
+        getSkills: () => ({ skills: [{
+          name: "mock-skill",
+          description: "Mock skill",
+          sourceInfo: { path: "<mock-skill>", source: "mock", scope: "temporary", origin: "top-level" },
+        }] }),
+      },
+      getAvailableThinkingLevels: () => ["off", "low", "medium", "high"],
+      get sessionName() { return mockSessions.find((info) => info.path === mockSession.sessionFile)?.name; },
+      getContextUsage: () => {
+        const lastAssistant = [...mockMessages].reverse().find((message: any) => message?.role === "assistant" && message?.usage) as any;
+        const tokens = Number(lastAssistant?.usage?.input || 0) || null;
+        const contextWindow = mockModel.contextWindow;
+        return { tokens, contextWindow, percent: tokens === null ? null : Math.round((tokens / contextWindow) * 1000) / 10 };
+      },
+      setSessionName: (name: string) => {
+        const info = mockSessions.find((item) => item.path === mockSession.sessionFile);
+        if (info) info.name = name.trim();
+        broadcast({ type: "pi_event", sessionId: mockSession.sessionId, sessionFile: mockSession.sessionFile, event: { type: "session_info_changed", name: name.trim() || undefined } });
+        if (isCurrentSession(mockSession)) broadcast({ type: "state_changed", ...currentState() as object });
+      },
+      setModel: async (model: unknown) => { mockSession.model = model as typeof mockModel; },
+      setThinkingLevel: (level: string) => { mockSession.thinkingLevel = level; },
+      reload: async () => undefined,
+      navigateTree: async (targetId: string, navigateOptions?: { summarize?: boolean; customInstructions?: string; label?: string }) => {
+        const target = entryById(targetId);
+        if (!target) throw new Error("Entry not found");
+        const oldLeafId = mockLeafId;
+        let nextLeafId: string | null = targetId;
+        let editorText: string | undefined;
+        if (target.type === "message" && target.message.role === "user") {
+          nextLeafId = target.parentId;
+          editorText = textFromMockContent(target.message.content);
+        }
+
+        if (navigateOptions?.summarize && oldLeafId && oldLeafId !== targetId) {
+          const timestamp = new Date().toISOString();
+          const id = `mock-summary-${Date.now()}`;
+          mockEntries.push({
+            type: "branch_summary",
+            id,
+            parentId: nextLeafId,
+            timestamp,
+            fromId: oldLeafId,
+            summary: navigateOptions.customInstructions ? `Mock branch summary focused on: ${navigateOptions.customInstructions}` : "Mock branch summary of the branch you left.",
+          } as any);
+          mockLeafId = id;
+          if (navigateOptions.label) labelsById.set(id, navigateOptions.label);
+        } else {
+          mockLeafId = nextLeafId;
+          if (navigateOptions?.label) labelsById.set(targetId, navigateOptions.label);
+        }
+        syncMessagesToLeaf();
+        return { editorText, cancelled: false };
+      },
+      compact: async (customInstructions?: string) => runMockCompaction(customInstructions),
+      prompt: async (message: string, promptOptions?: { images?: unknown[] }) => {
+        appendMockMessage({ role: "user", content: message, timestamp: new Date().toISOString() });
+        const withCompaction = /compact|compaction/i.test(message);
+        if (withCompaction) {
+          await runMockCompaction(undefined, /slow/i.test(message));
+          return;
+        }
+        const slow = /slow|running/i.test(message);
+        const withShowcase = /showcase/i.test(message);
+        const withProviderError = /provider error|assistant error|usage limit/i.test(message);
+        const withMalformedEditTool = /malformed edit/i.test(message);
+        const withEditTool = !withShowcase && !withMalformedEditTool && /edit diff/i.test(message);
+        const withPendingToolRefresh = /pending tool refresh/i.test(message);
+        const withTools = !withShowcase && !withEditTool && !withMalformedEditTool && /tool|interleav/i.test(message);
+        mockSession.isStreaming = true;
+        broadcastRuntimeChanged();
+        broadcast({ type: "pi_event", sessionId: mockSession.sessionId, sessionFile: mockSession.sessionFile, event: { type: "agent_start" } });
+        if (slow) await new Promise((resolve) => setTimeout(resolve, 750));
+        if (withProviderError) {
+          appendMockMessage({
+            role: "assistant",
+            content: [],
+            stopReason: "error",
+            errorMessage: "Codex error: {\"type\":\"error\",\"error\":{\"type\":\"usage_limit_reached\",\"message\":\"The usage limit has been reached\",\"resets_in_seconds\":120},\"status_code\":429}",
+            timestamp: new Date().toISOString(),
+          });
+        } else if (withShowcase) {
+          const editArgs = { path: "/Users/ashwin/projects/pi-web/src/style.css", edits: [{ oldText: ".sessionItem {\n  min-height: 40px;\n}", newText: ".sessionItem {\n  height: auto;\n  min-height: 0;\n}\n\n@media (max-width: 700px) {\n  .sessionDrawer { width: 100vw; }\n}" }] };
+          appendMockMessage({ role: "assistant", content: [
+            { type: "text", text: "## Mobile-first coding UI\n\nI reviewed the session drawer, checked the CSS, and tightened the responsive layout.\n\n```ts\nawait runVisualRegression({ projects: [\"mobile\", \"desktop\"] });\n```" },
+            { type: "toolCall", id: "call-showcase-read", toolName: "read", arguments: { path: "/Users/ashwin/projects/pi-web/src/style.css" } },
+            { type: "text", text: "The global button height was constraining session rows, so I patched the drawer-specific styles." },
+            { type: "toolCall", id: "call-showcase-edit", toolName: "edit", arguments: editArgs },
+            { type: "text", text: "Visual snapshots now cover the polished desktop and mobile states.\n\n![pi-web workflow](/api/artifacts/e2e-test.jpg)" },
+          ], timestamp: new Date().toISOString() });
+          appendMockMessage({ role: "toolResult", toolCallId: "call-showcase-read", toolName: "read", content: "session drawer CSS and responsive composer styles", timestamp: new Date().toISOString() });
+          appendMockMessage({ role: "toolResult", toolCallId: "call-showcase-edit", toolName: "edit", toolArgs: editArgs, content: "Successfully replaced 1 block(s) in /Users/ashwin/projects/pi-web/src/style.css.", timestamp: new Date().toISOString() });
+        } else if (withEditTool || withMalformedEditTool) {
+          const editArgs = withMalformedEditTool
+            ? { path: "/some/file.ts", edits: [{ newText: "const answer = 42;" }, { oldText: "console.log(answer);" }] }
+            : { path: "/some/file.ts", edits: [{ oldText: "const answer = 41;\nconsole.log(answer);", newText: "const answer = 42;\nconsole.info(answer);" }] };
+          broadcast({ type: "pi_event", sessionId: mockSession.sessionId, sessionFile: mockSession.sessionFile, event: { type: "tool_execution_start", toolName: "edit", toolCallId: "call-edit", args: editArgs } });
+          await new Promise((resolve) => setTimeout(resolve, 80));
+          broadcast({ type: "pi_event", sessionId: mockSession.sessionId, sessionFile: mockSession.sessionFile, event: { type: "tool_execution_end", toolName: "edit", toolCallId: "call-edit", isError: false, result: "Successfully replaced 1 block(s) in /some/file.ts." } });
+          appendMockMessage({ role: "assistant", content: [{ type: "toolCall", id: "call-edit", toolName: "edit", arguments: editArgs }], timestamp: new Date().toISOString() });
+          appendMockMessage({ role: "toolResult", toolCallId: "call-edit", toolName: "edit", toolArgs: editArgs, content: "Successfully replaced 1 block(s) in /some/file.ts.", timestamp: new Date().toISOString() });
+        } else if (withTools) {
+          const toolCallId = withPendingToolRefresh ? `call-pending-${Date.now()}` : "call-1";
+          broadcast({ type: "pi_event", sessionId: mockSession.sessionId, sessionFile: mockSession.sessionFile, event: { type: "message_update", assistantMessageEvent: { type: "text_delta", delta: "Let me check that for you. " } } });
+          await new Promise((resolve) => setTimeout(resolve, 80));
+          broadcast({ type: "pi_event", sessionId: mockSession.sessionId, sessionFile: mockSession.sessionFile, event: { type: "tool_execution_start", toolName: "read", toolCallId, args: { path: "/some/file" } } });
+          if (withPendingToolRefresh) {
+            appendMockMessage({ role: "assistant", content: [
+              { type: "text", text: "Let me check that for you. " },
+              { type: "toolCall", id: toolCallId, toolName: "read", arguments: { path: "/some/file" } },
+            ], timestamp: new Date().toISOString() });
+          }
+          await new Promise((resolve) => setTimeout(resolve, withPendingToolRefresh ? 3_000 : 150));
+          broadcast({ type: "pi_event", sessionId: mockSession.sessionId, sessionFile: mockSession.sessionFile, event: { type: "tool_execution_end", toolName: "read", toolCallId, isError: false, result: "file contents here" } });
+          await new Promise((resolve) => setTimeout(resolve, 80));
+          broadcast({ type: "pi_event", sessionId: mockSession.sessionId, sessionFile: mockSession.sessionFile, event: { type: "message_update", assistantMessageEvent: { type: "text_delta", delta: "Done reading." } } });
+          await new Promise((resolve) => setTimeout(resolve, 80));
+          if (!withPendingToolRefresh) {
+            appendMockMessage({ role: "assistant", content: [
+              { type: "text", text: "Let me check that for you. " },
+              { type: "toolCall", id: toolCallId, toolName: "read", arguments: { path: "/some/file" } },
+              { type: "text", text: "Done reading." },
+            ], timestamp: new Date().toISOString() });
+          }
+          appendMockMessage({ role: "toolResult", toolCallId, toolName: "read", content: "file contents here", timestamp: new Date().toISOString() });
+        } else if (/markdown artifact/i.test(message)) {
+          appendMockMessage({ role: "assistant", content: "Here is a markdown artifact:\n\n[report.md](/api/artifacts/report.md)", timestamp: new Date().toISOString() });
+        } else if (/html artifact/i.test(message)) {
+          appendMockMessage({ role: "assistant", content: "Here is an HTML artifact:\n\n[preview.html](/api/artifacts/preview.html)", timestamp: new Date().toISOString() });
+        } else if (/video artifact/i.test(message)) {
+          appendMockMessage({ role: "assistant", content: "Here is a video artifact:\n\n[e2e-video-artifact.webm](/api/artifacts/e2e-video-artifact.webm)", timestamp: new Date().toISOString() });
+        } else if (/artifact/i.test(message)) {
+          appendMockMessage({ role: "assistant", content: "Here is a screenshot:\n\n![e2e-test](/api/artifacts/e2e-test.png)", timestamp: new Date().toISOString() });
+        } else if (/markdown/i.test(message)) {
+          appendMockMessage({ role: "assistant", content: "Here is **bold** markdown.\n\n- one\n- two\n\n```ts\nconst answer = 42;\n```", timestamp: new Date().toISOString() });
+        } else {
+          appendMockMessage({ role: "assistant", content: `Mock response${promptOptions?.images?.length ? " with image" : ""}.`, timestamp: new Date().toISOString() });
+        }
+        mockSession.isStreaming = false;
+        broadcastRuntimeChanged();
+        broadcast({ type: "pi_event", sessionId: mockSession.sessionId, sessionFile: mockSession.sessionFile, event: { type: "agent_end" } });
+        if (isCurrentSession(mockSession)) broadcast({ type: "state_changed", ...currentState() as object });
+      },
+      abort: async () => { mockSession.isStreaming = false; broadcastRuntimeChanged(); },
+      abortCompaction: () => { compactionAbortRequested = true; },
+      clearQueue: () => undefined,
+      subscribe: () => undefined,
+    };
+    return mockSession;
+  }
+
+  return { mockSessions, createMockSession, resetMockSessions };
+}