castle-web-cli 0.4.236 → 0.4.238

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.
Files changed (218) hide show
  1. package/dist/api.d.ts +2 -0
  2. package/dist/bundle.d.ts +24 -0
  3. package/dist/bundle.js +447 -4
  4. package/dist/bundleLatin1.d.ts +6 -0
  5. package/dist/bundleLatin1.js +333 -0
  6. package/dist/castle-host/host.d.ts +10 -1
  7. package/dist/castle-host/host.js +78 -9
  8. package/dist/castleJson.d.ts +20 -0
  9. package/dist/castleJson.js +40 -0
  10. package/dist/deckExports.d.ts +35 -0
  11. package/dist/deckExports.js +365 -0
  12. package/dist/importCheckHook.d.ts +1 -0
  13. package/dist/importCheckHook.js +1 -1
  14. package/dist/index.js +5 -0
  15. package/dist/init.js +2 -1
  16. package/dist/save-deck.js +18 -13
  17. package/kits/base/castle.json +1 -1
  18. package/kits/base/sdk/README.md +47 -0
  19. package/kits/base/sdk/castle.d.ts +3 -1
  20. package/kits/base/sdk/castle.js +1 -0
  21. package/kits/base/sdk/commands.d.ts +25 -1
  22. package/kits/base/sdk/commands.js +29 -1
  23. package/kits/base/sdk/hub.d.ts +17 -0
  24. package/kits/base/sdk/hub.js +33 -9
  25. package/kits/base/sdk/localCache.d.ts +27 -0
  26. package/kits/base/sdk/localCache.js +115 -0
  27. package/kits/base/sdk/localCacheStore.d.ts +15 -0
  28. package/kits/base/sdk/localCacheStore.js +358 -0
  29. package/kits/base/sdk/transport.d.ts +1 -0
  30. package/kits/base/sdk/transport.js +4 -5
  31. package/kits/hub-game/CLAUDE.md +22 -2
  32. package/kits/hub-game/castle.json +4 -1
  33. package/kits/hub-game/code/client/act.js +66 -91
  34. package/kits/hub-game/code/client/actCore.js +134 -0
  35. package/kits/hub-game/code/client/car.js +35 -0
  36. package/kits/hub-game/code/client/chrome.js +207 -381
  37. package/kits/hub-game/code/client/crowdNames.js +2 -2
  38. package/kits/hub-game/code/client/emoteWheel.js +109 -0
  39. package/kits/hub-game/code/client/hats.js +2 -0
  40. package/kits/hub-game/code/client/hookLayer.js +99 -48
  41. package/kits/hub-game/code/client/hostGo.js +77 -0
  42. package/kits/hub-game/code/client/hubControls.js +125 -0
  43. package/kits/hub-game/code/client/hubEntry.js +187 -0
  44. package/kits/hub-game/code/client/hudSurface.js +148 -0
  45. package/kits/hub-game/code/client/hudTree.js +96 -0
  46. package/kits/hub-game/code/client/idle.js +59 -13
  47. package/kits/hub-game/code/client/invites.js +13 -4
  48. package/kits/hub-game/code/client/menuIcons.js +8 -0
  49. package/kits/hub-game/code/client/noTrips.js +38 -0
  50. package/kits/hub-game/code/client/qualityEntry.js +6 -1
  51. package/kits/hub-game/code/client/rehello.js +3 -1
  52. package/kits/hub-game/code/client/riders.js +26 -0
  53. package/kits/hub-game/code/client/role.js +79 -0
  54. package/kits/hub-game/code/client/safeLayout.js +32 -3
  55. package/kits/hub-game/code/client/sound.js +10 -3
  56. package/kits/hub-game/code/client/soundscape.js +2 -2
  57. package/kits/hub-game/code/client/soundscapeAmbience.js +38 -8
  58. package/kits/hub-game/code/client/soundscapeBaked.js +24 -5
  59. package/kits/hub-game/code/client/soundscapeCues.js +2 -1
  60. package/kits/hub-game/code/client/state.js +19 -0
  61. package/kits/hub-game/code/client/stuck.js +2 -1
  62. package/kits/hub-game/code/client/talkSurface.js +178 -0
  63. package/kits/hub-game/code/client/talkTree.js +238 -0
  64. package/kits/hub-game/code/client/tiers.js +8 -5
  65. package/kits/hub-game/code/client/uiDom.js +600 -0
  66. package/kits/hub-game/code/client/uiTree.js +359 -0
  67. package/kits/hub-game/code/client/vehicle.js +154 -0
  68. package/kits/hub-game/code/client/wear.js +27 -5
  69. package/kits/hub-game/code/client/worldLabels.js +3 -2
  70. package/kits/hub-game/code/client/yours.js +10 -3
  71. package/kits/hub-game/code/server/actors.js +4 -3
  72. package/kits/hub-game/code/server/analytics.js +56 -6
  73. package/kits/hub-game/code/server/decor.js +56 -16
  74. package/kits/hub-game/code/server/hub.js +258 -46
  75. package/kits/hub-game/code/server/idle.js +118 -5
  76. package/kits/hub-game/code/server/manifest.js +46 -4
  77. package/kits/hub-game/code/server/npcs.js +4 -2
  78. package/kits/hub-game/code/server/players.js +3 -0
  79. package/kits/hub-game/code/server/role.js +142 -0
  80. package/kits/hub-game/code/server/standing.js +6 -4
  81. package/kits/hub-game/code/server/vehicle.js +126 -0
  82. package/kits/hub-game/code/shared/car.js +52 -0
  83. package/kits/hub-game/code/shared/deckFlags.js +34 -0
  84. package/kits/hub-game/code/shared/deviceClass.js +39 -0
  85. package/kits/hub-game/code/shared/expression.js +9 -0
  86. package/kits/hub-game/code/systems/hub.js +300 -85
  87. package/kits/hub-game/docs/analytics.md +11 -2
  88. package/kits/hub-game/docs/contract.md +353 -14
  89. package/kits/hub-game/docs/vehicle-preset.md +132 -0
  90. package/kits/hub-game/models/hats/baker-cap.pxmodel +89 -0
  91. package/kits/hub-game/models/hats/chef-toque.pxmodel +60 -0
  92. package/kits/hub-game/models/hats/delivery-cap.pxmodel +105 -0
  93. package/kits/hub-game/models/hats/fire-helmet.pxmodel +87 -0
  94. package/kits/hub-game/models/hats/hard-hat.pxmodel +71 -0
  95. package/kits/hub-game/models/hats/nurse-cap.pxmodel +61 -0
  96. package/kits/hub-game/models/hats/police-cap.pxmodel +105 -0
  97. package/kits/hub-game/models/hats/teacher-beret.pxmodel +52 -0
  98. package/kits/hub-game/models/role/square/top-apron.pxmodel +109 -0
  99. package/kits/hub-game/models/role/square/top-cardigan.pxmodel +141 -0
  100. package/kits/hub-game/models/role/square/top-coat.pxmodel +157 -0
  101. package/kits/hub-game/models/role/square/top-scrubs.pxmodel +93 -0
  102. package/kits/hub-game/models/role/square/top-tabard.pxmodel +109 -0
  103. package/kits/hub-game/models/role/square/top-vest.pxmodel +109 -0
  104. package/kits/hub-game/models/role/tool-bag.pxmodel +75 -0
  105. package/kits/hub-game/models/role/tool-bell.pxmodel +71 -0
  106. package/kits/hub-game/models/role/tool-hose.pxmodel +60 -0
  107. package/kits/hub-game/models/role/tool-parcel.pxmodel +61 -0
  108. package/kits/hub-game/models/role/tool-torch.pxmodel +55 -0
  109. package/kits/hub-game/models/role/tool-tray.pxmodel +75 -0
  110. package/kits/hub-game/models/role/top-apron.pxmodel +70 -0
  111. package/kits/hub-game/models/role/top-cardigan.pxmodel +102 -0
  112. package/kits/hub-game/models/role/top-coat.pxmodel +79 -0
  113. package/kits/hub-game/models/role/top-scrubs.pxmodel +54 -0
  114. package/kits/hub-game/models/role/top-tabard.pxmodel +70 -0
  115. package/kits/hub-game/models/role/top-vest.pxmodel +70 -0
  116. package/kits/hub-game/package-lock.json +1 -1
  117. package/kits/hub-game/package.json +1 -1
  118. package/kits/hub-game/scripts/check.mjs +7 -4
  119. package/kits/hub-game/scripts/fixtures/car-vectors.json +279 -0
  120. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +2 -1
  121. package/kits/hub-game/scripts/fixtures/hud-surface.json +670 -0
  122. package/kits/hub-game/scripts/fixtures/talk-surface.json +3930 -0
  123. package/kits/hub-game/scripts/gen-hats.mjs +46 -2
  124. package/kits/hub-game/scripts/gen-role.mjs +80 -0
  125. package/kits/hub-game/scripts/test-act-core.mjs +167 -0
  126. package/kits/hub-game/scripts/test-actions-client.mjs +34 -0
  127. package/kits/hub-game/scripts/test-actors.mjs +48 -0
  128. package/kits/hub-game/scripts/test-analytics.mjs +99 -5
  129. package/kits/hub-game/scripts/test-apply-deck.mjs +122 -0
  130. package/kits/hub-game/scripts/test-back-visibility.mjs +3 -1
  131. package/kits/hub-game/scripts/test-ballot.mjs +2 -0
  132. package/kits/hub-game/scripts/test-car.mjs +43 -0
  133. package/kits/hub-game/scripts/test-decor-client.mjs +2 -1
  134. package/kits/hub-game/scripts/test-decor.mjs +77 -0
  135. package/kits/hub-game/scripts/test-device-class.mjs +83 -0
  136. package/kits/hub-game/scripts/test-emote-wheel.mjs +374 -0
  137. package/kits/hub-game/scripts/test-hats.mjs +5 -4
  138. package/kits/hub-game/scripts/test-host-go.mjs +265 -0
  139. package/kits/hub-game/scripts/test-hub-controls.mjs +108 -0
  140. package/kits/hub-game/scripts/test-hub-entry.mjs +531 -0
  141. package/kits/hub-game/scripts/test-hub-ops.mjs +75 -0
  142. package/kits/hub-game/scripts/test-hub-trip.mjs +85 -0
  143. package/kits/hub-game/scripts/test-hud-clear.mjs +12 -2
  144. package/kits/hub-game/scripts/test-hud-rate.mjs +6 -2
  145. package/kits/hub-game/scripts/test-hud-surface.mjs +272 -0
  146. package/kits/hub-game/scripts/test-idle.mjs +347 -1
  147. package/kits/hub-game/scripts/test-interest-cells.mjs +8 -1
  148. package/kits/hub-game/scripts/test-invites-client.mjs +42 -1
  149. package/kits/hub-game/scripts/test-manifest.mjs +30 -0
  150. package/kits/hub-game/scripts/test-no-trips.mjs +42 -0
  151. package/kits/hub-game/scripts/test-placement-cache.mjs +1 -1
  152. package/kits/hub-game/scripts/test-quality.mjs +13 -0
  153. package/kits/hub-game/scripts/test-rehello.mjs +258 -3
  154. package/kits/hub-game/scripts/test-resume-pose-server.mjs +203 -0
  155. package/kits/hub-game/scripts/test-resync.mjs +183 -0
  156. package/kits/hub-game/scripts/test-role-client.mjs +421 -0
  157. package/kits/hub-game/scripts/test-role.mjs +350 -0
  158. package/kits/hub-game/scripts/test-safe-layout.mjs +50 -1
  159. package/kits/hub-game/scripts/test-soundscape.mjs +124 -7
  160. package/kits/hub-game/scripts/test-standing.mjs +15 -1
  161. package/kits/hub-game/scripts/test-talk-surface.mjs +296 -0
  162. package/kits/hub-game/scripts/test-tiers.mjs +13 -0
  163. package/kits/hub-game/scripts/test-ui-dom-dom.mjs +96 -0
  164. package/kits/hub-game/scripts/test-ui-tree.mjs +711 -0
  165. package/kits/hub-game/scripts/test-vehicle-client.mjs +159 -0
  166. package/kits/hub-game/scripts/test-vehicle.mjs +135 -0
  167. package/kits/hub-game/scripts/test-yours.mjs +33 -0
  168. package/kits/hub-game/tools/hubScene/export.mjs +613 -0
  169. package/kits/hub-game/tools/hubScene/hubdata.mjs +921 -0
  170. package/kits/hub-game/tools/hubScene/merge-root.mjs +39 -0
  171. package/kits/hub-game/tools/hubScene/nodeworld.mjs +227 -0
  172. package/kits/hub-game/tools/hubScene/test/export-fixture.mjs +798 -0
  173. package/kits/hub-game/tools/hubScene/test/fixture.json +637 -0
  174. package/kits/hub-game/tools/hubScene/test/paint-export.mjs +40 -0
  175. package/kits/hub-game/tools/hubScene/test/upload.test.mjs +655 -0
  176. package/kits/hub-game/tools/hubScene/upload.mjs +636 -0
  177. package/kits/hub-game/tools/hubScene/validate-manifest.mjs +291 -0
  178. package/kits/multiplayer-3d/castle.json +4 -4
  179. package/kits/multiplayer-3d/code/client/resumeGate.js +30 -2
  180. package/kits/multiplayer-3d/code/client/steer.js +3 -1
  181. package/kits/multiplayer-3d/code/systems/multiplayer.js +30 -2
  182. package/kits/multiplayer-3d/package-lock.json +1 -1
  183. package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +74 -2
  184. package/kits/physics-3d/CLAUDE.md +1 -1
  185. package/kits/physics-3d/behaviors/Player.jsx +37 -27
  186. package/kits/physics-3d/castle.json +2 -2
  187. package/kits/physics-3d/docs/engine-geometry-memory.md +23 -0
  188. package/kits/physics-3d/engine3d/memoryprofile.js +17 -0
  189. package/kits/physics-3d/engine3d/playerRun.js +6 -1
  190. package/kits/physics-3d/engine3d/pxmodel.js +6 -1
  191. package/kits/physics-3d/engine3d/world3d.js +6 -3
  192. package/kits/physics-3d/package.json +1 -1
  193. package/kits/physics-3d/play/behaviors/Player.js +40 -28
  194. package/kits/physics-3d/scripts/test-memory-profile.mjs +237 -0
  195. package/kits/physics-3d/systems/physics3d.js +5 -2
  196. package/kits/real-time/castle.json +2 -2
  197. package/kits/real-time/code/client/messages.js +5 -0
  198. package/kits/real-time/code/server/session.js +28 -1
  199. package/kits/real-time/package-lock.json +1 -1
  200. package/package.json +5 -4
  201. package/vendor/three/LICENSE +21 -0
  202. package/vendor/three/build/three.core.js +58773 -0
  203. package/vendor/three/build/three.module.js +18251 -0
  204. package/vendor/three/examples/jsm/controls/OrbitControls.js +1860 -0
  205. package/vendor/three/examples/jsm/controls/TransformControls.js +1918 -0
  206. package/vendor/three/examples/jsm/exporters/GLTFExporter.js +3595 -0
  207. package/vendor/three/examples/jsm/geometries/RoundedBoxGeometry.js +216 -0
  208. package/vendor/three/examples/jsm/math/MeshSurfaceSampler.js +315 -0
  209. package/vendor/three/examples/jsm/postprocessing/EffectComposer.js +363 -0
  210. package/vendor/three/examples/jsm/postprocessing/MaskPass.js +195 -0
  211. package/vendor/three/examples/jsm/postprocessing/OutputPass.js +139 -0
  212. package/vendor/three/examples/jsm/postprocessing/Pass.js +191 -0
  213. package/vendor/three/examples/jsm/postprocessing/RenderPass.js +183 -0
  214. package/vendor/three/examples/jsm/postprocessing/ShaderPass.js +135 -0
  215. package/vendor/three/examples/jsm/shaders/CopyShader.js +52 -0
  216. package/vendor/three/examples/jsm/shaders/OutputShader.js +103 -0
  217. package/vendor/three/examples/jsm/utils/BufferGeometryUtils.js +1435 -0
  218. package/vendor/three/package.json +134 -0
@@ -348,9 +348,18 @@ export type HubCancelStatus = "cancelled" | "expired" | "none" | "unavailable";
348
348
  export interface HubCancelResult {
349
349
  status: HubCancelStatus;
350
350
  }
351
- export type HubEvent = {
351
+ export type HubBackEvent = {
352
352
  type: "back";
353
353
  };
354
+ export type HubGoEvent = {
355
+ type: "go";
356
+ doorId: string;
357
+ owner?: string;
358
+ title?: string;
359
+ party?: number;
360
+ };
361
+ export type HubEvent = HubBackEvent | HubGoEvent;
362
+ export declare const HUB_GO_DOOR_ID_MAX = 128;
354
363
  export interface HubEventEnvelope {
355
364
  castleSdk: typeof CASTLE_SDK_PROTOCOL;
356
365
  hub: HubEvent;
@@ -791,6 +800,16 @@ export interface CommandParams {
791
800
  };
792
801
  "cauldronStorage.usage": Record<string, never>;
793
802
  "lifecycle.restoreState": Record<string, never>;
803
+ "localCache.get": {
804
+ key: string;
805
+ };
806
+ "localCache.set": {
807
+ key: string;
808
+ value: ArrayBuffer | string;
809
+ };
810
+ "localCache.remove": {
811
+ key: string;
812
+ };
794
813
  }
795
814
  export interface CommandResult {
796
815
  "agent.chat": AgentChatResult;
@@ -938,6 +957,11 @@ export interface CommandResult {
938
957
  usage: StoreAllowances;
939
958
  };
940
959
  "lifecycle.restoreState": LifecycleRestoreStateResult;
960
+ "localCache.get": {
961
+ value: ArrayBuffer | string | null;
962
+ };
963
+ "localCache.set": Record<string, never>;
964
+ "localCache.remove": Record<string, never>;
941
965
  }
942
966
  export interface UserPayload {
943
967
  userId: string;
@@ -6,6 +6,7 @@
6
6
  // Marker + protocol version. Doubles as a discriminator so host messages can't
7
7
  // be confused with embed.js `castlexyz:` strings or RN console messages.
8
8
  export const CASTLE_SDK_PROTOCOL = 1;
9
+ export const HUB_GO_DOOR_ID_MAX = 128;
9
10
  export function hubEventFrom(value) {
10
11
  if (typeof value !== "object" || value === null)
11
12
  return null;
@@ -15,7 +16,29 @@ export function hubEventFrom(value) {
15
16
  const event = record.hub;
16
17
  if (typeof event !== "object" || event === null)
17
18
  return null;
18
- return event.type === "back" ? { type: "back" } : null;
19
+ if (event.type === "back")
20
+ return { type: "back" };
21
+ if (event.type === "go")
22
+ return hubGoEventFrom(event);
23
+ return null;
24
+ }
25
+ function hubGoEventFrom(event) {
26
+ const { doorId, owner, title, party } = event;
27
+ if (typeof doorId !== "string" || doorId.length === 0 || doorId.length > HUB_GO_DOOR_ID_MAX)
28
+ return null;
29
+ const go = { type: "go", doorId };
30
+ // A bad owner refuses the whole event: a trip to the wrong House is worse
31
+ // than none.
32
+ if (owner !== undefined && owner !== null) {
33
+ if (typeof owner !== "string" || !/^[1-9]\d{0,9}$/.test(owner))
34
+ return null;
35
+ go.owner = owner;
36
+ }
37
+ if (typeof title === "string")
38
+ go.title = title;
39
+ if (typeof party === "number" && Number.isInteger(party) && party > 0)
40
+ go.party = party;
41
+ return go;
19
42
  }
20
43
  // How long the deck waits for a reply to these commands, in place of the
21
44
  // data-command timeout. A deck list fetches every cover on the list. A host
@@ -32,6 +55,11 @@ export const COMMAND_TIMEOUTS_MS = {
32
55
  // Native auth may include a provider handoff, but it must not leave a deck
33
56
  // waiting forever if the host loses the completion callback.
34
57
  "hub.signIn": 120_000,
58
+ // A large entry is an IndexedDB read or write plus a copy into the other
59
+ // frame, and can wait behind other tabs' writes to the same store.
60
+ "localCache.get": 60_000,
61
+ "localCache.set": 60_000,
62
+ "localCache.remove": 60_000,
35
63
  };
36
64
  // Once a host streams a command, each stream envelope restarts the wait at this
37
65
  // length instead. The deck-agent service sends a heartbeat every 15 seconds, and the host
@@ -112,5 +112,22 @@ export interface CastleHubApi {
112
112
  * takes the player home itself. Returns an unsubscribe function.
113
113
  */
114
114
  onBack(listener: () => void): () => void;
115
+ /**
116
+ * The host asked to take the player through a door, e.g. a trip begun
117
+ * outside this page. A hub kit answers it like a fired pad: `go(doorId)`
118
+ * behind its door animation, passing `owner` as `ownerUserId` when set.
119
+ * `owner` names whose House a House door leads to, or null; `title` is the
120
+ * host's name for the door, or null; `party` is how many travel (1 when
121
+ * the host does not say). Hosts
122
+ * that never send it are the norm. Returns an unsubscribe function.
123
+ */
124
+ onGo(listener: (go: HubGoRequest) => void): () => void;
125
+ }
126
+ /** A host's request to go through a door (see `Hub.onGo`). */
127
+ export interface HubGoRequest {
128
+ doorId: string;
129
+ owner: string | null;
130
+ title: string | null;
131
+ party: number;
115
132
  }
116
133
  export declare const Hub: CastleHubApi;
@@ -20,6 +20,7 @@ export const Hub = {
20
20
  reportChat,
21
21
  cancel,
22
22
  onBack,
23
+ onGo,
23
24
  };
24
25
  async function go(doorId, options = {}) {
25
26
  if (typeof doorId !== "string" || doorId.length === 0) {
@@ -155,29 +156,52 @@ async function cancel() {
155
156
  return hostRequest("hub.cancel", {});
156
157
  }
157
158
  const backListeners = new Set();
159
+ const goListeners = new Set();
158
160
  function onBack(listener) {
161
+ return subscribe(backListeners, listener, "Hub.onBack");
162
+ }
163
+ function onGo(listener) {
164
+ return subscribe(goListeners, listener, "Hub.onGo");
165
+ }
166
+ // The host's hub event handler stays installed while any listener of any kind
167
+ // is left, so dropping the last Back listener never silences Go, or vice versa.
168
+ function subscribe(listeners, listener, operation) {
159
169
  if (typeof listener !== "function") {
160
170
  throw new CastleError({
161
171
  code: "INVALID_ARGUMENT",
162
- message: "Hub.onBack requires a function.",
163
- operation: "Hub.onBack",
172
+ message: `${operation} requires a function.`,
173
+ operation,
164
174
  });
165
175
  }
166
- backListeners.add(listener);
176
+ listeners.add(listener);
167
177
  setHubEventHandler(dispatchHubEvent);
168
178
  return () => {
169
- backListeners.delete(listener);
170
- if (backListeners.size === 0)
179
+ listeners.delete(listener);
180
+ if (backListeners.size === 0 && goListeners.size === 0)
171
181
  setHubEventHandler(null);
172
182
  };
173
183
  }
174
- function dispatchHubEvent() {
175
- for (const listener of [...backListeners]) {
184
+ function dispatchHubEvent(event) {
185
+ if (event.type === "back") {
186
+ notify(backListeners, (listener) => listener(), "Hub.onBack");
187
+ }
188
+ else if (event.type === "go") {
189
+ const go = {
190
+ doorId: event.doorId,
191
+ owner: event.owner ?? null,
192
+ title: event.title ?? null,
193
+ party: event.party ?? 1,
194
+ };
195
+ notify(goListeners, (listener) => listener({ ...go }), "Hub.onGo");
196
+ }
197
+ }
198
+ function notify(listeners, call, operation) {
199
+ for (const listener of [...listeners]) {
176
200
  try {
177
- listener();
201
+ call(listener);
178
202
  }
179
203
  catch (error) {
180
- console.error("Castle Hub.onBack listener threw:", error);
204
+ console.error(`Castle ${operation} listener threw:`, error);
181
205
  }
182
206
  }
183
207
  }
@@ -0,0 +1,27 @@
1
+ export interface LocalCacheApi {
2
+ getBinary(key: string): Promise<ArrayBuffer | null>;
3
+ getText(key: string): Promise<string | null>;
4
+ set(key: string, value: ArrayBuffer | Uint8Array | string): Promise<void>;
5
+ remove(key: string): Promise<void>;
6
+ }
7
+ /**
8
+ * A cache on the player's device, for bytes and text the deck can rebuild:
9
+ * downloaded or unpacked assets, compiled data. Entries belong to the deck
10
+ * whose code is running. A hub town's doors change the place but not the
11
+ * code, so the games played through them use the town's entries. In the app,
12
+ * decks loaded from the same web address share entries.
13
+ *
14
+ * Any entry can be gone at any time. Each deck has 20 MB; past that its own
15
+ * least recently used entries are evicted. On the web all decks together
16
+ * have 300 MB; past that the least recently used entries of any deck are
17
+ * evicted. Both are less when the device is short of space. The browser or
18
+ * app may also clear the whole cache.
19
+ *
20
+ * `getBinary` returns bytes (text entries as UTF-8), `getText` returns text
21
+ * (byte entries decoded as UTF-8). `set` takes an ArrayBuffer, a Uint8Array or
22
+ * a string. An ArrayBuffer is moved into the cache and is empty (detached)
23
+ * afterwards, so pass `buffer.slice(0)` to keep a copy; so is the buffer of a
24
+ * Uint8Array that covers all of it. A Uint8Array over part of a buffer is
25
+ * copied.
26
+ */
27
+ export declare const LocalCache: LocalCacheApi;
@@ -0,0 +1,115 @@
1
+ import { openLocalCacheStore } from "./localCacheStore";
2
+ import { getCommandChannel, hostRequest } from "./transport";
3
+ // The deck's own origin is its namespace, so every entry there uses this one.
4
+ const OWN_ORIGIN_NAMESPACE = "deck";
5
+ let ownStore = null;
6
+ function usesOwnOrigin() {
7
+ return getCommandChannel() !== "web";
8
+ }
9
+ function store() {
10
+ ownStore ??= openLocalCacheStore();
11
+ return ownStore;
12
+ }
13
+ async function read(key, operation) {
14
+ assertKey(key, operation);
15
+ try {
16
+ if (usesOwnOrigin()) {
17
+ return await store().get(OWN_ORIGIN_NAMESPACE, key);
18
+ }
19
+ const { value } = await hostRequest("localCache.get", { key });
20
+ return value;
21
+ }
22
+ catch {
23
+ return null;
24
+ }
25
+ }
26
+ async function write(key, value) {
27
+ assertKey(key, "LocalCache.set");
28
+ const moved = moveIn(value);
29
+ try {
30
+ if (usesOwnOrigin()) {
31
+ await store().set(OWN_ORIGIN_NAMESPACE, key, moved);
32
+ return;
33
+ }
34
+ const transfer = typeof moved === "string" ? [] : [moved];
35
+ await hostRequest("localCache.set", { key, value: moved }, { transfer });
36
+ }
37
+ catch {
38
+ // A write that fails stores nothing.
39
+ }
40
+ }
41
+ async function remove(key) {
42
+ assertKey(key, "LocalCache.remove");
43
+ try {
44
+ if (usesOwnOrigin()) {
45
+ await store().remove(OWN_ORIGIN_NAMESPACE, key);
46
+ return;
47
+ }
48
+ await hostRequest("localCache.remove", { key });
49
+ }
50
+ catch {
51
+ // A host without LocalCache never stored the entry.
52
+ }
53
+ }
54
+ // An ArrayBuffer is moved, not copied, in every host, so a deck sees the same
55
+ // detached buffer after the call wherever it runs. A Uint8Array that covers
56
+ // its whole buffer moves that buffer the same way; one that covers part of it
57
+ // has its bytes copied, and its buffer is left as it was.
58
+ function moveIn(value) {
59
+ if (typeof value === "string") {
60
+ return value;
61
+ }
62
+ if (value instanceof ArrayBuffer) {
63
+ return structuredClone(value, { transfer: [value] });
64
+ }
65
+ if (value instanceof Uint8Array) {
66
+ const buffer = value.buffer;
67
+ const whole = buffer instanceof ArrayBuffer && value.byteOffset === 0 && value.byteLength === buffer.byteLength;
68
+ return whole ? structuredClone(buffer, { transfer: [buffer] }) : value.slice().buffer;
69
+ }
70
+ throw new TypeError("LocalCache.set takes an ArrayBuffer, a Uint8Array or a string.");
71
+ }
72
+ // The host refuses a key with NUL in it, so the SDK does too, in every host.
73
+ function assertKey(key, operation) {
74
+ if (typeof key !== "string" || key.length === 0 || key.length > 1024 || key.includes("\0")) {
75
+ throw new TypeError(`${operation} takes a key of 1 to 1024 characters, without NUL.`);
76
+ }
77
+ }
78
+ /**
79
+ * A cache on the player's device, for bytes and text the deck can rebuild:
80
+ * downloaded or unpacked assets, compiled data. Entries belong to the deck
81
+ * whose code is running. A hub town's doors change the place but not the
82
+ * code, so the games played through them use the town's entries. In the app,
83
+ * decks loaded from the same web address share entries.
84
+ *
85
+ * Any entry can be gone at any time. Each deck has 20 MB; past that its own
86
+ * least recently used entries are evicted. On the web all decks together
87
+ * have 300 MB; past that the least recently used entries of any deck are
88
+ * evicted. Both are less when the device is short of space. The browser or
89
+ * app may also clear the whole cache.
90
+ *
91
+ * `getBinary` returns bytes (text entries as UTF-8), `getText` returns text
92
+ * (byte entries decoded as UTF-8). `set` takes an ArrayBuffer, a Uint8Array or
93
+ * a string. An ArrayBuffer is moved into the cache and is empty (detached)
94
+ * afterwards, so pass `buffer.slice(0)` to keep a copy; so is the buffer of a
95
+ * Uint8Array that covers all of it. A Uint8Array over part of a buffer is
96
+ * copied.
97
+ */
98
+ export const LocalCache = {
99
+ async getBinary(key) {
100
+ const value = await read(key, "LocalCache.getBinary");
101
+ if (typeof value === "string") {
102
+ return new TextEncoder().encode(value).buffer;
103
+ }
104
+ return value;
105
+ },
106
+ async getText(key) {
107
+ const value = await read(key, "LocalCache.getText");
108
+ if (value instanceof ArrayBuffer) {
109
+ return new TextDecoder().decode(value);
110
+ }
111
+ return value;
112
+ },
113
+ set: write,
114
+ remove,
115
+ };
@@ -0,0 +1,15 @@
1
+ export type LocalCacheValue = ArrayBuffer | string;
2
+ export interface LocalCacheStore {
3
+ get(namespace: string, key: string): Promise<LocalCacheValue | null>;
4
+ set(namespace: string, key: string, value: LocalCacheValue): Promise<void>;
5
+ remove(namespace: string, key: string): Promise<void>;
6
+ }
7
+ export interface LocalCacheStoreOptions {
8
+ databaseName?: string;
9
+ deckBudgetBytes?: number;
10
+ totalBudgetBytes?: number;
11
+ }
12
+ export declare const LOCAL_CACHE_DATABASE_NAME = "castle-local-cache";
13
+ export declare const LOCAL_CACHE_DECK_BUDGET_BYTES: number;
14
+ export declare const LOCAL_CACHE_TOTAL_BUDGET_BYTES: number;
15
+ export declare function openLocalCacheStore(options?: LocalCacheStoreOptions): LocalCacheStore;