specrails-desktop 2.20.1 → 2.22.0

package/server/dist/browser-capture-manager.js

@@ -21,6 +21,13 @@ function isTargetClosedError(err) {
 const MAX_SESSIONS_PER_PROJECT = 4;
 const DOM_HTML_BYTE_CAP = 100_000;
 const LAST_URL_KEY = 'config.browser_last_url';
+/** Conflation threshold for the screencast fan-out: skip sending a frame to a
+ *  client whose WS send-buffer already holds this many bytes. A slow consumer
+ *  otherwise accumulates seconds of stale frames (ever-growing latency), which is
+ *  what "sluggish" feels like. Every frame is an independent, complete JPEG, so
+ *  dropping intermediates is lossless — the client simply paints the next fresh
+ *  frame (newest-wins). `lastFrame` is still always updated. */
+const MAX_CLIENT_BUFFERED_BYTES = 1_000_000;
 /** How far back from capture time to include buffered network requests. */
 const NETWORK_WINDOW_MS = 30_000;
 /**
@@ -167,13 +174,15 @@ class BrowserCaptureManager {
             id,
             projectId: this.projectId,
             page,
+            popups: [],
+            popupView: false,
             clients: new Set(),
             lastFrame: null,
             url: null,
             title: null,
             viewport: { ...DEFAULT_VIEWPORT },
             createdAt: opts?.createdAtMs ?? this.now(),
-            screencasting: false,
+            screencastPage: null,
             screencastDesired: false,
             screencastOp: null,
             closed: false,
@@ -181,6 +190,18 @@ class BrowserCaptureManager {
         this.sessions.set(id, session);
         // The reservation is now realised as a committed session — release it.
         this._reserved--;
+        // Adopt popups the page opens (OAuth login windows etc.) as secondary pages
+        // of this session, and keep the client's URL bar live on in-page navigation
+        // (link clicks / redirects the REST navigate path never sees).
+        this.watchPopups(session, page);
+        page.onNavigated?.((url) => {
+            if (session.closed || this.disposed)
+                return;
+            session.url = url;
+            if (url && url !== 'about:blank')
+                this.setLastUrl(url);
+            this.broadcastControl(session, { type: 'nav', url, title: session.title });
+        });
         // Start capturing the page's network requests before the first navigation so
         // XHR/fetch made during page load are available at capture time. Best-effort:
         // a handle that doesn't support it (or a failure) just yields no network data.
@@ -188,13 +209,106 @@ class BrowserCaptureManager {
             await page.enableNetwork?.();
         }
         catch { /* network capture is best-effort */ }
+        // Kick the initial navigation WITHOUT blocking session creation. The old
+        // `await page.goto(...)` here held the create POST — and therefore the whole
+        // modal spinner — hostage to `domcontentloaded` (up to 30s on a slow site).
+        // Returning immediately lets the client attach and start the screencast right
+        // away, so the user watches the page paint progressively instead of staring
+        // at "opening…". The URL is set optimistically to the target; the resolved
+        // URL/title land via the `nav` control broadcast every client already handles.
         const target = opts?.initialUrl?.trim() || this.getLastUrl() || 'about:blank';
-        const result = await page.goto(target);
-        session.url = result.url;
-        session.title = result.title;
+        session.url = target;
+        void this.runInitialNavigation(session, target);
+        return this.toMeta(session);
+    }
+    /** Complete the initial `goto` in the background (see create()). Never throws;
+     *  a session killed mid-navigation is simply left alone. */
+    async runInitialNavigation(s, target) {
+        let result;
+        try {
+            result = await s.page.goto(target);
+        }
+        catch {
+            return; // the page keeps whatever it settled on; nav failures are non-fatal
+        }
+        if (s.closed || this.disposed)
+            return;
+        s.url = result.url;
+        s.title = result.title;
         if (result.url && result.url !== 'about:blank')
             this.setLastUrl(result.url);
-        return this.toMeta(session);
+        this.broadcastControl(s, { type: 'nav', url: result.url, title: result.title });
+    }
+    // ─── Popup support (OAuth login windows etc.) ───────────────────────────────
+    topPopup(s) {
+        return s.popups.length > 0 ? s.popups[s.popups.length - 1] : null;
+    }
+    /** The page the screencast + interactive input should target: the top popup
+     *  while one is open and being viewed, else the root page. */
+    activePage(s) {
+        return (s.popupView && this.topPopup(s)) || s.page;
+    }
+    watchPopups(s, opener) {
+        opener.onPopup?.((popup) => this.adoptPopup(s, popup));
+    }
+    /** Register a popup as a secondary page of the session: inherit the viewport,
+     *  reroute the screencast + input to it (latest-wins), and auto-return to the
+     *  opener when it closes (the typical OAuth self-close). */
+    adoptPopup(s, popup) {
+        if (s.closed || this.disposed) {
+            void popup.close().catch(() => { });
+            return;
+        }
+        s.popups.push(popup);
+        s.popupView = true;
+        // Popups inherit the session viewport so coordinate mapping + screencast
+        // dimensions stay identical to the root page.
+        void popup.setViewport(s.viewport.width, s.viewport.height).catch(() => { });
+        popup.onClose?.(() => this.dropPopup(s, popup));
+        popup.onNavigated?.(() => {
+            // Keep the "Login window — <origin>" label fresh while the top popup
+            // walks its redirect chain.
+            if (!s.closed && this.topPopup(s) === popup)
+                this.broadcastPopupState(s);
+        });
+        // Popups can themselves open popups (rare, but some IdPs chain windows).
+        this.watchPopups(s, popup);
+        this.broadcastPopupState(s);
+        void this.applyScreencast(s);
+    }
+    dropPopup(s, popup) {
+        const i = s.popups.indexOf(popup);
+        if (i === -1)
+            return;
+        s.popups.splice(i, 1);
+        if (s.popups.length === 0)
+            s.popupView = false;
+        if (s.closed)
+            return;
+        this.broadcastPopupState(s);
+        // Re-routes the screencast to the next popup down or back to the opener;
+        // startScreencast emits a frame immediately, so the switch paints at once.
+        void this.applyScreencast(s);
+    }
+    broadcastPopupState(s) {
+        const top = this.topPopup(s);
+        this.broadcastControl(s, {
+            type: 'popup',
+            count: s.popups.length,
+            active: s.popupView && top != null,
+            url: top ? top.currentUrl() : null,
+        });
+    }
+    /** Switch the viewed page between the root page and the top popup ("back to
+     *  page" / "show login window"). Returns false for an unknown session. */
+    setPopupView(sessionId, target) {
+        const s = this.getSession(sessionId);
+        if (!s)
+            return false;
+        s.popupView = target === 'popup' && s.popups.length > 0;
+        this.broadcastPopupState(s);
+        void this.applyScreencast(s);
+        return true;
     }
     // ─── WS attach / detach + screencast fan-out ────────────────────────────────
     async attach(sessionId, ws) {
@@ -207,6 +321,12 @@ class BrowserCaptureManager {
         this.safeSend(ws, JSON.stringify({ type: 'ready', id: s.id, url: s.url, title: s.title, viewport: s.viewport }));
         if (s.lastFrame)
             this.safeSend(ws, s.lastFrame);
+        // A (re)joining client must learn about a live popup immediately, or it
+        // would render popup frames with the root-page chrome.
+        if (s.popups.length > 0) {
+            const top = this.topPopup(s);
+            this.safeSend(ws, JSON.stringify({ type: 'popup', count: s.popups.length, active: s.popupView && top != null, url: top ? top.currentUrl() : null }));
+        }
         s.screencastDesired = true;
         await this.applyScreencast(s);
         return this.toMeta(s);
@@ -224,45 +344,48 @@ class BrowserCaptureManager {
     /**
      * Serialise screencast start/stop transitions on a per-session promise chain so
      * a rapid detach→attach (stop fired async, then start) can't double-initialise
-     * the CDP screencast. The chain always reconciles `screencasting` to
-     * `screencastDesired`.
+     * the CDP screencast. The chain reconciles the page the screencast runs on
+     * (`screencastPage`) to the DESIRED page — the active page (top popup while one
+     * is viewed, else the root page) when `screencastDesired`, or none. A popup
+     * open/close/focus switch therefore stops the cast on the old page and starts
+     * it on the new one; the same frame callback fans out to the same clients.
      */
     applyScreencast(s) {
         const prev = s.screencastOp ?? Promise.resolve();
         s.screencastOp = prev.then(async () => {
-            if (s.closed) {
-                if (s.screencasting) {
-                    s.screencasting = false;
-                    try {
-                        await s.page.stopScreencast();
-                    }
-                    catch { /* ignore */ }
-                }
+            const desired = !s.closed && s.screencastDesired ? this.activePage(s) : null;
+            if (s.screencastPage === desired)
                 return;
+            if (s.screencastPage) {
+                const old = s.screencastPage;
+                s.screencastPage = null;
+                try {
+                    await old.stopScreencast();
+                }
+                catch { /* ignore */ }
             }
-            if (s.screencastDesired && !s.screencasting) {
-                s.screencasting = true;
-                await s.page.startScreencast((frame) => {
+            if (desired) {
+                s.screencastPage = desired;
+                await desired.startScreencast((frame) => {
                     if (s.closed)
                         return;
                     s.lastFrame = frame.data;
                     for (const client of s.clients) {
-                        if (client.readyState === WS_OPEN) {
-                            try {
-                                client.send(frame.data);
-                            }
-                            catch { /* drop */ }
+                        if (client.readyState !== WS_OPEN)
+                            continue;
+                        // Conflate for slow consumers: when the socket's send-buffer is
+                        // already backed up, skip this frame for that client instead of
+                        // queueing ever-staler frames behind the backlog (latency, not
+                        // fps, is what makes a screencast feel sluggish).
+                        if ((client.bufferedAmount ?? 0) > MAX_CLIENT_BUFFERED_BYTES)
+                            continue;
+                        try {
+                            client.send(frame.data);
                         }
+                        catch { /* drop */ }
                     }
                 });
             }
-            else if (!s.screencastDesired && s.screencasting) {
-                s.screencasting = false;
-                try {
-                    await s.page.stopScreencast();
-                }
-                catch { /* ignore */ }
-            }
         }).catch(() => { });
         return s.screencastOp;
     }
@@ -308,8 +431,20 @@ class BrowserCaptureManager {
                 width: Math.max(1, Math.round(event.width)),
                 height: Math.max(1, Math.round(event.height)),
             };
+            // Keep every page of the session (root + popups) at the same viewport so
+            // switching between them never re-maps coordinates or resizes the canvas.
+            await s.page.dispatchInput(event);
+            for (const popup of s.popups) {
+                try {
+                    await popup.dispatchInput(event);
+                }
+                catch { /* ignore */ }
+            }
+            return;
         }
-        await s.page.dispatchInput(event);
+        // Interactive input (mouse/wheel/keys) goes to the page being VIEWED — the
+        // top popup during an OAuth login, else the root page.
+        await this.activePage(s).dispatchInput(event);
     }
     async navigate(sessionId, action, url) {
         if (this.disposed)
@@ -414,14 +549,17 @@ class BrowserCaptureManager {
         const s = this.getSession(sessionId);
         if (!s)
             return null;
+        // Clipboard follows the viewed page: pasting credentials into an OAuth
+        // popup must land in the popup, not the opener behind it.
+        const page = this.activePage(s);
         if (action === 'paste') {
             if (text)
-                await s.page.insertText?.(text);
+                await page.insertText?.(text);
             return { text: '' };
         }
-        const sel = (await s.page.getSelectionText?.()) ?? '';
+        const sel = (await page.getSelectionText?.()) ?? '';
         if (action === 'cut' && sel)
-            await s.page.deleteSelection?.();
+            await page.deleteSelection?.();
         return { text: sel };
     }
     // ─── Multi-breakpoint capture ───────────────────────────────────────────────
@@ -551,6 +689,12 @@ class BrowserCaptureManager {
             catch { /* ignore */ }
         }
         s.clients.clear();
+        for (const popup of s.popups.splice(0)) {
+            try {
+                await popup.close();
+            }
+            catch { /* ignore */ }
+        }
         try {
             await s.page.close();
         }
@@ -577,6 +721,12 @@ class BrowserCaptureManager {
                 catch { /* ignore */ }
             }
             s.clients.clear();
+            for (const popup of s.popups.splice(0)) {
+                try {
+                    await popup.close();
+                }
+                catch { /* ignore */ }
+            }
             try {
                 await s.page.close();
             }

package/server/dist/browser-playwright.js

@@ -9,6 +9,7 @@
 // screencast API; input + screenshot + DOM use Playwright's high-level page API.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isNavigableUrl = isNavigableUrl;
+exports.screencastParams = screencastParams;
 exports.normalizeUrl = normalizeUrl;
 exports.chromiumLaunchArgs = chromiumLaunchArgs;
 exports.createPlaywrightLauncher = createPlaywrightLauncher;
@@ -94,6 +95,30 @@ function isBlockedHost(host) {
     }
     return false;
 }
+/**
+ * CDP `Page.startScreencast` parameters, centralised and env-tunable.
+ *
+ * - `quality` (JPEG, default 70) can be tuned via
+ *   `SPECRAILS_BROWSER_SCREENCAST_QUALITY` (clamped to [1, 100]; non-numeric
+ *   values fall back to the default). Lower = smaller frames = higher fps on
+ *   slow links; higher = crisper at more bandwidth/decode cost.
+ * - `everyNthFrame: 1` — never skip source frames; the client-side pipeline
+ *   drops stale frames instead (newest-wins), which keeps latency minimal.
+ * - `maxWidth`/`maxHeight` are a GUARD, not a scaler: the session viewport is
+ *   sized to the displayed canvas (fit mode) or a device preset, so frames are
+ *   already ≤ display size. The caps only prevent a pathological viewport from
+ *   producing multi-megabyte frames. Chromium preserves aspect when clamping.
+ */
+function screencastParams(env = process.env) {
+    let quality = 70;
+    const raw = env.SPECRAILS_BROWSER_SCREENCAST_QUALITY;
+    if (raw !== undefined && raw !== '') {
+        const n = Number(raw);
+        if (Number.isFinite(n))
+            quality = Math.min(100, Math.max(1, Math.round(n)));
+    }
+    return { format: 'jpeg', quality, everyNthFrame: 1, maxWidth: 3840, maxHeight: 2400 };
+}
 /**
  * Normalize a user-supplied address into a safe, navigable URL. A bare host
  * (`example.com`) is upgraded to `https://`. The result is then validated by
@@ -125,6 +150,10 @@ class PlaywrightPageHandle {
     netCdp = null;
     netEnabled = false;
     netBuffer = new browser_network_1.NetworkRingBuffer();
+    // Last position the page's virtual mouse was moved to. Lets the wheel path skip
+    // the redundant `mouse.move` a scroll gesture would otherwise re-issue for
+    // every tick at the same cursor position (halves the CDP commands per wheel).
+    lastMouse = null;
     constructor(page) {
         this.page = page;
     }
@@ -187,16 +216,30 @@ class PlaywrightPageHandle {
     async dispatchInput(event) {
         try {
             if (event.type === 'mouse') {
-                if (event.action === 'move')
+                if (event.action === 'move') {
+                    this.lastMouse = { x: event.x, y: event.y };
                     await this.page.mouse.move(event.x, event.y);
-                else if (event.action === 'down')
+                }
+                else if (event.action === 'down') {
                     await this.page.mouse.down({ button: event.button ?? 'left', clickCount: event.clickCount ?? 1 });
-                else
+                }
+                else {
                     await this.page.mouse.up({ button: event.button ?? 'left', clickCount: event.clickCount ?? 1 });
+                }
             }
             else if (event.type === 'wheel') {
-                await this.page.mouse.move(event.x, event.y);
-                await this.page.mouse.wheel(event.deltaX, event.deltaY);
+                // Scroll fast-path: skip the redundant reposition when the cursor hasn't
+                // moved since the last event (the common case mid-gesture), and dispatch
+                // move+wheel back-to-back without a sequential await gap — the Playwright
+                // driver sends commands in call order, so Chromium still sees move→wheel,
+                // but a concurrent wheel can no longer interleave between the two.
+                const ops = [];
+                if (!this.lastMouse || this.lastMouse.x !== event.x || this.lastMouse.y !== event.y) {
+                    this.lastMouse = { x: event.x, y: event.y };
+                    ops.push(this.page.mouse.move(event.x, event.y));
+                }
+                ops.push(this.page.mouse.wheel(event.deltaX, event.deltaY));
+                await Promise.all(ops);
             }
             else if (event.type === 'key') {
                 if (event.action === 'down') {
@@ -227,7 +270,16 @@ class PlaywrightPageHandle {
         this.screencastHandler = onFrame;
         const ctx = this.page.context();
         this.cdp = await ctx.newCDPSession(this.page);
-        this.cdp.on('Page.screencastFrame', async (evt) => {
+        this.cdp.on('Page.screencastFrame', (evt) => {
+            // Ack FIRST, fire-and-forget: Chromium throttles the screencast on unacked
+            // frames, so acking before the fan-out lets it capture+compress the next
+            // frame while this one is being delivered (pipeline overlap → higher fps,
+            // lower frame age). The frames are independent JPEGs, so there is no
+            // ordering hazard in acking early.
+            try {
+                this.cdp?.send('Page.screencastFrameAck', { sessionId: evt.sessionId })?.catch?.(() => { });
+            }
+            catch { /* ignore */ }
             try {
                 this.screencastHandler?.({
                     data: Buffer.from(evt.data, 'base64'),
@@ -235,14 +287,9 @@ class PlaywrightPageHandle {
                     height: evt.metadata?.deviceHeight ?? 0,
                 });
             }
-            finally {
-                try {
-                    await this.cdp.send('Page.screencastFrameAck', { sessionId: evt.sessionId });
-                }
-                catch { /* ignore */ }
-            }
+            catch { /* never let a handler error kill the CDP session */ }
         });
-        await this.cdp.send('Page.startScreencast', { format: 'jpeg', quality: 70, everyNthFrame: 1 });
+        await this.cdp.send('Page.startScreencast', screencastParams());
     }
     async stopScreencast() {
         this.screencastHandler = null;
@@ -443,6 +490,44 @@ class PlaywrightPageHandle {
         }
         catch { /* ignore */ }
     }
+    onPopup(cb) {
+        // Playwright fires 'popup' for pages this page opens (window.open,
+        // target=_blank, OAuth login windows). The popup lives in the SAME browser
+        // context — cookies and the window.opener/postMessage relationship are
+        // intact, which is exactly what an OAuth redirect/popup flow needs.
+        try {
+            this.page.on('popup', (p) => {
+                try {
+                    cb(new PlaywrightPageHandle(p));
+                }
+                catch { /* never break the event loop */ }
+            });
+        }
+        catch { /* ignore */ }
+    }
+    onClose(cb) {
+        try {
+            this.page.on('close', () => {
+                try {
+                    cb();
+                }
+                catch { /* ignore */ }
+            });
+        }
+        catch { /* ignore */ }
+    }
+    onNavigated(cb) {
+        try {
+            this.page.on('framenavigated', (frame) => {
+                try {
+                    if (frame === this.page.mainFrame())
+                        cb(frame.url());
+                }
+                catch { /* ignore */ }
+            });
+        }
+        catch { /* ignore */ }
+    }
     async getSelectionText() {
         try {
             return await this.page.evaluate(() => window.getSelection()?.toString() ?? '');

package/server/dist/code-explorer-router.js

@@ -12,6 +12,7 @@ const feature_flags_1 = require("./feature-flags");
 const build_dirs_1 = require("./build-dirs");
 const file_provenance_1 = require("./file-provenance");
 const file_summary_manager_1 = require("./file-summary-manager");
+const file_story_1 = require("./file-story");
 const MAX_TREE_PAGE = 2000;
 const MAX_FILE_BYTES = 2 * 1024 * 1024;
 const BINARY_PROBE_BYTES = 8 * 1024;
@@ -661,6 +662,97 @@ function createCodeExplorerRouter(deps) {
         }
         res.json({ summary, summaryStale });
     });
+    // Construction story: the chronological list of interventions (specs/jobs)
+    // that built this file — provenance rows enriched with diff stats, the AI
+    // contribution paragraph when generated, and the spec's live title/status.
+    // Same guards as every sibling content endpoint. Works for deleted files too
+    // (their story is still worth telling), so no stat/existence requirement.
+    router.get('/file/story', (req, res) => {
+        const relRaw = req.query.path;
+        if (!relRaw || typeof relRaw !== 'string') {
+            res.status(400).json({ error: 'path query parameter is required' });
+            return;
+        }
+        const guard = resolveSafePath(deps.projectPath, relRaw);
+        if (!guard) {
+            res.status(400).json({ error: 'path traversal not allowed' });
+            return;
+        }
+        if (isDeniedRelPath(relRaw)) {
+            res.status(403).json({ error: 'path is excluded by the code-explorer deny-list' });
+            return;
+        }
+        const rel = normalizeRel(relRaw);
+        if (isGitIgnored(deps.projectPath, rel)) {
+            res.status(403).json({ error: 'path is gitignored' });
+            return;
+        }
+        res.json({ path: rel, story: (0, file_story_1.getFileStory)(deps.db, rel, deps.getTicketSpec) });
+    });
+    // Construction story: generate (budget-gated) the plain-language "what this
+    // spec contributed" paragraph for ONE intervention. Awaits the single model
+    // turn; the file.story_updated WS event fires too so other open viewers of
+    // the same file refresh.
+    router.post('/file/story/explain', async (req, res) => {
+        const relRaw = req.query.path;
+        if (!relRaw || typeof relRaw !== 'string') {
+            res.status(400).json({ error: 'path query parameter is required' });
+            return;
+        }
+        const guard = resolveSafePath(deps.projectPath, relRaw);
+        if (!guard) {
+            res.status(400).json({ error: 'path traversal not allowed' });
+            return;
+        }
+        if (isDeniedRelPath(relRaw)) {
+            res.status(403).json({ error: 'path is excluded by the code-explorer deny-list' });
+            return;
+        }
+        const rel = normalizeRel(relRaw);
+        if (isGitIgnored(deps.projectPath, rel)) {
+            res.status(403).json({ error: 'path is gitignored' });
+            return;
+        }
+        if (!deps.fileStoryManager) {
+            res.status(404).json({ error: 'story generation not available' });
+            return;
+        }
+        const body = (req.body ?? {});
+        const provenanceId = typeof body.provenanceId === 'number' && Number.isInteger(body.provenanceId) && body.provenanceId > 0
+            ? body.provenanceId
+            : null;
+        if (provenanceId == null) {
+            res.status(400).json({ error: 'provenanceId (positive integer) is required' });
+            return;
+        }
+        try {
+            const result = await deps.fileStoryManager.explain({
+                projectId: deps.projectId,
+                relPath: rel,
+                provenanceId,
+                overrideBudget: body.overrideBudget === true,
+            });
+            if (result === 'generated') {
+                res.json({ ok: true });
+                return;
+            }
+            if (result === 'skipped:budget') {
+                // 200 (not 4xx) so the client's budget-override prompt is reachable
+                // (mirrors /file/regenerate-summary).
+                res.status(200).json({ skipped: 'budget' });
+                return;
+            }
+            if (result === 'skipped:not-found') {
+                res.status(404).json({ error: 'intervention not found for this file' });
+                return;
+            }
+            res.status(500).json({ error: 'story generation failed' });
+        }
+        catch (err) {
+            console.error('[code-explorer-router] story explain failed:', err);
+            res.status(500).json({ error: 'story generation failed', message: err.message });
+        }
+    });
     router.post('/file/regenerate-summary', async (req, res) => {
         const relRaw = req.query.path;
         if (!relRaw || typeof relRaw !== 'string') {