atoo-studio 0.0.1 → 0.0.2

package/dist/src/services/preview/injected-scripts.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Injected scripts for Shadow Overlay interception.
+ * These scripts run inside the headless Chrome page via
+ * Page.addScriptToEvaluateOnNewDocument and intercept native
+ * controls that don't render in CDP screencast frames.
+ *
+ * Communication back to the server uses Runtime.addBinding.
+ */
+export declare function getInjectedScript(): string;

package/dist/src/services/preview/injected-scripts.js

@@ -0,0 +1,232 @@
+/**
+ * Injected scripts for Shadow Overlay interception.
+ * These scripts run inside the headless Chrome page via
+ * Page.addScriptToEvaluateOnNewDocument and intercept native
+ * controls that don't render in CDP screencast frames.
+ *
+ * Communication back to the server uses Runtime.addBinding.
+ */
+export function getInjectedScript() {
+    return `(function() {
+  'use strict';
+  if (window.__atoo_injected) return;
+  window.__atoo_injected = true;
+
+  // === UTILITY: Build a unique CSS selector path for an element ===
+  function getSelectorPath(el) {
+    var parts = [];
+    while (el && el !== document.body && el !== document.documentElement) {
+      var selector = el.tagName.toLowerCase();
+      if (el.id) {
+        parts.unshift('#' + CSS.escape(el.id));
+        break;
+      }
+      var parent = el.parentElement;
+      if (parent) {
+        var siblings = Array.from(parent.children).filter(function(c) {
+          return c.tagName === el.tagName;
+        });
+        if (siblings.length > 1) {
+          selector += ':nth-of-type(' + (siblings.indexOf(el) + 1) + ')';
+        }
+      }
+      parts.unshift(selector);
+      el = parent;
+    }
+    return parts.join(' > ');
+  }
+
+  function getRect(el) {
+    var r = el.getBoundingClientRect();
+    return { x: r.x, y: r.y, width: r.width, height: r.height };
+  }
+
+  // === SELECT INTERCEPTION ===
+  document.addEventListener('mousedown', function(e) {
+    var el = e.target;
+    // Walk up to find a <select> (handles clicking on the arrow, etc.)
+    while (el && el.tagName !== 'SELECT') el = el.parentElement;
+    if (!el) return;
+
+    // Don't intercept <select multiple> — it renders as a native list box, not a dropdown
+    if (el.multiple) return;
+
+    // Only intercept if the binding is available — otherwise let native behavior work
+    if (typeof window.__atoo_selectOpened !== 'function') return;
+
+    e.preventDefault();
+    e.stopPropagation();
+    e.stopImmediatePropagation();
+
+    var options = [];
+    for (var i = 0; i < el.options.length; i++) {
+      var opt = el.options[i];
+      var group = opt.parentElement && opt.parentElement.tagName === 'OPTGROUP'
+        ? opt.parentElement.label : null;
+      options.push({
+        value: opt.value,
+        text: opt.textContent || opt.innerText,
+        selected: opt.selected,
+        disabled: opt.disabled,
+        group: group,
+      });
+    }
+
+    try {
+      window.__atoo_selectOpened(JSON.stringify({
+        rect: getRect(el),
+        options: options,
+        selectedIndex: el.selectedIndex,
+        multiple: el.multiple,
+        selectorPath: getSelectorPath(el),
+      }));
+    } catch (err) { /* binding not available */ }
+  }, true);
+
+  // === INPUT PICKER INTERCEPTION ===
+  var PICKER_TYPES = ['date', 'time', 'datetime-local', 'month', 'week', 'color'];
+  var pickerFiredAt = 0;
+
+  function firePickerOpened(el) {
+    // Only intercept if the binding is actually available — otherwise let the input work normally
+    console.log('[atoo] firePickerOpened called, type=' + el.type + ', binding=' + typeof window.__atoo_pickerOpened);
+    if (typeof window.__atoo_pickerOpened !== 'function') {
+      console.log('[atoo] pickerOpened binding NOT available');
+      return false;
+    }
+    pickerFiredAt = Date.now();
+    try {
+      var payload = JSON.stringify({
+        type: el.type,
+        value: el.value,
+        min: el.min || null,
+        max: el.max || null,
+        step: el.step || null,
+        rect: getRect(el),
+        selectorPath: getSelectorPath(el),
+      });
+      console.log('[atoo] calling pickerOpened with:', payload);
+      window.__atoo_pickerOpened(payload);
+      console.log('[atoo] pickerOpened call returned');
+      return true;
+    } catch (err) {
+      console.log('[atoo] pickerOpened call FAILED:', err);
+      return false;
+    }
+  }
+
+  function findPickerInput(target) {
+    var el = target;
+    while (el && el.tagName !== 'INPUT') el = el.parentElement;
+    if (!el || PICKER_TYPES.indexOf(el.type) === -1) return null;
+    return el;
+  }
+
+  document.addEventListener('mousedown', function(e) {
+    console.log('[atoo] mousedown target:', e.target.tagName, e.target.type || '');
+    var el = findPickerInput(e.target);
+    if (!el) return;
+
+    console.log('[atoo] picker input found:', el.type);
+    // Try to fire the binding — only block default behavior if successful
+    if (!firePickerOpened(el)) return;
+
+    e.preventDefault();
+    e.stopPropagation();
+    e.stopImmediatePropagation();
+  }, true);
+
+  // Fallback: click listener in case mousedown doesn't fire reliably via CDP
+  document.addEventListener('click', function(e) {
+    var el = findPickerInput(e.target);
+    if (!el) return;
+    // Skip if mousedown already handled this (within 500ms)
+    if (Date.now() - pickerFiredAt < 500) return;
+
+    if (!firePickerOpened(el)) return;
+
+    e.preventDefault();
+    e.stopPropagation();
+    e.stopImmediatePropagation();
+  }, true);
+
+  // === TOOLTIP INTERCEPTION ===
+  var tooltipTimer = null;
+  var currentTooltipEl = null;
+
+  document.addEventListener('mouseover', function(e) {
+    var el = e.target;
+    while (el && !el.getAttribute('title')) el = el.parentElement;
+    if (!el || !el.getAttribute('title')) return;
+
+    var title = el.getAttribute('title');
+    // Remove native title to prevent browser tooltip
+    el.removeAttribute('title');
+    el.dataset.atooTitle = title;
+    currentTooltipEl = el;
+
+    clearTimeout(tooltipTimer);
+    tooltipTimer = setTimeout(function() {
+      try {
+        window.__atoo_tooltipShow(JSON.stringify({
+          text: title,
+          rect: getRect(el),
+        }));
+      } catch (err) { /* binding not available */ }
+    }, 500);
+  }, true);
+
+  document.addEventListener('mouseout', function(e) {
+    clearTimeout(tooltipTimer);
+    // Restore title attribute
+    if (currentTooltipEl && currentTooltipEl.dataset.atooTitle) {
+      currentTooltipEl.setAttribute('title', currentTooltipEl.dataset.atooTitle);
+      delete currentTooltipEl.dataset.atooTitle;
+      currentTooltipEl = null;
+    }
+    try {
+      window.__atoo_tooltipHide('{}');
+    } catch (err) { /* binding not available */ }
+  }, true);
+
+  // === CLIPBOARD COPY INTERCEPTION ===
+  document.addEventListener('copy', function() {
+    var sel = window.getSelection();
+    var text = sel ? sel.toString() : '';
+    if (text) {
+      try {
+        window.__atoo_clipboard(JSON.stringify({ text: text }));
+      } catch (err) { /* binding not available */ }
+    }
+  }, true);
+
+  // === CONTEXT MENU INTERCEPTION ===
+  document.addEventListener('contextmenu', function(e) {
+    e.preventDefault();
+    e.stopPropagation();
+    e.stopImmediatePropagation();
+
+    var sel = window.getSelection();
+    var selectedText = sel ? sel.toString() : '';
+    var link = null;
+    var el = e.target;
+    while (el) {
+      if (el.tagName === 'A' && el.href) { link = el; break; }
+      el = el.parentElement;
+    }
+    var img = e.target.closest ? e.target.closest('img') : null;
+
+    try {
+      window.__atoo_contextMenu(JSON.stringify({
+        x: e.clientX,
+        y: e.clientY,
+        selectedText: selectedText,
+        linkHref: link ? link.href : null,
+        linkText: link ? (link.textContent || '').trim() : null,
+        imgSrc: img ? img.src : null,
+      }));
+    } catch (err) { /* binding not available */ }
+  }, true);
+
+})();`;
+}

package/dist/src/services/preview/preview-backend.d.ts

@@ -0,0 +1,92 @@
+import { WebSocket } from 'ws';
+export interface PendingDialog {
+    resolve: (accept: boolean, promptText?: string) => void;
+    timeout: ReturnType<typeof setTimeout>;
+}
+export interface PreviewViewport {
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+    isMobile: boolean;
+    hasTouch: boolean;
+}
+export interface PreviewInstanceBase {
+    id: string;
+    targetPort: number;
+    /** CDP port — only available in headless mode */
+    cdpPort?: number;
+    headerHost?: string;
+    protocol: 'http' | 'https';
+    viewport: PreviewViewport;
+    quality: number;
+    wsClients: Set<WebSocket>;
+    lastActivity: number;
+    recording: boolean;
+    recordedFrames: {
+        data: Buffer;
+        timestamp: number;
+    }[];
+    lastFrameTime: number;
+    lastStreamRestart: number;
+    pendingDialogs: Map<string, PendingDialog>;
+    pendingAuthRequests: Map<string, {
+        requestId: string;
+        timeout: ReturnType<typeof setTimeout>;
+    }>;
+    downloadDir: string;
+}
+export interface CreatePreviewOpts {
+    targetPort: number;
+    headerHost?: string;
+    protocol?: 'http' | 'https';
+    width?: number;
+    height?: number;
+    dpr?: number;
+    isMobile?: boolean;
+    hasTouch?: boolean;
+    quality?: number;
+}
+export interface PreviewBackend {
+    readonly mode: 'headless';
+    create(key: string, opts: CreatePreviewOpts): Promise<PreviewInstanceBase>;
+    destroy(instance: PreviewInstanceBase): Promise<void>;
+    setViewport(instance: PreviewInstanceBase, viewport: {
+        width: number;
+        height: number;
+        dpr?: number;
+        isMobile?: boolean;
+        hasTouch?: boolean;
+    }): Promise<void>;
+    setQuality(instance: PreviewInstanceBase, quality: number): Promise<void>;
+    navigate(instance: PreviewInstanceBase, url: string): Promise<void>;
+    reload(instance: PreviewInstanceBase): Promise<void>;
+    dispatchMouseEvent(instance: PreviewInstanceBase, params: any): Promise<void>;
+    dispatchKeyEvent(instance: PreviewInstanceBase, params: any): Promise<void>;
+    insertText(instance: PreviewInstanceBase, text: string): Promise<void>;
+    dispatchScrollEvent(instance: PreviewInstanceBase, params: {
+        x: number;
+        y: number;
+        deltaX: number;
+        deltaY: number;
+    }): Promise<void>;
+    screenshot(instance: PreviewInstanceBase, fullPage?: boolean): Promise<string>;
+    handleDialogResponse(instance: PreviewInstanceBase, dialogId: string, accept: boolean, promptText?: string): void;
+    handleFileChooserResponse(instance: PreviewInstanceBase, backendNodeId: number, files: string[]): Promise<void>;
+    getDownloadPath(instance: PreviewInstanceBase, guid: string): string | null;
+    handleSelectResponse(instance: PreviewInstanceBase, selectorPath: string, value: string): Promise<void>;
+    handlePickerResponse(instance: PreviewInstanceBase, selectorPath: string, value: string, inputType: string): Promise<void>;
+    handleAuthResponse(instance: PreviewInstanceBase, requestId: string, username: string, password: string): void;
+    handleAuthCancel(instance: PreviewInstanceBase, requestId: string): void;
+    handleContextMenuAction(instance: PreviewInstanceBase, action: string, params: any): Promise<void>;
+    startRecording(instance: PreviewInstanceBase): void;
+    stopRecording(instance: PreviewInstanceBase): Promise<string>;
+    /** Restart screencast/stream if stalled */
+    restartStream(instance: PreviewInstanceBase): Promise<void>;
+    /** Cleanup on startup (e.g. orphaned processes/containers) */
+    cleanupOrphans(): void;
+    shutdown(): Promise<void>;
+}
+/** Broadcast a JSON message to all connected WS clients */
+export declare function broadcastJson(instance: PreviewInstanceBase, data: object): void;
+/** Broadcast a binary frame to all connected WS clients */
+export declare function broadcastBinary(instance: PreviewInstanceBase, data: Buffer): void;

package/dist/src/services/preview/preview-backend.js

@@ -0,0 +1,15 @@
+/** Broadcast a JSON message to all connected WS clients */
+export function broadcastJson(instance, data) {
+    const msg = JSON.stringify(data);
+    for (const ws of instance.wsClients) {
+        if (ws.readyState === 1)
+            ws.send(msg);
+    }
+}
+/** Broadcast a binary frame to all connected WS clients */
+export function broadcastBinary(instance, data) {
+    for (const ws of instance.wsClients) {
+        if (ws.readyState === 1)
+            ws.send(data);
+    }
+}

package/dist/src/services/preview/universal-setter.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Universal Setter — sets form element values bypassing framework guards.
+ *
+ * Uses the native prototype descriptor trick to bypass React/Vue/Angular
+ * controlled component state, then fires proper input + change events.
+ */
+export declare function buildUniversalSetterExpression(selectorPath: string, value: string): string;

package/dist/src/services/preview/universal-setter.js

@@ -0,0 +1,46 @@
+/**
+ * Universal Setter — sets form element values bypassing framework guards.
+ *
+ * Uses the native prototype descriptor trick to bypass React/Vue/Angular
+ * controlled component state, then fires proper input + change events.
+ */
+export function buildUniversalSetterExpression(selectorPath, value) {
+    const escapedSelector = JSON.stringify(selectorPath);
+    const escapedValue = JSON.stringify(value);
+    return `(function() {
+    var el = document.querySelector(${escapedSelector});
+    if (!el) return false;
+
+    var tag = el.tagName;
+    var proto;
+    if (tag === 'SELECT') {
+      proto = HTMLSelectElement.prototype;
+    } else if (tag === 'TEXTAREA') {
+      proto = HTMLTextAreaElement.prototype;
+    } else {
+      proto = HTMLInputElement.prototype;
+    }
+
+    var desc = Object.getOwnPropertyDescriptor(proto, 'value');
+    if (desc && desc.set) {
+      desc.set.call(el, ${escapedValue});
+    } else {
+      el.value = ${escapedValue};
+    }
+
+    // For <select>, also set selectedIndex
+    if (tag === 'SELECT') {
+      for (var i = 0; i < el.options.length; i++) {
+        if (el.options[i].value === ${escapedValue}) {
+          el.selectedIndex = i;
+          break;
+        }
+      }
+    }
+
+    // Fire events that frameworks listen to
+    el.dispatchEvent(new Event('input', { bubbles: true }));
+    el.dispatchEvent(new Event('change', { bubbles: true }));
+    return true;
+  })()`;
+}

package/dist/src/services/preview-manager.d.ts

@@ -0,0 +1,50 @@
+import { PreviewInstanceBase, CreatePreviewOpts } from './preview/preview-backend.js';
+export type { PreviewInstanceBase as PreviewInstance, CreatePreviewOpts } from './preview/preview-backend.js';
+declare class PreviewManager {
+    private instances;
+    private backend;
+    private cleanupTimer;
+    private initialized;
+    constructor();
+    private init;
+    private ensureInitialized;
+    get backendMode(): string;
+    private makeKey;
+    get(projectId: string, tabId: string): PreviewInstanceBase | undefined;
+    create(projectId: string, tabId: string, opts: CreatePreviewOpts): Promise<PreviewInstanceBase>;
+    destroy(projectId: string, tabId: string): Promise<void>;
+    destroyAllForProject(projectId: string): Promise<void>;
+    setViewport(projectId: string, tabId: string, viewport: {
+        width: number;
+        height: number;
+        dpr?: number;
+        isMobile?: boolean;
+        hasTouch?: boolean;
+    }): Promise<void>;
+    setQuality(projectId: string, tabId: string, quality: number): Promise<void>;
+    navigate(projectId: string, tabId: string, url: string): Promise<void>;
+    reload(projectId: string, tabId: string): Promise<void>;
+    dispatchMouseEvent(projectId: string, tabId: string, params: any): Promise<void>;
+    dispatchKeyEvent(projectId: string, tabId: string, params: any): Promise<void>;
+    insertText(projectId: string, tabId: string, text: string): Promise<void>;
+    dispatchScrollEvent(projectId: string, tabId: string, params: {
+        x: number;
+        y: number;
+        deltaX: number;
+        deltaY: number;
+    }): Promise<void>;
+    handleDialogResponse(projectId: string, tabId: string, dialogId: string, accept: boolean, promptText?: string): void;
+    handleFileChooserResponse(projectId: string, tabId: string, backendNodeId: number, files: string[]): Promise<void>;
+    getDownloadPath(projectId: string, tabId: string, guid: string): string | null;
+    handleSelectResponse(projectId: string, tabId: string, selectorPath: string, value: string): Promise<void>;
+    handlePickerResponse(projectId: string, tabId: string, selectorPath: string, value: string, inputType: string): Promise<void>;
+    handleAuthResponse(projectId: string, tabId: string, requestId: string, username: string, password: string): void;
+    handleAuthCancel(projectId: string, tabId: string, requestId: string): void;
+    handleContextMenuAction(projectId: string, tabId: string, action: string, params: any): Promise<void>;
+    screenshot(projectId: string, tabId: string, fullPage?: boolean): Promise<string>;
+    startRecording(projectId: string, tabId: string): void;
+    stopRecording(projectId: string, tabId: string): Promise<string>;
+    private cleanupInactive;
+    shutdown(): Promise<void>;
+}
+export declare const previewManager: PreviewManager;

package/dist/src/services/preview-manager.js

@@ -0,0 +1,216 @@
+import { HeadlessBackend } from './preview/headless-backend.js';
+const INACTIVITY_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+const CLEANUP_INTERVAL = 10 * 1000; // 10 seconds (also serves as stream watchdog)
+class PreviewManager {
+    instances = new Map();
+    backend;
+    cleanupTimer = null;
+    initialized = false;
+    constructor() {
+        this.cleanupTimer = setInterval(() => this.cleanupInactive(), CLEANUP_INTERVAL);
+        // Backend selection is deferred to init() since it's async
+        this.init();
+    }
+    async init() {
+        // Force headless CDP mode (shadow overlay interception requires it)
+        this.backend = new HeadlessBackend();
+        console.log('[preview] Using headless backend (forced)');
+        this.backend.cleanupOrphans();
+        this.initialized = true;
+    }
+    async ensureInitialized() {
+        // Spin until init() completes (typically < 100ms)
+        while (!this.initialized) {
+            await new Promise(r => setTimeout(r, 50));
+        }
+    }
+    get backendMode() {
+        return this.backend?.mode || 'initializing';
+    }
+    makeKey(projectId, tabId) {
+        return `${projectId}/${tabId}`;
+    }
+    get(projectId, tabId) {
+        return this.instances.get(this.makeKey(projectId, tabId));
+    }
+    // --- Public API (delegates to backend) ---
+    async create(projectId, tabId, opts) {
+        await this.ensureInitialized();
+        const key = this.makeKey(projectId, tabId);
+        // Destroy existing instance if any
+        if (this.instances.has(key)) {
+            await this.destroy(projectId, tabId);
+        }
+        const instance = await this.backend.create(key, opts);
+        this.instances.set(key, instance);
+        return instance;
+    }
+    async destroy(projectId, tabId) {
+        const key = this.makeKey(projectId, tabId);
+        const instance = this.instances.get(key);
+        if (!instance)
+            return;
+        this.instances.delete(key);
+        await this.backend.destroy(instance);
+    }
+    async destroyAllForProject(projectId) {
+        const prefix = `${projectId}/`;
+        const keys = Array.from(this.instances.keys()).filter(k => k.startsWith(prefix));
+        for (const key of keys) {
+            const [pid, tid] = key.split('/');
+            await this.destroy(pid, tid);
+        }
+    }
+    async setViewport(projectId, tabId, viewport) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return;
+        await this.backend.setViewport(instance, viewport);
+    }
+    async setQuality(projectId, tabId, quality) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return;
+        await this.backend.setQuality(instance, quality);
+    }
+    async navigate(projectId, tabId, url) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return;
+        await this.backend.navigate(instance, url);
+    }
+    async reload(projectId, tabId) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return;
+        await this.backend.reload(instance);
+    }
+    async dispatchMouseEvent(projectId, tabId, params) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return;
+        await this.backend.dispatchMouseEvent(instance, params);
+    }
+    async dispatchKeyEvent(projectId, tabId, params) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return;
+        await this.backend.dispatchKeyEvent(instance, params);
+    }
+    async insertText(projectId, tabId, text) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return;
+        await this.backend.insertText(instance, text);
+    }
+    async dispatchScrollEvent(projectId, tabId, params) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return;
+        await this.backend.dispatchScrollEvent(instance, params);
+    }
+    handleDialogResponse(projectId, tabId, dialogId, accept, promptText) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return;
+        this.backend.handleDialogResponse(instance, dialogId, accept, promptText);
+    }
+    async handleFileChooserResponse(projectId, tabId, backendNodeId, files) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return;
+        await this.backend.handleFileChooserResponse(instance, backendNodeId, files);
+    }
+    getDownloadPath(projectId, tabId, guid) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return null;
+        return this.backend.getDownloadPath(instance, guid);
+    }
+    // --- Shadow overlay response handlers ---
+    async handleSelectResponse(projectId, tabId, selectorPath, value) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return;
+        await this.backend.handleSelectResponse(instance, selectorPath, value);
+    }
+    async handlePickerResponse(projectId, tabId, selectorPath, value, inputType) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return;
+        await this.backend.handlePickerResponse(instance, selectorPath, value, inputType);
+    }
+    handleAuthResponse(projectId, tabId, requestId, username, password) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return;
+        this.backend.handleAuthResponse(instance, requestId, username, password);
+    }
+    handleAuthCancel(projectId, tabId, requestId) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return;
+        this.backend.handleAuthCancel(instance, requestId);
+    }
+    async handleContextMenuAction(projectId, tabId, action, params) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return;
+        await this.backend.handleContextMenuAction(instance, action, params);
+    }
+    async screenshot(projectId, tabId, fullPage) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            throw new Error('Preview instance not found');
+        return this.backend.screenshot(instance, fullPage);
+    }
+    startRecording(projectId, tabId) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            return;
+        this.backend.startRecording(instance);
+    }
+    async stopRecording(projectId, tabId) {
+        const instance = this.get(projectId, tabId);
+        if (!instance)
+            throw new Error('Preview instance not found');
+        return this.backend.stopRecording(instance);
+    }
+    // --- Cleanup ---
+    cleanupInactive() {
+        const now = Date.now();
+        for (const [key, instance] of this.instances) {
+            if (instance.wsClients.size === 0 && now - instance.lastActivity > INACTIVITY_TIMEOUT) {
+                const [projectId, tabId] = key.split('/');
+                console.log(`[preview] Cleaning up inactive instance ${key}`);
+                this.destroy(projectId, tabId);
+                continue;
+            }
+            // Watchdog: restart stream only if user interacted recently but no frames arrived.
+            // CDP screencast only fires on repaints — a static page with no visual changes
+            // produces zero frames, which is normal, not a stall.
+            if (instance.wsClients.size > 0 &&
+                now - instance.lastFrameTime > 5000 &&
+                instance.lastActivity > instance.lastFrameTime &&
+                now - instance.lastStreamRestart > 30_000) {
+                console.log(`[preview] Stream stalled for ${key}, restarting...`);
+                instance.lastStreamRestart = now;
+                this.backend.restartStream(instance).catch(() => { });
+            }
+        }
+    }
+    async shutdown() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        for (const [key] of this.instances) {
+            const [projectId, tabId] = key.split('/');
+            await this.destroy(projectId, tabId);
+        }
+        if (this.backend) {
+            await this.backend.shutdown();
+        }
+    }
+}
+export const previewManager = new PreviewManager();

package/dist/src/services/project-watcher.d.ts

@@ -0,0 +1,6 @@
+export declare function reconcileWorktrees(projectId: string, projectPath: string): void;
+export declare function watchProject(projectId: string, projectPath: string): void;
+export declare function unwatchProject(projectId: string): void;
+export declare function watchEnvironmentProjects(envId: string): void;
+export declare function unwatchAll(): void;
+export declare function isWatching(projectId: string): boolean;