castle-web-cli 0.4.152 → 0.4.153
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.
- package/dist/castle-host/host.js +11 -3
- package/dist/castleJson.d.ts +1 -0
- package/dist/castleJson.js +14 -0
- package/dist/ide.js +4 -0
- package/dist/imports.js +18 -12
- package/dist/init.js +28 -12
- package/dist/platformDoc.js +68 -0
- package/dist/save-deck.js +14 -9
- package/dist/serve.js +24 -6
- package/dist/serveSecurity.d.ts +2 -0
- package/dist/serveSecurity.js +7 -4
- package/dist/shell/assets/{index-Dlhc3eZW.js → index-DsDkYFvP.js} +2 -2
- package/dist/shell/index.html +1 -1
- package/kits/blank/castle.json +1 -1
- package/kits/blank/node_modules/.package-lock.json +13 -0
- package/kits/blank/node_modules/castle-web-fonts/README.md +114 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/catalog.d.ts +18 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/catalog.js +142 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/face.d.ts +1 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/face.js +52 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Bore.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Bore.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/CourierPrime.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/CourierPrime.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/DMSans.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/DMSans.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Glacier.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Glacier.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Piazzolla.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Piazzolla.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Synco.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Synco.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Tektur.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Tektur.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/YatraOne.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/YatraOne.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/index.d.ts +16 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/index.js +15 -0
- package/kits/blank/node_modules/castle-web-fonts/licenses/CC-BY-ND-4.0.txt +393 -0
- package/kits/blank/node_modules/castle-web-fonts/licenses/FONTS.md +64 -0
- package/kits/blank/node_modules/castle-web-fonts/licenses/OFL-1.1.txt +95 -0
- package/kits/blank/node_modules/castle-web-fonts/package.json +47 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/Bore.woff2 +0 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/CourierPrime.woff2 +0 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/DMSans.woff2 +0 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/Glacier.woff2 +0 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/HelicoCentrica.woff2 +0 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/Piazzolla.woff2 +0 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/SOURCE.txt +2 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/Synco.woff2 +0 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/Tektur.woff2 +0 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/YatraOne.woff2 +0 -0
- package/kits/blank/package-lock.json +10 -1
- package/kits/blank/package.json +3 -1
- package/kits/physics-2d/CLAUDE.md +158 -40
- package/kits/physics-2d/castle.json +3 -2
- package/kits/physics-2d/editors/SingleEditor.jsx +52 -19
- package/kits/physics-2d/editors/StyleEditor.jsx +139 -40
- package/kits/physics-2d/editors/deckFont.js +88 -0
- package/kits/physics-2d/editors/fontPreview.js +66 -0
- package/kits/physics-2d/editors/styleEditor.module.css +30 -3
- package/kits/physics-2d/editors/styleTheme.js +13 -2
- package/kits/physics-2d/engine/ScenePlayer.jsx +17 -2
- package/kits/physics-2d/engine/SceneUI.jsx +8 -0
- package/kits/physics-2d/engine/files.js +20 -9
- package/kits/physics-2d/engine/fonts.js +79 -0
- package/kits/physics-2d/engine/scene.js +6 -0
- package/kits/physics-2d/fonts.generated.js +9 -0
- package/kits/physics-2d/main.jsx +11 -0
- package/kits/physics-2d/package-lock.json +8 -1
- package/kits/physics-2d/package.json +1 -0
- package/kits/physics-2d/theme.style +2 -1
- package/kits/physics-3d/castle.json +1 -1
- package/kits/physics-3d/engine3d/PxModelEditor.jsx +3 -4
- package/kits/physics-3d/engine3d/Scene3DEditor.jsx +12 -8
- package/kits/physics-3d/engine3d/editorChrome.jsx +11 -6
- package/kits/physics-3d/engine3d/modelFiles.js +4 -5
- package/kits/physics-3d/package-lock.json +8 -1
- package/kits/physics-3d/package.json +1 -0
- package/kits/tabletop/.prettierrc +8 -0
- package/kits/tabletop/CLAUDE.md +309 -0
- package/kits/tabletop/castle.json +34 -0
- package/kits/tabletop/index.html +20 -0
- package/kits/tabletop/main.jsx +8 -0
- package/kits/tabletop/package-lock.json +341 -0
- package/kits/tabletop/package.json +29 -0
- package/kits/tabletop/room.js +269 -0
- package/kits/tabletop/testing.js +569 -0
- package/package.json +1 -1
- package/kits/blank/.castle/agent/children.json +0 -1
- package/kits/blank/.castle/agent/messages.json +0 -9
- package/kits/blank/.castle/agent/pending-sends.json +0 -1
- package/kits/blank/.castle/agent/tasks/index.md +0 -2
- package/kits/blank/.castle/docs/platform.md +0 -36
- package/kits/blank/node_modules/.vite/deps/_metadata.json +0 -8
- package/kits/blank/node_modules/.vite/deps/package.json +0 -3
|
@@ -0,0 +1,569 @@
|
|
|
1
|
+
// Everything a deck needs to test its server from a plain node script: a
|
|
2
|
+
// `MultiplayerServerSession` double, a movable clock, the room conformance
|
|
3
|
+
// suite, and the resolver hook that makes `@imports/` mean the same thing under
|
|
4
|
+
// `node` as it does in the deck.
|
|
5
|
+
//
|
|
6
|
+
// Run it from the deck directory, with this file as the `--import`:
|
|
7
|
+
//
|
|
8
|
+
// node --import ./imports/castle.tabletop/testing.js tools/check.mjs
|
|
9
|
+
//
|
|
10
|
+
// See "the @imports resolver" below for why that flag is needed at all.
|
|
11
|
+
|
|
12
|
+
import { register } from 'node:module';
|
|
13
|
+
import * as path from 'node:path';
|
|
14
|
+
import { pathToFileURL } from 'node:url';
|
|
15
|
+
import { restoreNow, setNow } from './room.js';
|
|
16
|
+
|
|
17
|
+
// --- the @imports resolver ------------------------------------------------
|
|
18
|
+
//
|
|
19
|
+
// `@imports/<alias>/...` is a Castle specifier: the CLI's vite plugin rewrites
|
|
20
|
+
// it to `<deck root>/imports/<alias>/...` for the dev server and for both
|
|
21
|
+
// bundlers. A deck's test script is neither -- it is `node tools/check.mjs` --
|
|
22
|
+
// so without this hook a server module written the blessed way cannot be
|
|
23
|
+
// imported by the tests that are supposed to check it, and the deck ends up
|
|
24
|
+
// with a relative path in production to keep node happy.
|
|
25
|
+
//
|
|
26
|
+
// The deck root is the working directory, which is the deck's own directory
|
|
27
|
+
// when its scripts run from `package.json`. `CASTLE_DECK_ROOT` overrides it.
|
|
28
|
+
|
|
29
|
+
const IMPORTS_PREFIX = '@imports/';
|
|
30
|
+
|
|
31
|
+
export async function resolve(specifier, context, nextResolve) {
|
|
32
|
+
if (!specifier.startsWith(IMPORTS_PREFIX)) return nextResolve(specifier, context);
|
|
33
|
+
const root = process.env.CASTLE_DECK_ROOT ?? process.cwd();
|
|
34
|
+
const target = path.join(root, 'imports', specifier.slice(IMPORTS_PREFIX.length));
|
|
35
|
+
return nextResolve(pathToFileURL(target).href, context);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
// Registering this same module is what lets one `--import` do both jobs. Node
|
|
39
|
+
// evaluates the file a second time inside its loader thread to read the hook;
|
|
40
|
+
// that copy registers once more and stops there, and nothing here has a
|
|
41
|
+
// top-level side effect for the second evaluation to duplicate.
|
|
42
|
+
register(import.meta.url);
|
|
43
|
+
|
|
44
|
+
// --- the session double ---------------------------------------------------
|
|
45
|
+
//
|
|
46
|
+
// A stand-in for `MultiplayerServerSession`, so a deck's server callbacks can be
|
|
47
|
+
// driven from a plain node script. It copies the real wrapper
|
|
48
|
+
// (`sdk/src/server/wrapper.ts`) where the copying matters, because the details
|
|
49
|
+
// it gets right are exactly the ones a room gets wrong:
|
|
50
|
+
//
|
|
51
|
+
// - the joining player is in `session.players` BEFORE `onPlayerJoin` runs;
|
|
52
|
+
// - the leaving player is OUT of it before `onPlayerLeave` runs;
|
|
53
|
+
// - players are keyed by `playerId`, which is a connection, not an account --
|
|
54
|
+
// two tabs of one account are two players;
|
|
55
|
+
// - every message crosses as JSON, so a payload that holds a live reference to
|
|
56
|
+
// the server's own state arrives as a copy, and one that cannot be
|
|
57
|
+
// stringified throws here rather than in production.
|
|
58
|
+
//
|
|
59
|
+
// It is not a transport: callbacks run synchronously, and a callback that
|
|
60
|
+
// returns a promise is not awaited. That is enough for room and rule tests, and
|
|
61
|
+
// a two-client game over the real socket is still the thing that proves a deck.
|
|
62
|
+
|
|
63
|
+
let sessionCounter = 0;
|
|
64
|
+
|
|
65
|
+
// `server` is the deck's default export from `server/index.js`.
|
|
66
|
+
// Options: `mode` ('public' | 'named' | 'party'), `sessionId`, `deckId`.
|
|
67
|
+
export function createSessionHarness(server, options = {}) {
|
|
68
|
+
const sessionId = options.sessionId ?? `test-session-${++sessionCounter}`;
|
|
69
|
+
const players = new Map();
|
|
70
|
+
const outbox = [];
|
|
71
|
+
const session = createSession(sessionId, options, players, outbox);
|
|
72
|
+
const harness = {
|
|
73
|
+
session,
|
|
74
|
+
outbox,
|
|
75
|
+
sessionId,
|
|
76
|
+
start: () => server.onStart?.(session),
|
|
77
|
+
join: (playerId, identity) => joinPlayer(server, session, players, playerId, identity),
|
|
78
|
+
leave: (player) => leavePlayer(server, session, players, player),
|
|
79
|
+
message: (player, data) => messageFrom(server, session, players, player, data),
|
|
80
|
+
// Every message this player has been sent, oldest first, already decoded.
|
|
81
|
+
sent: (playerId) => outbox.filter((entry) => entry.playerId === playerId).map((e) => e.data),
|
|
82
|
+
// The last one, optionally the last one matching a predicate -- a deck that
|
|
83
|
+
// sends more than one kind of message asks for the kind it renders.
|
|
84
|
+
last: (playerId, match) => lastSent(outbox, playerId, match),
|
|
85
|
+
};
|
|
86
|
+
harness.start();
|
|
87
|
+
return harness;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
function createSession(sessionId, options, players, outbox) {
|
|
91
|
+
return {
|
|
92
|
+
get players() {
|
|
93
|
+
return Array.from(players.values());
|
|
94
|
+
},
|
|
95
|
+
sessionId,
|
|
96
|
+
deckId: options.deckId ?? 'test-deck',
|
|
97
|
+
mode: options.mode ?? 'public',
|
|
98
|
+
send(playerId, data) {
|
|
99
|
+
outbox.push({ playerId, data: encode(data) });
|
|
100
|
+
},
|
|
101
|
+
broadcast(data, broadcastOptions) {
|
|
102
|
+
const encoded = encode(data);
|
|
103
|
+
for (const playerId of players.keys()) {
|
|
104
|
+
if (playerId !== broadcastOptions?.except) outbox.push({ playerId, data: encoded });
|
|
105
|
+
}
|
|
106
|
+
},
|
|
107
|
+
disconnect(playerId) {
|
|
108
|
+
const player = players.get(playerId);
|
|
109
|
+
if (player) players.delete(playerId);
|
|
110
|
+
return player ?? null;
|
|
111
|
+
},
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
// Messages cross the real transport as text, so they cross this one as text too.
|
|
116
|
+
// Encoding per recipient would be truer still, but a broadcast that shared one
|
|
117
|
+
// mutable object between players is the bug this is guarding against and one
|
|
118
|
+
// copy already prevents it.
|
|
119
|
+
function encode(data) {
|
|
120
|
+
const text = JSON.stringify(data);
|
|
121
|
+
if (text === undefined) {
|
|
122
|
+
throw new TypeError('Multiplayer server messages must be JSON-serializable.');
|
|
123
|
+
}
|
|
124
|
+
return JSON.parse(text);
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
function joinPlayer(server, session, players, playerId, identity = {}) {
|
|
128
|
+
const player = {
|
|
129
|
+
playerId,
|
|
130
|
+
userId: identity.userId ?? playerId,
|
|
131
|
+
username: identity.username ?? playerId,
|
|
132
|
+
isAnonymous: identity.isAnonymous ?? false,
|
|
133
|
+
};
|
|
134
|
+
players.set(playerId, player); // in the roster before the callback, as upstream
|
|
135
|
+
server.onPlayerJoin?.(session, player);
|
|
136
|
+
return player;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
function leavePlayer(server, session, players, player) {
|
|
140
|
+
const known = players.get(player.playerId);
|
|
141
|
+
if (!known) return null;
|
|
142
|
+
players.delete(player.playerId); // out of the roster before the callback
|
|
143
|
+
server.onPlayerLeave?.(session, known);
|
|
144
|
+
return known;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
function messageFrom(server, session, players, player, data) {
|
|
148
|
+
const known = players.get(player.playerId);
|
|
149
|
+
if (!known) return; // upstream drops messages from a connection it has closed
|
|
150
|
+
server.onMessage?.(session, known, encode(data));
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
function lastSent(outbox, playerId, match) {
|
|
154
|
+
for (let i = outbox.length - 1; i >= 0; i--) {
|
|
155
|
+
const entry = outbox[i];
|
|
156
|
+
if (entry.playerId !== playerId) continue;
|
|
157
|
+
if (!match || match(entry.data)) return entry.data;
|
|
158
|
+
}
|
|
159
|
+
return null;
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
// A clock the kit's rooms read, that a test can move. `advance` is how a check
|
|
163
|
+
// ages a table past an idle window without waiting minutes for it.
|
|
164
|
+
export function createTestClock(startAt = Date.now()) {
|
|
165
|
+
let t = startAt;
|
|
166
|
+
const clock = {
|
|
167
|
+
now: () => t,
|
|
168
|
+
advance: (ms) => {
|
|
169
|
+
t += ms;
|
|
170
|
+
return t;
|
|
171
|
+
},
|
|
172
|
+
set: (at) => {
|
|
173
|
+
t = at;
|
|
174
|
+
return t;
|
|
175
|
+
},
|
|
176
|
+
// Point the kit's clock at this one, and back at the wall clock after.
|
|
177
|
+
install: () => setNow(clock.now),
|
|
178
|
+
uninstall: () => restoreNow(),
|
|
179
|
+
};
|
|
180
|
+
return clock;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
// --- the room conformance suite -------------------------------------------
|
|
184
|
+
//
|
|
185
|
+
// The room rules, checked against a real deck's server.
|
|
186
|
+
//
|
|
187
|
+
// Every deck built on this kit should run these. They are the same rules for
|
|
188
|
+
// everyone -- who gets a seat, what a drop does, what an arrival is handed --
|
|
189
|
+
// so writing them once per deck only produces three chances to get them wrong.
|
|
190
|
+
// The check named "a seated player dropping leaves the game standing" is the one
|
|
191
|
+
// that matters most: it is the bug the kit exists to make unrepresentable, and
|
|
192
|
+
// it shipped in a deck.
|
|
193
|
+
//
|
|
194
|
+
// The deck supplies four hooks, all small:
|
|
195
|
+
//
|
|
196
|
+
// play(harness, seated) make ONE move the server will accept, from
|
|
197
|
+
// whichever seated player is allowed to make it.
|
|
198
|
+
// Called more than once in a row.
|
|
199
|
+
// junk(harness, player) send things the server must refuse: an illegal
|
|
200
|
+
// move, a malformed body, an unknown type. It is
|
|
201
|
+
// always called with `seated[0]`, who may not be
|
|
202
|
+
// the side to move -- so every message in it has
|
|
203
|
+
// to be one BOTH seats would be refused.
|
|
204
|
+
// snapshot(harness, playerId) the PUBLIC game -- board, turn, counts, whose
|
|
205
|
+
// win. Not the seat list, the names, or the
|
|
206
|
+
// watcher count, which change for reasons that
|
|
207
|
+
// are not the game changing; and not a player's
|
|
208
|
+
// private view, because five scenarios below
|
|
209
|
+
// compare one player's snapshot to another's.
|
|
210
|
+
// seatOf(harness, playerId) the seat that player holds, or null.
|
|
211
|
+
//
|
|
212
|
+
// plus `server` (the deck's default export), `seats` (how many), `idleMs`,
|
|
213
|
+
// `graceMs`, and `minPlayers` if it is not every seat.
|
|
214
|
+
|
|
215
|
+
export function checkRoom(options) {
|
|
216
|
+
const ctx = { ...options, minPlayers: options.minPlayers ?? options.seats, results: [] };
|
|
217
|
+
const clock = createTestClock();
|
|
218
|
+
clock.install();
|
|
219
|
+
try {
|
|
220
|
+
for (const scenario of SCENARIOS) scenario(ctx, clock);
|
|
221
|
+
} finally {
|
|
222
|
+
clock.uninstall();
|
|
223
|
+
}
|
|
224
|
+
return { results: ctx.results, failures: ctx.results.filter((r) => !r.ok).length };
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
// Prints one line per check and returns the failure count, so a deck's test
|
|
228
|
+
// script is `process.exit(printRoomChecks(checkRoom({...})))`.
|
|
229
|
+
export function printRoomChecks(outcome) {
|
|
230
|
+
for (const r of outcome.results) {
|
|
231
|
+
const detail = r.ok ? '' : `\n got ${json(r.actual)}\n want ${r.label}`;
|
|
232
|
+
console.log(`${r.ok ? 'ok ' : 'FAIL'} ${r.name}${detail}`);
|
|
233
|
+
}
|
|
234
|
+
console.log(outcome.failures === 0 ? '\nroom checks passed' : `\n${outcome.failures} FAILED`);
|
|
235
|
+
return outcome.failures;
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
function json(value) {
|
|
239
|
+
return JSON.stringify(value);
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
function check(ctx, name, actual, expected) {
|
|
243
|
+
const ok = json(actual) === json(expected);
|
|
244
|
+
ctx.results.push({ name, ok, actual, label: json(expected) });
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
function checkNot(ctx, name, actual, unexpected) {
|
|
248
|
+
const ok = json(actual) !== json(unexpected);
|
|
249
|
+
ctx.results.push({ name, ok, actual, label: `anything but ${json(unexpected)}` });
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
// --- scenario scaffolding -------------------------------------------------
|
|
253
|
+
|
|
254
|
+
let counter = 0;
|
|
255
|
+
|
|
256
|
+
// A session with every seat taken, and nothing played yet.
|
|
257
|
+
function seatedTable(ctx, mode = 'public') {
|
|
258
|
+
const harness = createSessionHarness(ctx.server, { mode, sessionId: `check-${++counter}` });
|
|
259
|
+
const seated = [];
|
|
260
|
+
for (let i = 0; i < ctx.seats; i++) seated.push(harness.join(`${harness.sessionId}-p${i}`));
|
|
261
|
+
return { harness, seated };
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
// The same, with one accepted move on it.
|
|
265
|
+
function playedTable(ctx, mode = 'public') {
|
|
266
|
+
const table = seatedTable(ctx, mode);
|
|
267
|
+
ctx.play(table.harness, table.seated);
|
|
268
|
+
return table;
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
// The game as a brand-new table looks, for comparing a cleared table against.
|
|
272
|
+
function freshGame(ctx) {
|
|
273
|
+
if (ctx.freshCache === undefined) {
|
|
274
|
+
const { harness, seated } = seatedTable(ctx);
|
|
275
|
+
ctx.freshCache = ctx.snapshot(harness, seated[0].playerId);
|
|
276
|
+
}
|
|
277
|
+
return ctx.freshCache;
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
// How many seated players have to go before the table stops being covered.
|
|
281
|
+
function dropsToUncover(ctx) {
|
|
282
|
+
return ctx.seats - ctx.minPlayers + 1;
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
function leaveSome(table, count) {
|
|
286
|
+
const gone = table.seated.slice(-count);
|
|
287
|
+
for (const player of gone) table.harness.leave(player);
|
|
288
|
+
return gone;
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
function leaveAll(table) {
|
|
292
|
+
for (const player of table.seated) table.harness.leave(player);
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
// --- scenarios ------------------------------------------------------------
|
|
296
|
+
|
|
297
|
+
// If this one fails, nothing below means anything: the hooks are wrong, not the
|
|
298
|
+
// deck.
|
|
299
|
+
function hooksWork(ctx) {
|
|
300
|
+
const { harness, seated } = playedTable(ctx);
|
|
301
|
+
checkNot(
|
|
302
|
+
ctx,
|
|
303
|
+
'the play hook changes the game',
|
|
304
|
+
ctx.snapshot(harness, seated[0].playerId),
|
|
305
|
+
freshGame(ctx)
|
|
306
|
+
);
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
function seating(ctx) {
|
|
310
|
+
const { harness, seated } = seatedTable(ctx);
|
|
311
|
+
const held = seated.map((p) => ctx.seatOf(harness, p.playerId));
|
|
312
|
+
check(ctx, 'every seat is taken, each by a different player', new Set(held).size, ctx.seats);
|
|
313
|
+
check(ctx, 'no arrival is left seatless while a seat is free', held.includes(null), false);
|
|
314
|
+
const watcher = harness.join(`${harness.sessionId}-extra`);
|
|
315
|
+
check(ctx, 'past the last seat, an arrival watches', ctx.seatOf(harness, watcher.playerId), null);
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
// Seating by connection rather than by account is also what makes two-tab local
|
|
319
|
+
// testing work at all.
|
|
320
|
+
function twoTabsOfOneAccount(ctx) {
|
|
321
|
+
const harness = createSessionHarness(ctx.server, { sessionId: `check-${++counter}` });
|
|
322
|
+
const a = harness.join('tab-a', { userId: 'one-account', username: 'nikki' });
|
|
323
|
+
const b = harness.join('tab-b', { userId: 'one-account', username: 'nikki' });
|
|
324
|
+
const held = [ctx.seatOf(harness, a.playerId), ctx.seatOf(harness, b.playerId)];
|
|
325
|
+
check(ctx, 'two tabs of one account take two seats', new Set(held).size, 2);
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
// The bug this kit exists for: one player's connection blips and the other
|
|
329
|
+
// player's game disappears from under them.
|
|
330
|
+
function dropDoesNotDestroy(ctx) {
|
|
331
|
+
const table = playedTable(ctx);
|
|
332
|
+
const stays = table.seated[0].playerId;
|
|
333
|
+
const before = ctx.snapshot(table.harness, stays);
|
|
334
|
+
leaveSome(table, dropsToUncover(ctx));
|
|
335
|
+
check(
|
|
336
|
+
ctx,
|
|
337
|
+
'a seated player dropping leaves the game standing',
|
|
338
|
+
ctx.snapshot(table.harness, stays),
|
|
339
|
+
before
|
|
340
|
+
);
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
function watcherIsPromoted(ctx) {
|
|
344
|
+
const table = playedTable(ctx);
|
|
345
|
+
const watcher = table.harness.join(`${table.harness.sessionId}-w`);
|
|
346
|
+
const leaver = table.seated[table.seated.length - 1];
|
|
347
|
+
const freed = ctx.seatOf(table.harness, leaver.playerId);
|
|
348
|
+
table.harness.leave(leaver);
|
|
349
|
+
check(
|
|
350
|
+
ctx,
|
|
351
|
+
'a watcher is promoted into the vacated seat',
|
|
352
|
+
ctx.seatOf(table.harness, watcher.playerId),
|
|
353
|
+
freed
|
|
354
|
+
);
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
function reconnectKeepsItsSeat(ctx, clock) {
|
|
358
|
+
const table = playedTable(ctx);
|
|
359
|
+
const stays = table.seated[0].playerId;
|
|
360
|
+
const before = ctx.snapshot(table.harness, stays);
|
|
361
|
+
const leaver = table.seated[table.seated.length - 1];
|
|
362
|
+
const seat = ctx.seatOf(table.harness, leaver.playerId);
|
|
363
|
+
table.harness.leave(leaver);
|
|
364
|
+
clock.advance(Math.max(1, Math.floor(ctx.graceMs / 2)));
|
|
365
|
+
table.harness.join(leaver.playerId);
|
|
366
|
+
check(
|
|
367
|
+
ctx,
|
|
368
|
+
'a reconnect inside the grace window gets its own seat back',
|
|
369
|
+
ctx.seatOf(table.harness, leaver.playerId),
|
|
370
|
+
seat
|
|
371
|
+
);
|
|
372
|
+
check(ctx, '...and the game with it', ctx.snapshot(table.harness, stays), before);
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
function presentOutranksGhost(ctx) {
|
|
376
|
+
const table = playedTable(ctx);
|
|
377
|
+
const watcher = table.harness.join(`${table.harness.sessionId}-w`);
|
|
378
|
+
const leaver = table.seated[table.seated.length - 1];
|
|
379
|
+
const seat = ctx.seatOf(table.harness, leaver.playerId);
|
|
380
|
+
table.harness.leave(leaver);
|
|
381
|
+
table.harness.join(leaver.playerId);
|
|
382
|
+
check(
|
|
383
|
+
ctx,
|
|
384
|
+
'a promoted watcher outranks a reconnecting ghost',
|
|
385
|
+
ctx.seatOf(table.harness, watcher.playerId),
|
|
386
|
+
seat
|
|
387
|
+
);
|
|
388
|
+
checkNot(
|
|
389
|
+
ctx,
|
|
390
|
+
'...so the returning player does not get its seat back',
|
|
391
|
+
ctx.seatOf(table.harness, leaver.playerId),
|
|
392
|
+
seat
|
|
393
|
+
);
|
|
394
|
+
}
|
|
395
|
+
|
|
396
|
+
// Everyone dropped and one of them came back inside the window: still their own
|
|
397
|
+
// game, however alone they are.
|
|
398
|
+
function reconnectAloneKeepsTheGame(ctx, clock) {
|
|
399
|
+
const table = playedTable(ctx);
|
|
400
|
+
const before = ctx.snapshot(table.harness, table.seated[0].playerId);
|
|
401
|
+
leaveAll(table);
|
|
402
|
+
clock.advance(Math.max(1, Math.floor(ctx.graceMs / 2)));
|
|
403
|
+
const back = table.harness.join(table.seated[0].playerId);
|
|
404
|
+
check(
|
|
405
|
+
ctx,
|
|
406
|
+
'a lone reconnect inside the grace window keeps its own game',
|
|
407
|
+
ctx.snapshot(table.harness, back.playerId),
|
|
408
|
+
before
|
|
409
|
+
);
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
function loneArrivalGetsACleanTable(ctx, clock) {
|
|
413
|
+
const table = playedTable(ctx);
|
|
414
|
+
leaveAll(table);
|
|
415
|
+
clock.advance(ctx.graceMs + 1);
|
|
416
|
+
const arrival = table.harness.join(`${table.harness.sessionId}-new`);
|
|
417
|
+
check(
|
|
418
|
+
ctx,
|
|
419
|
+
'a lone arrival gets a clean table',
|
|
420
|
+
ctx.snapshot(table.harness, arrival.playerId),
|
|
421
|
+
freshGame(ctx)
|
|
422
|
+
);
|
|
423
|
+
}
|
|
424
|
+
|
|
425
|
+
function staleTableIsCleared(ctx, clock) {
|
|
426
|
+
const table = playedTable(ctx);
|
|
427
|
+
leaveSome(table, dropsToUncover(ctx));
|
|
428
|
+
clock.advance(ctx.idleMs + 1);
|
|
429
|
+
const arrival = table.harness.join(`${table.harness.sessionId}-new`);
|
|
430
|
+
check(
|
|
431
|
+
ctx,
|
|
432
|
+
'a table untouched for the idle window is cleared for an arrival',
|
|
433
|
+
ctx.snapshot(table.harness, arrival.playerId),
|
|
434
|
+
freshGame(ctx)
|
|
435
|
+
);
|
|
436
|
+
}
|
|
437
|
+
|
|
438
|
+
function recentTableIsKept(ctx, clock) {
|
|
439
|
+
const table = playedTable(ctx);
|
|
440
|
+
const before = ctx.snapshot(table.harness, table.seated[0].playerId);
|
|
441
|
+
leaveSome(table, dropsToUncover(ctx));
|
|
442
|
+
clock.advance(Math.max(1, Math.floor(ctx.idleMs / 2)));
|
|
443
|
+
const arrival = table.harness.join(`${table.harness.sessionId}-new`);
|
|
444
|
+
check(
|
|
445
|
+
ctx,
|
|
446
|
+
'a recently played table with a free seat is kept',
|
|
447
|
+
ctx.snapshot(table.harness, arrival.playerId),
|
|
448
|
+
before
|
|
449
|
+
);
|
|
450
|
+
}
|
|
451
|
+
|
|
452
|
+
// The idle window is only ever consulted when the table is short of players, so
|
|
453
|
+
// however long the people at it stare at the board, nothing takes it away.
|
|
454
|
+
function coveredTableSurvivesALongThink(ctx, clock) {
|
|
455
|
+
const table = playedTable(ctx);
|
|
456
|
+
const before = ctx.snapshot(table.harness, table.seated[0].playerId);
|
|
457
|
+
clock.advance(ctx.idleMs * 10);
|
|
458
|
+
const arrival = table.harness.join(`${table.harness.sessionId}-w`);
|
|
459
|
+
check(
|
|
460
|
+
ctx,
|
|
461
|
+
'a long think with the seats covered is never cleared',
|
|
462
|
+
ctx.snapshot(table.harness, arrival.playerId),
|
|
463
|
+
before
|
|
464
|
+
);
|
|
465
|
+
check(ctx, '...and the arrival watches', ctx.seatOf(table.harness, arrival.playerId), null);
|
|
466
|
+
}
|
|
467
|
+
|
|
468
|
+
function refusedMessagesDoNotRefreshTheClock(ctx, clock) {
|
|
469
|
+
const table = playedTable(ctx);
|
|
470
|
+
const half = Math.max(1, Math.floor(ctx.idleMs * 0.6));
|
|
471
|
+
clock.advance(half);
|
|
472
|
+
ctx.junk(table.harness, table.seated[0]);
|
|
473
|
+
clock.advance(half);
|
|
474
|
+
leaveSome(table, dropsToUncover(ctx));
|
|
475
|
+
const arrival = table.harness.join(`${table.harness.sessionId}-new`);
|
|
476
|
+
check(
|
|
477
|
+
ctx,
|
|
478
|
+
'refused messages do not refresh the idle clock',
|
|
479
|
+
ctx.snapshot(table.harness, arrival.playerId),
|
|
480
|
+
freshGame(ctx)
|
|
481
|
+
);
|
|
482
|
+
}
|
|
483
|
+
|
|
484
|
+
function acceptedMovesDoRefreshTheClock(ctx, clock) {
|
|
485
|
+
const table = playedTable(ctx);
|
|
486
|
+
const half = Math.max(1, Math.floor(ctx.idleMs * 0.6));
|
|
487
|
+
clock.advance(half);
|
|
488
|
+
ctx.play(table.harness, table.seated);
|
|
489
|
+
const before = ctx.snapshot(table.harness, table.seated[0].playerId);
|
|
490
|
+
clock.advance(half);
|
|
491
|
+
leaveSome(table, dropsToUncover(ctx));
|
|
492
|
+
const arrival = table.harness.join(`${table.harness.sessionId}-new`);
|
|
493
|
+
check(
|
|
494
|
+
ctx,
|
|
495
|
+
'an accepted move does refresh it',
|
|
496
|
+
ctx.snapshot(table.harness, arrival.playerId),
|
|
497
|
+
before
|
|
498
|
+
);
|
|
499
|
+
}
|
|
500
|
+
|
|
501
|
+
// A party spins up its own session and a new one arrives constantly, so what a
|
|
502
|
+
// party session holds belongs to the people showing up. Nothing is cleared.
|
|
503
|
+
function partyTableIsNeverCleared(ctx, clock) {
|
|
504
|
+
const table = playedTable(ctx, 'party');
|
|
505
|
+
const before = ctx.snapshot(table.harness, table.seated[0].playerId);
|
|
506
|
+
leaveAll(table);
|
|
507
|
+
clock.advance(ctx.graceMs + ctx.idleMs + 1);
|
|
508
|
+
const arrival = table.harness.join(`${table.harness.sessionId}-new`);
|
|
509
|
+
check(
|
|
510
|
+
ctx,
|
|
511
|
+
'a party table survives a lone arrival and the idle window',
|
|
512
|
+
ctx.snapshot(table.harness, arrival.playerId),
|
|
513
|
+
before
|
|
514
|
+
);
|
|
515
|
+
}
|
|
516
|
+
|
|
517
|
+
// `named` is what a local serve reports for every session, so it is the branch a
|
|
518
|
+
// serve actually exercises. It must behave like public, not like party.
|
|
519
|
+
function namedBehavesLikePublic(ctx, clock) {
|
|
520
|
+
const table = playedTable(ctx, 'named');
|
|
521
|
+
leaveAll(table);
|
|
522
|
+
clock.advance(ctx.graceMs + 1);
|
|
523
|
+
const arrival = table.harness.join(`${table.harness.sessionId}-new`);
|
|
524
|
+
check(
|
|
525
|
+
ctx,
|
|
526
|
+
'a named session still clears for a lone arrival',
|
|
527
|
+
ctx.snapshot(table.harness, arrival.playerId),
|
|
528
|
+
freshGame(ctx)
|
|
529
|
+
);
|
|
530
|
+
}
|
|
531
|
+
|
|
532
|
+
// Two sessions must not share a table. A module-level game object is the usual
|
|
533
|
+
// way this goes wrong.
|
|
534
|
+
function sessionsDoNotLeak(ctx) {
|
|
535
|
+
const a = playedTable(ctx);
|
|
536
|
+
const b = seatedTable(ctx);
|
|
537
|
+
check(
|
|
538
|
+
ctx,
|
|
539
|
+
'a second session has its own table',
|
|
540
|
+
ctx.snapshot(b.harness, b.seated[0].playerId),
|
|
541
|
+
freshGame(ctx)
|
|
542
|
+
);
|
|
543
|
+
checkNot(
|
|
544
|
+
ctx,
|
|
545
|
+
'...and the first one still has its game',
|
|
546
|
+
ctx.snapshot(a.harness, a.seated[0].playerId),
|
|
547
|
+
freshGame(ctx)
|
|
548
|
+
);
|
|
549
|
+
}
|
|
550
|
+
|
|
551
|
+
const SCENARIOS = [
|
|
552
|
+
hooksWork,
|
|
553
|
+
seating,
|
|
554
|
+
twoTabsOfOneAccount,
|
|
555
|
+
dropDoesNotDestroy,
|
|
556
|
+
watcherIsPromoted,
|
|
557
|
+
reconnectKeepsItsSeat,
|
|
558
|
+
presentOutranksGhost,
|
|
559
|
+
reconnectAloneKeepsTheGame,
|
|
560
|
+
loneArrivalGetsACleanTable,
|
|
561
|
+
staleTableIsCleared,
|
|
562
|
+
recentTableIsKept,
|
|
563
|
+
coveredTableSurvivesALongThink,
|
|
564
|
+
refusedMessagesDoNotRefreshTheClock,
|
|
565
|
+
acceptedMovesDoRefreshTheClock,
|
|
566
|
+
partyTableIsNeverCleared,
|
|
567
|
+
namedBehavesLikePublic,
|
|
568
|
+
sessionsDoNotLeak,
|
|
569
|
+
];
|
package/package.json
CHANGED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
[]
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
[
|
|
2
|
-
{
|
|
3
|
-
"id": "YzUYA2mw",
|
|
4
|
-
"role": "assistant",
|
|
5
|
-
"text": "Welcome to an early test of Castle's new engine! You're starting with a blank deck, without the official art or scene editors, but if HTML and JavaScript can do it then I can help you build it.\n\nDo you already know what you want to make, or do you want to figure it out together?",
|
|
6
|
-
"at": "2026-08-27T19:05:49.289Z",
|
|
7
|
-
"status": "done"
|
|
8
|
-
}
|
|
9
|
-
]
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
[]
|
|
@@ -1,36 +0,0 @@
|
|
|
1
|
-
# Castle platform
|
|
2
|
-
|
|
3
|
-
How every Castle deck works, from the Castle CLI. Written fresh at every serve
|
|
4
|
-
start; the deck's own guide (its kit's CLAUDE.md under imports/) adds what its
|
|
5
|
-
kit provides on top of this.
|
|
6
|
-
|
|
7
|
-
## Imports are read-only
|
|
8
|
-
|
|
9
|
-
- **`imports/` holds other decks' files and is locked read-only on disk.** Files are mode 0444 and directories 0555, so any shell command that writes, moves, or deletes inside `imports/` fails with `EACCES` / "Permission denied" — that is the lock working, not a broken checkout. Do not `chmod` around it, do not `sudo`, and do not retry the command a different way.
|
|
10
|
-
- **Change an import through the CLI, never the filesystem.** `castle-web add-import <deckIdOrUrl>` adds one and `castle-web update-import [alias]` re-fetches it (`--check` to see if it is outdated, `--revert` to undo). These handle the unlock/relock themselves.
|
|
11
|
-
- **`castle-web list-decks [--kind mine|saved|kits]` is how you find out WHAT can be imported** — one deck per line, starting with the id `add-import` takes, and marked when this deck already has it. `imports/` only shows what is here already; it is not a catalogue.
|
|
12
|
-
- **To change one file of an import, FORK it**: `castle-web fork-import-file <path>` takes this deck's own version of that file, and every reference to the imported path uses your version from then on (`castle-web revert-import-file <path>` drops it and goes back to the import's). Fork only what you actually need to change, and as few files as you can -- a forked file stops taking the import's updates, so the more you fork the less an `update-import` can give you. To build something of your own rather than change theirs, write an ordinary file in this deck instead -- and check first whether the kit already lets a deck file register what you want (its CLAUDE.md names those seams), since that path keeps taking updates and a fork does not. When you do fork, it is often worth forking only to add a hook or registration point and keeping the logic itself in a deck file, so later changes need no further forks; for a quick one-off tweak a plain direct fork is fine.
|
|
13
|
-
- **Deleting the deck directory itself needs the lock released first** (`chmod -R u+w` on the deck dir) — that is the one legitimate reason to touch the modes, and only for a directory being thrown away.
|
|
14
|
-
|
|
15
|
-
## Assets
|
|
16
|
-
|
|
17
|
-
- **Load static assets (drawings, audio, etc.) through the bundler — never runtime-`fetch` a loose file path.** Use a static `import`, `import.meta.glob('./drawings/*.svg', { eager: true, import: 'default' })`, or inline the asset directly. The dev serve happens to serve loose files over HTTP, so `fetch('drawings/qb.svg')` looks like it works locally — but `save-deck` bundles the whole deck into a single file, loose files are no longer served, and the fetch silently fails on every platform. Kit decks: use the kit's own drawing/asset-loading APIs instead of a raw `fetch`.
|
|
18
|
-
|
|
19
|
-
## Touch controls
|
|
20
|
-
|
|
21
|
-
- **Playable on a touchscreen, with only the controls the game actually needs.** Castle decks are played on phones, so whatever input a game does use must work by touch — direct tap/drag on the game itself wherever possible, and on-screen buttons only where the mechanics genuinely call for them. Do NOT add controls a game doesn't need: never drop in a generic d-pad or movement overlay by default. Prefer touching the game directly over an overlay that just mirrors keyboard keys. Keyboard input is fine to support on top for desktop play. Match the controls to the actual mechanics — a game with no directional movement should have no movement controls at all.
|
|
22
|
-
|
|
23
|
-
## Fit the card
|
|
24
|
-
|
|
25
|
-
- **The deck plays inside a fixed 5:7 portrait card, not the full window.** The card is sized to fit the screen (at most about 450x630px), clips overflow, and does not scroll. Design the whole layout to fit inside that portrait box: size UI relative to the card with percentages, flex/grid, `min()`, `clamp()`, or viewport-relative units instead of fixed tall panels. Let playfields scale down on smaller cards rather than overflowing; anything outside the card edges is cut off. The SDK exports `CARD_RATIO` (= 5 / 7) if you need the exact ratio.
|
|
26
|
-
- **Hand-rolled `<canvas>` elements must account for devicePixelRatio, or the game looks blurry on phones.** Size the backing store to the CSS layout size times `devicePixelRatio` (e.g. `canvas.width = rect.width * dpr`), keep the CSS width/height as the layout size, and scale the 2D context (`ctx.scale(dpr, dpr)`) so drawing code stays in CSS units — re-apply on resize. Kit decks don't need to do this by hand; the kit's engine already configures its canvas for DPR.
|
|
27
|
-
- Exception: deliberate pixel art wants a fixed low-resolution backing store with `image-rendering: pixelated` CSS instead — don't DPR-scale that; the crisp chunky look is the point.
|
|
28
|
-
|
|
29
|
-
## Formats, reloading, editors
|
|
30
|
-
|
|
31
|
-
- **Supported media formats are exactly**: images `.png` `.jpg` `.jpeg` `.gif` `.webp` `.svg`, audio `.mp3` `.wav` `.m4a`, video `.mp4` (H.264). Nothing else — a published deck inlines every asset as a `data:` URI, where the browser trusts the declared type instead of sniffing the bytes, so a format that merely works while serving (`.mov` is the classic case) can be dead once published. Convert, don't improvise.
|
|
32
|
-
- To add an npm package, put it in `package.json` `dependencies` and run `castle-web install .` (the install `init` ran; it uses whichever package manager made the lockfile).
|
|
33
|
-
- Do not reload the deck after an edit. Nothing auto-reloads: the person applies your changes when they are ready, from the Play panel's restart button or a panel's own reload control. `npm run restart` reloads every open panel at once and breaks their flow — only when asked.
|
|
34
|
-
- The deck can define its own editors: declare a file type in `castle.json` (`editor.fileTypes`: ext, label, icon, and an `editors/` module) and the Files panel opens that type in it — whole recipe under `## Editors` in the deck's guide (its kit's `CLAUDE.md` under `imports/`). Editors under `imports/` are read-only; add or fork, don't edit.
|
|
35
|
-
- An editor is for content FILES the creator keeps coming back to (catalogs, dialogue, level tables) that nothing already opens. One-off or generated data stays code.
|
|
36
|
-
- Unprompted, an editor is an offer, never a build: when the same data keeps getting edited by hand, propose one and build on the user's yes. Never during a first build.
|