castle-web-cli 0.4.226 → 0.4.228

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 (50) hide show
  1. package/dist/agent-prompts.d.ts +5 -0
  2. package/dist/agent-prompts.js +7 -7
  3. package/dist/agent.d.ts +1 -0
  4. package/dist/agent.js +159 -48
  5. package/dist/api.d.ts +21 -0
  6. package/dist/api.js +21 -3
  7. package/dist/castle-host/host.d.ts +6 -0
  8. package/dist/castle-host/host.js +42 -3
  9. package/dist/cloudGit.d.ts +7 -0
  10. package/dist/cloudGit.js +92 -14
  11. package/dist/cloudGitServe.js +9 -5
  12. package/dist/get-deck.js +5 -2
  13. package/dist/gitCollaborators.d.ts +16 -0
  14. package/dist/gitCollaborators.js +42 -0
  15. package/dist/gitIncoming.d.ts +17 -0
  16. package/dist/gitIncoming.js +113 -0
  17. package/dist/gitRemote.js +2 -2
  18. package/dist/importBrowse.js +7 -6
  19. package/dist/imports.d.ts +2 -1
  20. package/dist/imports.js +82 -13
  21. package/dist/init.js +17 -4
  22. package/dist/native/playtest-browser.js +13 -1
  23. package/dist/platformDoc.d.ts +1 -0
  24. package/dist/platformDoc.js +31 -9
  25. package/dist/playPagePolicy.js +35 -1
  26. package/dist/remix.js +1 -1
  27. package/dist/save-deck.d.ts +1 -7
  28. package/dist/save-deck.js +18 -26
  29. package/dist/saveFailure.d.ts +26 -0
  30. package/dist/saveFailure.js +102 -0
  31. package/dist/serve.js +17 -0
  32. package/dist/shell/assets/index-Cf61cNfT.css +1 -0
  33. package/dist/shell/assets/{index-C7ksEq3_.js → index-D2tWM896.js} +94 -94
  34. package/dist/shell/index.html +2 -2
  35. package/kits/base/CLAUDE.md +2 -1
  36. package/kits/base/castle.json +1 -1
  37. package/kits/base/sdk/README.md +87 -0
  38. package/kits/base/sdk/castle.d.ts +3 -1
  39. package/kits/base/sdk/castle.js +1 -0
  40. package/kits/base/sdk/commands.d.ts +6 -0
  41. package/kits/base/sdk/display.d.ts +36 -0
  42. package/kits/base/sdk/display.js +96 -0
  43. package/kits/base/sdk/multiplayer.d.ts +3 -1
  44. package/kits/base/sdk/multiplayer.js +11 -1
  45. package/kits/base/sdk/runtime.js +35 -17
  46. package/kits/base/sdk/server/platformHandle.d.ts +2 -0
  47. package/kits/base/sdk/server/wrapper.d.ts +58 -0
  48. package/kits/base/sdk/server/wrapper.js +350 -8
  49. package/package.json +11 -3
  50. package/dist/shell/assets/index-4G5NKIQ8.css +0 -1
@@ -10,8 +10,8 @@
10
10
  <link rel="icon" type="image/png" sizes="32x32" href="/__castle/ide/favicon-32x32.png" />
11
11
  <link rel="icon" type="image/png" sizes="16x16" href="/__castle/ide/favicon-16x16.png" />
12
12
  <link rel="icon" href="/__castle/ide/favicon.ico" sizes="any" />
13
- <script type="module" crossorigin src="/__castle/ide/assets/index-C7ksEq3_.js"></script>
14
- <link rel="stylesheet" crossorigin href="/__castle/ide/assets/index-4G5NKIQ8.css">
13
+ <script type="module" crossorigin src="/__castle/ide/assets/index-D2tWM896.js"></script>
14
+ <link rel="stylesheet" crossorigin href="/__castle/ide/assets/index-Cf61cNfT.css">
15
15
  </head>
16
16
  <body>
17
17
  <div id="root"></div>
@@ -35,7 +35,8 @@ named in the bullet above.
35
35
 
36
36
  The three calls almost every deck makes:
37
37
 
38
- - `setup()` — once, before anything else. Mounts the 5:7 Castle card and, while
38
+ - `setup()` — once, before anything else. Mounts the Castle card (5:7, or the
39
+ whole stage for a deck that declares `castle-display` fill) and, while
39
40
  serving locally, forwards `console` output to the CLI.
40
41
  - `initCard()` — the element to draw into, when the deck renders into a
41
42
  `<canvas>` or raw DOM rather than a React tree at `#root`.
@@ -82,7 +82,7 @@
82
82
  "title": "base",
83
83
  "deckId": "yRcmH4_aYllE",
84
84
  "cardId": "zkFdingmIm3m",
85
- "publishedVersion": "2026-09-29T05:59:15.055Z",
85
+ "publishedVersion": "2026-09-30T05:53:28.406Z",
86
86
  "provides": [
87
87
  "castle-web-sdk"
88
88
  ]
@@ -151,6 +151,44 @@ Two differences follow from a session server not being a player:
151
151
  stop. An out-of-memory kill or a host failing sends no shutdown at all, so
152
152
  save as things change and treat `onShutdown` as the last chance, not the plan.
153
153
 
154
+ ### Persistent worlds
155
+
156
+ An opted-in persistent-world route has `session.world`; other sessions have
157
+ `session.world === null`. Alongside its checkpoint, the world keeps a journal
158
+ of its latest 512 entries and a last-seen row for each participant:
159
+
160
+ ```js
161
+ await session.world.journal.append({
162
+ operationId: "market-opened-day-12",
163
+ entries: [{
164
+ kind: "market.opened",
165
+ disclosure: "world",
166
+ data: { day: 12 },
167
+ }],
168
+ });
169
+
170
+ const page = await session.world.journal.read({
171
+ afterSeq: savedCursor,
172
+ participantId: player.participantId,
173
+ });
174
+ const { participants } = await session.world.participants.read({
175
+ participantIds: [player.participantId],
176
+ });
177
+ ```
178
+
179
+ `journal.append` accepts up to 16 entries per operation; each optional `data`
180
+ value must be JSON no larger than 2 KiB. Save `nextSeq` from `journal.read` as
181
+ the next cursor, and compare it with `oldestRetainedSeq` to detect a cursor that
182
+ fell behind retention. Entries disclosed to `participants` name participant
183
+ ids for the trusted deck server to project to those players; never broadcast
184
+ those entries to the whole session.
185
+
186
+ Every `MultiplayerServerPlayer` has a stable `participantId` for these calls
187
+ (`scopedUserId` when available, otherwise `userId`). The host records join,
188
+ leave, and shutdown presence automatically, and `participants.read` reflects
189
+ those host writes. The SDK never writes participant presence, and there is no
190
+ public touch method.
191
+
154
192
  ## Store
155
193
 
156
194
  `Store` saves data one key at a time. It is the storage to use for
@@ -1008,6 +1046,55 @@ Host-specific layout flags such as `CastleEmbed.feed` are deprecated.
1008
1046
  New code should let Castle hosts provide the frame and let the SDK infer
1009
1047
  whether it is running standalone or embedded.
1010
1048
 
1049
+ ### Filling the screen: `<meta name="castle-display">`
1050
+
1051
+ By default a deck is a 5:7 portrait card. A deck that can lay itself out at
1052
+ other shapes opts out of the card in its own `index.html`:
1053
+
1054
+ ```html
1055
+ <meta name="castle-display" content="layout=fill">
1056
+ <!-- or narrow the shapes it accepts (width / height, as 16/9, 16:9 or 1.78) -->
1057
+ <meta name="castle-display" content="layout=fill, min-aspect=9/16, max-aspect=16/9">
1058
+ ```
1059
+
1060
+ A `fill` deck gets the host's whole frame, edge to edge with no rounded
1061
+ corners, whenever that frame's aspect is inside its range (default 9/21 to
1062
+ 21/9); outside it, the deck gets the largest in-range box, centered. Castle's
1063
+ web player gives a fill deck a bigger stage and a fullscreen button. Hosts
1064
+ that don't know the tag still give it a 5:7 frame, so a fill deck should look
1065
+ right at 5:7 as well.
1066
+
1067
+ Lay out against the stage: the element `initCard()` returns, or
1068
+ `--castle-card-w`/`--castle-card-h` in CSS, with a resize listener. Not the
1069
+ window: the stage is smaller than the window when the host frame is outside
1070
+ the deck's range, and inside `castle-web serve`'s own page. `getDisplay()` returns the parsed declaration and `fitStage(w, h,
1071
+ display)` the box the SDK would pick.
1072
+
1073
+ Size HUD, buttons and text in the card unit, not in `vw` or `cqw`:
1074
+
1075
+ ```css
1076
+ .score { font-size: calc(5 * var(--castle-unit)); top: calc(3 * var(--castle-unit)); }
1077
+ ```
1078
+
1079
+ `--castle-unit` is 1% of the width of the largest 5:7 card that fits in the
1080
+ stage. On a card, or a stage taller than a card, it is 1% of the stage width
1081
+ (the same as `1vw`); on a wide stage it stops growing, so a HUD keeps its card
1082
+ size while the playfield gets the extra room. Anything sized in `vw` grows with
1083
+ the stage instead, and a 16:9 monitor makes it huge. Canvas code gets the same
1084
+ number from `cardUnit(width, height)` (px). The SDK sets the exact value for
1085
+ its own stage; in edit mode, and in a kit's scene editor that draws the stage
1086
+ smaller than the window, it falls back to the window's.
1087
+
1088
+ A 3D camera tuned for the card keeps its framing with `fovForAspect(fov,
1089
+ aspect)`: it returns `fov` at 5:7 and wider (a wide stage shows more to the
1090
+ sides) and widens it on a stage narrower than 5:7, so a tall phone still sees
1091
+ the card's full width.
1092
+
1093
+ ```js
1094
+ camera.fov = fovForAspect(50, width / height);
1095
+ camera.updateProjectionMatrix();
1096
+ ```
1097
+
1011
1098
  ### `CARD_RATIO`
1012
1099
 
1013
1100
  The card aspect ratio (`5 / 7`). Use this if you need to size something
@@ -14,7 +14,7 @@ export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, Leaderboard
14
14
  export { Lifecycle } from "./lifecycle";
15
15
  export type { CastleLifecycleApi } from "./lifecycle";
16
16
  export { Multiplayer } from "./multiplayer";
17
- export type { CastleMultiplayerApi, MultiplayerConnection, MultiplayerConnectionState, MultiplayerDestinationJoinResult, MultiplayerDestinationOptions, MultiplayerJoinOptions, MultiplayerRoster, MultiplayerStateMetadata, } from "./multiplayer";
17
+ export type { CastleMultiplayerApi, MultiplayerConnection, MultiplayerConnectionState, MultiplayerDestinationJoinResult, MultiplayerDestinationOptions, MultiplayerJoinHint, MultiplayerJoinOptions, MultiplayerRoster, MultiplayerStateMetadata, } from "./multiplayer";
18
18
  export type { MultiplayerVoice, VoiceJoinStatus, VoiceListener, VoiceMixEntry, VoiceSpatialOptions, VoiceState, VoiceVector, } from "./multiplayerVoice";
19
19
  export type { MultiplayerDestinationAudience, MultiplayerSoloReason } from "./commands";
20
20
  export { MAX_CLIENT_FRAME_BYTES, MAX_PLAYERS_CAP } from "./multiplayerProtocol";
@@ -29,6 +29,8 @@ export { Portal } from "./portal";
29
29
  export type { CastlePortalApi, PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./portal";
30
30
  export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
31
31
  export type { FileChange, FilesChangedEvent } from "./runtime";
32
+ export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
33
+ export type { DeckDisplay, DeckLayout } from "./display";
32
34
  export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
33
35
  export type { SaveState } from "./saveQueue";
34
36
  export { SharedStorage, Storage } from "./storage";
@@ -15,6 +15,7 @@ export { Pass } from "./passes";
15
15
  export { Snapshot } from "./snapshots";
16
16
  export { Portal } from "./portal";
17
17
  export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
18
+ export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
18
19
  export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
19
20
  export { SharedStorage, Storage } from "./storage";
20
21
  export { Store } from "./store";
@@ -114,6 +114,10 @@ export interface MultiplayerGetSessionResult {
114
114
  /** Internal local-serve scope for restoring this Play panel after a reload. */
115
115
  devReconnectScope?: string;
116
116
  }
117
+ export interface MultiplayerJoinHint {
118
+ routeId: string;
119
+ slot: string;
120
+ }
117
121
  export interface MultiplayerJoinDestinationParams {
118
122
  routeId: string;
119
123
  slot: string;
@@ -352,6 +356,7 @@ export interface CommandParams {
352
356
  style: HapticStyle;
353
357
  };
354
358
  "multiplayer.getSession": MultiplayerGetSessionParams;
359
+ "multiplayer.getJoinHint": Record<string, never>;
355
360
  "multiplayer.joinDestination": MultiplayerJoinDestinationParams;
356
361
  "voice.getState": {
357
362
  sessionId: string;
@@ -492,6 +497,7 @@ export interface CommandResult {
492
497
  "portal.info": PortalInfoResult;
493
498
  "haptics.play": HapticsResult;
494
499
  "multiplayer.getSession": MultiplayerGetSessionResult;
500
+ "multiplayer.getJoinHint": MultiplayerJoinHint | null;
495
501
  "multiplayer.joinDestination": MultiplayerJoinDestinationResult;
496
502
  "voice.getState": {
497
503
  state: VoiceState;
@@ -0,0 +1,36 @@
1
+ export type DeckLayout = "card" | "fill";
2
+ export interface DeckDisplay {
3
+ layout: DeckLayout;
4
+ /** Narrowest width / height the deck accepts. */
5
+ minAspect: number;
6
+ /** Widest width / height the deck accepts. */
7
+ maxAspect: number;
8
+ }
9
+ export declare const CARD_ASPECT: number;
10
+ /** Default fill range: a tall 21:9 phone held upright to a 21:9 monitor. */
11
+ export declare const FILL_MIN_ASPECT: number;
12
+ export declare const FILL_MAX_ASPECT: number;
13
+ export declare const CARD_DISPLAY: DeckDisplay;
14
+ export declare function parseDisplayContent(content: string | null | undefined): DeckDisplay;
15
+ /** The display this deck declared in its index.html (a card when it declared none). */
16
+ export declare function getDisplay(): DeckDisplay;
17
+ /**
18
+ * The card unit, in px, for a stage of `width` x `height`: 1% of the width of
19
+ * the largest 5:7 card that fits in it. On a card it is 1% of the card's width;
20
+ * on a wider stage it stops growing, so HUD and text sized in it stay the size
21
+ * they are on a card while the playfield gets the extra room. CSS gets the same
22
+ * value as `var(--castle-unit)`.
23
+ */
24
+ export declare function cardUnit(width: number, height: number): number;
25
+ /**
26
+ * A vertical field of view (degrees) for a camera tuned at 5:7. On a stage
27
+ * narrower than 5:7 (a tall phone) it widens so the card's horizontal extent
28
+ * stays in view; at 5:7 and wider it returns `fovDeg` unchanged, so a wide
29
+ * stage just shows more to the sides. Capped at 120 degrees.
30
+ */
31
+ export declare function fovForAspect(fovDeg: number, aspect: number): number;
32
+ /** The largest box inside `width` x `height` whose aspect is in the display's range. */
33
+ export declare function fitStage(width: number, height: number, display: DeckDisplay): {
34
+ w: number;
35
+ h: number;
36
+ };
@@ -0,0 +1,96 @@
1
+ // How much of the host's frame a deck may use.
2
+ //
3
+ // A deck declares it in its own index.html, the way a page declares its
4
+ // viewport:
5
+ //
6
+ // <meta name="castle-display" content="layout=fill">
7
+ // <meta name="castle-display" content="layout=fill, min-aspect=9/16, max-aspect=16/9">
8
+ //
9
+ // With no tag the deck is a `card`: the classic 5:7 portrait card, exactly as
10
+ // before. A `fill` deck takes whatever box the host gives it, as long as the
11
+ // box's aspect (width / height) is inside [minAspect, maxAspect]; outside that
12
+ // range it gets the largest box in range, centered. A card is just the range
13
+ // [5/7, 5/7].
14
+ //
15
+ // Hosts read the same tag out of the bundle to size the frame before the deck
16
+ // loads (castle-www common/deckDisplay.ts mirrors this parser). A host that
17
+ // knows nothing about it still gives the deck a 5:7 frame, so a fill deck
18
+ // should render well at 5:7 too; one whose range leaves 5/7 out (landscape
19
+ // only) is letterboxed inside such a frame.
20
+ export const CARD_ASPECT = 5 / 7;
21
+ /** Default fill range: a tall 21:9 phone held upright to a 21:9 monitor. */
22
+ export const FILL_MIN_ASPECT = 9 / 21;
23
+ export const FILL_MAX_ASPECT = 21 / 9;
24
+ export const CARD_DISPLAY = {
25
+ layout: "card",
26
+ minAspect: CARD_ASPECT,
27
+ maxAspect: CARD_ASPECT,
28
+ };
29
+ // "16/9", "16:9" or "1.78"; anything else (or a non-positive value) is null.
30
+ function parseAspect(value) {
31
+ const ratio = value.match(/^\s*(\d+(?:\.\d+)?)\s*[/:]\s*(\d+(?:\.\d+)?)\s*$/);
32
+ const n = ratio ? Number(ratio[1]) / Number(ratio[2]) : Number(value);
33
+ return Number.isFinite(n) && n > 0 ? n : null;
34
+ }
35
+ export function parseDisplayContent(content) {
36
+ if (!content)
37
+ return CARD_DISPLAY;
38
+ const fields = {};
39
+ for (const part of content.split(/[,;]/)) {
40
+ const eq = part.indexOf("=");
41
+ if (eq < 0)
42
+ continue;
43
+ fields[part.slice(0, eq).trim().toLowerCase()] = part.slice(eq + 1).trim();
44
+ }
45
+ if (fields.layout?.toLowerCase() !== "fill")
46
+ return CARD_DISPLAY;
47
+ let minAspect = parseAspect(fields["min-aspect"] ?? "") ?? FILL_MIN_ASPECT;
48
+ let maxAspect = parseAspect(fields["max-aspect"] ?? "") ?? FILL_MAX_ASPECT;
49
+ if (minAspect > maxAspect)
50
+ [minAspect, maxAspect] = [maxAspect, minAspect];
51
+ return { layout: "fill", minAspect, maxAspect };
52
+ }
53
+ let cached = null;
54
+ /** The display this deck declared in its index.html (a card when it declared none). */
55
+ export function getDisplay() {
56
+ if (cached)
57
+ return cached;
58
+ if (typeof document === "undefined")
59
+ return CARD_DISPLAY;
60
+ const meta = document.querySelector('meta[name="castle-display"]');
61
+ cached = parseDisplayContent(meta?.content);
62
+ return cached;
63
+ }
64
+ /**
65
+ * The card unit, in px, for a stage of `width` x `height`: 1% of the width of
66
+ * the largest 5:7 card that fits in it. On a card it is 1% of the card's width;
67
+ * on a wider stage it stops growing, so HUD and text sized in it stay the size
68
+ * they are on a card while the playfield gets the extra room. CSS gets the same
69
+ * value as `var(--castle-unit)`.
70
+ */
71
+ export function cardUnit(width, height) {
72
+ return Math.min(Math.max(0, width), Math.max(0, height) * CARD_ASPECT) / 100;
73
+ }
74
+ /**
75
+ * A vertical field of view (degrees) for a camera tuned at 5:7. On a stage
76
+ * narrower than 5:7 (a tall phone) it widens so the card's horizontal extent
77
+ * stays in view; at 5:7 and wider it returns `fovDeg` unchanged, so a wide
78
+ * stage just shows more to the sides. Capped at 120 degrees.
79
+ */
80
+ export function fovForAspect(fovDeg, aspect) {
81
+ if (!(aspect > 0) || aspect >= CARD_ASPECT)
82
+ return fovDeg;
83
+ const half = Math.atan((Math.tan((fovDeg * Math.PI) / 360) * CARD_ASPECT) / aspect);
84
+ return Math.min(120, (half * 360) / Math.PI);
85
+ }
86
+ /** The largest box inside `width` x `height` whose aspect is in the display's range. */
87
+ export function fitStage(width, height, display) {
88
+ const aw = Math.max(1, width);
89
+ const ah = Math.max(1, height);
90
+ const aspect = aw / ah;
91
+ if (aspect > display.maxAspect)
92
+ return { w: ah * display.maxAspect, h: ah };
93
+ if (aspect < display.minAspect)
94
+ return { w: aw, h: aw / display.minAspect };
95
+ return { w: aw, h: ah };
96
+ }
@@ -1,8 +1,9 @@
1
- import type { MultiplayerDestinationAudience, MultiplayerSoloReason } from "./commands";
1
+ import type { MultiplayerDestinationAudience, MultiplayerJoinHint, MultiplayerSoloReason } from "./commands";
2
2
  import { CastleError } from "./errors";
3
3
  import type { Json } from "./types";
4
4
  import { type MultiplayerPlayer, type MultiplayerCharacterDisclosure, type MultiplayerCharacterTurnStatus } from "./multiplayerProtocol";
5
5
  import { type MultiplayerVoice } from "./multiplayerVoice";
6
+ export type { MultiplayerJoinHint } from "./commands";
6
7
  export type MultiplayerJoinOptions = {
7
8
  mode: "named";
8
9
  key: string;
@@ -153,6 +154,7 @@ export interface MultiplayerConnection {
153
154
  }
154
155
  export interface CastleMultiplayerApi {
155
156
  join(options: MultiplayerJoinOptions): Promise<MultiplayerConnection>;
157
+ joinHint(): Promise<MultiplayerJoinHint | null>;
156
158
  joinDestination(options: MultiplayerDestinationOptions): Promise<MultiplayerDestinationJoinResult>;
157
159
  }
158
160
  export declare const Multiplayer: CastleMultiplayerApi;
@@ -18,7 +18,17 @@ let nextCharacterStatusRequestId = 1;
18
18
  let activeConnection = null;
19
19
  let latestJoinAttempt = 0;
20
20
  let pendingDestinationJoin = null;
21
- export const Multiplayer = { join, joinDestination };
21
+ export const Multiplayer = { join, joinHint, joinDestination };
22
+ async function joinHint() {
23
+ try {
24
+ return await hostRequest("multiplayer.getJoinHint", {});
25
+ }
26
+ catch (error) {
27
+ if (error instanceof CastleError && error.code === "UNKNOWN_COMMAND")
28
+ return null;
29
+ throw error;
30
+ }
31
+ }
22
32
  async function join(options) {
23
33
  const params = joinParams(options);
24
34
  latestJoinAttempt += 1;
@@ -1,5 +1,6 @@
1
1
  import { CASTLE_SDK_PROTOCOL, } from "./commands";
2
2
  import { getCastleEmbed, isEdit } from "./context";
3
+ import { cardUnit, fitStage, getDisplay } from "./display";
3
4
  import { appliedNotice, applyTunedParams, } from "./paramsRegistry";
4
5
  export const CARD_RATIO = 5 / 7;
5
6
  // Host -> deck capture request, and the deck's answer. Kept in sync with the
@@ -31,6 +32,7 @@ export function setup() {
31
32
  initHostCapture();
32
33
  initPlaySelection();
33
34
  initEditSelection();
35
+ initCardUnitFallback();
34
36
  initPlayCard();
35
37
  logPanelLoad();
36
38
  }
@@ -120,7 +122,7 @@ export function initCard() {
120
122
  body { display: flex; align-items: center; justify-content: center; }
121
123
  #castle-card {
122
124
  position: relative;
123
- border-radius: 4% / calc(4% * (5 / 7));
125
+ border-radius: ${cardRadius()};
124
126
  overflow: hidden;
125
127
  background: #121213;
126
128
  }
@@ -129,10 +131,12 @@ export function initCard() {
129
131
  const card = document.createElement("div");
130
132
  card.id = "castle-card";
131
133
  document.body.appendChild(card);
134
+ initCardUnitFallback();
132
135
  function resize() {
133
136
  const { w, h } = computeCardSize();
134
137
  card.style.width = w + "px";
135
138
  card.style.height = h + "px";
139
+ setCardUnit(w, h);
136
140
  }
137
141
  resize();
138
142
  window.addEventListener("resize", resize);
@@ -231,8 +235,10 @@ function initEditSelection() {
231
235
  selection.removeAllRanges();
232
236
  });
233
237
  }
234
- // Constrains whatever the deck renders into #root to a 5:7 card in play mode.
235
- // Hosts own max size and padding; the SDK only preserves the card aspect ratio.
238
+ // Constrains whatever the deck renders into #root to the deck's stage in play
239
+ // mode: a 5:7 card, or for a `fill` deck (see display.ts) the host's whole frame
240
+ // within the deck's aspect range. Hosts own max size and padding; the SDK only
241
+ // preserves the aspect.
236
242
  function initPlayCard() {
237
243
  if (isEdit())
238
244
  return;
@@ -247,7 +253,7 @@ function initPlayCard() {
247
253
  transform: translate(-50%, -50%) !important;
248
254
  width: var(--castle-card-w, 100vw) !important;
249
255
  height: var(--castle-card-h, 100vh) !important;
250
- border-radius: 4% / calc(4% * (5 / 7)) !important;
256
+ border-radius: ${cardRadius()} !important;
251
257
  overflow: hidden !important;
252
258
  }
253
259
  `;
@@ -276,25 +282,37 @@ function initPlayCard() {
276
282
  const { w, h } = computeCardSize();
277
283
  document.documentElement.style.setProperty("--castle-card-w", w + "px");
278
284
  document.documentElement.style.setProperty("--castle-card-h", h + "px");
285
+ setCardUnit(w, h);
279
286
  }
280
287
  resize();
281
288
  window.addEventListener("resize", resize);
282
289
  }
290
+ // `--castle-unit`: 1% of the width of the largest 5:7 card inside the stage
291
+ // (display.ts cardUnit). A deck sizes HUD and text in it so they keep card
292
+ // proportions on a wide fill stage. Play mode sets the exact px value on every
293
+ // resize; the stylesheet fallback covers edit mode and the moment before the
294
+ // first resize, and follows the window -- which is not the stage where a kit's
295
+ // scene editor draws the deck smaller inside the editor.
296
+ function setCardUnit(w, h) {
297
+ document.documentElement.style.setProperty("--castle-unit", cardUnit(w, h) + "px");
298
+ }
299
+ let cardUnitFallbackInstalled = false;
300
+ function initCardUnitFallback() {
301
+ if (cardUnitFallbackInstalled)
302
+ return;
303
+ cardUnitFallbackInstalled = true;
304
+ const style = document.createElement("style");
305
+ style.textContent = `:root { --castle-unit: min(1vw, 1vh * 5 / 7); }`;
306
+ document.head.appendChild(style);
307
+ }
283
308
  function computeCardSize() {
284
309
  const pad = shouldUseStandaloneChrome() ? 20 : 0;
285
- const aw = Math.max(1, window.innerWidth - pad * 2);
286
- const ah = Math.max(1, window.innerHeight - pad * 2);
287
- let w;
288
- let h;
289
- if (aw / ah < CARD_RATIO) {
290
- w = aw;
291
- h = w / CARD_RATIO;
292
- }
293
- else {
294
- h = ah;
295
- w = h * CARD_RATIO;
296
- }
297
- return { w, h };
310
+ return fitStage(window.innerWidth - pad * 2, window.innerHeight - pad * 2, getDisplay());
311
+ }
312
+ // A card keeps its rounded corners; a fill deck runs edge to edge and the host
313
+ // decides how its frame looks.
314
+ function cardRadius() {
315
+ return getDisplay().layout === "fill" ? "0" : "4% / calc(4% * (5 / 7))";
298
316
  }
299
317
  function shouldUseStandaloneChrome() {
300
318
  if (window.parent !== window)
@@ -43,6 +43,8 @@ export interface PlatformHandle {
43
43
  *
44
44
  * Optional because a published bundle may run on a host that predates storage.
45
45
  * Rejects with an Error whose `code` is the platform's error code.
46
+ * Persistent-world journal and participant operations share this broker; the
47
+ * host stamps their world binding and participant identity.
46
48
  */
47
49
  storage?(op: string, argsJson: string): Promise<string>;
48
50
  /** False when the host cannot broker storage, so a call can fail at once. */
@@ -5,6 +5,7 @@ export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, Pla
5
5
  export type { CharacterKnowledgeSource, CompleteCharacterBeatInput, DeliverCharacterKnowledgeInput, RecordCharacterEventInput, SetCharacterGameStateInput, ShareCharacterClaimInput, ServerStorage, ServerStorageBoard, ServerStorageBoardScore, ServerStorageListEntry, ServerStorageListOptions, ServerStorageListPage, ServerPlaythrough, ServerPlaythroughCharacters, ServerCharacterHistoryOptions, ServerStorageScope, } from "./storage";
6
6
  export interface MultiplayerServerPlayer extends PlayerIdentity {
7
7
  playerId: string;
8
+ readonly participantId: string;
8
9
  }
9
10
  export interface MultiplayerBroadcastOptions {
10
11
  except?: string;
@@ -52,8 +53,65 @@ export interface MultiplayerServerWorld {
52
53
  read(): Promise<MultiplayerWorldSnapshot>;
53
54
  /** Commits exactly against expectedRevision; conflicts never partially write. */
54
55
  commit(input: MultiplayerWorldCommitInput): Promise<MultiplayerWorldCommitReceipt>;
56
+ readonly journal: MultiplayerServerWorldJournal;
57
+ readonly participants: MultiplayerServerWorldParticipants;
55
58
  readonly characters: MultiplayerServerWorldCharacters;
56
59
  }
60
+ export interface MultiplayerWorldJournalAppendInput {
61
+ operationId: string;
62
+ entries: readonly MultiplayerWorldJournalAppendEntry[];
63
+ }
64
+ export interface MultiplayerWorldJournalAppendEntry {
65
+ kind: string;
66
+ disclosure: "world" | "participants";
67
+ participantIds?: readonly string[];
68
+ data?: Json;
69
+ }
70
+ export interface MultiplayerWorldJournalAppendReceipt {
71
+ operationId: string;
72
+ replayed: boolean;
73
+ firstSeq: string;
74
+ lastSeq: string;
75
+ }
76
+ export interface MultiplayerWorldJournalReadOptions {
77
+ afterSeq?: string;
78
+ limit?: number;
79
+ participantId?: string;
80
+ }
81
+ export interface MultiplayerWorldJournalEntry {
82
+ seq: string;
83
+ kind: string;
84
+ disclosure: "world" | "participants";
85
+ participantIds: readonly string[];
86
+ data: Json;
87
+ createdAt: string;
88
+ }
89
+ export interface MultiplayerWorldJournalReadResult {
90
+ entries: readonly MultiplayerWorldJournalEntry[];
91
+ nextSeq: string;
92
+ oldestRetainedSeq: string | null;
93
+ }
94
+ export interface MultiplayerServerWorldJournal {
95
+ append(input: MultiplayerWorldJournalAppendInput): Promise<MultiplayerWorldJournalAppendReceipt>;
96
+ read(options?: MultiplayerWorldJournalReadOptions): Promise<MultiplayerWorldJournalReadResult>;
97
+ }
98
+ export interface MultiplayerWorldParticipantsReadOptions {
99
+ participantIds?: readonly string[];
100
+ limit?: number;
101
+ }
102
+ export interface MultiplayerWorldParticipant {
103
+ participantId: string;
104
+ firstSeenAt: string;
105
+ lastSeenAt: string;
106
+ lastLeftAt: string | null;
107
+ visitCount: number;
108
+ }
109
+ export interface MultiplayerWorldParticipantsReadResult {
110
+ participants: readonly MultiplayerWorldParticipant[];
111
+ }
112
+ export interface MultiplayerServerWorldParticipants {
113
+ read(options?: MultiplayerWorldParticipantsReadOptions): Promise<MultiplayerWorldParticipantsReadResult>;
114
+ }
57
115
  export interface MultiplayerServerWorldCharacters {
58
116
  create(input: MultiplayerWorldRuntimeCharacterCreateInput): Promise<MultiplayerWorldRuntimeCharacterCreateReceipt>;
59
117
  list(): Promise<MultiplayerWorldCharacterList>;