castle-web-cli 0.4.214 → 0.4.215

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,3 +1,4 @@
1
+ import type { Json } from "../types";
1
2
  export type MultiplayerSessionMode = "named" | "party" | "public";
2
3
  export interface PlayerIdentity {
3
4
  userId: string;
@@ -11,6 +12,15 @@ export interface PlatformSessionConfig {
11
12
  readonly mode: MultiplayerSessionMode;
12
13
  readonly tickRate: number;
13
14
  readonly maxPlayers: number;
15
+ readonly world?: PlatformWorldSnapshot;
16
+ }
17
+ export interface PlatformWorldCheckpoint {
18
+ version: number;
19
+ value: Json;
20
+ }
21
+ export interface PlatformWorldSnapshot {
22
+ revision: string;
23
+ checkpoint: PlatformWorldCheckpoint | null;
14
24
  }
15
25
  export interface PlatformHandle {
16
26
  send(connId: string, text: string): void;
@@ -24,6 +34,9 @@ export interface PlatformHandle {
24
34
  on(event: "binaryMessage", callback: (connId: string, bytes: Uint8Array) => unknown): void;
25
35
  on(event: "replaced", callback: () => unknown): void;
26
36
  on(event: "shutdown", callback: (reason?: string) => unknown): void;
37
+ on(event: "worldCharacterTurn", callback: (request: PlatformWorldCharacterTurn) => unknown): void;
38
+ on(event: "worldCharacterCommand", callback: (request: PlatformWorldCharacterCommand) => unknown): void;
39
+ on(event: "worldCharacterRead", callback: (request: PlatformWorldCharacterRead) => unknown): void;
27
40
  /**
28
41
  * Deck storage. Strings in and strings out, like the rest of this handle, so a
29
42
  * runtime other than the Node shim can implement it without knowing what storage is.
@@ -34,5 +47,46 @@ export interface PlatformHandle {
34
47
  storage?(op: string, argsJson: string): Promise<string>;
35
48
  /** False when the host cannot broker storage, so a call can fail at once. */
36
49
  readonly storageEnabled?: boolean;
50
+ /** Persistent-world checkpoint broker. The host stamps the hidden world binding. */
51
+ worldCheckpointRead?(): Promise<string>;
52
+ worldCheckpointCommit?(argsJson: string): Promise<string>;
53
+ worldCharacterSend?(grantId: string): Promise<string>;
54
+ worldCharacterCommand?(grantId: string): Promise<string>;
55
+ worldCharacterRead?(grantId: string): Promise<string>;
56
+ worldCharacterReject?(grantId: string, code?: string): void;
37
57
  readonly config: PlatformSessionConfig;
38
58
  }
59
+ export interface PlatformWorldCharacterCommand {
60
+ grantId: string;
61
+ requestId: string;
62
+ operationId: string;
63
+ speaker: PlayerIdentity & {
64
+ playerId: string;
65
+ };
66
+ command: unknown;
67
+ }
68
+ export interface PlatformWorldCharacterRead {
69
+ grantId: string;
70
+ requestId: string;
71
+ speaker: PlayerIdentity & {
72
+ playerId: string;
73
+ };
74
+ query: unknown;
75
+ }
76
+ export interface PlatformWorldCharacterTurn {
77
+ grantId: string;
78
+ requestId: string;
79
+ operationId: string;
80
+ speaker: PlayerIdentity & {
81
+ playerId: string;
82
+ };
83
+ characterId: string;
84
+ input: string;
85
+ audience: {
86
+ disclosure: "participants" | "world";
87
+ players: Array<PlayerIdentity & {
88
+ playerId: string;
89
+ }>;
90
+ characterIds: string[];
91
+ };
92
+ }
@@ -1,6 +1,7 @@
1
1
  import type { MultiplayerSessionMode, PlatformHandle, PlayerIdentity } from "./platformHandle";
2
+ import type { Json } from "../types";
2
3
  import { type ServerStorage } from "./storage";
3
- export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, PlayerIdentity, } from "./platformHandle";
4
+ export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, PlatformWorldCheckpoint, PlatformWorldSnapshot, PlayerIdentity, } from "./platformHandle";
4
5
  export type { CharacterKnowledgeSource, CompleteCharacterBeatInput, DeliverCharacterKnowledgeInput, RecordCharacterEventInput, SetCharacterGameStateInput, ShareCharacterClaimInput, ServerStorage, ServerStorageBoard, ServerStorageBoardScore, ServerStorageListEntry, ServerStorageListOptions, ServerStorageListPage, ServerPlaythrough, ServerPlaythroughCharacters, ServerCharacterHistoryOptions, ServerStorageScope, } from "./storage";
5
6
  export interface MultiplayerServerPlayer extends PlayerIdentity {
6
7
  playerId: string;
@@ -18,12 +19,86 @@ export interface MultiplayerServerSession {
18
19
  * when its last player leaves and its memory goes with it.
19
20
  */
20
21
  readonly storage: ServerStorage;
22
+ /** A durable checkpoint for an opted-in persistent destination. */
23
+ readonly world: MultiplayerServerWorld | null;
21
24
  /** Sends bytes as a binary message and all other payloads as JSON. */
22
25
  send(playerId: string, data: unknown): void;
23
26
  /** Broadcasts bytes as a binary message and all other payloads as JSON. */
24
27
  broadcast(data: unknown, options?: MultiplayerBroadcastOptions): void;
25
28
  disconnect(playerId: string, reason?: string): void;
26
29
  }
30
+ export interface MultiplayerWorldCheckpoint {
31
+ version: number;
32
+ value: Json;
33
+ }
34
+ export interface MultiplayerWorldSnapshot {
35
+ revision: string;
36
+ checkpoint: MultiplayerWorldCheckpoint | null;
37
+ }
38
+ export interface MultiplayerWorldCommitInput {
39
+ expectedRevision: string;
40
+ operationId: string;
41
+ checkpoint: MultiplayerWorldCheckpoint;
42
+ }
43
+ export interface MultiplayerWorldCommitReceipt {
44
+ revision: string;
45
+ replayed: boolean;
46
+ operationId: string;
47
+ }
48
+ export interface MultiplayerServerWorld {
49
+ /** The checkpoint acquired before this runtime started. */
50
+ readonly snapshot: MultiplayerWorldSnapshot;
51
+ /** Reads the latest durable checkpoint, for example after a revision conflict. */
52
+ read(): Promise<MultiplayerWorldSnapshot>;
53
+ /** Commits exactly against expectedRevision; conflicts never partially write. */
54
+ commit(input: MultiplayerWorldCommitInput): Promise<MultiplayerWorldCommitReceipt>;
55
+ readonly characters: MultiplayerServerWorldCharacters;
56
+ }
57
+ export interface MultiplayerServerWorldCharacters {
58
+ publicInspect<T = unknown>(): Promise<T>;
59
+ publicRelay(input: {
60
+ operationId: string;
61
+ sourceId: string;
62
+ transmittingCharacterId: string;
63
+ recipientCharacterIds: string[];
64
+ }): Promise<unknown>;
65
+ }
66
+ export interface MultiplayerWorldCharacterCommandRequest {
67
+ readonly requestId: string;
68
+ readonly operationId: string;
69
+ readonly speaker: MultiplayerServerPlayer;
70
+ readonly command: Readonly<Record<string, unknown>>;
71
+ apply(): Promise<unknown>;
72
+ reject(code?: string): void;
73
+ }
74
+ export interface MultiplayerWorldCharacterReadRequest {
75
+ readonly requestId: string;
76
+ readonly speaker: MultiplayerServerPlayer;
77
+ readonly query: Readonly<Record<string, unknown>>;
78
+ read<T = unknown>(): Promise<T>;
79
+ reject(code?: string): void;
80
+ }
81
+ export interface MultiplayerWorldCharacterAdmission {
82
+ operationId: string;
83
+ status: "queued" | "completed" | "interrupted";
84
+ replayed: boolean;
85
+ }
86
+ export interface MultiplayerWorldCharacterTurn {
87
+ readonly requestId: string;
88
+ readonly operationId: string;
89
+ readonly speaker: MultiplayerServerPlayer;
90
+ readonly characterId: string;
91
+ readonly input: string;
92
+ readonly audience: {
93
+ readonly disclosure: "participants" | "world";
94
+ readonly players: readonly MultiplayerServerPlayer[];
95
+ readonly characterIds: readonly string[];
96
+ };
97
+ /** Durably admits the exact host-authorized request. No arguments can broaden it. */
98
+ send(): Promise<MultiplayerWorldCharacterAdmission>;
99
+ /** Explicitly rejects the request before admission. */
100
+ reject(code?: string): void;
101
+ }
27
102
  type CallbackResult = unknown;
28
103
  export interface MultiplayerServerCallbacks {
29
104
  onStart?: (session: MultiplayerServerSession) => CallbackResult;
@@ -31,6 +106,9 @@ export interface MultiplayerServerCallbacks {
31
106
  onPlayerLeave?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
32
107
  /** Receives binary messages as Uint8Array values and JSON messages otherwise. */
33
108
  onMessage?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer, data: unknown) => CallbackResult;
109
+ onWorldCharacterTurn?: (session: MultiplayerServerSession, turn: MultiplayerWorldCharacterTurn) => CallbackResult;
110
+ onWorldCharacterCommand?: (session: MultiplayerServerSession, request: MultiplayerWorldCharacterCommandRequest) => CallbackResult;
111
+ onWorldCharacterRead?: (session: MultiplayerServerSession, request: MultiplayerWorldCharacterReadRequest) => CallbackResult;
34
112
  onTick?: (session: MultiplayerServerSession) => CallbackResult;
35
113
  onReplaced?: (session: MultiplayerServerSession) => CallbackResult;
36
114
  /**
@@ -1,4 +1,5 @@
1
1
  import { isBinaryPayload, toUint8Array, } from "../multiplayerProtocol";
2
+ import { encodeStorageValue } from "../storageJson";
2
3
  import { createServerStorage } from "./storage";
3
4
  // The publish bundler binds the author's default callbacks export once and
4
5
  // exports the returned one-argument function as `__castleBootSession`.
@@ -42,6 +43,147 @@ async function bootSession(platformHandle, callbacks) {
42
43
  catch {
43
44
  // Older shims may reject event names they do not recognize.
44
45
  }
46
+ if (callbacks.onWorldCharacterTurn &&
47
+ typeof platformHandle.worldCharacterSend === "function" &&
48
+ typeof platformHandle.worldCharacterReject === "function") {
49
+ platformHandle.on("worldCharacterTurn", async (raw) => {
50
+ const request = assertPlatformWorldCharacterTurn(raw);
51
+ let settled = false;
52
+ const brokerFailure = { rejection: null };
53
+ const turn = Object.freeze({
54
+ requestId: request.requestId,
55
+ operationId: request.operationId,
56
+ speaker: Object.freeze({ ...request.speaker }),
57
+ characterId: request.characterId,
58
+ input: request.input,
59
+ audience: Object.freeze({
60
+ disclosure: request.audience.disclosure,
61
+ players: Object.freeze(request.audience.players.map((player) => Object.freeze({ ...player }))),
62
+ characterIds: Object.freeze([...request.audience.characterIds]),
63
+ }),
64
+ async send() {
65
+ if (settled)
66
+ throw new TypeError("This shared character request is already settled.");
67
+ settled = true;
68
+ let rawReceipt;
69
+ try {
70
+ rawReceipt = await platformHandle.worldCharacterSend(request.grantId);
71
+ }
72
+ catch (error) {
73
+ brokerFailure.rejection = { error };
74
+ throw error;
75
+ }
76
+ return parseWorldCharacterAdmission(rawReceipt, request.operationId);
77
+ },
78
+ reject(code) {
79
+ if (settled)
80
+ return;
81
+ settled = true;
82
+ platformHandle.worldCharacterReject(request.grantId, code);
83
+ },
84
+ });
85
+ try {
86
+ await callbacks.onWorldCharacterTurn(session, turn);
87
+ }
88
+ catch (error) {
89
+ if (brokerFailure.rejection === null || brokerFailure.rejection.error !== error)
90
+ throw error;
91
+ }
92
+ finally {
93
+ if (!settled)
94
+ turn.reject();
95
+ }
96
+ });
97
+ }
98
+ if (callbacks.onWorldCharacterCommand &&
99
+ hasWorldCharacterPlatform(platformHandle, "worldCharacterCommand")) {
100
+ platformHandle.on("worldCharacterCommand", async (raw) => {
101
+ const request = assertPlatformWorldCharacterCommand(raw);
102
+ let settled = false;
103
+ const brokerFailure = { rejection: null };
104
+ const command = Object.freeze({
105
+ requestId: request.requestId,
106
+ operationId: request.operationId,
107
+ speaker: Object.freeze({ ...request.speaker }),
108
+ command: deepFreezeJsonObject(request.command),
109
+ async apply() {
110
+ if (settled)
111
+ throw new TypeError("This shared character command is already settled.");
112
+ settled = true;
113
+ let rawResult;
114
+ try {
115
+ rawResult = await platformHandle.worldCharacterCommand(request.grantId);
116
+ }
117
+ catch (error) {
118
+ brokerFailure.rejection = { error };
119
+ throw error;
120
+ }
121
+ return parseSharedCharacterJson(rawResult);
122
+ },
123
+ reject(code) {
124
+ if (settled)
125
+ return;
126
+ settled = true;
127
+ platformHandle.worldCharacterReject(request.grantId, code);
128
+ },
129
+ });
130
+ try {
131
+ await callbacks.onWorldCharacterCommand(session, command);
132
+ }
133
+ catch (error) {
134
+ if (brokerFailure.rejection === null || brokerFailure.rejection.error !== error)
135
+ throw error;
136
+ }
137
+ finally {
138
+ if (!settled)
139
+ command.reject();
140
+ }
141
+ });
142
+ }
143
+ if (callbacks.onWorldCharacterRead &&
144
+ hasWorldCharacterPlatform(platformHandle, "worldCharacterRead")) {
145
+ platformHandle.on("worldCharacterRead", async (raw) => {
146
+ const request = assertPlatformWorldCharacterRead(raw);
147
+ let settled = false;
148
+ const brokerFailure = { rejection: null };
149
+ const read = Object.freeze({
150
+ requestId: request.requestId,
151
+ speaker: Object.freeze({ ...request.speaker }),
152
+ query: deepFreezeJsonObject(request.query),
153
+ async read() {
154
+ if (settled)
155
+ throw new TypeError("This shared character read is already settled.");
156
+ settled = true;
157
+ let rawResult;
158
+ try {
159
+ rawResult = await platformHandle.worldCharacterRead(request.grantId);
160
+ }
161
+ catch (error) {
162
+ brokerFailure.rejection = { error };
163
+ throw error;
164
+ }
165
+ return parseSharedCharacterJson(rawResult);
166
+ },
167
+ reject(code) {
168
+ if (settled)
169
+ return;
170
+ settled = true;
171
+ platformHandle.worldCharacterReject(request.grantId, code);
172
+ },
173
+ });
174
+ try {
175
+ await callbacks.onWorldCharacterRead(session, read);
176
+ }
177
+ catch (error) {
178
+ if (brokerFailure.rejection === null || brokerFailure.rejection.error !== error)
179
+ throw error;
180
+ }
181
+ finally {
182
+ if (!settled)
183
+ read.reject();
184
+ }
185
+ });
186
+ }
45
187
  platformHandle.on("replaced", async () => {
46
188
  await callbacks.onReplaced?.(session);
47
189
  });
@@ -68,6 +210,7 @@ function createAuthorSession(platformHandle, players) {
68
210
  deckId: platformHandle.config.deckId,
69
211
  mode: platformHandle.config.mode,
70
212
  storage: createServerStorage(platformHandle),
213
+ world: createServerWorld(platformHandle),
71
214
  send(playerId, data) {
72
215
  if (isBinaryPayload(data)) {
73
216
  requireSendBinary(platformHandle);
@@ -106,6 +249,235 @@ function createAuthorSession(platformHandle, players) {
106
249
  },
107
250
  };
108
251
  }
252
+ const WORLD_OPERATION_ID_MAX_BYTES = 128;
253
+ const WORLD_OPERATION_ID_MAX_CHARACTERS = 120;
254
+ const WORLD_CHECKPOINT_VERSION_MAX = 2_147_483_647;
255
+ function createServerWorld(platformHandle) {
256
+ if (!platformHandle.config.world)
257
+ return null;
258
+ if (typeof platformHandle.worldCheckpointRead !== "function" ||
259
+ typeof platformHandle.worldCheckpointCommit !== "function") {
260
+ throw worldError("The persistent-world checkpoint broker is unavailable.", "read");
261
+ }
262
+ const initial = parseWorldSnapshot(platformHandle.config.world, "read");
263
+ return Object.freeze({
264
+ snapshot: initial,
265
+ characters: createServerWorldCharacters(platformHandle),
266
+ async read() {
267
+ const result = await platformHandle.worldCheckpointRead();
268
+ return parseWorldSnapshot(parsePlatformJson(result, "read"), "read");
269
+ },
270
+ async commit(input) {
271
+ const expectedRevision = assertWorldRevision(input?.expectedRevision);
272
+ const operationId = assertWorldOperationId(input?.operationId);
273
+ const checkpoint = assertWorldCheckpoint(input?.checkpoint);
274
+ const raw = await platformHandle.worldCheckpointCommit(JSON.stringify({
275
+ expectedRevision,
276
+ operationId,
277
+ checkpoint,
278
+ }));
279
+ const result = parsePlatformJson(raw, "commit");
280
+ if (typeof result.replayed !== "boolean") {
281
+ throw worldError("The platform returned an invalid commit receipt.", "commit");
282
+ }
283
+ return Object.freeze({
284
+ revision: assertWorldRevision(result.revision),
285
+ replayed: result.replayed,
286
+ operationId,
287
+ });
288
+ },
289
+ });
290
+ }
291
+ function createServerWorldCharacters(platformHandle) {
292
+ return Object.freeze({
293
+ async publicInspect() {
294
+ if (typeof platformHandle.storage !== "function") {
295
+ throw new TypeError("The shared character broker is unavailable.");
296
+ }
297
+ return parseSharedCharacterJson(await platformHandle.storage("worldCharacterPublicInspect", "{}"));
298
+ },
299
+ async publicRelay(input) {
300
+ if (typeof platformHandle.storage !== "function") {
301
+ throw new TypeError("The shared character broker is unavailable.");
302
+ }
303
+ const operationId = assertWorldOperationId(input?.operationId);
304
+ const sourceId = assertWorldCharacterId(input?.sourceId, "sourceId", 128);
305
+ const transmittingCharacterId = assertWorldCharacterId(input?.transmittingCharacterId, "transmittingCharacterId");
306
+ if (!Array.isArray(input?.recipientCharacterIds) ||
307
+ input.recipientCharacterIds.length > 3) {
308
+ throw new TypeError("session.world.characters.publicRelay: recipientCharacterIds may contain at most 3 ids.");
309
+ }
310
+ const recipientCharacterIds = input.recipientCharacterIds.map((id) => assertWorldCharacterId(id, "recipientCharacterIds"));
311
+ if (new Set(recipientCharacterIds).size !== recipientCharacterIds.length) {
312
+ throw new TypeError("session.world.characters.publicRelay: recipientCharacterIds may not contain duplicates.");
313
+ }
314
+ return parseSharedCharacterJson(await platformHandle.storage("worldCharacterPublicRelay", JSON.stringify({
315
+ operationId,
316
+ sourceId,
317
+ transmittingCharacterId,
318
+ recipientCharacterIds: recipientCharacterIds.sort(),
319
+ })));
320
+ },
321
+ });
322
+ }
323
+ function parseWorldSnapshot(value, operation) {
324
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
325
+ throw worldError("The platform returned an invalid world checkpoint.", "read");
326
+ }
327
+ const raw = value;
328
+ return Object.freeze({
329
+ revision: assertWorldRevision(raw.revision),
330
+ checkpoint: raw.checkpoint === null
331
+ ? null
332
+ : assertWorldCheckpoint(raw.checkpoint, operation),
333
+ });
334
+ }
335
+ function assertPlatformWorldCharacterTurn(value) {
336
+ if (!value ||
337
+ typeof value !== "object" ||
338
+ typeof value.grantId !== "string" ||
339
+ typeof value.requestId !== "string" ||
340
+ typeof value.operationId !== "string" ||
341
+ typeof value.characterId !== "string" ||
342
+ typeof value.input !== "string" ||
343
+ !value.speaker ||
344
+ typeof value.speaker.playerId !== "string" ||
345
+ !value.audience ||
346
+ (value.audience.disclosure !== "participants" && value.audience.disclosure !== "world") ||
347
+ !Array.isArray(value.audience.players) ||
348
+ !Array.isArray(value.audience.characterIds)) {
349
+ throw new TypeError("The platform sent an invalid shared character request.");
350
+ }
351
+ return value;
352
+ }
353
+ function assertPlatformWorldCharacterCommand(value) {
354
+ if (!value ||
355
+ typeof value !== "object" ||
356
+ typeof value.grantId !== "string" ||
357
+ typeof value.requestId !== "string" ||
358
+ typeof value.operationId !== "string" ||
359
+ !value.speaker ||
360
+ typeof value.speaker.playerId !== "string" ||
361
+ !value.command ||
362
+ typeof value.command !== "object" ||
363
+ Array.isArray(value.command)) {
364
+ throw new TypeError("The platform sent an invalid shared character command.");
365
+ }
366
+ return value;
367
+ }
368
+ function assertPlatformWorldCharacterRead(value) {
369
+ if (!value ||
370
+ typeof value !== "object" ||
371
+ typeof value.grantId !== "string" ||
372
+ typeof value.requestId !== "string" ||
373
+ !value.speaker ||
374
+ typeof value.speaker.playerId !== "string" ||
375
+ !value.query ||
376
+ typeof value.query !== "object" ||
377
+ Array.isArray(value.query)) {
378
+ throw new TypeError("The platform sent an invalid shared character read.");
379
+ }
380
+ return value;
381
+ }
382
+ function hasWorldCharacterPlatform(platformHandle, operation) {
383
+ return (typeof platformHandle[operation] === "function" &&
384
+ typeof platformHandle.worldCharacterReject === "function");
385
+ }
386
+ function deepFreezeJsonObject(value) {
387
+ const normalized = JSON.parse(JSON.stringify(value));
388
+ deepFreeze(normalized);
389
+ return normalized;
390
+ }
391
+ function deepFreeze(value) {
392
+ if (!value || typeof value !== "object")
393
+ return;
394
+ Object.freeze(value);
395
+ for (const child of Object.values(value))
396
+ deepFreeze(child);
397
+ }
398
+ function parseSharedCharacterJson(json) {
399
+ try {
400
+ return JSON.parse(json);
401
+ }
402
+ catch {
403
+ throw new TypeError("The platform returned an invalid shared character response.");
404
+ }
405
+ }
406
+ function assertWorldCharacterId(value, field, maxCharacters = 100) {
407
+ if (typeof value !== "string" ||
408
+ value.length === 0 ||
409
+ value.length > maxCharacters ||
410
+ value.includes("\0") ||
411
+ new TextEncoder().encode(value).byteLength > 128) {
412
+ throw new TypeError(`session.world.characters: ${field} must be non-empty text of at most ${maxCharacters} characters and 128 bytes.`);
413
+ }
414
+ return value;
415
+ }
416
+ function parseWorldCharacterAdmission(json, operationId) {
417
+ let value;
418
+ try {
419
+ value = JSON.parse(json);
420
+ }
421
+ catch {
422
+ throw new TypeError("The platform returned an invalid shared character receipt.");
423
+ }
424
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
425
+ throw new TypeError("The platform returned an invalid shared character receipt.");
426
+ }
427
+ const receipt = value;
428
+ if (receipt.operationId !== operationId ||
429
+ (receipt.status !== "queued" &&
430
+ receipt.status !== "completed" &&
431
+ receipt.status !== "interrupted") ||
432
+ typeof receipt.replayed !== "boolean") {
433
+ throw new TypeError("The platform returned an invalid shared character receipt.");
434
+ }
435
+ return Object.freeze({
436
+ operationId,
437
+ status: receipt.status,
438
+ replayed: receipt.replayed,
439
+ });
440
+ }
441
+ function assertWorldCheckpoint(value, operation = "commit") {
442
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
443
+ throw worldError("A world checkpoint requires version and value.", operation);
444
+ }
445
+ const raw = value;
446
+ if (!Number.isSafeInteger(raw.version) ||
447
+ raw.version < 0 ||
448
+ raw.version > WORLD_CHECKPOINT_VERSION_MAX) {
449
+ throw worldError(`A world checkpoint version must be an integer from 0 through ${WORLD_CHECKPOINT_VERSION_MAX}.`, operation);
450
+ }
451
+ const text = encodeStorageValue(raw.value, `session.world.${operation}`);
452
+ const normalized = JSON.parse(text);
453
+ return Object.freeze({ version: raw.version, value: normalized });
454
+ }
455
+ function assertWorldRevision(value) {
456
+ if (typeof value === "string" && /^(?:0|[1-9][0-9]*)$/.test(value))
457
+ return value;
458
+ throw worldError("A world checkpoint revision must be a canonical decimal string.", "commit");
459
+ }
460
+ function assertWorldOperationId(value) {
461
+ if (typeof value !== "string" ||
462
+ value.length === 0 ||
463
+ value.length > WORLD_OPERATION_ID_MAX_CHARACTERS ||
464
+ value.includes("\0") ||
465
+ new TextEncoder().encode(value).byteLength > WORLD_OPERATION_ID_MAX_BYTES) {
466
+ throw worldError(`A world checkpoint operation id must be at most ${WORLD_OPERATION_ID_MAX_CHARACTERS} characters and ${WORLD_OPERATION_ID_MAX_BYTES} bytes.`, "commit");
467
+ }
468
+ return value;
469
+ }
470
+ function parsePlatformJson(value, operation) {
471
+ try {
472
+ return JSON.parse(value);
473
+ }
474
+ catch {
475
+ throw worldError("The platform returned an invalid world checkpoint response.", operation);
476
+ }
477
+ }
478
+ function worldError(message, operation) {
479
+ return new TypeError(`session.world.${operation}: ${message}`);
480
+ }
109
481
  function requireSendBinary(platformHandle) {
110
482
  if (typeof platformHandle.sendBinary !== "function")
111
483
  unsupportedBinaryRuntime();
@@ -23,6 +23,7 @@ const INTERACTIVE_COMMANDS = new Set([
23
23
  "pass.offer",
24
24
  "snapshot.offer",
25
25
  "portal.open",
26
+ "multiplayer.joinDestination",
26
27
  // The host's voice prompt and the browser's microphone permission.
27
28
  "voice.requestJoin",
28
29
  ]);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "castle-web-cli",
3
- "version": "0.4.214",
3
+ "version": "0.4.215",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"
@@ -12,7 +12,7 @@
12
12
  "scripts": {
13
13
  "build": "rm -rf dist && tsc && chmod +x dist/index.js && vite build && vite build -c vite.cover-bridge.config.ts && cp -R src/castle-host dist/castle-host && chmod -R u+w kits 2>/dev/null; rm -rf kits && cp -R ../kits kits && chmod -R u+w kits && rm -rf kits/*/imports",
14
14
  "dev": "tsc --watch",
15
- "check": "node ../scripts/sync-shared.mjs --check && node ../scripts/tests/icon-registry.mjs && node ../scripts/tests/sandbox-graphql-fields.mjs && node ../scripts/tests/kit-package-json.mjs && node ../scripts/tests/kit-catalog.mjs && node ../scripts/tests/router-fences.mjs && node ../scripts/tests/sdk-readme-limits.mjs && node ../scripts/tests/task-account.mjs && node ../scripts/tests/effort-support.mjs && eslint . && jscpd && tsc --noEmit && tsc --noEmit -p src/shell/tsconfig.json"
15
+ "check": "node ../scripts/sync-shared.mjs --check && node ../scripts/tests/icon-registry.mjs && node ../scripts/tests/sandbox-graphql-fields.mjs && node ../scripts/tests/kit-package-json.mjs && node ../scripts/tests/kit-catalog.mjs && node ../scripts/tests/router-fences.mjs && node ../scripts/tests/router-stops.mjs && node ../scripts/tests/plan-answered-questions.mjs && node ../scripts/tests/sdk-readme-limits.mjs && node ../scripts/tests/task-account.mjs && node ../scripts/tests/effort-support.mjs && eslint . && jscpd && tsc --noEmit && tsc --noEmit -p src/shell/tsconfig.json"
16
16
  },
17
17
  "jscpd": {
18
18
  "path": [