specrails-desktop 2.63.2 → 2.64.0

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

@@ -0,0 +1,366 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MobilePreviewService = exports.PreviewError = void 0;
+exports.createMobilePreviewRouter = createMobilePreviewRouter;
+const express_1 = require("express");
+const browser_capture_types_1 = require("../modules/browser/runtime/browser-capture-types");
+const preview_origins_1 = require("../modules/browser/domain/preview-origins");
+const agent_store_1 = require("../modules/agents/runtime/agent-store");
+const mobile_missions_1 = require("./mobile-missions");
+const mobile_preview_channel_1 = require("./mobile-preview-channel");
+class PreviewError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'PreviewError';
+    }
+}
+exports.PreviewError = PreviewError;
+/**
+ * Companion app-preview use cases. Owns only the channel bindings; sessions,
+ * budgets and the origin policy live in BrowserCaptureManager, targets in the
+ * process-log source. A binding is replaced on re-attach (new peer after a
+ * Wi-Fi drop) and detached — never killed — when its channel closes, so the
+ * idle sweep reclaims abandoned previews.
+ */
+class MobilePreviewService {
+    deps;
+    bindings = new Map();
+    now;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+    }
+    available() {
+        return this.deps.enabled();
+    }
+    /** Targets of a mission's running processes. */
+    targetsForMission(projectId, chatId) {
+        if (!this.available())
+            return [];
+        return this.deps.targets.list(projectId).filter((target) => target.chatId === chatId);
+    }
+    async open(device, projectId, input) {
+        const browser = this.requireBrowser(projectId);
+        const target = this.deps.targets.forProcess(projectId, input.processId);
+        if (!target || target.chatId !== input.chatId)
+            throw new PreviewError(404, 'preview_target_gone', 'This process is no longer running or announced no URL.');
+        const origin = (0, preview_origins_1.previewOrigin)(input.url);
+        if (!origin || !target.urls.some((url) => (0, preview_origins_1.previewOrigin)(url) === origin)) {
+            throw new PreviewError(400, 'preview_url_not_announced', 'Only URLs announced by this process can be previewed.');
+        }
+        let meta;
+        try {
+            meta = await browser.create({ initialUrl: input.url, owner: { kind: 'device', deviceId: device.id, deviceName: device.name }, viewport: input.viewport });
+        }
+        catch (err) {
+            throw translateBrowserError(err);
+        }
+        try {
+            const opened = { sessionId: meta.id, channel: this.bind(projectId, device.id, browser, meta.id), url: input.url };
+            this.changed();
+            return opened;
+        }
+        catch (err) {
+            await browser.kill(meta.id);
+            throw err;
+        }
+    }
+    /** Re-attach a live session after the peer reconnected. */
+    attach(device, projectId, sessionId) {
+        const browser = this.requireBrowser(projectId);
+        this.requireOwner(browser, device.id, sessionId);
+        return { sessionId, channel: this.bind(projectId, device.id, browser, sessionId) };
+    }
+    async navigate(device, projectId, sessionId, action, url) {
+        const browser = this.requireBrowser(projectId);
+        this.requireOwner(browser, device.id, sessionId);
+        try {
+            const result = await browser.navigateAsDevice(sessionId, device.id, action, url);
+            if (!result)
+                throw new PreviewError(404, 'preview_session_closed', 'This preview session has ended.');
+            return { url: result.url, title: result.title };
+        }
+        catch (err) {
+            throw translateBrowserError(err);
+        }
+    }
+    async close(device, projectId, sessionId) {
+        const browser = this.requireBrowser(projectId);
+        this.requireOwner(browser, device.id, sessionId);
+        this.unbind(sessionId);
+        await browser.kill(sessionId);
+        this.changed();
+    }
+    /** Live device-owned sessions across projects (Desktop indicator). */
+    listDeviceSessions() {
+        if (!this.available())
+            return [];
+        const sessions = [];
+        for (const browser of this.deps.allBrowsers()) {
+            for (const meta of browser.listSessions()) {
+                if (meta.owner.kind !== 'device')
+                    continue;
+                sessions.push({ projectId: meta.projectId, sessionId: meta.id, deviceId: meta.owner.deviceId, deviceName: meta.owner.deviceName,
+                    url: meta.url, title: meta.title, createdAt: meta.createdAt });
+            }
+        }
+        return sessions.sort((a, b) => b.createdAt - a.createdAt);
+    }
+    /** The Desktop user ends a phone's preview; the viewer shows "session closed". */
+    async endFromDesktop(projectId, sessionId) {
+        const browser = this.deps.browserFor(projectId);
+        if (!browser || browser.sessionOwner(sessionId)?.kind !== 'device')
+            return false;
+        // Kill first so the attached channel client receives `closed` before the
+        // binding is dropped.
+        const killed = await browser.kill(sessionId);
+        this.unbind(sessionId);
+        if (killed)
+            this.changed();
+        return killed;
+    }
+    /** Device revoked/unpaired: end every preview it owns, in every project. */
+    async closeForDevice(deviceId) {
+        for (const [sessionId, binding] of [...this.bindings])
+            if (binding.deviceId === deviceId)
+                this.unbind(sessionId);
+        for (const browser of this.deps.allBrowsers()) {
+            try {
+                await browser.killDeviceSessions(deviceId);
+            }
+            catch { /* best-effort per project */ }
+        }
+        this.changed();
+    }
+    changed() {
+        try {
+            this.deps.onChange?.();
+        }
+        catch { /* a notification failure never fails the use case */ }
+    }
+    requireBrowser(projectId) {
+        if (!this.available())
+            throw new PreviewError(404, 'preview_unavailable', 'App preview requires browser capture to be enabled on Desktop.');
+        const browser = this.deps.browserFor(projectId);
+        if (!browser)
+            throw new PreviewError(404, 'unknown_project', 'Unknown project');
+        return browser;
+    }
+    requireOwner(browser, deviceId, sessionId) {
+        const owner = browser.sessionOwner(sessionId);
+        // A session of another device or of Desktop is indistinguishable from a
+        // missing one: never confirm its existence to this device.
+        if (!owner || owner.kind !== 'device' || owner.deviceId !== deviceId) {
+            throw new PreviewError(404, 'preview_session_closed', 'This preview session has ended.');
+        }
+    }
+    bind(projectId, deviceId, browser, sessionId) {
+        const label = `${mobile_preview_channel_1.PREVIEW_CHANNEL_PREFIX}${sessionId}`;
+        const channel = this.deps.openChannel(deviceId, label);
+        if (!channel)
+            throw new PreviewError(409, 'preview_requires_webrtc', 'Reconnect Companion to Desktop to preview apps.');
+        this.unbind(sessionId);
+        const client = new mobile_preview_channel_1.PreviewChannelClient(channel);
+        const binding = { projectId, deviceId, channel, client };
+        this.bindings.set(sessionId, binding);
+        const limiter = new mobile_preview_channel_1.PreviewInboundLimiter(this.now);
+        const current = () => this.bindings.get(sessionId) === binding;
+        channel.onOpen(() => {
+            if (!current())
+                return;
+            void browser.attach(sessionId, client).then((meta) => {
+                if (!meta)
+                    client.close(1000, 'session_closed');
+            });
+        });
+        channel.onMessage((data) => {
+            if (!current() || !limiter.take())
+                return;
+            const msg = (0, mobile_preview_channel_1.parsePreviewInbound)(typeof data === 'string' ? data : data.toString('utf8'));
+            if (!msg)
+                return;
+            if (msg.type === 'input') {
+                void browser.handleInput(sessionId, msg.event).catch(() => { });
+            }
+            else {
+                void browser.navigateAsDevice(sessionId, deviceId, msg.action, msg.url).catch(() => {
+                    // A rejected or failed navigation keeps the current page; tell the
+                    // viewer so it can restore its address field.
+                    try {
+                        channel.send(JSON.stringify({ type: 'nav_rejected' }));
+                    }
+                    catch { /* ignore */ }
+                });
+            }
+        });
+        channel.onClose(() => {
+            browser.detach(sessionId, client);
+            if (current())
+                this.bindings.delete(sessionId);
+        });
+        return label;
+    }
+    unbind(sessionId) {
+        const binding = this.bindings.get(sessionId);
+        if (!binding)
+            return;
+        this.bindings.delete(sessionId);
+        try {
+            binding.channel.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+exports.MobilePreviewService = MobilePreviewService;
+function translateBrowserError(err) {
+    if (err instanceof PreviewError)
+        return err;
+    if (err instanceof browser_capture_types_1.BrowserNavigationRejectedError)
+        return new PreviewError(400, 'preview_url_not_announced', 'Only URLs announced by this project can be opened in a preview.');
+    if (err instanceof browser_capture_types_1.BrowserLimitExceededError)
+        return new PreviewError(429, 'preview_limit', `Up to ${err.limit} phones can preview this project at once. Close another preview and retry.`);
+    return new PreviewError(502, 'preview_failed', 'Desktop could not open the preview. Retry in a moment.');
+}
+const ID = /^[A-Za-z0-9_-]{1,160}$/;
+const ACTIONS = new Set(['goto', 'back', 'forward', 'reload']);
+function viewportFrom(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const v = raw;
+    const ok = (n) => typeof n === 'number' && Number.isFinite(n) && n > 0;
+    if (!ok(v.width) || !ok(v.height))
+        return undefined;
+    return { width: v.width, height: v.height, ...(ok(v.deviceScaleFactor) ? { deviceScaleFactor: v.deviceScaleFactor } : {}) };
+}
+/**
+ * Gateway routes. Preview targets come from mission processes, so they follow
+ * the mission rule: an all-projects device grant (`mobile-mission-control`).
+ */
+function createMobilePreviewRouter({ db, preview }) {
+    const router = (0, express_1.Router)();
+    const segment = (value) => typeof value === 'string' ? value : '';
+    const device = (req) => {
+        const row = req.mobileDevice;
+        return { id: row.id, name: row.name };
+    };
+    const fail = (res, err) => {
+        if (err instanceof PreviewError) {
+            res.status(err.status).json({ error: err.message, code: err.code });
+            return;
+        }
+        res.status(500).json({ error: 'Preview failed', code: 'preview_failed' });
+    };
+    const gate = (req, res) => {
+        const pid = segment(req.params.pid);
+        if (!ID.test(pid)) {
+            res.status(400).json({ error: 'Invalid parameter' });
+            return null;
+        }
+        if (!(0, mobile_missions_1.mobileCapabilities)(db, device(req).id).features.missions) {
+            res.status(403).json({ error: mobile_missions_1.MISSION_ACCESS_REASON });
+            return null;
+        }
+        if (!preview.available()) {
+            res.status(404).json({ error: 'App preview is unavailable on Desktop.', code: 'preview_unavailable' });
+            return null;
+        }
+        return pid;
+    };
+    const mission = (res, pid, cid) => {
+        if (!ID.test(cid)) {
+            res.status(400).json({ error: 'Invalid mission identity' });
+            return false;
+        }
+        const conversation = (0, agent_store_1.getAgentConversation)(db, cid);
+        if (!conversation || conversation.pinned_project_id !== pid) {
+            res.status(404).json({ error: 'Mission not found in this project' });
+            return false;
+        }
+        return true;
+    };
+    router.get('/projects/:pid/missions/:cid/preview-targets', (req, res) => {
+        const pid = gate(req, res);
+        if (!pid)
+            return;
+        const cid = segment(req.params.cid);
+        if (!mission(res, pid, cid))
+            return;
+        res.json({ targets: preview.targetsForMission(pid, cid).map(({ processId, urls }) => ({ processId, urls })) });
+    });
+    router.post('/projects/:pid/preview-sessions', async (req, res) => {
+        const pid = gate(req, res);
+        if (!pid)
+            return;
+        const body = (req.body ?? {});
+        const cid = segment(body.missionId), processId = segment(body.processId), url = segment(body.url);
+        if (!mission(res, pid, cid))
+            return;
+        if (!ID.test(processId) || !url || url.length > 2048) {
+            res.status(400).json({ error: 'processId and url are required' });
+            return;
+        }
+        try {
+            res.status(201).json(await preview.open(device(req), pid, { chatId: cid, processId, url, viewport: viewportFrom(body.viewport) }));
+        }
+        catch (err) {
+            fail(res, err);
+        }
+    });
+    router.post('/projects/:pid/preview-sessions/:sid/attach', (req, res) => {
+        const pid = gate(req, res);
+        if (!pid)
+            return;
+        const sid = segment(req.params.sid);
+        if (!ID.test(sid)) {
+            res.status(400).json({ error: 'Invalid parameter' });
+            return;
+        }
+        try {
+            res.json(preview.attach(device(req), pid, sid));
+        }
+        catch (err) {
+            fail(res, err);
+        }
+    });
+    router.post('/projects/:pid/preview-sessions/:sid/navigate', async (req, res) => {
+        const pid = gate(req, res);
+        if (!pid)
+            return;
+        const sid = segment(req.params.sid);
+        const body = (req.body ?? {});
+        const action = segment(body.action) || 'goto';
+        const url = typeof body.url === 'string' ? body.url : undefined;
+        if (!ID.test(sid) || !ACTIONS.has(action) || (action === 'goto' && (!url || url.length > 2048))) {
+            res.status(400).json({ error: 'Invalid navigation' });
+            return;
+        }
+        try {
+            res.json(await preview.navigate(device(req), pid, sid, action, url));
+        }
+        catch (err) {
+            fail(res, err);
+        }
+    });
+    router.delete('/projects/:pid/preview-sessions/:sid', async (req, res) => {
+        const pid = gate(req, res);
+        if (!pid)
+            return;
+        const sid = segment(req.params.sid);
+        if (!ID.test(sid)) {
+            res.status(400).json({ error: 'Invalid parameter' });
+            return;
+        }
+        try {
+            await preview.close(device(req), pid, sid);
+            res.json({ ok: true });
+        }
+        catch (err) {
+            fail(res, err);
+        }
+    });
+    return router;
+}

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

@@ -9,6 +9,7 @@ const mobile_auth_1 = require("./mobile-auth");
 const mobile_devices_1 = require("./mobile-devices");
 const mobile_missions_1 = require("./mobile-missions");
 const mobile_code_1 = require("./mobile-code");
+const mobile_preview_1 = require("./mobile-preview");
 // The gateway's authenticated REST surface: the `/v1/*` allow-list. Each route
 // forwards, in-process, via a REAL loopback HTTP request to
 // http://127.0.0.1:<desktopPort> with the master token injected server-side as
@@ -455,7 +456,9 @@ function createMobileRouter(deps) {
             ...(body !== undefined ? { body: JSON.stringify(body) } : {}) });
         return { status: response.status, json: await response.json() };
     };
-    v1.use((0, mobile_missions_1.createMobileMissionsRouter)({ db: deps.db, upstream: mobileUpstream }));
+    v1.use((0, mobile_missions_1.createMobileMissionsRouter)({ db: deps.db, upstream: mobileUpstream, appPreview: () => deps.preview?.available() ?? false }));
+    if (deps.preview)
+        v1.use((0, mobile_preview_1.createMobilePreviewRouter)({ db: deps.db, preview: deps.preview }));
     v1.use((0, mobile_code_1.createMobileCodeRouter)(mobileUpstream));
     router.use('/v1', v1);
     // Any unmatched gateway path → 404 JSON (NEVER falls through to a SPA handler;
@@ -472,6 +475,11 @@ exports.MOBILE_ALLOWLIST = [
     { method: 'GET', path: '/v1/projects/:pid/repositories/:rid/code/find' },
     { method: 'GET', path: '/v1/projects/:pid/repositories/:rid/code/file' },
     { method: 'GET', path: '/v1/capabilities' },
+    { method: 'GET', path: '/v1/projects/:pid/missions/:cid/preview-targets' },
+    { method: 'POST', path: '/v1/projects/:pid/preview-sessions' },
+    { method: 'POST', path: '/v1/projects/:pid/preview-sessions/:sid/attach' },
+    { method: 'POST', path: '/v1/projects/:pid/preview-sessions/:sid/navigate' },
+    { method: 'DELETE', path: '/v1/projects/:pid/preview-sessions/:sid' },
     { method: 'GET', path: '/v1/mission-models' },
     { method: 'PATCH', path: '/v1/projects/:pid/missions/:cid/messages/:mid/intent' },
     { method: 'GET', path: '/v1/projects/:pid/repositories' },

package/server/dist/mobile/mobile-webrtc-peer.js

@@ -14,6 +14,9 @@ class MobileWebrtcGateway {
     // answer to whatever happened to be pending. Per-room keying isolates them.
     _pending = new Map();
     _active = new Set();
+    /** The live peer of each authenticated device (latest wins), so Desktop can
+     *  open extra DataChannels (app preview) on the connection it already has. */
+    _byDevice = new Map();
     constructor(_deps) {
         this._deps = _deps;
     }
@@ -48,17 +51,23 @@ class MobileWebrtcGateway {
         //    require a valid existing device token instead, and never mint.
         new mobile_datachannel_1.DataChannelPeer(toChannelLike(dc), {
             registerDevice: async (input) => {
+                let result;
                 if (isReconnect) {
-                    return this._deps.registerDevice({
+                    result = await this._deps.registerDevice({
                         deviceName: input.deviceName,
                         platform: input.platform,
                         token: input.token,
                         requireExistingToken: true,
                     });
                 }
-                return input.secret && (0, auth_1.safeEqual)(input.secret, secret)
-                    ? this._deps.registerDevice({ deviceName: input.deviceName, platform: input.platform, token: input.token })
-                    : { ok: false };
+                else {
+                    result = input.secret && (0, auth_1.safeEqual)(input.secret, secret)
+                        ? await this._deps.registerDevice({ deviceName: input.deviceName, platform: input.platform, token: input.token })
+                        : { ok: false };
+                }
+                if (result.ok)
+                    this._byDevice.set(result.deviceId, pc);
+                return result;
             },
             rpcDispatch: this._deps.rpcDispatch,
             bridge: this._deps.bridge,
@@ -67,6 +76,9 @@ class MobileWebrtcGateway {
             console.log('[webrtc] pc connectionState:', s);
             if (s === 'failed' || s === 'closed' || s === 'disconnected') {
                 this._active.delete(pc);
+                for (const [deviceId, owned] of this._byDevice)
+                    if (owned === pc)
+                        this._byDevice.delete(deviceId);
                 // Drop this pc from whichever room slot still holds it.
                 if (this._pending.get(key)?.pc === pc)
                     this._pending.delete(key);
@@ -101,6 +113,24 @@ class MobileWebrtcGateway {
             return { ok: false };
         }
     }
+    /** Open an ordered, reliable DataChannel on the device's live peer (no SDP
+     *  renegotiation: the SCTP association already exists). Null when the
+     *  device has no connected WebRTC peer. */
+    openChannel(deviceId, label) {
+        const pc = this._byDevice.get(deviceId);
+        if (!pc || pc.connectionState !== 'connected')
+            return null;
+        try {
+            return toPreviewChannel(pc.createDataChannel(label, { ordered: true }));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Forget a device's peer (revoked). Its channels close with the peer. */
+    forgetDevice(deviceId) {
+        this._byDevice.delete(deviceId);
+    }
     /** Tear down every peer (gateway stopping / disabled). */
     stop() {
         for (const key of [...this._pending.keys()])
@@ -108,6 +138,7 @@ class MobileWebrtcGateway {
         for (const pc of this._active)
             this._close(pc);
         this._active.clear();
+        this._byDevice.clear();
     }
     _close(pc) {
         try {
@@ -137,6 +168,25 @@ function toChannelLike(dc) {
         },
     };
 }
+function toPreviewChannel(dc) {
+    return {
+        get label() { return dc.label; },
+        get readyState() { return dc.readyState; },
+        get bufferedAmount() { return dc.bufferedAmount; },
+        send: (data) => dc.send(data),
+        close: () => dc.close(),
+        onOpen: (cb) => {
+            if (dc.readyState === 'open')
+                queueMicrotask(cb);
+            else
+                dc.stateChanged.subscribe((s) => { if (s === 'open')
+                    cb(); });
+        },
+        onMessage: (cb) => { dc.onMessage.subscribe((d) => cb(d)); },
+        onClose: (cb) => { dc.stateChanged.subscribe((s) => { if (s === 'closed')
+            cb(); }); },
+    };
+}
 /** Vanilla ICE: resolve once gathering completes so the offer SDP carries all
  *  candidates (there's no trickle channel — the SDP travels by QR). */
 function waitIceComplete(pc) {

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

@@ -33,7 +33,8 @@ function topicFor(type) {
         case 'agent_pr_decision':
         case 'background_process.started':
         case 'background_process.updated':
-        case 'background_process.exited': return 'missions';
+        case 'background_process.exited':
+        case 'background_process.preview_targets': return 'missions';
         case 'queue': return 'queue';
         case 'phase': return 'phase';
         case 'ticket_created':
@@ -253,7 +254,8 @@ class MobileWsBridge {
                     continue;
                 const value = msg;
                 const process = value.process;
-                const cid = typeof value.conversationId === 'string' ? value.conversationId : process?.chatId;
+                const cid = typeof value.conversationId === 'string' ? value.conversationId
+                    : typeof value.chatId === 'string' ? value.chatId : process?.chatId;
                 const projectId = cid ? this._missionProjectFor(cid) : null;
                 if (!projectId || !s.projects.has(projectId))
                     continue;

package/server/dist/modules/browser/domain/preview-origins.js

@@ -0,0 +1,117 @@
+"use strict";
+// Pure rules for the Companion app preview: which local URLs a background
+// process announces, how loopback origins are normalised, and which
+// navigations a device-owned preview session may perform. No I/O here — the
+// runtime feeds log lines and the announced-origin set in.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLoopbackHost = isLoopbackHost;
+exports.previewOrigin = previewOrigin;
+exports.extractPreviewUrls = extractPreviewUrls;
+exports.previewTargetsFromLines = previewTargetsFromLines;
+exports.isPreviewRequestAllowed = isPreviewRequestAllowed;
+exports.isManualPreviewUrlAllowed = isManualPreviewUrlAllowed;
+const ANSI = /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b[@-Z\\-_]/g;
+// Host alternatives a dev server prints for "this machine". Bracketed IPv6
+// forms are matched literally; the wildcard binds are rewritten to localhost.
+const LOCAL_URL = /\bhttps?:\/\/(?:localhost|127(?:\.\d{1,3}){3}|0\.0\.0\.0|\[::1?\])(?::\d{1,5})?(?:\/[^\s'"<>)\]`]*)?/gi;
+const TRAILING_PUNCTUATION = /[.,;:!?]+$/;
+/** A loopback host as dev servers print it (wildcard binds included). */
+function isLoopbackHost(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[/, '').replace(/\]$/, '');
+    return host === 'localhost' || host.endsWith('.localhost') || host === '::1' || host === '::' ||
+        host === '0.0.0.0' || /^127(?:\.\d{1,3}){3}$/.test(host);
+}
+/**
+ * The comparable origin of `raw`, with every loopback spelling collapsed to
+ * `localhost` (so `http://127.0.0.1:5173` and `http://[::1]:5173` match an
+ * announced `http://localhost:5173`). Null for unparsable or non-http(s) URLs.
+ */
+function previewOrigin(raw) {
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return null;
+    const host = isLoopbackHost(url.hostname) ? 'localhost' : url.hostname.toLowerCase();
+    const port = url.port || (url.protocol === 'https:' ? '443' : '80');
+    return `${url.protocol}//${host}:${port}`;
+}
+/** Normalise an announced URL: loopback host → `localhost`, explicit path kept. */
+function normalizeAnnouncedUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw.replace(TRAILING_PUNCTUATION, ''));
+    }
+    catch {
+        return null;
+    }
+    if (!isLoopbackHost(url.hostname))
+        return null;
+    const port = url.port ? Number(url.port) : NaN;
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return null;
+    url.hostname = 'localhost';
+    url.hash = '';
+    return url.toString();
+}
+/**
+ * Local URLs a log line announces (`➜  Local:   http://localhost:5173/`,
+ * `ready on http://0.0.0.0:3000`), normalised and de-duplicated by origin in
+ * order of appearance. URLs without an explicit port are ignored: a dev server
+ * always prints one, while bare `http://localhost` mentions are usually docs.
+ */
+function extractPreviewUrls(line) {
+    const text = line.replace(ANSI, '');
+    const found = [];
+    const origins = new Set();
+    for (const match of text.matchAll(LOCAL_URL)) {
+        const url = normalizeAnnouncedUrl(match[0]);
+        const origin = url && previewOrigin(url);
+        if (!url || !origin || origins.has(origin))
+            continue;
+        origins.add(origin);
+        found.push(url);
+    }
+    return found;
+}
+/**
+ * Latest-first, origin-unique targets from a process's log lines (oldest first).
+ * A re-announced origin moves to the front with its newest URL.
+ */
+function previewTargetsFromLines(lines) {
+    const byOrigin = new Map();
+    for (const line of lines) {
+        for (const url of extractPreviewUrls(line)) {
+            const origin = previewOrigin(url);
+            byOrigin.delete(origin);
+            byOrigin.set(origin, url);
+        }
+    }
+    return [...byOrigin.values()].reverse();
+}
+/**
+ * Whether a device-owned preview session may load `url` (a navigation or a
+ * subresource request). Announced origins of the project are allowed even
+ * though they are loopback; everything else must pass the regular server-side
+ * guard (`fallback`, i.e. `isNavigableUrl`), which rejects loopback/private
+ * hosts and non-http(s) schemes.
+ */
+function isPreviewRequestAllowed(url, announcedOrigins, fallback) {
+    const origin = previewOrigin(url);
+    if (origin && announcedOrigins.has(origin))
+        return true;
+    return fallback(url);
+}
+/**
+ * Whether a device may *type* `url` (create or manual navigate). Stricter than
+ * the request guard: only paths on announced origins, never an arbitrary
+ * public URL — Desktop must not become a general browser proxy for the phone.
+ */
+function isManualPreviewUrlAllowed(url, announcedOrigins) {
+    const origin = previewOrigin(url);
+    return origin !== null && announcedOrigins.has(origin);
+}