@codeyam/codeyam-cli 0.1.0-staging.07d8f7b → 0.1.0-staging.08a490f

package/codeyam-cli/src/webserver/terminalServer.js

@@ -2,13 +2,109 @@ var _a, _b;
 import { WebSocketServer, WebSocket } from 'ws';
 import crypto from 'crypto';
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import * as pty from 'node-pty';
+import { createMarkerTransformer } from "../utils/scenarioMarkers.js";
+import { IdleDetector } from "./idleDetector.js";
+import { mockStateEventEmitter } from "./mockStateEvents.js";
+/**
+ * Strip the raw `claude ...` shell command from suppressed PTY output
+ * so it doesn't leak to the user in the fallback timeout path.
+ */
+export function stripClaudeCommand(output) {
+    // Find the line containing the claude command and strip everything before
+    // and including it (shell prompt, ANSI codes, command echo). Preserve any
+    // real output that follows.
+    const idx = output.indexOf('claude ');
+    if (idx === -1)
+        return output;
+    // Find the end of the command line (\r or \n after "claude")
+    let end = idx;
+    while (end < output.length && output[end] !== '\r' && output[end] !== '\n') {
+        end++;
+    }
+    // Skip past trailing \r\n
+    while (end < output.length &&
+        (output[end] === '\r' || output[end] === '\n')) {
+        end++;
+    }
+    // Strip leading ANSI escape sequences from the remainder
+    // (e.g. bracketed paste mode toggles like \x1b[?2004l)
+    let rest = output.slice(end);
+    rest = rest.replace(/^(\x1b\[[\x20-\x3f]*[\x40-\x7e]|\x1b[()][A-Z0-9])*/, '');
+    return rest;
+}
+/**
+ * Detect whether a PTY output chunk contains Claude Code's welcome banner.
+ * Supports both the old box-drawing format (`╭─── Claude Code ───╮`)
+ * and the new block-art format (`▐▛███▜▌   Claude Code`).
+ */
+export function isBannerChunk(data) {
+    // Strip ANSI escape sequences before checking — Claude Code's Ink renderer
+    // inserts SGR color codes between the banner characters (e.g. ▐\x1b[48;5;16m▛).
+    const plain = data.replace(/\x1b\[[0-9;?]*[A-Za-z]|\x1b\][^\x07]*\x07|\x1b[()][A-Z0-9]/g, '');
+    return plain.includes('╭') || plain.includes('▐▛');
+}
+/**
+ * Determine whether the startup output filter should be active.
+ * The filter strips the raw `claude --session-id ...` command from the
+ * terminal so the user never sees it.
+ */
+export function shouldFilterStartup(opts) {
+    return opts.hasContext || opts.editorMode;
+}
+/**
+ * Manages PTY output suppression during Claude startup.
+ *
+ * Suppresses all output until the welcome banner arrives, then clears
+ * the screen. The claude command is stripped from any chunk that is forwarded
+ * (both the banner chunk on the normal path and the buffered output on the
+ * fallback timeout path).
+ */
+export class StartupOutputFilter {
+    constructor() {
+        this.hasClearedScreen = false;
+        this.suppressedOutput = '';
+    }
+    /**
+     * Process a PTY data chunk. Returns an object describing what action to take:
+     * - `type: 'suppress'` — buffer the chunk, send nothing
+     * - `type: 'clear-and-send'` — clear screen, then send `data`
+     * - `type: 'send'` — send `data` as-is (post-startup)
+     */
+    processChunk(data) {
+        if (!this.hasClearedScreen && isBannerChunk(data)) {
+            this.hasClearedScreen = true;
+            const cleaned = stripClaudeCommand(data);
+            return { type: 'clear-and-send', data: cleaned };
+        }
+        if (!this.hasClearedScreen) {
+            this.suppressedOutput += data;
+            return { type: 'suppress' };
+        }
+        return { type: 'send', data };
+    }
+    /**
+     * Called when the fallback timeout fires (╭ never arrived).
+     * Returns the buffered output with the command stripped, or null if
+     * the screen was already cleared.
+     */
+    getTimeoutOutput() {
+        if (this.hasClearedScreen)
+            return null;
+        this.hasClearedScreen = true;
+        if (this.suppressedOutput.length === 0)
+            return null;
+        const cleaned = stripClaudeCommand(this.suppressedOutput);
+        return cleaned.length > 0 ? cleaned : null;
+    }
+}
 // Use globalThis so the sessions Set is shared across module instances.
 // In Vite dev mode, this file is loaded twice: once by the Vite plugin (Node.js native)
 // and once by the SSR context (ssrLoadModule). Without globalThis, each instance
 // gets its own empty Set — so broadcastPreviewRefresh() called from the SSR instance
-// (via the /api/dev-mode-refresh endpoint) would broadcast to 0 sessions.
+// (via the /api/dev-mode-preview endpoint) would broadcast to 0 sessions.
 const sessions = ((_a = globalThis).__codeyamTerminalSessions ?? (_a.__codeyamTerminalSessions = new Set()));
 // Detached PTYs waiting for reconnection (keyed by sessionId).
 // When a WebSocket drops, the PTY is moved here with a grace timer
@@ -51,9 +147,25 @@ const ENV_PASSTHROUGH_KEYS = [
     'HOMEBREW_CELLAR',
     'HOMEBREW_REPOSITORY',
 ];
-function buildPtyEnv() {
+// Additional env vars needed on Windows
+const WINDOWS_ENV_PASSTHROUGH_KEYS = [
+    'USERPROFILE',
+    'APPDATA',
+    'LOCALAPPDATA',
+    'COMSPEC',
+    'SystemRoot',
+    'TEMP',
+    'TMP',
+    // Nodist (Windows Node.js version manager)
+    'NODIST_PREFIX',
+    'NODIST_X64',
+];
+export function buildPtyEnv(options) {
     const env = {};
-    for (const key of ENV_PASSTHROUGH_KEYS) {
+    const keys = process.platform === 'win32'
+        ? [...ENV_PASSTHROUGH_KEYS, ...WINDOWS_ENV_PASSTHROUGH_KEYS]
+        : ENV_PASSTHROUGH_KEYS;
+    for (const key of keys) {
         const val = process.env[key];
         if (val != null)
             env[key] = val;
@@ -61,8 +173,56 @@ function buildPtyEnv() {
     // Always set TERM for proper terminal behavior
     if (!env.TERM)
         env.TERM = 'xterm-256color';
+    // Signal to hooks that this is an editor Build session.
+    // Without this, editor hooks fire in ALL Claude sessions in the project.
+    if (options?.editorMode) {
+        env.CODEYAM_EDITOR_ACTIVE = '1';
+    }
     return env;
 }
+/**
+ * Returns the shell executable and arguments for PTY spawning,
+ * handling platform differences (Windows uses cmd.exe, Unix uses $SHELL).
+ * cmd.exe is preferred over PowerShell on Windows because:
+ *  - .cmd shims run in-process (no window flash from subprocess spawning)
+ *  - No execution policy restrictions blocking .ps1 scripts
+ *  - Faster startup (no profile loading)
+ */
+export function getShellConfig() {
+    if (process.platform === 'win32') {
+        return { shell: 'cmd.exe', args: [] };
+    }
+    const defaultShell = process.platform === 'darwin' ? '/bin/zsh' : '/bin/sh';
+    return {
+        shell: process.env.SHELL || defaultShell,
+        args: ['-l'],
+    };
+}
+/**
+ * Quote a shell argument for the current platform.
+ * Unix shells use single quotes; cmd.exe uses double quotes.
+ */
+export function shellQuote(arg) {
+    if (process.platform === 'win32') {
+        return `"${arg.replace(/"/g, '""')}"`;
+    }
+    return `'${arg}'`;
+}
+/**
+ * Returns a safe working directory for the PTY, falling back through
+ * CODEYAM_ROOT_PATH → cwd → HOME/USERPROFILE → os.tmpdir().
+ */
+export function getSafeCwd() {
+    const cwd = process.env.CODEYAM_ROOT_PATH || process.cwd();
+    if (fs.existsSync(cwd))
+        return cwd;
+    const home = process.platform === 'win32'
+        ? process.env.USERPROFILE || process.env.HOME
+        : process.env.HOME;
+    if (home && fs.existsSync(home))
+        return home;
+    return os.tmpdir();
+}
 /**
  * Convert a name to a safe file name matching CodeYam's convention.
  * e.g. "Default Scenario" -> "Default_Scenario"
@@ -189,7 +349,7 @@ function writeDevModeContext(ctx) {
         // Server
         const serverPort = process.env.CODEYAM_PORT || '3111';
         lines.push('## Server');
-        lines.push(`- **Refresh preview:** \`curl -X POST http://localhost:${serverPort}/api/dev-mode-refresh\``);
+        lines.push(`- **Refresh preview:** \`curl -X POST http://localhost:${serverPort}/api/dev-mode-preview -H 'Content-Type: application/json' -d '{"dimension":"Desktop"}'\` (dimension is REQUIRED)`);
         lines.push('');
         fs.writeFileSync(contextPath, lines.join('\n'), 'utf8');
         return true;
@@ -226,28 +386,34 @@ function writeEditorModeContext(ctx) {
             `- **Proxy:** http://localhost:${proxyPort} (used by the browser iframe only — do NOT use for health checks)`,
             '',
             '## Workflow',
-            '- **Guided steps:** Run `codeyam editor` for the next step (plan → prototype → confirm → deconstruct → glossary → analyze → app scenarios → user scenarios → verify → review)',
-            '- Each feature follows 10 steps: `codeyam editor 1` through `codeyam editor 10`',
-            '- Steps 1, 3, and 10 require user confirmation before proceeding',
+            '- **Guided steps:** Run `codeyam editor steps` for the next step (plan → prepare → prototype → verify prototype → confirm → deconstruct → extract → glossary → analyze → app scenarios → user scenarios → verify → journal → review → present → commit → finalize → push)',
+            '- Each feature follows 18 steps — run `codeyam editor steps` to see what to do next. Never expose `codeyam editor` commands to the user.',
+            '- **Run ONE step at a time.** Read the FULL output, complete every checklist item, then advance. NEVER batch-run steps in a loop or delegate them to a subagent.',
+            '- Steps 1, 5, 15, and 18 require user confirmation before proceeding',
+            '',
+            '## Preview Updates',
+            '- **Refresh the preview frequently** — the user watches the preview as you work. Refresh after every meaningful change (new page, UI section, data seeding, styling), not just at the end.',
+            `- **Refresh command:** \`curl -s -X POST http://localhost:${serverPort}/api/dev-mode-preview -H 'Content-Type: application/json' -d '{"dimension":"Desktop"}'\` (dimension is REQUIRED)`,
+            '- Aim for 4-8+ preview updates during a typical building session.',
             '',
             '## Verifying the Dev Server',
             '- Get the dev server URL: `curl -s http://localhost:' +
                 serverPort +
                 '/api/editor-dev-server` → look at the `"url"` field (e.g., `http://localhost:3000`)',
-            '- Check the page loads: `curl -s -o /dev/null -w "%{http_code}" http://localhost:3000` (use the actual dev server URL, NOT the proxy)',
-            '- Check API routes work: `curl -s http://localhost:3000/api/your-route` (should return JSON, not "Internal Server Error")',
+            '- Verify pages and API routes: `codeyam editor verify-routes \'{"paths":["/"],"apiRoutes":["/api/your-route"]}\'` (checks HTTP status and JSON validity)',
             '- **NEVER check localhost:' +
                 proxyPort +
                 ' for health** — the proxy returns 200 even when the app is broken',
             '',
             '## API Endpoints',
-            `- **Register scenario (auto-captures screenshot):** \`curl -X POST http://localhost:${serverPort}/api/editor-register-scenario -H 'Content-Type: application/json' -d '{"name":"...","description":"...","mockData":{"routes":{"/api/tasks":{"body":[...]}}}}\``,
+            `- **Register scenario (auto-captures screenshot):** \`codeyam editor register '{"name":"...","url":"/page-to-screenshot","type":"application","seed":{...}}'\` — ALWAYS include "url" for the page to screenshot. For large payloads, write JSON to a file and use @ prefix: \`codeyam editor register @/tmp/scenario.json\``,
             `- **Get active scenario data:** \`curl http://localhost:${serverPort}/api/editor-scenario-data\``,
-            `- **Refresh preview:** \`curl -X POST http://localhost:${serverPort}/api/dev-mode-refresh\``,
+            `- **Refresh/navigate/switch preview:** \`curl -X POST http://localhost:${serverPort}/api/dev-mode-preview -H 'Content-Type: application/json' -d '{"dimension":"Desktop"}'\` (dimension is REQUIRED in every call; add \`"path":"/route"\` to navigate; add \`"scenarioId":"..."\` to switch scenario). Clears logs, waits for HMR, checks SSR health.`,
             `- **Refresh config:** \`curl -X POST http://localhost:${serverPort}/api/editor-refresh\` (also starts dev server if a webapp is detected)`,
             `- **Dev server status:** \`curl http://localhost:${serverPort}/api/editor-dev-server\``,
             `- **Start dev server:** \`curl -X POST http://localhost:${serverPort}/api/editor-dev-server -H 'Content-Type: application/json' -d '{"action":"start"}'\``,
             `- **Restart dev server:** \`curl -X POST http://localhost:${serverPort}/api/editor-dev-server -H 'Content-Type: application/json' -d '{"action":"restart"}'\``,
+            `- **Feature complete (after push):** \`curl -s -X POST http://localhost:${serverPort}/api/editor-feature-complete\` — signals the UI that the feature is done. Call this after step 18 push/skip, then STOP.`,
             `- **Re-capture scenario screenshot:** \`curl -X POST http://localhost:${serverPort}/api/editor-capture-scenario -H 'Content-Type: application/json' -d '{"scenarioId":"...","url":"..."}'\` (for manual re-capture; register auto-captures)`,
             `- **Journal screenshot:** \`curl -X POST http://localhost:${serverPort}/api/editor-journal-screenshot -H 'Content-Type: application/json' -d '{"url":"...","filename":"..."}'\``,
             `- **Journal entry:** \`curl -X POST http://localhost:${serverPort}/api/editor-journal-entry -H 'Content-Type: application/json' -d '{"title":"...","type":"feature","description":"..."}'\``,
@@ -259,6 +425,23 @@ function writeEditorModeContext(ctx) {
             '- The proxy intercepts GET requests to matching routes and returns the mock data',
             '- POST/PUT/DELETE always go through to the real dev server',
             '',
+            '## Component Isolation Routes',
+            '- Create isolation route dirs: `codeyam editor isolate ComponentA ComponentB ...`',
+            '  - This creates the layout guard and a directory per component under `app/isolated-components/`',
+            '- Create ONE isolation route page per component:',
+            '  - **Remix:** `app/routes/isolated-components.ComponentName.tsx` → `/isolated-components/ComponentName`',
+            '  - **Next.js:** `app/isolated-components/ComponentName/page.tsx` → `/isolated-components/ComponentName`',
+            '  - **Expo:** `app/isolated-components/ComponentName.tsx` → `/isolated-components/ComponentName` (use `useLocalSearchParams` from expo-router)',
+            '- The route defines a `scenarios` object mapping scenario names to props, reads `?s=ScenarioName` from the URL, and renders the component',
+            '- For web apps: Wrap the component in a centered container: `<div style="display:flex;justify-content:center;align-items:center;min-height:100vh"><div style="width:100%;max-width:...">` — set max-width to match the component\'s real container (e.g. card in 3-col grid → 24rem)',
+            '- For Expo: Wrap with `<View nativeID="codeyam-capture">` (nativeID maps to id on web for screenshot capture)',
+            '- **Create multiple scenarios per component** (like tests): default/happy path, edge cases (empty data, long text, max items), different visual states (loading, error, disabled)',
+            '- Register each scenario: `codeyam editor register \'{"name":"ComponentName - Scenario","componentName":"ComponentName","componentPath":"path/to/file.tsx","url":"/isolated-components/ComponentName?s=Scenario","mockData":{"routes":{"/api/...":{"body":[...]}}}}\'`',
+            '- The url is a PATH, not a full URL — the proxy appends it and intercepts API calls the component makes',
+            '- `mockData.routes` provides data for any API calls the component makes internally (omit if none)',
+            '- Isolation routes stay in the project so the editor preview can display them',
+            '- Ensure `.gitignore` includes `**/isolated-components*` so they are not committed',
+            '',
             '## Files',
             '- **Scenario data:** .codeyam/editor-scenarios/{scenario-id}.json',
             '- **Scenario screenshots:** .codeyam/editor-scenarios/screenshots/{scenario-id}.png',
@@ -271,9 +454,21 @@ function writeEditorModeContext(ctx) {
         const hasPackageJson = fs.existsSync(path.join(codeyamRoot, 'package.json'));
         if (!hasPackageJson) {
             lines.push('## Status');
-            lines.push('- **Empty project** — no package.json found. Ask the user what they want to build.');
+            lines.push('- **Empty project** — no package.json found. Run `codeyam editor steps` to begin.');
             lines.push('');
         }
+        // Include handoff context if a provider switch generated one
+        try {
+            const handoffContextPath = path.join(codeyamRoot, '.codeyam', 'handoff-context.md');
+            if (fs.existsSync(handoffContextPath)) {
+                lines.push('');
+                lines.push(fs.readFileSync(handoffContextPath, 'utf8'));
+                lines.push('');
+            }
+        }
+        catch {
+            // Non-fatal
+        }
         fs.writeFileSync(contextPath, lines.join('\n'), 'utf8');
         return true;
     }
@@ -311,6 +506,12 @@ export function attachTerminalServer(httpServer) {
         }
     }, PING_INTERVAL_MS);
     globalThis.__codeyamPingInterval = pingInterval;
+    // Subscribe to mock state events and broadcast to all terminal clients
+    mockStateEventEmitter.on('event', (event) => {
+        if (event.type === 'data-mutation-forwarded') {
+            broadcastDataMutationForwarded(event.method, event.pathname);
+        }
+    });
     wss.on('connection', (ws, req) => {
         // Parse entity context from query params
         const url = new URL(req.url || '', `http://${req.headers.host}`);
@@ -324,6 +525,9 @@ export function attachTerminalServer(httpServer) {
         const projectSlug = url.searchParams.get('projectSlug') || '';
         const editorMode = url.searchParams.get('editorMode') === 'true';
         const reconnectId = url.searchParams.get('reconnectId') || '';
+        const claudeStartMode = url.searchParams.get('claudeStartMode') || '';
+        const claudeSessionId = url.searchParams.get('claudeSessionId') || '';
+        const editorStepLabel = url.searchParams.get('editorStepLabel') || '';
         // --- Reconnection: reattach to a detached PTY ---
         if (reconnectId && detachedPtys.has(reconnectId)) {
             const detached = detachedPtys.get(reconnectId);
@@ -348,20 +552,42 @@ export function attachTerminalServer(httpServer) {
             // and was buffering output into detached.outputBuffer. We need to replace it.
             // Unfortunately node-pty doesn't expose removeListener, so we use a closure flag.
             let detachedFlag = false;
+            const reconnectPort = process.env.CODEYAM_PORT || '3111';
+            const reconnectTransformMarkers = createMarkerTransformer(reconnectPort);
+            const reconnectIdleDetector = new IdleDetector({
+                onIdle: () => {
+                    if (ws.readyState === WebSocket.OPEN) {
+                        console.log('[terminalServer] Sending claude-idle (reconnected)');
+                        ws.send(JSON.stringify({ type: 'claude-idle' }));
+                    }
+                },
+                onActive: () => {
+                    if (ws.readyState === WebSocket.OPEN) {
+                        console.log('[terminalServer] Sending claude-active (reconnected)');
+                        ws.send(JSON.stringify({ type: 'claude-active' }));
+                    }
+                },
+            }, { activeOutputPattern: /[✶✢·◼]/ });
             detached.ptyProcess.onData((data) => {
                 if (detachedFlag)
                     return; // Superseded by a newer listener
                 if (ws.readyState === WebSocket.OPEN) {
                     if (!detached.hasClearedScreen &&
                         detached.hasContext &&
-                        data.includes('╭')) {
+                        isBannerChunk(data)) {
                         detached.hasClearedScreen = true;
                         ws.send(JSON.stringify({ type: 'output', data: '\x1b[2J\x1b[H' }));
                     }
-                    ws.send(JSON.stringify({ type: 'output', data }));
+                    const transformed = reconnectTransformMarkers(data);
+                    if (transformed.length > 0) {
+                        ws.send(JSON.stringify({ type: 'output', data: transformed }));
+                    }
+                    reconnectIdleDetector.onPtyOutput(data);
                 }
             });
             detached.ptyProcess.onExit(() => {
+                console.log('[terminalServer] PTY exited (reconnected), flushing idle state');
+                reconnectIdleDetector.disposeAndFlush();
                 sessions.delete(session);
                 if (ws.readyState === WebSocket.OPEN) {
                     ws.close();
@@ -372,6 +598,7 @@ export function attachTerminalServer(httpServer) {
                 try {
                     const msg = JSON.parse(raw.toString());
                     if (msg.type === 'input') {
+                        reconnectIdleDetector.onUserInput();
                         detached.ptyProcess.write(msg.data);
                     }
                     else if (msg.type === 'resize' && msg.cols && msg.rows) {
@@ -392,19 +619,17 @@ export function attachTerminalServer(httpServer) {
             return;
         }
         // --- New connection: spawn a fresh PTY ---
-        const shell = process.env.SHELL || '/bin/zsh';
-        const cwd = process.env.CODEYAM_ROOT_PATH || process.cwd();
-        // Verify cwd exists, fall back to HOME
-        const safeCwd = fs.existsSync(cwd) ? cwd : process.env.HOME || '/tmp';
+        const { shell, args: shellArgs } = getShellConfig();
+        const safeCwd = getSafeCwd();
         // Spawn PTY with a clean env (no giant JSON blobs from CODEYAM_PROJECT etc.)
         let ptyProcess;
         try {
-            ptyProcess = pty.spawn(shell, ['-l'], {
+            ptyProcess = pty.spawn(shell, shellArgs, {
                 name: 'xterm-256color',
                 cols: 120,
                 rows: 30,
                 cwd: safeCwd,
-                env: buildPtyEnv(),
+                env: buildPtyEnv({ editorMode }),
             });
         }
         catch (error) {
@@ -444,19 +669,79 @@ export function attachTerminalServer(httpServer) {
                 projectSlug,
             });
         let hasClearedScreen = false;
+        const filterStartup = shouldFilterStartup({ hasContext, editorMode });
+        const startupFilter = filterStartup ? new StartupOutputFilter() : null;
+        // Safety timeout: stop suppressing output after 5s even if ╭ never arrives.
+        // Prevents "Starting Claude..." hanging forever if the banner format changes.
+        if (filterStartup) {
+            setTimeout(() => {
+                const output = startupFilter.getTimeoutOutput();
+                if (output !== null) {
+                    hasClearedScreen = true;
+                    console.log('[terminalServer] Suppression timeout — showing output');
+                    if (ws.readyState === WebSocket.OPEN) {
+                        // Clear the "Starting Claude..." message
+                        ws.send(JSON.stringify({ type: 'output', data: '\x1b[2J\x1b[H' }));
+                        const transformed = transformMarkers(output);
+                        if (transformed.length > 0) {
+                            ws.send(JSON.stringify({ type: 'output', data: transformed }));
+                        }
+                    }
+                }
+            }, 5000);
+        }
+        const idleDetector = new IdleDetector({
+            onIdle: () => {
+                if (ws.readyState === WebSocket.OPEN) {
+                    console.log('[terminalServer] Sending claude-idle');
+                    ws.send(JSON.stringify({ type: 'claude-idle' }));
+                }
+            },
+            onActive: () => {
+                if (ws.readyState === WebSocket.OPEN) {
+                    console.log('[terminalServer] Sending claude-active');
+                    ws.send(JSON.stringify({ type: 'claude-active' }));
+                }
+            },
+        }, { activeOutputPattern: /[✶✢·◼]/ });
         // PTY output -> WebSocket
+        const serverPort = process.env.CODEYAM_PORT || '3111';
+        // Stateful transformer that buffers partial {{scenario:...}} markers
+        // across PTY chunks so they don't appear as raw text.
+        const transformMarkers = createMarkerTransformer(serverPort);
         ptyProcess.onData((data) => {
             if (ws.readyState === WebSocket.OPEN) {
-                // When Claude Code starts (indicated by its box-drawing welcome banner),
-                // clear the screen to hide the raw shell command.
-                if (!hasClearedScreen && hasContext && data.includes('╭')) {
-                    hasClearedScreen = true;
-                    ws.send(JSON.stringify({ type: 'output', data: '\x1b[2J\x1b[H' }));
+                // During startup, suppress output until Claude's welcome banner (╭)
+                // arrives, then clear screen and strip the raw command from the chunk.
+                if (startupFilter && !hasClearedScreen) {
+                    const result = startupFilter.processChunk(data);
+                    if (result.type === 'clear-and-send') {
+                        hasClearedScreen = true;
+                        ws.send(JSON.stringify({ type: 'output', data: '\x1b[2J\x1b[H' }));
+                        if (result.data.length > 0) {
+                            const transformed = transformMarkers(result.data);
+                            if (transformed.length > 0) {
+                                ws.send(JSON.stringify({ type: 'output', data: transformed }));
+                            }
+                        }
+                        idleDetector.onPtyOutput(data);
+                    }
+                    // type === 'suppress': skip sending and idle detection
+                }
+                else {
+                    // Transform {{scenario:Name:ID}} markers into OSC 8 clickable hyperlinks.
+                    // Uses stateful buffering to handle markers split across PTY chunks.
+                    const transformed = transformMarkers(data);
+                    if (transformed.length > 0) {
+                        ws.send(JSON.stringify({ type: 'output', data: transformed }));
+                    }
+                    idleDetector.onPtyOutput(data);
                 }
-                ws.send(JSON.stringify({ type: 'output', data }));
             }
         });
         ptyProcess.onExit(() => {
+            console.log('[terminalServer] PTY exited, flushing idle state');
+            idleDetector.disposeAndFlush();
             sessions.delete(session);
             // Also clean up from detachedPtys if it was detached
             if (detachedPtys.has(sessionId)) {
@@ -472,6 +757,7 @@ export function attachTerminalServer(httpServer) {
             try {
                 const msg = JSON.parse(raw.toString());
                 if (msg.type === 'input') {
+                    idleDetector.onUserInput();
                     ptyProcess.write(msg.data);
                 }
                 else if (msg.type === 'resize' && msg.cols && msg.rows) {
@@ -489,14 +775,57 @@ export function attachTerminalServer(httpServer) {
         ws.on('close', () => {
             detachSession(session, hasContext, hasClearedScreen);
         });
+        // Show a loading indicator while Claude Code starts up.
+        // PTY output is suppressed until Claude's welcome banner (╭) appears
+        // and triggers a screen clear, so the user never sees the raw command.
+        if (filterStartup) {
+            ws.send(JSON.stringify({
+                type: 'output',
+                data: '\x1b[2J\x1b[H\r\n\x1b[90m  Starting Claude...\x1b[0m\r\n',
+            }));
+        }
         // Start Claude Code with the appropriate skill.
         // Using a skill avoids shell escaping issues and multi-line paste detection.
+        //
+        // Session recovery modes (editor only):
+        //   resume + sessionId → claude --resume <uuid> (resumes exact conversation)
+        //   resume, no sessionId → claude --continue (fallback for pre-existing sessions)
+        //   fresh → generate UUID, write to .codeyam/claude-session-id.txt,
+        //           launch claude --session-id <uuid> '/codeyam-editor'
+        //
+        // The UUID is generated HERE (not in printStep1) so it's available before
+        // Claude launches. printStep1 runs inside the session — too late.
         setTimeout(() => {
             if (editorMode && hasContext) {
-                ptyProcess.write("claude '/codeyam-editor'\r");
+                if (claudeStartMode === 'resume' && claudeSessionId) {
+                    const resumePrompt = editorStepLabel === 'Present'
+                        ? 'The session was interrupted. Please rerun show-results.'
+                        : 'The session was interrupted. Please continue where you left off.';
+                    ptyProcess.write(`claude --resume ${shellQuote(claudeSessionId)} ${shellQuote(resumePrompt)}\r`);
+                }
+                else if (claudeStartMode === 'resume') {
+                    // No session ID available — fall back to most recent session
+                    const resumePrompt = editorStepLabel === 'Present'
+                        ? 'The session was interrupted. Please rerun show-results.'
+                        : 'The session was interrupted. Please continue where you left off.';
+                    ptyProcess.write(`claude --continue ${shellQuote(resumePrompt)}\r`);
+                }
+                else {
+                    // Fresh session: generate a trackable UUID
+                    const newSessionId = crypto.randomUUID();
+                    const sessionIdPath = path.join(safeCwd, '.codeyam', 'claude-session-id.txt');
+                    try {
+                        fs.mkdirSync(path.dirname(sessionIdPath), { recursive: true });
+                        fs.writeFileSync(sessionIdPath, newSessionId, 'utf8');
+                    }
+                    catch (err) {
+                        console.error('[terminalServer] Failed to write claude-session-id.txt:', err);
+                    }
+                    ptyProcess.write(`claude --session-id ${shellQuote(newSessionId)} ${shellQuote('/codeyam-editor')}\r`);
+                }
             }
             else if (hasContext) {
-                ptyProcess.write("claude '/codeyam-dev-mode'\r");
+                ptyProcess.write(`claude ${shellQuote('/codeyam-dev-mode')}\r`);
             }
             else {
                 ptyProcess.write('claude\r');
@@ -549,8 +878,116 @@ function detachSession(session, hasContext = false, hasClearedScreen = false) {
  * Send a refresh-preview message to all connected terminal WebSocket clients.
  * The Terminal component relays this to the parent page to reload the iframe.
  */
-export function broadcastPreviewRefresh() {
-    const msg = JSON.stringify({ type: 'refresh-preview' });
+export function broadcastPreviewRefresh(path, scenarioId) {
+    const msg = JSON.stringify({
+        type: 'refresh-preview',
+        ...(path && { path }),
+        ...(scenarioId && { scenarioId }),
+    });
+    let count = 0;
+    for (const session of sessions) {
+        try {
+            if (session.ws.readyState === WebSocket.OPEN) {
+                session.ws.send(msg);
+                count++;
+            }
+        }
+        catch {
+            // Ignore send errors
+        }
+    }
+    return count;
+}
+/**
+ * Notify all connected terminal WebSocket clients that a data mutation
+ * was forwarded to the real dev server (seed-based scenario).
+ * The Terminal component relays this to editor.tsx to show a save banner.
+ */
+export function broadcastDataMutationForwarded(method, pathname) {
+    const msg = JSON.stringify({
+        type: 'data-mutation-forwarded',
+        method,
+        pathname,
+    });
+    let count = 0;
+    for (const session of sessions) {
+        try {
+            if (session.ws.readyState === WebSocket.OPEN) {
+                session.ws.send(msg);
+                count++;
+            }
+        }
+        catch {
+            // Ignore send errors
+        }
+    }
+    return count;
+}
+/**
+ * Show the results panel below the terminal in the Build tab.
+ * Triggered by Claude at end of step 12.
+ */
+export function broadcastShowResults() {
+    const msg = JSON.stringify({ type: 'show-results' });
+    let count = 0;
+    for (const session of sessions) {
+        try {
+            if (session.ws.readyState === WebSocket.OPEN) {
+                session.ws.send(msg);
+                count++;
+            }
+        }
+        catch {
+            // Ignore send errors
+        }
+    }
+    return count;
+}
+/**
+ * Hide the results panel (e.g. after Save & Commit).
+ */
+export function broadcastHideResults() {
+    const msg = JSON.stringify({ type: 'hide-results' });
+    let count = 0;
+    for (const session of sessions) {
+        try {
+            if (session.ws.readyState === WebSocket.OPEN) {
+                session.ws.send(msg);
+                count++;
+            }
+        }
+        catch {
+            // Ignore send errors
+        }
+    }
+    return count;
+}
+/**
+ * Notify the editor UI that the current feature is complete (after push/skip).
+ * The UI shows a transition overlay letting the user start fresh or continue.
+ */
+export function broadcastFeatureComplete() {
+    const msg = JSON.stringify({ type: 'feature-complete' });
+    let count = 0;
+    for (const session of sessions) {
+        try {
+            if (session.ws.readyState === WebSocket.OPEN) {
+                session.ws.send(msg);
+                count++;
+            }
+        }
+        catch {
+            // Ignore send errors
+        }
+    }
+    return count;
+}
+/**
+ * Send a set-viewport message to all connected terminal WebSocket clients.
+ * The Terminal component relays this to the parent page to update the preview viewport.
+ */
+export function broadcastSetViewport(viewport) {
+    const msg = JSON.stringify({ type: 'set-viewport', ...viewport });
     let count = 0;
     for (const session of sessions) {
         try {