@platless/axom-cli 0.5.9 → 0.6.36

package/dist/workstation/desktopControl/nativeProvider.js

@@ -0,0 +1,1018 @@
+import { promises as fs, constants } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { z } from 'zod';
+import { HelperProcess, DesktopQueue, NativeCommandError, bounded } from './helperProcess.js';
+import { DesktopMediaStream, decodeMedia, desktopMediaLane, mediaRequire } from './media.js';
+import { canonicalDesktopJson, decodeCapabilityReport, decodeDesktopControl, supportsDesktopMode, captureRegion } from './protocol.js';
+import { captureSamplingModes } from './captureModes.js';
+import { captureTargetLabel } from './captureTargetLabel.js';
+import { XfceWallpaperReader, decodeWallpaper } from './wallpaper.js';
+const execute = promisify(execFile);
+const totals = ['captured', 'encoded', 'videoPayloadBytes', 'headerBytes', 'rateReopens'];
+class ViewerLifetime {
+    epoch = 0;
+    nextFrameId = 1;
+    controlGeneration = 0;
+    deviceGeneration = '';
+    inputSequence = 0;
+    lastAppliedInputSequence = 0;
+    text = new Map();
+    pendingText;
+    initialReservoirBits = 1_000_000;
+    appliedTargetBps = 4_000_000;
+    appliedFps = 30;
+    prepared = false;
+    transportDebtBits = 0;
+    transportCosts = new Map();
+    offsets = { captured: 0, encoded: 0, videoPayloadBytes: 0, headerBytes: 0, rateReopens: 0 };
+    session;
+    touched = performance.now();
+    reserve() {
+        mediaRequire(this.epoch < 0xffffffff && Number.isSafeInteger(this.nextFrameId + 1_000_000));
+        const nextFrameId = this.nextFrameId;
+        this.nextFrameId += 1_000_000;
+        return { epoch: ++this.epoch, nextFrameId, frameIdLimit: this.nextFrameId - 1 };
+    }
+    bind(binding) {
+        if (this.controlGeneration !== binding.controlGeneration || this.deviceGeneration !== binding.deviceGeneration) {
+            this.controlGeneration = binding.controlGeneration;
+            this.deviceGeneration = binding.deviceGeneration;
+            this.inputSequence = 0;
+            this.lastAppliedInputSequence = 0;
+            this.text.clear();
+            this.pendingText = undefined;
+        }
+    }
+}
+/** No helper/session construction in discovery. Only the image's admitted software is offered. */
+export class NativeProvider {
+    options;
+    lifetimes = new Map();
+    revision = 1;
+    geometry;
+    geometryTail = Promise.resolve();
+    geometryJobs = 0;
+    displayId;
+    factory;
+    windowRevisions = new Map();
+    executable;
+    constructor(options) {
+        this.options = options;
+        mediaRequire(path.isAbsolute(options.helperPath) && path.isAbsolute(options.runtimeDir));
+        this.displayId = '00000000000000000000000000000001';
+        this.executable = options.helperPath;
+        this.factory = options.helperFactory ?? (binding => HelperProcess.launch(this.executable, { ...this.environment,
+            ...(binding ? { AXOM_KEEPER_TARGET: binding.displayId } : {}) }));
+    }
+    get environment() {
+        return this.options.environment ?? { ...process.env, XDG_RUNTIME_DIR: this.options.runtimeDir };
+    }
+    get displayControl() {
+        const executable = this.environment.AXOM_DESKTOP_DISPLAY_CONTROL ?? '/usr/local/bin/axom-display';
+        mediaRequire(path.isAbsolute(executable));
+        return executable;
+    }
+    async readBounded(file, limit = 49152) {
+        const handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const info = await handle.stat();
+            mediaRequire(info.isFile() && info.size <= limit);
+            const bytes = Buffer.alloc(limit + 1);
+            const read = await handle.read(bytes, 0, limit + 1, 0);
+            mediaRequire(read.bytesRead <= limit);
+            return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, read.bytesRead)));
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    withGeometry(run) {
+        mediaRequire(this.geometryJobs < 16);
+        this.geometryJobs++;
+        const next = this.geometryTail.then(run);
+        this.geometryTail = next.catch(() => { }).finally(() => { this.geometryJobs--; });
+        return next;
+    }
+    probe() { return this.withGeometry(() => this.probeCurrent()); }
+    async wallpaper(targetId) {
+        mediaRequire(/^[a-f0-9]{32}$/.test(targetId));
+        const capabilities = await this.probe();
+        mediaRequire(capabilities?.displays.some(display => display.id === targetId));
+        const reader = new XfceWallpaperReader(async (command, args) => {
+            const result = await execute(command, args, { timeout: 1500, maxBuffer: 49152,
+                env: this.environment });
+            return result.stdout;
+        });
+        const discovered = await reader.discover();
+        const result = await execute(this.executable, ['--wallpaper-asset', discovered.file, discovered.background], { timeout: 4000, maxBuffer: 100000, env: this.environment });
+        const wallpaper = decodeWallpaper(result.stdout);
+        return { asset: { ...wallpaper.asset, placement: discovered.placement,
+                background: discovered.background, fidelity: discovered.fidelity === 'approximate' ? 'approximate' : wallpaper.asset.fidelity }, jpeg: wallpaper.jpeg };
+    }
+    async probeCurrent() {
+        if (this.options.enumerate)
+            return this.options.enumerate();
+        const c = decodeCapabilityReport(JSON.stringify({ generation: 'local', revision: 1,
+            desktop: await this.readBounded(this.options.manifestPath ?? '/opt/axom-desktop/provider.json') })).desktop;
+        mediaRequire(c && c.encoderBackends.length === 1 && c.encoderBackends[0].id === 'libx264' && c.encoderBackends[0].kind === 'software');
+        await fs.access(this.executable, constants.X_OK);
+        const identity = z.strictObject({ continuationAbi: z.literal(1), helperSha256: z.string().regex(/^[a-f0-9]{64}$/) }).parse(await this.readBounded(path.join(path.dirname(this.options.manifestPath ?? '/opt/axom-desktop/provider.json'), 'provider-identity.json'), 1024));
+        const binary = await fs.open(this.executable, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const info = await binary.stat();
+            mediaRequire(info.isFile() && info.size <= 32 * 1024 * 1024);
+            const hash = createHash('sha256');
+            for await (const bytes of binary.createReadStream({ autoClose: false }))
+                hash.update(bytes);
+            mediaRequire(hash.digest('hex') === identity.helperSha256);
+        }
+        finally {
+            await binary.close();
+        }
+        await fs.access(this.environment.XAUTHORITY ?? '/run/axom-desktop/Xauthority', constants.R_OK);
+        const runtime = await fs.stat(this.options.runtimeDir);
+        mediaRequire(runtime.isDirectory() && runtime.uid === process.getuid?.() && !(runtime.mode & 0o022));
+        const geometry = z.object({ width: z.number().int().min(2).max(4096), height: z.number().int().min(2).max(4096),
+            dpi: z.number().int().min(64).max(384).optional() }).parse(await this.readBounded(path.join(this.options.runtimeDir, 'geometry.json'), 1024));
+        if (c.displays[0].maxDpi !== undefined)
+            mediaRequire(geometry.dpi !== undefined && geometry.dpi <= c.displays[0].maxDpi);
+        if (this.geometry && (geometry.width !== this.geometry.width || geometry.height !== this.geometry.height || geometry.dpi !== this.geometry.dpi))
+            this.nextRevision();
+        this.geometry = geometry;
+        let failed = false;
+        for (const name of ['display-failed', 'input-failed']) {
+            try {
+                await fs.lstat(path.join(this.options.runtimeDir, name));
+                failed = true;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        const root = c.displays[0];
+        const sampling = root.captureViewport === true ? { capturePixelScale: 1, resize: 'dynamic',
+            resizeRange: { minWidth: 2, minHeight: 2, maxWidth: geometry.width, maxHeight: geometry.height },
+            modes: captureSamplingModes(geometry.width, geometry.height) } : {};
+        const displays = [{ ...root, id: this.displayId, ...geometry, ...sampling, revision: this.revision }];
+        if (c.providerVersion === 'axom-linux-2' && !failed) {
+            const { stdout } = await execute(this.executable, ['--capture-targets'], { env: this.environment, timeout: 2500, maxBuffer: 49152 });
+            const axis = z.number().int().min(2).max(4096);
+            const targets = z.array(z.strictObject({ id: z.string().regex(/^[0-9a-f]{32}$/), kind: z.literal('window'), label: z.string().max(4096), width: axis, height: axis })).max(127).parse(JSON.parse(stdout));
+            for (const target of targets) {
+                const old = this.windowRevisions.get(target.id);
+                const revision = old ? old.revision + Number(old.width !== target.width || old.height !== target.height) : 1;
+                this.windowRevisions.set(target.id, { width: target.width, height: target.height, revision });
+                displays.push({ ...target, label: captureTargetLabel(target.label), revision, resize: 'dynamic', captureViewport: true, capturePixelScale: 1, ...(root.overview ? { overview: true } : {}),
+                    resizeRange: { minWidth: 2, minHeight: 2, maxWidth: target.width & ~1, maxHeight: target.height & ~1 }, modes: captureSamplingModes(target.width, target.height) });
+            }
+            const live = new Set(targets.map(t => t.id));
+            for (const key of this.windowRevisions.keys())
+                if (!live.has(key))
+                    this.windowRevisions.delete(key);
+        }
+        return { ...c, cursorEmbedded: false, health: failed ? 'unavailable' : 'ready', reason: failed ? 'recovery_unverified' : null, displays };
+    }
+    nextRevision() { mediaRequire(this.revision < 0xffffffff); return ++this.revision; }
+    /** Publish dimensions and revision only after the native transaction verifies them. */
+    geometryTransaction(run, sampling = false) {
+        return this.withGeometry(async () => {
+            mediaRequire(this.revision < 0xffffffff);
+            const revision = this.revision + 1, actual = await run(revision);
+            mediaRequire(Number.isSafeInteger(actual.displayRevision) && actual.displayRevision >= revision && actual.displayRevision <= 0xffffffff);
+            if (!sampling)
+                this.geometry = { width: actual.width, height: actual.height, ...(actual.dpi === undefined ? {} : { dpi: actual.dpi }) };
+            else if (this.geometry && actual.dpi !== undefined)
+                this.geometry = { ...this.geometry, dpi: actual.dpi };
+            this.revision = actual.displayRevision;
+            return actual;
+        });
+    }
+    async prepare(selection, binding) {
+        await this.options.validateSession?.();
+        const caps = await this.probe();
+        mediaRequire(caps?.health === 'ready' && ['granted', 'not_applicable'].includes(caps.permission));
+        if (selection.cursorVisible !== undefined)
+            mediaRequire(caps.cursorVisibility === true);
+        const display = caps.displays.find(d => d.id === binding.displayId);
+        mediaRequire(display);
+        // Capture sampling keeps the physical source geometry independent of the
+        // encoded output size. Physical-resolution sessions use their configured grid.
+        const effectiveRegion = selection.captureRegion ?? (display.captureViewport === true ? {
+            x: 0, y: 0, width: display.width, height: display.height,
+            sourceWidth: display.width, sourceHeight: display.height,
+        } : undefined);
+        if (selection.captureRegion !== undefined) {
+            const region = captureRegion.parse(selection.captureRegion);
+            mediaRequire(display.captureViewport === true && region.sourceWidth === display.width && region.sourceHeight === display.height);
+        }
+        if (selection.dpi !== undefined)
+            mediaRequire(display.maxDpi !== undefined && selection.dpi <= display.maxDpi);
+        const format = caps.encoderBackends.find(b => b.id === (this.options.backend ?? 'libx264'))?.formats.find(f => f.format === selection.format && f.cappedRate);
+        mediaRequire(format && selection.width <= format.maxWidth && selection.height <= format.maxHeight &&
+            selection.width * selection.height <= format.maxPixels && selection.fpsCeiling <= format.maxFps &&
+            supportsDesktopMode(display, selection.width, selection.height));
+        for (const [id, life] of this.lifetimes)
+            if (!life.session && performance.now() - life.touched > 60000)
+                this.lifetimes.delete(id);
+        let life = this.lifetimes.get(binding.sessionId);
+        if (!life) {
+            mediaRequire(this.lifetimes.size < 1024);
+            life = new ViewerLifetime();
+            this.lifetimes.set(binding.sessionId, life);
+        }
+        if (life.session)
+            await life.session.stop();
+        life.bind(binding);
+        let revision = Math.max(this.revision, display.revision);
+        if ((display.captureViewport !== true && (selection.width !== display.width || selection.height !== display.height)) || selection.dpi !== undefined) {
+            const physicalWidth = display.captureViewport === true ? display.width : selection.width;
+            const physicalHeight = display.captureViewport === true ? display.height : selection.height;
+            const actual = await this.geometryTransaction(async (displayRevision) => {
+                const { stdout } = await execute(this.displayControl, ['--transaction', `${physicalWidth}x${physicalHeight}${selection.dpi === undefined ? '' : '@' + selection.dpi}`], { env: this.environment, timeout: 4500, maxBuffer: 4096 });
+                const result = z.object({ outcome: z.literal('applied'), width: z.literal(physicalWidth), height: z.literal(physicalHeight),
+                    dpi: selection.dpi === undefined ? z.number().optional() : z.literal(selection.dpi) }).parse(JSON.parse(stdout));
+                return { ...result, displayRevision };
+            });
+            revision = actual.displayRevision;
+        }
+        const helper = await (this.options.sessionHelperFactory?.(binding) ?? this.factory(binding));
+        const identity = { sessionId: binding.sessionId, deviceGeneration: binding.deviceGeneration,
+            controlGeneration: binding.controlGeneration, displayRevision: revision };
+        const reserved = life.reserve();
+        try {
+            mediaRequire((await helper.request('verify_cleanup', identity)).result.verified === true);
+            const payload = { ...(selection.cursorVisible === undefined ? {} : { cursorVisible: selection.cursorVisible }), ...(effectiveRegion ? { captureRegion: effectiveRegion } : {}), width: selection.width, height: selection.height, fpsCeiling: life.prepared ? Math.min(life.appliedFps, selection.fpsCeiling) : selection.fpsCeiling,
+                rateTargetBps: life.appliedTargetBps, quality: selection.quality, backend: this.options.backend ?? 'libx264', leaseMs: 30000, representation: 1,
+                ...reserved, ...(life.prepared ? { continuation: { initialReservoirBits: life.initialReservoirBits, inputSequence: life.inputSequence,
+                        lastAppliedInputSequence: life.lastAppliedInputSequence } } : {}) };
+            const reply = await helper.request('prepare', identity, payload);
+            const actual = z.strictObject({ backend: z.literal(this.options.backend ?? 'libx264'), width: z.literal(selection.width), height: z.literal(selection.height),
+                fpsCeiling: z.literal(payload.fpsCeiling), rateTargetBps: z.literal(payload.rateTargetBps), representation: z.literal(payload.representation) }).parse(reply.result.selection);
+            if (!life.prepared)
+                life.initialReservoirBits = actual.rateTargetBps / 4;
+            life.appliedFps = actual.fpsCeiling;
+            life.prepared = true;
+            const session = new NativeBackendSession(helper, life, identity, selection, reserved, this, effectiveRegion);
+            life.session = session;
+            return session;
+        }
+        catch (error) {
+            await helper.stop(identity);
+            throw error;
+        }
+    }
+    async recoverDisplay(binding, reserved) {
+        return this.geometryTransaction(async () => {
+            const helper = await (this.options.sessionHelperFactory?.(binding) ?? this.factory(binding));
+            const identity = { sessionId: binding.sessionId, deviceGeneration: binding.deviceGeneration, controlGeneration: binding.controlGeneration,
+                displayRevision: reserved.displayRevision };
+            try {
+                mediaRequire((await helper.request('verify_cleanup', identity)).result.verified === true);
+                const { result } = await helper.request('recover_display', identity);
+                const actual = z.object({ outcome: z.literal('recovered'), width: z.number().int().min(2).max(4096), height: z.number().int().min(2).max(4096) }).parse(result);
+                return { verified: true, width: actual.width, height: actual.height, displayRevision: reserved.displayRevision };
+            }
+            finally {
+                await helper.stop(identity);
+            }
+        });
+    }
+}
+export class NativeBackendSession {
+    helper;
+    life;
+    identity;
+    selection;
+    reserved;
+    provider;
+    effectiveRegion;
+    get audioSupported() { return this.helper.audioSupported === true; }
+    get audioPackets() { return this.helper.audioPackets; }
+    async startAudio(audioEpoch, bitrate) {
+        return this.serialized(async () => {
+            mediaRequire(!this.stopped && this.life.session === this && this.audioSupported);
+            const reply = await this.helper.request('audio_start', this.identity, { audioEpoch, bitrate });
+            return z.strictObject({ audioEpoch: z.literal(audioEpoch), sampleRate: z.literal(48000), channels: z.literal(2),
+                framesPerPacket: z.literal(960), bitrate: z.literal(bitrate), lookaheadFrames: z.number().int().min(0).max(960) }).parse(reply.result);
+        });
+    }
+    async setAudioRate(bitrate) {
+        return this.serialized(async () => {
+            mediaRequire(!this.stopped && this.life.session === this && this.audioSupported);
+            await this.helper.request('audio_rate', this.identity, { bitrate });
+        });
+    }
+    async stopAudio() {
+        return this.serialized(async () => {
+            if (!this.stopped && this.audioSupported)
+                await this.helper.request('audio_stop', this.identity);
+        });
+    }
+    async audioStatus() {
+        const reply = await this.helper.request('audio_status', this.identity);
+        return z.strictObject({ state: z.enum(['off', 'playing', 'unavailable']) }).parse(reply.result).state;
+    }
+    runtimeRate = false;
+    get runtimeRateReconfigure() { return this.runtimeRate; }
+    codecFpsCeiling;
+    get runtimeRateFpsCeiling() { return this.codecFpsCeiling; }
+    events = new DesktopQueue();
+    stopped = false;
+    stopPromise;
+    started = false;
+    captureEpoch = 0;
+    configuration;
+    stream = new DesktopMediaStream(() => this.effectiveRegion ? { width: this.effectiveRegion.sourceWidth, height: this.effectiveRegion.sourceHeight } : undefined);
+    desired;
+    applied;
+    reservedRate;
+    firstFrame = 0;
+    presented = false;
+    packetConsumer = false;
+    lastCounters;
+    transportTotal = 0;
+    transportRestored = false;
+    operationTail = Promise.resolve();
+    operationCount = 0;
+    boundaryAttempt;
+    retiringMedia;
+    pendingPackets = new Map();
+    pendingPacketBytes = 0;
+    readPayloadEpoch = 0;
+    readPayloadBytes = 0;
+    cutSettledFrame = 0;
+    motionCut;
+    packetKey(packet) { return `${packet.epoch}:${desktopMediaLane(packet.type)}:${packet.sequence}`; }
+    forwardingUnit = false;
+    forwardingCursor = false;
+    forwardedFrame;
+    drainWake;
+    constructor(helper, life, identity, selection, reserved, provider, effectiveRegion) {
+        this.helper = helper;
+        this.life = life;
+        this.identity = identity;
+        this.selection = selection;
+        this.reserved = reserved;
+        this.provider = provider;
+        this.effectiveRegion = effectiveRegion;
+        this.desired = this.applied = { targetBps: life.appliedTargetBps, fpsCeiling: life.prepared ? Math.min(life.appliedFps, selection.fpsCeiling) : selection.fpsCeiling, pauseCapture: false, reopenEpoch: false };
+        this.codecFpsCeiling = this.applied.fpsCeiling;
+        this.forwardedFrame = helper.counters?.lastAllocatedFrameId ?? 0;
+        this.publishConfigured();
+        void helper.closed.then(() => { if (!this.stopped)
+            this.events.push({ type: 'failed', code: 'encoder_failed' }); });
+    }
+    get nativeTelemetry() { return this.helper.counters; }
+    get epoch() { return this.reserved.epoch; }
+    get displayRevision() { return this.identity.displayRevision; }
+    focusRevision = 1;
+    async focus(focus) {
+        return this.serialized(async () => {
+            const region = this.effectiveRegion;
+            mediaRequire(this.presented && this.selection.captureRegion && region && focus.revision > this.focusRevision &&
+                focus.region.sourceWidth === region.sourceWidth && focus.region.sourceHeight === region.sourceHeight);
+            const result = await this.command('focus', { epoch: this.epoch, displayRevision: this.displayRevision, focus });
+            const checked = decodeDesktopControl(JSON.stringify({ v: 1, type: 'focus_result', sessionId: this.identity.sessionId,
+                payload: { commandId: this.selection.commandId, controlGeneration: this.identity.controlGeneration, mediaEpoch: this.epoch,
+                    displayRevision: this.displayRevision, ...result } }), 'device');
+            mediaRequire(checked.type === 'focus_result');
+            if (checked.payload.outcome === 'applied') {
+                mediaRequire(canonicalDesktopJson(checked.payload.focus) === canonicalDesktopJson(focus));
+                this.focusRevision = focus.revision;
+                this.effectiveRegion = focus.region;
+            }
+            return { focus: checked.payload.focus, outcome: checked.payload.outcome };
+        });
+    }
+    get rateState() { return { desired: { ...this.desired }, applied: { ...this.applied } }; }
+    async checkHealth() {
+        await this.provider.options.validateSession?.();
+        await this.operationTail;
+        await this.command('status');
+        if (this.lastCounters?.inputAvailable === false) {
+            this.events.push({ type: 'recovery', result: { kind: 'input', verified: false } });
+            throw new NativeCommandError('unavailable');
+        }
+    }
+    get counters() { return Object.fromEntries(totals.map(k => [k, this.life.offsets[k] + (this.lastCounters?.[k] ?? 0)])); }
+    configured() {
+        // Capture-only options belong to prepare, not the configured wire message.
+        const { cursorVisible: _cursorVisible, ...selection } = this.selection;
+        return { ...selection, deviceGeneration: this.identity.deviceGeneration, controlGeneration: this.identity.controlGeneration,
+            mediaEpoch: this.epoch, displayRevision: this.displayRevision, encoderBackend: this.provider.options.backend ?? 'libx264', rateTargetBps: this.applied.targetBps,
+            fpsCeiling: this.codecFpsCeiling };
+    }
+    publishConfigured() { this.events.push({ type: 'configured', configured: this.configured() }); }
+    async command(name, payload = {}) {
+        if (['input', 'held_state', 'clipboard', 'focus', 'resize'].includes(name))
+            await this.provider.options.validateSession?.();
+        mediaRequire(!this.stopped && this.life.session === this);
+        const admission = name === 'set_rate' ? { ...payload } : undefined;
+        const current = () => {
+            if (admission && this.captureEpoch !== admission.epoch)
+                admission.pauseCapture = true;
+            return !this.stopped && this.life.session === this;
+        };
+        current();
+        const reply = await this.helper.request(name, { ...this.identity }, admission ?? payload, current);
+        this.lastCounters = reply.counters;
+        this.life.lastAppliedInputSequence = Math.max(this.life.lastAppliedInputSequence, reply.counters.lastInputSequence ?? 0);
+        mediaRequire(!this.stopped && this.life.session === this);
+        return reply.result;
+    }
+    async cacheDependency(request) {
+        return this.serialized(async () => {
+            mediaRequire(request.mediaEpoch === this.epoch && request.controlGeneration === this.identity.controlGeneration && request.displayRevision === this.displayRevision);
+            const result = await this.command('cache_dependency', { epoch: request.mediaEpoch, exactSequence: request.exactSequence, cacheId: request.cacheId });
+            const dependency = z.strictObject({ cacheId: z.literal(request.cacheId), width: z.literal(request.width), height: z.literal(request.height),
+                pixels: z.array(z.number().int().min(0).max(255)).length(request.width * request.height * 4) }).parse(result);
+            const pixels = Buffer.from(dependency.pixels);
+            mediaRequire(pixels.every((byte, i) => i % 4 !== 3 || byte === 255));
+            return pixels.toString('base64');
+        });
+    }
+    async accountTransportCost(cost) {
+        return this.serialized(async () => {
+            mediaRequire(/^[a-f0-9]{32}$/.test(cost.id) && Number.isSafeInteger(cost.totalBytes) && cost.totalBytes >= 0);
+            const previous = this.life.transportCosts.get(cost.id) ?? 0;
+            mediaRequire(cost.totalBytes >= previous);
+            if (!this.life.transportCosts.has(cost.id)) {
+                // rateTick owns one report at a time; retired peers cannot enqueue a
+                // later report behind eight subsequent replacements.
+                if (this.life.transportCosts.size === 8)
+                    this.life.transportCosts.delete(this.life.transportCosts.keys().next().value);
+                this.life.transportCosts.set(cost.id, 0);
+            }
+            await this.restoreTransportDebt();
+            const total = this.transportTotal + cost.totalBytes - previous;
+            mediaRequire(Number.isSafeInteger(total));
+            if (total !== this.transportTotal)
+                await this.command('transport_cost', { totalBytes: total });
+            this.transportTotal = total;
+            this.life.transportCosts.set(cost.id, cost.totalBytes);
+        });
+    }
+    async restoreTransportDebt() {
+        if (this.transportRestored)
+            return;
+        this.transportTotal = Math.ceil(this.life.transportDebtBits / 8);
+        if (this.transportTotal)
+            await this.command('transport_cost', { totalBytes: this.transportTotal });
+        this.transportRestored = true;
+    }
+    async start() {
+        await this.restoreTransportDebt();
+        const reserved = this.reserved;
+        this.captureEpoch = reserved.epoch;
+        try {
+            if (!this.started) {
+                const result = await this.command('start', { viewerReady: true, mediaBound: true });
+                this.accepted(result.accepted, this.applied.targetBps, this.applied.fpsCeiling);
+                this.started = true;
+            }
+            else {
+                await this.command('set_rate', { ...this.applied, pauseCapture: false, reopenEpoch: false, epoch: this.epoch });
+                this.applied.pauseCapture = false;
+            }
+            mediaRequire(this.reserved === reserved);
+        }
+        catch (error) {
+            if (this.reserved === reserved)
+                this.captureEpoch = 0;
+            throw error;
+        }
+    }
+    accepted(value, targetBps, fpsCeiling, verified = false) {
+        const schema = z.object({ backend: z.literal(this.provider.options.backend ?? 'libx264'), representation: z.literal(1),
+            width: z.literal(this.selection.width), height: z.literal(this.selection.height), fpsCeiling: z.union([z.literal(15), z.literal(30), z.literal(60)]),
+            targetBps: z.number().int().min(1).max(20000000), maxRateBps: z.number().int().min(1), bufferBits: z.number().int().min(1),
+            maxBFrames: z.literal(0), qualifiedCap: z.boolean(), runtimeRateReconfigure: z.boolean().optional(),
+            rateAdapter: z.string().optional() });
+        const actual = schema.parse(value);
+        mediaRequire(actual.targetBps === targetBps && actual.fpsCeiling === fpsCeiling && actual.maxRateBps <= targetBps &&
+            actual.bufferBits <= targetBps / 4 && actual.representation === 1);
+        const runtimeAdapter = this.provider.options.backend === 'videotoolbox' ? 'videotoolbox-data-rate-runtime-v1' : 'x264-vbv-runtime-v1';
+        if (verified) {
+            mediaRequire(actual.qualifiedCap);
+            this.runtimeRate = actual.runtimeRateReconfigure === true && actual.rateAdapter === runtimeAdapter;
+        }
+        return actual;
+    }
+    async credit(value) {
+        // Credits unblock boundary drains and must never wait on the boundary operation.
+        mediaRequire(!this.stopped && this.life.session === this);
+        const binding = { ...this.identity };
+        const current = () => !this.stopped && this.life.session === this && this.identity.displayRevision === binding.displayRevision &&
+            (this.helper.counters ?? this.lastCounters)?.epoch === value.epoch;
+        if (!current())
+            return;
+        let reply;
+        try {
+            reply = await this.helper.request('credit', binding, value, current);
+        }
+        catch (error) {
+            if (!current())
+                return;
+            throw error;
+        }
+        if (!current())
+            return;
+        this.lastCounters = reply.counters;
+        this.life.lastAppliedInputSequence = Math.max(this.life.lastAppliedInputSequence, reply.counters.lastInputSequence ?? 0);
+    }
+    /** Settle the pipe packet only after actual bounded transport admission and its ownership fence. */
+    mediaForwarded(packet) {
+        if (this.stopped || this.life.session !== this)
+            return;
+        const key = this.packetKey(packet), pending = this.pendingPackets.get(key);
+        mediaRequire(pending && pending.epoch === packet.epoch && pending.displayRevision === packet.displayRevision && pending.sequence === packet.sequence && pending.type === packet.type &&
+            pending.frameId === packet.frameId && pending.fragmentIndex === packet.fragmentIndex);
+        this.pendingPackets.delete(key);
+        this.pendingPacketBytes -= pending.payload.length;
+        if (packet.fragmentIndex + 1 === packet.fragmentCount) {
+            if (packet.type === 2)
+                this.forwardingUnit = false;
+            if (packet.type === 3)
+                this.forwardingCursor = false;
+            if (packet.type === 2 || packet.type === 5)
+                this.forwardedFrame = Math.max(this.forwardedFrame, packet.frameId);
+        }
+        this.drainWake?.();
+    }
+    async prepareMotionCut(value) {
+        mediaRequire(value.epoch === this.epoch && Number.isSafeInteger(value.cutId) && value.cutId > 0 && !this.stopped && this.life.session === this);
+        if (this.motionCut) {
+            if (this.motionCut.fence.epoch === value.epoch && this.motionCut.fence.cutId === value.cutId)
+                return this.motionCut.fence;
+            mediaRequire(this.motionCut.committed && (this.motionCut.fence.epoch !== value.epoch || value.cutId > this.motionCut.fence.cutId));
+        }
+        const deadline = performance.now() + 4500;
+        for (;;) {
+            try {
+                const reply = await this.helper.request('prepare_motion_cut', this.identity, value, () => !this.stopped && this.life.session === this && this.epoch === value.epoch);
+                mediaRequire(!this.stopped && this.life.session === this && this.epoch === value.epoch && reply.counters.epoch === value.epoch);
+                const fence = z.strictObject({ epoch: z.literal(value.epoch), cutId: z.literal(value.cutId), pictureThrough: z.number().int().min(0).max(0xffffffff), frameThrough: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER) }).parse(reply.result);
+                this.lastCounters = reply.counters;
+                this.motionCut = { fence, pipeThrough: reply.counters.sentPayloadBytes, settled: false, committed: false };
+                return fence;
+            }
+            catch (error) {
+                if (!(error instanceof NativeCommandError) || error.code !== 'busy' || performance.now() >= deadline)
+                    throw error;
+                await delay(10);
+            }
+        }
+    }
+    mediaDisposed(packet, fence) {
+        const cut = this.motionCut;
+        mediaRequire(cut && cut.fence.cutId === fence.cutId && cut.fence.epoch === packet.epoch && packet.type === 2 && packet.sequence <= fence.pictureThrough);
+        const key = this.packetKey(packet), pending = this.pendingPackets.get(key);
+        mediaRequire(pending && pending.type === 2 && pending.epoch === packet.epoch && pending.displayRevision === packet.displayRevision && pending.frameId === packet.frameId && pending.fragmentIndex === packet.fragmentIndex);
+        this.pendingPackets.delete(key);
+        this.pendingPacketBytes -= pending.payload.length;
+        if (packet.fragmentIndex + 1 === packet.fragmentCount)
+            this.forwardingUnit = false;
+        this.drainWake?.();
+    }
+    async settleMotionCut(fence) {
+        const cut = this.motionCut;
+        mediaRequire(cut && cut.fence.cutId === fence.cutId && cut.fence.epoch === fence.epoch);
+        if (cut.settled)
+            return;
+        const deadline = performance.now() + 4500;
+        while (this.readPayloadEpoch !== fence.epoch || this.readPayloadBytes < cut.pipeThrough || [...this.pendingPackets.values()].some(p => p.epoch === fence.epoch && p.type === 2 && p.sequence <= fence.pictureThrough)) {
+            mediaRequire(!this.stopped && this.life.session === this && this.epoch === fence.epoch);
+            const remaining = deadline - performance.now();
+            mediaRequire(remaining > 0);
+            try {
+                await bounded(new Promise(resolve => { this.drainWake = resolve; }), remaining);
+            }
+            finally {
+                this.drainWake = undefined;
+            }
+        }
+        this.stream.applyMotionCut(fence.pictureThrough, fence.frameThrough);
+        this.forwardingUnit = false;
+        this.cutSettledFrame = Math.max(this.cutSettledFrame, fence.frameThrough);
+        cut.settled = true;
+        this.drainWake?.();
+    }
+    async commitMotionCut(value) {
+        const cut = this.motionCut;
+        mediaRequire(cut && cut.settled && cut.fence.cutId === value.cutId && cut.fence.epoch === value.epoch && this.epoch === value.epoch);
+        if (cut.committed)
+            return;
+        await this.command('commit_motion_cut', value);
+        cut.committed = true;
+    }
+    async drainForwarded(frameId) {
+        if (!this.packetConsumer)
+            return;
+        const deadline = performance.now() + 4500;
+        while (Math.max(this.forwardedFrame, this.cutSettledFrame) < frameId || this.forwardingUnit || this.forwardingCursor || this.pendingPackets.size) {
+            mediaRequire(!this.stopped && this.life.session === this);
+            const remaining = deadline - performance.now();
+            mediaRequire(remaining > 0);
+            try {
+                await bounded(new Promise(resolve => { this.drainWake = resolve; }), remaining);
+            }
+            finally {
+                this.drainWake = undefined;
+            }
+        }
+        mediaRequire(!this.stopped && this.life.session === this);
+    }
+    /** Stop new captures, but keep complete encoded units flowing on the old media leg. */
+    async pauseAndDrain() {
+        const payload = { ...this.applied, pauseCapture: true, reopenEpoch: false, epoch: this.epoch };
+        const deadline = performance.now() + 4500;
+        do {
+            await this.command('set_rate', payload);
+            if (this.lastCounters?.pendingPayloadBytes === 0)
+                return;
+            await delay(10);
+        } while (!this.stopped && performance.now() < deadline);
+        throw new NativeCommandError('transport_failed');
+    }
+    async decoderReady(ack) {
+        mediaRequire(ack.controlGeneration === this.identity.controlGeneration && ack.displayRevision === this.displayRevision &&
+            ack.mediaEpoch === this.epoch && this.configuration && ack.representation === this.configuration.representation &&
+            JSON.stringify(ack.parameterSets) === JSON.stringify(this.configuration.parameterSets));
+        await this.command('decoder_ready', { epoch: this.epoch, representation: ack.representation, parameterSets: ack.parameterSets });
+    }
+    async firstPresented(ack) {
+        mediaRequire(ack.epoch === this.epoch && this.firstFrame > 0 && ack.frameId >= this.firstFrame);
+        if (!this.presented) {
+            await this.command('first_presented', { epoch: this.epoch, frameId: this.firstFrame });
+            this.presented = true;
+        }
+    }
+    async acknowledge(ack) {
+        await this.operationTail;
+        if (this.stopped || ack.epoch !== this.epoch || !this.presented)
+            return;
+        await this.command('acknowledge', ack);
+    }
+    async renewAuthenticatedLease(renewal) {
+        await this.operationTail;
+        await this.command('renew', renewal);
+    }
+    async heldState(snapshot) {
+        await this.operationTail;
+        if (snapshot.controlGeneration !== this.identity.controlGeneration || snapshot.displayRevision !== this.displayRevision || snapshot.sequence < this.life.inputSequence)
+            return;
+        if (snapshot.sequence > this.life.inputSequence) {
+            await this.command('held_state', { ...snapshot, keys: [], buttons: [], sequence: this.life.inputSequence });
+            return;
+        }
+        await this.command('held_state', snapshot);
+    }
+    async reserveOverview(value) {
+        await this.operationTail;
+        if (this.stopped || !this.started || value.epoch !== this.epoch)
+            return false;
+        mediaRequire(Number.isSafeInteger(value.wireBytes) && value.wireBytes >= 44 && value.wireBytes <= 32808);
+        const epoch = this.epoch;
+        try {
+            const result = await this.command('reserve_overview', value);
+            mediaRequire(typeof result.admitted === 'boolean');
+            return !this.stopped && this.epoch === epoch && result.admitted;
+        }
+        catch {
+            return false;
+        }
+    }
+    async overview(maxSide) {
+        if (!this.selection.captureRegion || !this.started || this.stopped)
+            return undefined;
+        try {
+            const reply = await this.command('overview', { maxSide });
+            if (typeof reply.jpeg !== 'string')
+                return undefined;
+            const jpeg = Buffer.from(reply.jpeg, 'base64');
+            mediaRequire(jpeg.length <= 32768 && jpeg.toString('base64') === reply.jpeg);
+            return { width: Number(reply.width), height: Number(reply.height), sourceWidth: Number(reply.sourceWidth), sourceHeight: Number(reply.sourceHeight), jpeg };
+        }
+        catch {
+            // An optional image must never retire decoder/input authority.
+            return undefined;
+        }
+    }
+    async clipboard(request) {
+        mediaRequire(request.controlGeneration === this.identity.controlGeneration && !this.stopped);
+        const reply = await this.command('clipboard', request);
+        const message = decodeDesktopControl(JSON.stringify({ v: 1, type: 'clipboard_result', sessionId: this.identity.sessionId,
+            payload: reply }), 'device');
+        mediaRequire(message.type === 'clipboard_result');
+        return message.payload;
+    }
+    async input(event) {
+        decodeDesktopControl(JSON.stringify({ v: 1, type: 'input', sessionId: this.identity.sessionId, payload: event }), 'viewer');
+        const rejected = { sequence: event.sequence, outcome: 'rejected', ...(event.action === 'text' ? { operationId: event.operationId } : {}) };
+        if (this.stopped || event.controlGeneration !== this.identity.controlGeneration || event.displayRevision !== this.displayRevision ||
+            event.sequence <= this.life.inputSequence)
+            return rejected;
+        this.life.inputSequence = event.sequence;
+        if (event.action === 'text') {
+            const previous = this.life.text.get(event.operationId);
+            if (previous)
+                return { ...previous, sequence: event.sequence };
+            if (this.life.text.size >= 1024 || this.life.pendingText)
+                return rejected;
+            this.life.text.set(event.operationId, { ...rejected, outcome: 'unknown' });
+            this.life.pendingText = event.operationId;
+        }
+        try {
+            let nativeEvent = event;
+            if (event.action === 'pointer' || event.action === 'button' || event.action === 'wheel') {
+                const region = this.selection.captureRegion;
+                const width = region?.sourceWidth ?? this.selection.width;
+                const height = region?.sourceHeight ?? this.selection.height;
+                if (event.x < 0 || event.x >= width || event.y < 0 || event.y >= height)
+                    return rejected;
+                if (!region && this.effectiveRegion) {
+                    const source = this.effectiveRegion;
+                    nativeEvent = { ...event, x: Math.floor(event.x * source.sourceWidth / width),
+                        y: Math.floor(event.y * source.sourceHeight / height) };
+                }
+            }
+            const result = await this.command('input', nativeEvent);
+            if (event.action === 'text' && result.outcome === 'pending')
+                return await this.textResult(event.operationId);
+            const parsed = decodeDesktopControl(JSON.stringify({ v: 1, type: 'input_result', sessionId: this.identity.sessionId, payload: result }), 'device');
+            mediaRequire(parsed.type === 'input_result');
+            if (event.action === 'text') {
+                this.life.text.set(event.operationId, parsed.payload);
+                this.life.pendingText = undefined;
+            }
+            return parsed.payload;
+        }
+        catch {
+            if (event.action === 'text') {
+                this.life.pendingText = undefined;
+                return this.life.text.get(event.operationId);
+            }
+            return rejected;
+        }
+    }
+    async textResult(operationId) {
+        const saved = this.life.text.get(operationId);
+        mediaRequire(saved);
+        if (this.life.pendingText !== operationId)
+            return saved;
+        const deadline = performance.now() + 5000;
+        try {
+            while (!this.stopped && performance.now() < deadline) {
+                const result = await this.command('text_result', { operationId });
+                if (result.outcome !== 'pending') {
+                    const message = decodeDesktopControl(JSON.stringify({ v: 1, type: 'input_result', sessionId: this.identity.sessionId, payload: result }), 'device');
+                    mediaRequire(message.type === 'input_result');
+                    this.life.text.set(operationId, message.payload);
+                    return message.payload;
+                }
+                await delay(10);
+            }
+        }
+        catch { /* Preserve UNKNOWN and never replay after interruption. */ }
+        finally {
+            if (this.life.pendingText === operationId)
+                this.life.pendingText = undefined;
+        }
+        return this.life.text.get(operationId);
+    }
+    serialized(run) {
+        // Control requests (up to 32 in the supervisor) share this queue with the
+        // rate controller. Theme sync can overlap a resize and a rate update at
+        // first presentation; pending work must wait rather than invalidate it.
+        mediaRequire(this.operationCount < 64);
+        this.operationCount++;
+        const result = this.operationTail.then(run);
+        this.operationTail = result.catch(() => { }).finally(() => { this.operationCount--; });
+        return result;
+    }
+    async atBoundary(command, payload, reserved) {
+        const deadline = performance.now() + (command === 'set_rate' ? 12000 : 4500);
+        do {
+            const coalesced = command === 'set_rate' ? { ...payload, ...this.desired, pauseCapture: true, reopenEpoch: true, epoch: reserved.epoch } : payload;
+            try {
+                const old = { epoch: this.epoch, displayRevision: this.displayRevision };
+                const attempt = this.command(command, coalesced);
+                this.boundaryAttempt = attempt;
+                let result;
+                try {
+                    result = await attempt;
+                }
+                finally {
+                    if (this.boundaryAttempt === attempt)
+                        this.boundaryAttempt = undefined;
+                }
+                // Native has closed old capture admission and completed its private writes.
+                // Its allocation fence becomes proof only after the real WS acknowledgements.
+                this.retiringMedia = old;
+                await this.drainForwarded(this.lastCounters.lastAllocatedFrameId);
+                return result;
+            }
+            catch (error) {
+                if (!(error instanceof NativeCommandError) || !['busy', 'rate_limited'].includes(error.code) || performance.now() >= deadline)
+                    throw error;
+                this.events.push({ type: 'rate_deferred', reason: error.code, reserved });
+                await delay(25);
+            }
+        } while (!this.stopped);
+        throw new NativeCommandError('transport_failed');
+    }
+    async setRate(decision) {
+        this.desired = { ...decision };
+        return this.serialized(async () => {
+            const current = { ...this.desired };
+            if (current.targetBps === this.applied.targetBps && current.fpsCeiling === this.applied.fpsCeiling)
+                current.reopenEpoch = false;
+            if (!current.reopenEpoch && this.captureEpoch === this.epoch &&
+                current.targetBps === this.applied.targetBps && current.fpsCeiling === this.applied.fpsCeiling &&
+                current.pauseCapture === this.applied.pauseCapture)
+                return;
+            if (!current.reopenEpoch) {
+                if (!this.runtimeRate) {
+                    if (current.targetBps !== this.applied.targetBps || current.fpsCeiling > this.applied.fpsCeiling)
+                        return;
+                    await this.command('set_rate', { ...current, epoch: this.epoch });
+                    this.applied = { ...current, pauseCapture: this.lastCounters.pauseCapture };
+                    return;
+                }
+                const changed = current.targetBps !== this.applied.targetBps || current.fpsCeiling !== this.applied.fpsCeiling;
+                const result = await this.command('set_rate', { ...current, epoch: this.epoch });
+                if (changed) {
+                    this.accepted(result.accepted, current.targetBps, current.fpsCeiling, true);
+                    mediaRequire(result.reopened === false && Number.isSafeInteger(result.appliedAtMonotonicMs));
+                    this.life.appliedTargetBps = current.targetBps;
+                    this.life.appliedFps = current.fpsCeiling;
+                    this.events.push({ type: 'rate_applied', decision: current, epoch: this.epoch, actualTargetBps: current.targetBps,
+                        actualFpsCeiling: current.fpsCeiling, appliedAtMonotonicMs: result.appliedAtMonotonicMs });
+                }
+                this.applied = { ...current, pauseCapture: this.lastCounters.pauseCapture };
+                return;
+            }
+            this.captureEpoch = 0;
+            const reserved = this.reservedRate ??= this.life.reserve();
+            // Pause until the new CONFIG is committed by viewer_ready + Server START.
+            const result = await this.atBoundary('set_rate', { ...current, pauseCapture: true, epoch: reserved.epoch }, reserved);
+            const applied = z.object({ targetBps: z.number().int().min(500000).max(20000000), fpsCeiling: z.union([z.literal(15), z.literal(30), z.literal(60)]) }).parse(result.accepted);
+            const accepted = this.accepted(result.accepted, applied.targetBps, applied.fpsCeiling);
+            mediaRequire(Number.isSafeInteger(result.appliedAtMonotonicMs));
+            this.applied = { ...current, targetBps: accepted.targetBps, fpsCeiling: accepted.fpsCeiling, pauseCapture: true };
+            this.codecFpsCeiling = accepted.fpsCeiling;
+            this.life.appliedTargetBps = accepted.targetBps;
+            this.life.appliedFps = accepted.fpsCeiling;
+            this.reserved = reserved;
+            this.reservedRate = undefined;
+            this.configuration = undefined;
+            this.firstFrame = 0;
+            this.presented = false;
+            this.events.push({ type: 'rate_applied', decision: current, epoch: this.epoch, actualTargetBps: this.applied.targetBps,
+                actualFpsCeiling: this.applied.fpsCeiling, appliedAtMonotonicMs: result.appliedAtMonotonicMs });
+            this.publishConfigured();
+        });
+    }
+    async refresh() {
+        return this.serialized(async () => {
+            this.captureEpoch = 0;
+            const reserved = this.life.reserve();
+            await this.pauseAndDrain();
+            await this.atBoundary('refresh', { epoch: reserved.epoch }, reserved);
+            this.reserved = reserved;
+            this.configuration = undefined;
+            this.firstFrame = 0;
+            this.presented = false;
+            this.publishConfigured();
+        });
+    }
+    async setCursorVisible(visible) {
+        return this.serialized(async () => {
+            mediaRequire(!this.stopped && this.life.session === this);
+            const reply = await this.helper.request('cursor_visibility', this.identity, { visible });
+            return z.object({ mediaEpoch: z.number().int().min(1), afterFrameId: z.number().int().min(0) }).parse(reply.result);
+        });
+    }
+    async setAppearance(colorScheme) {
+        mediaRequire(colorScheme === 'light' || colorScheme === 'dark');
+        return this.serialized(async () => {
+            mediaRequire(!this.stopped && this.life.session === this && (await this.provider.probe())?.displays[0].appearanceSync === true);
+            const { stdout } = await execute(this.provider.displayControl, ['--appearance', colorScheme], { env: this.provider.environment, timeout: 4500, maxBuffer: 4096 });
+            z.object({ colorScheme: z.literal(colorScheme), outcome: z.literal('applied') }).parse(JSON.parse(stdout));
+        });
+    }
+    async resize(mode) {
+        return this.serialized(() => this.provider.geometryTransaction(async (revision) => {
+            this.captureEpoch = 0;
+            const reserved = this.life.reserve();
+            await this.pauseAndDrain();
+            const effectiveRegion = mode.captureRegion ?? (this.effectiveRegion ? {
+                x: 0, y: 0, width: this.effectiveRegion.sourceWidth, height: this.effectiveRegion.sourceHeight,
+                sourceWidth: this.effectiveRegion.sourceWidth, sourceHeight: this.effectiveRegion.sourceHeight,
+            } : undefined);
+            const result = await this.atBoundary('resize', { ...mode, ...(effectiveRegion ? { captureRegion: effectiveRegion } : {}),
+                ...reserved, expectedDisplayRevision: this.displayRevision, displayRevision: revision }, reserved);
+            const axis = z.number().int().min(2).max(4096).refine(n => n % 2 === 0);
+            const actual = z.object({ outcome: z.enum(['applied', 'rolled_back']), width: axis, height: axis, displayRevision: z.literal(revision),
+                dpi: z.number().int().min(64).max(384).optional(), captureRegion: captureRegion.optional() }).parse(result);
+            mediaRequire(canonicalDesktopJson(actual.captureRegion ?? null) === canonicalDesktopJson(effectiveRegion ?? null));
+            this.effectiveRegion = effectiveRegion;
+            // A helper-only region must not change the identity acknowledged to the server.
+            actual.captureRegion = mode.captureRegion;
+            if (mode.dpi !== undefined)
+                mediaRequire(actual.dpi !== undefined && (actual.outcome !== 'applied' || actual.dpi === mode.dpi));
+            else if (this.selection.dpi === undefined)
+                delete actual.dpi;
+            this.identity.displayRevision = actual.displayRevision;
+            this.reserved = reserved;
+            this.focusRevision = 1;
+            this.selection = { ...this.selection, captureRegion: actual.captureRegion, width: actual.width, height: actual.height, ...(actual.dpi === undefined ? {} : { dpi: actual.dpi }) };
+            this.configuration = undefined;
+            this.firstFrame = 0;
+            this.presented = false;
+            this.publishConfigured();
+            return { ...actual, commandId: this.selection.commandId };
+        }, mode.captureRegion !== undefined || this.effectiveRegion !== undefined));
+    }
+    /** Keeps server command identities without extending the public provider interface. */
+    configurationCommand(commandId) { this.selection = { ...this.selection, commandId }; }
+    get codec() { return this.configuration; }
+    get packets() {
+        const self = this;
+        return { async *[Symbol.asyncIterator]() {
+                mediaRequire(!self.packetConsumer);
+                self.packetConsumer = true;
+                let skipCursor = false;
+                for await (const bytes of self.helper.packets) {
+                    if (self.stopped || self.life.session !== self)
+                        return;
+                    const reserved = self.reserved;
+                    const packet = decodeMedia(bytes), retired = self.retiringMedia;
+                    const old = retired && packet.epoch === retired.epoch && packet.displayRevision === retired.displayRevision;
+                    mediaRequire((packet.epoch === self.epoch && packet.displayRevision === self.displayRevision) || (old && (packet.type === 3 || packet.type === 4)));
+                    self.life.lastAppliedInputSequence = Math.max(self.life.lastAppliedInputSequence, packet.lastInputSequence);
+                    if (self.readPayloadEpoch !== packet.epoch) {
+                        self.readPayloadEpoch = packet.epoch;
+                        self.readPayloadBytes = 0;
+                    }
+                    self.readPayloadBytes += packet.payload.length;
+                    mediaRequire(Number.isSafeInteger(self.readPayloadBytes));
+                    const unit = self.stream.accept(bytes);
+                    if (packet.fragmentIndex === 0)
+                        skipCursor = !!old && (packet.type === 3 || packet.type === 4) && !self.forwardingCursor;
+                    if (skipCursor)
+                        continue;
+                    if (packet.type === 1) {
+                        self.retiringMedia = undefined;
+                        // Native can verify SPS only after the authorized first encode. Reuse the
+                        // existing non-reopening response, retaining the current admission state.
+                        const result = await self.command('set_rate', { ...self.applied, epoch: self.epoch, reopenEpoch: false });
+                        if (self.stopped || self.life.session !== self || self.reserved !== reserved)
+                            continue;
+                        self.accepted(result.accepted, self.applied.targetBps, self.applied.fpsCeiling, true);
+                        self.configuration = self.stream.configuration;
+                    }
+                    if (unit && !self.firstFrame)
+                        self.firstFrame = unit.frameId;
+                    const key = self.packetKey(packet);
+                    mediaRequire(!self.pendingPackets.has(key) && self.pendingPackets.size < 128 && self.pendingPacketBytes + packet.payload.length <= 524288);
+                    self.pendingPackets.set(key, packet);
+                    self.pendingPacketBytes += packet.payload.length;
+                    if (packet.type === 2 && packet.fragmentCount > 1)
+                        self.forwardingUnit = true;
+                    if (packet.type === 3 && packet.fragmentCount > 1)
+                        self.forwardingCursor = true;
+                    self.drainWake?.();
+                    yield bytes;
+                }
+            } };
+    }
+    stop() {
+        if (this.stopPromise)
+            return this.stopPromise;
+        this.stopped = true;
+        this.drainWake?.();
+        return this.stopPromise = (async () => {
+            if (this.life.pendingText)
+                this.life.pendingText = undefined;
+            await this.helper.stop(this.identity);
+            const last = this.helper.counters ?? this.lastCounters;
+            this.life.transportDebtBits = last?.rateBudget?.debtBits ?? this.life.transportDebtBits;
+            for (const k of totals) {
+                const next = this.life.offsets[k] + (last?.[k] ?? 0);
+                mediaRequire(Number.isSafeInteger(next));
+                this.life.offsets[k] = next;
+            }
+            this.lastCounters = undefined;
+            this.life.touched = performance.now();
+            if (this.life.session === this)
+                this.life.session = undefined;
+            this.events.close();
+        })();
+    }
+}