@codeyam/codeyam-cli 0.1.0-staging.ae0de75 → 0.1.0-staging.b147f46

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

@@ -5,6 +5,100 @@ import fs from 'fs';
 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
@@ -52,7 +146,7 @@ const ENV_PASSTHROUGH_KEYS = [
     'HOMEBREW_CELLAR',
     'HOMEBREW_REPOSITORY',
 ];
-function buildPtyEnv() {
+export function buildPtyEnv(options) {
     const env = {};
     for (const key of ENV_PASSTHROUGH_KEYS) {
         const val = process.env[key];
@@ -62,6 +156,11 @@ 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;
 }
 /**
@@ -190,7 +289,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-preview\``);
+        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;
@@ -227,9 +326,15 @@ 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 → extract → glossary → analyze → app scenarios → user scenarios → verify → review)',
-            '- Each feature follows 11 steps: `codeyam editor 1` through `codeyam editor 11`',
-            '- Steps 1, 3, and 11 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:' +
@@ -242,9 +347,9 @@ function writeEditorModeContext(ctx) {
                 ' for health** — the proxy returns 200 even when the app is broken',
             '',
             '## API Endpoints',
-            `- **Register scenario (auto-captures screenshot):** \`codeyam editor register '{"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/navigate preview:** \`curl -X POST http://localhost:${serverPort}/api/dev-mode-preview\` (no body = refresh; with \`{"path":"/route"}\` = navigate; with \`{"scenarioSlug":"..."}\` = switch scenario). Clears logs, waits for HMR, checks SSR health.`,
+            `- **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"}'\``,
@@ -261,17 +366,19 @@ function writeEditorModeContext(ctx) {
             '- POST/PUT/DELETE always go through to the real dev server',
             '',
             '## Component Isolation Routes',
-            '- To screenshot individual components, create ONE isolation route per component:',
-            '  - **Remix:** `app/routes/codeyam-isolate.ComponentName.tsx` → `/codeyam-isolate/ComponentName`',
-            '  - **Next.js:** `app/codeyam-isolate/ComponentName/page.tsx` → `/codeyam-isolate/ComponentName`',
+            '- 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`',
             '- The route defines a `scenarios` object mapping scenario names to props, reads `?s=ScenarioName` from the URL, and renders the component',
-            '- Wrap the component in a centered container: `<div style="display:flex;justify-content:center;align-items:center;min-height:100vh;padding:20px"><div style="width:100%;max-width:...">` — set max-width to match the component\'s real container (e.g. card in 3-col grid → 24rem)',
+            '- 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)',
             '- **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":"/codeyam-isolate/ComponentName?s=Scenario","mockData":{"routes":{"/api/...":{"body":[...]}}}}\'`',
+            '- 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 `**/codeyam-isolate*` so they are not committed',
+            '- Ensure `.gitignore` includes `**/isolated-components*` so they are not committed',
             '',
             '## Files',
             '- **Scenario data:** .codeyam/editor-scenarios/{scenario-id}.json',
@@ -285,7 +392,7 @@ 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('');
         }
         fs.writeFileSync(contextPath, lines.join('\n'), 'utf8');
@@ -325,6 +432,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}`);
@@ -338,6 +451,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);
@@ -364,13 +480,27 @@ export function attachTerminalServer(httpServer) {
             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' }));
                     }
@@ -378,14 +508,12 @@ export function attachTerminalServer(httpServer) {
                     if (transformed.length > 0) {
                         ws.send(JSON.stringify({ type: 'output', data: transformed }));
                     }
-                    const stripped = data.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
-                    if (stripped.includes('Editor Mode \u2014')) {
-                        console.log('[terminalServer] Detected claude-idle signal (reconnect)');
-                        ws.send(JSON.stringify({ type: 'claude-idle' }));
-                    }
+                    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();
@@ -396,6 +524,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) {
@@ -428,7 +557,7 @@ export function attachTerminalServer(httpServer) {
                 cols: 120,
                 rows: 30,
                 cwd: safeCwd,
-                env: buildPtyEnv(),
+                env: buildPtyEnv({ editorMode }),
             });
         }
         catch (error) {
@@ -468,9 +597,41 @@ export function attachTerminalServer(httpServer) {
                 projectSlug,
             });
         let hasClearedScreen = false;
-        // Rolling buffer of trailing text to detect "Editor Mode —" across PTY chunks.
-        let idleDetectBuffer = '';
-        const IDLE_MARKER = 'Editor Mode \u2014';
+        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
@@ -478,35 +639,37 @@ export function attachTerminalServer(httpServer) {
         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' }));
-                }
-                // 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 }));
-                }
-                // Detect the Stop hook output — signals Claude is waiting for user input.
-                // The hook outputs "Editor Mode —" when Claude finishes a turn.
-                // Strip ANSI escape codes and check buffer+current to handle cross-chunk splits.
-                const stripped = data.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
-                const combined = idleDetectBuffer + stripped;
-                if (combined.includes(IDLE_MARKER)) {
-                    console.log('[terminalServer] Detected claude-idle signal');
-                    ws.send(JSON.stringify({ type: 'claude-idle' }));
-                    idleDetectBuffer = '';
+                // 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 {
-                    // Keep trailing chars in case the marker spans two chunks
-                    idleDetectBuffer = stripped.slice(-(IDLE_MARKER.length - 1));
+                    // 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);
                 }
             }
         });
         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)) {
@@ -522,6 +685,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) {
@@ -539,11 +703,54 @@ 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 '${claudeSessionId}' '${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 '${resumePrompt}'\r`);
+                }
+                else {
+                    // Fresh session: generate a trackable UUID
+                    const newSessionId = crypto.randomUUID();
+                    const sessionIdPath = path.join(cwd, '.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 '${newSessionId}' '/codeyam-editor'\r`);
+                }
             }
             else if (hasContext) {
                 ptyProcess.write("claude '/codeyam-dev-mode'\r");
@@ -599,10 +806,36 @@ 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(path) {
+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) {
@@ -638,6 +871,45 @@ export function broadcastShowResults() {
     }
     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;
+}
+/**
+ * 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 {
+            if (session.ws.readyState === WebSocket.OPEN) {
+                session.ws.send(msg);
+                count++;
+            }
+        }
+        catch {
+            // Ignore send errors
+        }
+    }
+    return count;
+}
 /**
  * Kill all active PTY sessions and detached PTYs. Call during shutdown.
  */