@mayurajs/browser-viewer 0.0.0-stage → 1.2.0

package/dist/viewer.js

@@ -0,0 +1,225 @@
+import { MayuraError } from 'mayura';
+import { viewerPage } from './page.js';
+import { browserScreencast } from './screencast.js';
+const boundary = 'mayura-frame';
+const encoder = new TextEncoder();
+const origin = /^https?:\/\/[a-z0-9.-]+(?::\d{1,5})?$/iu;
+function bound(value, name, fallback, min, max) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result < min || result > max)
+        throw new MayuraError('INVALID_CONFIG', `browserViewer(): ${name} is ${min.toLocaleString('en-US')} to ${max.toLocaleString('en-US')}.`);
+    return result;
+}
+function base64Url(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/u, '');
+}
+/** A request's body as text, read no further than `max` bytes; undefined when it is longer. */
+async function bodyText(request, max) {
+    if (!request.body)
+        return '';
+    const reader = request.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > max) {
+            await reader.cancel().catch(() => undefined);
+            return undefined;
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(bytes);
+}
+async function digest(token) {
+    const hash = new Uint8Array(await crypto.subtle.digest('SHA-256', encoder.encode(token)));
+    return [...hash].map(byte => byte.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * A live viewer for `mayura/browser` browsers, as web-standard request handling for any server: `share(browser)` gives
+ * a link with a secret token to a page showing the browser's active tab as it changes (an MJPEG stream of its
+ * screencast), and with `interact` a person can use the page too. Links expire, and end with the browser; nothing is
+ * shown that is not shared. For a server of its own on Node, see `serveBrowserViewer`.
+ */
+export function browserViewer(options = {}) {
+    const basePath = options.basePath ?? '/';
+    if (typeof basePath !== 'string' || !/^\/(?:[A-Za-z0-9._~-]+\/)*$/u.test(basePath))
+        throw new MayuraError('INVALID_CONFIG', 'browserViewer(): basePath is a path such as / or /viewer/, starting and ending with /.');
+    const frameAncestors = options.frameAncestors ?? [];
+    if (!Array.isArray(frameAncestors) || frameAncestors.length > 16 || frameAncestors.some(item => typeof item !== 'string' || !origin.test(item))) {
+        throw new MayuraError('INVALID_CONFIG', 'browserViewer(): frameAncestors are origins such as https://app.example.');
+    }
+    const maxViewers = bound(options.maxViewersPerShare, 'maxViewersPerShare', 2, 1, 16);
+    const maxShares = bound(options.maxShares, 'maxShares', 16, 1, 256);
+    const maxInput = bound(options.maxInputPerSecond, 'maxInputPerSecond', 60, 1, 500);
+    const { basePath: _basePath, frameAncestors: _frameAncestors, maxViewersPerShare: _viewers, maxShares: _shares, maxInputPerSecond: _input, ...castOptions } = options;
+    // Checked now, rather than when someone first watches.
+    if (castOptions.webSocket !== undefined && typeof castOptions.webSocket !== 'function')
+        throw new MayuraError('INVALID_CONFIG', 'browserViewer(): webSocket must be a function.');
+    bound(castOptions.quality, 'quality', 60, 1, 100);
+    bound(castOptions.maxWidth, 'maxWidth', 1_280, 320, 3_840);
+    bound(castOptions.maxHeight, 'maxHeight', 800, 240, 2_160);
+    bound(castOptions.maxFps, 'maxFps', 5, 1, 30);
+    bound(castOptions.maxFrameBytes, 'maxFrameBytes', 2_097_152, 65_536, 16_777_216);
+    const ancestors = frameAncestors.length ? frameAncestors.join(' ') : "'none'";
+    const shares = new Map(); // by the token's SHA-256
+    let closed = false;
+    const revoke = (key) => {
+        const share = shares.get(key);
+        if (!share)
+            return;
+        shares.delete(key);
+        share.revoked = true;
+        clearTimeout(share.timer);
+        for (const cast of share.casts)
+            cast.close();
+    };
+    /** The share a token names, while it is open and its browser has not ended. */
+    const find = (key) => {
+        const share = shares.get(key);
+        if (share?.browser.ended) {
+            revoke(key);
+            return undefined;
+        }
+        return share;
+    };
+    const headers = (extra = {}) => ({
+        'cache-control': 'no-store', 'referrer-policy': 'no-referrer', 'x-content-type-options': 'nosniff',
+        'content-security-policy': `default-src 'none'; frame-ancestors ${ancestors}; base-uri 'none'; form-action 'none'`, ...extra,
+    });
+    const text = (status, body) => new Response(body, { status, headers: headers({ 'content-type': 'text/plain; charset=utf-8' }) });
+    const stream = async (share) => {
+        if (share.casts.size >= maxViewers)
+            return text(429, 'Too many people are watching this browser.');
+        let cast;
+        try {
+            cast = await browserScreencast(share.browser, { ...castOptions, interact: share.interact });
+        }
+        catch {
+            return text(410, 'This browser cannot be shown.');
+        }
+        // Revoked while connecting.
+        if (share.revoked) {
+            cast.close();
+            return text(404, 'Not found.');
+        }
+        share.casts.add(cast);
+        const body = new ReadableStream({
+            pull: async (controller) => {
+                const frame = await cast.next();
+                if (!frame) {
+                    share.casts.delete(cast);
+                    controller.close();
+                    return;
+                }
+                controller.enqueue(encoder.encode(`--${boundary}\r\nContent-Type: image/jpeg\r\nContent-Length: ${frame.data.byteLength}\r\n\r\n`));
+                controller.enqueue(frame.data);
+                controller.enqueue(encoder.encode('\r\n'));
+            },
+            cancel: () => { share.casts.delete(cast); cast.close(); },
+        }, { highWaterMark: 0 });
+        return new Response(body, { status: 200, headers: headers({ 'content-type': `multipart/x-mixed-replace; boundary=${boundary}` }) });
+    };
+    const input = async (share, request) => {
+        if (!share.interact)
+            return text(403, 'This link is view only.');
+        // A JSON body cannot be sent across sites without a preflight, which is never allowed; nor from another site.
+        if (!/^application\/json(?:;|$)/iu.test(request.headers.get('content-type') ?? ''))
+            return text(415, 'Send JSON.');
+        const site = request.headers.get('sec-fetch-site');
+        if (site !== null && site !== 'same-origin')
+            return text(403, 'Not from this page.');
+        const now = Date.now();
+        share.inputs = share.inputs.filter(time => now - time < 1_000);
+        if (share.inputs.length >= maxInput)
+            return text(429, 'Too many inputs.');
+        share.inputs.push(now);
+        const raw = await bodyText(request, 4_096);
+        if (raw === undefined)
+            return text(413, 'Too large.');
+        let event;
+        try {
+            event = JSON.parse(raw);
+        }
+        catch {
+            return text(400, 'Send JSON.');
+        }
+        // Input goes to the page as the newest viewer shows it.
+        const cast = [...share.casts].at(-1);
+        if (!cast)
+            return text(409, 'Nothing is being watched.');
+        try {
+            await cast.input(event);
+        }
+        catch (error) {
+            return text(error instanceof MayuraError && error.code === 'INVALID_INPUT' ? 400 : 409, error instanceof MayuraError && error.code === 'INVALID_INPUT' ? error.message : 'The browser did not take that.');
+        }
+        return new Response(null, { status: 204, headers: headers() });
+    };
+    return {
+        share: async (browser, shareOptions = {}) => {
+            if (closed)
+                throw new MayuraError('INVALID_CONFIG', 'The viewer was closed.');
+            if (!browser || typeof browser.tabs !== 'function')
+                throw new MayuraError('INVALID_CONFIG', 'share() needs a browser.');
+            if (!browser.cdp)
+                throw new MayuraError('INVALID_CONFIG', `The ${browser.provider} provider's browsers cannot be joined: each connection starts a browser of its own.`);
+            if (browser.ended)
+                throw new MayuraError('INVALID_INPUT', 'The browser has ended.');
+            if (shareOptions.interact !== undefined && typeof shareOptions.interact !== 'boolean')
+                throw new MayuraError('INVALID_CONFIG', 'share(): interact must be a boolean.');
+            const expiresInMs = shareOptions.expiresInMs ?? 3_600_000;
+            if (!Number.isSafeInteger(expiresInMs) || expiresInMs < 1_000 || expiresInMs > 86_400_000)
+                throw new MayuraError('INVALID_CONFIG', 'share(): expiresInMs is 1 s to 24 hours.');
+            for (const key of [...shares.keys()])
+                find(key);
+            if (shares.size >= maxShares)
+                throw new MayuraError('LIMIT_EXCEEDED', 'Too many shares are open: revoke one first.');
+            const token = base64Url(crypto.getRandomValues(new Uint8Array(32)));
+            const key = await digest(token);
+            const expiresAt = Date.now() + expiresInMs;
+            const timer = setTimeout(() => revoke(key), expiresInMs);
+            // An open link does not keep the process running.
+            timer.unref?.();
+            shares.set(key, { browser, interact: shareOptions.interact === true, timer, casts: new Set(), inputs: [], revoked: false });
+            return Object.freeze({ path: `${basePath}v/${token}/`, interact: shareOptions.interact === true, expiresAt, revoke: () => revoke(key) });
+        },
+        handle: async (request) => {
+            const { pathname } = new URL(request.url);
+            if (!pathname.startsWith(`${basePath}v/`))
+                return undefined;
+            const match = /^([A-Za-z0-9_-]{43})\/(stream|input)?$/u.exec(pathname.slice(basePath.length + 2));
+            const share = match ? find(await digest(match[1])) : undefined;
+            if (!match || !share)
+                return text(404, 'Not found.');
+            const part = match[2];
+            if (part === 'input')
+                return request.method === 'POST' ? input(share, request) : text(405, 'Use POST.');
+            if (request.method !== 'GET')
+                return text(405, 'Use GET.');
+            if (part === 'stream')
+                return stream(share);
+            const nonce = base64Url(crypto.getRandomValues(new Uint8Array(16)));
+            return new Response(viewerPage({ interact: share.interact, nonce }), { status: 200, headers: headers({
+                    'content-type': 'text/html; charset=utf-8',
+                    'content-security-policy': `default-src 'none'; img-src 'self'; connect-src 'self'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; frame-ancestors ${ancestors}; base-uri 'none'; form-action 'none'`,
+                }) });
+        },
+        get size() { for (const key of [...shares.keys()])
+            find(key); return shares.size; },
+        close: () => { closed = true; for (const key of [...shares.keys()])
+            revoke(key); },
+    };
+}
+//# sourceMappingURL=viewer.js.map

package/dist/viewer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewer.js","sourceRoot":"","sources":["../src/viewer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAErC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAA6D,MAAM,iBAAiB,CAAC;AAmD/G,MAAM,QAAQ,GAAG,cAAc,CAAC;AAChC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAClC,MAAM,MAAM,GAAG,yCAAyC,CAAC;AAEzD,SAAS,KAAK,CAAC,KAAyB,EAAE,IAAY,EAAE,QAAgB,EAAE,GAAW,EAAE,GAAW;IAChG,MAAM,MAAM,GAAG,KAAK,IAAI,QAAQ,CAAC;IACjC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,GAAG,IAAI,MAAM,GAAG,GAAG;QAAE,MAAM,IAAI,WAAW,CAAC,gBAAgB,EAAE,oBAAoB,IAAI,OAAO,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC,OAAO,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC5M,OAAO,MAAM,CAAC;AAChB,CAAC;AACD,SAAS,SAAS,CAAC,KAAiB;IAClC,IAAI,MAAM,GAAG,EAAE,CAAC;IAAC,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAC/E,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACpF,CAAC;AACD,+FAA+F;AAC/F,KAAK,UAAU,QAAQ,CAAC,OAAgB,EAAE,GAAW;IACnD,IAAI,CAAC,OAAO,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAC7B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;IAAC,MAAM,MAAM,GAAiB,EAAE,CAAC;IAAC,IAAI,IAAI,GAAG,CAAC,CAAC;IACvF,SAAS,CAAC;QACR,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QAC5C,IAAI,IAAI;YAAE,MAAM;QAChB,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC;QACzB,IAAI,IAAI,GAAG,GAAG,EAAE,CAAC;YAAC,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAAC,OAAO,SAAS,CAAC;QAAC,CAAC;QACnF,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAAC,IAAI,MAAM,GAAG,CAAC,CAAC;IACnD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAAC,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC;IAAC,CAAC;IACrF,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AACD,KAAK,UAAU,MAAM,CAAC,KAAa;IACjC,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1F,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,OAAO,GAAyB,EAAE;IAC9D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,GAAG,CAAC;IACzC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,8BAA8B,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,MAAM,IAAI,WAAW,CAAC,gBAAgB,EAAE,wFAAwF,CAAC,CAAC;IACtN,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,EAAE,CAAC;IACpD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,cAAc,CAAC,MAAM,GAAG,EAAE,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAChJ,MAAM,IAAI,WAAW,CAAC,gBAAgB,EAAE,0EAA0E,CAAC,CAAC;IACtH,CAAC;IACD,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,kBAAkB,EAAE,oBAAoB,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IACrF,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;IACpE,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,iBAAiB,EAAE,mBAAmB,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;IACnF,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,cAAc,EAAE,eAAe,EAAE,kBAAkB,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,GAAG,WAAW,EAAE,GAAG,OAAO,CAAC;IACtK,uDAAuD;IACvD,IAAI,WAAW,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,WAAW,CAAC,SAAS,KAAK,UAAU;QAAE,MAAM,IAAI,WAAW,CAAC,gBAAgB,EAAE,gDAAgD,CAAC,CAAC;IAClL,KAAK,CAAC,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;IAAC,KAAK,CAAC,WAAW,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAAC,KAAK,CAAC,WAAW,CAAC,SAAS,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAC1K,KAAK,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,WAAW,CAAC,aAAa,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IAChI,MAAM,SAAS,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAE9E,MAAM,MAAM,GAAG,IAAI,GAAG,EAAiB,CAAC,CAAC,yBAAyB;IAClE,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,MAAM,MAAM,GAAG,CAAC,GAAW,EAAE,EAAE;QAC7B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;QAAC,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACpE,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK;YAAE,IAAI,CAAC,KAAK,EAAE,CAAC;IAC/C,CAAC,CAAC;IACF,+EAA+E;IAC/E,MAAM,IAAI,GAAG,CAAC,GAAW,EAAqB,EAAE;QAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAAC,OAAO,SAAS,CAAC;QAAC,CAAC;QAC5D,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,CAAC,KAAK,GAA2B,EAAE,EAA0B,EAAE,CAAC,CAAC;QAC/E,eAAe,EAAE,UAAU,EAAE,iBAAiB,EAAE,aAAa,EAAE,wBAAwB,EAAE,SAAS;QAClG,yBAAyB,EAAE,uCAAuC,SAAS,uCAAuC,EAAE,GAAG,KAAK;KAC7H,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,CAAC,MAAc,EAAE,IAAY,EAAE,EAAE,CAAC,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,EAAE,2BAA2B,EAAE,CAAC,EAAE,CAAC,CAAC;IAEjJ,MAAM,MAAM,GAAG,KAAK,EAAE,KAAY,EAAqB,EAAE;QACvD,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,UAAU;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,4CAA4C,CAAC,CAAC;QACnG,IAAI,IAAgB,CAAC;QACrB,IAAI,CAAC;YAAC,IAAI,GAAG,MAAM,iBAAiB,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,GAAG,WAAW,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QAAC,CAAC;QACpG,MAAM,CAAC;YAAC,OAAO,IAAI,CAAC,GAAG,EAAE,+BAA+B,CAAC,CAAC;QAAC,CAAC;QAC5D,4BAA4B;QAC5B,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YAAC,OAAO,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;QAAC,CAAC;QACpE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtB,MAAM,IAAI,GAAG,IAAI,cAAc,CAAa;YAC1C,IAAI,EAAE,KAAK,EAAC,UAAU,EAAC,EAAE;gBACvB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;gBAChC,IAAI,CAAC,KAAK,EAAE,CAAC;oBAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;oBAAC,UAAU,CAAC,KAAK,EAAE,CAAC;oBAAC,OAAO;gBAAC,CAAC;gBACrE,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,QAAQ,mDAAmD,KAAK,CAAC,IAAI,CAAC,UAAU,UAAU,CAAC,CAAC,CAAC;gBACpI,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAAC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;YAC7E,CAAC;YACD,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;SAC1D,EAAE,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC,CAAC;QACzB,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,EAAE,uCAAuC,QAAQ,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IACtI,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,KAAK,EAAE,KAAY,EAAE,OAAgB,EAAqB,EAAE;QACxE,IAAI,CAAC,KAAK,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,yBAAyB,CAAC,CAAC;QACjE,8GAA8G;QAC9G,IAAI,CAAC,6BAA6B,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;QACnH,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QACnD,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,aAAa;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC;QACrF,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,GAAG,IAAI,GAAG,KAAK,CAAC,CAAC;QAC/D,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,IAAI,QAAQ;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;QAC1E,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC3C,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;QACtD,IAAI,KAAkB,CAAC;QACvB,IAAI,CAAC;YAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAgB,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;QAAC,CAAC;QACzF,wDAAwD;QACxD,MAAM,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,2BAA2B,CAAC,CAAC;QACzD,IAAI,CAAC;YAAC,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAAC,CAAC;QAChC,OAAO,KAAK,EAAE,CAAC;YAAC,OAAO,IAAI,CAAC,KAAK,YAAY,WAAW,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,YAAY,WAAW,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,gCAAgC,CAAC,CAAC;QAAC,CAAC;QAC7N,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;IACjE,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,EAAE,KAAK,EAAE,OAAgB,EAAE,YAAY,GAAuB,EAAE,EAAE,EAAE;YACvE,IAAI,MAAM;gBAAE,MAAM,IAAI,WAAW,CAAC,gBAAgB,EAAE,wBAAwB,CAAC,CAAC;YAC9E,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,UAAU;gBAAE,MAAM,IAAI,WAAW,CAAC,gBAAgB,EAAE,0BAA0B,CAAC,CAAC;YACxH,IAAI,CAAC,OAAO,CAAC,GAAG;gBAAE,MAAM,IAAI,WAAW,CAAC,gBAAgB,EAAE,OAAO,OAAO,CAAC,QAAQ,qFAAqF,CAAC,CAAC;YACxK,IAAI,OAAO,CAAC,KAAK;gBAAE,MAAM,IAAI,WAAW,CAAC,eAAe,EAAE,wBAAwB,CAAC,CAAC;YACpF,IAAI,YAAY,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,YAAY,CAAC,QAAQ,KAAK,SAAS;gBAAE,MAAM,IAAI,WAAW,CAAC,gBAAgB,EAAE,sCAAsC,CAAC,CAAC;YACvK,MAAM,WAAW,GAAG,YAAY,CAAC,WAAW,IAAI,SAAS,CAAC;YAC1D,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,KAAK,IAAI,WAAW,GAAG,UAAU;gBAAE,MAAM,IAAI,WAAW,CAAC,gBAAgB,EAAE,0CAA0C,CAAC,CAAC;YAC/K,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;gBAAE,IAAI,CAAC,GAAG,CAAC,CAAC;YAChD,IAAI,MAAM,CAAC,IAAI,IAAI,SAAS;gBAAE,MAAM,IAAI,WAAW,CAAC,gBAAgB,EAAE,6CAA6C,CAAC,CAAC;YACrH,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACpE,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC;YAChC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,WAAW,CAAC;YAC3C,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,CAAC;YACzD,kDAAkD;YACjD,KAAgC,CAAC,KAAK,EAAE,EAAE,CAAC;YAC5C,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,CAAC,QAAQ,KAAK,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;YAC5H,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,GAAG,QAAQ,KAAK,KAAK,GAAG,EAAE,QAAQ,EAAE,YAAY,CAAC,QAAQ,KAAK,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3I,CAAC;QACD,MAAM,EAAE,KAAK,EAAE,OAAgB,EAAE,EAAE;YACjC,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC1C,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,QAAQ,IAAI,CAAC;gBAAE,OAAO,SAAS,CAAC;YAC5D,MAAM,KAAK,GAAG,yCAAyC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;YAClG,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAChE,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;YACrD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACtB,IAAI,IAAI,KAAK,OAAO;gBAAE,OAAO,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;YACxG,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK;gBAAE,OAAO,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;YAC3D,IAAI,IAAI,KAAK,QAAQ;gBAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;YAC5C,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACpE,OAAO,IAAI,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC;oBACnG,cAAc,EAAE,0BAA0B;oBAC1C,yBAAyB,EAAE,6EAA6E,KAAK,uBAAuB,KAAK,sBAAsB,SAAS,uCAAuC;iBAChN,CAAC,EAAE,CAAC,CAAC;QACR,CAAC;QACD,IAAI,IAAI,KAAK,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QACnF,KAAK,EAAE,GAAG,EAAE,GAAG,MAAM,GAAG,IAAI,CAAC,CAAC,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;YAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;KACnF,CAAC;AACJ,CAAC","sourcesContent":["import { MayuraError } from 'mayura';\nimport type { Browser } from 'mayura/browser';\nimport { viewerPage } from './page.js';\nimport { browserScreencast, type Screencast, type ScreencastOptions, type ViewerInput } from './screencast.js';\n\nexport interface BrowserViewerOptions extends Omit<ScreencastOptions, 'interact' | 'signal'> {\n  /** Where the viewer is mounted in your server, such as `/viewer/`; `/` by default. */\n  readonly basePath?: string;\n  /**\n   * Who may show the viewer page in a frame (its CSP `frame-ancestors`), such as `['https://app.example']`; nobody by\n   * default.\n   */\n  readonly frameAncestors?: readonly string[];\n  /** How many people may watch one share at once; 2 by default (1 to 16). */\n  readonly maxViewersPerShare?: number;\n  /** How many shares may be open at once; 16 by default (1 to 256). */\n  readonly maxShares?: number;\n  /** Input events a second, per share; 60 by default (1 to 500). */\n  readonly maxInputPerSecond?: number;\n}\n\nexport interface ViewerShareOptions {\n  /** Let whoever has the link use the browser (mouse, keyboard, typing); off by default. */\n  readonly interact?: boolean;\n  /** How long the link works, in milliseconds; 1 hour by default (1 s to 24 hours). It also stops when the browser ends. */\n  readonly expiresInMs?: number;\n}\n\nexport interface ViewerShare {\n  /** The viewer page's path, under `basePath`, with the link's token in it: treat it as a secret. */\n  readonly path: string;\n  readonly interact: boolean;\n  /** When the link stops working, in milliseconds since the epoch. */\n  readonly expiresAt: number;\n  /** Stops the link now, and ends what is being watched through it. */\n  revoke(): void;\n}\n\nexport interface BrowserViewer {\n  /** A link to watch the browser, and with `interact` to use it, for whoever has it. */\n  share(browser: Browser, options?: ViewerShareOptions): Promise<ViewerShare>;\n  /** Answers a request for a viewer path (`<basePath>v/...`); undefined for any other, for your server to answer. */\n  handle(request: Request): Promise<Response | undefined>;\n  /** How many shares are open. */\n  readonly size: number;\n  /** Revokes every share, and makes no more. */\n  close(): void;\n}\n\ninterface Share {\n  readonly browser: Browser; readonly interact: boolean; readonly timer: ReturnType<typeof setTimeout>;\n  readonly casts: Set<Screencast>; inputs: number[]; revoked: boolean;\n}\n\nconst boundary = 'mayura-frame';\nconst encoder = new TextEncoder();\nconst origin = /^https?:\\/\\/[a-z0-9.-]+(?::\\d{1,5})?$/iu;\n\nfunction bound(value: number | undefined, name: string, fallback: number, min: number, max: number): number {\n  const result = value ?? fallback;\n  if (!Number.isSafeInteger(result) || result < min || result > max) throw new MayuraError('INVALID_CONFIG', `browserViewer(): ${name} is ${min.toLocaleString('en-US')} to ${max.toLocaleString('en-US')}.`);\n  return result;\n}\nfunction base64Url(bytes: Uint8Array): string {\n  let binary = ''; for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/u, '');\n}\n/** A request's body as text, read no further than `max` bytes; undefined when it is longer. */\nasync function bodyText(request: Request, max: number): Promise<string | undefined> {\n  if (!request.body) return '';\n  const reader = request.body.getReader(); const chunks: Uint8Array[] = []; let size = 0;\n  for (;;) {\n    const { value, done } = await reader.read();\n    if (done) break;\n    size += value.byteLength;\n    if (size > max) { await reader.cancel().catch(() => undefined); return undefined; }\n    chunks.push(value);\n  }\n  const bytes = new Uint8Array(size); let offset = 0;\n  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }\n  return new TextDecoder().decode(bytes);\n}\nasync function digest(token: string): Promise<string> {\n  const hash = new Uint8Array(await crypto.subtle.digest('SHA-256', encoder.encode(token)));\n  return [...hash].map(byte => byte.toString(16).padStart(2, '0')).join('');\n}\n\n/**\n * A live viewer for `mayura/browser` browsers, as web-standard request handling for any server: `share(browser)` gives\n * a link with a secret token to a page showing the browser's active tab as it changes (an MJPEG stream of its\n * screencast), and with `interact` a person can use the page too. Links expire, and end with the browser; nothing is\n * shown that is not shared. For a server of its own on Node, see `serveBrowserViewer`.\n */\nexport function browserViewer(options: BrowserViewerOptions = {}): BrowserViewer {\n  const basePath = options.basePath ?? '/';\n  if (typeof basePath !== 'string' || !/^\\/(?:[A-Za-z0-9._~-]+\\/)*$/u.test(basePath)) throw new MayuraError('INVALID_CONFIG', 'browserViewer(): basePath is a path such as / or /viewer/, starting and ending with /.');\n  const frameAncestors = options.frameAncestors ?? [];\n  if (!Array.isArray(frameAncestors) || frameAncestors.length > 16 || frameAncestors.some(item => typeof item !== 'string' || !origin.test(item))) {\n    throw new MayuraError('INVALID_CONFIG', 'browserViewer(): frameAncestors are origins such as https://app.example.');\n  }\n  const maxViewers = bound(options.maxViewersPerShare, 'maxViewersPerShare', 2, 1, 16);\n  const maxShares = bound(options.maxShares, 'maxShares', 16, 1, 256);\n  const maxInput = bound(options.maxInputPerSecond, 'maxInputPerSecond', 60, 1, 500);\n  const { basePath: _basePath, frameAncestors: _frameAncestors, maxViewersPerShare: _viewers, maxShares: _shares, maxInputPerSecond: _input, ...castOptions } = options;\n  // Checked now, rather than when someone first watches.\n  if (castOptions.webSocket !== undefined && typeof castOptions.webSocket !== 'function') throw new MayuraError('INVALID_CONFIG', 'browserViewer(): webSocket must be a function.');\n  bound(castOptions.quality, 'quality', 60, 1, 100); bound(castOptions.maxWidth, 'maxWidth', 1_280, 320, 3_840); bound(castOptions.maxHeight, 'maxHeight', 800, 240, 2_160);\n  bound(castOptions.maxFps, 'maxFps', 5, 1, 30); bound(castOptions.maxFrameBytes, 'maxFrameBytes', 2_097_152, 65_536, 16_777_216);\n  const ancestors = frameAncestors.length ? frameAncestors.join(' ') : \"'none'\";\n\n  const shares = new Map<string, Share>(); // by the token's SHA-256\n  let closed = false;\n  const revoke = (key: string) => {\n    const share = shares.get(key);\n    if (!share) return;\n    shares.delete(key); share.revoked = true; clearTimeout(share.timer);\n    for (const cast of share.casts) cast.close();\n  };\n  /** The share a token names, while it is open and its browser has not ended. */\n  const find = (key: string): Share | undefined => {\n    const share = shares.get(key);\n    if (share?.browser.ended) { revoke(key); return undefined; }\n    return share;\n  };\n\n  const headers = (extra: Record<string, string> = {}): Record<string, string> => ({\n    'cache-control': 'no-store', 'referrer-policy': 'no-referrer', 'x-content-type-options': 'nosniff',\n    'content-security-policy': `default-src 'none'; frame-ancestors ${ancestors}; base-uri 'none'; form-action 'none'`, ...extra,\n  });\n  const text = (status: number, body: string) => new Response(body, { status, headers: headers({ 'content-type': 'text/plain; charset=utf-8' }) });\n\n  const stream = async (share: Share): Promise<Response> => {\n    if (share.casts.size >= maxViewers) return text(429, 'Too many people are watching this browser.');\n    let cast: Screencast;\n    try { cast = await browserScreencast(share.browser, { ...castOptions, interact: share.interact }); }\n    catch { return text(410, 'This browser cannot be shown.'); }\n    // Revoked while connecting.\n    if (share.revoked) { cast.close(); return text(404, 'Not found.'); }\n    share.casts.add(cast);\n    const body = new ReadableStream<Uint8Array>({\n      pull: async controller => {\n        const frame = await cast.next();\n        if (!frame) { share.casts.delete(cast); controller.close(); return; }\n        controller.enqueue(encoder.encode(`--${boundary}\\r\\nContent-Type: image/jpeg\\r\\nContent-Length: ${frame.data.byteLength}\\r\\n\\r\\n`));\n        controller.enqueue(frame.data); controller.enqueue(encoder.encode('\\r\\n'));\n      },\n      cancel: () => { share.casts.delete(cast); cast.close(); },\n    }, { highWaterMark: 0 });\n    return new Response(body, { status: 200, headers: headers({ 'content-type': `multipart/x-mixed-replace; boundary=${boundary}` }) });\n  };\n\n  const input = async (share: Share, request: Request): Promise<Response> => {\n    if (!share.interact) return text(403, 'This link is view only.');\n    // A JSON body cannot be sent across sites without a preflight, which is never allowed; nor from another site.\n    if (!/^application\\/json(?:;|$)/iu.test(request.headers.get('content-type') ?? '')) return text(415, 'Send JSON.');\n    const site = request.headers.get('sec-fetch-site');\n    if (site !== null && site !== 'same-origin') return text(403, 'Not from this page.');\n    const now = Date.now();\n    share.inputs = share.inputs.filter(time => now - time < 1_000);\n    if (share.inputs.length >= maxInput) return text(429, 'Too many inputs.');\n    share.inputs.push(now);\n    const raw = await bodyText(request, 4_096);\n    if (raw === undefined) return text(413, 'Too large.');\n    let event: ViewerInput;\n    try { event = JSON.parse(raw) as ViewerInput; } catch { return text(400, 'Send JSON.'); }\n    // Input goes to the page as the newest viewer shows it.\n    const cast = [...share.casts].at(-1);\n    if (!cast) return text(409, 'Nothing is being watched.');\n    try { await cast.input(event); }\n    catch (error) { return text(error instanceof MayuraError && error.code === 'INVALID_INPUT' ? 400 : 409, error instanceof MayuraError && error.code === 'INVALID_INPUT' ? error.message : 'The browser did not take that.'); }\n    return new Response(null, { status: 204, headers: headers() });\n  };\n\n  return {\n    share: async (browser: Browser, shareOptions: ViewerShareOptions = {}) => {\n      if (closed) throw new MayuraError('INVALID_CONFIG', 'The viewer was closed.');\n      if (!browser || typeof browser.tabs !== 'function') throw new MayuraError('INVALID_CONFIG', 'share() needs a browser.');\n      if (!browser.cdp) throw new MayuraError('INVALID_CONFIG', `The ${browser.provider} provider's browsers cannot be joined: each connection starts a browser of its own.`);\n      if (browser.ended) throw new MayuraError('INVALID_INPUT', 'The browser has ended.');\n      if (shareOptions.interact !== undefined && typeof shareOptions.interact !== 'boolean') throw new MayuraError('INVALID_CONFIG', 'share(): interact must be a boolean.');\n      const expiresInMs = shareOptions.expiresInMs ?? 3_600_000;\n      if (!Number.isSafeInteger(expiresInMs) || expiresInMs < 1_000 || expiresInMs > 86_400_000) throw new MayuraError('INVALID_CONFIG', 'share(): expiresInMs is 1 s to 24 hours.');\n      for (const key of [...shares.keys()]) find(key);\n      if (shares.size >= maxShares) throw new MayuraError('LIMIT_EXCEEDED', 'Too many shares are open: revoke one first.');\n      const token = base64Url(crypto.getRandomValues(new Uint8Array(32)));\n      const key = await digest(token);\n      const expiresAt = Date.now() + expiresInMs;\n      const timer = setTimeout(() => revoke(key), expiresInMs);\n      // An open link does not keep the process running.\n      (timer as { unref?: () => void }).unref?.();\n      shares.set(key, { browser, interact: shareOptions.interact === true, timer, casts: new Set(), inputs: [], revoked: false });\n      return Object.freeze({ path: `${basePath}v/${token}/`, interact: shareOptions.interact === true, expiresAt, revoke: () => revoke(key) });\n    },\n    handle: async (request: Request) => {\n      const { pathname } = new URL(request.url);\n      if (!pathname.startsWith(`${basePath}v/`)) return undefined;\n      const match = /^([A-Za-z0-9_-]{43})\\/(stream|input)?$/u.exec(pathname.slice(basePath.length + 2));\n      const share = match ? find(await digest(match[1]!)) : undefined;\n      if (!match || !share) return text(404, 'Not found.');\n      const part = match[2];\n      if (part === 'input') return request.method === 'POST' ? input(share, request) : text(405, 'Use POST.');\n      if (request.method !== 'GET') return text(405, 'Use GET.');\n      if (part === 'stream') return stream(share);\n      const nonce = base64Url(crypto.getRandomValues(new Uint8Array(16)));\n      return new Response(viewerPage({ interact: share.interact, nonce }), { status: 200, headers: headers({\n        'content-type': 'text/html; charset=utf-8',\n        'content-security-policy': `default-src 'none'; img-src 'self'; connect-src 'self'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; frame-ancestors ${ancestors}; base-uri 'none'; form-action 'none'`,\n      }) });\n    },\n    get size() { for (const key of [...shares.keys()]) find(key); return shares.size; },\n    close: () => { closed = true; for (const key of [...shares.keys()]) revoke(key); },\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@mayurajs/browser-viewer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.0",
+  "description": "A live viewer for mayura/browser browsers: a screencast of the active tab, shared by link, optionally interactive.",
+  "author": {
+    "name": "Aryabh",
+    "email": "dev@rokad.co"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KartikeyAI/mayura.git",
+    "directory": "extensions/browser-viewer"
+  },
+  "homepage": "https://github.com/KartikeyAI/mayura#readme",
+  "bugs": {
+    "url": "https://github.com/KartikeyAI/mayura/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.12.0 <23 || >=24.14.1 <25"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "dependencies": {},
+  "peerDependencies": {
+    "mayura": "^1.2.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { browserScreencast } from './screencast.js';
+export type { Screencast, ScreencastFrame, ScreencastOptions, ViewerInput } from './screencast.js';
+export { browserViewer } from './viewer.js';
+export type { BrowserViewer, BrowserViewerOptions, ViewerShare, ViewerShareOptions } from './viewer.js';
+export { serveBrowserViewer } from './serve.js';
+export type { ServeBrowserViewerOptions, ServedBrowserViewer } from './serve.js';

package/src/page.ts

@@ -0,0 +1,41 @@
+// The viewer page: the stream as an image, and with interact, the person's mouse and keys sent back as input. Its
+// script and style run only by the page's nonce; it reaches nothing but its own stream and input.
+const script = `
+const view = document.getElementById('view'); const state = document.getElementById('state');
+const send = event => fetch('input', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(event) }).catch(() => undefined);
+const at = event => { const box = view.getBoundingClientRect(); return { x: Math.min(1, Math.max(0, (event.clientX - box.left) / box.width)), y: Math.min(1, Math.max(0, (event.clientY - box.top) / box.height)) }; };
+const mods = event => (event.altKey ? 1 : 0) | (event.ctrlKey ? 2 : 0) | (event.metaKey ? 4 : 0) | (event.shiftKey ? 8 : 0);
+const button = event => ['left', 'middle', 'right'][event.button] ?? 'left';
+let moved = 0;
+view.addEventListener('mousedown', event => { event.preventDefault(); view.focus(); send({ type: 'mouse', action: 'down', ...at(event), button: button(event), clicks: Math.min(3, Math.max(1, event.detail)), modifiers: mods(event) }); });
+view.addEventListener('mouseup', event => { event.preventDefault(); send({ type: 'mouse', action: 'up', ...at(event), button: button(event), clicks: Math.min(3, Math.max(1, event.detail)), modifiers: mods(event) }); });
+view.addEventListener('mousemove', event => { const now = Date.now(); if (now - moved < 50) return; moved = now; send({ type: 'mouse', action: 'move', ...at(event), modifiers: mods(event) }); });
+view.addEventListener('wheel', event => { event.preventDefault(); send({ type: 'wheel', ...at(event), dx: Math.round(event.deltaX), dy: Math.round(event.deltaY) }); }, { passive: false });
+view.addEventListener('contextmenu', event => event.preventDefault());
+for (const action of ['down', 'up']) view.addEventListener('key' + action, event => {
+  if (event.isComposing) return;
+  event.preventDefault(); send({ type: 'key', action, key: event.key, modifiers: mods(event) });
+});
+view.addEventListener('paste', event => { const text = event.clipboardData?.getData('text/plain'); if (text) { event.preventDefault(); send({ type: 'text', text: text.slice(0, 1000) }); } });
+state.textContent = 'Live: you can use this browser. Click the page to type into it.';
+`;
+
+export function viewerPage({ interact, nonce }: { readonly interact: boolean; readonly nonce: string }): string {
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="referrer" content="no-referrer">
+<title>Browser viewer</title>
+<style nonce="${nonce}">
+:root { color-scheme: light dark; --bg: #f6f6f4; --fg: #1d1d1b; --muted: #6b6b66; --edge: #d9d9d4; }
+@media (prefers-color-scheme: dark) { :root { --bg: #151514; --fg: #ecece8; --muted: #9a9a94; --edge: #33332f; } }
+* { box-sizing: border-box; }
+body { margin: 0; min-height: 100vh; display: flex; flex-direction: column; background: var(--bg); color: var(--fg); font: 14px/1.4 system-ui, sans-serif; }
+header { padding: 8px 16px; color: var(--muted); border-bottom: 1px solid var(--edge); }
+main { flex: 1; display: flex; align-items: center; justify-content: center; padding: 16px; }
+img { max-width: 100%; max-height: calc(100vh - 80px); border: 1px solid var(--edge); background: #fff; outline: none; }
+img:focus-visible { outline: 2px solid #3b6fd8; }
+</style></head>
+<body><header id="state">Live: view only.</header>
+<main><img id="view" src="stream" alt="The browser's page, live"${interact ? ' tabindex="0"' : ''}></main>
+${interact ? `<script nonce="${nonce}">${script}</script>` : ''}
+</body></html>`;
+}

package/src/screencast.ts

@@ -0,0 +1,228 @@
+import { MayuraError } from 'mayura';
+import { connectCdp, type Browser, type CdpConnection, type CdpSocketFactory } from 'mayura/browser';
+
+export interface ScreencastOptions {
+  /** JPEG quality, 1 to 100; 60 by default. */
+  readonly quality?: number;
+  /** The widest frame, in pixels; 1,280 by default (320 to 3,840). */
+  readonly maxWidth?: number;
+  /** The tallest frame, in pixels; 800 by default (240 to 2,160). */
+  readonly maxHeight?: number;
+  /** The most frames a second; 5 by default (1 to 30). */
+  readonly maxFps?: number;
+  /** Frames larger than this are skipped, in bytes; 2 MiB by default. */
+  readonly maxFrameBytes?: number;
+  /** Lets `input` use the page, as a person would: off by default. */
+  readonly interact?: boolean;
+  /** For runtimes whose WebSocket cannot send the headers a browser's CDP connection needs. */
+  readonly webSocket?: CdpSocketFactory;
+  /** Ends the screencast. */
+  readonly signal?: AbortSignal;
+}
+
+export interface ScreencastFrame {
+  /** A JPEG of the page as shown. */
+  readonly data: Uint8Array;
+  readonly mediaType: 'image/jpeg';
+  /** The page's size in CSS pixels, which `input` coordinates are fractions of. */
+  readonly width: number;
+  readonly height: number;
+  /** The tab shown, as `browser.tabs()` names it. */
+  readonly tab: string;
+}
+
+/** What a person does in the viewer. Coordinates are fractions of the frame, 0 to 1 from the top left. */
+export type ViewerInput =
+  | { readonly type: 'mouse'; readonly action: 'down' | 'up' | 'move'; readonly x: number; readonly y: number; readonly button?: 'left' | 'middle' | 'right'; readonly clicks?: number; readonly modifiers?: number }
+  | { readonly type: 'wheel'; readonly x: number; readonly y: number; readonly dx: number; readonly dy: number }
+  | { readonly type: 'key'; readonly action: 'down' | 'up'; readonly key: string; readonly modifiers?: number }
+  | { readonly type: 'text'; readonly text: string };
+
+/** The frames of a browser's active tab as it changes, following the tab the browser has active. */
+export interface Screencast extends AsyncIterable<ScreencastFrame> {
+  /** The next frame, waiting for one; undefined once the screencast ended. */
+  next(): Promise<ScreencastFrame | undefined>;
+  /** Uses the page shown, for screencasts with `interact`. */
+  input(event: ViewerInput, options?: { readonly signal?: AbortSignal }): Promise<void>;
+  /** True once closed, or once its browser or connection ended. */
+  readonly ended: boolean;
+  close(): void;
+}
+
+const named: Readonly<Record<string, { readonly code: string; readonly keyCode: number; readonly text?: string }>> = {
+  Enter: { code: 'Enter', keyCode: 13, text: '\r' }, Tab: { code: 'Tab', keyCode: 9 }, Escape: { code: 'Escape', keyCode: 27 },
+  Backspace: { code: 'Backspace', keyCode: 8 }, Delete: { code: 'Delete', keyCode: 46 },
+  ArrowUp: { code: 'ArrowUp', keyCode: 38 }, ArrowDown: { code: 'ArrowDown', keyCode: 40 }, ArrowLeft: { code: 'ArrowLeft', keyCode: 37 }, ArrowRight: { code: 'ArrowRight', keyCode: 39 },
+  Home: { code: 'Home', keyCode: 36 }, End: { code: 'End', keyCode: 35 }, PageUp: { code: 'PageUp', keyCode: 33 }, PageDown: { code: 'PageDown', keyCode: 34 },
+  Shift: { code: 'ShiftLeft', keyCode: 16 }, Control: { code: 'ControlLeft', keyCode: 17 }, Alt: { code: 'AltLeft', keyCode: 18 }, Meta: { code: 'MetaLeft', keyCode: 91 },
+};
+const buttons = { left: 'left', middle: 'middle', right: 'right' } as const;
+const mouseTypes = { down: 'mousePressed', up: 'mouseReleased', move: 'mouseMoved' } as const;
+
+function bound(value: number | undefined, name: string, fallback: number, min: number, max: number): number {
+  const result = value ?? fallback;
+  if (!Number.isSafeInteger(result) || result < min || result > max) throw new MayuraError('INVALID_CONFIG', `browserScreencast(): ${name} is ${min.toLocaleString('en-US')} to ${max.toLocaleString('en-US')}.`);
+  return result;
+}
+const fraction = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+const modifiersOf = (value: unknown): number => {
+  if (value === undefined) return 0;
+  if (!Number.isSafeInteger(value) || (value as number) < 0 || (value as number) > 15) throw new MayuraError('INVALID_INPUT', 'modifiers is 0 to 15 (Alt 1, Control 2, Meta 4, Shift 8).');
+  return value as number;
+};
+function decode(base64: string): Uint8Array {
+  const binary = atob(base64); const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+  return bytes;
+}
+
+/**
+ * A screencast of a `mayura/browser` browser: the active tab's frames as JPEGs, over a CDP connection of its own, and,
+ * with `interact`, a way for a person to use the page. Frames come no faster than `maxFps`, and only as fast as they
+ * are taken. The browser's origins hold for whatever a person does. It needs a browser other clients can join
+ * (`browser.cdp`).
+ */
+export async function browserScreencast(browser: Browser, options: ScreencastOptions = {}): Promise<Screencast> {
+  if (!browser || typeof browser.tabs !== 'function') throw new MayuraError('INVALID_CONFIG', 'browserScreencast() needs a browser.');
+  const quality = bound(options.quality, 'quality', 60, 1, 100);
+  const maxWidth = bound(options.maxWidth, 'maxWidth', 1_280, 320, 3_840);
+  const maxHeight = bound(options.maxHeight, 'maxHeight', 800, 240, 2_160);
+  const maxFps = bound(options.maxFps, 'maxFps', 5, 1, 30);
+  const maxFrameBytes = bound(options.maxFrameBytes, 'maxFrameBytes', 2_097_152, 65_536, 16_777_216);
+  if (options.interact !== undefined && typeof options.interact !== 'boolean') throw new MayuraError('INVALID_CONFIG', 'browserScreencast(): interact must be a boolean.');
+  const cdp = browser.cdp;
+  if (!cdp) throw new MayuraError('INVALID_CONFIG', `The ${browser.provider} provider's browsers cannot be joined: each connection starts a browser of its own.`);
+  if (browser.ended) throw new MayuraError('INVALID_INPUT', 'The browser has ended.');
+
+  const connection: CdpConnection = await connectCdp(cdp.url, { headers: cdp.headers, ...(options.webSocket ? { webSocket: options.webSocket } : {}), ...(options.signal ? { signal: options.signal } : {}) });
+  let ended = false;
+  let shown: { readonly tab: string; readonly sessionId: string } | undefined;
+  let size = { width: 0, height: 0 };
+  let waiting: { readonly frame: ScreencastFrame; readonly ack: number; readonly sessionId: string } | undefined;
+  let taker: ((frame: ScreencastFrame | undefined) => void) | undefined;
+  let lastAck = 0; let ackTimer: ReturnType<typeof setTimeout> | undefined;
+  let followTimer: ReturnType<typeof setTimeout> | undefined; let failures = 0;
+
+  const end = () => {
+    if (ended) return;
+    ended = true;
+    clearTimeout(ackTimer); clearTimeout(followTimer);
+    options.signal?.removeEventListener('abort', end);
+    waiting = undefined; const take = taker; taker = undefined; take?.(undefined);
+    connection.close();
+  };
+  options.signal?.addEventListener('abort', end, { once: true });
+  void connection.closed.then(end);
+
+  const ack = (sessionId: string, id: number) => { void connection.send('Page.screencastFrameAck', { sessionId: id }, { sessionId }).catch(() => undefined); };
+  const offFrames = connection.on('Page.screencastFrame', (params, sessionId) => {
+    if (ended || !shown || sessionId !== shown.sessionId) return;
+    const id = params['sessionId']; const data = params['data']; const metadata = params['metadata'] as { deviceWidth?: unknown; deviceHeight?: unknown } | undefined;
+    if (typeof id !== 'number' || typeof data !== 'string') return;
+    // Base64 is 4/3 of the bytes: a frame too large is skipped, unread.
+    if (data.length > Math.ceil(maxFrameBytes / 3) * 4) { ack(sessionId, id); return; }
+    const width = typeof metadata?.deviceWidth === 'number' && metadata.deviceWidth > 0 ? metadata.deviceWidth : size.width;
+    const height = typeof metadata?.deviceHeight === 'number' && metadata.deviceHeight > 0 ? metadata.deviceHeight : size.height;
+    let bytes: Uint8Array;
+    try { bytes = decode(data); } catch { ack(sessionId, id); return; }
+    size = { width, height };
+    const frame: ScreencastFrame = Object.freeze({ data: bytes, mediaType: 'image/jpeg' as const, width, height, tab: shown.tab });
+    if (taker) { const take = taker; taker = undefined; take(frame); schedule(sessionId, id); }
+    else waiting = { frame, ack: id, sessionId };
+  });
+  void connection.closed.then(offFrames);
+  // The next frame is asked for once this one is taken, and no sooner than maxFps allows.
+  const schedule = (sessionId: string, id: number) => {
+    const wait = Math.max(0, lastAck + 1_000 / maxFps - Date.now());
+    ackTimer = setTimeout(() => { lastAck = Date.now(); ack(sessionId, id); }, wait);
+  };
+
+  const show = async (tab: string) => {
+    const previous = shown; shown = undefined; waiting = undefined;
+    if (previous) await connection.send('Target.detachFromTarget', { sessionId: previous.sessionId }).catch(() => undefined);
+    const { sessionId } = await connection.send<{ sessionId: string }>('Target.attachToTarget', { targetId: tab, flatten: true });
+    shown = { tab, sessionId };
+    await connection.send('Page.startScreencast', { format: 'jpeg', quality, maxWidth, maxHeight, everyNthFrame: 1 }, { sessionId });
+  };
+  // Follows the tab the browser has active, as its agent moves between tabs.
+  const follow = async () => {
+    if (ended) return;
+    if (browser.ended) { end(); return; }
+    try {
+      const active = (await browser.tabs(options.signal ? { signal: options.signal } : {})).find(tab => tab.active);
+      if (active && active.tab !== shown?.tab) await show(active.tab);
+      failures = 0;
+    } catch {
+      if (browser.ended || ++failures >= 3) { end(); return; }
+    }
+    if (!ended) followTimer = setTimeout(() => void follow(), 1_000);
+  };
+  await follow();
+
+  const next = (): Promise<ScreencastFrame | undefined> => {
+    if (ended) return Promise.resolve(undefined);
+    if (waiting) { const { frame, ack: id, sessionId } = waiting; waiting = undefined; schedule(sessionId, id); return Promise.resolve(frame); }
+    if (taker) return Promise.reject(new MayuraError('INVALID_INPUT', 'Take one frame at a time.'));
+    return new Promise(resolve => { taker = resolve; });
+  };
+
+  const input = async (event: ViewerInput, inputOptions: { readonly signal?: AbortSignal } = {}): Promise<void> => {
+    if (options.interact !== true) throw new MayuraError('PERMISSION_DENIED', 'This screencast is view only.');
+    if (ended) throw new MayuraError('INVALID_INPUT', 'The screencast has ended.');
+    const on = shown;
+    if (!on || size.width === 0) throw new MayuraError('INVALID_INPUT', 'No page is shown yet.');
+    const send = (method: string, params: Record<string, unknown>) => connection.send(method, params, { sessionId: on.sessionId, ...(inputOptions.signal ? { signal: inputOptions.signal } : {}) });
+    const item = event as Record<string, unknown> | null;
+    if (!item || typeof item !== 'object') throw new MayuraError('INVALID_INPUT', 'An input is an object with a type.');
+    if (item['type'] === 'mouse' || item['type'] === 'wheel') {
+      if (!fraction(item['x']) || !fraction(item['y'])) throw new MayuraError('INVALID_INPUT', 'x and y are fractions of the frame, 0 to 1.');
+      const point = { x: Math.round(item['x'] * size.width), y: Math.round(item['y'] * size.height) };
+      if (item['type'] === 'wheel') {
+        const { dx, dy } = item;
+        if (typeof dx !== 'number' || typeof dy !== 'number' || !Number.isFinite(dx) || !Number.isFinite(dy) || Math.abs(dx) > 10_000 || Math.abs(dy) > 10_000) throw new MayuraError('INVALID_INPUT', 'dx and dy are pixels, -10,000 to 10,000.');
+        await send('Input.dispatchMouseEvent', { type: 'mouseWheel', ...point, deltaX: dx, deltaY: dy });
+        return;
+      }
+      const type = mouseTypes[item['action'] as keyof typeof mouseTypes];
+      const button = item['button'] === undefined ? 'left' : buttons[item['button'] as keyof typeof buttons];
+      const clicks = item['clicks'] ?? 1;
+      if (!Object.hasOwn(mouseTypes, item['action'] as string) || !button || !Object.hasOwn(buttons, button) || !Number.isSafeInteger(clicks) || (clicks as number) < 1 || (clicks as number) > 3) {
+        throw new MayuraError('INVALID_INPUT', 'A mouse input has action down, up or move, a button left, middle or right, and clicks 1 to 3.');
+      }
+      await send('Input.dispatchMouseEvent', { type, ...point, modifiers: modifiersOf(item['modifiers']), ...(type === 'mouseMoved' ? {} : { button, clickCount: clicks }) });
+      return;
+    }
+    if (item['type'] === 'key') {
+      const key = item['key'];
+      if ((item['action'] !== 'down' && item['action'] !== 'up') || typeof key !== 'string') throw new MayuraError('INVALID_INPUT', 'A key input has action down or up, and a key.');
+      const modifiers = modifiersOf(item['modifiers']);
+      const definition = Object.hasOwn(named, key) ? named[key]! : [...key].length === 1 && /^[^\p{Cc}]$/u.test(key) ? {
+        code: /^[a-z]$/iu.test(key) ? `Key${key.toUpperCase()}` : /^\d$/u.test(key) ? `Digit${key}` : '', keyCode: /^[a-z\d]$/iu.test(key) ? key.toUpperCase().charCodeAt(0) : 0,
+        // Typed as text unless Control, Alt or Meta is held.
+        ...(modifiers & 7 ? {} : { text: key }),
+      } : undefined;
+      if (!definition) throw new MayuraError('INVALID_INPUT', 'key is one character, or a key such as Enter, Tab, Backspace or ArrowDown.');
+      const common = { key, code: definition.code, windowsVirtualKeyCode: definition.keyCode, modifiers };
+      await send('Input.dispatchKeyEvent', item['action'] === 'up' ? { type: 'keyUp', ...common }
+        : definition.text !== undefined ? { type: 'keyDown', ...common, text: definition.text, unmodifiedText: definition.text } : { type: 'rawKeyDown', ...common });
+      return;
+    }
+    if (item['type'] === 'text') {
+      if (typeof item['text'] !== 'string' || item['text'].length === 0 || item['text'].length > 1_000) throw new MayuraError('INVALID_INPUT', 'text is 1 to 1,000 characters.');
+      await send('Input.insertText', { text: item['text'] });
+      return;
+    }
+    throw new MayuraError('INVALID_INPUT', 'type is mouse, wheel, key or text.');
+  };
+
+  const screencast: Screencast = {
+    next, input,
+    get ended() { return ended; },
+    close: end,
+    [Symbol.asyncIterator]: () => ({
+      next: async () => { const frame = await next(); return frame ? { value: frame, done: false } : { value: undefined, done: true }; },
+      return: async () => { end(); return { value: undefined, done: true }; },
+    }),
+  };
+  return screencast;
+}