castle-web-cli 0.4.204 → 0.4.206

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 (134) hide show
  1. package/dist/agent-failures.d.ts +3 -1
  2. package/dist/agent-failures.js +19 -0
  3. package/dist/agent-prompts.d.ts +1 -0
  4. package/dist/agent-prompts.js +7 -2
  5. package/dist/agent.d.ts +3 -2
  6. package/dist/agent.js +29 -18
  7. package/dist/castle-host/host.d.ts +17 -0
  8. package/dist/castle-host/host.js +551 -4
  9. package/dist/devSessionStorage.js +65 -4
  10. package/dist/effortSupport.d.ts +7 -0
  11. package/dist/effortSupport.js +31 -0
  12. package/dist/imports.d.ts +1 -1
  13. package/dist/imports.js +59 -19
  14. package/dist/index.js +4 -3
  15. package/dist/init.d.ts +9 -1
  16. package/dist/init.js +64 -25
  17. package/dist/kitCatalog.d.ts +13 -0
  18. package/dist/kitCatalog.js +111 -0
  19. package/dist/platformDoc.js +7 -2
  20. package/dist/serve.js +35 -2
  21. package/dist/shell/assets/{index-DHzA0-Sj.js → index-hWQTC8q6.js} +5 -5
  22. package/dist/shell/index.html +1 -1
  23. package/dist/vitePlugins.js +19 -1
  24. package/kits/base/CLAUDE.md +2 -0
  25. package/kits/base/castle.json +1 -1
  26. package/kits/base/sdk/README.md +131 -0
  27. package/kits/base/sdk/agent.d.ts +6 -0
  28. package/kits/base/sdk/agent.js +70 -0
  29. package/kits/base/sdk/castle.d.ts +4 -0
  30. package/kits/base/sdk/castle.js +2 -0
  31. package/kits/base/sdk/commands.d.ts +106 -0
  32. package/kits/base/sdk/commands.js +21 -0
  33. package/kits/base/sdk/decks.d.ts +7 -0
  34. package/kits/base/sdk/decks.js +31 -0
  35. package/kits/base/sdk/runtime.d.ts +4 -2
  36. package/kits/base/sdk/runtime.js +51 -40
  37. package/kits/base/sdk/server/storage.d.ts +44 -0
  38. package/kits/base/sdk/server/storage.js +54 -0
  39. package/kits/base/sdk/transport.d.ts +5 -1
  40. package/kits/base/sdk/transport.js +106 -23
  41. package/kits/multiplayer-2d/castle.json +5 -4
  42. package/kits/multiplayer-2d/code/client/poses.js +7 -0
  43. package/kits/multiplayer-2d/code/server/limits.js +3 -0
  44. package/kits/multiplayer-2d/code/server/ownership.js +36 -8
  45. package/kits/multiplayer-2d/code/systems/multiplayer.js +23 -2
  46. package/kits/multiplayer-3d/CLAUDE.md +12 -1
  47. package/kits/multiplayer-3d/castle.json +5 -4
  48. package/kits/multiplayer-3d/code/client/avatars.js +7 -1
  49. package/kits/multiplayer-3d/code/client/poses.js +61 -1
  50. package/kits/multiplayer-3d/code/client/steer.js +383 -0
  51. package/kits/multiplayer-3d/code/server/limits.js +3 -0
  52. package/kits/multiplayer-3d/code/server/ownership.js +114 -18
  53. package/kits/multiplayer-3d/code/server/world.js +12 -4
  54. package/kits/multiplayer-3d/code/systems/multiplayer.js +315 -34
  55. package/kits/physics-2d/castle.json +1 -0
  56. package/kits/physics-3d/CLAUDE.md +65 -7
  57. package/kits/physics-3d/castle.json +4 -3
  58. package/kits/physics-3d/docs/pxmodel-format.md +916 -15
  59. package/kits/physics-3d/engine3d/PxModelEditor.jsx +2 -2
  60. package/kits/physics-3d/engine3d/artobjects.js +218 -0
  61. package/kits/physics-3d/engine3d/blob.js +1058 -0
  62. package/kits/physics-3d/engine3d/branches.js +300 -0
  63. package/kits/physics-3d/engine3d/cage.js +496 -0
  64. package/kits/physics-3d/engine3d/cageops.js +516 -0
  65. package/kits/physics-3d/engine3d/frame.js +669 -0
  66. package/kits/physics-3d/engine3d/look.js +675 -0
  67. package/kits/physics-3d/engine3d/materialpresets.js +486 -0
  68. package/kits/physics-3d/engine3d/modelEditorWorld.js +3 -2
  69. package/kits/physics-3d/engine3d/modelrefs.js +120 -0
  70. package/kits/physics-3d/engine3d/motion.js +560 -0
  71. package/kits/physics-3d/engine3d/objtext.js +37 -0
  72. package/kits/physics-3d/engine3d/optimize.js +1083 -0
  73. package/kits/physics-3d/engine3d/paint.js +674 -0
  74. package/kits/physics-3d/engine3d/partgeometry.js +467 -0
  75. package/kits/physics-3d/engine3d/paths.js +324 -0
  76. package/kits/physics-3d/engine3d/pxmodel.js +429 -26
  77. package/kits/physics-3d/engine3d/scatter.js +102 -0
  78. package/kits/physics-3d/engine3d/sculpt.js +1148 -0
  79. package/kits/physics-3d/engine3d/surfacedetail.js +267 -0
  80. package/kits/physics-3d/engine3d/sweep.js +480 -0
  81. package/kits/physics-3d/engine3d/thumbnails.js +6 -4
  82. package/kits/physics-3d/engine3d/world3d.js +119 -17
  83. package/kits/physics-3d/eslint.config.js +13 -0
  84. package/kits/physics-3d/models/parts/axe.pxmodel +40 -0
  85. package/kits/physics-3d/models/parts/backpack.pxmodel +47 -0
  86. package/kits/physics-3d/models/parts/barrel.pxmodel +22 -0
  87. package/kits/physics-3d/models/parts/bedroll.pxmodel +28 -0
  88. package/kits/physics-3d/models/parts/belt-pouch.pxmodel +22 -0
  89. package/kits/physics-3d/models/parts/bolt.pxmodel +10 -0
  90. package/kits/physics-3d/models/parts/bracer.pxmodel +26 -0
  91. package/kits/physics-3d/models/parts/chain-span.pxmodel +12 -0
  92. package/kits/physics-3d/models/parts/chimney.pxmodel +11 -0
  93. package/kits/physics-3d/models/parts/crate.pxmodel +44 -0
  94. package/kits/physics-3d/models/parts/crystal.pxmodel +22 -0
  95. package/kits/physics-3d/models/parts/door-arched.pxmodel +12 -0
  96. package/kits/physics-3d/models/parts/engine-block.pxmodel +39 -0
  97. package/kits/physics-3d/models/parts/exhaust-pipe.pxmodel +30 -0
  98. package/kits/physics-3d/models/parts/fence-span.pxmodel +10 -0
  99. package/kits/physics-3d/models/parts/fender.pxmodel +19 -0
  100. package/kits/physics-3d/models/parts/headlight.pxmodel +24 -0
  101. package/kits/physics-3d/models/parts/hood.pxmodel +17 -0
  102. package/kits/physics-3d/models/parts/horned-helmet.pxmodel +37 -0
  103. package/kits/physics-3d/models/parts/jerry-can.pxmodel +26 -0
  104. package/kits/physics-3d/models/parts/ladder.pxmodel +10 -0
  105. package/kits/physics-3d/models/parts/lamp.pxmodel +20 -0
  106. package/kits/physics-3d/models/parts/lantern.pxmodel +30 -0
  107. package/kits/physics-3d/models/parts/leaf-cluster.pxmodel +21 -0
  108. package/kits/physics-3d/models/parts/offroad-tire.pxmodel +48 -0
  109. package/kits/physics-3d/models/parts/pauldron.pxmodel +26 -0
  110. package/kits/physics-3d/models/parts/rivet.pxmodel +8 -0
  111. package/kits/physics-3d/models/parts/rock.pxmodel +21 -0
  112. package/kits/physics-3d/models/parts/roll-bar-light.pxmodel +26 -0
  113. package/kits/physics-3d/models/parts/round-shield.pxmodel +31 -0
  114. package/kits/physics-3d/models/parts/saddlebag.pxmodel +30 -0
  115. package/kits/physics-3d/models/parts/spoked-wheel.pxmodel +39 -0
  116. package/kits/physics-3d/models/parts/staff.pxmodel +33 -0
  117. package/kits/physics-3d/models/parts/stepping-stones.pxmodel +8 -0
  118. package/kits/physics-3d/models/parts/stone-base.pxmodel +10 -0
  119. package/kits/physics-3d/models/parts/sword.pxmodel +33 -0
  120. package/kits/physics-3d/models/parts/window-lit.pxmodel +13 -0
  121. package/kits/physics-3d/models/parts/wizard-hat.pxmodel +28 -0
  122. package/kits/physics-3d/models/templates/biped-stout.pxmodel +59 -0
  123. package/kits/physics-3d/models/templates/biped-tall.pxmodel +63 -0
  124. package/kits/physics-3d/models/templates/quadruped.pxmodel +52 -0
  125. package/kits/physics-3d/scripts/render/filmstrip.js +217 -0
  126. package/kits/physics-3d/scripts/render/index.html +20 -0
  127. package/kits/physics-3d/scripts/render/sheet.js +411 -0
  128. package/kits/physics-3d/scripts/render.mjs +646 -0
  129. package/kits/real-time/castle.json +2 -2
  130. package/kits/real-time/code/client/ownership.js +14 -4
  131. package/kits/real-time/code/client/smooth.js +2 -2
  132. package/kits/real-time/code/server/session.js +20 -4
  133. package/kits/turn-based/castle.json +1 -0
  134. package/package.json +2 -2
@@ -0,0 +1,31 @@
1
+ export const EFFORT_ORDER = ['low', 'medium', 'high', 'xhigh', 'max'];
2
+ // Levels a model's endpoint refuses outright with a 400, keyed by exact
3
+ // OpenRouter slug so that deleting one entry re-enables the level for that
4
+ // model alone. Meta's docs: max is "Standard-tier muse-spark-1.3 only; not
5
+ // available on Contributor-tier models". The endpoint has flapped (it accepted
6
+ // max on 2026-09-22 and refused it from 09-24), so re-check before trusting
7
+ // either state for long.
8
+ export const UNSUPPORTED_EFFORTS = {
9
+ 'meta/muse-spark-1.3-contributor': ['max'],
10
+ };
11
+ // OpenRouter's ":nitro"-style variant suffixes route to the same endpoint.
12
+ function unsupportedFor(slug) {
13
+ const key = slug.trim().toLowerCase();
14
+ return UNSUPPORTED_EFFORTS[key] ?? UNSUPPORTED_EFFORTS[key.replace(/:[^/:]*$/, '')] ?? [];
15
+ }
16
+ export function effortSupported(slug, effort) {
17
+ return !unsupportedFor(slug).includes(effort);
18
+ }
19
+ export function supportedEffort(slug, effort) {
20
+ if (effortSupported(slug, effort))
21
+ return effort;
22
+ const at = EFFORT_ORDER.indexOf(effort);
23
+ const lower = EFFORT_ORDER.slice(0, at).reverse().find((level) => effortSupported(slug, level));
24
+ return lower ?? EFFORT_ORDER.slice(at + 1).find((level) => effortSupported(slug, level)) ?? effort;
25
+ }
26
+ export function isEffortLevel(value) {
27
+ return EFFORT_ORDER.includes(value);
28
+ }
29
+ export function pressedEffort(slug, stored) {
30
+ return slug && isEffortLevel(stored) ? supportedEffort(slug, stored) : stored;
31
+ }
package/dist/imports.d.ts CHANGED
@@ -6,7 +6,7 @@ export interface ImportVersion {
6
6
  }
7
7
  export declare function writeImportVersion(importDir: string, value: ImportVersion): void;
8
8
  export declare function readImportVersion(deckDir: string, alias: string): ImportVersion | null;
9
- export type ImportErrorCode = 'no-deck-ref' | 'bad-deck-ref' | 'no-such-dir' | 'self-import' | 'no-source' | 'bad-alias';
9
+ export type ImportErrorCode = 'no-deck-ref' | 'bad-deck-ref' | 'no-such-dir' | 'self-import' | 'no-source' | 'bad-alias' | 'already-imported';
10
10
  export declare class ImportError extends Error {
11
11
  code: ImportErrorCode;
12
12
  constructor(code: ImportErrorCode, message: string);
package/dist/imports.js CHANGED
@@ -5,6 +5,7 @@ import * as api from './api.js';
5
5
  import { runTar } from './save-deck.js';
6
6
  import { normalizeDeckPackageJson } from './normalize.js';
7
7
  import { getKitsDir } from './localPaths.js';
8
+ import { shippedFrameworkKit, shippedKitAlias } from './kitCatalog.js';
8
9
  import { SDK_PACKAGE } from './sdkResolve.js';
9
10
  import { writePlatformDocs } from './platformDoc.js';
10
11
  import { findImportUpdateHook, runImportUpdateHook, } from './importUpdateHook.js';
@@ -506,22 +507,23 @@ export function importedDeckIds(deckDir) {
506
507
  .map((p) => p?.deckId)
507
508
  .filter((id) => !!id));
508
509
  }
509
- // The import itself. Throws ImportError rather than exiting, because this also
510
- // runs inside the serve (from the editor's Import panel), where taking the
511
- // process down is not an option. The CLI wrapper below prints and exits.
512
- export async function addImportTo(dir, options = {}) {
513
- const targetDir = path.resolve(dir);
514
- const ref = options.deckRef?.trim();
515
- if (!ref) {
516
- throw new ImportError('no-deck-ref', 'No deck given. Pass a deck id or a castle.xyz deck link.');
510
+ async function placeShippedKit(targetDir, kit, givenAlias) {
511
+ const alias = shippedKitAlias(kit);
512
+ if (givenAlias && givenAlias.trim() !== alias) {
513
+ throw new ImportError('bad-alias', `A shipped kit is always imported as ${alias}; drop --as.`);
517
514
  }
518
- const deckId = parseDeckRef(ref);
519
- if (!deckId) {
520
- throw new ImportError('bad-deck-ref', `Not a deck id or a castle deck link: ${ref}`);
521
- }
522
- if (!fs.existsSync(targetDir)) {
523
- throw new ImportError('no-such-dir', `No such directory: ${targetDir}`);
515
+ // Add-only: the CLI's copy can be older than the one the deck updated to, and
516
+ // replacing it would pin the kit backwards under data already migrated forward.
517
+ const pins = (tryReadCastleJson(targetDir)?.imports ?? {});
518
+ if (Object.hasOwn(pins, alias) || fs.existsSync(path.join(targetDir, IMPORTS_DIR, alias))) {
519
+ throw new ImportError('already-imported', `${alias} is already imported; run \`castle-web update-import ${alias}\` to move it to the latest version.`);
524
520
  }
521
+ const { importShippedKit } = await import('./init.js');
522
+ const placed = importShippedKit(targetDir, kit);
523
+ clearStatusCache(targetDir);
524
+ return placed;
525
+ }
526
+ async function placeFetchedImport(targetDir, deckId, givenAlias) {
525
527
  if (readCastleJson(targetDir)?.deckId === deckId) {
526
528
  throw new ImportError('self-import', `Deck ${deckId} is this deck -- a deck can't import itself.`);
527
529
  }
@@ -533,8 +535,8 @@ export async function addImportTo(dir, options = {}) {
533
535
  throw new ImportError('no-source', `No source archive on the server for deck ${deckId}. ` +
534
536
  'Its owner needs to run `castle-web save-deck` before it can be imported.');
535
537
  }
536
- const given = options.alias ? slugifyGivenAlias(options.alias) : '';
537
- if (options.alias && !given) {
538
+ const given = givenAlias ? slugifyGivenAlias(givenAlias) : '';
539
+ if (givenAlias && !given) {
538
540
  throw new ImportError('bad-alias', 'Could not derive a usable name; pick one with letters or digits.');
539
541
  }
540
542
  // An explicit `--as` is the caller's call, collision and all. A derived one
@@ -542,6 +544,35 @@ export async function addImportTo(dir, options = {}) {
542
544
  const alias = given || availableAlias(targetDir, qualifiedAlias(meta, deckId), deckId);
543
545
  const { replaced } = await placeImport(targetDir, alias, deckId, source);
544
546
  const transitive = await addTransitiveImports(targetDir, alias, importedDeckIds(targetDir));
547
+ return { deckId, alias, replaced, transitive };
548
+ }
549
+ // The import itself. Throws ImportError rather than exiting, because this also
550
+ // runs inside the serve (from the editor's Import panel), where taking the
551
+ // process down is not an option. The CLI wrapper below prints and exits.
552
+ export async function addImportTo(dir, options = {}) {
553
+ const targetDir = path.resolve(dir);
554
+ const ref = options.deckRef?.trim();
555
+ if (!ref) {
556
+ throw new ImportError('no-deck-ref', 'No deck given. Pass a deck id or a castle.xyz deck link.');
557
+ }
558
+ if (!fs.existsSync(targetDir)) {
559
+ throw new ImportError('no-such-dir', `No such directory: ${targetDir}`);
560
+ }
561
+ // Before parseDeckRef: a kit's name is id-shaped, so the other order would
562
+ // send `physics-2d` to the server as a deck id.
563
+ const kit = shippedFrameworkKit(ref);
564
+ const deckId = kit ? null : parseDeckRef(ref);
565
+ let placed;
566
+ if (kit) {
567
+ placed = await placeShippedKit(targetDir, kit, options.alias);
568
+ }
569
+ else if (deckId) {
570
+ placed = await placeFetchedImport(targetDir, deckId, options.alias);
571
+ }
572
+ else {
573
+ throw new ImportError('bad-deck-ref', `Not a deck id or a castle deck link: ${ref}`);
574
+ }
575
+ const { alias, replaced, transitive } = placed;
545
576
  const dependencies = syncImportDependencies(targetDir);
546
577
  // A kit declares its entry module (castle.json `main`). Importing one into a
547
578
  // deck that is still the untouched `--kit none` scaffold means "start from this
@@ -552,9 +583,10 @@ export async function addImportTo(dir, options = {}) {
552
583
  const declaredMain = tryReadCastleJson(importDir)?.main;
553
584
  let adoptedMain = null;
554
585
  if (typeof declaredMain === 'string' && declaredMain.trim()) {
555
- const { isPristineBareDeck, adoptImportEntry, writeStarterScene, writeStarterTheme, retargetBareClaudeMd, } = await import('./init.js');
586
+ const { isPristineBareDeck, adoptImportEntry, writeStarterScene, writeStarterTheme, retargetBareClaudeMd, adoptKitConfig, } = await import('./init.js');
556
587
  if (isPristineBareDeck(targetDir)) {
557
588
  adoptImportEntry(targetDir, alias, declaredMain.trim());
589
+ adoptKitConfig(targetDir, importDir, alias);
558
590
  adoptedMain = declaredMain.trim();
559
591
  retargetBareClaudeMd(targetDir, alias);
560
592
  // A kit's runtime with no scene to run is a blank screen, and the agent
@@ -600,7 +632,15 @@ export async function addImportTo(dir, options = {}) {
600
632
  writePlatformDocs(targetDir);
601
633
  const trimmedMain = typeof declaredMain === 'string' && declaredMain.trim() ? declaredMain.trim() : null;
602
634
  const offersMain = trimmedMain && !adoptedMain ? trimmedMain : null;
603
- return { deckId, alias, replaced, transitive, dependencies, adoptedMain, offersMain };
635
+ return {
636
+ deckId: placed.deckId,
637
+ alias,
638
+ replaced,
639
+ transitive,
640
+ dependencies,
641
+ adoptedMain,
642
+ offersMain,
643
+ };
604
644
  }
605
645
  export async function addImport(dir, options = {}) {
606
646
  let result;
@@ -612,7 +652,7 @@ export async function addImport(dir, options = {}) {
612
652
  throw err;
613
653
  console.error(err.message);
614
654
  if (err.code === 'no-deck-ref') {
615
- console.error('Usage: castle-web add-import <deckId|url> [dir] [--as ALIAS]');
655
+ console.error('Usage: castle-web add-import <deckId|url|kit> [dir] [--as ALIAS]');
616
656
  }
617
657
  process.exit(1);
618
658
  }
package/dist/index.js CHANGED
@@ -143,7 +143,7 @@ function usage() {
143
143
  castle-web save-deck [dir] [--title TITLE] [--caption TEXT] [--visibility unlisted|private]
144
144
  castle-web get-deck [dir] [--deck-id ID] [--force] (replaces the source if the deck is already there)
145
145
  castle-web list-decks [dir] [--kind mine|saved|kits] (decks this one could import; ids are what add-import takes)
146
- castle-web add-import <deckId|url> [dir] [--as ALIAS] (adds another deck as a read-only dependency in imports/)
146
+ castle-web add-import <deckId|url|kit> [dir] [--as ALIAS] (adds another deck, or a kit this CLI ships, as a read-only dependency in imports/)
147
147
  castle-web fork-import-file <imports/...> [dir] (this deck's own version of one imported file)
148
148
  castle-web revert-import-file <imports/...> [dir]
149
149
  castle-web update-import [alias] [dir] [--check] [--revert] (re-fetches imports; no alias means all)
@@ -243,8 +243,9 @@ async function main() {
243
243
  break;
244
244
  }
245
245
  case 'add-import': {
246
- // The deck -- an id or the link to its page -- is the first positional;
247
- // the importing deck's dir is an optional second, defaulting to the cwd.
246
+ // The deck -- an id, the link to its page, or a shipped kit's name -- is the
247
+ // first positional; the importing deck's dir is an optional second,
248
+ // defaulting to the cwd.
248
249
  const positionals = readPositionals();
249
250
  await addImport(positionals[1] ?? '.', {
250
251
  deckRef: getFlagValue('--deck-id') ?? positionals[0],
package/dist/init.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  export declare const BASE_KIT = "base";
2
- export declare const BASE_ALIAS = "castle.base";
2
+ export declare const BASE_ALIAS: string;
3
3
  export declare function resolveScaffoldRefs(): {
4
4
  workspaceMode: boolean;
5
5
  sdkRef: string;
@@ -14,6 +14,14 @@ export declare function getCliVersion(): string;
14
14
  export declare function writeStarterScene(projectDir: string, kitDir: string, alias: string): void;
15
15
  export declare function writeStarterTheme(projectDir: string, kitDir: string): void;
16
16
  export declare function retargetBareClaudeMd(deckDir: string, alias: string): void;
17
+ export interface ShippedKitImport {
18
+ alias: string;
19
+ deckId: string;
20
+ replaced: false;
21
+ transitive: string[];
22
+ }
23
+ export declare function importShippedKit(deckDir: string, kit: string): ShippedKitImport;
24
+ export declare function adoptKitConfig(deckDir: string, kitDir: string, alias: string): void;
17
25
  export declare function init(dir: string, opts?: {
18
26
  kit?: string;
19
27
  serve?: boolean;
package/dist/init.js CHANGED
@@ -5,6 +5,7 @@ import { installDeps } from './install.js';
5
5
  import { deckMainFile, deckStarterScene, STARTER_THEME_FILES } from './castleJson.js';
6
6
  import { addImportTo, IMPORTS_DIR, lockImportTree, restoreMissingImports, syncImportDependencies, writeImportVersion, } from './imports.js';
7
7
  import { discardParentSource, fetchParentSource, unpackParentSource, writeRemixIdentity, } from './remix.js';
8
+ import { kitFromAlias, shippedKitAlias } from './kitCatalog.js';
8
9
  import { getCliEntryPath, getKitsDir, getSdkPackagePath, toPosixPath } from './localPaths.js';
9
10
  import { SDK_PACKAGE } from './sdkResolve.js';
10
11
  import { serve } from './serve.js';
@@ -12,15 +13,12 @@ import { createVersion } from './versions.js';
12
13
  // Default kit imported by `init` when no --kit is given. `none`/`bare` skips the
13
14
  // framework and produces the minimal index.html + game.js stub below.
14
15
  const DEFAULT_KIT = 'physics-2d';
15
- // The account the first-party kits are (to be) published under, so a kit
16
- // imported from the CLI's copy is named the same as one fetched from the server.
17
- const KIT_AUTHOR = 'castle';
18
16
  // EVERY deck imports this one, kit or not. It carries the SDK (which resolves
19
17
  // out of it -- see sdkResolve.ts), the editor host a deck with no kit mounts
20
18
  // its editors through, and the authoring guide every deck is written against.
21
19
  // A framework kit imports it too, so a kit deck has it as well.
22
20
  export const BASE_KIT = 'base';
23
- export const BASE_ALIAS = `${KIT_AUTHOR}.${BASE_KIT}`;
21
+ export const BASE_ALIAS = shippedKitAlias(BASE_KIT);
24
22
  const INDEX_HTML = `<!DOCTYPE html>
25
23
  <html>
26
24
  <head>
@@ -56,7 +54,7 @@ if (!(await mountEditorRoute())) startGame(initCard());
56
54
  // Registry version of castle-web-sdk to inject when scaffolding from a
57
55
  // globally-installed castle-web (not from inside the workspace). Bumped
58
56
  // alongside cli/sdk version bumps.
59
- const PUBLISHED_SDK_VERSION = '0.4.34';
57
+ const PUBLISHED_SDK_VERSION = '0.4.35';
60
58
  // Range, not a pin: `castle-web-fonts` is its own package precisely so a tenth
61
59
  // face can ship without a cli release, and a caret range means an existing
62
60
  // deck's next install picks it up. Nothing here has to move when it does.
@@ -118,7 +116,7 @@ function tryMakeAgentsSymlink(agentsPath) {
118
116
  // scaffold gets, plus the kit's own authoring commands re-pointed at where the
119
117
  // kit now lives -- a kit's CLAUDE.md tells the agent to run `npm run draw` and
120
118
  // `npm run restart`, and those have to exist in the deck for that to be true.
121
- function makeKitDeckScripts(kitDir, alias, cliCommand) {
119
+ function makeKitDeckScripts(kitDir, alias, cliCommand, copied) {
122
120
  const scripts = {
123
121
  restart: `${cliCommand} restart .`,
124
122
  screenshot: `${cliCommand} screenshot .`,
@@ -130,6 +128,16 @@ function makeKitDeckScripts(kitDir, alias, cliCommand) {
130
128
  if (fs.existsSync(path.join(kitDir, 'scripts', 'draw.mjs'))) {
131
129
  scripts.draw = `node ${IMPORTS_DIR}/${alias}/scripts/draw.mjs`;
132
130
  }
131
+ // `render` is physics-3d's. A kit built on it (multiplayer-3d) has it copied
132
+ // in beside itself, so every copied kit is checked, the scaffolding kit
133
+ // first. The script starts serves and playtests of its own and is told the
134
+ // CLI command the deck's other scripts use.
135
+ for (const [copiedAlias, copiedDir] of copied) {
136
+ if (fs.existsSync(path.join(copiedDir, 'scripts', 'render.mjs'))) {
137
+ scripts.render = `CASTLE_WEB_CLI='${cliCommand}' node ${IMPORTS_DIR}/${copiedAlias}/scripts/render.mjs`;
138
+ break;
139
+ }
140
+ }
133
141
  return scripts;
134
142
  }
135
143
  // No `castle-web-sdk` dependency: the SDK is a file of the `base` kit this deck
@@ -491,9 +499,7 @@ function copyKitImport(projectDir, kitDir, kit, alias, pins, copied) {
491
499
  for (const [depAlias, depPin] of Object.entries(kitPins)) {
492
500
  if (copied.has(depAlias) || pins[depAlias])
493
501
  continue;
494
- const depKit = depAlias.startsWith(`${KIT_AUTHOR}.`)
495
- ? depAlias.slice(KIT_AUTHOR.length + 1)
496
- : depAlias;
502
+ const depKit = kitFromAlias(depAlias);
497
503
  const depKitDir = path.join(getKitsDir(), depKit);
498
504
  if (fs.existsSync(depKitDir) && fs.statSync(depKitDir).isDirectory()) {
499
505
  copyKitImport(projectDir, depKitDir, depKit, depAlias, pins, copied);
@@ -503,6 +509,28 @@ function copyKitImport(projectDir, kitDir, kit, alias, pins, copied) {
503
509
  }
504
510
  }
505
511
  }
512
+ // `add-import <kit>`: the same copy `init --kit` makes, into an existing deck
513
+ // that does not have the kit yet (the caller refuses one that does). Kits the
514
+ // deck already pins are left as they are, which is what keeps a bare deck's
515
+ // base import from being copied over itself.
516
+ export function importShippedKit(deckDir, kit) {
517
+ const alias = shippedKitAlias(kit);
518
+ const configPath = path.join(deckDir, 'castle.json');
519
+ const pins = { ...(readJsonFile(configPath)?.imports ?? {}) };
520
+ const copied = new Map();
521
+ copyKitImport(deckDir, path.join(getKitsDir(), kit), kit, alias, pins, copied);
522
+ const pin = pins[alias];
523
+ writeJsonFile(configPath, { ...readJsonFile(configPath), imports: pins });
524
+ for (const copiedAlias of copied.keys()) {
525
+ lockImportTree(path.join(deckDir, IMPORTS_DIR, copiedAlias));
526
+ }
527
+ return {
528
+ alias,
529
+ deckId: typeof pin.deckId === 'string' ? pin.deckId : kit,
530
+ replaced: false,
531
+ transitive: [...copied.keys()].filter((a) => a !== alias),
532
+ };
533
+ }
506
534
  // The kit's server block, with `main` pointed at the copy under `imports/`. The
507
535
  // kit names its own file, which is right when the kit itself is served and wrong
508
536
  // in a deck, where that file only exists inside the import.
@@ -517,6 +545,29 @@ function serverForDeck(server, kitDir, alias) {
517
545
  }
518
546
  return { ...block, main: `${IMPORTS_DIR}/${alias}/${main}` };
519
547
  }
548
+ // The deck's own castle.json takes the kit's editor config (panel layout, file
549
+ // filters) as a starting point -- it is the deck's to edit from here -- and the
550
+ // kit's server block. Every other key the deck already has is kept. Shared by
551
+ // `init --kit` and `add-import` adopting a kit onto a bare deck, so the two
552
+ // cannot write different decks.
553
+ //
554
+ // `fileTypes` is deliberately NOT copied. It is the kit's own vocabulary, and
555
+ // the deck resolves it live from every import's castle.json (see
556
+ // editorConfig.resolveFileTypes) -- so the kit keeps owning it, a kit fix
557
+ // reaches the deck like any other, and a kit imported LATER contributes its
558
+ // types too, which a copy taken at scaffold time never could.
559
+ export function adoptKitConfig(deckDir, kitDir, alias) {
560
+ const kitConfig = readJsonFile(path.join(kitDir, 'castle.json')) ?? {};
561
+ const configPath = path.join(deckDir, 'castle.json');
562
+ const { editor, server, ...rest } = readJsonFile(configPath) ?? {};
563
+ const nextEditor = kitConfig.editor ? deckEditorBlock(kitConfig.editor) : editor;
564
+ const nextServer = kitConfig.server ? serverForDeck(kitConfig.server, kitDir, alias) : server;
565
+ writeJsonFile(configPath, {
566
+ ...(nextEditor !== undefined ? { editor: nextEditor } : {}),
567
+ ...(nextServer !== undefined ? { server: nextServer } : {}),
568
+ ...rest,
569
+ });
570
+ }
520
571
  function scaffoldFromKitImport(kit, projectDir) {
521
572
  const kitDir = requireKitDir(kit);
522
573
  // Qualified like any other import (`<author>.<deck>`), and qualified NOW even
@@ -524,7 +575,7 @@ function scaffoldFromKitImport(kit, projectDir) {
524
575
  // writes, so it can't change later without rewriting them. Publishing the
525
576
  // kits under the castle account turns the pin into a deckId; the name it is
526
577
  // already known by stays put.
527
- const alias = `${KIT_AUTHOR}.${kit}`;
578
+ const alias = shippedKitAlias(kit);
528
579
  const pins = {};
529
580
  const copied = new Map();
530
581
  copyKitImport(projectDir, kitDir, kit, alias, pins, copied);
@@ -533,20 +584,8 @@ function scaffoldFromKitImport(kit, projectDir) {
533
584
  writeDeckIndexHtml(projectDir, alias, title, deckMainFile(kitDir));
534
585
  writeStarterScene(projectDir, kitDir, alias);
535
586
  writeStarterTheme(projectDir, kitDir);
536
- // The deck's own castle.json: the kit's editor config (panel layout, file
537
- // filters) as a starting point -- it is the deck's to edit from here -- plus
538
- // the import pin.
539
- //
540
- // `fileTypes` is deliberately NOT copied. It is the kit's own vocabulary, and
541
- // the deck resolves it live from every import's castle.json (see
542
- // editorConfig.resolveFileTypes) -- so the kit keeps owning it, a kit fix
543
- // reaches the deck like any other, and a kit imported LATER contributes its
544
- // types too, which a copy taken at scaffold time never could.
545
- writeJsonFile(path.join(projectDir, 'castle.json'), {
546
- ...(kitConfig.editor ? { editor: deckEditorBlock(kitConfig.editor) } : {}),
547
- ...(kitConfig.server ? { server: serverForDeck(kitConfig.server, kitDir, alias) } : {}),
548
- imports: pins,
549
- });
587
+ writeJsonFile(path.join(projectDir, 'castle.json'), { imports: pins });
588
+ adoptKitConfig(projectDir, kitDir, alias);
550
589
  // The kit's code runs from THIS deck's node_modules, so its dependencies are
551
590
  // declared here (see syncImportDependencies, which does the same for imports
552
591
  // added later). Every copied kit contributes, the scaffolding kit first, so
@@ -570,7 +609,7 @@ function scaffoldFromKitImport(kit, projectDir) {
570
609
  name: path.basename(projectDir),
571
610
  private: true,
572
611
  type: 'module',
573
- scripts: makeKitDeckScripts(kitDir, alias, cliCommand),
612
+ scripts: makeKitDeckScripts(kitDir, alias, cliCommand, copied),
574
613
  dependencies,
575
614
  });
576
615
  fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), makeImportedKitClaudeMd(alias, !!kitConfig.server));
@@ -0,0 +1,13 @@
1
+ export declare const KIT_AUTHOR = "castle";
2
+ export declare function shippedKitAlias(kit: string): string;
3
+ export declare function kitFromAlias(alias: string): string;
4
+ export interface ShippedKit {
5
+ name: string;
6
+ alias: string;
7
+ description: string;
8
+ fileTypeLabels: string[];
9
+ }
10
+ export declare function shippedFrameworkKit(ref: string, kitsDir?: string): string | null;
11
+ export declare function listShippedKits(kitsDir?: string): ShippedKit[];
12
+ export declare function kitCatalogLine(kit: ShippedKit): string;
13
+ export declare function kitCatalogLines(deckDir: string, kitsDir?: string): string[] | undefined;
@@ -0,0 +1,111 @@
1
+ import * as fs from 'fs';
2
+ import * as path from 'path';
3
+ import { IMPORTS_DIR } from './castleJson.js';
4
+ import { getKitsDir } from './localPaths.js';
5
+ // The account the first-party kits are (to be) published under, so a kit
6
+ // imported from the CLI's copy is named the same as one fetched from the server.
7
+ export const KIT_AUTHOR = 'castle';
8
+ export function shippedKitAlias(kit) {
9
+ return `${KIT_AUTHOR}.${kit}`;
10
+ }
11
+ export function kitFromAlias(alias) {
12
+ return alias.startsWith(`${KIT_AUTHOR}.`) ? alias.slice(KIT_AUTHOR.length + 1) : alias;
13
+ }
14
+ function readKitConfig(kitsDir, kit) {
15
+ try {
16
+ return JSON.parse(fs.readFileSync(path.join(kitsDir, kit, 'castle.json'), 'utf8'));
17
+ }
18
+ catch {
19
+ return null;
20
+ }
21
+ }
22
+ function nonEmpty(value) {
23
+ return typeof value === 'string' && value.trim() ? value.trim() : null;
24
+ }
25
+ function isFramework(config) {
26
+ return !!config && nonEmpty(config.main) !== null;
27
+ }
28
+ export function shippedFrameworkKit(ref, kitsDir = getKitsDir()) {
29
+ const kit = kitFromAlias(ref.trim());
30
+ if (!kit || kit.includes('/') || kit.includes('\\') || kit.startsWith('.'))
31
+ return null;
32
+ return isFramework(readKitConfig(kitsDir, kit)) ? kit : null;
33
+ }
34
+ // Only framework imports are followed: the library kits under them (base above
35
+ // all) contribute types every deck already has, which is not what a kit offers.
36
+ function fileTypeLabels(kitsDir, kit, seen) {
37
+ if (seen.has(kit))
38
+ return [];
39
+ seen.add(kit);
40
+ const config = readKitConfig(kitsDir, kit);
41
+ if (!isFramework(config))
42
+ return [];
43
+ const labels = (config?.editor?.fileTypes ?? [])
44
+ .filter((type) => !type.unsupported)
45
+ .map((type) => nonEmpty(type.label))
46
+ .filter((label) => label !== null);
47
+ for (const alias of Object.keys(config?.imports ?? {})) {
48
+ labels.push(...fileTypeLabels(kitsDir, kitFromAlias(alias), seen));
49
+ }
50
+ return [...new Set(labels)];
51
+ }
52
+ export function listShippedKits(kitsDir = getKitsDir()) {
53
+ let names;
54
+ try {
55
+ names = fs
56
+ .readdirSync(kitsDir, { withFileTypes: true })
57
+ .filter((entry) => entry.isDirectory())
58
+ .map((entry) => entry.name);
59
+ }
60
+ catch {
61
+ return [];
62
+ }
63
+ const kits = [];
64
+ for (const name of names.sort()) {
65
+ const config = readKitConfig(kitsDir, name);
66
+ const description = nonEmpty(config?.description);
67
+ if (!isFramework(config) || !description)
68
+ continue;
69
+ kits.push({
70
+ name,
71
+ alias: shippedKitAlias(name),
72
+ description,
73
+ fileTypeLabels: fileTypeLabels(kitsDir, name, new Set()),
74
+ });
75
+ }
76
+ return kits;
77
+ }
78
+ function joinWithAnd(items) {
79
+ if (items.length <= 1)
80
+ return items.join('');
81
+ return `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
82
+ }
83
+ export function kitCatalogLine(kit) {
84
+ const opens = kit.fileTypeLabels.length ? ` Opens ${joinWithAnd(kit.fileTypeLabels)} files.` : '';
85
+ return `- ${kit.name}: ${kit.description}${opens} Import it with: castle-web add-import ${kit.name}`;
86
+ }
87
+ // What the router may offer a deck that runs no kit. A deck that already
88
+ // imports one -- shipped, fetched or its author's own -- gets nothing: its guide
89
+ // is that kit's, and offering a second framework on top of it would be offering
90
+ // to replace the first.
91
+ export function kitCatalogLines(deckDir, kitsDir = getKitsDir()) {
92
+ const kits = listShippedKits(kitsDir);
93
+ if (kits.length === 0)
94
+ return undefined;
95
+ let imports = {};
96
+ try {
97
+ imports = JSON.parse(fs.readFileSync(path.join(deckDir, 'castle.json'), 'utf8')).imports ?? {};
98
+ }
99
+ catch {
100
+ imports = {};
101
+ }
102
+ const aliases = Object.keys(imports);
103
+ // The shipped-alias check also covers a pin whose tree is not on disk yet
104
+ // (a fresh clone before the serve restores imports/).
105
+ if (kits.some((kit) => aliases.includes(kit.alias)))
106
+ return undefined;
107
+ if (aliases.some((alias) => isFramework(readKitConfig(path.join(deckDir, IMPORTS_DIR), alias)))) {
108
+ return undefined;
109
+ }
110
+ return kits.map(kitCatalogLine);
111
+ }
@@ -53,6 +53,7 @@ const MODE_BULLET = "- Unprompted, an editor is an offer, never a build: when th
53
53
  // list computed per deck.
54
54
  export function everyDeckBullets(deckDir) {
55
55
  return [
56
+ "- **Castle's Parameters panel is where a creator tunes the deck.** It is one of Castle's own panels, beside Play and Files: it shows the `PARAMS` values of every file that has one as live fields the creator drags while the deck runs, which is how they change the way it plays without putting a cursor in code.",
56
57
  `- **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.`,
57
58
  "- 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).",
58
59
  "- 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.",
@@ -157,7 +158,7 @@ export function quickReferenceFor(deckDir, quickReference, role) {
157
158
  const COMMON_SECTIONS = `## Imports are read-only
158
159
 
159
160
  - **\`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.
160
- - **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.
161
+ - **Change an import through the CLI, never the filesystem.** \`castle-web add-import <deckIdOrUrl>\` adds one (or one of the kits the CLI ships, by its name) 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.
161
162
  - **\`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.
162
163
  - **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.
163
164
  - **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.
@@ -264,7 +265,11 @@ export function platformGuide(deckDir) {
264
265
 
265
266
  ## Formats, reloading, editors
266
267
 
267
- ${everyDeckBullets(deckDir).join('\n')}
268
+ ${everyDeckBullets(deckDir).filter((b) => !b.includes('PARAMS')).join('\n')}
269
+
270
+ ## Tunable values and the Parameters panel
271
+
272
+ ${everyDeckBullets(deckDir).filter((b) => b.includes('PARAMS')).join('\n')}
268
273
  `;
269
274
  }
270
275
  function platformDoc(deckDir) {
package/dist/serve.js CHANGED
@@ -20,7 +20,7 @@ import { migrateClaudeMd, PLATFORM_DOC_REL, writePlatformDocs } from './platform
20
20
  import { FORKS_DIR, ownForkFile, splitImportRel } from './forks.js';
21
21
  import * as config from './config.js';
22
22
  import { graphql as castleGraphql } from './api.js';
23
- import { executeCommand } from './castle-host/host.js';
23
+ import { executeCommand, fetchOracleStream } from './castle-host/host.js';
24
24
  import { ServeSecurity } from './serveSecurity.js';
25
25
  import { atomicWriteFileSync } from './atomicFile.js';
26
26
  import { isSameOriginUpgrade } from './wsOrigin.js';
@@ -726,8 +726,33 @@ async function devHostContext(projectDir) {
726
726
  username: me.username,
727
727
  };
728
728
  }
729
+ // Agent.chat's route to the oracle, authed with the CLI's login token.
730
+ const oracleStream = fetchOracleStream(() => config.getToken());
731
+ // Commands in flight on each socket, so a deck's cancel or a closed socket can
732
+ // abort a streaming one.
733
+ const commandAborts = new WeakMap();
734
+ function abortCommand(ws, requestId) {
735
+ commandAborts.get(ws)?.get(requestId)?.abort();
736
+ }
737
+ function abortSocketCommands(ws) {
738
+ for (const controller of commandAborts.get(ws)?.values() ?? []) {
739
+ controller.abort();
740
+ }
741
+ commandAborts.delete(ws);
742
+ }
729
743
  async function handleCastleCommand(ws, projectDir, broadcast, multiplayer, multiplayerUrl, playSessionSlot, requestId, command, params) {
744
+ // Registered before the first await, so a cancel that arrives while the
745
+ // context is being fetched still finds it.
746
+ const aborts = commandAborts.get(ws) ?? new Map();
747
+ commandAborts.set(ws, aborts);
748
+ const controller = new AbortController();
749
+ aborts.set(requestId, controller);
730
750
  const ctx = await devHostContext(projectDir);
751
+ const onStream = (event) => {
752
+ if (ws.readyState === WebSocket.OPEN) {
753
+ ws.send(JSON.stringify({ type: 'castle_command_stream', castleSdk: 1, requestId, stream: event }));
754
+ }
755
+ };
731
756
  // The dev server services data commands via GraphQL but supplies no
732
757
  // platformHandler, so platform/capability commands (e.g. passes.purchase)
733
758
  // resolve to their normalized "unavailable" outcome. The leaderboard UI it
@@ -735,6 +760,7 @@ async function handleCastleCommand(ws, projectDir, broadcast, multiplayer, multi
735
760
  // shell, which mounts the same panel the app and the website use.
736
761
  const result = await executeCommand(ctx, command, params, {
737
762
  graphqlFetch: castleGraphql,
763
+ oracleStream,
738
764
  showLeaderboard: (payload) => broadcast({ type: 'castle_leaderboard_show', payload }),
739
765
  getMultiplayerSession: () => {
740
766
  if (!multiplayer || !multiplayerUrl) {
@@ -755,7 +781,8 @@ async function handleCastleCommand(ws, projectDir, broadcast, multiplayer, multi
755
781
  ...(playSessionSlot ? { devReconnectScope: playSessionSlot } : {}),
756
782
  });
757
783
  },
758
- });
784
+ }, { onStream, signal: controller.signal });
785
+ aborts.delete(requestId);
759
786
  if (ws.readyState === WebSocket.OPEN) {
760
787
  ws.send(JSON.stringify({ type: 'castle_command_response', castleSdk: 1, requestId, ...result }));
761
788
  }
@@ -806,6 +833,7 @@ const BRIDGED_CONTENT_MESSAGES = new Set([
806
833
  'write_file',
807
834
  'rename_file',
808
835
  'castle_command',
836
+ 'castle_command_cancel',
809
837
  ]);
810
838
  const LEGACY_CONTENT_MESSAGES = new Set([...BRIDGED_CONTENT_MESSAGES, 'ping']);
811
839
  function readServeJson(projectDir) {
@@ -1659,6 +1687,10 @@ function startWSServer(projectDir, logFile, screenshotsDir, viteHolder, security
1659
1687
  // it runs the command via the SDK host executor with the CLI's login
1660
1688
  // token, then replies to just this socket. See castle-web-sdk's
1661
1689
  // transport.ts (local channel) + host.ts.
1690
+ if (msg.type === 'castle_command_cancel' && typeof msg.requestId === 'string') {
1691
+ abortCommand(ws, msg.requestId);
1692
+ return;
1693
+ }
1662
1694
  if (msg.type === 'castle_command' && typeof msg.requestId === 'string') {
1663
1695
  const commandMultiplayerUrl = bridgeRole
1664
1696
  ? devMultiplayerUrlFromOrigin(bridgeContentOrigin ??
@@ -1673,6 +1705,7 @@ function startWSServer(projectDir, logFile, screenshotsDir, viteHolder, security
1673
1705
  });
1674
1706
  ws.on('close', () => {
1675
1707
  clients.delete(ws);
1708
+ abortSocketCommands(ws);
1676
1709
  // Drop any in-flight requests this socket issued so the map can't leak.
1677
1710
  for (const [id, pending] of requestOrigins) {
1678
1711
  if (pending.origin === ws)