@pro-vi/designer 0.3.9 → 0.3.11

package/README.md

@@ -118,7 +118,7 @@ Writes `tasting.html` with variant tabs + 1/2/3 shortcuts + persistent notes, se
 ## Operations
 
 - `designer doctor` — diagnose setup state. Exits 2 on failure.
-- `designer health [--json]` — probe 17 UI anchors. Wire into cron to catch claude.ai UI regressions.
+- `designer health [--json]` — probe every UI anchor designer depends on. Wire into cron to catch claude.ai UI regressions.
 - **Daily CI** in `.github/workflows/`: `daily-health.yml` runs the auth-required UI probe on a self-hosted macOS runner once per day; `ci.yml` typechecks + builds + does a Docker clean-room install smoke on every PR; `release-please.yml` opens a release PR on conventional commits, merging it tags + publishes via `release-publish.yml`. Selector regressions land as auto-opened PRs under the `selectors-drift` label.
 
 ## Known quirks

package/dist/browser.js

@@ -12,9 +12,10 @@ export function createBrowser({ session = DEFAULT_SESSION, headed = true, timeou
     function connectFlags() {
         if (!cdp)
             return [];
+        const scope = ['--session', `designer-cdp-${cdp.replace(/[^a-zA-Z0-9.-]/g, '_')}`];
         if (cdp === 'auto' || cdp === '1' || cdp === 'true')
-            return ['--auto-connect'];
-        return ['--cdp', cdp];
+            return [...scope, '--auto-connect'];
+        return [...scope, '--cdp', cdp];
     }
     function run(args, { input, parseJson = false } = {}) {
         return new Promise((resolve, reject) => {
@@ -64,6 +65,15 @@ export function createBrowser({ session = DEFAULT_SESSION, headed = true, timeou
         activateTab: async (index) => {
             await run(['tab', String(index)]);
         },
+        reload: () => run(['reload']),
+        cookies: async () => {
+            const out = await run(['cookies', 'get', '--json']);
+            const env = JSON.parse(out);
+            if (env.success === false) {
+                throw new Error(`agent-browser cookies get failed: ${JSON.stringify(env.error)}`);
+            }
+            return env.data?.cookies ?? [];
+        },
         snapshot: ({ interactive = true, scope } = {}) => {
             const args = ['snapshot', '--json'];
             if (interactive)

package/dist/cdp-ensure.js

@@ -19,6 +19,9 @@ function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
 export async function ensureCdpUp() {
+    if (process.env.DESIGNER_CDP === '') {
+        throw new Error("CDP explicitly disabled (DESIGNER_CDP=''); using the agent-browser session-managed flow.");
+    }
     if (await isCdpUp())
         return;
     if (!fs.existsSync(PROFILE)) {

package/dist/cdp-trace.js

@@ -0,0 +1,509 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureCdpUp } from "./cdp-ensure.js";
+const DEFAULT_PORT = process.env.DESIGNER_CDP || '9222';
+const DESIGN_URL_PATTERN = /^https:\/\/claude\.ai\/design/;
+const REDACT_KEY_PATTERN = /^(cookie|set-cookie|authorization|proxy-authorization|x-api-key)$/i;
+const STREAMABLE_RESOURCE_TYPES = new Set(['XHR', 'Fetch', 'EventSource']);
+const AUTH_URL_DENYLIST = /\/(oauth|auth|login|logout|sign[_-]?in|sign[_-]?out|sign[_-]?up|register|token|sessions?|account|credential|password|mfa|totp|verify)\b/i;
+export function scrubSecrets(s) {
+    return s
+        .replace(/eyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}/g, '[redacted-jwt]')
+        .replace(/\bsk-[A-Za-z0-9_-]{16,}\b/g, '[redacted-key]')
+        .replace(/(["']?(?:access[_-]?token|refresh[_-]?token|id[_-]?token|session[_-]?key|sessionKey|api[_-]?key|client[_-]?secret|secret|password|passwd|pwd)["']?\s*[:=]\s*["']?)[^"'&,;\s}]+/gi, '$1[redacted]')
+        .replace(/\bsessionKey=[^;"'\s&]+/gi, 'sessionKey=[redacted]')
+        .replace(/\b([Bb]earer)\s+[A-Za-z0-9._~+/=-]{12,}/g, '$1 [redacted]');
+}
+const PERSIST_METHODS = new Set([
+    'Network.requestWillBeSent',
+    'Network.responseReceived',
+    'Network.dataReceived',
+    'Network.loadingFinished',
+    'Network.loadingFailed',
+    'Network.requestServedFromCache',
+    'Network.eventSourceMessageReceived',
+    'Network.webSocketCreated',
+    'Network.webSocketWillSendHandshakeRequest',
+    'Network.webSocketHandshakeResponseReceived',
+    'Network.webSocketFrameSent',
+    'Network.webSocketFrameReceived',
+    'Network.webSocketClosed',
+    'Page.frameNavigated',
+    'Page.frameStartedLoading',
+    'Page.frameStoppedLoading',
+    'Page.lifecycleEvent'
+]);
+function asRec(v) {
+    return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+}
+function isCdpTarget(v) {
+    const r = asRec(v);
+    return (typeof r.id === 'string' &&
+        typeof r.type === 'string' &&
+        typeof r.title === 'string' &&
+        typeof r.url === 'string' &&
+        typeof r.webSocketDebuggerUrl === 'string');
+}
+export function redact(value) {
+    if (Array.isArray(value))
+        return value.map(redact);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = REDACT_KEY_PATTERN.test(k) ? '[redacted]' : redact(v);
+        }
+        return out;
+    }
+    return value;
+}
+export async function listTargets(port = DEFAULT_PORT) {
+    const res = await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(3000) });
+    if (!res.ok)
+        throw new Error(`CDP /json/list on :${port} returned ${res.status}`);
+    const body = await res.json();
+    if (!Array.isArray(body))
+        throw new Error(`CDP /json/list on :${port} returned a non-array payload`);
+    return body.filter(isCdpTarget);
+}
+export async function findDesignTarget({ port = DEFAULT_PORT, urlPattern = DESIGN_URL_PATTERN, preferUrlPrefix = null } = {}) {
+    const targets = await listTargets(port);
+    const candidates = targets.filter((t) => t.type === 'page' && urlPattern.test(t.url) && t.webSocketDebuggerUrl);
+    if (candidates.length === 0) {
+        throw new Error(`No page target matching ${urlPattern} on CDP :${port}. Open claude.ai/design first.`);
+    }
+    if (preferUrlPrefix) {
+        const preferred = candidates.find((t) => t.url.startsWith(preferUrlPrefix));
+        if (preferred)
+            return preferred;
+    }
+    const only = candidates[0];
+    if (candidates.length === 1 && only)
+        return only;
+    throw new Error(`Multiple design tabs match — pass --target-url to disambiguate:\n` +
+        candidates.map((t) => `  ${t.url}`).join('\n'));
+}
+export class CdpSession {
+    ws;
+    target;
+    sessionOpts;
+    stopped = false;
+    reconnects = 0;
+    pending = new Map();
+    socketClosed = false;
+    nextId = 0;
+    constructor(ws, target, opts = {}) {
+        this.ws = ws;
+        this.target = target;
+        this.sessionOpts = {
+            port: opts.port ?? DEFAULT_PORT,
+            urlPattern: opts.urlPattern ?? DESIGN_URL_PATTERN,
+            preferUrlPrefix: opts.preferUrlPrefix ?? null,
+            reconnect: opts.reconnect ?? true
+        };
+        this.wire(ws);
+    }
+    static async connectTarget(opts = {}) {
+        await ensureCdpUp();
+        const target = await findDesignTarget({
+            port: opts.port ?? DEFAULT_PORT,
+            urlPattern: opts.urlPattern,
+            preferUrlPrefix: opts.preferUrlPrefix ?? null
+        });
+        const ws = await this.openSocket(target.webSocketDebuggerUrl);
+        return { ws, target };
+    }
+    static openSocket(url) {
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(url);
+            const onOpen = () => {
+                cleanup();
+                resolve(ws);
+            };
+            const onError = () => {
+                cleanup();
+                reject(new Error(`Failed to open CDP WebSocket ${url}`));
+            };
+            const cleanup = () => {
+                ws.removeEventListener('open', onOpen);
+                ws.removeEventListener('error', onError);
+            };
+            ws.addEventListener('open', onOpen);
+            ws.addEventListener('error', onError);
+        });
+    }
+    targetInfo() {
+        return { url: this.target.url, wsUrl: this.target.webSocketDebuggerUrl, port: this.sessionOpts.port };
+    }
+    async enableDomains() {
+        await this.send('Network.enable', { maxTotalBufferSize: 100_000_000, maxResourceBufferSize: 50_000_000 });
+    }
+    send(method, params, sessionId) {
+        const id = ++this.nextId;
+        const msg = { id, method };
+        if (params !== undefined)
+            msg.params = params;
+        if (sessionId)
+            msg.sessionId = sessionId;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            try {
+                this.ws.send(JSON.stringify(msg));
+            }
+            catch (e) {
+                this.pending.delete(id);
+                reject(e instanceof Error ? e : new Error(String(e)));
+            }
+        });
+    }
+    close() {
+        this.closeSocket();
+    }
+    closeSocket() {
+        if (this.socketClosed)
+            return false;
+        this.socketClosed = true;
+        this.stopped = true;
+        this.rejectPending(new Error('CDP WebSocket closed'));
+        try {
+            this.ws.close();
+        }
+        catch {
+        }
+        return true;
+    }
+    onSocketGap(_detail) { }
+    onSocketReconnected(_target) { }
+    onSocketReconnectFailed(_detail) { }
+    wire(ws) {
+        ws.addEventListener('message', (ev) => {
+            this.onMessage(typeof ev.data === 'string' ? ev.data : String(ev.data));
+        });
+        ws.addEventListener('close', () => {
+            void this.handleClose();
+        });
+    }
+    onMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (!msg || typeof msg !== 'object' || Array.isArray(msg))
+            return;
+        const rec = msg;
+        if (typeof rec.id === 'number') {
+            const p = this.pending.get(rec.id);
+            if (!p)
+                return;
+            this.pending.delete(rec.id);
+            if (rec.error)
+                p.reject(new Error(`CDP ${JSON.stringify(rec.error)}`));
+            else
+                p.resolve(rec.result);
+            return;
+        }
+        const method = typeof rec.method === 'string' ? rec.method : '';
+        if (!method)
+            return;
+        this.onEvent(method, rec.params, typeof rec.sessionId === 'string' ? rec.sessionId : undefined);
+    }
+    rejectPending(error) {
+        for (const [, p] of this.pending)
+            p.reject(error);
+        this.pending.clear();
+    }
+    async handleClose() {
+        this.rejectPending(new Error('CDP WebSocket closed'));
+        if (this.stopped)
+            return;
+        this.onSocketGap({ reason: 'socket-closed' });
+        if (!this.sessionOpts.reconnect)
+            return;
+        for (let i = 0; i < 30 && !this.stopped; i++) {
+            await new Promise((r) => setTimeout(r, 1000));
+            try {
+                const target = await findDesignTarget({
+                    port: this.sessionOpts.port,
+                    urlPattern: this.sessionOpts.urlPattern,
+                    preferUrlPrefix: this.sessionOpts.preferUrlPrefix
+                });
+                const ws = await CdpSession.openSocket(target.webSocketDebuggerUrl);
+                this.ws = ws;
+                this.target = target;
+                this.wire(ws);
+                await this.enableDomains();
+                this.reconnects++;
+                this.onSocketReconnected(target);
+                return;
+            }
+            catch {
+            }
+        }
+        if (!this.stopped)
+            this.onSocketReconnectFailed({ gaveUpAfterMs: 30_000 });
+    }
+}
+export class CdpTraceRecorder extends CdpSession {
+    opts;
+    out;
+    requests = new Map();
+    wsSocketUrls = new Map();
+    pendingBodies = new Set();
+    startedAt = Date.now();
+    total = 0;
+    bodyCaptures = 0;
+    ended = false;
+    byMethod = {};
+    droppedByMethod = {};
+    constructor(ws, target, opts) {
+        super(ws, target, opts);
+        this.opts = {
+            outFile: opts.outFile,
+            port: opts.port ?? DEFAULT_PORT,
+            urlPattern: opts.urlPattern ?? DESIGN_URL_PATTERN,
+            preferUrlPrefix: opts.preferUrlPrefix ?? null,
+            captureBodiesFor: opts.captureBodiesFor ?? /^https:\/\/claude\.ai\//,
+            maxBodyBytesPerRequest: opts.maxBodyBytesPerRequest ?? 2 * 1024 * 1024,
+            reconnect: opts.reconnect ?? true
+        };
+        fs.mkdirSync(path.dirname(opts.outFile), { recursive: true });
+        this.out = fs.createWriteStream(opts.outFile, { flags: 'a' });
+        this.out.on('error', () => { });
+    }
+    static async attach(opts) {
+        if (typeof WebSocket === 'undefined') {
+            throw new Error('Native WebSocket unavailable — cdp-trace requires Node >= 22.');
+        }
+        const { ws, target } = await CdpTraceRecorder.connectTarget(opts);
+        return new CdpTraceRecorder(ws, target, opts);
+    }
+    async start() {
+        this.startedAt = Date.now();
+        await this.enableDomains();
+        this.writeLine({
+            ts: Date.now(),
+            kind: 'recorder',
+            event: 'attach',
+            detail: { targetUrl: this.target.url, wsUrl: this.target.webSocketDebuggerUrl }
+        });
+    }
+    async enableDomains() {
+        await super.enableDomains();
+        await this.send('Page.enable');
+        await this.send('Page.setLifecycleEventsEnabled', { enabled: true });
+    }
+    marker(name, detail) {
+        this.writeLine({ ts: Date.now(), kind: 'recorder', event: 'marker', detail: { name, ...asRec(detail) } });
+    }
+    record(ev) {
+        this.writeLine({ ...ev, ts: ev.ts || Date.now() });
+    }
+    async stop() {
+        this.stopped = true;
+        await Promise.race([
+            Promise.allSettled([...this.pendingBodies]),
+            new Promise((r) => setTimeout(r, 3000))
+        ]);
+        this.writeLine({ ts: Date.now(), kind: 'recorder', event: 'detach' });
+        this.close();
+        this.ended = true;
+        await new Promise((resolve) => this.out.end(resolve));
+        return {
+            durationMs: Date.now() - this.startedAt,
+            total: this.total,
+            byMethod: this.byMethod,
+            droppedByMethod: this.droppedByMethod,
+            reconnects: this.reconnects,
+            bodyCaptures: this.bodyCaptures
+        };
+    }
+    onEvent(method, rawParams, sessionId) {
+        if (!PERSIST_METHODS.has(method)) {
+            this.droppedByMethod[method] = (this.droppedByMethod[method] || 0) + 1;
+            return;
+        }
+        const params = asRec(rawParams);
+        this.trackRequest(method, params);
+        const shaped = this.shapePayloads(method, params);
+        const ev = { ts: Date.now(), kind: 'cdp', method, params: redact(shaped) };
+        if (sessionId)
+            ev.sessionId = sessionId;
+        this.writeLine(ev);
+        this.byMethod[method] = (this.byMethod[method] || 0) + 1;
+        if (method === 'Network.responseReceived')
+            this.maybeStreamContent(params);
+        if (method === 'Network.loadingFinished')
+            this.maybeFetchBody(params);
+    }
+    trackRequest(method, params) {
+        const requestId = typeof params.requestId === 'string' ? params.requestId : null;
+        if (!requestId)
+            return;
+        if (method === 'Network.requestWillBeSent') {
+            const req = asRec(params.request);
+            this.requests.set(requestId, {
+                url: String(req.url || ''),
+                resourceType: typeof params.type === 'string' ? params.type : null,
+                mimeType: null,
+                streamed: false,
+                bodyBytes: 0,
+                bodyFetched: false
+            });
+        }
+        else if (method === 'Network.responseReceived') {
+            const info = this.requests.get(requestId);
+            if (info) {
+                const resp = asRec(params.response);
+                info.mimeType = typeof resp.mimeType === 'string' ? resp.mimeType : null;
+                if (typeof params.type === 'string')
+                    info.resourceType = params.type;
+            }
+        }
+        else if (method === 'Network.webSocketCreated') {
+            this.wsSocketUrls.set(requestId, String(params.url || ''));
+        }
+    }
+    shapePayloads(method, params) {
+        if (method === 'Network.requestWillBeSent') {
+            const req = asRec(params.request);
+            if (typeof req.postData === 'string') {
+                if (!this.opts.captureBodiesFor.test(String(req.url || ''))) {
+                    return { ...params, request: { ...req, postData: undefined, postDataBytes: req.postData.length } };
+                }
+                return { ...params, request: { ...req, postData: scrubSecrets(req.postData) } };
+            }
+            return params;
+        }
+        if (method === 'Network.webSocketFrameSent' || method === 'Network.webSocketFrameReceived') {
+            const requestId = String(params.requestId || '');
+            const socketUrl = this.wsSocketUrls.get(requestId) || '';
+            const resp = asRec(params.response);
+            if (typeof resp.payloadData === 'string') {
+                if (!this.opts.captureBodiesFor.test(socketUrl)) {
+                    return { ...params, response: { ...resp, payloadData: undefined, payloadBytes: resp.payloadData.length } };
+                }
+                return { ...params, response: { ...resp, payloadData: scrubSecrets(resp.payloadData) } };
+            }
+            return params;
+        }
+        if (method === 'Network.dataReceived' && typeof params.data === 'string') {
+            const requestId = String(params.requestId || '');
+            const info = this.requests.get(requestId);
+            const bytes = Math.floor((params.data.length * 3) / 4);
+            if (info) {
+                if (info.bodyBytes + bytes > this.opts.maxBodyBytesPerRequest) {
+                    return { ...params, data: undefined, dataDroppedBytes: bytes, truncated: true };
+                }
+                info.bodyBytes += bytes;
+            }
+            return params;
+        }
+        return params;
+    }
+    maybeStreamContent(params) {
+        const requestId = typeof params.requestId === 'string' ? params.requestId : null;
+        if (!requestId)
+            return;
+        const info = this.requests.get(requestId);
+        if (!info || info.streamed)
+            return;
+        if (!this.opts.captureBodiesFor.test(info.url))
+            return;
+        if (AUTH_URL_DENYLIST.test(info.url))
+            return;
+        if (!info.resourceType || !STREAMABLE_RESOURCE_TYPES.has(info.resourceType))
+            return;
+        const resp = asRec(params.response);
+        const headers = asRec(resp.headers);
+        const hasContentLength = Object.keys(headers).some((k) => k.toLowerCase() === 'content-length');
+        const isSse = info.mimeType === 'text/event-stream';
+        if (!isSse && hasContentLength)
+            return;
+        info.streamed = true;
+        const p = this.send('Network.streamResourceContent', { requestId })
+            .then((result) => {
+            const buffered = String(asRec(result).bufferedData || '');
+            const bytes = Math.floor((buffered.length * 3) / 4);
+            const truncated = bytes > this.opts.maxBodyBytesPerRequest;
+            info.bodyBytes += Math.min(bytes, this.opts.maxBodyBytesPerRequest);
+            this.bodyCaptures++;
+            this.writeLine({
+                ts: Date.now(),
+                kind: 'body',
+                requestId,
+                url: info.url,
+                source: 'streamBuffered',
+                base64: truncated ? buffered.slice(0, Math.ceil((this.opts.maxBodyBytesPerRequest * 4) / 3)) : buffered,
+                truncated,
+                bytes
+            });
+        })
+            .catch(() => {
+            info.streamed = false;
+        })
+            .finally(() => this.pendingBodies.delete(p));
+        this.pendingBodies.add(p);
+    }
+    maybeFetchBody(params) {
+        const requestId = typeof params.requestId === 'string' ? params.requestId : null;
+        if (!requestId || this.stopped)
+            return;
+        const info = this.requests.get(requestId);
+        if (!info || info.streamed || info.bodyFetched)
+            return;
+        if (!this.opts.captureBodiesFor.test(info.url))
+            return;
+        if (AUTH_URL_DENYLIST.test(info.url))
+            return;
+        if (!info.resourceType || !STREAMABLE_RESOURCE_TYPES.has(info.resourceType))
+            return;
+        info.bodyFetched = true;
+        const p = this.send('Network.getResponseBody', { requestId })
+            .then((result) => {
+            const r = asRec(result);
+            const isB64 = r.base64Encoded === true;
+            const body = isB64 ? String(r.body || '') : scrubSecrets(String(r.body || ''));
+            const bytes = isB64 ? Math.floor((body.length * 3) / 4) : body.length;
+            const truncated = bytes > this.opts.maxBodyBytesPerRequest;
+            const cap = isB64 ? Math.ceil((this.opts.maxBodyBytesPerRequest * 4) / 3) : this.opts.maxBodyBytesPerRequest;
+            this.bodyCaptures++;
+            this.writeLine({
+                ts: Date.now(),
+                kind: 'body',
+                requestId,
+                url: info.url,
+                source: 'getResponseBody',
+                base64: isB64 ? (truncated ? body.slice(0, cap) : body) : Buffer.from(truncated ? body.slice(0, cap) : body).toString('base64'),
+                truncated,
+                bytes
+            });
+        })
+            .catch((e) => {
+            this.writeLine({
+                ts: Date.now(),
+                kind: 'recorder',
+                event: 'error',
+                detail: { op: 'getResponseBody', requestId, url: info.url, message: e.message }
+            });
+        })
+            .finally(() => this.pendingBodies.delete(p));
+        this.pendingBodies.add(p);
+    }
+    onSocketGap() {
+        this.writeLine({ ts: Date.now(), kind: 'recorder', event: 'gap', detail: { reason: 'socket-closed' } });
+    }
+    onSocketReconnected(target) {
+        this.writeLine({ ts: Date.now(), kind: 'recorder', event: 'reconnect', detail: { targetUrl: target.url } });
+    }
+    onSocketReconnectFailed(detail) {
+        this.writeLine({ ts: Date.now(), kind: 'recorder', event: 'error', detail: { op: 'reconnect', ...detail } });
+    }
+    writeLine(ev) {
+        if (this.ended)
+            return;
+        this.out.write(JSON.stringify(ev) + '\n');
+        this.total++;
+    }
+}

package/dist/designer-controller.js

@@ -8,6 +8,7 @@ import { sessionDir, saveIteration } from "./artifact-store.js";
 import { upsertSession, appendHistory, getSession } from "./session-store.js";
 import { REPO_ROOT } from "./repo-root.js";
 import { ensureCdpUp } from "./cdp-ensure.js";
+import { RunStateObserver } from "./run-state.js";
 const DESIGN_HOME = 'https://claude.ai/design';
 const FLAT_LAYOUT_SUFFIX = '\n\nFile layout: keep all generated files at the project root. No subfolders.';
 const DECISIVE_SUFFIX = '\n\nIf you would otherwise stop to ask clarifying questions, do not. Choose the most defensible answer for each axis yourself and proceed. Note your assumption in a one-line `<!-- assumed: ... -->` comment at the top of the relevant file so I can override on the next turn.';
@@ -241,16 +242,20 @@ export class DesignerController {
         return true;
       })()`);
     }
-    async sendPrompt(prompt, { decisive = false } = {}) {
+    async sendPrompt(prompt, { decisive = false, onBeforeSubmit } = {}) {
         const before = await this.fetchServedHtml();
         this._preSendHtml = before.html;
         const effective = prompt + FLAT_LAYOUT_SUFFIX + (decisive ? DECISIVE_SUFFIX : '');
+        onBeforeSubmit?.();
         await this._submitPrompt(effective);
         const suffixApplied = decisive ? 'flat_layout+decisive' : 'flat_layout';
         appendHistory(this.key, { kind: 'prompt', prompt, suffixApplied });
         return { ok: true };
     }
     async waitForGenerationDone({ timeoutMs = 20 * 60_000, stabilityMs = 4000, pollMs = 1500 } = {}) {
+        return this._waitForGenerationDoneHtml({ timeoutMs, stabilityMs, pollMs });
+    }
+    async _waitForGenerationDoneHtml({ timeoutMs = 20 * 60_000, stabilityMs = 4000, pollMs = 1500 } = {}) {
         const start = Date.now();
         const preHtml = this._preSendHtml || '';
         let lastHtml = '';
@@ -286,6 +291,36 @@ export class DesignerController {
         }
         return { ok: false, error: 'timeout', elapsedMs: Date.now() - start };
     }
+    async _waitForGenerationDoneNetwork(observer, { timeoutMs = 20 * 60_000, stabilityMs = 4000, pollMs = 1500 } = {}) {
+        const terminal = await observer.awaitTerminal({ hardTimeoutMs: timeoutMs });
+        if (terminal.terminal === 'observer-lost') {
+            return { ok: false, error: 'observer-lost', elapsedMs: terminal.elapsedMs, reason: terminal.reason };
+        }
+        if (terminal.terminal === 'blocked') {
+            return { ok: false, error: 'blocked', elapsedMs: terminal.elapsedMs, reason: terminal.reason };
+        }
+        if (terminal.terminal === 'timeout') {
+            return { ok: false, error: 'stalled', elapsedMs: terminal.elapsedMs, reason: terminal.reason };
+        }
+        let { html, src } = await this.fetchServedHtml();
+        const preHtml = this._preSendHtml || '';
+        const settleDeadline = Date.now() + Math.min(timeoutMs, Math.max(stabilityMs, 12_000));
+        let stableSince = Date.now();
+        while (Date.now() < settleDeadline) {
+            await new Promise((r) => setTimeout(r, pollMs));
+            const next = await this.fetchServedHtml();
+            if (next.html !== html) {
+                html = next.html;
+                src = next.src;
+                stableSince = Date.now();
+            }
+            else if (html !== preHtml && Date.now() - stableSince >= stabilityMs) {
+                break;
+            }
+        }
+        const url = await this.currentUrl();
+        return { ok: true, elapsedMs: terminal.elapsedMs, url, iframeSrc: src, htmlBytes: html.length, html };
+    }
     async snapshotDesign({ html: knownHtml, iframeSrc: knownSrc } = {}) {
         const iframeSrc = knownSrc || (await this.getIframeSrc());
         let html = knownHtml ?? null;
@@ -318,8 +353,34 @@ export class DesignerController {
             await this.openFile(file);
         const preFiles = await this.listFiles().catch(() => []);
         const preChatCount = (await this.getChatTurns()).length;
-        await this.sendPrompt(prompt, { decisive });
-        const done = await this.waitForGenerationDone({ timeoutMs, stabilityMs });
+        const waitBudgetMs = timeoutMs ?? 20 * 60_000;
+        const cdpEnabled = (process.env.DESIGNER_CDP ?? '9222') !== '';
+        let observer = cdpEnabled
+            ? await RunStateObserver.attach({
+                preferUrlPrefix: (await this.currentUrl()).split('?')[0] || null
+            })
+            : null;
+        let done;
+        try {
+            await this.sendPrompt(prompt, { decisive, onBeforeSubmit: () => observer?.beginRun() });
+            if (observer) {
+                done = await this._waitForGenerationDoneNetwork(observer, { timeoutMs: waitBudgetMs, stabilityMs });
+                if (done.error === 'observer-lost') {
+                    const fallback = await this._waitForGenerationDoneHtml({
+                        timeoutMs: Math.max(1, waitBudgetMs - done.elapsedMs),
+                        stabilityMs
+                    });
+                    done = { ...fallback, elapsedMs: done.elapsedMs + fallback.elapsedMs };
+                }
+            }
+            else {
+                done = await this._waitForGenerationDoneHtml({ timeoutMs: waitBudgetMs, stabilityMs });
+            }
+        }
+        finally {
+            observer?.close();
+            observer = null;
+        }
         const postFiles = await this.listFiles().catch(() => []);
         const postTurns = await this.getChatTurns();
         const lastTurn = postTurns[postTurns.length - 1];
@@ -332,8 +393,16 @@ export class DesignerController {
         const htmlHash = snap.html ? hashHex(snap.html) : null;
         const activeFile = extractFileParam(snap.url);
         let failureMode = null;
-        if (!done.ok)
-            failureMode = done.error === 'timeout' ? 'timeout' : 'unstable';
+        if (!done.ok) {
+            if (done.error === 'timeout')
+                failureMode = 'timeout';
+            else if (done.error === 'stalled')
+                failureMode = 'stalled';
+            else if (done.error === 'blocked')
+                failureMode = 'blocked';
+            else
+                failureMode = 'unstable';
+        }
         else if (snap.html === this._preSendHtml && newFiles.length === 0)
             failureMode = 'no_change';
         const fidelity = getSession(this.key)?.fidelity || null;