specrails-desktop 2.2.1 → 2.4.0

package/server/dist/project-router-spending.js

@@ -0,0 +1,320 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSpendingRoutes = registerSpendingRoutes;
+const queue_manager_1 = require("./queue-manager");
+const config_1 = require("./config");
+const ai_invocations_1 = require("./ai-invocations");
+const spending_1 = require("./spending");
+const ticket_store_1 = require("./ticket-store");
+function registerSpendingRoutes(deps) {
+    const { router, registry, ctx, ticketPath } = deps;
+    // ─── Spending dashboard ──────────────────────────────────────────────────────
+    router.get('/:projectId/spending', (req, res) => {
+        const filters = (0, spending_1.parseSpendingFilters)(req.query);
+        if (filters.period === 'custom' && (!filters.from || !filters.to)) {
+            res.status(400).json({ error: 'from and to are required for custom period' });
+            return;
+        }
+        try {
+            res.json((0, spending_1.getSpending)(ctx(req).db, ctx(req).project.id, filters));
+        }
+        catch (err) {
+            console.error('[project-router] spending error:', err);
+            res.status(500).json({ error: 'Failed to compute spending' });
+        }
+    });
+    // ─── Raw invocations table ───────────────────────────────────────────────────
+    router.get('/:projectId/invocations', (req, res) => {
+        const filters = (0, spending_1.parseSpendingFilters)(req.query);
+        // Clamp to [1, 10000] when provided (H-11): a negative/NaN limit becomes
+        // SQLite LIMIT -1 (unlimited) and dumps the entire invocations table.
+        const rawLimit = req.query.limit ? parseInt(req.query.limit, 10) : undefined;
+        const limit = rawLimit !== undefined && Number.isFinite(rawLimit)
+            ? Math.max(1, Math.min(rawLimit, 10_000))
+            : undefined;
+        const offset = req.query.offset ? parseInt(req.query.offset, 10) : undefined;
+        try {
+            const result = (0, spending_1.getInvocations)(ctx(req).db, ctx(req).project.id, {
+                ...filters,
+                ...(limit ? { limit } : {}),
+                ...(offset ? { offset } : {}),
+            });
+            // Enrich with ticket titles from YAML store.
+            try {
+                const store = (0, ticket_store_1.readStore)(ticketPath(req));
+                for (const r of result.rows) {
+                    if (r.ticket_id != null) {
+                        const t = store.tickets[String(r.ticket_id)];
+                        r.ticket_title = t?.title ?? null;
+                    }
+                }
+            }
+            catch { /* tickets store may not exist yet */ }
+            res.json(result);
+        }
+        catch (err) {
+            console.error('[project-router] invocations error:', err);
+            res.status(500).json({ error: 'Failed to list invocations' });
+        }
+    });
+    // ─── Per-ticket spending summary (used by TicketDetailModal) ─────────────────
+    router.get('/:projectId/tickets/:id/spending-summary', (req, res) => {
+        const ticketId = parseInt(req.params.id, 10);
+        if (Number.isNaN(ticketId)) {
+            res.status(400).json({ error: 'Invalid ticket id' });
+            return;
+        }
+        try {
+            res.json((0, ai_invocations_1.getTicketSpendingSummary)(ctx(req).db, ticketId));
+        }
+        catch (err) {
+            console.error('[project-router] ticket spending summary error:', err);
+            res.status(500).json({ error: 'Failed to compute ticket spending' });
+        }
+    });
+    // ─── Spending / analytics export (Summary + Raw, CSV or JSON) ────────────────
+    router.get('/:projectId/analytics/export', async (req, res) => {
+        const format = req.query.format || 'json';
+        const mode = req.query.mode || 'summary';
+        if (format !== 'json' && format !== 'csv') {
+            res.status(400).json({ error: 'Invalid format. Must be json or csv' });
+            return;
+        }
+        if (mode !== 'summary' && mode !== 'raw') {
+            res.status(400).json({ error: 'Invalid mode. Must be summary or raw' });
+            return;
+        }
+        const periodRaw = req.query.period ?? '30d';
+        const validPeriods = ['7d', '30d', '90d', 'all', 'custom'];
+        if (!validPeriods.includes(periodRaw)) {
+            res.status(400).json({ error: 'Invalid period. Must be one of: 7d, 30d, 90d, all, custom' });
+            return;
+        }
+        const filters = (0, spending_1.parseSpendingFilters)(req.query);
+        if (filters.period === 'custom' && (!filters.from || !filters.to)) {
+            res.status(400).json({ error: 'from and to are required for custom period' });
+            return;
+        }
+        const { project } = ctx(req);
+        const projectId = project.id;
+        const dateStamp = new Date().toISOString().slice(0, 10);
+        const periodTag = filters.period ?? '30d';
+        const surfaceTag = (filters.surface && filters.surface.length === 1)
+            ? `-${filters.surface[0].replace('-spec', '').replace('-', '')}`
+            : '';
+        try {
+            if (mode === 'summary') {
+                const data = (0, spending_1.getSpending)(ctx(req).db, projectId, filters);
+                if (format === 'json') {
+                    res.setHeader('Content-Disposition', `attachment; filename="${project.slug}-analytics-${periodTag}-${dateStamp}.json"`);
+                    res.json(data);
+                    return;
+                }
+                // CSV summary: multi-section composite
+                const lines = [];
+                lines.push('# Totals');
+                lines.push('totalCostUsd,totalRuns,prevTotalCostUsd,deltaPct,avgCostPerRun,failureRate');
+                lines.push([
+                    data.summary.totalCostUsd,
+                    data.summary.totalRuns,
+                    data.summary.prevTotalCostUsd,
+                    data.summary.deltaPct ?? '',
+                    data.summary.avgCostPerRun ?? '',
+                    data.summary.failureRate,
+                ].join(','));
+                lines.push('');
+                lines.push('# Daily timeline');
+                lines.push('date,jobsCostUsd,quickCostUsd,exploreCostUsd,aiEditCostUsd,totalCostUsd');
+                for (const d of data.dailyTimeline) {
+                    lines.push(`${d.date},${d.jobsCostUsd},${d.quickCostUsd},${d.exploreCostUsd},${d.aiEditCostUsd},${d.totalCostUsd}`);
+                }
+                lines.push('');
+                lines.push('# By surface');
+                lines.push('surface,count,costUsd');
+                for (const s of data.bySurface)
+                    lines.push(`${s.surface},${s.count},${s.costUsd}`);
+                lines.push('');
+                lines.push('# By model');
+                lines.push('model,count,costUsd');
+                for (const m of data.byModel)
+                    lines.push(`${csvEscape(m.model)},${m.count},${m.costUsd}`);
+                lines.push('');
+                lines.push('# Top tickets');
+                lines.push('ticketId,totalCostUsd,totalRuns,jobCost,quickCost,exploreCost,aiEditCost');
+                for (const t of data.topTickets) {
+                    lines.push([
+                        t.ticketId ?? '(unattributed)',
+                        t.totalCostUsd,
+                        t.totalRuns,
+                        t.bySurface.job.costUsd,
+                        t.bySurface['quick-spec'].costUsd,
+                        t.bySurface['explore-spec'].costUsd,
+                        t.bySurface['ai-edit'].costUsd,
+                    ].join(','));
+                }
+                res.setHeader('Content-Type', 'text/csv');
+                res.setHeader('Content-Disposition', `attachment; filename="${project.slug}-analytics-${periodTag}-${dateStamp}.csv"`);
+                res.send(lines.join('\n'));
+            }
+            else {
+                // raw mode: capped invocations
+                const result = (0, spending_1.getInvocations)(ctx(req).db, projectId, { ...filters, cap: 10000 });
+                // Enrich titles
+                try {
+                    const store = (0, ticket_store_1.readStore)(ticketPath(req));
+                    for (const r of result.rows) {
+                        if (r.ticket_id != null)
+                            r.ticket_title = store.tickets[String(r.ticket_id)]?.title ?? null;
+                    }
+                }
+                catch { /* no tickets yet */ }
+                if (format === 'json') {
+                    res.setHeader('Content-Disposition', `attachment; filename="${project.slug}-invocations-${periodTag}${surfaceTag}-${dateStamp}.json"`);
+                    res.json(result);
+                    return;
+                }
+                const headers = [
+                    'id', 'surface', 'surface_ref_id', 'ticket_id', 'ticket_title', 'conversation_id',
+                    'model', 'status', 'started_at', 'finished_at', 'duration_ms', 'duration_api_ms',
+                    'tokens_in', 'tokens_out', 'tokens_cache_read', 'tokens_cache_create',
+                    'total_cost_usd', 'num_turns', 'session_id'
+                ];
+                const lines = [headers.join(',')];
+                for (const r of result.rows) {
+                    lines.push(headers.map((h) => csvEscape(r[h])).join(','));
+                }
+                if (result.truncated) {
+                    lines.push(`# truncated_at=${result.rows.length} of ${result.totalAvailable}`);
+                }
+                res.setHeader('Content-Type', 'text/csv');
+                res.setHeader('Content-Disposition', `attachment; filename="${project.slug}-invocations-${periodTag}${surfaceTag}-${dateStamp}.csv"`);
+                res.send(lines.join('\n'));
+            }
+        }
+        catch (err) {
+            console.error('[project-router] export error:', err);
+            res.status(500).json({ error: 'Failed to export' });
+        }
+    });
+    function csvEscape(v) {
+        const s = v == null ? '' : String(v);
+        return s.includes(',') || s.includes('"') || s.includes('\n')
+            ? `"${s.replace(/"/g, '""')}"`
+            : s;
+    }
+    router.get('/:projectId/config', (req, res) => {
+        const { project, db } = ctx(req);
+        try {
+            const config = (0, config_1.getConfig)(project.path, db, project.name);
+            const dailyBudgetRaw = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.daily_budget_usd'`).get()?.value;
+            const dailyBudgetUsd = dailyBudgetRaw != null ? parseFloat(dailyBudgetRaw) : null;
+            const zombieTimeoutRaw = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.zombie_timeout_ms'`).get()?.value;
+            const zombieTimeoutMs = zombieTimeoutRaw != null ? parseInt(zombieTimeoutRaw, 10) : null;
+            res.json({ ...config, dailyBudgetUsd, zombieTimeoutMs });
+        }
+        catch (err) {
+            console.error('[project-router] config error:', err);
+            res.status(500).json({ error: 'Failed to read config' });
+        }
+    });
+    router.post('/:projectId/config', (req, res) => {
+        const { active, labelFilter, dailyBudgetUsd, zombieTimeoutMs } = req.body ?? {};
+        const { db, queueManager } = ctx(req);
+        try {
+            if (active !== undefined) {
+                db.prepare(`INSERT OR REPLACE INTO queue_state (key, value) VALUES ('config.active_tracker', ?)`).run(active ?? '');
+            }
+            if (labelFilter !== undefined) {
+                db.prepare(`INSERT OR REPLACE INTO queue_state (key, value) VALUES ('config.label_filter', ?)`).run(labelFilter ?? '');
+            }
+            if (dailyBudgetUsd !== undefined) {
+                if (dailyBudgetUsd === null) {
+                    db.prepare(`DELETE FROM queue_state WHERE key = 'config.daily_budget_usd'`).run();
+                }
+                else if (typeof dailyBudgetUsd === 'number' && dailyBudgetUsd > 0) {
+                    db.prepare(`INSERT OR REPLACE INTO queue_state (key, value) VALUES ('config.daily_budget_usd', ?)`).run(String(dailyBudgetUsd));
+                }
+            }
+            if (zombieTimeoutMs !== undefined) {
+                if (zombieTimeoutMs === null) {
+                    db.prepare(`DELETE FROM queue_state WHERE key = 'config.zombie_timeout_ms'`).run();
+                }
+                else if (typeof zombieTimeoutMs === 'number' && zombieTimeoutMs > 0) {
+                    db.prepare(`INSERT OR REPLACE INTO queue_state (key, value) VALUES ('config.zombie_timeout_ms', ?)`).run(String(zombieTimeoutMs));
+                }
+                queueManager.setZombieTimeout(typeof zombieTimeoutMs === 'number' && zombieTimeoutMs > 0 ? zombieTimeoutMs : queue_manager_1.DEFAULT_ZOMBIE_TIMEOUT_MS);
+            }
+            res.json({ ok: true });
+        }
+        catch (err) {
+            console.error('[project-router] config persist error:', err);
+            res.status(500).json({ error: 'Failed to persist config' });
+        }
+    });
+    // ─── Budget routes ────────────────────────────────────────────────────────────
+    router.get('/:projectId/budget', (req, res) => {
+        const { db } = ctx(req);
+        try {
+            const dailyBudgetRaw = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.daily_budget_usd'`).get()?.value;
+            const dailyBudgetUsd = dailyBudgetRaw != null ? parseFloat(dailyBudgetRaw) : null;
+            const jobThresholdRaw = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.job_cost_threshold_usd'`).get()?.value;
+            const jobCostThresholdUsd = jobThresholdRaw != null ? parseFloat(jobThresholdRaw) : null;
+            const costRow = db.prepare(`SELECT COALESCE(SUM(total_cost_usd), 0) as costToday FROM jobs WHERE started_at >= date('now')`).get();
+            const costToday = costRow.costToday;
+            const budgetUtilizationPct = dailyBudgetUsd != null && dailyBudgetUsd > 0
+                ? (costToday / dailyBudgetUsd) * 100
+                : null;
+            res.json({ dailyBudgetUsd, jobCostThresholdUsd, costToday, budgetUtilizationPct });
+        }
+        catch (err) {
+            console.error('[project-router] budget get error:', err);
+            res.status(500).json({ error: 'Failed to read budget' });
+        }
+    });
+    router.patch('/:projectId/budget', (req, res) => {
+        const { dailyBudgetUsd, jobCostThresholdUsd } = req.body ?? {};
+        const { db } = ctx(req);
+        try {
+            if (dailyBudgetUsd !== undefined) {
+                if (dailyBudgetUsd === null) {
+                    db.prepare(`DELETE FROM queue_state WHERE key = 'config.daily_budget_usd'`).run();
+                }
+                else if (typeof dailyBudgetUsd === 'number' && dailyBudgetUsd > 0) {
+                    db.prepare(`INSERT OR REPLACE INTO queue_state (key, value) VALUES ('config.daily_budget_usd', ?)`).run(String(dailyBudgetUsd));
+                }
+            }
+            if (jobCostThresholdUsd !== undefined) {
+                if (jobCostThresholdUsd === null) {
+                    db.prepare(`DELETE FROM queue_state WHERE key = 'config.job_cost_threshold_usd'`).run();
+                }
+                else if (typeof jobCostThresholdUsd === 'number' && jobCostThresholdUsd > 0) {
+                    db.prepare(`INSERT OR REPLACE INTO queue_state (key, value) VALUES ('config.job_cost_threshold_usd', ?)`).run(String(jobCostThresholdUsd));
+                }
+            }
+            res.json({ ok: true });
+        }
+        catch (err) {
+            console.error('[project-router] budget patch error:', err);
+            res.status(500).json({ error: 'Failed to update budget' });
+        }
+    });
+    router.get('/:projectId/issues', (req, res) => {
+        const { project, db } = ctx(req);
+        try {
+            const config = (0, config_1.getConfig)(project.path, db, project.name);
+            const tracker = config.issueTracker.active;
+            if (!tracker) {
+                res.status(503).json({ error: 'No issue tracker configured', trackers: config.issueTracker });
+                return;
+            }
+            const search = req.query.search;
+            const label = req.query.label;
+            const issues = (0, config_1.fetchIssues)(tracker, { search, label, repo: config.project.repo, cwd: project.path });
+            res.json(issues);
+        }
+        catch (err) {
+            console.error('[project-router] issues error:', err);
+            res.status(500).json({ error: 'Failed to fetch issues' });
+        }
+    });
+}

package/server/dist/project-router-terminals.js

@@ -0,0 +1,312 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTerminalsRoutes = registerTerminalsRoutes;
+const terminal_settings_1 = require("./terminal-settings");
+const feature_flags_1 = require("./feature-flags");
+const browser_capture_types_1 = require("./browser-capture-types");
+const terminal_manager_1 = require("./terminal-manager");
+const project_router_helpers_1 = require("./project-router-helpers");
+function registerTerminalsRoutes(deps) {
+    const { router, registry, ctx, ticketPath } = deps;
+    // ─── Terminals ───────────────────────────────────────────────────────────────
+    function requireTerminalsEnabled(_req, res, next) {
+        if (!project_router_helpers_1.TERMINAL_PANEL_ENABLED) {
+            res.status(404).json({ error: 'Terminal panel disabled' });
+            return;
+        }
+        next();
+    }
+    router.get('/:projectId/terminals', requireTerminalsEnabled, (req, res) => {
+        const projectId = ctx(req).project.id;
+        const sessions = (0, terminal_manager_1.getTerminalManager)().listForProject(projectId);
+        res.json({ sessions, limit: terminal_manager_1.TERMINAL_MAX_PER_PROJECT });
+    });
+    router.post('/:projectId/terminals', requireTerminalsEnabled, (req, res) => {
+        const { cols, rows, name } = req.body ?? {};
+        const projectCtx = ctx(req);
+        const project = projectCtx.project;
+        const settings = (0, terminal_settings_1.resolveTerminalSettings)(registry.desktopDb, projectCtx.db);
+        try {
+            const meta = (0, terminal_manager_1.getTerminalManager)().create(project.id, {
+                cwd: project.path,
+                cols: typeof cols === 'number' ? cols : undefined,
+                rows: typeof rows === 'number' ? rows : undefined,
+                name: typeof name === 'string' ? name : undefined,
+                projectSlug: project.slug,
+                projectDb: projectCtx.db,
+                settings,
+            });
+            res.status(201).json({ session: meta });
+        }
+        catch (err) {
+            if (err instanceof terminal_manager_1.TerminalLimitExceededError) {
+                res.status(409).json({ error: 'terminal_limit_exceeded', limit: terminal_manager_1.TERMINAL_MAX_PER_PROJECT });
+                return;
+            }
+            if (err instanceof terminal_manager_1.TerminalNameInvalidError) {
+                res.status(400).json({ error: 'terminal_name_invalid' });
+                return;
+            }
+            if (err instanceof terminal_manager_1.TerminalSpawnError) {
+                // The shell failed to spawn (commonly the host running out of file
+                // descriptors). Surface a concrete, actionable reason — a bare 500 hid
+                // this and made the "+" button look like it did nothing.
+                console.error('[project-router] terminal spawn failed:', err.reason, err.message);
+                res.status(502).json({ error: 'terminal_spawn_failed', reason: err.reason });
+                return;
+            }
+            console.error('[project-router] terminal create error:', err);
+            res.status(500).json({ error: 'Failed to create terminal' });
+        }
+    });
+    router.patch('/:projectId/terminals/:id', requireTerminalsEnabled, (req, res) => {
+        const { name } = req.body ?? {};
+        if (typeof name !== 'string') {
+            res.status(400).json({ error: 'name is required' });
+            return;
+        }
+        const projectId = ctx(req).project.id;
+        try {
+            const meta = (0, terminal_manager_1.getTerminalManager)().rename(projectId, req.params.id, name);
+            res.json({ session: meta });
+        }
+        catch (err) {
+            if (err instanceof terminal_manager_1.TerminalNotFoundError) {
+                res.status(404).json({ error: 'terminal_not_found' });
+                return;
+            }
+            if (err instanceof terminal_manager_1.TerminalNameInvalidError) {
+                res.status(400).json({ error: 'terminal_name_invalid' });
+                return;
+            }
+            console.error('[project-router] terminal rename error:', err);
+            res.status(500).json({ error: 'Failed to rename terminal' });
+        }
+    });
+    router.delete('/:projectId/terminals/:id', requireTerminalsEnabled, (req, res) => {
+        const projectId = ctx(req).project.id;
+        const ok = (0, terminal_manager_1.getTerminalManager)().kill(projectId, req.params.id);
+        if (!ok) {
+            res.status(404).json({ error: 'terminal_not_found' });
+            return;
+        }
+        res.json({ ok: true });
+    });
+    // ─── Embedded browser ("Add Spec from browser") ──────────────────────────────
+    function requireBrowserCaptureEnabled(_req, res, next) {
+        if (!(0, feature_flags_1.isBrowserCaptureEnabled)()) {
+            res.status(404).json({ error: 'browser_capture_disabled' });
+            return;
+        }
+        next();
+    }
+    function parseRect(raw) {
+        if (!raw || typeof raw !== 'object')
+            return null;
+        const r = raw;
+        const nums = [r.x, r.y, r.width, r.height];
+        if (!nums.every((n) => typeof n === 'number' && Number.isFinite(n)))
+            return null;
+        const x = r.x, y = r.y, width = r.width, height = r.height;
+        if (width <= 0 || height <= 0)
+            return null;
+        if (x < 0 || y < 0)
+            return null;
+        // Upper bound guards against an over-read request far past any real viewport.
+        if (x + width > 20000 || y + height > 20000)
+            return null;
+        return { x, y, width, height };
+    }
+    // pendingSpecId becomes a filesystem path segment inside attachmentManager
+    // (~/.specrails/projects/<slug>/attachments/<pendingSpecId>/). Reject anything
+    // that isn't a safe opaque token so a crafted value can't traverse the tree.
+    const SAFE_PENDING_ID = /^[A-Za-z0-9_-]{1,128}$/;
+    router.get('/:projectId/browser/sessions', requireBrowserCaptureEnabled, (req, res) => {
+        const mgr = ctx(req).browserCaptureManager;
+        res.json({ sessions: mgr.listSessions(), lastUrl: mgr.getLastUrl() });
+    });
+    router.post('/:projectId/browser/sessions', requireBrowserCaptureEnabled, async (req, res) => {
+        const mgr = ctx(req).browserCaptureManager;
+        const initialUrl = typeof req.body?.initialUrl === 'string' ? req.body.initialUrl : undefined;
+        try {
+            const session = await mgr.create({ initialUrl });
+            res.status(201).json({ session });
+        }
+        catch (err) {
+            if (err instanceof browser_capture_types_1.BrowserLimitExceededError) {
+                res.status(409).json({ error: 'browser_session_limit_exceeded', limit: err.limit });
+                return;
+            }
+            if (err instanceof browser_capture_types_1.BrowserLaunchError) {
+                console.error('[project-router] browser launch failed:', err.cause?.message ?? err.message);
+                res.status(502).json({ error: 'browser_launch_failed' });
+                return;
+            }
+            console.error('[project-router] browser session create error:', err);
+            res.status(500).json({ error: 'Failed to create browser session' });
+        }
+    });
+    router.post('/:projectId/browser/sessions/:id/navigate', requireBrowserCaptureEnabled, async (req, res) => {
+        const mgr = ctx(req).browserCaptureManager;
+        const action = req.body?.action ?? 'goto';
+        const validActions = new Set(['goto', 'back', 'forward', 'reload']);
+        if (!validActions.has(action)) {
+            res.status(400).json({ error: 'action must be one of: goto, back, forward, reload' });
+            return;
+        }
+        let url;
+        if (action === 'goto') {
+            url = typeof req.body?.url === 'string' ? req.body.url.trim() : '';
+            if (!url) {
+                res.status(400).json({ error: 'url is required for goto' });
+                return;
+            }
+            // Only allow web schemes (or bare hosts the manager will https-prefix).
+            // Blocks file://, data:, javascript: etc. from reaching the embedded browser.
+            if (/^[a-z][a-z0-9+.-]*:/i.test(url) && !/^https?:\/\//i.test(url)) {
+                res.status(400).json({ error: 'only http(s) URLs are allowed' });
+                return;
+            }
+        }
+        try {
+            const result = await mgr.navigate(req.params.id, action, url);
+            if (!result) {
+                res.status(404).json({ error: 'browser_session_not_found' });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            console.error('[project-router] browser navigate error:', err);
+            res.status(500).json({ error: 'Failed to navigate' });
+        }
+    });
+    router.post('/:projectId/browser/sessions/:id/capture', requireBrowserCaptureEnabled, async (req, res) => {
+        const mgr = ctx(req).browserCaptureManager;
+        const rect = parseRect(req.body?.rect);
+        if (!rect) {
+            res.status(400).json({ error: 'rect {x,y,width,height} with positive size is required' });
+            return;
+        }
+        const pendingSpecId = typeof req.body?.pendingSpecId === 'string' ? req.body.pendingSpecId.trim() : '';
+        if (!pendingSpecId) {
+            res.status(400).json({ error: 'pendingSpecId is required' });
+            return;
+        }
+        if (!SAFE_PENDING_ID.test(pendingSpecId)) {
+            res.status(400).json({ error: 'pendingSpecId has an invalid format' });
+            return;
+        }
+        const captureNetwork = req.body?.captureNetwork !== false;
+        try {
+            const result = await mgr.capture(req.params.id, rect, pendingSpecId, { captureNetwork });
+            if (!result) {
+                res.status(404).json({ error: 'browser_session_not_found' });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            console.error('[project-router] browser capture error:', err);
+            res.status(500).json({ error: 'Failed to capture' });
+        }
+    });
+    router.post('/:projectId/browser/sessions/:id/capture-breakpoints', requireBrowserCaptureEnabled, async (req, res) => {
+        const mgr = ctx(req).browserCaptureManager;
+        const rect = parseRect(req.body?.rect);
+        if (!rect) {
+            res.status(400).json({ error: 'rect {x,y,width,height} with positive size is required' });
+            return;
+        }
+        const pendingSpecId = typeof req.body?.pendingSpecId === 'string' ? req.body.pendingSpecId.trim() : '';
+        if (!pendingSpecId || !SAFE_PENDING_ID.test(pendingSpecId)) {
+            res.status(400).json({ error: 'pendingSpecId is required and must be well-formed' });
+            return;
+        }
+        // Validate the per-breakpoint viewport dims (client-supplied; single source).
+        const rawDims = req.body?.breakpoints;
+        const dims = {};
+        if (rawDims && typeof rawDims === 'object') {
+            for (const [k, v] of Object.entries(rawDims)) {
+                if (Object.keys(dims).length >= 4)
+                    break;
+                if (!/^[a-z0-9_-]{1,20}$/i.test(k))
+                    continue;
+                const d = v;
+                const w = Math.round(Number(d?.width));
+                const h = Math.round(Number(d?.height));
+                if (Number.isFinite(w) && Number.isFinite(h) && w >= 1 && h >= 1 && w <= 4000 && h <= 4000) {
+                    dims[k] = { width: w, height: h };
+                }
+            }
+        }
+        if (Object.keys(dims).length === 0) {
+            res.status(400).json({ error: 'breakpoints {name:{width,height}} is required' });
+            return;
+        }
+        const a = req.body?.anchorPoint;
+        const anchorPoint = a && typeof a.x === 'number' && typeof a.y === 'number'
+            ? { x: a.x, y: a.y }
+            : { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+        try {
+            const result = await mgr.captureBreakpoints(req.params.id, rect, anchorPoint, pendingSpecId, dims);
+            if (!result) {
+                res.status(404).json({ error: 'browser_session_not_found' });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            console.error('[project-router] browser capture-breakpoints error:', err);
+            res.status(500).json({ error: 'Failed to capture' });
+        }
+    });
+    router.post('/:projectId/browser/sessions/:id/element', requireBrowserCaptureEnabled, async (req, res) => {
+        const mgr = ctx(req).browserCaptureManager;
+        const selector = typeof req.body?.selector === 'string' ? req.body.selector : '';
+        const direction = req.body?.direction;
+        if (!selector || (direction !== 'parent' && direction !== 'child' && direction !== 'self')) {
+            res.status(400).json({ error: 'selector and direction (parent|child|self) are required' });
+            return;
+        }
+        try {
+            // probe may be null (can't step further / element gone) — still 200.
+            const probe = await mgr.navigateElement(req.params.id, selector.slice(0, 4000), direction);
+            res.json({ probe });
+        }
+        catch (err) {
+            console.error('[project-router] browser element navigate error:', err);
+            res.status(500).json({ error: 'Failed to resolve element' });
+        }
+    });
+    router.post('/:projectId/browser/sessions/:id/clipboard', requireBrowserCaptureEnabled, async (req, res) => {
+        const mgr = ctx(req).browserCaptureManager;
+        const action = req.body?.action;
+        if (action !== 'copy' && action !== 'paste' && action !== 'cut') {
+            res.status(400).json({ error: 'action must be copy | paste | cut' });
+            return;
+        }
+        const text = typeof req.body?.text === 'string' ? req.body.text.slice(0, 100_000) : undefined;
+        try {
+            const out = await mgr.clipboard(req.params.id, action, text);
+            if (!out) {
+                res.status(404).json({ error: 'browser_session_not_found' });
+                return;
+            }
+            res.json(out);
+        }
+        catch (err) {
+            console.error('[project-router] browser clipboard error:', err);
+            res.status(500).json({ error: 'Failed clipboard op' });
+        }
+    });
+    router.delete('/:projectId/browser/sessions/:id', requireBrowserCaptureEnabled, async (req, res) => {
+        const mgr = ctx(req).browserCaptureManager;
+        const ok = await mgr.kill(req.params.id);
+        if (!ok) {
+            res.status(404).json({ error: 'browser_session_not_found' });
+            return;
+        }
+        res.json({ ok: true });
+    });
+}