@rynx-ai/server 0.1.9 → 0.1.10-beta.3

package/dist/session-browser-surface-coordinator.js

@@ -1,16 +1,17 @@
-import { RUNTIME_BROWSER_SURFACE_MAX_CONTROL_FRAME_BYTES, RUNTIME_BROWSER_SURFACE_MAX_ENCODED_FRAME_BYTES, RUNTIME_BROWSER_SURFACE_FRAME_ACK_TIMEOUT_MS, RUNTIME_BROWSER_SURFACE_MAX_RELIABLE_INPUT_QUEUE, } from "@rynx-ai/protocol/runtime-browser-surface";
+import { RUNTIME_BROWSER_SURFACE_MAX_CONTROL_FRAME_BYTES, RUNTIME_BROWSER_SURFACE_MAX_ENCODED_FRAME_BYTES, RUNTIME_BROWSER_SURFACE_FRAME_ACK_TIMEOUT_MS, RUNTIME_BROWSER_SURFACE_MAX_RELIABLE_INPUT_QUEUE, RUNTIME_BROWSER_SURFACE_MAX_SUBSCRIBERS_PER_PAGE, } from "@rynx-ai/protocol/runtime-browser-surface";
 import { DirectRuntimeBrowserSurfaceHostError, } from "./direct-runtime-browser-surface-server.js";
 import { SessionBrowserHostError, SessionBrowserServiceError, SessionBrowserSurfaceUnsupportedError, } from "./session-browser-service.js";
 const DEFAULT_MAX_PENDING_EVENTS = 8;
 const DEFAULT_MAX_PENDING_EVENT_BYTES = RUNTIME_BROWSER_SURFACE_MAX_ENCODED_FRAME_BYTES +
     RUNTIME_BROWSER_SURFACE_MAX_CONTROL_FRAME_BYTES * DEFAULT_MAX_PENDING_EVENTS;
 /**
- * Owns the one-stream-per-Page lease, frame acknowledgement, and human-driver
- * rules above physical Browser capture. It never exposes a Host Page ID or CDP.
+ * Owns one physical capture stream per Page, fans it out to bounded logical
+ * subscribers, and arbitrates the single human-driver lease. It never exposes a
+ * Host Page ID or CDP.
  */
 export class SessionBrowserSurfaceCoordinator {
     browsers;
-    attachments = new Map();
+    pages = new Map();
     pageQueues = new Map();
     frameAcknowledgeTimeoutMs;
     maxPendingEvents;
@@ -44,43 +45,53 @@ export class SessionBrowserSurfaceCoordinator {
                 throw mapSurfaceOpenError(error);
             }
             context.signal.throwIfAborted();
-            const previous = this.attachments.get(pageKey);
-            if (previous)
-                await previous.replace();
-            let source;
-            try {
-                source = await this.browsers.openSurface({
-                    sessionId: frame.sessionId,
-                    browserGeneration: frame.browserGeneration,
-                    pageId: frame.pageId,
-                    format: frame.format,
-                    quality: frame.quality,
-                    maximumFrameRate: frame.maximumFrameRate,
-                    signal: context.signal,
-                });
+            let page = this.pages.get(pageKey);
+            if (page?.isClosing()) {
+                await page.closed();
+                page = undefined;
             }
-            catch (error) {
-                throw mapSurfaceOpenError(error);
+            if (page && page.browserGeneration !== frame.browserGeneration) {
+                await page.finish("generation_changed", "Browser generation changed", true);
+                page = undefined;
             }
-            if (context.signal.aborted) {
-                await source.close().catch(() => undefined);
-                throw new DirectRuntimeBrowserSurfaceHostError("cancelled", "Browser Surface open was cancelled");
+            if (!page) {
+                const sourceController = new AbortController();
+                let source;
+                try {
+                    source = await this.browsers.openSurface({
+                        sessionId: frame.sessionId,
+                        browserGeneration: frame.browserGeneration,
+                        pageId: frame.pageId,
+                        format: frame.format,
+                        quality: frame.quality,
+                        maximumFrameRate: frame.maximumFrameRate,
+                        signal: sourceController.signal,
+                    });
+                }
+                catch (error) {
+                    sourceController.abort();
+                    throw mapSurfaceOpenError(error);
+                }
+                if (context.signal.aborted) {
+                    sourceController.abort();
+                    await source.close().catch(() => undefined);
+                    throw new DirectRuntimeBrowserSurfaceHostError("cancelled", "Browser Surface open was cancelled");
+                }
+                page = new SharedPageSurface({
+                    source,
+                    sourceController,
+                    frameAcknowledgeTimeoutMs: this.frameAcknowledgeTimeoutMs,
+                    maxPendingEvents: this.maxPendingEvents,
+                    maxPendingEventBytes: this.maxPendingEventBytes,
+                    onClose: () => {
+                        if (this.pages.get(pageKey) === page)
+                            this.pages.delete(pageKey);
+                    },
+                });
+                this.pages.set(pageKey, page);
             }
-            let attachment;
-            attachment = new CoordinatedSurfaceAttachment({
-                open: frame,
-                source,
-                signal: context.signal,
-                frameAcknowledgeTimeoutMs: this.frameAcknowledgeTimeoutMs,
-                maxPendingEvents: this.maxPendingEvents,
-                maxPendingEventBytes: this.maxPendingEventBytes,
-                onClose: () => {
-                    if (this.attachments.get(pageKey) === attachment)
-                        this.attachments.delete(pageKey);
-                },
-            });
-            this.attachments.set(pageKey, attachment);
-            attachment.start();
+            const attachment = page.attach(frame, context.signal);
+            page.start();
             return attachment;
         });
     }
@@ -96,36 +107,296 @@ export class SessionBrowserSurfaceCoordinator {
         return result;
     }
 }
+class SharedPageSurface {
+    page;
+    browserGeneration;
+    subscribers = new Map();
+    restingDriver;
+    physicalDriver;
+    owner;
+    desiredOwner;
+    pendingInputCount = 0;
+    inputTail = Promise.resolve();
+    inputEpoch = 0;
+    acceptingInput = false;
+    inputResetRequired = false;
+    driverTransitionTail = Promise.resolve();
+    started = false;
+    closing = false;
+    closePromise;
+    constructor(page) {
+        this.page = page;
+        this.browserGeneration = page.source.browserGeneration;
+        this.restingDriver = page.source.setHumanDriver ? "desktop" : "none";
+        this.physicalDriver = this.restingDriver;
+    }
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        void this.pumpFrames();
+    }
+    isClosing() {
+        return this.closing;
+    }
+    closed() {
+        return this.closePromise ?? Promise.resolve();
+    }
+    attach(open, signal) {
+        if (this.closing) {
+            throw new DirectRuntimeBrowserSurfaceHostError("browser_closed", "Browser Surface is closing");
+        }
+        if (open.browserGeneration !== this.browserGeneration) {
+            throw new DirectRuntimeBrowserSurfaceHostError("generation_changed", "Browser generation changed");
+        }
+        if (open.format !== this.page.source.format) {
+            throw new DirectRuntimeBrowserSurfaceHostError("capacity", `Browser Surface Page is already streaming ${this.page.source.format}`);
+        }
+        if (this.subscribers.size >= RUNTIME_BROWSER_SURFACE_MAX_SUBSCRIBERS_PER_PAGE) {
+            throw new DirectRuntimeBrowserSurfaceHostError("capacity", "Browser Surface Page reached its Preview limit");
+        }
+        if (this.subscribers.has(open.subscriptionId)) {
+            throw new DirectRuntimeBrowserSurfaceHostError("protocol_error", "Browser Surface subscription already exists");
+        }
+        const attachment = new CoordinatedSurfaceAttachment({
+            open,
+            page: this,
+            signal,
+            frameAcknowledgeTimeoutMs: this.page.frameAcknowledgeTimeoutMs,
+            maxPendingEvents: this.page.maxPendingEvents,
+            maxPendingEventBytes: this.page.maxPendingEventBytes,
+        });
+        this.subscribers.set(open.subscriptionId, attachment);
+        attachment.start();
+        return attachment;
+    }
+    getViewport() {
+        return this.page.source.getViewport();
+    }
+    driverState() {
+        return this.owner
+            ? { driver: "stream", driverSubscriptionId: this.owner.subscriptionId }
+            : { driver: this.restingDriver };
+    }
+    async pumpFrames() {
+        try {
+            for await (const frame of this.page.source.frames) {
+                if (this.closing) {
+                    await frame.acknowledge();
+                    return;
+                }
+                if (frame.browserGeneration !== this.browserGeneration) {
+                    await frame.acknowledge();
+                    await this.finish("generation_changed", "Browser generation changed", true);
+                    return;
+                }
+                if (frame.format !== this.page.source.format) {
+                    await frame.acknowledge();
+                    throw new Error("Browser Host changed the Surface image format");
+                }
+                for (const subscriber of [...this.subscribers.values()]) {
+                    subscriber.offerFrame(frame);
+                }
+                await frame.acknowledge();
+                if (this.closing)
+                    return;
+            }
+            if (!this.closing) {
+                await this.finish("browser_closed", "Browser Surface source ended", true);
+            }
+        }
+        catch (error) {
+            if (!this.closing) {
+                const mapped = mapSurfaceHostError(error, "Browser Surface source failed");
+                await this.finish(mapped.reason, mapped.message, true);
+            }
+        }
+    }
+    takeDriver(attachment) {
+        if (this.closing || !this.subscribers.has(attachment.subscriptionId))
+            return Promise.resolve();
+        if (this.desiredOwner === attachment && this.owner === attachment && this.acceptingInput) {
+            return Promise.resolve();
+        }
+        if (this.owner !== attachment) {
+            this.fenceInput();
+            if (this.owner)
+                this.inputResetRequired = true;
+        }
+        this.desiredOwner = attachment;
+        return this.enqueueDriverTransition(() => this.reconcileDriver()).catch((error) => {
+            throw mapSurfaceHostError(error, "Browser Surface driver handoff failed");
+        });
+    }
+    releaseDriver(attachment) {
+        if (this.desiredOwner !== attachment && this.owner !== attachment)
+            return Promise.resolve();
+        this.fenceInput();
+        this.inputResetRequired = true;
+        if (this.desiredOwner === attachment)
+            this.desiredOwner = undefined;
+        return this.enqueueDriverTransition(() => this.reconcileDriver()).catch((error) => {
+            throw mapSurfaceHostError(error, "Browser Surface driver release failed");
+        });
+    }
+    async dispatchInput(attachment, frame) {
+        if (this.owner !== attachment ||
+            !this.acceptingInput ||
+            !this.subscribers.has(attachment.subscriptionId)) {
+            throw new DirectRuntimeBrowserSurfaceHostError("unauthorized", "Browser Surface does not own the human driver");
+        }
+        if (this.pendingInputCount >= RUNTIME_BROWSER_SURFACE_MAX_RELIABLE_INPUT_QUEUE) {
+            throw new DirectRuntimeBrowserSurfaceHostError("capacity", "Browser Surface input queue is full");
+        }
+        this.pendingInputCount += 1;
+        const inputEpoch = this.inputEpoch;
+        try {
+            const operation = this.inputTail.then(async () => {
+                if (this.closing ||
+                    !this.acceptingInput ||
+                    this.owner !== attachment ||
+                    inputEpoch !== this.inputEpoch)
+                    return;
+                await this.page.source.dispatchTrustedInput({
+                    browserGeneration: frame.browserGeneration,
+                    viewportRevision: frame.viewportRevision,
+                    event: frame.event,
+                });
+            });
+            this.inputTail = operation.then(() => undefined, () => undefined);
+            await operation;
+        }
+        catch (error) {
+            throw mapSurfaceHostError(error, "Browser Surface input failed");
+        }
+        finally {
+            this.pendingInputCount -= 1;
+        }
+    }
+    detach(attachment) {
+        if (this.subscribers.get(attachment.subscriptionId) !== attachment) {
+            return Promise.resolve();
+        }
+        this.subscribers.delete(attachment.subscriptionId);
+        if (this.owner === attachment || this.desiredOwner === attachment) {
+            this.fenceInput();
+            this.inputResetRequired = true;
+            if (this.desiredOwner === attachment)
+                this.desiredOwner = undefined;
+        }
+        if (this.subscribers.size === 0) {
+            return this.finish("cancelled", undefined, false);
+        }
+        return this.enqueueDriverTransition(() => this.reconcileDriver()).catch(() => undefined);
+    }
+    async reconcileDriver() {
+        await this.inputTail;
+        if (this.inputResetRequired) {
+            await this.page.source.resetTrustedInput?.();
+            this.inputResetRequired = false;
+        }
+        const desired = this.desiredOwner &&
+            this.subscribers.get(this.desiredOwner.subscriptionId) === this.desiredOwner
+            ? this.desiredOwner
+            : undefined;
+        const targetDriver = desired ? "stream" : this.restingDriver;
+        if (this.physicalDriver !== targetDriver) {
+            await this.page.source.setHumanDriver?.(targetDriver === "stream" ? "stream" : "desktop");
+            this.physicalDriver = targetDriver;
+        }
+        const currentDesired = this.desiredOwner &&
+            this.subscribers.get(this.desiredOwner.subscriptionId) === this.desiredOwner
+            ? this.desiredOwner
+            : undefined;
+        if (currentDesired !== desired || this.closing)
+            return;
+        const changed = this.owner !== desired;
+        this.owner = desired;
+        this.inputEpoch += 1;
+        this.acceptingInput = desired !== undefined;
+        if (changed)
+            this.broadcastDriverChanged();
+    }
+    enqueueDriverTransition(operation) {
+        const result = this.driverTransitionTail.then(operation, operation);
+        this.driverTransitionTail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    fenceInput() {
+        this.acceptingInput = false;
+        this.inputEpoch += 1;
+    }
+    broadcastDriverChanged() {
+        const state = this.driverState();
+        for (const subscriber of [...this.subscribers.values()]) {
+            subscriber.emitDriverChanged(state);
+        }
+    }
+    finish(reason, message, notify) {
+        if (this.closePromise)
+            return this.closePromise;
+        this.closing = true;
+        this.fenceInput();
+        if (this.owner || this.desiredOwner || this.physicalDriver === "stream") {
+            this.inputResetRequired = true;
+        }
+        this.desiredOwner = undefined;
+        for (const subscriber of [...this.subscribers.values()]) {
+            subscriber.finishFromPage(reason, message, notify);
+        }
+        this.subscribers.clear();
+        this.page.sourceController.abort();
+        const releaseDriver = this.enqueueDriverTransition(async () => {
+            await this.inputTail;
+            try {
+                if (this.inputResetRequired)
+                    await this.page.source.resetTrustedInput?.();
+                this.inputResetRequired = false;
+            }
+            catch {
+                // Closing remains fail-safe: capture must still be released if the
+                // renderer no longer accepts synthesized key/button releases.
+            }
+            if (this.physicalDriver !== this.restingDriver) {
+                try {
+                    await this.page.source.setHumanDriver?.("desktop");
+                    this.physicalDriver = this.restingDriver;
+                }
+                catch {
+                    // Closing remains fail-safe: capture is released even if Host handoff fails.
+                }
+            }
+            this.owner = undefined;
+        });
+        this.closePromise = releaseDriver.then(() => this.page.source.close())
+            .catch(() => undefined)
+            .finally(this.page.onClose);
+        return this.closePromise;
+    }
+}
 class CoordinatedSurfaceAttachment {
     attachment;
     ready;
     events;
+    subscriptionId;
     eventQueue;
     abortHandler;
     frameSequence = 0;
     lastInputSequence = -1;
-    pendingInputCount = 0;
-    inputTail = Promise.resolve();
-    inputEpoch = 0;
-    acceptingInput = false;
-    inputResetRequired = false;
     pendingFrame;
-    driver;
-    physicalDriver;
-    driverIntent = 0;
-    driverTransitionTail = Promise.resolve();
     closing = false;
     closePromise;
     constructor(attachment) {
         this.attachment = attachment;
+        this.subscriptionId = attachment.open.subscriptionId;
         this.eventQueue = new SurfaceEventQueue({
             maxPendingEvents: attachment.maxPendingEvents,
             maxPendingBytes: attachment.maxPendingEventBytes,
         });
-        const viewport = attachment.source.getViewport();
+        const viewport = attachment.page.getViewport();
         this.ready = {
             type: "browser.surface.ready",
-            subscriptionId: attachment.open.subscriptionId,
+            subscriptionId: this.subscriptionId,
             browserGeneration: attachment.open.browserGeneration,
             viewportRevision: viewport.revision,
             sourceWidth: viewport.width,
@@ -134,8 +405,6 @@ class CoordinatedSurfaceAttachment {
             format: attachment.open.format,
             grantedRole: attachment.open.requestedRole,
         };
-        this.driver = attachment.source.setHumanDriver ? "desktop" : "none";
-        this.physicalDriver = this.driver;
         this.events = this.eventQueue;
         this.abortHandler = () => {
             void this.finish("cancelled", "Browser Surface connection was cancelled", true);
@@ -143,20 +412,12 @@ class CoordinatedSurfaceAttachment {
         attachment.signal.addEventListener("abort", this.abortHandler, { once: true });
     }
     start() {
-        try {
-            this.emitDriverChanged();
-        }
-        catch (error) {
-            const mapped = mapSurfaceHostError(error, "Browser Surface event queue is full");
-            void this.finish(mapped.reason, mapped.message, true);
-            return;
-        }
-        void this.pumpFrames();
+        this.emitDriverChanged(this.attachment.page.driverState());
     }
     async handle(frame) {
         if (this.closing)
             return;
-        if (frame.subscriptionId !== this.attachment.open.subscriptionId) {
+        if (frame.subscriptionId !== this.subscriptionId) {
             throw new DirectRuntimeBrowserSurfaceHostError("protocol_error", "Browser Surface subscription does not match");
         }
         switch (frame.type) {
@@ -168,120 +429,71 @@ class CoordinatedSurfaceAttachment {
                 this.requireControlRole();
                 if (!this.matchesViewport(frame.viewportRevision))
                     return;
-                await this.takeDriver();
+                await this.attachment.page.takeDriver(this);
                 return;
             case "browser.surface.driver.release":
                 this.requireGeneration(frame.browserGeneration);
-                await this.releaseDriver();
+                await this.attachment.page.releaseDriver(this);
                 return;
             case "browser.surface.input":
                 this.requireGeneration(frame.browserGeneration);
                 this.requireControlRole();
-                if (this.driver !== "stream" || !this.acceptingInput) {
-                    throw new DirectRuntimeBrowserSurfaceHostError("unauthorized", "Browser Surface does not own the human driver");
-                }
                 if (!this.matchesViewport(frame.viewportRevision))
                     return;
                 if (frame.inputSequence <= this.lastInputSequence) {
                     throw new DirectRuntimeBrowserSurfaceHostError("protocol_error", "Browser Surface input sequence must increase");
                 }
-                if (this.pendingInputCount >= RUNTIME_BROWSER_SURFACE_MAX_RELIABLE_INPUT_QUEUE) {
-                    throw new DirectRuntimeBrowserSurfaceHostError("capacity", "Browser Surface input queue is full");
-                }
                 this.lastInputSequence = frame.inputSequence;
-                this.pendingInputCount += 1;
-                const inputEpoch = this.inputEpoch;
-                try {
-                    const operation = this.inputTail.then(async () => {
-                        if (this.closing ||
-                            !this.acceptingInput ||
-                            this.driver !== "stream" ||
-                            inputEpoch !== this.inputEpoch)
-                            return;
-                        await this.attachment.source.dispatchTrustedInput({
-                            browserGeneration: frame.browserGeneration,
-                            viewportRevision: frame.viewportRevision,
-                            event: frame.event,
-                        });
-                    });
-                    this.inputTail = operation.then(() => undefined, () => undefined);
-                    await operation;
-                }
-                catch (error) {
-                    throw mapSurfaceHostError(error, "Browser Surface input failed");
-                }
-                finally {
-                    this.pendingInputCount -= 1;
-                }
+                await this.attachment.page.dispatchInput(this, frame);
         }
     }
     close(_reason) {
         return this.finish("cancelled", undefined, false);
     }
-    replace() {
-        return this.finish("replaced", "Browser Surface was opened elsewhere", true);
-    }
-    async pumpFrames() {
-        try {
-            for await (const frame of this.attachment.source.frames) {
-                if (this.closing) {
-                    await frame.acknowledge();
-                    return;
-                }
-                if (frame.browserGeneration !== this.attachment.open.browserGeneration) {
-                    await frame.acknowledge();
-                    await this.finish("generation_changed", "Browser generation changed", true);
-                    return;
-                }
-                if (frame.format !== this.attachment.open.format) {
-                    await frame.acknowledge();
-                    throw new Error("Browser Host changed the Surface image format");
-                }
-                const sequence = ++this.frameSequence;
-                const released = new Promise((resolve) => {
-                    const timer = setTimeout(() => {
-                        void this.finish("idle_timeout", "Browser Surface frame was not acknowledged", true);
-                    }, this.attachment.frameAcknowledgeTimeoutMs);
-                    timer.unref?.();
-                    this.pendingFrame = { sequence, release: resolve, timer };
-                });
-                const image = {
-                    subscriptionId: this.attachment.open.subscriptionId,
-                    frameSequence: sequence,
-                    viewportRevision: frame.viewportRevision,
-                    timestampMilliseconds: frame.timestampMilliseconds,
-                    width: frame.width,
-                    height: frame.height,
-                    format: frame.format,
-                    encodedBytes: frame.encodedBytes,
-                };
-                if (!this.eventQueue.push(image)) {
-                    const pending = this.pendingFrame;
-                    this.pendingFrame = undefined;
-                    if (pending) {
-                        clearTimeout(pending.timer);
-                        pending.release();
-                    }
-                    await frame.acknowledge();
-                    await this.finish("capacity", "Browser Surface event queue is full", true);
-                    return;
-                }
-                await released;
-                await frame.acknowledge();
-                if (this.closing)
-                    return;
-            }
-            if (!this.closing) {
-                await this.finish("browser_closed", "Browser Surface source ended", true);
-            }
+    offerFrame(frame) {
+        if (this.closing || this.pendingFrame)
+            return;
+        const sequence = ++this.frameSequence;
+        const timer = setTimeout(() => {
+            void this.finish("idle_timeout", "Browser Surface frame was not acknowledged", true);
+        }, this.attachment.frameAcknowledgeTimeoutMs);
+        timer.unref?.();
+        this.pendingFrame = { sequence, timer };
+        const image = {
+            subscriptionId: this.subscriptionId,
+            frameSequence: sequence,
+            viewportRevision: frame.viewportRevision,
+            timestampMilliseconds: frame.timestampMilliseconds,
+            width: frame.width,
+            height: frame.height,
+            format: frame.format,
+            encodedBytes: frame.encodedBytes,
+        };
+        if (!this.eventQueue.push(image)) {
+            clearTimeout(timer);
+            this.pendingFrame = undefined;
+            void this.finish("capacity", "Browser Surface event queue is full", true);
         }
-        catch (error) {
-            if (!this.closing) {
-                const mapped = mapSurfaceHostError(error, "Browser Surface source failed");
-                await this.finish(mapped.reason, mapped.message, true);
-            }
+    }
+    emitDriverChanged(state) {
+        if (this.closing)
+            return;
+        const event = {
+            type: "browser.surface.driver.changed",
+            subscriptionId: this.subscriptionId,
+            browserGeneration: this.ready.browserGeneration,
+            driver: state.driver,
+            ...(state.driverSubscriptionId === undefined
+                ? {}
+                : { driverSubscriptionId: state.driverSubscriptionId }),
+        };
+        if (!this.eventQueue.push(event)) {
+            void this.finish("capacity", "Browser Surface event queue is full", true);
         }
     }
+    finishFromPage(reason, message, notify) {
+        void this.finish(reason, message, notify, false);
+    }
     acknowledgeFrame(sequence) {
         const pending = this.pendingFrame;
         if (!pending || pending.sequence !== sequence) {
@@ -289,146 +501,40 @@ class CoordinatedSurfaceAttachment {
         }
         clearTimeout(pending.timer);
         this.pendingFrame = undefined;
-        pending.release();
     }
     requireGeneration(generation) {
-        if (generation !== this.attachment.open.browserGeneration) {
+        if (generation !== this.ready.browserGeneration) {
             throw new DirectRuntimeBrowserSurfaceHostError("generation_changed", "Browser generation changed");
         }
     }
     matchesViewport(revision) {
-        return revision === this.attachment.source.getViewport().revision;
+        return revision === this.attachment.page.getViewport().revision;
     }
     requireControlRole() {
         if (this.ready.grantedRole !== "control") {
             throw new DirectRuntimeBrowserSurfaceHostError("unauthorized", "Browser Surface is view-only");
         }
     }
-    emitDriverChanged() {
-        const event = {
-            type: "browser.surface.driver.changed",
-            subscriptionId: this.attachment.open.subscriptionId,
-            browserGeneration: this.attachment.open.browserGeneration,
-            driver: this.driver,
-            ...(this.driver === "stream"
-                ? { driverSubscriptionId: this.attachment.open.subscriptionId }
-                : {}),
-        };
-        if (!this.eventQueue.push(event)) {
-            throw new DirectRuntimeBrowserSurfaceHostError("capacity", "Browser Surface event queue is full");
-        }
-    }
-    takeDriver() {
-        const intent = ++this.driverIntent;
-        const operation = this.enqueueDriverTransition(async () => {
-            if (this.closing || intent !== this.driverIntent)
-                return;
-            if (this.inputResetRequired) {
-                await this.inputTail;
-                await this.attachment.source.resetTrustedInput?.();
-                this.inputResetRequired = false;
-            }
-            if (this.closing || intent !== this.driverIntent)
-                return;
-            if (this.physicalDriver !== "stream") {
-                await this.attachment.source.setHumanDriver?.("stream");
-                this.physicalDriver = "stream";
-            }
-            if (this.closing || intent !== this.driverIntent)
-                return;
-            const changed = this.driver !== "stream";
-            this.inputEpoch += 1;
-            this.acceptingInput = true;
-            this.driver = "stream";
-            if (changed)
-                this.emitDriverChanged();
-        });
-        return operation.catch((error) => {
-            throw mapSurfaceHostError(error, "Browser Surface driver handoff failed");
-        });
-    }
-    releaseDriver() {
-        this.fenceInput();
-        this.inputResetRequired = true;
-        const intent = ++this.driverIntent;
-        const operation = this.enqueueDriverTransition(async () => {
-            await this.inputTail;
-            await this.attachment.source.resetTrustedInput?.();
-            this.inputResetRequired = false;
-            if (this.closing || intent !== this.driverIntent)
-                return;
-            const restingDriver = this.attachment.source.setHumanDriver ? "desktop" : "none";
-            if (this.physicalDriver !== restingDriver) {
-                await this.attachment.source.setHumanDriver?.("desktop");
-                this.physicalDriver = restingDriver;
-            }
-            if (this.closing || intent !== this.driverIntent)
-                return;
-            const changed = this.driver !== restingDriver;
-            this.driver = restingDriver;
-            if (changed)
-                this.emitDriverChanged();
-        });
-        return operation.catch((error) => {
-            throw mapSurfaceHostError(error, "Browser Surface driver release failed");
-        });
-    }
-    enqueueDriverTransition(operation) {
-        const result = this.driverTransitionTail.then(operation, operation);
-        this.driverTransitionTail = result.then(() => undefined, () => undefined);
-        return result;
-    }
-    fenceInput() {
-        this.acceptingInput = false;
-        this.inputEpoch += 1;
-    }
-    finish(reason, message, notify) {
+    finish(reason, message, notify, detach = true) {
         if (this.closePromise)
             return this.closePromise;
         this.closing = true;
-        this.fenceInput();
-        this.inputResetRequired = true;
-        this.driverIntent += 1;
         this.attachment.signal.removeEventListener("abort", this.abortHandler);
         const pending = this.pendingFrame;
         this.pendingFrame = undefined;
-        if (pending) {
+        if (pending)
             clearTimeout(pending.timer);
-            pending.release();
-        }
         this.eventQueue.close(notify
             ? {
                 type: "browser.surface.closed",
-                subscriptionId: this.attachment.open.subscriptionId,
+                subscriptionId: this.subscriptionId,
                 reason,
                 ...(message === undefined ? {} : { message: message.slice(0, 1_024) }),
             }
             : undefined);
-        const restingDriver = this.attachment.source.setHumanDriver ? "desktop" : "none";
-        const releaseDriver = this.enqueueDriverTransition(async () => {
-            await this.inputTail;
-            try {
-                await this.attachment.source.resetTrustedInput?.();
-                this.inputResetRequired = false;
-            }
-            catch {
-                // Closing remains fail-safe: capture must still be released if the
-                // renderer no longer accepts synthesized key/button releases.
-            }
-            if (this.physicalDriver !== restingDriver) {
-                try {
-                    await this.attachment.source.setHumanDriver?.("desktop");
-                    this.physicalDriver = restingDriver;
-                }
-                catch {
-                    // Closing remains fail-safe: capture is released even if Host handoff fails.
-                }
-            }
-            this.driver = restingDriver;
-        });
-        this.closePromise = releaseDriver.then(() => this.attachment.source.close())
-            .catch(() => undefined)
-            .finally(this.attachment.onClose);
+        this.closePromise = detach
+            ? this.attachment.page.detach(this)
+            : Promise.resolve();
         return this.closePromise;
     }
 }