@platless/axom-cli 0.5.9 → 0.6.36

package/dist/workstation/desktopControl/networkEvidence.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+const counter = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+const pathSchema = z.strictObject({
+    sequence: counter.min(1), pathGeneration: counter.min(1),
+    rttUs: counter, minRttUs: counter, bandwidthBps: counter.nullable(),
+    cwndBytes: counter, sentPackets: counter, lostPackets: counter,
+    congestionEvents: counter, udpTxBytes: counter,
+});
+export function decodeQuicPathStats(bytes, observedAtMs) {
+    if (bytes.length > 4096 || !Number.isFinite(observedAtMs) || observedAtMs < 0)
+        throw new Error('invalid path stats');
+    const stats = pathSchema.parse(JSON.parse(bytes.toString('utf8')));
+    if (stats.lostPackets > stats.sentPackets)
+        throw new Error('invalid path counters');
+    return { ...stats, observedAtMs };
+}
+export class DesktopNetworkEvidence {
+    previous;
+    state = 'unknown';
+    queueMs = 0;
+    sample(nowMs, stats, demandBps) {
+        if (!stats || stats.observedAtMs > nowMs || nowMs - stats.observedAtMs > Math.max(1500, stats.rttUs / 1000 * 3)) {
+            return { state: 'unknown', fresh: false, queueMs: 0 };
+        }
+        const previous = this.previous;
+        const samePath = previous?.id === stats.id && previous.pathGeneration === stats.pathGeneration;
+        if (samePath && stats.sequence <= previous.sequence) {
+            return { state: this.state, fresh: false, queueMs: this.queueMs, bandwidthBps: previous.bandwidthBps ?? undefined };
+        }
+        this.previous = stats;
+        this.queueMs = Math.max(0, (stats.rttUs - stats.minRttUs) / 1000);
+        const queueThresholdMs = Math.max(10, stats.minRttUs / 1000 * 0.1);
+        const countersAdvance = samePath && stats.sentPackets >= previous.sentPackets &&
+            stats.lostPackets >= previous.lostPackets && stats.congestionEvents >= previous.congestionEvents &&
+            stats.udpTxBytes > previous.udpTxBytes;
+        const congestion = countersAdvance && stats.congestionEvents > previous.congestionEvents;
+        const bandwidth = stats.bandwidthBps ?? undefined;
+        const loaded = countersAdvance && bandwidth !== undefined && bandwidth > 0 && demandBps >= bandwidth * 0.85;
+        this.state = this.queueMs > queueThresholdMs && (congestion || loaded) ? 'congested'
+            : this.queueMs <= queueThresholdMs ? 'usable' : 'unknown';
+        return { state: this.state, fresh: true, queueMs: this.queueMs, bandwidthBps: bandwidth };
+    }
+}

package/dist/workstation/desktopControl/overview.js

@@ -0,0 +1,58 @@
+import { createHash } from 'node:crypto';
+import { mediaRequire } from './media.js';
+/** A single initial image, then <=2% of focus target and <=32kbps, including wire headers. */
+export class DesktopOverviewBudget {
+    tokens = 32808;
+    at = 0;
+    lastSent = -Infinity;
+    digest;
+    initialized = false;
+    canCapture(now, targetBps, pressure) {
+        this.refill(now, targetBps);
+        return !pressure && now - this.lastSent >= 2000 && this.tokens >= 1024;
+    }
+    get maxSide() { return this.tokens < 8192 ? 320 : 640; }
+    eligible(bytes, now, targetBps) {
+        this.refill(now, targetBps);
+        const digest = createHash('sha256').update(bytes.subarray(16, 28)).update(bytes.subarray(40)).digest('hex');
+        if (digest === this.digest || bytes.length > this.tokens || now - this.lastSent < 2000)
+            return false;
+        return true;
+    }
+    admit(bytes, now, targetBps) {
+        if (!this.eligible(bytes, now, targetBps))
+            return false;
+        this.tokens -= bytes.length;
+        this.lastSent = now;
+        this.digest = createHash('sha256').update(bytes.subarray(16, 28)).update(bytes.subarray(40)).digest('hex');
+        return true;
+    }
+    disconnected() { this.digest = undefined; }
+    refill(now, targetBps) {
+        mediaRequire(Number.isFinite(now) && Number.isFinite(targetBps) && targetBps >= 0);
+        if (!this.initialized) {
+            this.at = now;
+            this.initialized = true;
+        }
+        this.tokens = Math.min(32808, this.tokens + Math.max(0, now - this.at) / 1000 * Math.min(4000, targetBps / 400));
+        this.at = now;
+    }
+}
+export function overviewPacket(image, sequence, generation) {
+    const { width: w, height: h, sourceWidth: sw, sourceHeight: sh, jpeg } = image;
+    mediaRequire([w, h, sw, sh, sequence, generation].every(Number.isSafeInteger) && sequence > 0 && generation > 0 &&
+        w >= 2 && h >= 2 && w <= 640 && h <= 640 && sw >= w && sh >= h && sw <= 16384 && sh <= 16384 &&
+        Math.abs(w / h - sw / sh) <= 2 / h && jpeg.length >= 4 && jpeg.length <= 32768 && jpeg.readUInt16BE(0) === 0xffd8 && jpeg.readUInt16BE(jpeg.length - 2) === 0xffd9);
+    const bytes = Buffer.alloc(40 + jpeg.length);
+    bytes.write('AXOV');
+    bytes[4] = 1;
+    bytes.writeBigUInt64BE(BigInt(sequence), 8);
+    bytes.writeUInt32BE(sw, 16);
+    bytes.writeUInt32BE(sh, 20);
+    bytes.writeUInt16BE(w, 24);
+    bytes.writeUInt16BE(h, 26);
+    bytes.writeUInt32BE(jpeg.length, 28);
+    bytes.writeBigUInt64BE(BigInt(generation), 32);
+    jpeg.copy(bytes, 40);
+    return bytes;
+}

package/dist/workstation/desktopControl/protocol.js

@@ -0,0 +1,302 @@
+import { z } from 'zod';
+import { audioConfiguration, audioMode } from './audio.js';
+import { lobbyRequestSchema, lobbyPlanSchema } from './lobby.js';
+export const DESKTOP_MAX_JSON_BYTES = 48 * 1024;
+export class DesktopProtocolError extends Error {
+    code = 'invalid_request';
+}
+const invalid = () => { throw new DesktopProtocolError('Invalid desktop protocol value'); };
+const int = (min = 0, max = Number.MAX_SAFE_INTEGER) => z.number().int().min(min).max(max);
+const positive = int(1);
+const u32 = int(1, 0xffffffff);
+const id = z.string().regex(/^[0-9a-f]{32}$/);
+const bounded = z.string().min(1).refine(s => Buffer.byteLength(s) <= 128 && !/[\x00-\x1f\x7f]/.test(s));
+const code = z.string().regex(/^[a-z0-9_]{1,128}$/);
+const sourceAxis = int(2, 4096);
+const axis = sourceAxis.refine(n => n % 2 === 0);
+const fps = z.union([z.literal(15), z.literal(30), z.literal(60)]);
+const dpi = int(64, 384);
+const format = z.literal('h264-420-v1');
+const quality = z.enum(['auto', 'text', 'motion']);
+const distinct = (items) => new Set(items.map(i => canonicalDesktopJson(i))).size === items.length;
+const formats = z.array(format).min(1).max(1).refine(distinct);
+const protocols = z.strictObject({ min: int(1, 2147483647), max: int(1, 2147483647) }).refine(p => p.min <= p.max);
+const mode = z.strictObject({ width: axis, height: axis });
+const resizeRange = z.strictObject({ minWidth: axis, minHeight: axis, maxWidth: axis, maxHeight: axis })
+    .refine(r => r.minWidth <= r.maxWidth && r.minHeight <= r.maxHeight);
+const display = z.strictObject({ id, label: bounded, width: sourceAxis, height: sourceAxis, revision: u32,
+    resize: z.enum(['none', 'modes', 'dynamic']), modes: z.array(mode).max(32).refine(distinct),
+    kind: z.enum(['display', 'window']).optional(),
+    resizeRange: resizeRange.nullable().optional(), captureViewport: z.boolean().optional(), overview: z.boolean().optional(), capturePixelScale: z.number().min(1).max(16).optional(),
+    dpi: dpi.optional(), maxDpi: dpi.optional(), appearanceSync: z.boolean().optional(),
+}).refine(d => (d.capturePixelScale == null || d.captureViewport === true) && (d.resize !== 'modes' || d.modes.length > 0) &&
+    (d.dpi == null) === (d.maxDpi == null) && (d.dpi == null || d.dpi <= d.maxDpi) &&
+    (d.resize === 'dynamic') === (d.resizeRange != null) &&
+    (d.resizeRange == null || d.modes.every(m => m.width >= d.resizeRange.minWidth && m.width <= d.resizeRange.maxWidth &&
+        m.height >= d.resizeRange.minHeight && m.height <= d.resizeRange.maxHeight)));
+const encoderFormat = z.strictObject({ format, maxWidth: axis, maxHeight: axis, maxPixels: int(4, 16777216), maxFps: fps, cappedRate: z.boolean() });
+const backend = z.strictObject({ id: bounded, kind: z.enum(['software', 'hardware']),
+    formats: z.array(encoderFormat).min(1).max(2).refine(a => distinct(a.map(f => f.format))),
+});
+export const desktopCapabilitiesSchema = z.strictObject({
+    cursorEmbedded: z.boolean().optional(), cursorVisibility: z.boolean().optional(), lobby: z.boolean().optional(),
+    protocols, providerId: bounded, providerVersion: bounded, configured: z.boolean(),
+    permission: z.enum(['granted', 'required', 'unknown', 'not_applicable']), health: z.enum(['ready', 'unavailable']), reason: code.nullable(),
+    formats, encoderBackends: z.array(backend),
+    input: z.strictObject({ pointer: z.boolean(), physicalKeyboard: z.boolean(), unicodeText: z.boolean(), clipboard: z.boolean().optional(), textPaste: z.boolean().optional() }),
+    displays: z.array(display).min(1).max(128).refine(a => distinct(a.map(d => d.id))),
+}).refine(c => distinct(c.encoderBackends.map(b => b.id)) && c.encoderBackends.every(b => b.formats.every(f => c.formats.includes(f.format))));
+export const capabilityReportSchema = z.strictObject({ generation: bounded, revision: positive, desktop: desktopCapabilitiesSchema.nullable() });
+export const captureRegion = z.strictObject({ x: int(), y: int(), width: positive, height: positive,
+    sourceWidth: sourceAxis, sourceHeight: sourceAxis }).refine(r => r.x + r.width <= r.sourceWidth && r.y + r.height <= r.sourceHeight);
+const focus = z.strictObject({ revision: positive, region: captureRegion });
+const focusRequest = z.strictObject({ commandId: id, controlGeneration: positive, mediaEpoch: u32, displayRevision: u32, focus });
+const selection = z.strictObject({ commandId: id, format, width: axis, height: axis, fpsCeiling: fps, quality, dpi: dpi.optional(), captureRegion: captureRegion.optional(), cursorVisible: z.boolean().optional() });
+const configured = z.strictObject({ commandId: id, deviceGeneration: bounded, controlGeneration: positive, mediaEpoch: u32,
+    displayRevision: u32, format, width: axis, height: axis, fpsCeiling: fps, quality, encoderBackend: bounded, rateTargetBps: positive, dpi: dpi.optional(), captureRegion: captureRegion.optional() });
+const ready = z.strictObject({ controlGeneration: positive, mediaEpoch: u32, displayRevision: u32 });
+const command = z.strictObject({ commandId: id });
+const inputBase = { controlGeneration: positive, displayRevision: u32, sequence: positive };
+const point = { x: int(0, 4095), y: int(0, 4095) };
+const text = z.string().refine(s => {
+    if (Buffer.byteLength(s) > 32768)
+        return false;
+    let scalars = 0;
+    for (const c of s) {
+        const n = c.codePointAt(0);
+        if (++scalars > 8192 || n >= 0xd800 && n <= 0xdfff || n < 32 && n !== 9 && n !== 10 || n >= 127 && n <= 159)
+            return false;
+    }
+    return true;
+});
+const input = z.discriminatedUnion('action', [
+    z.strictObject({ ...inputBase, action: z.literal('pointer'), ...point }),
+    z.strictObject({ ...inputBase, action: z.literal('button'), ...point, button: int(1, 3), down: z.boolean() }),
+    z.strictObject({ ...inputBase, action: z.literal('wheel'), ...point, wheelX: int(-120, 120), wheelY: int(-120, 120) }),
+    z.strictObject({ ...inputBase, action: z.literal('key'), usage: int(4, 231), down: z.boolean() }),
+    z.strictObject({ ...inputBase, action: z.literal('release_all') }),
+    z.strictObject({ ...inputBase, action: z.literal('text'), operationId: id, paste: z.boolean().optional(), text }),
+]);
+const held = z.strictObject({ controlGeneration: positive, displayRevision: u32, sequence: int(),
+    keys: z.array(int(4, 231)).max(228).refine(distinct), buttons: z.array(int(1, 3)).max(3).refine(distinct) });
+const inputResult = z.strictObject({ sequence: positive, outcome: z.enum(['injected', 'rejected', 'unknown']), operationId: id.nullable().optional() })
+    .refine(r => r.outcome !== 'unknown' || r.operationId != null);
+const finite = z.number().finite().min(0);
+const feedback = z.strictObject({ epoch: u32, receivedId: int(), decodedId: int(), presentedId: int(), receivedTotalBytes: int(),
+    queueDepth: int(0, 2), queueAgeMs: finite, decodeMs: finite, presentMs: finite, exactPresentedSequence: int() }).refine(f => f.receivedId >= f.decodedId && f.decodedId >= f.presentedId);
+const resizeResult = z.strictObject({ commandId: id, width: axis, height: axis, displayRevision: u32, outcome: z.enum(['applied', 'rolled_back', 'failed']), dpi: dpi.optional(), captureRegion: captureRegion.optional() });
+export const desktopErrorCodeSchema = z.enum(['unavailable', 'unknown_capability', 'unsupported_protocol', 'unsupported_client',
+    'permission_required', 'busy', 'conflict', 'invalid_request', 'rate_limited', 'startup_timeout', 'encoder_failed', 'decoder_failed',
+    'resize_failed', 'transport_failed', 'authorization_lost', 'takeover_lost']);
+const state = z.enum(['REQUESTED', 'PREPARING', 'NEGOTIATING', 'STARTING', 'ACTIVE', 'RECONFIGURING', 'SUSPENDED', 'RECONNECTING', 'FAILED', 'CLOSED']);
+const clipboardChunk = { controlGeneration: positive, requestId: id, revision: int().default(0), offset: int(0, 1048576).default(0),
+    total: int(0, 1048576).default(0), data: z.string().max(10924).default('') };
+const validClipboardChunk = (v) => {
+    const bytes = Buffer.from(v.data, 'base64');
+    return bytes.length <= 8192 && v.offset + bytes.length <= v.total && bytes.toString('base64') === v.data;
+};
+const clipboardRequest = z.strictObject({ ...clipboardChunk, action: z.enum(['read', 'write', 'paste']) })
+    .refine(v => validClipboardChunk(v) && (v.action === 'write' || v.data === '' && (v.action !== 'paste' || v.offset === 0 && v.total === 0)));
+const clipboardResult = z.strictObject({ ...clipboardChunk, outcome: z.enum(['ok', 'pending', 'conflict', 'unavailable']) })
+    .refine(validClipboardChunk);
+const cacheDependency = z.strictObject({ commandId: id, controlGeneration: positive, mediaEpoch: u32, displayRevision: u32,
+    frameId: positive, exactSequence: positive, cacheId: positive, width: int(1, 32), height: int(1, 32) });
+const cacheDependencyResult = z.strictObject({ request: cacheDependency, pixels: z.string().max(5464) }).refine(v => {
+    const pixels = Buffer.from(v.pixels, 'base64');
+    return pixels.toString('base64') === v.pixels && pixels.length === v.request.width * v.request.height * 4 &&
+        pixels.every((byte, i) => i % 4 !== 3 || byte === 255);
+});
+const motionCut = { commandId: id, controlGeneration: positive, mediaEpoch: u32, displayRevision: u32 };
+const motionCutPrepared = { ...motionCut, cutId: positive, pictureThrough: int(0, 0xffffffff), frameThrough: positive };
+const payloadSchemas = {
+    audio_select: z.strictObject({ commandId: id, mode: audioMode }),
+    audio_ready: z.strictObject({ commandId: id, audioEpoch: u32 }),
+    audio_configured: audioConfiguration,
+    audio_state: z.strictObject({ commandId: id, state: z.enum(['off', 'buffering', 'playing', 'unavailable', 'suspended']), reason: z.string().regex(/^[a-z0-9_]{1,128}$/).nullable().default(null) }),
+    audio_feedback: z.strictObject({ audioEpoch: u32, receivedPackets: int(), latePackets: int(), lostPackets: int(), playedSample: int(), queueAgeMs: z.number().finite().min(0).max(10000), underruns: int() }),
+    focus: focusRequest,
+    cache_dependency: cacheDependency, cache_dependency_result: cacheDependencyResult,
+    focus_result: focusRequest.extend({ outcome: z.enum(['applied', 'failed']) }),
+    motion_cut_barrier: z.strictObject(motionCutPrepared),
+    motion_cut_request: z.strictObject(motionCut),
+    motion_cut_prepare: z.strictObject({ ...motionCut, cutId: positive }),
+    motion_cut_prepared: z.strictObject(motionCutPrepared),
+    motion_cut_fence: z.strictObject({ ...motionCutPrepared, motionCommittedBytes: int() }),
+    motion_cut_ack: z.strictObject({ ...motionCut, cutId: positive }),
+    motion_cut_commit: z.strictObject({ ...motionCut, cutId: positive }),
+    clipboard_request: clipboardRequest, clipboard_result: clipboardResult,
+    offer: desktopCapabilitiesSchema, select: selection, configured, viewer_ready: ready, decoder_ready: ready,
+    cursor_visibility: z.strictObject({ commandId: id, visible: z.boolean() }),
+    cursor_visibility_result: z.strictObject({ commandId: id, visible: z.boolean(), outcome: z.enum(['applied', 'failed']), mediaEpoch: int().default(0), afterFrameId: int().default(0) }),
+    appearance: z.strictObject({ commandId: id, colorScheme: z.enum(['light', 'dark']) }),
+    appearance_result: z.strictObject({ commandId: id, colorScheme: z.enum(['light', 'dark']), outcome: z.enum(['applied', 'failed']) }),
+    start: command, request_refresh: command, suspend: command, resume: command, stop: command, media_open: command,
+    input, held_state: held, input_result: inputResult, feedback,
+    credit: z.strictObject({ epoch: u32, motionConsumedBytes: int(), cursorConsumedBytes: int(), exactConsumedBytes: int(), windowBytes: int(196608, 524288) }).refine(v => Number.isSafeInteger(v.motionConsumedBytes + v.cursorConsumedBytes + v.exactConsumedBytes)),
+    ping: z.strictObject({ challenge: bounded }), pong: z.strictObject({ challenge: bounded }),
+    resize: z.strictObject({ commandId: id, expectedDisplayRevision: u32, width: axis, height: axis, dpi: dpi.optional(), captureRegion: captureRegion.optional() }), resize_result: resizeResult,
+    state: z.strictObject({ state, code: desktopErrorCodeSchema.nullable().optional() }),
+    error: z.strictObject({ code: desktopErrorCodeSchema, retryable: z.boolean() }),
+};
+export function supportsDesktopMode(display, width, height) {
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 2 || height < 2 || width > 4096 || height > 4096 || width % 2 || height % 2)
+        return false;
+    if (width === display.width && height === display.height)
+        return true;
+    const range = display.resizeRange;
+    if (display.resize === 'dynamic')
+        return range != null && width >= range.minWidth && width <= range.maxWidth && height >= range.minHeight && height <= range.maxHeight;
+    return display.resize === 'modes' && display.modes.some(m => m.width === width && m.height === height);
+}
+const viewer = z.strictObject({ protocols, formats, maxWidth: axis, maxHeight: axis, maxPixels: int(4, 16777216), maxFps: fps, maxDpi: dpi.optional(), appearanceSync: z.boolean().optional(), clipboard: z.boolean().optional(), overview: z.boolean().optional(), cursorControl: z.boolean().optional() });
+const sessionRequest = z.strictObject({ requestId: id, displayId: id, viewer,
+    viewport: z.strictObject({ widthDp: z.number().positive().max(16384), heightDp: z.number().positive().max(16384),
+        deviceScale: z.number().min(0.5).max(8), orientation: z.enum(['landscape', 'portrait']) }),
+    resolution: z.discriminatedUnion('mode', [z.strictObject({ mode: z.literal('fit') }), z.strictObject({ mode: z.literal('fixed'), width: axis, height: axis })]),
+    quality, takeover: z.boolean().default(false), lobbyId: id.optional(), planId: id.optional(), mediaTransport: z.enum(['quic', 'wss']).optional() })
+    .refine(request => (request.lobbyId == null) === (request.planId == null) && (request.lobbyId == null) === (request.mediaTransport == null));
+const desktopManagementSchema = z.discriminatedUnion('t', [
+    z.strictObject({ t: z.literal('desktop_lobby'), commandId: id, lobbyId: id, deviceGeneration: bounded, request: z.lazy(() => lobbyRequestSchema),
+        wssProbeGrant: z.string().regex(/^[A-Za-z0-9_-]{43}$/).nullish(), quicProbeGrant: z.string().regex(/^[A-Za-z0-9_-]{43}$/).nullish(),
+        quic: z.strictObject({ port: int(1, 65535), certificate: z.string().min(64).max(2048) }).nullish() }),
+    z.strictObject({ t: z.literal('desktop_background'), commandId: id, lobbyId: id, deviceGeneration: bounded,
+        planId: id, revision: positive, targetId: id, grant: z.string().regex(/^[A-Za-z0-9_-]{43}$/),
+        cachedVersion: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/).nullish() }),
+    z.strictObject({ t: z.literal('desktop_lobby_result'), commandId: id, lobbyId: id, deviceGeneration: bounded,
+        plan: z.lazy(() => lobbyPlanSchema).nullable(), code: desktopErrorCodeSchema.nullable() }),
+    z.strictObject({ t: z.literal('workstation_capabilities'), ...capabilityReportSchema.shape }),
+    z.strictObject({ t: z.literal('workstation_capabilities_request'), generation: bounded }),
+    z.strictObject({ t: z.literal('desktop_prepare'), commandId: id, sessionId: id, displayId: id,
+        deviceGeneration: bounded, controlGeneration: positive, controlGrant: z.string().regex(/^[A-Za-z0-9_-]{43}$/),
+        candidate: z.boolean().optional(), mediaTransport: z.enum(['quic', 'wss']).optional() }),
+    z.strictObject({ t: z.literal('desktop_prepare_result'), commandId: id, sessionId: id,
+        state: z.enum(['bound', 'failed']), code: desktopErrorCodeSchema.nullable() }),
+    z.strictObject({ t: z.literal('desktop_cancel'), commandId: id, sessionId: id, controlGeneration: positive, code: desktopErrorCodeSchema }),
+    z.strictObject({ t: z.literal('desktop_session_state'), sessionId: id, controlGeneration: positive, state, code: desktopErrorCodeSchema.nullable() }),
+]);
+export function decodeDesktopManagementFrame(source, from) {
+    const frame = checked(desktopManagementSchema, source);
+    const sender = ['desktop_lobby_result', 'workstation_capabilities', 'desktop_prepare_result', 'desktop_session_state'].includes(frame.t) ? 'device' : 'server';
+    if (from && from !== sender)
+        return invalid();
+    return frame;
+}
+const authors = {
+    motion_cut_barrier: ['device', 'server'], motion_cut_request: ['viewer', 'device'], motion_cut_prepare: ['server'], motion_cut_prepared: ['device'], motion_cut_fence: ['server'], motion_cut_ack: ['viewer'], motion_cut_commit: ['server'],
+    cursor_visibility: ['viewer'], cursor_visibility_result: ['device'], appearance: ['viewer'], appearance_result: ['device'],
+    audio_select: ['viewer'], audio_ready: ['viewer'], audio_feedback: ['viewer'], audio_configured: ['device'], audio_state: ['device'],
+    clipboard_result: ['device'], clipboard_request: ['viewer'],
+    cache_dependency: ['viewer'], cache_dependency_result: ['device'], focus_result: ['device'], offer: ['device'], configured: ['device'], input_result: ['device'], resize_result: ['device'], media_open: ['device'],
+    select: ['viewer'], viewer_ready: ['viewer'], decoder_ready: ['viewer'], input: ['viewer'], held_state: ['viewer'],
+    focus: ['viewer'], feedback: ['viewer'], resize: ['viewer'], request_refresh: ['viewer'], suspend: ['viewer'], resume: ['viewer'], stop: ['viewer'],
+    start: ['server'], state: ['device', 'server'], error: ['device', 'server'],
+};
+/** JSON.parse runs only after a lexical pass checks duplicate decoded keys and exact integer tokens. */
+export function parseDesktopJson(source, limit = DESKTOP_MAX_JSON_BYTES, integerFields) {
+    if (typeof source !== 'string' && source.byteLength > limit)
+        invalid();
+    const value = typeof source === 'string' ? source : new TextDecoder('utf-8', { fatal: true }).decode(source);
+    if (Buffer.byteLength(value) > limit)
+        invalid();
+    let offset = 0;
+    const space = () => { while (/[ \t\r\n]/.test(value[offset] ?? '\0'))
+        offset++; };
+    const take = (c) => { space(); if (value[offset] !== c)
+        return false; offset++; return true; };
+    const string = () => {
+        space();
+        const start = offset;
+        if (!take('"'))
+            return invalid();
+        while (offset < value.length) {
+            const c = value[offset++];
+            if (c === '\\')
+                offset++;
+            else if (c === '"')
+                return JSON.parse(value.slice(start, offset));
+        }
+        return invalid();
+    };
+    const floatFields = new Set(['widthDp', 'heightDp', 'deviceScale', 'capturePixelScale', 'queueAgeMs', 'decodeMs', 'presentMs']);
+    const visit = (depth, field = '') => {
+        if (depth > 32)
+            invalid();
+        space();
+        if (take('{')) {
+            const keys = new Set();
+            if (take('}'))
+                return;
+            do {
+                const key = string();
+                if (keys.has(key) || !take(':'))
+                    invalid();
+                keys.add(key);
+                visit(depth + 1, key);
+            } while (take(','));
+            if (!take('}'))
+                invalid();
+        }
+        else if (take('[')) {
+            if (take(']'))
+                return;
+            do {
+                visit(depth + 1, field);
+            } while (take(','));
+            if (!take(']'))
+                invalid();
+        }
+        else if (value[offset] === '"') {
+            string();
+        }
+        else {
+            const start = offset;
+            while (offset < value.length && !/[,\]} \t\r\n]/.test(value[offset]))
+                offset++;
+            const token = value.slice(start, offset);
+            if (/^-?[0-9]/.test(token) && (integerFields ? integerFields.has(field) : !floatFields.has(field))) {
+                if (!/^-?(0|[1-9][0-9]*)$/.test(token) || !Number.isSafeInteger(Number(token)))
+                    invalid();
+            }
+            if (!token)
+                invalid();
+        }
+    };
+    visit(0);
+    space();
+    if (offset !== value.length)
+        invalid();
+    return JSON.parse(value);
+}
+function checked(schema, source) {
+    try {
+        return schema.parse(parseDesktopJson(source));
+    }
+    catch {
+        return invalid();
+    }
+}
+export function decodeCapabilityReport(source) { return checked(capabilityReportSchema, source); }
+export function decodeDesktopSessionRequest(source) { return checked(sessionRequest, source); }
+export function decodeDesktopControl(source, from) {
+    try {
+        const envelope = z.strictObject({ v: z.literal(1), type: z.string(), sessionId: id, payload: z.unknown() }).parse(parseDesktopJson(source));
+        if (!Object.hasOwn(payloadSchemas, envelope.type))
+            return invalid();
+        const type = envelope.type;
+        if (from && authors[type] && !authors[type].includes(from))
+            return invalid();
+        return { ...envelope, type, payload: payloadSchemas[type].parse(envelope.payload) };
+    }
+    catch {
+        return invalid();
+    }
+}
+export function encodeDesktopControl(message) {
+    const text = JSON.stringify(message);
+    decodeDesktopControl(text);
+    return text;
+}
+export function canonicalDesktopJson(value) {
+    return JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+        ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b))) : item);
+}

package/dist/workstation/desktopControl/quicMedia.js

@@ -0,0 +1,240 @@
+import { spawn } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { once } from 'node:events';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { bounded, DesktopQueue, NativeCommandError } from './helperProcess.js';
+import { mediaRequire } from './media.js';
+import { decodeQuicPathStats } from './networkEvidence.js';
+const safeU64 = (b, offset) => { const n = b.readBigUInt64BE(offset); mediaRequire(n <= BigInt(Number.MAX_SAFE_INTEGER)); return Number(n); };
+export function decodeQuicCutEvent(bytes) {
+    mediaRequire(bytes.length === 48 && bytes[0] === 1 && bytes[1] >= 1 && bytes[1] <= 6 && bytes[2] <= 7 && bytes[3] === 0 && bytes.readUInt32BE(20) === 0);
+    const value = { action: bytes[1], reason: bytes[2], epoch: bytes.readUInt32BE(4), cutId: safeU64(bytes, 8), pictureThrough: bytes.readUInt32BE(16), frameThrough: safeU64(bytes, 24), wireThrough: safeU64(bytes, 32), motionCommittedBytes: safeU64(bytes, 40) };
+    mediaRequire(value.epoch > 0 && (value.action === 1 || value.cutId > 0));
+    return value;
+}
+export class DesktopMediaAdmissionCancelled extends NativeCommandError {
+    cutId;
+    epoch;
+    pictureSequence;
+    constructor(cutId, epoch, pictureSequence) {
+        super('transport_failed');
+        this.cutId = cutId;
+        this.epoch = epoch;
+        this.pictureSequence = pictureSequence;
+    }
+}
+export const isQuicMediaQueueEvent = (kind) => kind === 1 || kind === 2 || kind === 3 || kind === 4;
+/** At most one unresolved ticket per lane, sharing the caller's existing bounded reservation. */
+export class DesktopQuicAdmission {
+    peer;
+    write;
+    pending = new Map();
+    nextId = 0n;
+    totals = new Map([[0, [0, 0, 0]]]);
+    epoch = 0;
+    dead = false;
+    cut;
+    constructor(peer, write) {
+        this.peer = peer;
+        this.write = write;
+    }
+    ownCut(id, epoch, pictureThrough) { mediaRequire(Number.isSafeInteger(id) && id > 0 && epoch > 0 && !this.cut); this.cut = { id, epoch, pictureThrough }; }
+    finishCut(id) { mediaRequire(this.cut?.id === id); this.cut = undefined; }
+    async send(kind, bytes) {
+        mediaRequire(!this.dead && (kind === 2 || kind === 3) && bytes.length > 0 && bytes.length <= 65600);
+        let lane = 255, epoch = 0, sequence = 0, payloadBytes = 0;
+        if (kind === 3) {
+            mediaRequire(bytes.length >= 65 && bytes.subarray(0, 5).equals(Buffer.from('AXDS\x01')));
+            lane = bytes[5] <= 2 ? 0 : bytes[5] <= 4 ? 1 : 2;
+            epoch = bytes.readUInt32BE(12);
+            sequence = bytes.readUInt32BE(20);
+            payloadBytes = bytes.length - 64;
+            mediaRequire(bytes[5] >= 1 && bytes[5] <= 5 && epoch > 0 && sequence > 0);
+            if (bytes[5] === 1) {
+                mediaRequire(epoch > this.epoch);
+                const oldest = [...this.totals.keys()].filter(e => e !== 0 && e !== this.epoch);
+                for (const old of oldest) {
+                    mediaRequire(![...this.pending.values()].some(p => p.epoch === old));
+                    this.totals.delete(old);
+                }
+                this.epoch = epoch;
+                if (!this.totals.has(epoch))
+                    this.totals.set(epoch, [0, 0, 0]);
+            }
+            else {
+                mediaRequire(epoch === this.epoch || this.epoch === 0);
+                if (!this.totals.has(epoch))
+                    this.totals.set(epoch, [0, 0, 0]);
+            }
+        }
+        mediaRequire(![...this.pending.values()].some(p => p.lane === lane));
+        const id = ++this.nextId;
+        mediaRequire(id <= BigInt(Number.MAX_SAFE_INTEGER));
+        const header = Buffer.alloc(21);
+        header.writeUInt32BE(bytes.length + 17);
+        header[4] = kind;
+        header.writeBigUInt64BE(this.peer, 5);
+        header.writeBigUInt64BE(id, 13);
+        return new Promise((resolve, reject) => {
+            const item = { id, kind, lane, epoch, sequence, payloadBytes, frame: Buffer.concat([header, bytes]), resolve, reject, busy: false, deadline: setTimeout(() => { this.close(new NativeCommandError('transport_failed')); }, 5000) };
+            this.pending.set(id, item);
+            void this.write(item.frame).catch(e => this.close(e));
+        });
+    }
+    accept(peer, bytes) {
+        mediaRequire(peer === this.peer && bytes.length === 32 && bytes.readUInt16BE(10) === 0 && bytes.readUInt32BE(20) === 0);
+        const id = bytes.readBigUInt64BE(), p = this.pending.get(id);
+        mediaRequire(p && bytes[8] >= 1 && bytes[8] <= 3 && bytes[9] === p.lane && bytes.readUInt32BE(12) === p.epoch && bytes.readUInt32BE(16) === p.sequence);
+        const total = safeU64(bytes, 24), previous = p.lane === 255 ? 0 : this.totals.get(p.epoch)[p.lane];
+        mediaRequire(total === previous + (bytes[8] === 1 ? p.payloadBytes : 0));
+        if (bytes[8] === 3) {
+            mediaRequire(!p.busy);
+            p.busy = true;
+            p.timer = setTimeout(() => { p.busy = false; if (this.pending.get(id) === p)
+                void this.write(p.frame).catch(e => this.close(e)); }, 10);
+            return;
+        }
+        if (bytes[8] === 2)
+            mediaRequire(p.lane === 0 && this.cut && p.epoch === this.cut.epoch && p.sequence <= this.cut.pictureThrough);
+        this.pending.delete(id);
+        clearTimeout(p.deadline);
+        clearTimeout(p.timer);
+        if (bytes[8] === 1) {
+            if (p.lane !== 255)
+                this.totals.get(p.epoch)[p.lane] = total;
+            p.resolve();
+        }
+        else
+            p.reject(new DesktopMediaAdmissionCancelled(this.cut.id, p.epoch, p.sequence));
+    }
+    close(error = new NativeCommandError('transport_failed')) { this.dead = true; for (const p of this.pending.values()) {
+        clearTimeout(p.deadline);
+        clearTimeout(p.timer);
+        p.reject(error);
+    } this.pending.clear(); }
+}
+/** The subprocess is a platform build of the same Rust engine embedded by native viewers. */
+export async function openQuicMedia(server, offer, signal, current) {
+    const packaged = fileURLToPath(new URL(`../../native/${process.platform}-${process.arch}/axom-quic`, import.meta.url));
+    const candidates = [...(process.env.AXOM_QUIC_BINARY ? [process.env.AXOM_QUIC_BINARY] : []), packaged, path.join(homedir(), '.axom/workstation/quic', `${process.platform}-${process.arch}`, 'axom-quic'), '/usr/local/bin/axom-quic'];
+    const executable = await (async () => { for (const file of candidates) {
+        try {
+            await access(file);
+            return file;
+        }
+        catch { }
+    } return undefined; })();
+    if (!executable)
+        return undefined;
+    const child = spawn(executable, [], { stdio: ['pipe', 'pipe', 'ignore'] });
+    const queue = new DesktopQueue();
+    const events = queue[Symbol.asyncIterator]();
+    let buffer = Buffer.alloc(0), peer = 0n, dead = false, transportBytes = 0;
+    let pathStats;
+    let admission;
+    const cuts = new DesktopQueue(16);
+    const close = () => { if (dead)
+        return; dead = true; child.stdin.destroy(); child.kill(); admission?.close(); queue.close(); cuts.close(); signal.removeEventListener('abort', close); };
+    const closed = new Promise(resolve => child.once('close', () => { close(); resolve(); }));
+    signal.addEventListener('abort', close, { once: true });
+    child.once('error', close);
+    child.stdin.on('error', close);
+    if (signal.aborted)
+        close();
+    child.stdout.on('data', (bytes) => {
+        try {
+            mediaRequire(buffer.length + bytes.length <= 2 * 65613);
+            buffer = Buffer.concat([buffer, bytes]);
+            while (buffer.length >= 4) {
+                const length = buffer.readUInt32BE();
+                mediaRequire(length >= 9 && length <= 65609);
+                if (buffer.length < length + 4)
+                    break;
+                const frame = buffer.subarray(4, 4 + length);
+                buffer = buffer.subarray(4 + length);
+                const kind = frame[0], eventPeer = frame.readBigUInt64BE(1), payload = Buffer.from(frame.subarray(9));
+                if (kind === 1) {
+                    mediaRequire(peer === 0n && eventPeer > 0n);
+                    peer = eventPeer;
+                }
+                if (kind === 9) {
+                    mediaRequire(eventPeer === peer && payload.length === 8);
+                    const total = safeU64(payload, 0);
+                    mediaRequire(total >= transportBytes);
+                    transportBytes = total;
+                }
+                else if (kind === 10) {
+                    mediaRequire(eventPeer === peer);
+                    const next = decodeQuicPathStats(payload, performance.now());
+                    mediaRequire(!pathStats || next.sequence > pathStats.sequence && next.pathGeneration >= pathStats.pathGeneration);
+                    pathStats = next;
+                }
+                else if (kind === 8) {
+                    mediaRequire(admission);
+                    admission.accept(eventPeer, payload);
+                }
+                else if (kind === 7) {
+                    mediaRequire(eventPeer === peer);
+                    cuts.push(decodeQuicCutEvent(payload));
+                }
+                else if (isQuicMediaQueueEvent(kind))
+                    queue.push({ kind, peer: eventPeer, bytes: payload });
+                // Native event extensions belong to their own lanes. Never let an
+                // unrecognized event become an AXDS media packet and retire the RD session.
+            }
+        }
+        catch {
+            close();
+        }
+    });
+    const write = async (bytes) => { mediaRequire(current() && !signal.aborted && !dead); if (!child.stdin.write(bytes))
+        await bounded(once(child.stdin, 'drain'), 2000); };
+    try {
+        const config = Buffer.from(JSON.stringify({ mode: 'client', host: new URL(server).hostname.replace(/^\[|\]$/g, ''), port: offer.port, certificate: offer.certificate }));
+        const header = Buffer.alloc(4);
+        header.writeUInt32BE(config.length);
+        await write(Buffer.concat([header, config]));
+        const ready = await bounded(events.next(), 1800);
+        mediaRequire(!ready.done && ready.value.kind === 1);
+        peer = ready.value.peer;
+        admission = new DesktopQuicAdmission(peer, write);
+    }
+    catch (error) {
+        close();
+        if (signal.aborted)
+            throw error;
+        return undefined;
+    }
+    const send = (kind, bytes) => admission.send(kind, bytes);
+    const sendAudio = async (bytes) => {
+        mediaRequire(bytes.length >= 41 && bytes.length <= 1040 && bytes.subarray(0, 4).equals(Buffer.from('AXDA')));
+        if (!current() || signal.aborted || dead || child.stdin.writableLength > 4096)
+            return false;
+        const frame = Buffer.alloc(21);
+        frame.writeUInt32BE(17 + bytes.length);
+        frame[4] = 12;
+        frame.writeBigUInt64BE(peer, 5);
+        child.stdin.write(Buffer.concat([frame, bytes]));
+        return true;
+    };
+    const cutCommand = async (kind, cutId, epoch, pictureThrough = 0, frameThrough = 0) => {
+        mediaRequire(Number.isSafeInteger(cutId) && cutId > 0 && Number.isInteger(epoch) && epoch > 0);
+        const payload = Buffer.alloc(kind === 9 ? 16 : 4);
+        payload.writeUInt32BE(epoch);
+        if (kind === 9) {
+            payload.writeUInt32BE(pictureThrough, 4);
+            payload.writeBigUInt64BE(BigInt(frameThrough), 8);
+            admission.ownCut(cutId, epoch, pictureThrough);
+        }
+        const frame = Buffer.alloc(21);
+        frame.writeUInt32BE(17 + payload.length);
+        frame[4] = kind;
+        frame.writeBigUInt64BE(peer, 5);
+        frame.writeBigUInt64BE(BigInt(cutId), 13);
+        await write(Buffer.concat([frame, payload]));
+    };
+    return { send, sendAudio, close, closed, transportCost: () => transportBytes, pathStats: () => pathStats, cutEvents: cuts, cutCommand, finishCut: (id) => admission.finishCut(id), receive: async (timeoutMs = 0) => { const event = timeoutMs ? await bounded(events.next(), timeoutMs) : await events.next(); if (event.done || event.value.kind === 4)
+            throw new NativeCommandError('transport_failed'); return event.value; } };
+}