@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/desktopControl/lobby.js

@@ -0,0 +1,131 @@
+import { z } from 'zod';
+import { decodeDesktopSessionRequest, parseDesktopJson } from './protocol.js';
+const identifier = z.string().regex(/^[a-f0-9]{32}$/);
+const safe = z.number().int().min(1).max(Number.MAX_SAFE_INTEGER);
+const sourceAxis = z.number().int().min(2).max(4096);
+const axis = sourceAxis.refine(value => value % 2 === 0);
+const sourceModeSchema = z.strictObject({ width: sourceAxis, height: sourceAxis });
+const modeSchema = z.strictObject({ width: axis, height: axis });
+const viewportSchema = z.strictObject({ widthDp: z.number().finite().positive().max(16384),
+    heightDp: z.number().finite().positive().max(16384), deviceScale: z.number().finite().min(0.5).max(8),
+    orientation: z.enum(['landscape', 'portrait']) });
+const resolutionSchema = z.discriminatedUnion('mode', [z.strictObject({ mode: z.literal('fit') }),
+    z.strictObject({ mode: z.literal('fixed'), width: axis, height: axis })]);
+export const lobbyRequestSchema = z.strictObject({ requestId: identifier, revision: safe, viewport: viewportSchema,
+    resolution: resolutionSchema, dpi: z.number().int().min(64).max(384).nullable(),
+    transports: z.array(z.enum(['quic', 'wss'])).min(1).max(2).refine(values => new Set(values).size === values.length),
+    targetId: identifier.nullable().optional(), viewer: z.unknown().nullable().optional(),
+    backgroundVersion: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/).nullish() });
+const rangeSchema = z.strictObject({ minWidth: axis, minHeight: axis, maxWidth: axis, maxHeight: axis });
+export const lobbyPlanSchema = z.strictObject({ lobbyId: identifier, planId: identifier, revision: safe, targetId: identifier,
+    desktop: sourceModeSchema, dpi: z.number().int().min(64).max(384).nullable(), resize: z.enum(['none', 'modes', 'dynamic']),
+    modes: z.array(modeSchema).max(32), resizeRange: rangeSchema.nullable(), dynamicDpi: z.boolean(), canAcquire: z.boolean(),
+    reason: z.string().max(128).nullable(), maxDpi: z.number().int().min(64).max(384).nullable(), captureViewport: z.boolean(),
+    sampling: modeSchema, targets: z.array(z.strictObject({ id: identifier, label: z.string().min(1).max(128),
+        kind: z.enum(['display', 'window']), available: z.boolean() })).max(128) });
+export function decodeLobbyRequest(text) {
+    if (Buffer.byteLength(text) > 49152)
+        throw new Error('invalid_request');
+    const request = lobbyRequestSchema.parse(parseDesktopJson(text));
+    if (request.viewer != null)
+        decodeDesktopSessionRequest(JSON.stringify({ requestId: request.requestId,
+            displayId: request.targetId ?? request.requestId, viewer: request.viewer, viewport: request.viewport,
+            resolution: request.resolution, quality: 'auto', takeover: false }));
+    return request;
+}
+export const wallpaperAssetSchema = z.strictObject({ assetId: z.string().min(1).max(128), version: z.string().min(1).max(128),
+    originalWidth: z.number().int().min(1).max(65536), originalHeight: z.number().int().min(1).max(65536),
+    width: z.number().int().min(1).max(4096), height: z.number().int().min(1).max(4096),
+    placement: z.enum(['cover', 'fit', 'stretch', 'center', 'tile']).default('cover'),
+    coverage: z.enum(['full_asset', 'composited']).default('full_asset'), compatibleDesktop: sourceModeSchema.nullable().optional(),
+    anchorX: z.number().finite().min(0).max(1).default(0.5), anchorY: z.number().finite().min(0).max(1).default(0.5),
+    background: z.string().regex(/^#[a-fA-F0-9]{6}$/).default('#000000'),
+    intrinsicScale: z.number().finite().min(0.125).max(16).default(1),
+    mimeType: z.enum(['image/jpeg', 'image/webp']).default('image/jpeg'),
+    fidelity: z.enum(['exact', 'approximate']).default('exact'), colorSpace: z.literal('srgb').default('srgb')
+}).refine(asset => asset.width * asset.height <= 8_388_608 && (asset.coverage !== 'composited' || asset.compatibleDesktop != null));
+export function composeWallpaper(value, selected) {
+    const asset = wallpaperAssetSchema.parse(value);
+    const desktop = sourceModeSchema.parse(selected);
+    if (asset.coverage === 'composited' && (asset.compatibleDesktop?.width !== desktop.width || asset.compatibleDesktop.height !== desktop.height))
+        throw new Error('incompatible_wallpaper');
+    const full = { x: 0, y: 0, width: 1, height: 1 };
+    if (asset.coverage === 'composited' || asset.placement === 'stretch')
+        return { source: full, destination: full, version: 1 };
+    const imageWidth = asset.originalWidth * asset.intrinsicScale;
+    const imageHeight = asset.originalHeight * asset.intrinsicScale;
+    if (asset.placement === 'tile')
+        return { source: full, destination: full,
+            tileWidth: imageWidth / desktop.width, tileHeight: imageHeight / desktop.height, version: 1 };
+    const scale = asset.placement === 'cover' ? Math.max(desktop.width / imageWidth, desktop.height / imageHeight) :
+        asset.placement === 'fit' ? Math.min(desktop.width / imageWidth, desktop.height / imageHeight) : 1;
+    const sourceWidth = Math.min(1, desktop.width / (imageWidth * scale));
+    const sourceHeight = Math.min(1, desktop.height / (imageHeight * scale));
+    const destinationWidth = Math.min(1, imageWidth * scale / desktop.width);
+    const destinationHeight = Math.min(1, imageHeight * scale / desktop.height);
+    return { source: { x: (1 - sourceWidth) * asset.anchorX, y: (1 - sourceHeight) * asset.anchorY,
+            width: sourceWidth, height: sourceHeight },
+        destination: { x: (1 - destinationWidth) * asset.anchorX, y: (1 - destinationHeight) * asset.anchorY,
+            width: destinationWidth, height: destinationHeight }, version: 1 };
+}
+export function planLobby(request, capabilities, lobbyId, planId, automaticDpi = true) {
+    const target = capabilities.displays.find(display => display.id === request.targetId) ??
+        (request.targetId == null ? capabilities.displays.find(display => display.kind !== 'window') : undefined);
+    if (!target)
+        throw new Error('unavailable');
+    const viewer = request.viewer == null ? null : decodeDesktopSessionRequest(JSON.stringify({ requestId: request.requestId,
+        displayId: target.id, viewer: request.viewer, viewport: request.viewport, resolution: request.resolution,
+        quality: 'auto', takeover: false })).viewer;
+    const limits = capabilities.encoderBackends.flatMap(backend => backend.formats).filter(format => format.cappedRate &&
+        capabilities.formats.includes(format.format) && (!viewer || viewer.formats.includes(format.format)));
+    const limit = limits.sort((first, second) => second.maxPixels - first.maxPixels)[0];
+    if (!limit || viewer && (viewer.protocols.min > 2 || viewer.protocols.max < 2))
+        throw new Error('unsupported_client');
+    const maxWidth = Math.min(viewer?.maxWidth ?? 4096, limit.maxWidth);
+    const maxHeight = Math.min(viewer?.maxHeight ?? 4096, limit.maxHeight);
+    const maxPixels = Math.min(viewer?.maxPixels ?? 4_000_000, limit.maxPixels);
+    const layoutScale = !automaticDpi && !target.captureViewport ? 1 : request.viewport.deviceScale;
+    const desired = request.resolution.mode === 'fixed' ? request.resolution : {
+        width: Math.max(2, Math.floor(request.viewport.widthDp * layoutScale / 2) * 2),
+        height: Math.max(2, Math.floor(request.viewport.heightDp * layoutScale / 2) * 2)
+    };
+    let desktop;
+    if (target.captureViewport || target.resize === 'none')
+        desktop = { width: target.width, height: target.height };
+    else if (target.resize === 'dynamic' && target.resizeRange) {
+        const range = target.resizeRange;
+        const factor = Math.min(1, Math.min(maxWidth, range.maxWidth) / desired.width, Math.min(maxHeight, range.maxHeight) / desired.height, Math.sqrt(Math.min(maxPixels, 4_000_000) / (desired.width * desired.height)));
+        desktop = { width: Math.max(range.minWidth, Math.floor(desired.width * factor / 2) * 2),
+            height: Math.max(range.minHeight, Math.floor(desired.height * factor / 2) * 2) };
+    }
+    else {
+        desktop = [...target.modes].filter(candidate => candidate.width <= maxWidth && candidate.height <= maxHeight &&
+            candidate.width * candidate.height <= maxPixels).sort((first, second) => {
+            const score = (candidate) => Math.abs(Math.log((candidate.width / candidate.height) / (desired.width / desired.height))) * 10 +
+                Math.abs(Math.log(candidate.width * candidate.height / (desired.width * desired.height)));
+            return score(first) - score(second);
+        })[0] ?? { width: target.width, height: target.height };
+    }
+    const maximumDpi = target.maxDpi == null ? undefined : Math.min(target.maxDpi, viewer?.maxDpi ?? target.maxDpi);
+    const baselineDpi = automaticDpi && request.resolution.mode === 'fit' ? Math.max(96, Math.round(96 * Math.min(desktop.width / request.viewport.widthDp, desktop.height / request.viewport.heightDp))) : 96;
+    const dpi = maximumDpi == null ? null : Math.min(maximumDpi, request.dpi ?? baselineDpi);
+    let sampling = desktop;
+    if (target.captureViewport) {
+        const density = Math.min(target.capturePixelScale ?? 1, request.resolution.mode === 'fixed' ?
+            Math.min(desired.width / desktop.width, desired.height / desktop.height) :
+            Math.min(request.viewport.widthDp / desktop.width, request.viewport.heightDp / desktop.height) * request.viewport.deviceScale);
+        const width = desktop.width * density, height = desktop.height * density;
+        const factor = Math.min(1, maxWidth / width, maxHeight / height, Math.sqrt(maxPixels / (width * height)));
+        sampling = { width: Math.max(2, Math.floor(width * factor / 2) * 2), height: Math.max(2, Math.floor(height * factor / 2) * 2) };
+    }
+    const supported = sampling.width <= maxWidth && sampling.height <= maxHeight && sampling.width * sampling.height <= maxPixels;
+    const modes = target.captureViewport ? [sampling] : target.resize === 'none' ? [desktop] : [...target.modes.filter(candidate => candidate.width <= maxWidth && candidate.height <= maxHeight && candidate.width * candidate.height <= maxPixels &&
+            (candidate.width !== desktop.width || candidate.height !== desktop.height)).slice(0, 31), desktop];
+    return { lobbyId, planId, revision: request.revision, targetId: target.id, desktop, dpi,
+        resize: target.captureViewport ? 'none' : target.resize, modes,
+        resizeRange: target.captureViewport ? null : target.resizeRange ?? null, dynamicDpi: maximumDpi != null,
+        maxDpi: maximumDpi ?? null, captureViewport: target.captureViewport ?? false, sampling,
+        canAcquire: supported && capabilities.configured && capabilities.health === 'ready' && ['granted', 'not_applicable'].includes(capabilities.permission),
+        reason: supported ? capabilities.reason : 'unsupported_client', targets: capabilities.displays.map(display => ({ id: display.id, label: display.label,
+            kind: display.kind ?? 'display', available: true })) };
+}

package/dist/workstation/desktopControl/macProvider.js

@@ -0,0 +1,156 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createConnection } from 'node:net';
+import { z } from 'zod';
+import { NativeProvider } from './nativeProvider.js';
+import { HelperProcess, bounded, NativeCommandError } from './helperProcess.js';
+import { readDeviceHostGrant } from './hostGrant.js';
+import { desktopCapabilitiesSchema } from './protocol.js';
+import { NativeDeviceAdmission } from './nativeDeviceAdmission.js';
+import { captureTargetLabel } from './captureTargetLabel.js';
+import { decodeWallpaper } from './wallpaper.js';
+import { captureSamplingModes as macCaptureModes } from './captureModes.js';
+const execute = promisify(execFile);
+export const macDesktopGrantSchema = z.strictObject({ schemaVersion: z.literal(2),
+    hostGeneration: z.string().min(1).max(128),
+    executable: z.string().startsWith('/').max(4096), sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    socket: z.string().startsWith('/').max(103), token: z.string().regex(/^[a-f0-9]{64}$/) });
+const target = z.object({ id: z.string().regex(/^[0-9a-f]{32}$/), kind: z.enum(['display', 'window']), label: z.string(), displayIdentity: z.string().min(1).max(256), capturePixelScale: z.number().min(1).max(16).optional(),
+    width: z.number().int().min(2).max(4096).refine(n => n % 2 === 0), height: z.number().int().min(2).max(4096).refine(n => n % 2 === 0) }).refine(t => t.width * t.height <= 16777216);
+const geometry = z.object({ targets: z.array(target).min(1).max(128), screenRecording: z.boolean(), accessibility: z.boolean(), independentCursor: z.boolean(), captureViewport: z.boolean().optional(), overview: z.boolean().optional(), cursorVisibility: z.boolean().optional(), audio: z.boolean().optional() });
+export { captureTargetLabel } from './captureTargetLabel.js';
+export { captureSamplingModes as macCaptureModes } from './captureModes.js';
+export async function checkMacHost(grant) {
+    const socket = createConnection(grant.socket);
+    try {
+        await bounded(new Promise((resolve, reject) => {
+            socket.once('error', reject);
+            socket.once('connect', () => socket.write(grant.token));
+            socket.once('data', bytes => bytes.length === 1 && bytes[0] === 1 ? resolve() : reject(new NativeCommandError('unavailable')));
+            socket.once('end', () => reject(new NativeCommandError('unavailable')));
+        }), 1000, 'unavailable');
+    }
+    finally {
+        socket.destroy();
+    }
+}
+/** Discovery can report permissions but cannot prompt, capture, encode or inject input. */
+export class MacProvider {
+    directory;
+    sourceFile;
+    async prepareAutomation(binding) {
+        const provider = await this.liveProvider();
+        if (!provider)
+            throw new NativeCommandError('unavailable');
+        return provider.prepareAutomation(binding);
+    }
+    admission;
+    original;
+    get deviceAdmission() { return this.admission; }
+    static async connect(directory, sourceFile) {
+        const provider = new MacProvider(directory, undefined, sourceFile);
+        if (!await provider.liveProvider())
+            throw new NativeCommandError('unavailable');
+        return provider;
+    }
+    provider;
+    identity = '';
+    revisions = new Map();
+    constructor(directory, _binding, sourceFile) {
+        this.directory = directory;
+        this.sourceFile = sourceFile;
+    }
+    async grant() {
+        const grant = await readDeviceHostGrant(this.sourceFile ?? path.join(this.directory, 'desktop-provider.json'));
+        if (this.original && JSON.stringify(grant) !== JSON.stringify(this.original))
+            throw new NativeCommandError('unavailable');
+        if (!grant.executable.endsWith('/Axom Work Computer Use.app/Contents/MacOS/Axom Work Computer Use'))
+            throw new NativeCommandError('unavailable');
+        await execute('/usr/bin/codesign', ['--verify', '--strict', '-R', '=identifier "com.platless.axom.computer-use"', path.resolve(grant.executable, '../../..')], { timeout: 7000, maxBuffer: 65536 });
+        await checkMacHost(grant);
+        return grant;
+    }
+    async capabilities() {
+        const grant = await this.grant();
+        const { stdout } = await execute(grant.executable, ['--probe'], { timeout: 7000, maxBuffer: 65536, env: { ...process.env, AXOM_KEEPER_SOCKET: grant.socket, AXOM_KEEPER_TOKEN: grant.token } });
+        const g = geometry.parse(JSON.parse(stdout));
+        const displays = g.targets.map(t => {
+            const previous = this.revisions.get(t.id);
+            const identity = t.displayIdentity;
+            const revision = previous ? (previous.identity === identity ? previous.revision : previous.revision + 1) : 1;
+            this.revisions.set(t.id, { identity, revision });
+            return { ...(g.overview ? { overview: true } : {}), id: t.id, kind: t.kind, label: captureTargetLabel(t.label), width: t.width, height: t.height, revision, resize: g.captureViewport ? 'dynamic' : 'none', modes: g.captureViewport ? macCaptureModes(t.width, t.height, t.capturePixelScale ?? 1) : [], ...(g.captureViewport ? { captureViewport: true, capturePixelScale: t.capturePixelScale ?? 1, resizeRange: { minWidth: 2, minHeight: 2, maxWidth: Math.min(4096, Math.floor(t.width * (t.capturePixelScale ?? 1) / 2) * 2), maxHeight: Math.min(4096, Math.floor(t.height * (t.capturePixelScale ?? 1) / 2) * 2) } } : {}) };
+        });
+        const liveIds = new Set(displays.map(d => d.id));
+        for (const id of this.revisions.keys())
+            if (!liveIds.has(id))
+                this.revisions.delete(id);
+        const formats = ['h264-420-v1'];
+        const permission = g.screenRecording && g.accessibility, ready = permission && g.independentCursor;
+        return desktopCapabilitiesSchema.parse({ protocols: { min: 2, max: g.audio ? 3 : 2 }, providerId: 'macos-arm64-v1', providerVersion: 'axom-macos-1', configured: true, cursorEmbedded: false, cursorVisibility: g.cursorVisibility === true,
+            permission: permission ? 'granted' : 'required', health: ready ? 'ready' : 'unavailable', reason: ready ? null : permission ? 'cursor_unavailable' : 'permission_required', formats,
+            encoderBackends: [{ id: 'videotoolbox', kind: 'hardware', formats: formats.map(format => ({ format, maxWidth: 4096, maxHeight: 4096, maxPixels: 8847360, maxFps: 30, cappedRate: true })) }],
+            input: { pointer: true, physicalKeyboard: true, unicodeText: true, clipboard: true, textPaste: true },
+            displays });
+    }
+    async liveProvider() {
+        try {
+            const grant = await this.grant(), identity = grant.sha256 + grant.token;
+            if (this.original && identity !== this.identity)
+                return null;
+            if (identity !== this.identity) {
+                const admission = await NativeDeviceAdmission.connect(grant);
+                if (admission.hostLifetimeId !== grant.hostGeneration)
+                    throw new NativeCommandError('unavailable');
+                this.original = grant;
+                this.admission = admission;
+                this.identity = identity;
+                this.provider = new NativeProvider({ helperPath: grant.executable, runtimeDir: this.directory, backend: 'videotoolbox',
+                    deviceAdmission: admission, environment: { ...process.env, AXOM_KEEPER_SOCKET: grant.socket, AXOM_KEEPER_TOKEN: grant.token },
+                    enumerate: () => this.capabilities(), sessionHelperFactory: async (binding) => HelperProcess.launch(grant.executable, { ...process.env, AXOM_KEEPER_TARGET: binding.displayId,
+                        AXOM_KEEPER_SOCKET: grant.socket, AXOM_KEEPER_TOKEN: grant.token,
+                        AXOM_DEVICE_CONTEXT: admission.context(binding.deviceGrant?.registrationId ?? '', binding.deviceGeneration, binding.sessionId, binding.deviceGrant) }, 'macos') });
+            }
+            return this.provider;
+        }
+        catch {
+            return null;
+        }
+    }
+    async probe() {
+        // Only explicit removal of the desktop grant disables discovery. A stopped or
+        // unresponsive keeper is a connection failure, not a disappearing capability.
+        try {
+            await fs.lstat(path.join(this.directory, 'desktop-provider.json'));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+        return this.capabilities();
+    }
+    async prepare(selection, binding, current) {
+        const provider = await this.liveProvider();
+        if (!provider)
+            throw new NativeCommandError('unavailable');
+        // NativeProvider.prepare performs fresh permission/geometry admission itself.
+        // Repeating full enumeration here added another WindowServer round trip per window.
+        return provider.prepare(selection, binding, current);
+    }
+    async wallpaper(targetId, pixels = { width: 1920, height: 1080 }) {
+        const grant = await this.grant();
+        if (!/^[a-f0-9]{32}$/.test(targetId))
+            throw new NativeCommandError('invalid_request');
+        const result = await execute(grant.executable, ['--wallpaper', targetId, String(pixels.width), String(pixels.height)], { timeout: 8000, maxBuffer: 3 * 1024 * 1024,
+            env: { ...process.env, AXOM_KEEPER_SOCKET: grant.socket, AXOM_KEEPER_TOKEN: grant.token } });
+        return decodeWallpaper(result.stdout);
+    }
+    async recoverDisplay(binding, reserved) {
+        if (!await this.probe() || !this.provider)
+            throw new NativeCommandError('unavailable');
+        return this.provider.recoverDisplay(binding, reserved);
+    }
+}

package/dist/workstation/desktopControl/media.js

@@ -0,0 +1,331 @@
+import { z } from 'zod';
+import { DesktopProtocolError, parseDesktopJson } from './protocol.js';
+export function mediaRequire(value) {
+    if (!value)
+        throw new DesktopProtocolError('Invalid desktop media');
+}
+const integer = (n, min = 0, max = Number.MAX_SAFE_INTEGER) => Number.isSafeInteger(n) && n >= min && n <= max;
+const axis = z.number().int().min(2).max(4096).refine(n => n % 2 === 0);
+const label = z.string().min(1).refine(s => Buffer.byteLength(s) <= 128 && !/[\x00-\x1f\x7f]/.test(s));
+const codecSchema = z.strictObject({ codec: z.literal('h264'), representation: z.literal(1),
+    width: axis, height: axis, fpsCeiling: z.union([z.literal(15), z.literal(30), z.literal(60)]),
+    profile: label, level: label, colorMatrix: z.literal('bt709'), colorRange: z.literal('limited'), parameterSets: z.array(z.string()) });
+function checked(read) {
+    try {
+        return read();
+    }
+    catch {
+        throw new DesktopProtocolError('Invalid desktop media');
+    }
+}
+export function decodeConfig(bytes) {
+    return checked(() => {
+        const c = codecSchema.parse(parseDesktopJson(bytes, 16384));
+        mediaRequire(c.parameterSets.length === 2);
+        c.parameterSets.forEach((encoded, i) => {
+            mediaRequire(encoded.length <= 2732);
+            const nal = Buffer.from(encoded, 'base64');
+            mediaRequire(nal.length >= 1 && nal.length <= 2048 && nal.toString('base64') === encoded &&
+                (nal[0] & 128) === 0 && (nal[0] & 31) === (i % 2 === 0 ? 7 : 8));
+        });
+        return c;
+    });
+}
+function validateUnit(p, bytes) {
+    if (p.type === 1)
+        mediaRequire(decodeConfig(bytes).representation === p.representation);
+    else if (p.type === 3) {
+        const w = bytes.readUInt16BE(), h = bytes.readUInt16BE(2);
+        mediaRequire(w >= 1 && w <= 256 && h >= 1 && h <= 256 && bytes.readUInt16BE(4) < w &&
+            bytes.readUInt16BE(6) < h && w * h * 4 + 8 === p.unitLength);
+    }
+    else if (p.type === 5) {
+        mediaRequire(bytes.length >= 95 && bytes.subarray(0, 16).equals(Buffer.from('28b4619e8e524cf29ae8415852473034', 'hex')) && bytes[16] === 4 && bytes[37] === 1 && bytes.readUInt32BE(38) === 0 && bytes.readUInt16BE(42) > 0 && bytes.readUInt16BE(42) <= 1024);
+        const focusRevision = bytes.readBigUInt64BE(44), [x, y, w, h, sw, sh] = [52, 56, 60, 64, 68, 72].map(o => bytes.readUInt32BE(o));
+        mediaRequire(focusRevision > 0n && focusRevision <= BigInt(Number.MAX_SAFE_INTEGER) && w > 0 && h > 0 && sw >= 2 && sh >= 2 && sw <= 4096 && sh <= 4096 && x + w <= sw && y + h <= sh);
+        mediaRequire(axis.safeParse(bytes.readUInt16BE(17)).success && axis.safeParse(bytes.readUInt16BE(19)).success && bytes.readBigUInt64BE(21) > 0n && bytes.readBigUInt64BE(21) <= BigInt(Number.MAX_SAFE_INTEGER) && bytes.readBigUInt64BE(29) > 0n && bytes.readBigUInt64BE(29) <= BigInt(Number.MAX_SAFE_INTEGER));
+    }
+    else if (p.type === 4)
+        cursor(bytes);
+}
+function cursor(bytes) {
+    return checked(() => z.strictObject({ x: z.number().int().min(0).max(4095),
+        y: z.number().int().min(0).max(4095), visible: z.boolean() }).parse(parseDesktopJson(bytes, 1024)));
+}
+/** Validates the header and current identity before retaining/reassembling payload. */
+export function decodeMedia(bytes, fence = () => { }) {
+    return checked(() => {
+        mediaRequire(bytes.length >= 65 && bytes.length <= 65600 && bytes.subarray(0, 5).equals(Buffer.from('AXDS\x01')) &&
+            bytes.readUInt16BE(8) === 64 && bytes.readUInt16BE(10) === 0 && bytes.readUIntBE(61, 3) === 0);
+        const u64 = (offset) => { const n = bytes.readBigUInt64BE(offset); mediaRequire(n <= BigInt(Number.MAX_SAFE_INTEGER)); return Number(n); };
+        const length = bytes.readUInt32BE(48);
+        const p = { type: bytes[5], flags: bytes.readUInt16BE(6), epoch: bytes.readUInt32BE(12),
+            displayRevision: bytes.readUInt32BE(16), sequence: bytes.readUInt32BE(20), frameId: u64(24), timestampUs: u64(32),
+            lastInputSequence: u64(40), unitLength: bytes.readUInt32BE(52), fragmentIndex: bytes.readUInt16BE(56),
+            fragmentCount: bytes.readUInt16BE(58), representation: bytes[60], payload: Buffer.alloc(0) };
+        mediaRequire(p.type >= 1 && p.type <= 5 && p.representation === 1 && p.flags <= 1 &&
+            (p.type === 2 || p.flags === 0) && p.epoch > 0 && p.displayRevision > 0 && p.sequence > 0 &&
+            ((p.type === 2 || p.type === 5) ? p.frameId > 0 : p.frameId === 0 && p.timestampUs === 0));
+        mediaRequire(length > 0 && length <= 65536 && bytes.length === 64 + length && p.unitLength > 0 && p.unitLength <= 8388608);
+        const count = Math.ceil(p.unitLength / 65536);
+        mediaRequire(p.fragmentCount === count && p.fragmentIndex < count &&
+            length === (p.fragmentIndex === count - 1 ? p.unitLength - p.fragmentIndex * 65536 : 65536));
+        if (p.type === 1)
+            mediaRequire(count === 1 && p.unitLength <= 16384);
+        if (p.type === 3)
+            mediaRequire(p.unitLength >= 12 && p.unitLength <= 262152);
+        if (p.type === 5)
+            mediaRequire(count === 1 && p.unitLength >= 95 && p.unitLength <= 24576);
+        if (p.type === 4)
+            mediaRequire(count === 1 && p.unitLength <= 1024);
+        fence(p);
+        p.payload = bytes.subarray(64);
+        if (count === 1)
+            validateUnit(p, p.payload);
+        return p;
+    });
+}
+export class DesktopMediaStream {
+    sourceDimensions;
+    constructor(sourceDimensions = () => undefined) {
+        this.sourceDimensions = sourceDimensions;
+    }
+    configuration = null;
+    epoch = 0;
+    revision = 0;
+    picture = { sequence: 0, lastFrame: 0, pending: undefined, storage: undefined, next: 0 };
+    cursorLane = { sequence: 0, lastFrame: 0, pending: undefined, storage: undefined, next: 0 };
+    exactLane = { sequence: 0, lastFrame: 0, pending: undefined, storage: undefined, next: 0 };
+    lane(type) { return type === 3 || type === 4 ? this.cursorLane : type === 5 ? this.exactLane : this.picture; }
+    exactSequence = 0;
+    recentFrames = [];
+    needsIdr = true;
+    failed = false;
+    accept(bytes) {
+        mediaRequire(!this.failed);
+        try {
+            const p = decodeMedia(bytes, packet => this.validate(packet));
+            const lane = this.lane(p.type);
+            lane.sequence = p.sequence;
+            if (p.type === 1) {
+                this.configuration = decodeConfig(p.payload);
+                this.epoch = p.epoch;
+                this.revision = p.displayRevision;
+                this.needsIdr = true;
+                this.exactSequence = 0;
+                this.exactLane.sequence = 0;
+                this.exactLane.pending = undefined;
+                this.exactLane.storage = undefined;
+                this.exactLane.next = 0;
+                this.cursorLane.sequence = 0;
+                this.cursorLane.pending = undefined;
+                this.cursorLane.storage = undefined;
+                this.cursorLane.next = 0;
+                return null;
+            }
+            if (p.fragmentCount === 1)
+                return this.complete(p, p.payload);
+            if (!lane.pending) {
+                lane.pending = { ...p, payload: Buffer.alloc(0) };
+                lane.storage = Buffer.alloc(p.unitLength);
+                lane.next = 0;
+            }
+            p.payload.copy(lane.storage, lane.next++ * 65536);
+            if (lane.next !== p.fragmentCount)
+                return null;
+            const first = lane.pending, unit = lane.storage;
+            lane.pending = undefined;
+            lane.storage = undefined;
+            validateUnit(first, unit);
+            return this.complete(first, unit);
+        }
+        catch {
+            this.failed = true;
+            this.picture.pending = this.cursorLane.pending = this.exactLane.pending = undefined;
+            this.picture.storage = this.cursorLane.storage = this.exactLane.storage = undefined;
+            throw new DesktopProtocolError('Invalid desktop stream');
+        }
+    }
+    applyMotionCut(pictureThrough, frameThrough) {
+        mediaRequire(!this.failed && this.configuration && integer(pictureThrough, this.picture.sequence, 0xffffffff) && integer(frameThrough, this.picture.lastFrame));
+        this.picture.sequence = pictureThrough;
+        this.picture.lastFrame = frameThrough;
+        this.picture.pending = undefined;
+        this.picture.storage = undefined;
+        this.picture.next = 0;
+        this.needsIdr = true;
+    }
+    validate(p) {
+        const lane = this.lane(p.type);
+        if (p.type === 1) {
+            mediaRequire(!this.picture.pending && p.epoch > this.epoch && p.sequence === 1);
+            return;
+        }
+        mediaRequire(this.configuration && p.epoch === this.epoch && p.displayRevision === this.revision &&
+            p.representation === this.configuration.representation && p.sequence === lane.sequence + 1);
+        if (!lane.pending) {
+            mediaRequire(p.fragmentIndex === 0);
+            if (p.type === 2 || p.type === 5)
+                mediaRequire(p.frameId > lane.lastFrame && !this.recentFrames.includes(p.frameId) && p.frameId !== this.picture.pending?.frameId && (!this.needsIdr || p.type === 2 && p.flags === 1));
+        }
+        else {
+            const first = lane.pending;
+            mediaRequire(['type', 'flags', 'frameId', 'timestampUs', 'lastInputSequence', 'unitLength', 'fragmentCount']
+                .every(k => p[k] === first[k]) && p.fragmentIndex === lane.next);
+        }
+    }
+    complete(p, bytes) {
+        if (p.type === 4) {
+            const c = cursor(bytes), source = this.sourceDimensions() ?? this.configuration;
+            mediaRequire(c.x < source.width && c.y < source.height);
+        }
+        if (p.type !== 2 && p.type !== 5)
+            return null;
+        const exactSequence = p.type === 5 ? Number(bytes.readBigUInt64BE(29)) : 0;
+        if (p.type === 5) {
+            mediaRequire(exactSequence === this.exactSequence + 1 && bytes.readUInt16BE(17) === this.configuration.width && bytes.readUInt16BE(19) === this.configuration.height);
+            this.exactSequence = exactSequence;
+        }
+        else
+            this.needsIdr = false;
+        this.lane(p.type).lastFrame = p.frameId;
+        this.recentFrames.push(p.frameId);
+        if (this.recentFrames.length > 128)
+            this.recentFrames.shift();
+        return { ...p, payload: bytes, mainAU: bytes, exactSequence };
+    }
+}
+const lanes = ['motion', 'cursor', 'exact'];
+const consumedKey = { motion: 'motionConsumedBytes', cursor: 'cursorConsumedBytes', exact: 'exactConsumedBytes' };
+const freshTotals = () => ({ motion: 0, cursor: 0, exact: 0 });
+export function desktopMediaLane(type) {
+    mediaRequire(integer(type, 1, 5));
+    return type <= 2 ? 'motion' : type <= 4 ? 'cursor' : 'exact';
+}
+/** One epoch's bounded reservations and actual transport admissions. Pipe writes never commit. */
+export class DesktopMediaFlowWindow {
+    window;
+    records = new Map();
+    committed = freshTotals();
+    reserved = freshTotals();
+    observed = freshTotals();
+    consumed = freshTotals();
+    lastId = 0;
+    constructor(window = 0) {
+        this.window = window;
+        mediaRequire(window === 0 || integer(window, 196608, 524288));
+    }
+    get inFlightBytes() { return lanes.reduce((n, l) => n + this.debt(l), 0); }
+    get recordCount() { return this.records.size; }
+    get hasCredit() { return this.window > 0; }
+    get appliedCredit() { return { motionConsumedBytes: this.consumed.motion, cursorConsumedBytes: this.consumed.cursor, exactConsumedBytes: this.consumed.exact, windowBytes: this.window }; }
+    debt(lane) { return this.committed[lane] + this.reserved[lane] - this.consumed[lane]; }
+    laneRecords(lane) { return [...this.records.values()].filter(r => r.lane === lane).length; }
+    admit(lane, bytes) {
+        mediaRequire(lanes.includes(lane) && integer(bytes, 1, lane === 'exact' ? 24576 : 65536));
+        const others = lanes.filter(l => l !== lane && l !== 'motion');
+        const protectedBytes = others.reduce((n, l) => n + Math.max(0, (l === 'cursor' ? 65536 : 24576) - this.debt(l)), 0);
+        const protectedRecords = others.reduce((n, l) => n + (this.laneRecords(l) === 0 ? 1 : 0), 0);
+        return this.records.size + 1 <= 128 - protectedRecords && this.inFlightBytes + bytes <= this.window - protectedBytes;
+    }
+    /** IDs are fresh monotonically increasing local admission attempts, including failed attempts. */
+    reserve(id, lane, bytes) {
+        mediaRequire(integer(id, this.lastId + 1));
+        this.lastId = id;
+        if (!this.admit(lane, bytes))
+            return false;
+        mediaRequire(this.committed[lane] <= Number.MAX_SAFE_INTEGER - this.reserved[lane] - bytes);
+        this.reserved[lane] += bytes;
+        this.records.set(id, { lane, bytes, remaining: bytes, committed: false });
+        return true;
+    }
+    commit(id) {
+        const r = this.records.get(id);
+        mediaRequire(r && !r.committed);
+        this.reserved[r.lane] -= r.bytes;
+        this.committed[r.lane] += r.bytes;
+        r.committed = true;
+        this.applyPending();
+    }
+    cancel(id) {
+        const r = this.records.get(id);
+        mediaRequire(r && !r.committed);
+        mediaRequire(this.observed[r.lane] <= this.committed[r.lane] + this.reserved[r.lane] - r.bytes);
+        this.reserved[r.lane] -= r.bytes;
+        this.records.delete(id);
+    }
+    credit(value) {
+        mediaRequire(integer(value.windowBytes, 196608, 524288) && Number.isSafeInteger(value.motionConsumedBytes + value.cursorConsumedBytes + value.exactConsumedBytes));
+        for (const l of lanes)
+            mediaRequire(integer(value[consumedKey[l]], this.observed[l], this.committed[l] + this.reserved[l]));
+        for (const l of lanes)
+            this.observed[l] = value[consumedKey[l]];
+        this.window = value.windowBytes;
+        this.applyPending();
+    }
+    applyPending() {
+        for (const lane of lanes) {
+            if (this.observed[lane] > this.committed[lane])
+                continue;
+            let delta = this.observed[lane] - this.consumed[lane];
+            this.consumed[lane] = this.observed[lane];
+            for (const [id, r] of this.records)
+                if (delta && r.lane === lane && r.committed) {
+                    const used = Math.min(delta, r.remaining);
+                    r.remaining -= used;
+                    delta -= used;
+                    if (!r.remaining)
+                        this.records.delete(id);
+                }
+            mediaRequire(delta === 0);
+        }
+    }
+}
+/** Sender-clock complete-frame send -> feedback. Feedback scheduling is not network delay. */
+export class DesktopDeliveryDelay {
+    frames = new Map();
+    samples = [];
+    observation = 0;
+    sampled = 0;
+    sent(frame, at) {
+        this.frames.set(frame, at);
+        if (this.frames.size > 512)
+            this.frames.delete(this.frames.keys().next().value);
+    }
+    received(frame, at) {
+        const sent = this.frames.get(frame);
+        if (sent === undefined)
+            return;
+        this.samples.push({ at, delay: Math.max(0, at - sent), observation: ++this.observation });
+        if (this.samples.length > 500)
+            this.samples.shift();
+        // Independent exact/motion completion may insert IDs out of numeric order.
+        for (const id of this.frames.keys())
+            if (id <= frame)
+                this.frames.delete(id);
+    }
+    excess(now) {
+        this.samples = this.samples.filter(s => now - s.at <= 90000);
+        const recent = this.samples.filter(s => now - s.at <= 1250);
+        if (!recent.length)
+            return 0;
+        return Math.max(0, Math.min(...recent.map(s => s.delay)) - Math.min(...this.samples.map(s => s.delay)));
+    }
+    sample(now) {
+        const raw = this.excess(now);
+        const fresh = this.samples.filter(s => s.observation > this.sampled && now - s.at <= 1250);
+        this.sampled = this.observation;
+        if (!fresh.length)
+            return { excessMs: raw, observations: 0, delayMs: undefined };
+        const excessMs = Math.max(0, Math.min(...fresh.map(s => s.delay)) - Math.min(...this.samples.map(s => s.delay)));
+        // The active feedback cadence allows 200ms of scheduling uncertainty. Only
+        // the excess beyond that can establish >40ms congestion; ambiguity must hold.
+        const delayMs = excessMs <= 40 ? excessMs : excessMs > 240 ? excessMs - 200 : undefined;
+        return { excessMs, observations: fresh.length, delayMs };
+    }
+    reset() {
+        this.frames.clear();
+        this.samples = [];
+        this.sampled = this.observation;
+    }
+}