castle-web-cli 0.4.193 → 0.4.195
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/agent-prompts.d.ts +1 -0
- package/dist/agent-prompts.js +14 -5
- package/dist/agent.js +101 -4
- package/dist/api.d.ts +1 -0
- package/dist/api.js +5 -0
- package/dist/bundle.js +2 -1
- package/dist/castleJson.d.ts +1 -2
- package/dist/castleJson.js +0 -39
- package/dist/check.js +14 -6
- package/dist/devSessionFrameBudget.d.ts +14 -0
- package/dist/devSessionFrameBudget.js +64 -0
- package/dist/devSessionServer.d.ts +6 -0
- package/dist/devSessionServer.js +38 -1
- package/dist/editorConfig.d.ts +1 -1
- package/dist/editorConfig.js +12 -4
- package/dist/filesChanged.js +7 -3
- package/dist/ide.js +28 -59
- package/dist/importUpdateHook.d.ts +31 -0
- package/dist/importUpdateHook.js +135 -0
- package/dist/importUpdateHookRunner.d.ts +2 -0
- package/dist/importUpdateHookRunner.js +24 -0
- package/dist/imports.js +58 -10
- package/dist/index.js +58 -7
- package/dist/init.d.ts +1 -0
- package/dist/init.js +15 -9
- package/dist/multiplayerDoc.d.ts +1 -0
- package/dist/multiplayerDoc.js +228 -0
- package/dist/native/loop.js +29 -9
- package/dist/platformDoc.d.ts +1 -0
- package/dist/platformDoc.js +25 -6
- package/dist/remix.js +4 -1
- package/dist/scriptErrors.d.ts +23 -0
- package/dist/scriptErrors.js +147 -0
- package/dist/serve.js +366 -36
- package/dist/serverBundle.js +1 -1
- package/dist/shell/assets/index-kMH1qj6D.js +449 -0
- package/dist/shell/index.html +1 -1
- package/dist/versions.d.ts +14 -0
- package/dist/versions.js +21 -0
- package/dist/viteClientStub.d.ts +18 -0
- package/dist/viteClientStub.js +193 -0
- package/dist/vitePlugins.d.ts +1 -0
- package/dist/vitePlugins.js +18 -0
- package/kits/base/CLAUDE.md +3 -3
- package/kits/base/castle.json +1 -3
- package/kits/base/sdk/README.md +17 -0
- package/kits/multiplayer-2d/CLAUDE.md +9 -2
- package/kits/multiplayer-2d/blueprints/crate.scene +32 -4
- package/kits/multiplayer-2d/blueprints/other-player.scene +31 -4
- package/kits/multiplayer-2d/blueprints/player.scene +38 -6
- package/kits/multiplayer-2d/blueprints/wall.scene +25 -3
- package/kits/multiplayer-2d/castle.json +3 -12
- package/kits/multiplayer-2d/test/two-client-test.mjs +4 -4
- package/kits/multiplayer-3d/CLAUDE.md +5 -2
- package/kits/multiplayer-3d/castle.json +3 -11
- package/kits/multiplayer-3d/scenes/main.scene +128 -0
- package/kits/physics-2d/CLAUDE.md +16 -11
- package/kits/physics-2d/behaviors/Camera.jsx +5 -6
- package/kits/physics-2d/behaviors/Goal.jsx +5 -2
- package/kits/physics-2d/behaviors/Joints.jsx +4 -3
- package/kits/physics-2d/behaviors/Layout.jsx +120 -3
- package/kits/physics-2d/behaviors/Sprite.jsx +9 -9
- package/kits/physics-2d/behaviors/Style.jsx +22 -15
- package/kits/physics-2d/behaviors/Text.jsx +7 -6
- package/kits/physics-2d/blueprints/ball.scene +27 -5
- package/kits/physics-2d/blueprints/block.scene +16 -3
- package/kits/physics-2d/blueprints/cauldron.scene +3 -1
- package/kits/physics-2d/blueprints/crate.scene +23 -4
- package/kits/physics-2d/blueprints/goal.scene +12 -2
- package/kits/physics-2d/blueprints/text.scene +13 -3
- package/kits/physics-2d/castle.json +2 -11
- package/kits/physics-2d/editors/SceneEditor.jsx +68 -5
- package/kits/physics-2d/editors/SelectionOverlay.jsx +27 -20
- package/kits/physics-2d/editors/behaviorRegistry.js +8 -2
- package/kits/physics-2d/engine/ErrorOverlay.jsx +69 -0
- package/kits/physics-2d/engine/ScenePlayer.jsx +2 -67
- package/kits/physics-2d/engine/blueprint.js +111 -54
- package/kits/physics-2d/engine/blueprintCore.js +59 -0
- package/kits/physics-2d/engine/collider.js +28 -17
- package/kits/physics-2d/engine/layout.js +61 -0
- package/kits/physics-2d/engine/layoutOriginMigration.js +223 -0
- package/kits/physics-2d/engine/liveReload.js +5 -4
- package/kits/physics-2d/engine/physics/PhysicsSystem.js +11 -7
- package/kits/physics-2d/engine/physics/controls.js +4 -8
- package/kits/physics-2d/engine/physics/matterBridge.js +13 -8
- package/kits/physics-2d/engine/scene.js +38 -34
- package/kits/physics-2d/engine/spriteGeometry.js +17 -9
- package/kits/physics-2d/engine/tap.js +4 -3
- package/kits/physics-2d/scenes/main.scene +59 -6
- package/kits/physics-2d/scenes/sandbox.scene +69 -7
- package/kits/physics-2d/scripts/onUpdate.mjs +199 -0
- package/kits/physics-3d/castle.json +0 -11
- package/kits/real-time/castle.json +2 -8
- package/kits/real-time/code/server/persist.js +14 -0
- package/kits/turn-based/CLAUDE.md +18 -10
- package/kits/turn-based/blueprints/board.scene +3 -1
- package/kits/turn-based/blueprints/square.scene +3 -1
- package/kits/turn-based/castle.json +3 -14
- package/kits/turn-based/code/behaviors/Board.jsx +33 -21
- package/package.json +1 -1
- package/dist/shell/assets/index-ColHKJYj.js +0 -449
package/dist/init.js
CHANGED
|
@@ -68,13 +68,10 @@ const FONTS_RANGE = '^1.0.0';
|
|
|
68
68
|
// Never copied into a deck's import: build/dependency junk.
|
|
69
69
|
const KIT_COPY_EXCLUDE = new Set(['node_modules', '.castle', 'dist', '.git']);
|
|
70
70
|
// The bare (`--kit none`) deck's default editor config: just the Files panel and
|
|
71
|
-
// a Play panel.
|
|
72
|
-
// knows what's there; show everything for now.
|
|
71
|
+
// a Play panel.
|
|
73
72
|
const BARE_CASTLE_JSON = {
|
|
74
73
|
editor: {
|
|
75
74
|
initialPanels: [{ type: 'files' }, { type: 'playtest' }],
|
|
76
|
-
hiddenPaths: [],
|
|
77
|
-
visiblePaths: [],
|
|
78
75
|
},
|
|
79
76
|
};
|
|
80
77
|
// Resolve how a scaffolded deck should reference the sdk + cli. Both the bare
|
|
@@ -434,11 +431,15 @@ function makeKitPin(kitConfig, kit) {
|
|
|
434
431
|
}
|
|
435
432
|
return { source: 'builtin', kit, version: getCliVersion() };
|
|
436
433
|
}
|
|
437
|
-
// The
|
|
438
|
-
//
|
|
439
|
-
|
|
434
|
+
// The layout a new deck starts from: the kit's editor block minus the
|
|
435
|
+
// vocabulary the deck resolves from the kit itself (`fileTypes`) and minus the
|
|
436
|
+
// path filters, which name the kit's OWN files -- in the deck those live under
|
|
437
|
+
// `imports/<alias>/` and are filtered by the import's castle.json there.
|
|
438
|
+
function deckEditorBlock(editor) {
|
|
440
439
|
const rest = { ...(editor ?? {}) };
|
|
441
440
|
delete rest.fileTypes;
|
|
441
|
+
delete rest.hiddenPaths;
|
|
442
|
+
delete rest.visiblePaths;
|
|
442
443
|
return rest;
|
|
443
444
|
}
|
|
444
445
|
// Scaffold a deck that IMPORTS its kit instead of copying it. The kit's files
|
|
@@ -542,7 +543,7 @@ function scaffoldFromKitImport(kit, projectDir) {
|
|
|
542
543
|
// reaches the deck like any other, and a kit imported LATER contributes its
|
|
543
544
|
// types too, which a copy taken at scaffold time never could.
|
|
544
545
|
writeJsonFile(path.join(projectDir, 'castle.json'), {
|
|
545
|
-
...(kitConfig.editor ? { editor:
|
|
546
|
+
...(kitConfig.editor ? { editor: deckEditorBlock(kitConfig.editor) } : {}),
|
|
546
547
|
...(kitConfig.server ? { server: serverForDeck(kitConfig.server, kitDir, alias) } : {}),
|
|
547
548
|
imports: pins,
|
|
548
549
|
});
|
|
@@ -708,7 +709,12 @@ export async function init(dir, opts = {}) {
|
|
|
708
709
|
const noOpen = process.env.CASTLE_WEB_CLI_NO_OPEN === '1' ||
|
|
709
710
|
!!process.env.SSH_CONNECTION ||
|
|
710
711
|
!!process.env.SSH_TTY;
|
|
711
|
-
await serve(projectDir, {
|
|
712
|
+
await serve(projectDir, {
|
|
713
|
+
port: opts.port,
|
|
714
|
+
host: '0.0.0.0',
|
|
715
|
+
detach: true,
|
|
716
|
+
open: !noOpen,
|
|
717
|
+
});
|
|
712
718
|
return;
|
|
713
719
|
}
|
|
714
720
|
console.log('');
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare const MULTIPLAYER_DOC = "# Multiplayer, in practice\n\nRead this before writing or changing a server entry or client netcode by hand.\nWritten fresh by the Castle CLI at every serve start; the full API reference is\nthe SDK's own, at `imports/castle.base/sdk/README.md`.\n\n## Reach for a kit first\n\n`castle.multiplayer-2d` and `castle.multiplayer-3d` (both on `castle.real-time`)\nalready do everything below: a server-authoritative world, one snapshot per\ntick, pose interpolation, roster handling, reconnects, ownership of loose\nobjects. `castle.turn-based` does the same for games played in turns, with\nseats, spectators and idle clearing. A deck on one of those kits normally\nwrites nothing against the raw session API, and the right move is usually to\nadd a rule to the deck's own game hooks rather than a message of your own.\n\nHand-roll only when the game genuinely does not fit them -- and then keep the\nshape below, because it is the shape the platform's limits ask for.\n\n## The outbound budget\n\nA session may send about `40 + 40 x connected players` frames per second, with\nroughly two seconds of burst, and about 1 MiB/s of bytes. What a frame costs:\n\n| call | frames |\n|---|---|\n| `session.send(playerId, data)` | 1 |\n| `session.broadcast(data)` | 1, whatever the player count |\n| `session.broadcast(data, { except })` | one per recipient -- it is a loop of sends |\n\nFrames over the budget are **dropped silently**. The session keeps running and\na dropped frame is never retried, so the symptom is not an error: it is a\nclient whose world quietly stops matching everyone else's. Only sustained abuse\nat several times the budget ends a session.\n\nThe arithmetic that matters, at `tickRate: 20`:\n\n- 4 players, one `send` per player per tick: 80 frames/s of a 200 budget --\n before a single hit, join, chat or one-off frame.\n- 8 players, same: 160 of 360. A second per-player message per tick makes it\n 320, and at `tickRate: 30` that is 480 -- over, and frames start dropping.\n- Either, with one `broadcast` per tick: 20 frames/s. The budget stops being\n something you have to think about.\n\nPer-player sends also send the same bytes N times toward the byte budget. The\nlocal serve does not drop anything, but it warns when a 1-second window goes\nover -- `[multiplayer] server sent ...` in `.castle/logs.txt` and in the serve's\nown output (`.castle/serve.log` when it was detached).\n\n## The snapshot pattern\n\nAuthoritative state lives on the server. `onTick` builds ONE snapshot of every\nplayer and broadcasts it once.\n\nEvery client reads EVERY entry in that snapshot, **including its own** -- the\ndifference is only what it does with each:\n\n- **Other players' entries** drive what it draws for them (interpolated between\n snapshots), and are how it learns someone left or went silent.\n- **Its own entry** is the server's verdict on itself. Take hp, alive/wrecked,\n kills, score and the match state from it every tick, exactly as if it were\n someone else's. The one field it does NOT overwrite each tick is its own pose:\n the local player moves on its own input so the game stays responsive, and the\n client only snaps to the server's position when the two have drifted far\n apart. Ignoring the rest of its own entry is how a player ends up alive on\n their own screen and dead on everyone else's.\n\n```js\nconst state = { matchNumber: 1, players: {}, parked: new Map() };\n\nexport default {\n onPlayerJoin(session, player) {\n state.players[player.playerId] = { x: 0, y: 0, hp: 100, kills: 0, alive: true };\n },\n onMessage(session, player, data) {\n if (data.t === 'move') applyMove(state.players[player.playerId], data);\n },\n onTick(session) {\n // One frame per tick, for any number of players.\n session.broadcast({ t: 'snap', n: state.matchNumber, players: state.players });\n },\n};\n```\n\n```js\nconnection.onMessage((msg) => {\n if (msg.t !== 'snap') return;\n match.setNumber(msg.n); // a new match number means: reset, the round moved on\n for (const [id, p] of Object.entries(msg.players)) {\n if (id === connection.playerId) {\n // My own entry: the server owns all of it except where I am right now.\n Object.assign(me, { hp: p.hp, kills: p.kills, alive: p.alive });\n if (Math.hypot(p.x - me.x, p.y - me.y) > SNAP_DISTANCE) {\n me.x = p.x; // drifted too far to argue; the server is right\n me.y = p.y;\n }\n continue;\n }\n remote.set(id, { ...p, seenAt: performance.now() });\n }\n});\n```\n\nDo not build a per-player payload (\"everyone except you\") on the server: the\nclient needs its own entry anyway, and one tailored message per player costs N\nframes where the shared snapshot costs 1.\n\n## One-off events must be self-healing\n\nA dropped or missed event frame is gone for good. So an event may carry an\neffect, never the only copy of a result:\n\n- `{ t: 'hit', target, dmg }` -- fine for a flash, a sound, a particle.\n- The hp it produced, whether the player is alive or wrecked, the kill count,\n the match number: all of that belongs in the periodic snapshot, and the\n client reconciles from the snapshot every tick.\n\nWrite the client so that receiving zero events and only snapshots still\nproduces a correct, playable screen. Then a dropped frame costs one missing\nspark instead of a player who is dead everywhere but on their own device.\n\n## Connection loss has to be visible\n\nTwo independent things can go quiet: the socket, and a player.\n\n```js\nconnection.onStateChange((state, meta) => {\n // 'acquiring' | 'connecting' | 'connected' | 'reconnecting' | 'closed'\n // meta?.type: 'connectionLost' | 'replaced' | 'bye' | 'left' | 'error'\n hud.setConnection(state, meta?.type);\n});\n```\n\n- Show `reconnecting` and `closed` in the deck's own UI. A player staring at a\n frozen game with no explanation assumes the game is broken.\n- Expire a remote player whose last snapshot is older than a few seconds\n (`performance.now() - p.seenAt > 3000`) and stop drawing them. This must run\n off the client's own clock, not off an event -- if the server or the socket\n goes silent, no message will ever arrive to tell you, and every remote player\n stays frozen mid-stride forever.\n- The SDK reconnects short drops by itself and `send` is safe to call while the\n socket is down (those messages are dropped), so the client's job is to show\n the state and recover, not to manage the socket.\n\n## Reconnects: park match state, never delete it\n\n`playerId` is stable across a platform reconnect, but the server still sees\n`onPlayerLeave` and then `onPlayerJoin`. A server that deletes the player's row\non leave silently drops a reconnecting player out of the match while their\nclient happily thinks it is still playing.\n\n```js\nonPlayerLeave(session, player) {\n const parked = state.players[player.playerId];\n delete state.players[player.playerId];\n if (parked) state.parked.set(player.playerId, { at: Date.now(), parked }); // or by userId\n},\nonPlayerJoin(session, player) {\n const held = state.parked.get(player.playerId);\n state.parked.delete(player.playerId);\n state.players[player.playerId] =\n held && Date.now() - held.at < 60_000 ? held.parked : freshPlayer();\n session.send(player.playerId, { t: 'full', ...fullState() }); // 1 frame, once\n},\n```\n\nPark for about 60 seconds (the platform's own reconnect window), keyed by\n`playerId`, or by `userId` when the match should survive a genuinely new\nconnection from the same account. Sweep expired entries on a tick.\n\nOn the client, after a state change back to `connected`, ask for full state\nonce and rebuild from the answer rather than assuming the world is as you left\nit.\n\n## The server ignores and tells\n\nWhen the server refuses a message because the player is not in the state the\nclient assumed -- not in the match, already dead, not their turn -- do not just\n`return`. The client believes something false and nothing will correct it.\n\n```js\nonMessage(session, player, data) {\n const me = state.players[player.playerId];\n if (!me || !me.alive) {\n session.send(player.playerId, { t: 'full', ...fullState() }); // authoritative answer\n return;\n }\n ...\n}\n```\n\nOne frame, and the client resyncs instead of arguing with itself. Rate-limit\nthat reply (once per player per second is plenty) so a looping client cannot\nspend the whole budget on corrections.\n\n## Client to server\n\nClient frames are capped at 16 KB and about 30 messages per second; **exceeding\nthe rate closes the socket**, which is much harsher than the server side's\nsilent drop.\n\n- Throttle pose/input sends to a fixed rate. 8-15 per second is plenty when the\n client interpolates between samples (the real-time kit reports at 20). Never\n send once per animation frame -- 60/s closes the connection.\n- Send intent (\"I am holding left\", \"I fired\"), not results. The server decides\n what happened.\n- Coalesce: one message per send tick carrying the latest pose beats three\n messages describing how it got there.\n\n## Testing it\n\n- Open **four or more** tabs, not two. Every budget and roster bug scales with\n the player count, and two tabs is exactly the case that never reproduces one.\n- Reload tabs mid-match to exercise leave/rejoin, and leave one tab idle to see\n what a silent player looks like to everyone else.\n- Kill and restart the serve (or edit the server entry, which restarts it) to\n see the disconnected state the deck shows.\n- Watch the serve log for the `[multiplayer]` budget warning and for dropped\n oversize frames while you play.\n";
|
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
// The on-demand multiplayer guide, written beside platform.md at every serve
|
|
2
|
+
// start (platformDoc.ts owns both paths and the writing). Tool-call-only by
|
|
3
|
+
// design: platform.md carries one bullet pointing here -- see the header
|
|
4
|
+
// comment in platformDoc.ts about the inlined vs tool-call-only split -- and
|
|
5
|
+
// nothing below is inlined into any prompt. It is what an agent reads before
|
|
6
|
+
// hand-rolling a server entry or client netcode: the frame budget, the snapshot
|
|
7
|
+
// pattern, and the reconnect/disconnect handling that a hand-rolled session
|
|
8
|
+
// gets wrong and a multiplayer kit already does.
|
|
9
|
+
export const MULTIPLAYER_DOC = `# Multiplayer, in practice
|
|
10
|
+
|
|
11
|
+
Read this before writing or changing a server entry or client netcode by hand.
|
|
12
|
+
Written fresh by the Castle CLI at every serve start; the full API reference is
|
|
13
|
+
the SDK's own, at \`imports/castle.base/sdk/README.md\`.
|
|
14
|
+
|
|
15
|
+
## Reach for a kit first
|
|
16
|
+
|
|
17
|
+
\`castle.multiplayer-2d\` and \`castle.multiplayer-3d\` (both on \`castle.real-time\`)
|
|
18
|
+
already do everything below: a server-authoritative world, one snapshot per
|
|
19
|
+
tick, pose interpolation, roster handling, reconnects, ownership of loose
|
|
20
|
+
objects. \`castle.turn-based\` does the same for games played in turns, with
|
|
21
|
+
seats, spectators and idle clearing. A deck on one of those kits normally
|
|
22
|
+
writes nothing against the raw session API, and the right move is usually to
|
|
23
|
+
add a rule to the deck's own game hooks rather than a message of your own.
|
|
24
|
+
|
|
25
|
+
Hand-roll only when the game genuinely does not fit them -- and then keep the
|
|
26
|
+
shape below, because it is the shape the platform's limits ask for.
|
|
27
|
+
|
|
28
|
+
## The outbound budget
|
|
29
|
+
|
|
30
|
+
A session may send about \`40 + 40 x connected players\` frames per second, with
|
|
31
|
+
roughly two seconds of burst, and about 1 MiB/s of bytes. What a frame costs:
|
|
32
|
+
|
|
33
|
+
| call | frames |
|
|
34
|
+
|---|---|
|
|
35
|
+
| \`session.send(playerId, data)\` | 1 |
|
|
36
|
+
| \`session.broadcast(data)\` | 1, whatever the player count |
|
|
37
|
+
| \`session.broadcast(data, { except })\` | one per recipient -- it is a loop of sends |
|
|
38
|
+
|
|
39
|
+
Frames over the budget are **dropped silently**. The session keeps running and
|
|
40
|
+
a dropped frame is never retried, so the symptom is not an error: it is a
|
|
41
|
+
client whose world quietly stops matching everyone else's. Only sustained abuse
|
|
42
|
+
at several times the budget ends a session.
|
|
43
|
+
|
|
44
|
+
The arithmetic that matters, at \`tickRate: 20\`:
|
|
45
|
+
|
|
46
|
+
- 4 players, one \`send\` per player per tick: 80 frames/s of a 200 budget --
|
|
47
|
+
before a single hit, join, chat or one-off frame.
|
|
48
|
+
- 8 players, same: 160 of 360. A second per-player message per tick makes it
|
|
49
|
+
320, and at \`tickRate: 30\` that is 480 -- over, and frames start dropping.
|
|
50
|
+
- Either, with one \`broadcast\` per tick: 20 frames/s. The budget stops being
|
|
51
|
+
something you have to think about.
|
|
52
|
+
|
|
53
|
+
Per-player sends also send the same bytes N times toward the byte budget. The
|
|
54
|
+
local serve does not drop anything, but it warns when a 1-second window goes
|
|
55
|
+
over -- \`[multiplayer] server sent ...\` in \`.castle/logs.txt\` and in the serve's
|
|
56
|
+
own output (\`.castle/serve.log\` when it was detached).
|
|
57
|
+
|
|
58
|
+
## The snapshot pattern
|
|
59
|
+
|
|
60
|
+
Authoritative state lives on the server. \`onTick\` builds ONE snapshot of every
|
|
61
|
+
player and broadcasts it once.
|
|
62
|
+
|
|
63
|
+
Every client reads EVERY entry in that snapshot, **including its own** -- the
|
|
64
|
+
difference is only what it does with each:
|
|
65
|
+
|
|
66
|
+
- **Other players' entries** drive what it draws for them (interpolated between
|
|
67
|
+
snapshots), and are how it learns someone left or went silent.
|
|
68
|
+
- **Its own entry** is the server's verdict on itself. Take hp, alive/wrecked,
|
|
69
|
+
kills, score and the match state from it every tick, exactly as if it were
|
|
70
|
+
someone else's. The one field it does NOT overwrite each tick is its own pose:
|
|
71
|
+
the local player moves on its own input so the game stays responsive, and the
|
|
72
|
+
client only snaps to the server's position when the two have drifted far
|
|
73
|
+
apart. Ignoring the rest of its own entry is how a player ends up alive on
|
|
74
|
+
their own screen and dead on everyone else's.
|
|
75
|
+
|
|
76
|
+
\`\`\`js
|
|
77
|
+
const state = { matchNumber: 1, players: {}, parked: new Map() };
|
|
78
|
+
|
|
79
|
+
export default {
|
|
80
|
+
onPlayerJoin(session, player) {
|
|
81
|
+
state.players[player.playerId] = { x: 0, y: 0, hp: 100, kills: 0, alive: true };
|
|
82
|
+
},
|
|
83
|
+
onMessage(session, player, data) {
|
|
84
|
+
if (data.t === 'move') applyMove(state.players[player.playerId], data);
|
|
85
|
+
},
|
|
86
|
+
onTick(session) {
|
|
87
|
+
// One frame per tick, for any number of players.
|
|
88
|
+
session.broadcast({ t: 'snap', n: state.matchNumber, players: state.players });
|
|
89
|
+
},
|
|
90
|
+
};
|
|
91
|
+
\`\`\`
|
|
92
|
+
|
|
93
|
+
\`\`\`js
|
|
94
|
+
connection.onMessage((msg) => {
|
|
95
|
+
if (msg.t !== 'snap') return;
|
|
96
|
+
match.setNumber(msg.n); // a new match number means: reset, the round moved on
|
|
97
|
+
for (const [id, p] of Object.entries(msg.players)) {
|
|
98
|
+
if (id === connection.playerId) {
|
|
99
|
+
// My own entry: the server owns all of it except where I am right now.
|
|
100
|
+
Object.assign(me, { hp: p.hp, kills: p.kills, alive: p.alive });
|
|
101
|
+
if (Math.hypot(p.x - me.x, p.y - me.y) > SNAP_DISTANCE) {
|
|
102
|
+
me.x = p.x; // drifted too far to argue; the server is right
|
|
103
|
+
me.y = p.y;
|
|
104
|
+
}
|
|
105
|
+
continue;
|
|
106
|
+
}
|
|
107
|
+
remote.set(id, { ...p, seenAt: performance.now() });
|
|
108
|
+
}
|
|
109
|
+
});
|
|
110
|
+
\`\`\`
|
|
111
|
+
|
|
112
|
+
Do not build a per-player payload ("everyone except you") on the server: the
|
|
113
|
+
client needs its own entry anyway, and one tailored message per player costs N
|
|
114
|
+
frames where the shared snapshot costs 1.
|
|
115
|
+
|
|
116
|
+
## One-off events must be self-healing
|
|
117
|
+
|
|
118
|
+
A dropped or missed event frame is gone for good. So an event may carry an
|
|
119
|
+
effect, never the only copy of a result:
|
|
120
|
+
|
|
121
|
+
- \`{ t: 'hit', target, dmg }\` -- fine for a flash, a sound, a particle.
|
|
122
|
+
- The hp it produced, whether the player is alive or wrecked, the kill count,
|
|
123
|
+
the match number: all of that belongs in the periodic snapshot, and the
|
|
124
|
+
client reconciles from the snapshot every tick.
|
|
125
|
+
|
|
126
|
+
Write the client so that receiving zero events and only snapshots still
|
|
127
|
+
produces a correct, playable screen. Then a dropped frame costs one missing
|
|
128
|
+
spark instead of a player who is dead everywhere but on their own device.
|
|
129
|
+
|
|
130
|
+
## Connection loss has to be visible
|
|
131
|
+
|
|
132
|
+
Two independent things can go quiet: the socket, and a player.
|
|
133
|
+
|
|
134
|
+
\`\`\`js
|
|
135
|
+
connection.onStateChange((state, meta) => {
|
|
136
|
+
// 'acquiring' | 'connecting' | 'connected' | 'reconnecting' | 'closed'
|
|
137
|
+
// meta?.type: 'connectionLost' | 'replaced' | 'bye' | 'left' | 'error'
|
|
138
|
+
hud.setConnection(state, meta?.type);
|
|
139
|
+
});
|
|
140
|
+
\`\`\`
|
|
141
|
+
|
|
142
|
+
- Show \`reconnecting\` and \`closed\` in the deck's own UI. A player staring at a
|
|
143
|
+
frozen game with no explanation assumes the game is broken.
|
|
144
|
+
- Expire a remote player whose last snapshot is older than a few seconds
|
|
145
|
+
(\`performance.now() - p.seenAt > 3000\`) and stop drawing them. This must run
|
|
146
|
+
off the client's own clock, not off an event -- if the server or the socket
|
|
147
|
+
goes silent, no message will ever arrive to tell you, and every remote player
|
|
148
|
+
stays frozen mid-stride forever.
|
|
149
|
+
- The SDK reconnects short drops by itself and \`send\` is safe to call while the
|
|
150
|
+
socket is down (those messages are dropped), so the client's job is to show
|
|
151
|
+
the state and recover, not to manage the socket.
|
|
152
|
+
|
|
153
|
+
## Reconnects: park match state, never delete it
|
|
154
|
+
|
|
155
|
+
\`playerId\` is stable across a platform reconnect, but the server still sees
|
|
156
|
+
\`onPlayerLeave\` and then \`onPlayerJoin\`. A server that deletes the player's row
|
|
157
|
+
on leave silently drops a reconnecting player out of the match while their
|
|
158
|
+
client happily thinks it is still playing.
|
|
159
|
+
|
|
160
|
+
\`\`\`js
|
|
161
|
+
onPlayerLeave(session, player) {
|
|
162
|
+
const parked = state.players[player.playerId];
|
|
163
|
+
delete state.players[player.playerId];
|
|
164
|
+
if (parked) state.parked.set(player.playerId, { at: Date.now(), parked }); // or by userId
|
|
165
|
+
},
|
|
166
|
+
onPlayerJoin(session, player) {
|
|
167
|
+
const held = state.parked.get(player.playerId);
|
|
168
|
+
state.parked.delete(player.playerId);
|
|
169
|
+
state.players[player.playerId] =
|
|
170
|
+
held && Date.now() - held.at < 60_000 ? held.parked : freshPlayer();
|
|
171
|
+
session.send(player.playerId, { t: 'full', ...fullState() }); // 1 frame, once
|
|
172
|
+
},
|
|
173
|
+
\`\`\`
|
|
174
|
+
|
|
175
|
+
Park for about 60 seconds (the platform's own reconnect window), keyed by
|
|
176
|
+
\`playerId\`, or by \`userId\` when the match should survive a genuinely new
|
|
177
|
+
connection from the same account. Sweep expired entries on a tick.
|
|
178
|
+
|
|
179
|
+
On the client, after a state change back to \`connected\`, ask for full state
|
|
180
|
+
once and rebuild from the answer rather than assuming the world is as you left
|
|
181
|
+
it.
|
|
182
|
+
|
|
183
|
+
## The server ignores and tells
|
|
184
|
+
|
|
185
|
+
When the server refuses a message because the player is not in the state the
|
|
186
|
+
client assumed -- not in the match, already dead, not their turn -- do not just
|
|
187
|
+
\`return\`. The client believes something false and nothing will correct it.
|
|
188
|
+
|
|
189
|
+
\`\`\`js
|
|
190
|
+
onMessage(session, player, data) {
|
|
191
|
+
const me = state.players[player.playerId];
|
|
192
|
+
if (!me || !me.alive) {
|
|
193
|
+
session.send(player.playerId, { t: 'full', ...fullState() }); // authoritative answer
|
|
194
|
+
return;
|
|
195
|
+
}
|
|
196
|
+
...
|
|
197
|
+
}
|
|
198
|
+
\`\`\`
|
|
199
|
+
|
|
200
|
+
One frame, and the client resyncs instead of arguing with itself. Rate-limit
|
|
201
|
+
that reply (once per player per second is plenty) so a looping client cannot
|
|
202
|
+
spend the whole budget on corrections.
|
|
203
|
+
|
|
204
|
+
## Client to server
|
|
205
|
+
|
|
206
|
+
Client frames are capped at 16 KB and about 30 messages per second; **exceeding
|
|
207
|
+
the rate closes the socket**, which is much harsher than the server side's
|
|
208
|
+
silent drop.
|
|
209
|
+
|
|
210
|
+
- Throttle pose/input sends to a fixed rate. 8-15 per second is plenty when the
|
|
211
|
+
client interpolates between samples (the real-time kit reports at 20). Never
|
|
212
|
+
send once per animation frame -- 60/s closes the connection.
|
|
213
|
+
- Send intent ("I am holding left", "I fired"), not results. The server decides
|
|
214
|
+
what happened.
|
|
215
|
+
- Coalesce: one message per send tick carrying the latest pose beats three
|
|
216
|
+
messages describing how it got there.
|
|
217
|
+
|
|
218
|
+
## Testing it
|
|
219
|
+
|
|
220
|
+
- Open **four or more** tabs, not two. Every budget and roster bug scales with
|
|
221
|
+
the player count, and two tabs is exactly the case that never reproduces one.
|
|
222
|
+
- Reload tabs mid-match to exercise leave/rejoin, and leave one tab idle to see
|
|
223
|
+
what a silent player looks like to everyone else.
|
|
224
|
+
- Kill and restart the serve (or edit the server entry, which restarts it) to
|
|
225
|
+
see the disconnected state the deck shows.
|
|
226
|
+
- Watch the serve log for the \`[multiplayer]\` budget warning and for dropped
|
|
227
|
+
oversize frames while you play.
|
|
228
|
+
`;
|
package/dist/native/loop.js
CHANGED
|
@@ -29,13 +29,25 @@ function playtestFrameList(frames) {
|
|
|
29
29
|
}
|
|
30
30
|
// -- run logging ----------------------------------------------------------------
|
|
31
31
|
// Structured JSONL, one event per line, appended (task retry attempts share
|
|
32
|
-
// one log.jsonl, same as the CLI backends).
|
|
33
|
-
//
|
|
34
|
-
//
|
|
35
|
-
//
|
|
36
|
-
//
|
|
37
|
-
|
|
38
|
-
|
|
32
|
+
// one log.jsonl, same as the CLI backends).
|
|
33
|
+
//
|
|
34
|
+
// These logs are a permanent training corpus, not just a debugging aid, so
|
|
35
|
+
// every model-facing field is recorded EXACTLY: the prompt and system text the
|
|
36
|
+
// run was given (the init event), the tool-call arguments the model itself
|
|
37
|
+
// emitted, the tool output the model was shown on its next turn, and the
|
|
38
|
+
// assistant text it produced. Nothing here may be summarized or elided -- a
|
|
39
|
+
// truncated field is a corrupted training example, not a shorter one.
|
|
40
|
+
//
|
|
41
|
+
// LOG_FIELD_CAP is therefore a safety valve, NOT a display budget: it exists
|
|
42
|
+
// only so one pathological tool (a runaway bash command, a huge grep) cannot
|
|
43
|
+
// write an unbounded line into a file we ship whole. At 1 MiB it is far above
|
|
44
|
+
// anything a real turn produces -- if it ever fires, the payload was already
|
|
45
|
+
// too big to have been useful context.
|
|
46
|
+
const LOG_FIELD_CAP = 1024 * 1024; // 1 MiB per field -- see above.
|
|
47
|
+
// Identity for every realistic field; only a pathological payload is clipped,
|
|
48
|
+
// and it says so in-band so a reader (or a corpus filter) can drop the example
|
|
49
|
+
// rather than mistake the clipped text for what the model saw.
|
|
50
|
+
function capForLog(raw) {
|
|
39
51
|
if (raw.length <= LOG_FIELD_CAP)
|
|
40
52
|
return raw;
|
|
41
53
|
return `${raw.slice(0, LOG_FIELD_CAP)}... (+${raw.length - LOG_FIELD_CAP} chars)`;
|
|
@@ -438,7 +450,7 @@ async function runToolCalls(toolCalls, role, ctx, playtestFrames, labels, imageL
|
|
|
438
450
|
id: call.id,
|
|
439
451
|
name,
|
|
440
452
|
ok: result.ok,
|
|
441
|
-
output:
|
|
453
|
+
output: capForLog(result.output),
|
|
442
454
|
...(result.images && result.images.length > 0
|
|
443
455
|
? {
|
|
444
456
|
imageCount: result.images.length,
|
|
@@ -484,6 +496,14 @@ export async function runAgentNative(opts) {
|
|
|
484
496
|
model: opts.model,
|
|
485
497
|
tools: toolSchemas.map((t) => t.function.name),
|
|
486
498
|
promptChars: opts.prompt.length,
|
|
499
|
+
// The two halves of what this run was actually asked, verbatim: the user
|
|
500
|
+
// message (opts.prompt) and the system message exactly as buildSystemMessage
|
|
501
|
+
// assembles it for the messages array -- role framing + the router's stable
|
|
502
|
+
// part (opts.system) + a task's appended reminder (opts.systemReminder),
|
|
503
|
+
// whichever of those are present. Without these the log records the model's
|
|
504
|
+
// answers with the question missing, which is useless as training data.
|
|
505
|
+
prompt: opts.prompt,
|
|
506
|
+
systemPrompt: buildSystemMessage(opts),
|
|
487
507
|
...(opts.attachments && opts.attachments.length > 0 ? { attachments: opts.attachments } : {}),
|
|
488
508
|
});
|
|
489
509
|
try {
|
|
@@ -662,7 +682,7 @@ async function runLoop(opts, toolSchemas, log) {
|
|
|
662
682
|
toolCalls: toolCalls.map((tc) => ({
|
|
663
683
|
id: tc.id,
|
|
664
684
|
name: tc.function.name,
|
|
665
|
-
args:
|
|
685
|
+
args: capForLog(tc.function.arguments),
|
|
666
686
|
})),
|
|
667
687
|
}
|
|
668
688
|
: {}),
|
package/dist/platformDoc.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
export declare const PLATFORM_DOCS_DIR: string;
|
|
2
2
|
export declare const PLATFORM_DOC_REL: string;
|
|
3
|
+
export declare const MULTIPLAYER_DOC_REL: string;
|
|
3
4
|
export declare function everyDeckBullets(deckDir: string): string[];
|
|
4
5
|
export type AgentRole = 'router' | 'task';
|
|
5
6
|
export declare function roleLoadsClaudeMd(role: AgentRole): boolean;
|
package/dist/platformDoc.js
CHANGED
|
@@ -2,6 +2,7 @@ import * as crypto from 'crypto';
|
|
|
2
2
|
import * as fs from 'fs';
|
|
3
3
|
import * as path from 'path';
|
|
4
4
|
import { resolveFileTypes } from './editorConfig.js';
|
|
5
|
+
import { MULTIPLAYER_DOC } from './multiplayerDoc.js';
|
|
5
6
|
// The platform's own guidance to agents -- the rules identical in a bare deck
|
|
6
7
|
// and a kit deck: the card, touch, assets and formats, imports, reloading,
|
|
7
8
|
// editors. Its one home is here. The serve writes it under the deck's .castle/
|
|
@@ -21,6 +22,10 @@ import { resolveFileTypes } from './editorConfig.js';
|
|
|
21
22
|
// the vehicle, not a rewrite.
|
|
22
23
|
export const PLATFORM_DOCS_DIR = path.join('.castle', 'docs');
|
|
23
24
|
export const PLATFORM_DOC_REL = path.join(PLATFORM_DOCS_DIR, 'platform.md');
|
|
25
|
+
// The one guide that is read on demand rather than inlined: multiplayerDoc.ts
|
|
26
|
+
// holds its text, platform.md's Multiplayer section points at this path, and
|
|
27
|
+
// nothing puts it in a prompt.
|
|
28
|
+
export const MULTIPLAYER_DOC_REL = path.join(PLATFORM_DOCS_DIR, 'multiplayer.md');
|
|
24
29
|
const MEDIA = {
|
|
25
30
|
images: ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg'],
|
|
26
31
|
audio: ['.mp3', '.wav', '.m4a'],
|
|
@@ -51,6 +56,8 @@ export function everyDeckBullets(deckDir) {
|
|
|
51
56
|
`- **Supported media formats are exactly**: ${mediaList(deckDir)}. 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.`,
|
|
52
57
|
"- 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).",
|
|
53
58
|
"- 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.",
|
|
59
|
+
'- If the browser console shows `[vite] failed to connect to websocket` (or a "Direct websocket connection fallback" line), ignore it. Vite HMR is deliberately off on this serve, so the line is expected and harmless: it is never why a scene is blank, a game is not running, or multiplayer is not connecting. Do not investigate or "fix" it.',
|
|
60
|
+
"- Never revert, replace, or re-scaffold the deck's scenes, scripts, or behaviors back to kit, starter, or imported content, and never delete or rewrite a whole scene to diagnose a problem -- those files are the person's own work. Fix forward with targeted edits, and treat a request to diagnose or explain as read-only unless they asked for a fix.",
|
|
54
61
|
"- 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.",
|
|
55
62
|
'- 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.',
|
|
56
63
|
"- **Put the values someone would tune while playtesting in a `PARAMS` object**: `export const PARAMS = { jumpHeight: 4.2, coyoteTime: 0.08 };` near the top of the file that uses them. The Parameters panel lists every file in the deck that has one and renders their values as fields -- a number scrubs, a boolean toggles, a `'#rrggbb'` string opens a color picker -- and writes the edit back into the file. It edits every file's params in one place, so nobody has to remember which file a setting lives in, and a file that has params says so above its code with a way in. That is how a creator tunes a game on a phone without putting a cursor inside an expression. Nested one level deep (`player: { speed: 5 }`) renders as a group. **Write each value as a plain number, not as arithmetic** (`0.333`, not `1 / 3`): the panel folds arithmetic over plain numbers into a field and replaces it with the tuned literal on the first edit, so the expression you wrote does not survive the first tune. A value that NAMES something (`speed: BASE * 2`) shows read-only, as a link onto its own line in the code.",
|
|
@@ -214,7 +221,8 @@ const COMMON_SECTIONS = `## Imports are read-only
|
|
|
214
221
|
|
|
215
222
|
## Multiplayer
|
|
216
223
|
|
|
217
|
-
- **
|
|
224
|
+
- **Read \`${MULTIPLAYER_DOC_REL}\` before writing or changing a server entry or client netcode by hand.** It carries what this section leaves out: the outbound frame budget in practice, the snapshot pattern, self-healing events, and the reconnect and disconnect handling a hand-rolled session gets wrong. A deck built on the \`castle.multiplayer-2d\` / \`castle.multiplayer-3d\` (or \`castle.turn-based\`) kits already does all of that and normally writes nothing against the raw session API.
|
|
225
|
+
- **A deck becomes multiplayer by having a server entry** — no flag, no dashboard. The entry is \`castle.json\`'s \`server.main\` when set (a kit deck points it under \`imports/\`), otherwise the first of \`server/index.{js,ts,mjs}\` or \`code/server/index.{js,ts,mjs}\` that exists; removing the entry turns multiplayer off on the next \`save-deck\`. Castle runs that module as a real server process, one per session, shared by the players in it. Other options under \`server\`: \`maxPlayers\` (max 24), and \`tickRate\` (defaults to 20, max 30; 0 turns ticks off).
|
|
218
226
|
- **The server module default-exports lifecycle callbacks**, each taking the session first:
|
|
219
227
|
|
|
220
228
|
\`\`\`js
|
|
@@ -223,7 +231,7 @@ const COMMON_SECTIONS = `## Imports are read-only
|
|
|
223
231
|
onPlayerJoin(session, player) {}, // player: { playerId, userId, username, isAnonymous }
|
|
224
232
|
onPlayerLeave(session, player) {},
|
|
225
233
|
onMessage(session, player, data) {}, // data is what the client sent, already parsed
|
|
226
|
-
onTick(session
|
|
234
|
+
onTick(session) {}, // only when castle.json sets server.tickRate > 0
|
|
227
235
|
onReplaced(session) {}, // you published a new version; this session keeps the old one
|
|
228
236
|
async onShutdown(session) {}, // the session is ending; awaited, so a save here lands
|
|
229
237
|
};
|
|
@@ -257,10 +265,10 @@ const COMMON_SECTIONS = `## Imports are read-only
|
|
|
257
265
|
|
|
258
266
|
Publishing a server takes ownership of \`deck\` scope: from then on clients read that data but no longer write it, which is what lets you keep authoritative state players cannot forge. A server can write any player's public bucket and submit any player's score, so name the player — there is no \`storage.me\`. It can never read \`private\` storage, not even for its own players.
|
|
259
267
|
- **Save as things change, not only at the end.** \`onShutdown\` is awaited and a save made there does land, but it only runs on a clean stop: an out-of-memory kill or a host failing sends no shutdown at all. Treat it as the last chance rather than the plan.
|
|
260
|
-
- **Limits worth designing around.** Client→server messages are capped at 16 KB and about 30 per second; server→client messages are capped at 64 KB. These limits apply to both JSON and binary frames and are measured on the frame, so a binary frame's one-byte protocol tag leaves you one byte under the cap for payload.
|
|
268
|
+
- **Limits worth designing around.** Client→server messages are capped at 16 KB and about 30 per second; server→client messages are capped at 64 KB. These limits apply to both JSON and binary frames and are measured on the frame, so a binary frame's one-byte protocol tag leaves you one byte under the cap for payload. A session may also SEND only about \`40 + 40 × connected players\` frames per second (about two seconds of burst, and about 1 MiB/s of bytes): \`session.send\` costs one frame per call, \`session.broadcast(data)\` costs ONE frame however many players are in the session, and \`session.broadcast(data, { except })\` is a loop of sends, so it costs one frame per recipient. Frames over the budget are dropped silently and never retried — the session keeps running, so the symptom is a client whose world quietly stops matching everyone else's; only sustained abuse at several times the budget ends a session. So send one \`broadcast\` per tick carrying every player's state, rather than a tailored \`send\` per player: every client reads every entry of that snapshot INCLUDING its own — it takes hp, kills and match state from its own entry and only keeps its own position locally predicted.
|
|
261
269
|
- **Binary messages are opt-in per payload.** Pass any typed array, \`DataView\`, or \`ArrayBuffer\` to client \`send\`, server \`send\`, or server \`broadcast\` to send its raw bytes. \`onMessage\` always receives those bytes as a \`Uint8Array\`, while every other payload continues to use JSON. Reconstruct another view type such as \`Float32Array\` on receipt; multi-byte values use the sender platform's byte order.
|
|
262
|
-
- **Test multiplayer locally with no setup.** \`castle-web serve\` runs your server file alongside the deck
|
|
263
|
-
- **Publishing does not disturb games in progress.** \`save-deck\` bundles and publishes
|
|
270
|
+
- **Test multiplayer locally with no setup.** \`castle-web serve\` runs your server file alongside the deck. Open the shell URL it prints in two tabs, then open the Play panel in each; those play surfaces share a session. If you open the content origin from \`.castle/serve.json\` directly, use \`/index.html?edit=0\`. Its bare origin loads the edit surface, where \`Multiplayer.join\` is not answered. Editing the server entry, anything beside it, or a deck-owned hook under \`server/\` or \`code/server/\` restarts it and clients reconnect, so you exercise your reconnect path constantly. Server \`console.log\` goes to the serve's logs, not the browser console.
|
|
271
|
+
- **Publishing does not disturb games in progress.** \`save-deck\` bundles and publishes the server entry, but sessions already running keep the code they started with (they get \`onReplaced\`, so you can prompt players), and the next new session picks up the new version.
|
|
264
272
|
`;
|
|
265
273
|
export function platformGuide(deckDir) {
|
|
266
274
|
return `${COMMON_SECTIONS.trimEnd()}
|
|
@@ -280,10 +288,21 @@ kit provides on top of this.
|
|
|
280
288
|
${platformGuide(deckDir)}`;
|
|
281
289
|
}
|
|
282
290
|
// Written by the serve at every start, so the copy in a deck is exactly as
|
|
283
|
-
// fresh as the CLI serving it.
|
|
291
|
+
// fresh as the CLI serving it. platform.md is the always-loaded one; the
|
|
292
|
+
// multiplayer guide sits beside it and is read only when a deck's server or
|
|
293
|
+
// netcode is being written by hand.
|
|
284
294
|
export function writePlatformDocs(deckDir) {
|
|
285
295
|
fs.mkdirSync(path.join(deckDir, PLATFORM_DOCS_DIR), { recursive: true });
|
|
286
296
|
fs.writeFileSync(path.join(deckDir, PLATFORM_DOC_REL), platformDoc(deckDir));
|
|
297
|
+
// Best-effort, unlike platform.md above: the serve calls this on its way up,
|
|
298
|
+
// and a deck missing a guide it reads on demand is a missing reference, never
|
|
299
|
+
// a reason to fail a serve start that would otherwise work.
|
|
300
|
+
try {
|
|
301
|
+
fs.writeFileSync(path.join(deckDir, MULTIPLAYER_DOC_REL), MULTIPLAYER_DOC);
|
|
302
|
+
}
|
|
303
|
+
catch (error) {
|
|
304
|
+
console.warn(`Could not write ${MULTIPLAYER_DOC_REL}: ${error instanceof Error ? error.message : String(error)}`);
|
|
305
|
+
}
|
|
287
306
|
}
|
|
288
307
|
// What the deck's root CLAUDE.md carries for the platform: one @import line
|
|
289
308
|
// (which claude auto-loads) inside a short section that says what it is, for
|
package/dist/remix.js
CHANGED
|
@@ -4,7 +4,9 @@ import * as api from './api.js';
|
|
|
4
4
|
import { downloadSourceArchive, runTar } from './save-deck.js';
|
|
5
5
|
// Scaffolding a deck from another published deck, for `init --remix`.
|
|
6
6
|
// Dropped from the copied castle.json. `autoUpdateWhenImported` is the parent's
|
|
7
|
-
// promise to ITS importers, which a remix hasn't made
|
|
7
|
+
// promise to ITS importers, which a remix hasn't made -- and `onUpdate` is the
|
|
8
|
+
// migration it runs in them, naming a module the remix keeps as ordinary source
|
|
9
|
+
// rather than as a hook.
|
|
8
10
|
const PARENT_ONLY_KEYS = [
|
|
9
11
|
'deckId',
|
|
10
12
|
'cardId',
|
|
@@ -12,6 +14,7 @@ const PARENT_ONLY_KEYS = [
|
|
|
12
14
|
'caption',
|
|
13
15
|
'publishedVersion',
|
|
14
16
|
'autoUpdateWhenImported',
|
|
17
|
+
'onUpdate',
|
|
15
18
|
];
|
|
16
19
|
function parseJson(text) {
|
|
17
20
|
try {
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import type { ServerResponse } from 'http';
|
|
2
|
+
import type { Plugin } from 'vite';
|
|
3
|
+
export interface ScriptError {
|
|
4
|
+
/** Deck-relative path of the file that failed (absolute if outside the deck). */
|
|
5
|
+
path: string;
|
|
6
|
+
message: string;
|
|
7
|
+
line?: number;
|
|
8
|
+
column?: number;
|
|
9
|
+
/** Vite's source excerpt around the failure, when it produced one. */
|
|
10
|
+
frame?: string;
|
|
11
|
+
}
|
|
12
|
+
export interface ScriptErrors {
|
|
13
|
+
/** Observe a failed transform. Returns what was recorded, or null if it wasn't ours. */
|
|
14
|
+
record(error: unknown): ScriptError | null;
|
|
15
|
+
/** Observe a module id transforming cleanly again. */
|
|
16
|
+
clearId(id: string): void;
|
|
17
|
+
/** The latest error per path, for `/__castle/script-errors`. */
|
|
18
|
+
snapshot(): Record<string, ScriptError>;
|
|
19
|
+
/** Answer a `/__castle/script-errors` request. */
|
|
20
|
+
respond(res: ServerResponse): void;
|
|
21
|
+
}
|
|
22
|
+
export declare function createScriptErrors(projectDir: string, broadcast: (message: unknown) => void): ScriptErrors;
|
|
23
|
+
export declare function scriptErrorsPlugin(errors: ScriptErrors): Plugin;
|