specrails-desktop 2.63.2 → 2.64.0

package/client/dist/index.html

@@ -204,7 +204,7 @@
         .specrails-splash__mark .pill { opacity: 1; }
       }
     </style>
-    <script type="module" crossorigin src="/assets/index-CECj3joE.js"></script>
+    <script type="module" crossorigin src="/assets/index-IdGpV21X.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-CNC7AqOf.js">
     <link rel="modulepreload" crossorigin href="/assets/jsx-runtime-BbYvbtY8.js">
     <link rel="modulepreload" crossorigin href="/assets/react-dom-DDD8FYaU.js">
@@ -236,23 +236,23 @@
     <link rel="modulepreload" crossorigin href="/assets/narration-DbHnz0qV.js">
     <link rel="modulepreload" crossorigin href="/assets/nav--u7iPYlS.js">
     <link rel="modulepreload" crossorigin href="/assets/packet-B0H15elv.js">
-    <link rel="modulepreload" crossorigin href="/assets/settings-nryN6wuS.js">
+    <link rel="modulepreload" crossorigin href="/assets/settings-Pyw8uYtL.js">
     <link rel="modulepreload" crossorigin href="/assets/setup-CKGUxKr-.js">
     <link rel="modulepreload" crossorigin href="/assets/specs-DfIdoU5L.js">
     <link rel="modulepreload" crossorigin href="/assets/subscriptionUsage-CdlE5Mg1.js">
     <link rel="modulepreload" crossorigin href="/assets/terminal-BAzpHtpY.js">
     <link rel="modulepreload" crossorigin href="/assets/tickets-D41ZMQpf.js">
     <link rel="modulepreload" crossorigin href="/assets/createLucideIcon-DtODIU64.js">
-    <link rel="modulepreload" crossorigin href="/assets/useSharedWebSocket-CcsE5986.js">
-    <link rel="modulepreload" crossorigin href="/assets/Trans-ZiXIfj50.js">
-    <link rel="modulepreload" crossorigin href="/assets/useDesktop-C0mRIlHT.js">
+    <link rel="modulepreload" crossorigin href="/assets/useSharedWebSocket-Bj4LMp7b.js">
+    <link rel="modulepreload" crossorigin href="/assets/Trans-BbFxRFtR.js">
+    <link rel="modulepreload" crossorigin href="/assets/useDesktop-BjLT0_EE.js">
     <link rel="modulepreload" crossorigin href="/assets/provider-capabilities-lePfeT_Y.js">
     <link rel="modulepreload" crossorigin href="/assets/save-LmPSfsvZ.js">
-    <link rel="modulepreload" crossorigin href="/assets/spending-eWiZGhC_.js">
+    <link rel="modulepreload" crossorigin href="/assets/spending-CQnrWiR3.js">
     <link rel="modulepreload" crossorigin href="/assets/chevron-up-6EFqEHBj.js">
     <link rel="modulepreload" crossorigin href="/assets/sparkles-CCfUdFGY.js">
     <link rel="modulepreload" crossorigin href="/assets/x-Bu7X_eR2.js">
-    <link rel="modulepreload" crossorigin href="/assets/MinimizedChatsContext-BHIUPVmC.js">
+    <link rel="modulepreload" crossorigin href="/assets/MinimizedChatsContext-DHfigjHS.js">
     <link rel="modulepreload" crossorigin href="/assets/ban-wqfdzoXt.js">
     <link rel="modulepreload" crossorigin href="/assets/file-text-C0blZHLh.js">
     <link rel="modulepreload" crossorigin href="/assets/circle-x-D2ttKotB.js">
@@ -268,21 +268,21 @@
     <link rel="modulepreload" crossorigin href="/assets/search-BDVp3fkH.js">
     <link rel="modulepreload" crossorigin href="/assets/trash-D8zYUmTg.js">
     <link rel="modulepreload" crossorigin href="/assets/triangle-alert-Cxpn8bqr.js">
-    <link rel="modulepreload" crossorigin href="/assets/jira-api-C_D_RDhl.js">
+    <link rel="modulepreload" crossorigin href="/assets/jira-api-Cabj-H0J.js">
     <link rel="modulepreload" crossorigin href="/assets/zap-bugHyWzQ.js">
     <link rel="modulepreload" crossorigin href="/assets/clsx-CjueKrWZ.js">
     <link rel="modulepreload" crossorigin href="/assets/utils-BC4DHlz2.js">
     <link rel="modulepreload" crossorigin href="/assets/dialog-DtdR05v1.js">
     <link rel="modulepreload" crossorigin href="/assets/lib-DWJfei6y.js">
-    <link rel="modulepreload" crossorigin href="/assets/getTimezoneOffsetInMilliseconds-62h40I4t.js">
-    <link rel="modulepreload" crossorigin href="/assets/formatDistanceToNow-CdN5lTyD.js">
+    <link rel="modulepreload" crossorigin href="/assets/getTimezoneOffsetInMilliseconds-vJ7qUoqN.js">
+    <link rel="modulepreload" crossorigin href="/assets/formatDistanceToNow-NjPHBLfB.js">
     <link rel="modulepreload" crossorigin href="/assets/button-4FS1ZDTp.js">
-    <link rel="modulepreload" crossorigin href="/assets/project-repositories-Be0CWklo.js">
-    <link rel="modulepreload" crossorigin href="/assets/RepositoryScopeSelector-DeCoUsRN.js">
-    <link rel="modulepreload" crossorigin href="/assets/TicketDetailModalContext-DiPngt2g.js">
+    <link rel="modulepreload" crossorigin href="/assets/project-repositories-Cnnuj9Ia.js">
+    <link rel="modulepreload" crossorigin href="/assets/RepositoryScopeSelector-2eSqR9WK.js">
+    <link rel="modulepreload" crossorigin href="/assets/TicketDetailModalContext-Dkwo2cDs.js">
     <link rel="modulepreload" crossorigin href="/assets/core-B3mKBIh5.js">
-    <link rel="modulepreload" crossorigin href="/assets/RepositoryDeliveries-DAIxIYsl.js">
-    <link rel="modulepreload" crossorigin href="/assets/useRuntimeRuns-B1a6GChu.js">
+    <link rel="modulepreload" crossorigin href="/assets/RepositoryDeliveries-B4ybHOyB.js">
+    <link rel="modulepreload" crossorigin href="/assets/useRuntimeRuns-C97qEqMg.js">
     <link rel="modulepreload" crossorigin href="/assets/event-Bt7f3wXe.js">
     <link rel="stylesheet" crossorigin href="/assets/index-BgbCbIua.css">
   </head>

package/docs/internals/api-reference.md

@@ -127,6 +127,32 @@ Loopback-only admin surface for the Mobile Gateway (the gateway itself is a sepa
 | `GET` | `/devices` | List paired devices |
 | `DELETE` | `/devices/:id` | Revoke a paired device |
 | `POST` | `/cert/rotate` | Rotate the gateway TLS identity (unpairs every device) |
+| `GET` | `/previews` | Live Companion app previews (`{ previews: [{ projectId, projectName, sessionId, deviceId, deviceName, url, title, createdAt }] }`) |
+| `DELETE` | `/previews/:projectId/:sessionId` | End a device-owned preview from Desktop (`{ ok }`; Desktop sessions are never affected) |
+
+Revoking a device also ends its previews. The app-level WS event `mobile.previews_changed` (no `projectId`) tells Settings ▸ Mobile to refetch the list.
+
+#### Companion app preview (gateway `/v1`)
+
+A paired Companion views a project's locally served web app through a device-owned server-side browser session. The routes require the mission grant (all-projects device) and the `appPreview` capability (`GET /v1/capabilities` → `features.appPreview`, true when browser capture is enabled).
+
+| Method | Path | Notes |
+|--------|------|-------|
+| `GET` | `/v1/projects/:pid/missions/:cid/preview-targets` | `{ targets: [{ processId, urls }] }`: local URLs announced in the logs of the mission's running background processes |
+| `POST` | `/v1/projects/:pid/preview-sessions` | Body `{ missionId, processId, url, viewport? }`; `url` must be announced by that process. `201 { sessionId, channel, url }` |
+| `POST` | `/v1/projects/:pid/preview-sessions/:sid/attach` | Re-attach after a reconnect: `{ sessionId, channel }` (a new DataChannel replaces the old one) |
+| `POST` | `/v1/projects/:pid/preview-sessions/:sid/navigate` | Body `{ action: goto\|back\|forward\|reload, url? }`; `goto` accepts only paths on announced origins |
+| `DELETE` | `/v1/projects/:pid/preview-sessions/:sid` | End the device's own preview |
+
+Errors carry `{ error, code }`. Codes: `preview_unavailable` (404), `preview_target_gone` (404), `preview_session_closed` (404), `preview_url_not_announced` (400), `preview_limit` (429), `preview_requires_webrtc` (409), `preview_failed` (502). Sessions owned by Desktop or by another device are reported as `preview_session_closed`.
+
+**Channel.** `channel` is the label of an ordered, reliable DataChannel (`preview:<sessionId>`) that Desktop opens on the device's existing WebRTC peer without renegotiation:
+
+- **Desktop → Companion, text:** JSON control: `ready` (`{ id, url, title, viewport }`), `nav`, `popup`, `closed` (`{ reason }`) and `nav_rejected`.
+- **Desktop → Companion, binary:** JPEG screencast frames in fragments of at most 16 000 bytes. Each fragment starts with an 8-byte big-endian header `u32 frameSeq | u16 index | u16 count`. Render a frame only when all of its fragments have arrived. A newer `frameSeq` discards an incomplete older frame.
+- **Companion → Desktop:** JSON `{ type: 'input', event }` (mouse / wheel / key / resize, validated) and `{ type: 'navigate', action, url? }`, rate-limited to 6 000 messages per minute.
+
+**Origin policy.** A device session may load a loopback origin only while a running background process of the project announces it. Every other request passes the regular server-side SSRF guard. Device sessions have their own budget: one per device (opening a new one replaces it) and two per project. They never count against Desktop's four sessions.
 
 ### specrails-tech proxy
 

package/docs/internals/source-map.md

@@ -5,7 +5,7 @@ architectural dependency declaration. Search a heading or filename and read only
 the relevant source and tests. Feature prefixes group the legacy server files;
 new bounded modules live under `server/modules/`.
 
-Includes 1046 source/build files. Nearby tests are linked where names
+Includes 1050 source/build files. Nearby tests are linked where names
 match; integration suites may live elsewhere. Use `rg` to find other consumers.
 
 ## cli
@@ -1057,6 +1057,8 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [mobile-event-bus.ts](../../server/mobile/mobile-event-bus.ts)
 - [mobile-gateway.ts](../../server/mobile/mobile-gateway.ts) · [test](../../server/mobile/mobile-gateway.test.ts)
 - [mobile-missions.ts](../../server/mobile/mobile-missions.ts) · [test](../../server/mobile/mobile-missions.test.ts)
+- [mobile-preview-channel.ts](../../server/mobile/mobile-preview-channel.ts) · [test](../../server/mobile/mobile-preview-channel.test.ts)
+- [mobile-preview.ts](../../server/mobile/mobile-preview.ts) · [test](../../server/mobile/mobile-preview.test.ts)
 - [mobile-redact.ts](../../server/mobile/mobile-redact.ts) · [test](../../server/mobile/mobile-redact.test.ts)
 - [mobile-router.ts](../../server/mobile/mobile-router.ts) · [test](../../server/mobile/mobile-router.test.ts)
 - [mobile-signal-reconnect.ts](../../server/mobile/mobile-signal-reconnect.ts) · [test](../../server/mobile/mobile-signal-reconnect.test.ts)
@@ -1148,6 +1150,10 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [profile-manager.ts](../../server/modules/agents/runtime/profile-manager.ts) · [test](../../server/modules/agents/runtime/profile-manager.test.ts)
 - [profiles-router.ts](../../server/modules/agents/runtime/profiles-router.ts) · [test](../../server/modules/agents/runtime/profiles-router.test.ts)
 
+## server/modules/browser/domain
+
+- [preview-origins.ts](../../server/modules/browser/domain/preview-origins.ts) · [test](../../server/modules/browser/domain/preview-origins.test.ts)
+
 ## server/modules/browser/runtime
 
 - [browser-capture-manager.ts](../../server/modules/browser/runtime/browser-capture-manager.ts) · [test](../../server/modules/browser/runtime/browser-capture-manager.test.ts)
@@ -1156,6 +1162,7 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [browser-network.ts](../../server/modules/browser/runtime/browser-network.ts) · [test](../../server/modules/browser/runtime/browser-network.test.ts)
 - [browser-playwright.ts](../../server/modules/browser/runtime/browser-playwright.ts) · [test](../../server/modules/browser/runtime/browser-playwright.test.ts)
 - [browser-viewport.ts](../../server/modules/browser/runtime/browser-viewport.ts) · [test](../../server/modules/browser/runtime/browser-viewport.test.ts)
+- [preview-targets.ts](../../server/modules/browser/runtime/preview-targets.ts) · [test](../../server/modules/browser/runtime/preview-targets.test.ts)
 
 ## server/modules/builder/runtime
 
@@ -1406,7 +1413,7 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 ## server/modules/terminals/runtime
 
 - [background-process-control.ts](../../server/modules/terminals/runtime/background-process-control.ts) · [test](../../server/modules/terminals/runtime/background-process-control.test.ts)
-- [background-process-service.ts](../../server/modules/terminals/runtime/background-process-service.ts)
+- [background-process-service.ts](../../server/modules/terminals/runtime/background-process-service.ts) · [test](../../server/modules/terminals/runtime/background-process-service.test.ts)
 - [background-process-store.ts](../../server/modules/terminals/runtime/background-process-store.ts) · [test](../../server/modules/terminals/runtime/background-process-store.test.ts)
 - [background-windows-bootstrap.ts](../../server/modules/terminals/runtime/background-windows-bootstrap.ts) · [test](../../server/modules/terminals/runtime/background-windows-bootstrap.test.ts)
 - [terminal-manager.ts](../../server/modules/terminals/runtime/terminal-manager.ts) · [test](../../server/modules/terminals/runtime/terminal-manager.test.ts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.63.2",
+  "version": "2.64.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/server/dist/index.js

@@ -623,7 +623,20 @@ function applyPtyWsRateLimiting(ws) {
     // Second HTTPS+WSS listener in THIS process; the main server stays loopback.
     // The control plane is desktop-only: loopback + (via /api below) requireAuth.
     // Mounted before the /api desktop router so its sub-path is unambiguous.
-    const mobileGateway = new mobile_1.MobileGateway({ desktopDb: registry.desktopDb, desktopPort: port, broadcast });
+    const mobileGateway = new mobile_1.MobileGateway({
+        desktopDb: registry.desktopDb,
+        desktopPort: port,
+        broadcast,
+        // Companion app preview: each project's browser + the process-log targets.
+        preview: {
+            enabled: () => BROWSER_CAPTURE_ENABLED,
+            browserFor: (projectId) => registry.getContext(projectId)?.browserCaptureManager ?? null,
+            allBrowsers: () => registry.listProjects()
+                .map((project) => registry.getContext(project.id)?.browserCaptureManager)
+                .filter((manager) => manager != null),
+            targets: registry.previewTargets,
+        },
+    });
     _mobileGateway = mobileGateway;
     app.use('/api/mobile', auth_1.requireLoopback, (0, mobile_1.createMobileAdminRouter)({
         gateway: mobileGateway,

package/server/dist/mobile/mobile-admin-router.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMobileAdminRouter = createMobileAdminRouter;
 const express_1 = require("express");
 const mobile_devices_1 = require("./mobile-devices");
+const desktop_db_1 = require("../desktop-db");
 const DEVICE_ID_RE = /^[A-Za-z0-9-]{1,64}$/;
 function createMobileAdminRouter(deps) {
     const router = (0, express_1.Router)();
@@ -37,10 +38,25 @@ function createMobileAdminRouter(deps) {
         const changed = (0, mobile_devices_1.revokeDevice)(desktopDb, id);
         if (changed) {
             gateway.bridge?.closeForDevice(id);
+            void gateway.closePreviewsForDevice(id).catch(() => { });
             deps.broadcast({ type: 'mobile.device_revoked', deviceId: id, timestamp: new Date().toISOString() });
         }
         res.json({ ok: changed });
     });
+    // —— Companion app previews (Desktop indicator) ——
+    router.get('/previews', (_req, res) => {
+        const previews = gateway.preview?.listDeviceSessions() ?? [];
+        res.json({ previews: previews.map((p) => ({ ...p, projectName: (0, desktop_db_1.getProject)(desktopDb, p.projectId)?.name ?? p.projectId })) });
+    });
+    router.delete('/previews/:projectId/:sessionId', async (req, res) => {
+        const projectId = typeof req.params.projectId === 'string' ? req.params.projectId : '';
+        const sessionId = typeof req.params.sessionId === 'string' ? req.params.sessionId : '';
+        if (!/^[A-Za-z0-9_-]{1,160}$/.test(projectId) || !/^[A-Za-z0-9_-]{1,160}$/.test(sessionId)) {
+            res.status(400).json({ error: 'Invalid parameter' });
+            return;
+        }
+        res.json({ ok: (await gateway.preview?.endFromDesktop(projectId, sessionId)) ?? false });
+    });
     router.post('/cert/rotate', async (_req, res) => {
         const status = await gateway.rotateCert();
         res.json(status);

package/server/dist/mobile/mobile-gateway.js

@@ -17,6 +17,7 @@ const mobile_webrtc_peer_1 = require("./mobile-webrtc-peer");
 const mobile_signal_reconnect_1 = require("./mobile-signal-reconnect");
 const mobile_webrtc_1 = require("./mobile-webrtc");
 const agent_store_1 = require("../modules/agents/runtime/agent-store");
+const mobile_preview_1 = require("./mobile-preview");
 // Lifecycle owner of the second HTTPS+WSS listener (default :4202), hard-isolated
 // from the main server. Off by default; started on enable or boot-if-enabled.
 const DEFAULT_PORT = 4202;
@@ -47,12 +48,28 @@ class MobileGateway {
     _running = false;
     _boundPort = DEFAULT_PORT;
     _portOverride;
+    _preview;
     constructor(deps) {
         this._db = deps.desktopDb;
         this._desktopPort = deps.desktopPort;
         this._broadcast = deps.broadcast;
         this._bindHost = deps.bindHost ?? '0.0.0.0';
         this._portOverride = deps.port;
+        this._preview = deps.preview
+            ? new mobile_preview_1.MobilePreviewService({
+                ...deps.preview,
+                openChannel: (deviceId, label) => this._webrtc?.openChannel(deviceId, label) ?? null,
+                onChange: () => this._broadcast({ type: 'mobile.previews_changed', timestamp: new Date().toISOString() }),
+            })
+            : null;
+    }
+    get preview() {
+        return this._preview;
+    }
+    /** A revoked device loses its peer mapping and every preview it owns. */
+    async closePreviewsForDevice(deviceId) {
+        this._webrtc?.forgetDevice(deviceId);
+        await this._preview?.closeForDevice(deviceId);
     }
     get bridge() {
         return this._bridge;
@@ -139,6 +156,7 @@ class MobileGateway {
             db: this._db,
             desktopPort: this._desktopPort,
             currentFingerprint: () => this._cert.fingerprint,
+            ...(this._preview ? { preview: this._preview } : {}),
         }));
         const server = https_1.default.createServer({ cert: this._cert.certPem, key: this._cert.keyPem }, app);
         // BUG-MOBILE-02: scope each socket's subscribe to the device's granted

package/server/dist/mobile/mobile-missions.js

@@ -16,9 +16,11 @@ const record = (value) => value && typeof value === 'object' && !Array.isArray(v
 const pick = (value, keys) => Object.fromEntries(Object.entries(record(value)).filter(([key]) => keys.includes(key)));
 exports.MOBILE_PROTOCOL_VERSION = 2;
 exports.MISSION_ACCESS_REASON = 'Mission agents can access more than their pinned project. Missions require an all-projects device grant; your permitted Specs and Rails remain available.';
-function mobileCapabilities(db, deviceId) {
+function mobileCapabilities(db, deviceId, opts = {}) {
     const missions = process.env.SPECRAILS_AGENT_CHAT !== 'false' && (0, mobile_devices_1.getAllowedProjects)(db, deviceId) === null;
-    return { protocolVersion: exports.MOBILE_PROTOCOL_VERSION, features: { missions, missionControl: missions, missionQueue: missions, missionProcesses: missions, repositories: true, codeExplorer: (0, feature_flags_1.isCodeExplorerEnabled)(), missionRailCards: missions && (0, feature_flags_1.isMissionRailCardsEnabled)() },
+    // App preview targets come from mission processes, so it inherits the
+    // mission grant and additionally needs Desktop's browser capture.
+    return { protocolVersion: exports.MOBILE_PROTOCOL_VERSION, features: { missions, missionControl: missions, missionQueue: missions, missionProcesses: missions, repositories: true, codeExplorer: (0, feature_flags_1.isCodeExplorerEnabled)(), missionRailCards: missions && (0, feature_flags_1.isMissionRailCardsEnabled)(), appPreview: missions && opts.appPreview === true },
         ...(!missions ? { missionsUnavailableReason: process.env.SPECRAILS_AGENT_CHAT === 'false' ? 'Missions are disabled on Desktop.' : exports.MISSION_ACCESS_REASON } : {}) };
 }
 function conversationView(value) {
@@ -72,7 +74,7 @@ function missionSnapshot(value) {
         pendingMessages, pendingTruncated: pending.length > 50,
         live: { ...pick(live, ['isStreaming', 'startedAt']), streamingText, textTruncated: streamingText.length < liveRaw.length } };
 }
-function createMobileMissionsRouter({ db, upstream }) {
+function createMobileMissionsRouter({ db, upstream, appPreview }) {
     const router = (0, express_1.Router)();
     const segment = (value) => typeof value === 'string' ? value : '';
     const send = async (res, method, path, body, shape) => {
@@ -84,7 +86,7 @@ function createMobileMissionsRouter({ db, upstream }) {
             res.status(502).json({ error: 'Desktop is unreachable. Retry when connected.' });
         }
     };
-    router.get('/capabilities', (req, res) => res.json(mobileCapabilities(db, req.mobileDevice.id)));
+    router.get('/capabilities', (req, res) => res.json(mobileCapabilities(db, req.mobileDevice.id, { appPreview: appPreview?.() ?? false })));
     router.get('/mission-models', (req, res) => {
         const provider = segment(req.query.provider);
         if (!/^[a-z0-9_-]{1,40}$/.test(provider)) {

package/server/dist/mobile/mobile-preview-channel.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PreviewInboundLimiter = exports.PreviewChannelClient = exports.PREVIEW_INBOUND_MAX_BYTES = exports.PREVIEW_INBOUND_MAX_PER_MINUTE = exports.PREVIEW_MAX_MESSAGE_BYTES = exports.PREVIEW_CHUNK_HEADER_BYTES = exports.PREVIEW_CHANNEL_PREFIX = void 0;
+exports.encodeFrameChunks = encodeFrameChunks;
+exports.parsePreviewInbound = parsePreviewInbound;
+// Companion app preview: one WebRTC DataChannel per browser session, labelled
+// `preview:<sessionId>`, opened by Desktop on the device's EXISTING peer (a new
+// channel on an established SCTP association needs no SDP renegotiation). It is
+// separate from the `mobile` RPC channel so JPEG frames never queue ahead of RPC.
+//
+// Wire format (Desktop → Companion):
+//   - text:   JSON control (`ready`, `nav`, `popup`, `closed`) — always small.
+//   - binary: screencast frame fragments, each `u32 frameSeq | u16 index |
+//             u16 count` (big-endian) + payload. A frame renders only once all
+//             of its fragments arrived; a newer `frameSeq` discards an older
+//             incomplete one.
+// Wire format (Companion → Desktop): JSON text `{type:'input', event}` and
+// `{type:'navigate', action, url?}`.
+exports.PREVIEW_CHANNEL_PREFIX = 'preview:';
+exports.PREVIEW_CHUNK_HEADER_BYTES = 8;
+/** Same per-message budget the `mobile` channel's text chunking proved safe
+ *  across werift, libwebrtc (native companion) and browsers (web companion). */
+exports.PREVIEW_MAX_MESSAGE_BYTES = 16000;
+const MAX_CHUNKS = 0xffff;
+const WS_OPEN = 1;
+const WS_CLOSED = 3;
+/** Mirrors the PTY-tuned cap of `/ws/browser/:id` (BUG-MOBILE-07). */
+exports.PREVIEW_INBOUND_MAX_PER_MINUTE = 6000;
+exports.PREVIEW_INBOUND_MAX_BYTES = 64 * 1024;
+/** Split one JPEG frame into header-prefixed binary fragments. */
+function encodeFrameChunks(frameSeq, frame, maxMessageBytes = exports.PREVIEW_MAX_MESSAGE_BYTES) {
+    const payload = maxMessageBytes - exports.PREVIEW_CHUNK_HEADER_BYTES;
+    if (payload <= 0)
+        throw new RangeError('maxMessageBytes too small');
+    const count = Math.max(1, Math.ceil(frame.length / payload));
+    if (count > MAX_CHUNKS)
+        throw new RangeError('frame too large');
+    const seq = frameSeq >>> 0;
+    const chunks = [];
+    for (let index = 0; index < count; index++) {
+        const part = frame.subarray(index * payload, (index + 1) * payload);
+        const chunk = Buffer.allocUnsafe(exports.PREVIEW_CHUNK_HEADER_BYTES + part.length);
+        chunk.writeUInt32BE(seq, 0);
+        chunk.writeUInt16BE(index, 4);
+        chunk.writeUInt16BE(count, 6);
+        part.copy(chunk, exports.PREVIEW_CHUNK_HEADER_BYTES);
+        chunks.push(chunk);
+    }
+    return chunks;
+}
+/**
+ * Presents a preview DataChannel to `BrowserCaptureManager` as a
+ * `BrowserWsClient`, so attach/detach, popup state and the newest-wins
+ * screencast fan-out (which checks `bufferedAmount` BEFORE handing over a
+ * frame) are reused unchanged. A frame is always sent whole: conflation runs
+ * per frame, never per fragment, so a partial frame never goes out.
+ */
+class PreviewChannelClient {
+    channel;
+    frameSeq = 0;
+    constructor(channel) {
+        this.channel = channel;
+    }
+    get readyState() {
+        return this.channel.readyState === 'open' ? WS_OPEN : WS_CLOSED;
+    }
+    get bufferedAmount() {
+        return this.channel.bufferedAmount;
+    }
+    send(data) {
+        if (typeof data === 'string') {
+            this.channel.send(data);
+            return;
+        }
+        const seq = this.frameSeq;
+        this.frameSeq = (this.frameSeq + 1) >>> 0;
+        for (const chunk of encodeFrameChunks(seq, data))
+            this.channel.send(chunk);
+    }
+    close(_code, reason) {
+        try {
+            if (this.channel.readyState === 'open')
+                this.channel.send(JSON.stringify({ type: 'closed', reason: reason ?? 'session_closed' }));
+        }
+        catch { /* the channel is already going away */ }
+        try {
+            this.channel.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+exports.PreviewChannelClient = PreviewChannelClient;
+const finite = (value) => typeof value === 'number' && Number.isFinite(value);
+const modifiers = (value) => Number.isInteger(value) && value >= 0 && value <= 15 ? value : undefined;
+const BUTTONS = new Set(['left', 'middle', 'right']);
+function parseEvent(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const e = raw;
+    switch (e.type) {
+        case 'mouse': {
+            if (!['move', 'down', 'up'].includes(e.action) || !finite(e.x) || !finite(e.y) || e.x < 0 || e.y < 0)
+                return null;
+            const button = typeof e.button === 'string' && BUTTONS.has(e.button) ? e.button : undefined;
+            const clickCount = Number.isInteger(e.clickCount) && e.clickCount >= 1 && e.clickCount <= 3 ? e.clickCount : undefined;
+            return { type: 'mouse', action: e.action, x: e.x, y: e.y, ...(button ? { button } : {}), ...(clickCount ? { clickCount } : {}), ...(modifiers(e.modifiers) !== undefined ? { modifiers: modifiers(e.modifiers) } : {}) };
+        }
+        case 'wheel': {
+            if (!finite(e.x) || !finite(e.y) || !finite(e.deltaX) || !finite(e.deltaY) || e.x < 0 || e.y < 0)
+                return null;
+            const clamp = (v) => Math.max(-10_000, Math.min(10_000, v));
+            return { type: 'wheel', x: e.x, y: e.y, deltaX: clamp(e.deltaX), deltaY: clamp(e.deltaY), ...(modifiers(e.modifiers) !== undefined ? { modifiers: modifiers(e.modifiers) } : {}) };
+        }
+        case 'key': {
+            if (!['down', 'up'].includes(e.action) || typeof e.key !== 'string' || e.key.length === 0 || e.key.length > 32)
+                return null;
+            const code = typeof e.code === 'string' && e.code.length <= 32 ? e.code : undefined;
+            const text = typeof e.text === 'string' && e.text.length <= 8 ? e.text : undefined;
+            return { type: 'key', action: e.action, key: e.key, ...(code ? { code } : {}), ...(text !== undefined ? { text } : {}), ...(modifiers(e.modifiers) !== undefined ? { modifiers: modifiers(e.modifiers) } : {}) };
+        }
+        case 'resize': {
+            if (!finite(e.width) || !finite(e.height) || e.width <= 0 || e.height <= 0)
+                return null;
+            return { type: 'resize', width: e.width, height: e.height, ...(finite(e.deviceScaleFactor) ? { deviceScaleFactor: e.deviceScaleFactor } : {}) };
+        }
+        default:
+            return null;
+    }
+}
+/** Validate one inbound control message; anything malformed is dropped. */
+function parsePreviewInbound(text) {
+    if (text.length > exports.PREVIEW_INBOUND_MAX_BYTES)
+        return null;
+    let msg;
+    try {
+        msg = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!msg || typeof msg !== 'object')
+        return null;
+    if (msg.type === 'input') {
+        const event = parseEvent(msg.event);
+        return event ? { type: 'input', event } : null;
+    }
+    if (msg.type === 'navigate') {
+        const action = msg.action ?? 'goto';
+        if (!['goto', 'back', 'forward', 'reload'].includes(action))
+            return null;
+        if (action === 'goto' && (typeof msg.url !== 'string' || msg.url.length > 2048))
+            return null;
+        return { type: 'navigate', action: action, ...(action === 'goto' ? { url: msg.url } : {}) };
+    }
+    return null;
+}
+/** Sliding one-minute message budget for one channel. */
+class PreviewInboundLimiter {
+    now;
+    maxPerMinute;
+    windowStart = 0;
+    count = 0;
+    constructor(now = Date.now, maxPerMinute = exports.PREVIEW_INBOUND_MAX_PER_MINUTE) {
+        this.now = now;
+        this.maxPerMinute = maxPerMinute;
+    }
+    take() {
+        const at = this.now();
+        if (at - this.windowStart >= 60_000) {
+            this.windowStart = at;
+            this.count = 0;
+        }
+        if (this.count >= this.maxPerMinute)
+            return false;
+        this.count += 1;
+        return true;
+    }
+}
+exports.PreviewInboundLimiter = PreviewInboundLimiter;