@crowdedkingdoms/crowdyjs 15.4.2 → 15.5.0-test.1

package/README.md

@@ -174,7 +174,7 @@ never told about, so a native refresh without it is a re-placement.
    — `appId` is **required** (the SDK opens the realtime socket on demand and
    scopes it to that app).
 4. Join a chunk by sending an initial actor update.
-5. Send actor, voxel, text, audio, and client-event updates through `game.udp`
+5. Send actor, voxel, text, audio, video, and client-event updates through `game.udp`
    or the higher-level `game.world(appId)` helpers.
 6. Before the app token expires, call `game.refreshGameplayToken()`.
 7. Call `client.close()` (and `game.close()`) when disposing the SDK instances.
@@ -203,7 +203,7 @@ never told about, so a native refresh without it is a re-placement.
 | `client.marketplace` | Player-code store/install/consent flows plus player-authorized grid claims (`claimGridOwnership`, `claimGridChunk`, `releaseClaimedGrid`) and client-mod artifact fetches. |
 | `client.crowdyStudio` | Cloud project, personal-library, and common-file APIs for Crowdy Studio: target-scoped files, metadata/module names, optimistic revisions, copy-by-value imports, atomic saves. |
 | `client.crowdyStudioAgent` | Generated, app-token Game API transport for durable agent sessions: history/session pages, descriptors/budgets, approvals, tool results, heartbeat, control mutations, ordered event subscriptions. |
-| `client.udp` | UDP proxy subscriptions + spatial mutations (`sendActorUpdate`, `sendVoxelUpdate`, `sendAudioPacket`, `sendTextPacket`, `sendClientEvent`, `sendSingleActorMessage`, `sendChannelMessage`). |
+| `client.udp` | UDP proxy subscriptions + spatial mutations (`sendActorUpdate`, `sendVoxelUpdate`, `sendAudioPacket`, `sendVideoPacket` / `sendVideoFrame`, `sendTextPacket`, `sendClientEvent`, `sendSingleActorMessage`, `sendChannelMessage`). |
 | `client.realtime` | Connection status, manual `connect()` / `disconnect()`, `onStatus()` listener. |
 | `client.refreshGameplayToken()` | Safely rotates an active game client's app token (see [Token refresh](#token-refresh-during-gameplay)). |
 | `client.world(appId)` | Higher-level helpers for browser games (`actor.join`, `actor.sendState`, `actor.sendText`, `actor.sendToActor`). |
@@ -287,6 +287,16 @@ const unsubscribe = client.udp.subscribe(
     voxelUpdate: (event) => { /* ... */ },
     text: (event) => { /* ... */ },
     audio: (event) => { /* ... */ },
+    video: (event) => {
+      // One webcam fragment; feed a VideoFrameAssembler to get whole frames.
+      const frame = assembler.ingest(event.uuid, decodeBase64(event.videoData));
+      if (frame) drawJpeg(event.uuid, frame.bytes);
+    },
+    actorLeft: (event) => {
+      // The server says this actor is gone (about 5 s after its last update).
+      // World Stores do this for you: `session.actors.onLeave` fires at once.
+      removeAvatar(event.uuid);
+    },
     clientEvent: (event) => { /* ... */ },
     serverEvent: (event) => { /* ... */ },
     singleActorMessage: (event) => {
@@ -460,6 +470,9 @@ session.self.patchState({ x: 12.5, yaw: 1.57 });
 console.log(session.self.status, session.self.lastAck?.state);
 
 // Everyone else: typed, self-filtered, staleness-managed — render from it.
+// A departure the server announces (ActorLeftNotification, Buddy v0.25.0)
+// removes the actor and fires `onLeave` immediately; the 12 s reaper is the
+// fallback for a lost datagram. A later update for the same uuid is a rejoin.
 for (const actor of session.actors.list()) {
   render(actor.uuid, actor.state, actor.samples); // samples → interpolation
 }

package/dist/binary-wire.d.ts

@@ -34,6 +34,9 @@ export declare const WireMessageType: {
     readonly CLIENT_EVENT_NOTIFICATION_2: 138;
     readonly SERVER_EVENT_NOTIFICATION_2: 139;
     readonly SINGLE_ACTOR_MESSAGE: 142;
+    readonly CLIENT_VIDEO_PACKET_2: 143;
+    readonly CLIENT_VIDEO_NOTIFICATION_2: 144;
+    readonly ACTOR_LEFT_NOTIFICATION_2: 145;
 };
 /**
  * Per-session signing context: the game token id (from the relay `ready`
@@ -73,6 +76,13 @@ export declare function serializeVoxelUpdate(ctx: RelaySignContext, input: Spati
 export declare function serializeAudioPacket(ctx: RelaySignContext, input: SpatialSendBase & {
     audioData: string;
 }): Promise<Uint8Array>;
+/**
+ * One video FRAGMENT (header + body slice from `fragmentFrame`) as a 143 datagram.
+ * Defaults match audio: `distance` 1, `decayRate` 0.
+ */
+export declare function serializeVideoPacket(ctx: RelaySignContext, input: SpatialSendBase & {
+    videoData: string;
+}): Promise<Uint8Array>;
 export declare function serializeTextPacket(ctx: RelaySignContext, input: SpatialSendBase & {
     text: string;
 }): Promise<Uint8Array>;

package/dist/binary-wire.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"binary-wire.d.ts","sourceRoot":"","sources":["../src/binary-wire.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"binary-wire.d.ts","sourceRoot":"","sources":["../src/binary-wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,kEAAkE;AAClE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;CAuBlB,CAAC;AA6DX;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;IACvB,GAAG,EAAE,SAAS,CAAC;CAChB;AAED,gFAAgF;AAChF,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAU3B;AAmGD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,eAAe,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GACzC,OAAO,CAAC,UAAU,CAAC,CAYrB;AAED,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,eAAe,GAAG;IACvB,KAAK,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,GACA,OAAO,CAAC,UAAU,CAAC,CAqBrB;AAED,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,eAAe,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAC7C,OAAO,CAAC,UAAU,CAAC,CAYrB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,eAAe,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAC7C,OAAO,CAAC,UAAU,CAAC,CAYrB;AAED,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GACxC,OAAO,CAAC,UAAU,CAAC,CAYrB;AAED,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,eAAe,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC5D,OAAO,CAAC,UAAU,CAAC,CAgBrB;AAED,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE;IACL,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,GACA,OAAO,CAAC,UAAU,CAAC,CAYrB;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE;IACL,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,GACA,OAAO,CAAC,UAAU,CAAC,CAqCrB;AAyOD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,eAAe,EAAE,CA4BpE"}

package/dist/binary-wire.js

@@ -34,6 +34,11 @@ export const WireMessageType = {
     CLIENT_EVENT_NOTIFICATION_2: 138,
     SERVER_EVENT_NOTIFICATION_2: 139,
     SINGLE_ACTOR_MESSAGE: 142,
+    // Buddy v0.25.0: webcam video pair (audio's shape, payload = one SDK
+    // fragment, see media/video-frames.ts) and the server-only actor-left downlink.
+    CLIENT_VIDEO_PACKET_2: 143,
+    CLIENT_VIDEO_NOTIFICATION_2: 144,
+    ACTOR_LEFT_NOTIFICATION_2: 145,
 };
 const SPATIAL_HEADER_SIZE = 68;
 const UUID_SIZE = 32;
@@ -174,6 +179,13 @@ export function serializeVoxelUpdate(ctx, input) {
 export function serializeAudioPacket(ctx, input) {
     return serializeSpatial(ctx, WireMessageType.CLIENT_AUDIO_PACKET_2, input.appId, input.chunk, input.distance ?? 1, input.decayRate ?? 0, input.uuid, decodeBase64(input.audioData ?? ''), input.sequenceNumber ?? 0);
 }
+/**
+ * One video FRAGMENT (header + body slice from `fragmentFrame`) as a 143 datagram.
+ * Defaults match audio: `distance` 1, `decayRate` 0.
+ */
+export function serializeVideoPacket(ctx, input) {
+    return serializeSpatial(ctx, WireMessageType.CLIENT_VIDEO_PACKET_2, input.appId, input.chunk, input.distance ?? 1, input.decayRate ?? 0, input.uuid, decodeBase64(input.videoData ?? ''), input.sequenceNumber ?? 0);
+}
 export function serializeTextPacket(ctx, input) {
     return serializeSpatial(ctx, WireMessageType.CLIENT_TEXT_PACKET_2, input.appId, input.chunk, input.distance ?? 8, input.decayRate ?? 0, input.uuid, textEncoder.encode(input.text ?? ''), input.sequenceNumber ?? 0);
 }
@@ -375,6 +387,21 @@ function parseOne(bytes) {
                 ...spatialCommon(p),
                 audioData: encodeBase64(p.payload),
             };
+        case WireMessageType.CLIENT_VIDEO_NOTIFICATION_2:
+            return {
+                __typename: 'ClientVideoNotification',
+                ...spatialCommon(p),
+                videoData: encodeBase64(p.payload),
+            };
+        case WireMessageType.ACTOR_LEFT_NOTIFICATION_2: {
+            // [1B reason]; anything but 1 reads as STALE (0) per the contract.
+            const { decayRate: _r, ...rest } = spatialCommon(p);
+            return {
+                __typename: 'ActorLeftNotification',
+                ...rest,
+                leftReason: p.payload.length >= 1 && p.payload[0] === 1 ? 1 : 0,
+            };
+        }
         case WireMessageType.CLIENT_TEXT_NOTIFICATION_2:
             return {
                 __typename: 'ClientTextNotification',

package/dist/default-origin.d.ts

@@ -1,6 +1,6 @@
 /**
  * GENERATED — do not edit. The operator tooling's
- * `sync-client-origins.mjs --write --tier prod` writes this file, and
+ * `sync-client-origins.mjs --write --tier test` writes this file, and
  * `check-sdk-default-origin.mjs` refuses it when it names the wrong tier or a
  * host that declaration does not carry. Regenerate; never hand-edit.
  *
@@ -10,14 +10,14 @@
  * than no default at all. Every fallback this SDK ever removed named a host that
  * was already dead. A generated file plus a gate is what makes this one different.
  *
- * Source: the operator's per-tier public CK API origin declaration, tier 'prod'
+ * Source: the operator's per-tier public CK API origin declaration, tier 'test'
  */
 /** The tier this build of the SDK is published for. */
-export declare const CROWDY_DEFAULT_TIER = "prod";
+export declare const CROWDY_DEFAULT_TIER = "test";
 /** The public CK API origin for that tier. */
-export declare const CROWDY_DEFAULT_HTTP_ORIGIN = "https://ck.prod.crowdedkingdoms.com";
+export declare const CROWDY_DEFAULT_HTTP_ORIGIN = "https://ck.test.crowdedkingdoms.com";
 /** The same host over WebSocket. A scheme is composed; a hostname is looked up. */
-export declare const CROWDY_DEFAULT_WS_ORIGIN = "wss://ck.prod.crowdedkingdoms.com";
+export declare const CROWDY_DEFAULT_WS_ORIGIN = "wss://ck.test.crowdedkingdoms.com";
 /** The bare hostname, for callers that need to compare rather than dial. */
-export declare const CROWDY_DEFAULT_HOST = "ck.prod.crowdedkingdoms.com";
+export declare const CROWDY_DEFAULT_HOST = "ck.test.crowdedkingdoms.com";
 //# sourceMappingURL=default-origin.d.ts.map

package/dist/default-origin.js

@@ -1,6 +1,6 @@
 /**
  * GENERATED — do not edit. The operator tooling's
- * `sync-client-origins.mjs --write --tier prod` writes this file, and
+ * `sync-client-origins.mjs --write --tier test` writes this file, and
  * `check-sdk-default-origin.mjs` refuses it when it names the wrong tier or a
  * host that declaration does not carry. Regenerate; never hand-edit.
  *
@@ -10,13 +10,13 @@
  * than no default at all. Every fallback this SDK ever removed named a host that
  * was already dead. A generated file plus a gate is what makes this one different.
  *
- * Source: the operator's per-tier public CK API origin declaration, tier 'prod'
+ * Source: the operator's per-tier public CK API origin declaration, tier 'test'
  */
 /** The tier this build of the SDK is published for. */
-export const CROWDY_DEFAULT_TIER = 'prod';
+export const CROWDY_DEFAULT_TIER = 'test';
 /** The public CK API origin for that tier. */
-export const CROWDY_DEFAULT_HTTP_ORIGIN = 'https://ck.prod.crowdedkingdoms.com';
+export const CROWDY_DEFAULT_HTTP_ORIGIN = 'https://ck.test.crowdedkingdoms.com';
 /** The same host over WebSocket. A scheme is composed; a hostname is looked up. */
-export const CROWDY_DEFAULT_WS_ORIGIN = 'wss://ck.prod.crowdedkingdoms.com';
+export const CROWDY_DEFAULT_WS_ORIGIN = 'wss://ck.test.crowdedkingdoms.com';
 /** The bare hostname, for callers that need to compare rather than dial. */
-export const CROWDY_DEFAULT_HOST = 'ck.prod.crowdedkingdoms.com';
+export const CROWDY_DEFAULT_HOST = 'ck.test.crowdedkingdoms.com';

package/dist/domains/udp.d.ts

@@ -1,8 +1,9 @@
 import type { GraphQLClient } from '../client.js';
 import type { SubscriptionManager, UdpNotificationHandlers } from '../subscriptions.js';
-import { type ConnectUdpProxyMutation, type UdpProxyConnectionStatusQuery, type SendActorUpdateMutationVariables, type SendVoxelUpdateMutationVariables, type SendAudioPacketMutationVariables, type SendTextPacketMutationVariables, type SendClientEventMutationVariables, type SendSingleActorMessageMutationVariables, type SendChannelMessageMutationVariables } from '../generated/graphql.js';
+import { type ConnectUdpProxyMutation, type UdpProxyConnectionStatusQuery, type SendActorUpdateMutationVariables, type SendVoxelUpdateMutationVariables, type SendAudioPacketMutationVariables, type SendVideoPacketMutationVariables, type SendTextPacketMutationVariables, type SendClientEventMutationVariables, type SendSingleActorMessageMutationVariables, type SendChannelMessageMutationVariables } from '../generated/graphql.js';
 import type { RealtimeMetrics } from '../metrics.js';
 import type { SpatialNotification } from '../realtime.js';
+import { type VideoCodec } from '../media/video-frames.js';
 /**
  * UDP proxy access for browser-style clients that can't open raw UDP sockets.
  * Exposed as `client.udp`; for game loops prefer the ergonomic, app-scoped
@@ -250,6 +251,51 @@ export declare class UdpAPI {
     sendAudioPacketAndWait(input: SendAudioPacketMutationVariables['input'], options?: {
         timeoutMs?: number;
     }): Promise<SpatialNotification>;
+    /**
+     * Send ONE webcam video fragment, fanned out to nearby actors as a
+     * `ClientVideoNotification` (Buddy v0.25.0). Fire-and-forget; opens a UDP
+     * proxy session automatically. Gated by the `use_video_chat` runtime
+     * permission at app AND grid level — without it the game server replies
+     * asynchronously with a `GenericErrorResponse` (`errorCode` `UNAUTHORIZED`).
+     * Prefer {@link sendVideoFrame}, which fragments a whole encoded frame; this is
+     * the single-datagram primitive beneath it.
+     *
+     * On the GraphQL proxy path this is a mutation PER FRAGMENT (30–80 a second for
+     * live video). Enable `binaryTransport` so video rides the relay.
+     *
+     * @param input - {@link ClientVideoPacketInput}: `videoData` is base64 of a
+     *   6-byte fragment header plus a slice of the encoded frame (see
+     *   `fragmentFrame`); `distance` defaults to 1, `decayRate` to 0.
+     * @returns `true` when accepted for sending — **not** confirmation of delivery.
+     */
+    sendVideoPacket(input: SendVideoPacketMutationVariables['input']): Promise<boolean>;
+    /**
+     * Send one encoded webcam frame (a JPEG or WebP file) as however many
+     * fragments it needs (at most 16, ~17.8 KB), each a {@link sendVideoPacket}.
+     * Receivers reassemble with `VideoFrameAssembler`. Every receiver in range
+     * pays the egress bytes: keep `distance` at 0–1, frames small (≤ 8 KB) and
+     * the rate low (≤ 10 fps).
+     *
+     * @param input - `appId`, `chunk`, `uuid`, optional `distance` / `decayRate`,
+     *   plus `frame` (encoded bytes), `frameId` (0–65535, +1 per frame, wraps —
+     *   the caller keeps the counter) and `codec` (0 JPEG default, 1 WebP).
+     * @returns the number of fragments sent.
+     * @throws {RangeError} when the frame exceeds 16 fragments; nothing is sent.
+     */
+    sendVideoFrame(input: {
+        appId: string;
+        chunk: {
+            x: string;
+            y: string;
+            z: string;
+        };
+        uuid: string;
+        frame: Uint8Array;
+        frameId: number;
+        codec?: VideoCodec;
+        distance?: number;
+        decayRate?: number;
+    }): Promise<number>;
     /**
      * Send a spatial text/chat packet, fanned out to nearby actors as a
      * `ClientTextNotification`. Fire-and-forget; opens a UDP proxy session

package/dist/domains/udp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"udp.d.ts","sourceRoot":"","sources":["../../src/domains/udp.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"udp.d.ts","sourceRoot":"","sources":["../../src/domains/udp.ts"],"names":[],"mappings":"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"}

package/dist/domains/udp.js

@@ -1,7 +1,9 @@
-import { ConnectUdpProxyDocument, DisconnectUdpProxyDocument, UdpProxyConnectionStatusDocument, SendActorUpdateDocument, SendVoxelUpdateDocument, SendAudioPacketDocument, SendTextPacketDocument, SendClientEventDocument, SendSingleActorMessageDocument, SendChannelMessageDocument, } from '../generated/graphql.js';
+import { ConnectUdpProxyDocument, DisconnectUdpProxyDocument, UdpProxyConnectionStatusDocument, SendActorUpdateDocument, SendVoxelUpdateDocument, SendAudioPacketDocument, SendVideoPacketDocument, SendTextPacketDocument, SendClientEventDocument, SendSingleActorMessageDocument, SendChannelMessageDocument, } from '../generated/graphql.js';
 import { payloadBytesOf } from '../metrics.js';
 import { SequenceAllocator } from '../utils.js';
-import { serializeActorUpdate, serializeAudioPacket, serializeChannelMessage, serializeClientEvent, serializeSingleActorMessage, serializeTextPacket, serializeVoxelUpdate, } from '../binary-wire.js';
+import { serializeActorUpdate, serializeAudioPacket, serializeChannelMessage, serializeClientEvent, serializeSingleActorMessage, serializeTextPacket, serializeVideoPacket, serializeVoxelUpdate, } from '../binary-wire.js';
+import { fragmentFrame } from '../media/video-frames.js';
+import { encodeBase64 } from '../utils.js';
 /**
  * UDP proxy access for browser-style clients that can't open raw UDP sockets.
  * Exposed as `client.udp`; for game loops prefer the ergonomic, app-scoped
@@ -358,6 +360,61 @@ export class UdpAPI {
         await this.sendAudioPacket(request);
         return wait;
     }
+    /**
+     * Send ONE webcam video fragment, fanned out to nearby actors as a
+     * `ClientVideoNotification` (Buddy v0.25.0). Fire-and-forget; opens a UDP
+     * proxy session automatically. Gated by the `use_video_chat` runtime
+     * permission at app AND grid level — without it the game server replies
+     * asynchronously with a `GenericErrorResponse` (`errorCode` `UNAUTHORIZED`).
+     * Prefer {@link sendVideoFrame}, which fragments a whole encoded frame; this is
+     * the single-datagram primitive beneath it.
+     *
+     * On the GraphQL proxy path this is a mutation PER FRAGMENT (30–80 a second for
+     * live video). Enable `binaryTransport` so video rides the relay.
+     *
+     * @param input - {@link ClientVideoPacketInput}: `videoData` is base64 of a
+     *   6-byte fragment header plus a slice of the encoded frame (see
+     *   `fragmentFrame`); `distance` defaults to 1, `decayRate` to 0.
+     * @returns `true` when accepted for sending — **not** confirmation of delivery.
+     */
+    async sendVideoPacket(input) {
+        const viaRelay = await this.sendViaRelay((ctx) => serializeVideoPacket(ctx, input));
+        if (viaRelay !== null) {
+            this.record('video', input);
+            return viaRelay;
+        }
+        const data = await this.gql.request(SendVideoPacketDocument, { input });
+        this.record('video', input);
+        return data.sendVideoPacket;
+    }
+    /**
+     * Send one encoded webcam frame (a JPEG or WebP file) as however many
+     * fragments it needs (at most 16, ~17.8 KB), each a {@link sendVideoPacket}.
+     * Receivers reassemble with `VideoFrameAssembler`. Every receiver in range
+     * pays the egress bytes: keep `distance` at 0–1, frames small (≤ 8 KB) and
+     * the rate low (≤ 10 fps).
+     *
+     * @param input - `appId`, `chunk`, `uuid`, optional `distance` / `decayRate`,
+     *   plus `frame` (encoded bytes), `frameId` (0–65535, +1 per frame, wraps —
+     *   the caller keeps the counter) and `codec` (0 JPEG default, 1 WebP).
+     * @returns the number of fragments sent.
+     * @throws {RangeError} when the frame exceeds 16 fragments; nothing is sent.
+     */
+    async sendVideoFrame(input) {
+        const fragments = fragmentFrame(input.frame, input.frameId, input.codec);
+        for (const fragment of fragments) {
+            await this.sendVideoPacket({
+                appId: input.appId,
+                chunk: input.chunk,
+                uuid: input.uuid,
+                videoData: encodeBase64(fragment),
+                distance: input.distance,
+                decayRate: input.decayRate,
+                sequenceNumber: input.frameId & 0xff,
+            });
+        }
+        return fragments.length;
+    }
     /**
      * Send a spatial text/chat packet, fanned out to nearby actors as a
      * `ClientTextNotification`. Fire-and-forget; opens a UDP proxy session