@linkshell/host 0.4.44 → 0.4.46

package/dist/host/src/screen.js

@@ -9,6 +9,9 @@ import { closeInputApp, inputApp, InputControl, macAppSupported, NO_APP, videoSi
 import { LADDER, Pacer, RELAY_LEVEL, rung } from "./screen-pacer.js";
 import { viewerPage } from "./screen-viewer.js";
 import { screenMeasurementLog } from "./screen-metrics.js";
+import { captureWindows, configureWindowsCapture, WindowsFrameSplitter, windowsDisplays, windowsHelper, windowsProfile } from "./windows-screen.js";
+import { WindowsVideoSession, windowsMedia } from "./windows-video.js";
+import { fallbackProfile, fallbackSize, SCREEN_RETAIN_MS, screenConfiguration } from "./screen-session.js";
 // Viewing the computer's screen from the phone. The host serves a small
 // viewer page on a loopback port; the phone opens it through the same
 // encrypted forwarder as port previews. A random token gates the port: other
@@ -30,9 +33,18 @@ async function hasFfmpeg() {
 }
 /** What the phone is told when the picture can't be had for want of the permission. */
 const notAllowed = (app) => `电脑还没有允许${app ? `「${app}」` : ""}录制屏幕。在电脑上运行 linkshell screen 按提示操作，或在「系统设置 › 隐私与安全性 › 录屏与系统录音」里打开${app ? `「${app}」` : "它"}的开关，然后重新进入这个页面。`;
+async function captureReleased(capture) {
+    let timer;
+    try {
+        await Promise.race([capture.gone, new Promise((resolve) => { timer = setTimeout(resolve, 3000); timer.unref(); })]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 /** ffmpeg's capture of an X display (Linux), for one rung of the ladder (see `screen-pacer.ts`): 0 is the best picture. */
-export function captureArgs(level = 0) {
-    const profile = rung(level);
+export function captureArgs(level = 0, profile = fallbackProfile(level)) {
     const rate = (bits) => `${Math.round(bits / 1000)}k`;
     return [
         "-hide_banner",
@@ -207,6 +219,7 @@ export class ScreenShare {
     /** The viewer the app is sending the screen to as a video track. One at a time, like captures. */
     video;
     controls = new Set();
+    viewers = new Map();
     constructor(log, 
     /** The servers both ends ask for their public address, to reach each other directly. */
     iceServers = () => []) {
@@ -224,18 +237,22 @@ export class ScreenShare {
         return { port, token: this.token, displays: displays.map(({ index, name }) => ({ index, name })) };
     }
     async listDisplays() {
+        if (process.platform === "win32")
+            return (await windowsDisplays()).map(({ screen, name, w, h }) => ({ index: screen, screen, name, w, h }));
         if (process.platform === "darwin") {
             const app = inputApp(this.log);
             if (!app)
                 throw RpcError.app("not_supported", NO_APP);
             const displays = await app.displays();
-            return displays.map(({ screen, name }) => ({ index: screen, screen, name: name || `屏幕 ${screen + 1}` }));
+            return displays.map(({ screen, name, w, h }) => ({ index: screen, screen, name: name || `屏幕 ${screen + 1}`, w, h }));
         }
         if (process.platform !== "linux")
             throw RpcError.app("not_supported", "这台电脑的系统暂不支持查看屏幕");
         if (!(await hasFfmpeg()))
             throw RpcError.app("not_supported", "查看屏幕需要电脑上装有 ffmpeg");
-        return [{ index: 0, name: "屏幕", screen: 0 }];
+        // x11grab captures the X display's root window, which may span several monitors.
+        const dimensions = await run("xdpyinfo", [], { timeout: 5000 }).then(({ stdout }) => /dimensions:\s+(\d+)x(\d+)\s+pixels/.exec(stdout), () => null);
+        return [{ index: 0, name: "屏幕", screen: 0, ...(dimensions ? { w: Number(dimensions[1]), h: Number(dimensions[2]) } : {}) }];
     }
     listen() {
         if (this.server)
@@ -252,7 +269,7 @@ export class ScreenShare {
                 response.writeHead(302, { location: `${url.pathname}${url.search}`, "cache-control": "no-store" }).end();
                 return;
             }
-            response.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" }).end(viewerPage());
+            response.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" }).end(viewerPage(process.platform));
         });
         const sockets = new WebSocketServer({ noServer: true });
         server.on("upgrade", (request, socket, head) => {
@@ -289,6 +306,16 @@ export class ScreenShare {
      * (`ffmpeg`: whether what captures is there — ffmpeg itself on Linux.)
      */
     async access(ask) {
+        if (process.platform === "win32") {
+            const found = Boolean(windowsHelper());
+            try {
+                const displays = await windowsDisplays();
+                return { supported: true, ffmpeg: true, recording: displays.length > 0, control: true, app: "LinkShell" };
+            }
+            catch (error) {
+                return { supported: true, ffmpeg: found, recording: false, control: false, problem: error.message };
+            }
+        }
         const supported = macAppSupported() || process.platform === "linux";
         if (process.platform !== "darwin")
             return { supported, ffmpeg: supported && (await hasFfmpeg()), recording: null, control: null, problem: "controlling the screen needs macOS" };
@@ -310,7 +337,7 @@ export class ScreenShare {
         }
     }
     /** Starts a capture where it may record. Undefined when it may not: the viewer has been told why. */
-    async capture(screen, level, on) {
+    async capture(screen, level, on, profile = fallbackProfile(level), wanted = () => true) {
         let ended = false;
         let leave = () => { };
         const gone = new Promise((resolve) => (leave = resolve));
@@ -321,6 +348,8 @@ export class ScreenShare {
                 return undefined;
             }
             const status = await app.access();
+            if (!wanted())
+                return undefined;
             if (!status.recording) {
                 // Someone may be at the computer: the app's window for its permissions comes up there.
                 void app.ask().catch(() => { });
@@ -328,9 +357,9 @@ export class ScreenShare {
                 return undefined;
             }
             let size;
-            const stream = await app.stream(screen, rung(level), {
+            const stream = await app.stream(screen, profile, {
                 frame: (unit, key, generation) => {
-                    if (ended)
+                    if (ended || !wanted())
                         return;
                     if (size !== undefined && generation !== size)
                         on.resized?.();
@@ -339,37 +368,54 @@ export class ScreenShare {
                 },
                 exit: (error) => {
                     leave();
-                    if (ended)
+                    if (ended || !wanted())
                         return;
                     if (error)
                         this.log(`[screen] the app's capture ended: ${error}`);
                     on.exit(!error ? undefined : /permission|not allowed|not authorized|denied|declined/i.test(error) ? notAllowed(status.app) : "屏幕捕获失败");
                 },
             });
+            const ready = stream.ready.then(({ width, height, fps }) => ({ width, height, maxFps: fps }));
+            void ready.catch(() => { });
             return {
                 on,
                 gone,
+                ready,
                 end: () => {
                     ended = true;
                     stream.end();
                     leave();
                 },
-                change: (next) => stream.set(rung(next)),
+                change: (next, requested) => stream.set(requested ?? rung(next)),
                 key: () => stream.key(),
             };
         }
-        const capture = spawn("ffmpeg", captureArgs(level), { stdio: ["ignore", "pipe", "pipe"] });
+        if (!wanted())
+            return undefined;
+        const windows = process.platform === "win32";
+        const capture = windows ? captureWindows(screen, { ...profile, quality: windowsProfile(level).quality }) : spawn("ffmpeg", captureArgs(level, profile), { stdio: ["ignore", "pipe", "pipe"] });
         this.captures.add(capture);
         const splitter = new AccessUnitSplitter();
+        const jpeg = new WindowsFrameSplitter();
         let errors = "";
         capture.stdout.on("data", (chunk) => {
-            if (!ended)
-                splitter.push(chunk, on.frame);
+            if (ended || !wanted())
+                return;
+            try {
+                if (windows)
+                    jpeg.push(chunk, frame => on.frame(frame, true));
+                else
+                    splitter.push(chunk, on.frame);
+            }
+            catch (error) {
+                errors = error.message;
+                endCapture(capture, true);
+            }
         });
         capture.stderr.on("data", (chunk) => (errors = (errors + chunk.toString()).slice(-2000)));
         const finished = (code, said) => {
             leave();
-            if (ended)
+            if (ended || !wanted())
                 return;
             if (code)
                 this.log(`[screen] capture exited ${code}: ${said.trim()}`);
@@ -387,11 +433,17 @@ export class ScreenShare {
                 ended = true;
                 endCapture(capture);
             },
+            ...(windows ? {
+                change: (next, requested) => configureWindowsCapture(capture, { t: "profile", ...(requested ?? profile), quality: windowsProfile(next).quality }),
+                key: () => configureWindowsCapture(capture, { t: "keyframe" }),
+            } : {}),
         };
     }
     /** Takes the screen for a new capture: whatever holds it is ended, and has left, before the new one starts. */
-    take(screen, level, on, wanted) {
+    take(screen, level, on, wanted, profile = fallbackProfile(level)) {
         const mine = this.turn.then(async () => {
+            if (!wanted())
+                return undefined;
             this.video?.taken();
             const previous = this.holder;
             if (previous) {
@@ -400,11 +452,15 @@ export class ScreenShare {
                 // Another device's picture ends here; a viewer changing its own just carries on.
                 if (previous.on !== on)
                     previous.on.exit("屏幕画面被另一台设备接手了");
-                await Promise.race([previous.gone, new Promise((resolve) => setTimeout(resolve, 3000))]);
+                await captureReleased(previous);
             }
             if (!wanted())
                 return undefined;
-            const running = await this.capture(screen, level, on);
+            const running = await this.capture(screen, level, on, profile, wanted);
+            if (!wanted()) {
+                running?.end();
+                return undefined;
+            }
             this.holder = running;
             return running;
         });
@@ -416,6 +472,56 @@ export class ScreenShare {
      * app without the media engine): the picture then goes down the socket.
      */
     async offerVideo(screen, maxWidth, maxFps, diagnostics, codec, viewer) {
+        if (process.platform === "win32" && process.env.LINKSHELL_SCREEN_VIDEO !== "off" && windowsMedia()) {
+            // The native guard checks the selected desktop and the local opt-out throughout capture.
+            await windowsDisplays();
+            if (viewer.closed())
+                return "refused";
+            this.video?.taken();
+            const holder = this.holder;
+            if (holder) {
+                this.holder = undefined;
+                holder.end();
+                holder.on.exit("屏幕画面被另一台设备接手了");
+                await captureReleased(holder);
+            }
+            if (viewer.closed())
+                return "refused";
+            const iceServers = this.iceServers().map(url => ({ urls: [url] }));
+            viewer.tell({ rtc: { t: "config", iceServers } });
+            const session = new WindowsVideoSession({ screen, iceServers, maxWidth, maxFps }, {
+                tell: message => viewer.tell({ rtc: message }), input: viewer.input, lost: viewer.lost, log: this.log,
+            });
+            const mine = { id: session.id, taken: () => {
+                    if (this.video === mine)
+                        this.video = undefined;
+                    session.end();
+                    viewer.refuse("屏幕画面被另一台设备接手了");
+                } };
+            this.video = mine;
+            const cancelled = setInterval(() => { if (viewer.closed())
+                session.end(); }, 100);
+            try {
+                await session.offer();
+                if (viewer.closed() || this.video !== mine) {
+                    session.end();
+                    if (this.video === mine)
+                        this.video = undefined;
+                    return "refused";
+                }
+                return session;
+            }
+            catch (error) {
+                session.end();
+                if (this.video === mine)
+                    this.video = undefined;
+                this.log(`[screen] Windows video could not start: ${String(error)}`);
+                return undefined;
+            }
+            finally {
+                clearInterval(cancelled);
+            }
+        }
         // LINKSHELL_SCREEN_VIDEO=off: every viewer gets the picture down the socket (to compare the two, or should the track ever misbehave).
         const app = process.platform === "darwin" && process.env.LINKSHELL_SCREEN_VIDEO !== "off" ? inputApp(this.log) : undefined;
         if (!app)
@@ -435,10 +541,14 @@ export class ScreenShare {
         this.video?.taken();
         const holder = this.holder;
         if (holder) {
-            this.holder = undefined;
             holder.end();
             holder.on.exit("屏幕画面被另一台设备接手了");
+            await captureReleased(holder);
+            if (this.holder === holder)
+                this.holder = undefined;
         }
+        if (viewer.closed())
+            return "refused";
         const id = `video-${randomBytes(6).toString("hex")}`;
         const mine = {
             id,
@@ -480,44 +590,153 @@ export class ScreenShare {
                 viewer.tell({ rtc: { ...rest, t: kind.slice(4) } });
             }
         });
-        return { app, id };
+        if (viewer.closed() || this.video !== mine) {
+            app.endVideo(id);
+            if (this.video === mine)
+                this.video = undefined;
+            return "refused";
+        }
+        return { id, reconfigure: status.videoReconfigure === true, configure: configuration => app.configureVideo(id, configuration), signal: message => app.signal(id, message), end: () => app.endVideo(id) };
     }
     stream(ws, display, relayed, wantsVideo, width, maxFps, diagnostics = false, codec) {
-        const shown = this.displays.find((entry) => entry.index === display) ?? this.displays[0];
-        const tell = (message) => ws.readyState === ws.OPEN && ws.send(JSON.stringify(message));
-        // The viewer's hands: started when it first asks to control, for the display it is watching.
-        const control = new InputControl({
-            state: (state) => tell({ control: state }),
-            cursor: (x, y) => tell({ cursor: { x, y } }),
-            posted: (event) => this.log(`[screen] dry run: ${JSON.stringify(event)}`),
-        }, this.log);
-        this.controls.add(control);
-        // The picture: as good as the path carries without falling behind (see `screen-pacer.ts`).
-        const best = relayed ? RELAY_LEVEL : 0;
-        const pacer = new Pacer(Date.now());
-        let level = best;
+        // Paused viewers still own a session. A new authenticated viewer takes that ownership too.
+        for (const [previous, release] of this.viewers) {
+            if (previous.readyState === previous.OPEN)
+                previous.send(JSON.stringify({ error: "屏幕画面被另一台设备接手了" }));
+            release();
+            previous.close();
+        }
+        let shown = this.displays.find((entry) => entry.index === display) ?? this.displays[0];
+        let desired = { display: shown?.index ?? 0, width: width ?? 1920, maxFps: maxFps === 30 || maxFps === 60 || maxFps === 120 ? maxFps : undefined, paused: false };
         let closed = false;
+        const live = () => !closed && ws.readyState === ws.OPEN;
+        const tell = (message) => { if (live())
+            ws.send(JSON.stringify(message)); };
+        let control;
+        let controlRequested = false;
+        let inputEnabled = false;
+        let generationEnabled = false;
+        let inputGeneration = 0;
+        let appliedGeneration;
+        let revision = 0;
+        let lastRequestId = -1;
+        let desiredRequestId;
+        let helperRequestId = 0;
+        let pending;
+        let configuring = false;
+        let initialized = false;
+        let canConfigure = false;
+        let pausedExpiry;
+        let running;
+        let captureGeneration = 0;
+        let video;
+        let signals = Promise.resolve();
+        const windows = process.platform === "win32";
+        const best = relayed ? windows ? 1 : RELAY_LEVEL : 0;
+        const pacer = new Pacer(Date.now(), windows ? { maxInFlight: 2, behindMs: 120, caughtUpMs: 50, probeMs: 1500 } : {});
+        const profileFor = (next, configuration) => ({
+            ...fallbackProfile(next, configuration),
+            ...(windows ? windowsProfile(next, configuration.width, configuration.maxFps) : {}),
+        });
+        let level = best;
         let changing = false;
         let lighter = false;
         let askedForKey = 0;
-        // Nobody is looking at the viewer (its page is hidden): nothing is sent, and its slowness to answer means nothing.
-        let unwatched = false;
-        // Sending again starts at a keyframe.
-        let wantsKey = false;
-        let running;
-        // Dropping, with only a keyframe missing to carry on: a capture that makes one when asked is asked.
+        let wantsKey = true;
+        const stopControl = () => {
+            inputEnabled = false;
+            if (!control)
+                return;
+            control.stop();
+            this.controls.delete(control);
+            control = undefined;
+        };
+        const startControl = async (preparing = false) => {
+            if (!live() || (!inputEnabled && !preparing) || desired.paused || !controlRequested || control)
+                return;
+            const at = revision;
+            const created = new InputControl({
+                // Readiness may arrive while the applied target is still being acknowledged; it is
+                // safe to report permissions then, while the independent input gate stays closed.
+                state: (state) => { if (control === created && revision === at)
+                    tell({ control: state }); },
+                cursor: (x, y) => { if (control === created && inputEnabled && !video?.cursor?.(x, y))
+                    tell({ cursor: { x, y } }); },
+                posted: (event) => this.log(`[screen] dry run: ${JSON.stringify(event)}`),
+            }, this.log);
+            control = created;
+            this.controls.add(created);
+            await created.start(shown?.screen ?? 0);
+            if (!live() || control !== created || revision !== at || (!inputEnabled && !preparing)) {
+                created.stop();
+                this.controls.delete(created);
+            }
+        };
+        const stopRunning = () => {
+            captureGeneration += 1;
+            const stopped = running;
+            running = undefined;
+            stopped?.end();
+            // ffmpeg can hold the recorder until SIGKILL; the next capture must wait for it.
+            if (stopped && this.holder === stopped)
+                void stopped.gone.then(() => { if (this.holder === stopped)
+                    this.holder = undefined; });
+        };
+        const endVideo = () => {
+            if (!video)
+                return;
+            const ended = video;
+            video = undefined;
+            ended.end();
+            if (this.video?.id === ended.id)
+                this.video = undefined;
+        };
+        const expirePaused = () => {
+            if (pausedExpiry)
+                return;
+            pausedExpiry = setTimeout(() => {
+                pausedExpiry = undefined;
+                if (live()) {
+                    dispose();
+                    ws.close(1000, "screen retention expired");
+                }
+            }, SCREEN_RETAIN_MS);
+            pausedExpiry.unref();
+        };
+        const resumed = () => {
+            if (pausedExpiry)
+                clearTimeout(pausedExpiry);
+            pausedExpiry = undefined;
+        };
+        const capabilities = () => tell({ session: { t: "capabilities", version: 1, configure: canConfigure, pause: video ? !!(video.reconfigure || video.pause) : true, retainMs: SCREEN_RETAIN_MS } });
+        const failure = (error) => {
+            if (!live())
+                return;
+            this.log(`[screen] the capture did not start: ${String(error)}`);
+            tell({ error: "屏幕捕获失败" });
+            dispose();
+            ws.close();
+        };
         const askForKey = () => {
+            if (!live() || desired.paused || configuring)
+                return;
             const now = Date.now();
             if (!running?.key || now - askedForKey < 500 || !pacer.needsKey(now))
                 return;
             askedForKey = now;
             running.key();
         };
-        // A still screen sends no frame to be reminded by.
-        const reminder = setInterval(askForKey, 500);
+        let reminder;
+        const stopReminder = () => { if (reminder)
+            clearInterval(reminder); reminder = undefined; };
+        const startReminder = () => { if (!reminder)
+            reminder = setInterval(askForKey, 500); };
+        startReminder();
         const events = {
             frame: (unit, key) => {
-                if (ws.readyState !== ws.OPEN || unwatched)
+                if (!live() || desired.paused)
+                    return;
+                if (windows && ws.bufferedAmount > 256 * 1024)
                     return;
                 if (wantsKey && !key)
                     return;
@@ -526,110 +745,239 @@ export class ScreenShare {
                 const seq = pacer.next(key, now);
                 if (seq !== undefined) {
                     const head = Buffer.allocUnsafe(5);
-                    head[0] = key ? 1 : 0;
+                    head[0] = windows ? 2 : key ? 1 : 0;
                     head.writeUInt32BE(seq >>> 0, 1);
                     ws.send(Buffer.concat([head, unit]));
                 }
                 else
                     askForKey();
-                const advice = changing ? undefined : pacer.advice(now, level > best, level < LADDER.length - 1);
+                const advice = changing || configuring ? undefined : pacer.advice(now, level > best, level < LADDER.length - 1);
                 if (advice)
-                    void change(level + (advice === "down" ? 1 : -1));
+                    void changeLevel(level + (advice === "down" ? 1 : -1));
             },
-            // The page starts its decoder afresh for the new size; what it had of the old one came before this, in order.
             resized: () => tell({ restart: true, level, lighter }),
-            exit: (message) => {
-                if (message)
-                    tell({ error: message });
-                ws.close();
-            },
+            exit: (message) => { if (message)
+                tell({ error: message }); dispose(); ws.close(); },
         };
-        const begin = async () => {
-            const started = await this.take(shown?.screen ?? 0, level, events, () => !closed);
-            if (closed)
+        const begin = async (at, target, configuration) => {
+            const captureAt = ++captureGeneration;
+            const wanted = () => live() && revision === at && captureGeneration === captureAt && !desired.paused && !video;
+            const scoped = {
+                frame: (unit, key) => { if (wanted())
+                    events.frame(unit, key); },
+                resized: () => { if (wanted())
+                    events.resized?.(); },
+                exit: (message) => { if (wanted())
+                    events.exit(message); },
+            };
+            const started = await this.take(target?.screen ?? 0, level, scoped, wanted, profileFor(level, configuration));
+            if (!wanted()) {
+                if (this.holder === started)
+                    this.holder = undefined;
                 started?.end();
-            else
+            }
+            else {
                 running = started;
+                if (started?.ready) {
+                    let timer;
+                    try {
+                        const size = await Promise.race([started.ready, new Promise((_resolve, reject) => { timer = setTimeout(() => reject(new Error("屏幕捕获启动超时")), 15_000); timer.unref(); })]);
+                        if (wanted())
+                            return size;
+                    }
+                    catch (error) {
+                        if (wanted())
+                            throw error;
+                    }
+                    finally {
+                        if (timer)
+                            clearTimeout(timer);
+                    }
+                }
+            }
+            return undefined;
         };
-        const failed = (error) => {
-            this.log(`[screen] the capture did not start: ${error.message}`);
-            tell({ error: "屏幕捕获失败" });
-            ws.close();
-        };
-        const change = async (next) => {
+        const changeLevel = async (next) => {
+            if (!live() || desired.paused || configuring || changing)
+                return;
             changing = true;
             lighter = next > level;
-            const to = rung(next);
-            this.log(`[screen] picture ${lighter ? "lighter" : "better"}: ${to.width} wide, ${to.fps} a second, ${Math.round(to.bitrate / 1000)} kbit/s`);
+            level = next;
             if (running?.change) {
-                // The capture carries on: the new level takes over at a keyframe, with nothing lost in between.
-                running.change(next);
-                level = next;
+                running.change(next, profileFor(next, desired));
                 pacer.changed(Date.now());
-                changing = false;
-                return;
             }
-            // Nothing more of the old stream goes out; the page starts its decoder afresh for the new one.
-            running?.end();
-            tell({ restart: true, level: next, lighter });
-            level = next;
-            await begin().catch(failed);
-            pacer.restarted(Date.now());
+            else {
+                stopRunning();
+                tell({ restart: true, level, lighter });
+                await begin(revision, shown, desired).catch(failure);
+                pacer.restarted(Date.now());
+            }
             changing = false;
         };
-        // The picture as a video track; down this socket when that can't be had, or didn't get across.
-        let video;
-        /** The viewer's answer and candidates, kept in the order they arrived (`resolvedCandidate`). */
-        let signals = Promise.resolve();
-        const endVideo = () => {
-            if (!video)
+        const current = (change) => live() && revision === change.revision;
+        const drain = async () => {
+            if (!initialized || configuring || !live())
                 return;
-            video.app.endVideo(video.id);
-            if (this.video?.id === video.id)
-                this.video = undefined;
-            video = undefined;
+            configuring = true;
+            try {
+                while (pending && live()) {
+                    const change = pending;
+                    pending = undefined;
+                    const configuration = change.configuration;
+                    try {
+                        if (!canConfigure && change.requestId !== undefined)
+                            throw new Error("电脑上的屏幕组件不支持保留连接，请重新连接");
+                        // A monitor may have been unplugged since screen.start listed it.
+                        const displays = await this.listDisplays();
+                        if (!current(change))
+                            continue;
+                        this.displays = displays;
+                        const target = displays.find((entry) => entry.index === configuration.display);
+                        if (!target)
+                            throw new Error("所选屏幕已不可用，请选择其他屏幕");
+                        let applied;
+                        if (video) {
+                            if (!video.reconfigure || !video.configure) {
+                                // Windows can pause its existing track, but target changes still reconnect.
+                                if (video.pause && change.requestId === undefined) {
+                                    video.pause(configuration.paused);
+                                    applied = { screen: target.screen, width: target.w ?? 0, height: target.h ?? 0, maxFps: configuration.maxFps ?? 60, paused: configuration.paused };
+                                }
+                                else {
+                                    if (configuration.paused) {
+                                        dispose();
+                                        ws.close();
+                                        return;
+                                    }
+                                    throw new Error("电脑上的屏幕组件不支持保留连接，请重新连接");
+                                }
+                            }
+                            else
+                                applied = await video.configure({
+                                    requestId: ++helperRequestId, screen: target.screen, maxWidth: configuration.width,
+                                    ...(configuration.maxFps === undefined ? {} : { maxFps: configuration.maxFps }), paused: configuration.paused,
+                                    ...(change.generation === undefined ? {} : { inputGeneration: change.generation }),
+                                });
+                            if (applied.screen !== target.screen || applied.paused !== configuration.paused || (change.generation !== undefined && applied.generation !== change.generation)) {
+                                throw new Error("电脑返回的屏幕设置无效，请重试");
+                            }
+                        }
+                        else {
+                            const profile = profileFor(level, configuration);
+                            let size = !target.w || !target.h ? { width: 0, height: 0 } : fallbackSize(target, profile);
+                            let fps = profile.fps;
+                            if ((!size.width || !size.height) && change.requestId !== undefined)
+                                throw new Error("无法读取当前屏幕尺寸，请重新连接");
+                            stopRunning();
+                            if (!configuration.paused) {
+                                wantsKey = true;
+                                pacer.restarted(Date.now());
+                                tell({ restart: true, level, lighter: false });
+                                const started = await begin(change.revision, target, configuration);
+                                if (started) {
+                                    size = started;
+                                    fps = started.maxFps;
+                                }
+                            }
+                            applied = { screen: target.screen, ...size, maxFps: fps, paused: configuration.paused, generation: change.generation };
+                        }
+                        if (!current(change))
+                            continue;
+                        shown = target;
+                        appliedGeneration = change.generation;
+                        if (!configuration.paused)
+                            await startControl(true);
+                        if (!current(change))
+                            continue;
+                        inputEnabled = !configuration.paused;
+                        if (!configuration.paused) {
+                            resumed();
+                            startReminder();
+                        }
+                        if (change.requestId !== undefined)
+                            tell({ session: {
+                                    t: "configured", requestId: change.requestId, display: target.index, width: applied.width, height: applied.height,
+                                    maxFps: applied.maxFps, paused: applied.paused,
+                                    ...(applied.generation === undefined ? {} : { generation: applied.generation }),
+                                } });
+                    }
+                    catch (error) {
+                        if (!current(change))
+                            continue;
+                        stopControl();
+                        if (!video)
+                            stopRunning();
+                        this.log(`[screen] configuration failed: ${String(error)}`);
+                        if (change.requestId !== undefined)
+                            tell({ session: { t: "error", requestId: change.requestId, message: "屏幕设置未能应用，请重试" } });
+                        else if (configuration.paused) {
+                            dispose();
+                            ws.close();
+                        }
+                    }
+                }
+            }
+            finally {
+                configuring = false;
+            }
         };
-        const fallBack = () => {
-            if (!video)
-                return;
+        const configure = (configuration, requestId) => {
+            desired = configuration;
+            if (requestId !== undefined) {
+                generationEnabled = true;
+                desiredRequestId = requestId;
+            }
+            const at = ++revision;
+            pending = { configuration, revision: at, requestId, ...(generationEnabled ? { generation: ++inputGeneration } : {}) };
+            stopControl();
+            if (configuration.paused) {
+                stopReminder();
+                stopRunning();
+                expirePaused();
+            }
+            void drain();
+        };
+        const startFallback = () => {
             endVideo();
-            if (closed)
+            if (!live())
                 return;
             tell({ rtc: { t: "off" } });
-            void begin().catch(failed);
+            canConfigure = !!shown?.w && !!shown?.h;
+            initialized = true;
+            capabilities();
+            if (pending || desiredRequestId !== undefined || desired.paused) {
+                configure(desired, desiredRequestId);
+            }
+            else {
+                const at = revision;
+                void begin(at, shown, desired).then(() => {
+                    if (live() && revision === at && !desired.paused) {
+                        inputEnabled = true;
+                        void startControl();
+                    }
+                }).catch(failure);
+            }
         };
-        if (wantsVideo) {
-            this.offerVideo(shown?.screen ?? 0, width, maxFps, diagnostics, codec, {
-                closed: () => closed,
-                tell,
-                refuse: (message) => {
-                    video = undefined;
-                    tell({ error: message });
-                    ws.close();
-                },
-                lost: fallBack,
-            })
-                .then((offered) => {
-                if (offered === "refused")
-                    return;
-                if (closed) {
-                    if (offered)
-                        offered.app.endVideo(offered.id);
-                    return;
-                }
-                if (offered)
-                    video = offered;
-                else {
-                    tell({ rtc: { t: "off" } });
-                    return begin();
-                }
-            })
-                .catch(failed);
-        }
-        else
-            void begin().catch(failed);
+        const fallBack = () => { if (video)
+            startFallback(); };
+        const dispose = () => {
+            if (closed)
+                return;
+            closed = true;
+            revision += 1;
+            pending = undefined;
+            stopReminder();
+            resumed();
+            stopRunning();
+            endVideo();
+            stopControl();
+            this.viewers.delete(ws);
+        };
+        this.viewers.set(ws, dispose);
+        ws.on("close", dispose);
         ws.on("message", (data, binary) => {
-            if (binary)
+            if (binary || !live())
                 return;
             let message;
             try {
@@ -639,77 +987,124 @@ export class ScreenShare {
                 return;
             }
             const kind = message?.t;
-            if (kind === "ack")
+            if (kind === "screen.configure") {
+                const parsed = screenConfiguration.safeParse(message);
+                if (!parsed.success || !this.displays.some((entry) => entry.index === parsed.data.display)) {
+                    const requestId = message.requestId;
+                    tell({ session: { t: "error", ...(typeof requestId === "number" && Number.isSafeInteger(requestId) && requestId >= 0 ? { requestId } : {}), message: "屏幕设置无效，请检查屏幕、分辨率和帧率" } });
+                    return;
+                }
+                if (parsed.data.requestId <= lastRequestId)
+                    return;
+                if (initialized && !canConfigure) {
+                    tell({ session: { t: "error", requestId: parsed.data.requestId, message: "电脑上的屏幕组件不支持保留连接，请重新连接" } });
+                    return;
+                }
+                lastRequestId = parsed.data.requestId;
+                const { t: _type, requestId, ...configuration } = parsed.data;
+                configure(configuration, requestId);
+            }
+            else if (kind === "hidden" || kind === "shown") {
+                const paused = kind === "hidden";
+                if (desired.paused !== paused)
+                    configure({ ...desired, paused });
+            }
+            else if (kind === "ack")
                 pacer.ack(Number(message.n), Date.now());
             else if (kind === "rtc.answer" || kind === "rtc.ice") {
                 const signal = videoSignal.safeParse(message);
                 if (!signal.success)
                     return;
-                // Resolving a name takes a moment, and the answer must still reach the app before the
-                // candidates that followed it: each signal waits for the one before.
-                signals = signals
-                    .then(async () => {
-                    const data = signal.data;
-                    if (!video)
+                signals = signals.then(async () => {
+                    const target = video;
+                    if (!target || !live())
                         return;
-                    video.app.signal(video.id, data.t === "rtc.ice" ? { ...data, candidate: await resolvedCandidate(data.candidate) } : data);
-                })
-                    // One signal that couldn't be passed on must not take the ones behind it with it.
-                    .catch(() => { });
+                    const data = signal.data;
+                    const resolved = data.t === "rtc.ice" ? { ...data, candidate: await resolvedCandidate(data.candidate) } : data;
+                    if (live() && video === target)
+                        target.signal(resolved);
+                }).catch(() => { });
             }
-            // The viewer's decoder lost its place (it skipped ahead, or failed): it can only carry on from a keyframe.
-            // (Named apart from the viewer's own events: whatever isn't one of these kinds is taken for a pointer or key event.)
             else if (kind === "keyframe") {
                 const now = Date.now();
-                if (running?.key && now - askedForKey >= 500) {
+                if (!desired.paused && !configuring && running?.key && now - askedForKey >= 500) {
                     askedForKey = now;
                     running.key();
                 }
             }
-            else if (kind === "hidden")
-                unwatched = true;
-            else if (kind === "shown") {
-                if (!unwatched)
-                    return;
-                unwatched = false;
-                wantsKey = true;
-                // What was on its way when the page went out of sight is not waited for.
-                pacer.restarted(Date.now());
-                running?.key?.();
-            }
-            // Why a viewer gave its track up: what ICE gathered and tried, for this log only.
             else if (kind === "rtc.diagnosis") {
                 const { reason, ice } = message;
                 this.log(`[screen] the video track was given up (${String(reason ?? "no reason").slice(0, 120)}): ${String(ice || "no ICE statistics").slice(0, 300)}`);
             }
-            // No direct path between the two, or none in time: the viewer asks for the picture here instead.
-            else if (kind === "rtc.failed") {
-                this.log(`[screen] no video track for this viewer (${String(message.reason ?? "no reason given").slice(0, 200)}): the picture goes down the socket`);
+            else if (kind === "rtc.failed")
                 fallBack();
-            }
-            // A viewer measuring (`?measure=1`): its clock against this computer's (it keeps the answer that came back
-            // quickest), then what it sees, once a second.
             else if (kind === "ping")
                 tell({ pong: { n: message.n, at: message.at, now: Date.now() } });
             else if (kind === "measure")
                 this.log(`[screen] measured: ${screenMeasurementLog(message)}`);
-            else if (kind === "control")
-                void control.start(shown?.screen ?? 0);
-            else
-                control.send(message);
-        });
-        ws.on("close", () => {
-            closed = true;
-            clearInterval(reminder);
-            if (running && this.holder === running)
-                this.holder = undefined;
-            running?.end();
-            endVideo();
-            control.stop();
-            this.controls.delete(control);
+            else if (kind === "control" && !desired.paused) {
+                // Requesting control only records intent. Input still needs the applied generation,
+                // and startup/configuration must finish before the helper can be joined.
+                controlRequested = true;
+                void startControl();
+            }
+            else if (!desired.paused && inputEnabled && (!generationEnabled || message?.screenGeneration === appliedGeneration)) {
+                control?.send(message);
+            }
         });
+        if (wantsVideo) {
+            let lostWhileOpening = false;
+            void this.offerVideo(shown?.screen ?? 0, width, maxFps, diagnostics, codec, {
+                closed: () => !live(), tell,
+                refuse: (message) => { tell({ error: message }); dispose(); ws.close(); },
+                lost: () => { if (video)
+                    fallBack();
+                else
+                    lostWhileOpening = true; },
+                input: message => {
+                    if (!live() || desired.paused || !inputEnabled)
+                        return;
+                    controlRequested = true;
+                    const at = revision;
+                    void startControl().then(() => { if (live() && revision === at && inputEnabled && !desired.paused)
+                        control?.send(message); });
+                },
+            }).then((offered) => {
+                if (offered === "refused")
+                    return;
+                if (!live()) {
+                    offered?.end();
+                    return;
+                }
+                if (!offered) {
+                    startFallback();
+                    return;
+                }
+                video = offered;
+                if (lostWhileOpening) {
+                    startFallback();
+                    return;
+                }
+                initialized = true;
+                canConfigure = offered.reconfigure === true;
+                capabilities();
+                if (pending)
+                    void drain();
+                else {
+                    inputEnabled = true;
+                    void startControl();
+                }
+            }).catch(failure);
+        }
+        else
+            startFallback();
     }
     stop() {
+        for (const [viewer, release] of this.viewers) {
+            release();
+            viewer.close(1000, "host stopped");
+        }
+        this.viewers.clear();
         // The host is going: there is no later to insist in.
         this.holder?.end();
         this.holder = undefined;