castle-web-cli 0.4.142 → 0.4.144
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 +7 -2
- package/dist/agent.js +11 -9
- package/dist/imports.js +26 -1
- package/dist/init.d.ts +4 -0
- package/dist/init.js +62 -25
- package/dist/install.js +4 -0
- package/dist/platformDoc.d.ts +12 -0
- package/dist/platformDoc.js +236 -0
- package/dist/serve.d.ts +1 -0
- package/dist/serve.js +27 -3
- package/kits/blank/CLAUDE.md +198 -0
- package/kits/blank/castle.json +8 -0
- package/kits/blank/index.html +42 -0
- package/kits/blank/package-lock.json +10 -0
- package/kits/blank/package.json +9 -0
- package/kits/physics-2d/CLAUDE.md +0 -4
- package/kits/physics-2d/behaviors/Sprite.jsx +2 -4
- package/kits/physics-3d/CLAUDE.md +2 -3
- package/package.json +1 -1
- package/dist/commonInstructions.d.ts +0 -1
- package/dist/commonInstructions.js +0 -26
package/dist/agent-prompts.d.ts
CHANGED
|
@@ -73,6 +73,7 @@ export declare function applyPlanOps(fileText: string, ops: PlanOp[], sources?:
|
|
|
73
73
|
export declare function renderPlanDigest(plan: RouterPlanOpts, tasks: PromptTask[]): string;
|
|
74
74
|
export declare function planOpenQuestionLines(fileText: string): string[];
|
|
75
75
|
export declare function renderTaskPlanSlice(fileText: string, item: string | undefined, finishedWork?: PlanFinishedWork[]): string;
|
|
76
|
+
export declare const NO_DECK_DOCS = "This deck has no CLAUDE.md / AGENTS.md quick reference. There is no documentation to read -- do not search for one (CLAUDE.md, README, **/*.md, etc.).";
|
|
76
77
|
export declare function buildRouterPrompt(opts: {
|
|
77
78
|
deckLabel: string;
|
|
78
79
|
quickReference?: string;
|
package/dist/agent-prompts.js
CHANGED
|
@@ -790,6 +790,11 @@ function renderTasks(tasks, showItems) {
|
|
|
790
790
|
})
|
|
791
791
|
.join("\n");
|
|
792
792
|
}
|
|
793
|
+
// Said outright rather than left out: a router/task agent on a deck with no
|
|
794
|
+
// quick reference otherwise cannot tell "no docs exist" from "the section was
|
|
795
|
+
// not included" and burns its first turns hunting for CLAUDE.md. Exported so
|
|
796
|
+
// the platform block (platformDoc.ts) can keep the sentence after itself.
|
|
797
|
+
export const NO_DECK_DOCS = "This deck has no CLAUDE.md / AGENTS.md quick reference. There is no documentation to read -- do not search for one (CLAUDE.md, README, **/*.md, etc.).";
|
|
793
798
|
export function buildRouterPrompt(opts) {
|
|
794
799
|
// Making the ABSENCE explicit, not just omitting the section, matters: a
|
|
795
800
|
// router on a bare/greenfield deck otherwise has no way to tell "no docs
|
|
@@ -799,7 +804,7 @@ export function buildRouterPrompt(opts) {
|
|
|
799
804
|
// 8-file deck with zero markdown files).
|
|
800
805
|
const quickReference = opts.quickReference?.trim()
|
|
801
806
|
? `\n\n== how this deck works ==\n${opts.quickReference.trim()}`
|
|
802
|
-
:
|
|
807
|
+
: `\n\n== how this deck works ==\n${NO_DECK_DOCS}`;
|
|
803
808
|
const deckFiles = opts.deckTree?.trim()
|
|
804
809
|
? `\n\n== deck files ==\n${opts.deckTree.trim()}`
|
|
805
810
|
: "";
|
|
@@ -869,7 +874,7 @@ export function buildTaskPrompt(opts) {
|
|
|
869
874
|
// does if it has to discover the absence itself via a failed read/grep.
|
|
870
875
|
const quickReference = opts.quickReference?.trim()
|
|
871
876
|
? `\n\nHow this deck works (from its docs -- read the full CLAUDE.md / AGENTS.md only when you need detail beyond this):\n\n${opts.quickReference.trim()}\n`
|
|
872
|
-
:
|
|
877
|
+
: `\n\n${NO_DECK_DOCS}\n`;
|
|
873
878
|
const layout = opts.deckTree?.trim()
|
|
874
879
|
? `\n\nDeck files (snapshot at task start; parallel sibling tasks may create files named in your prompt that are absent here):\n\n${opts.deckTree.trim()}\n`
|
|
875
880
|
: "";
|
package/dist/agent.js
CHANGED
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
// runs with --mode ask (read-only at the CLI level); task agents run with
|
|
16
16
|
// --force. Claude support can slot in later behind runAgentCli.
|
|
17
17
|
import { execFileSync, spawn } from 'child_process';
|
|
18
|
+
import { quickReferenceFor } from './platformDoc.js';
|
|
18
19
|
import { IMPORTS_DIR } from './imports.js';
|
|
19
20
|
import { isSameOriginUpgrade } from './wsOrigin.js';
|
|
20
21
|
import * as fs from 'fs';
|
|
@@ -641,13 +642,11 @@ function extractDirectives(full) {
|
|
|
641
642
|
};
|
|
642
643
|
}
|
|
643
644
|
const planSessions = new Map();
|
|
644
|
-
// What a deck that says nothing gets.
|
|
645
|
-
//
|
|
646
|
-
//
|
|
647
|
-
// feature to someone outside the rollout. The cloud editor sets it per user
|
|
648
|
-
// from a feature gate; see serveOnPort in castle-www's cloudSandbox.ts.
|
|
645
|
+
// What a deck that says nothing gets. On unless the serve was explicitly told
|
|
646
|
+
// otherwise -- `CASTLE_AGENT_PLAN=off` is what the agent-qa harness uses to keep
|
|
647
|
+
// the plan doc out of scenarios that aren't testing it.
|
|
649
648
|
function planDefault() {
|
|
650
|
-
return process.env.CASTLE_AGENT_PLAN
|
|
649
|
+
return process.env.CASTLE_AGENT_PLAN !== 'off';
|
|
651
650
|
}
|
|
652
651
|
function planSession(deckDir) {
|
|
653
652
|
const existing = planSessions.get(deckDir);
|
|
@@ -1355,7 +1354,10 @@ function readClaudeSectionWithImports(deckDir, section) {
|
|
|
1355
1354
|
const text = readClaudeSection(path.join(deckDir, IMPORTS_DIR, alias), section);
|
|
1356
1355
|
if (!text)
|
|
1357
1356
|
continue;
|
|
1358
|
-
|
|
1357
|
+
// "not the entry" only distinguishes an import from the one that IS the
|
|
1358
|
+
// entry. A deck running its own code has no entry import, and every import
|
|
1359
|
+
// it has is simply an import.
|
|
1360
|
+
const role = alias === entry ? 'this deck runs on it' : entry ? 'imported, not the entry' : 'imported';
|
|
1359
1361
|
parts.push(`### from the ${alias} kit (${role})\n\n${text}`);
|
|
1360
1362
|
}
|
|
1361
1363
|
return parts.join('\n\n');
|
|
@@ -2377,7 +2379,7 @@ async function runTaskAgentIn(ctx, task) {
|
|
|
2377
2379
|
? { maxEntries: DECK_TREE_SLIM_MAX_ENTRIES, perDir: DECK_TREE_SLIM_PER_DIR }
|
|
2378
2380
|
: undefined),
|
|
2379
2381
|
deckContents,
|
|
2380
|
-
quickReference: ctx.quickReference,
|
|
2382
|
+
quickReference: quickReferenceFor(ctx.deckDir, ctx.quickReference, ctx.backend),
|
|
2381
2383
|
plan: taskPlanOpts(ctx.deckDir, task.item, ctx.finishedWork),
|
|
2382
2384
|
siblings: ctx.siblings,
|
|
2383
2385
|
});
|
|
@@ -3103,7 +3105,7 @@ function routerTurnPrompt(ctx, instruction, selfMessageId, plan) {
|
|
|
3103
3105
|
const isSmith = ctx.backend() === 'smith';
|
|
3104
3106
|
return buildRouterPrompt({
|
|
3105
3107
|
deckLabel: ctx.deckLabel,
|
|
3106
|
-
quickReference: ctx.quickReference,
|
|
3108
|
+
quickReference: quickReferenceFor(ctx.deckDir, ctx.quickReference, ctx.backend()),
|
|
3107
3109
|
deckTree: buildDeckTree(ctx.deckDir, isSmith
|
|
3108
3110
|
? { maxEntries: DECK_TREE_SLIM_MAX_ENTRIES, perDir: DECK_TREE_SLIM_PER_DIR }
|
|
3109
3111
|
: undefined),
|
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 { writePlatformDocs } from './platformDoc.js';
|
|
8
9
|
import { ensureVisibleGlob, IMPORTS_DIR, readCastleJson as tryReadCastleJson, readCastleJsonOrThrow as readCastleJson, } from './castleJson.js';
|
|
9
10
|
// Adding another deck as a dependency (`castle-web add-import`; removing one is a
|
|
10
11
|
// later command). Deliberately NOT `get-deck`: that one
|
|
@@ -380,6 +381,23 @@ function backupImport(deckDir, alias) {
|
|
|
380
381
|
fs.writeFileSync(path.join(dest, '.castle-import-pin.json'), JSON.stringify(pin, null, 2), 'utf-8');
|
|
381
382
|
}
|
|
382
383
|
}
|
|
384
|
+
// The docs-only kit a bare scaffold imports for its agent guide. A deck that
|
|
385
|
+
// adopts a real kit no longer has anything to say: leaving it would put two
|
|
386
|
+
// quick references in front of the agent every turn, one of them opening "No
|
|
387
|
+
// kit: nothing in this deck comes from a framework" about a deck that has one.
|
|
388
|
+
function dropBareDocsImport(deckDir, alias) {
|
|
389
|
+
const dir = path.join(deckDir, IMPORTS_DIR, alias);
|
|
390
|
+
if (fs.existsSync(dir)) {
|
|
391
|
+
unlockImportTree(dir);
|
|
392
|
+
fs.rmSync(dir, { recursive: true, force: true });
|
|
393
|
+
}
|
|
394
|
+
const existing = readCastleJson(deckDir);
|
|
395
|
+
if (!existing?.imports?.[alias])
|
|
396
|
+
return;
|
|
397
|
+
const imports = { ...existing.imports };
|
|
398
|
+
delete imports[alias];
|
|
399
|
+
fs.writeFileSync(path.join(deckDir, 'castle.json'), JSON.stringify({ ...existing, imports }, null, 2) + '\n', 'utf-8');
|
|
400
|
+
}
|
|
383
401
|
async function placeImport(deckDir, alias, deckId, source, via) {
|
|
384
402
|
const destDir = path.join(deckDir, IMPORTS_DIR, alias);
|
|
385
403
|
const replaced = fs.existsSync(destDir);
|
|
@@ -493,10 +511,12 @@ export async function addImportTo(dir, options = {}) {
|
|
|
493
511
|
const declaredMain = tryReadCastleJson(importDir)?.main;
|
|
494
512
|
let adoptedMain = null;
|
|
495
513
|
if (typeof declaredMain === 'string' && declaredMain.trim()) {
|
|
496
|
-
const { isPristineBareDeck, adoptImportEntry, writeStarterScene, writeStarterTheme } = await import('./init.js');
|
|
514
|
+
const { isPristineBareDeck, adoptImportEntry, writeStarterScene, writeStarterTheme, retargetBareClaudeMd, BARE_DOCS_ALIAS, } = await import('./init.js');
|
|
497
515
|
if (isPristineBareDeck(targetDir)) {
|
|
498
516
|
adoptImportEntry(targetDir, alias, declaredMain.trim());
|
|
499
517
|
adoptedMain = declaredMain.trim();
|
|
518
|
+
retargetBareClaudeMd(targetDir, alias);
|
|
519
|
+
dropBareDocsImport(targetDir, BARE_DOCS_ALIAS);
|
|
500
520
|
// A kit's runtime with no scene to run is a blank screen, and the agent
|
|
501
521
|
// has nothing to edit. Give the deck the kit's own starter, same as
|
|
502
522
|
// `init --kit`. Only when the deck has no scenes -- never overwrite.
|
|
@@ -535,6 +555,9 @@ export async function addImportTo(dir, options = {}) {
|
|
|
535
555
|
console.warn(`Imported ${alias}, but installing its dependencies failed -- run \`castle-web install\`. ${e instanceof Error ? e.message : String(e)}`);
|
|
536
556
|
}
|
|
537
557
|
}
|
|
558
|
+
// The platform guide's media list names the deck's declared types, which
|
|
559
|
+
// this import may have just changed.
|
|
560
|
+
writePlatformDocs(targetDir);
|
|
538
561
|
const trimmedMain = typeof declaredMain === 'string' && declaredMain.trim() ? declaredMain.trim() : null;
|
|
539
562
|
const offersMain = trimmedMain && !adoptedMain ? trimmedMain : null;
|
|
540
563
|
return { deckId, alias, replaced, transitive, dependencies, adoptedMain, offersMain };
|
|
@@ -712,6 +735,7 @@ export async function updateImport(dir, options = {}) {
|
|
|
712
735
|
for (const alias of aliases)
|
|
713
736
|
revertImport(deckDir, alias);
|
|
714
737
|
syncImportDependencies(deckDir);
|
|
738
|
+
writePlatformDocs(deckDir);
|
|
715
739
|
return;
|
|
716
740
|
}
|
|
717
741
|
let changed = false;
|
|
@@ -749,6 +773,7 @@ export async function updateImport(dir, options = {}) {
|
|
|
749
773
|
const added = syncImportDependencies(deckDir);
|
|
750
774
|
for (const dep of added)
|
|
751
775
|
console.log(`Added dependency ${dep}`);
|
|
776
|
+
writePlatformDocs(deckDir);
|
|
752
777
|
console.log('Play the deck to check the update before saving; `--revert` puts the old version back.');
|
|
753
778
|
}
|
|
754
779
|
// Restore the copy taken when this import was last replaced.
|
package/dist/init.d.ts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
export declare const BARE_DOCS_KIT = "blank";
|
|
2
|
+
export declare const BARE_DOCS_ALIAS = "castle.blank";
|
|
1
3
|
export declare function resolveScaffoldRefs(): {
|
|
2
4
|
workspaceMode: boolean;
|
|
3
5
|
sdkRef: string;
|
|
@@ -5,11 +7,13 @@ export declare function resolveScaffoldRefs(): {
|
|
|
5
7
|
cliDistAbs: string | null;
|
|
6
8
|
sdkPathPosix: string | null;
|
|
7
9
|
};
|
|
10
|
+
export declare function ensureAgentsSymlink(projectDir: string): void;
|
|
8
11
|
export declare function isPristineBareDeck(dir: string): boolean;
|
|
9
12
|
export declare function adoptImportEntry(deckDir: string, alias: string, mainFile: string): void;
|
|
10
13
|
export declare function getCliVersion(): string;
|
|
11
14
|
export declare function writeStarterScene(projectDir: string, kitDir: string, alias: string): void;
|
|
12
15
|
export declare function writeStarterTheme(projectDir: string, kitDir: string): void;
|
|
16
|
+
export declare function retargetBareClaudeMd(deckDir: string, alias: string): void;
|
|
13
17
|
export declare function init(dir: string, opts?: {
|
|
14
18
|
kit?: string;
|
|
15
19
|
serve?: boolean;
|
package/dist/init.js
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
import * as fs from 'fs';
|
|
2
2
|
import * as path from 'path';
|
|
3
|
-
import {
|
|
3
|
+
import { CLAUDE_MD_PLATFORM_SECTION } from './platformDoc.js';
|
|
4
4
|
import { installDeps } from './install.js';
|
|
5
5
|
import { deckMainFile, deckStarterScene } from './castleJson.js';
|
|
6
6
|
import { addImportTo, IMPORTS_DIR, lockImportTree, restoreMissingImports, syncImportDependencies, } from './imports.js';
|
|
7
7
|
import { discardParentSource, fetchParentSource, unpackParentSource, writeRemixIdentity, } from './remix.js';
|
|
8
|
-
import { getCliEntryPath, getKitsDir,
|
|
8
|
+
import { getCliEntryPath, getKitsDir, getSdkPackagePath, toPosixPath, } from './localPaths.js';
|
|
9
9
|
import { serve } from './serve.js';
|
|
10
10
|
import { createVersion } from './versions.js';
|
|
11
11
|
const INDEX_HTML = `<!DOCTYPE html>
|
|
@@ -36,6 +36,13 @@ card.appendChild(el);
|
|
|
36
36
|
// Default kit imported by `init` when no --kit is given. `none`/`bare` skip the
|
|
37
37
|
// kit and produce the minimal index.html + game.js stub above.
|
|
38
38
|
const DEFAULT_KIT = 'physics-2d';
|
|
39
|
+
// A kit-less deck still imports ONE kit: a docs-only deck holding the guide to
|
|
40
|
+
// building without a framework. It is imported rather than written into the
|
|
41
|
+
// deck's own CLAUDE.md so it behaves like every other kit's guide -- the quick
|
|
42
|
+
// reference reaches the agent every turn, the rest is read on demand, and the
|
|
43
|
+
// text ships to existing decks via `autoUpdateWhenImported` instead of waiting
|
|
44
|
+
// for whatever CLI release the deck was scaffolded by.
|
|
45
|
+
export const BARE_DOCS_KIT = 'blank';
|
|
39
46
|
// Registry version of castle-web-sdk to inject when scaffolding from a
|
|
40
47
|
// globally-installed castle-web (not from inside the workspace). Bumped
|
|
41
48
|
// alongside cli/sdk version bumps.
|
|
@@ -43,6 +50,7 @@ const PUBLISHED_SDK_VERSION = '0.4.17';
|
|
|
43
50
|
// The account the first-party kits are (to be) published under, so a kit
|
|
44
51
|
// imported from the CLI's copy is named the same as one fetched from the server.
|
|
45
52
|
const KIT_AUTHOR = 'castle';
|
|
53
|
+
export const BARE_DOCS_ALIAS = `${KIT_AUTHOR}.${BARE_DOCS_KIT}`;
|
|
46
54
|
// Never copied into a deck's import: build/dependency junk.
|
|
47
55
|
const KIT_COPY_EXCLUDE = new Set(['node_modules', '.castle', 'dist', '.git']);
|
|
48
56
|
// The bare (`--kit none`) deck's default editor config: just the Files panel and
|
|
@@ -77,28 +85,15 @@ export function resolveScaffoldRefs() {
|
|
|
77
85
|
sdkPathPosix,
|
|
78
86
|
};
|
|
79
87
|
}
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
const repoRoot = getRepoRoot();
|
|
85
|
-
const upstream = path.join(repoRoot, 'CLAUDE.md');
|
|
86
|
-
try {
|
|
87
|
-
return fs.readFileSync(upstream, 'utf8').trimEnd() + '\n';
|
|
88
|
-
}
|
|
89
|
-
catch {
|
|
90
|
-
return `# Castle Experimental Web\n\nSee https://github.com/castle-xyz/castle-experimental-web for the agent guide.\n`;
|
|
91
|
-
}
|
|
92
|
-
}
|
|
93
|
-
// Append the cli-owned common guidance to the deck's CLAUDE.md. Runs after
|
|
94
|
-
// the kit's (or bare) CLAUDE.md is written; the AGENTS.md symlink picks the
|
|
95
|
-
// appended content up for free.
|
|
96
|
-
function appendCommonInstructions(projectDir) {
|
|
88
|
+
// Append the platform section -- the @import of the serve-written platform
|
|
89
|
+
// guide (platformDoc.ts) -- after the kit's (or bare) pointer is written. The
|
|
90
|
+
// AGENTS.md symlink picks it up for free.
|
|
91
|
+
function appendPlatformSection(projectDir) {
|
|
97
92
|
const claudePath = path.join(projectDir, 'CLAUDE.md');
|
|
98
93
|
const existing = fs.existsSync(claudePath)
|
|
99
94
|
? fs.readFileSync(claudePath, 'utf8').trimEnd() + '\n\n'
|
|
100
95
|
: '';
|
|
101
|
-
fs.writeFileSync(claudePath, existing +
|
|
96
|
+
fs.writeFileSync(claudePath, existing + CLAUDE_MD_PLATFORM_SECTION);
|
|
102
97
|
}
|
|
103
98
|
function tryMakeAgentsSymlink(agentsPath) {
|
|
104
99
|
try {
|
|
@@ -143,7 +138,7 @@ function makePackageJson(projectDir) {
|
|
|
143
138
|
}
|
|
144
139
|
// Some coding agents read AGENTS.md by convention. Symlink so they get the
|
|
145
140
|
// same guidance without a duplicate copy.
|
|
146
|
-
function ensureAgentsSymlink(projectDir) {
|
|
141
|
+
export function ensureAgentsSymlink(projectDir) {
|
|
147
142
|
const agentsPath = path.join(projectDir, 'AGENTS.md');
|
|
148
143
|
if (fs.lstatSync(agentsPath, { throwIfNoEntry: false }))
|
|
149
144
|
return;
|
|
@@ -182,11 +177,16 @@ function scaffoldBare(projectDir) {
|
|
|
182
177
|
fs.mkdirSync(projectDir, { recursive: true });
|
|
183
178
|
fs.writeFileSync(path.join(projectDir, 'index.html'), INDEX_HTML);
|
|
184
179
|
fs.writeFileSync(path.join(projectDir, 'game.js'), GAME_JS);
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
180
|
+
const pins = {};
|
|
181
|
+
copyKitImport(projectDir, requireKitDir(BARE_DOCS_KIT), BARE_DOCS_KIT, BARE_DOCS_ALIAS, pins, new Map());
|
|
182
|
+
writeJsonFile(path.join(projectDir, 'castle.json'), { ...BARE_CASTLE_JSON, imports: pins });
|
|
183
|
+
fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), makeBareClaudeMd(BARE_DOCS_ALIAS));
|
|
184
|
+
appendPlatformSection(projectDir);
|
|
188
185
|
ensureAgentsSymlink(projectDir);
|
|
189
186
|
fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify(makePackageJson(projectDir), null, 2) + '\n');
|
|
187
|
+
// The docs kit declares no dependencies, so unlike a real kit's import there
|
|
188
|
+
// is nothing to merge into package.json before the install.
|
|
189
|
+
lockImportTree(path.join(projectDir, IMPORTS_DIR, BARE_DOCS_ALIAS));
|
|
190
190
|
}
|
|
191
191
|
// Copy a framework kit from kits/<kit>/ into the new deck dir, dropping
|
|
192
192
|
// build/dependency junk and castle.json.
|
|
@@ -295,6 +295,24 @@ export function writeStarterTheme(projectDir, kitDir) {
|
|
|
295
295
|
return;
|
|
296
296
|
fs.copyFileSync(src, dest);
|
|
297
297
|
}
|
|
298
|
+
function makeBareClaudeMd(alias) {
|
|
299
|
+
return `# Castle deck (no kit)
|
|
300
|
+
|
|
301
|
+
This deck is a normal browser project: \`index.html\` loads \`game.js\` as an ES
|
|
302
|
+
module, \`package.json\` holds its scripts and any npm package it adds, and
|
|
303
|
+
\`castle.json\` is its editor config. Nothing here comes from a framework -- there
|
|
304
|
+
is no scene, behavior, sprite, or level format unless this deck defines one, and
|
|
305
|
+
no editor other than the code editor unless this deck builds one. Everything it
|
|
306
|
+
renders, it renders itself: DOM, canvas, WebGL, React, Pixi, Three, WebAssembly,
|
|
307
|
+
whatever the web offers.
|
|
308
|
+
|
|
309
|
+
Read \`${IMPORTS_DIR}/${alias}/CLAUDE.md\` for the authoring guide: the deck's
|
|
310
|
+
file layout, the Castle SDK, and how to give a file type an editor of its own.
|
|
311
|
+
|
|
312
|
+
Do not edit anything under \`${IMPORTS_DIR}/\`: those files belong to the deck they
|
|
313
|
+
came from, and are replaced wholesale when the import is updated.
|
|
314
|
+
`;
|
|
315
|
+
}
|
|
298
316
|
function makeImportedKitClaudeMd(alias) {
|
|
299
317
|
return `# Castle deck
|
|
300
318
|
|
|
@@ -312,6 +330,24 @@ something in the kit behaves, define your own behavior of the same name in
|
|
|
312
330
|
\`behaviors/\` -- the deck's own files win over an import's.
|
|
313
331
|
`;
|
|
314
332
|
}
|
|
333
|
+
// A bare deck's CLAUDE.md points at the docs kit, which adopting a real kit is
|
|
334
|
+
// about to remove. Rewrite it to point at the kit that is now mounted -- but
|
|
335
|
+
// only while the file is still byte-for-byte what the scaffold wrote, since
|
|
336
|
+
// `isPristineBareDeck` answers for the entry point and says nothing about
|
|
337
|
+
// whatever the creator may have written here.
|
|
338
|
+
export function retargetBareClaudeMd(deckDir, alias) {
|
|
339
|
+
const claudePath = path.join(deckDir, 'CLAUDE.md');
|
|
340
|
+
const scaffolded = makeBareClaudeMd(BARE_DOCS_ALIAS).trimEnd() + '\n\n' + CLAUDE_MD_PLATFORM_SECTION;
|
|
341
|
+
try {
|
|
342
|
+
if (fs.readFileSync(claudePath, 'utf8') !== scaffolded)
|
|
343
|
+
return;
|
|
344
|
+
}
|
|
345
|
+
catch {
|
|
346
|
+
return;
|
|
347
|
+
}
|
|
348
|
+
fs.writeFileSync(claudePath, makeImportedKitClaudeMd(alias));
|
|
349
|
+
appendPlatformSection(deckDir);
|
|
350
|
+
}
|
|
315
351
|
// How the deck names the kit it was built on. `scripts/publish-kits.mjs` stamps
|
|
316
352
|
// a published kit's castle.json with the deckId it lives at and the version it
|
|
317
353
|
// was published as, and both have to be present to pin it that way: a deckId
|
|
@@ -445,7 +481,8 @@ function scaffoldFromKitImport(kit, projectDir) {
|
|
|
445
481
|
dependencies,
|
|
446
482
|
});
|
|
447
483
|
fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), makeImportedKitClaudeMd(alias));
|
|
448
|
-
|
|
484
|
+
appendPlatformSection(projectDir);
|
|
485
|
+
ensureAgentsSymlink(projectDir);
|
|
449
486
|
for (const importedAlias of copied.keys()) {
|
|
450
487
|
lockImportTree(path.join(projectDir, IMPORTS_DIR, importedAlias));
|
|
451
488
|
}
|
package/dist/install.js
CHANGED
|
@@ -2,6 +2,7 @@ import { execSync, spawn } from 'child_process';
|
|
|
2
2
|
import * as fs from 'fs';
|
|
3
3
|
import * as path from 'path';
|
|
4
4
|
import { restoreMissingImports, syncImportDependencies } from './imports.js';
|
|
5
|
+
import { writePlatformDocs } from './platformDoc.js';
|
|
5
6
|
function hasPnpm() {
|
|
6
7
|
try {
|
|
7
8
|
execSync('pnpm --version', { stdio: 'ignore' });
|
|
@@ -67,6 +68,9 @@ export async function install(dir) {
|
|
|
67
68
|
const restored = await restoreMissingImports(projectDir);
|
|
68
69
|
for (const alias of restored)
|
|
69
70
|
console.log(`Restored import ${alias}`);
|
|
71
|
+
// A fetched deck's CLAUDE.md already @imports the platform guide; write it
|
|
72
|
+
// now rather than leaving the reference dangling until the first serve.
|
|
73
|
+
writePlatformDocs(projectDir);
|
|
70
74
|
// Imports declare packages the deck has to install (see syncImportDependencies).
|
|
71
75
|
// Re-done here, not just at add-import time, so a deck fetched with get-deck --
|
|
72
76
|
// which brings castle.json's pins but not the dependency files -- still ends up
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
export declare const PLATFORM_DOCS_DIR: string;
|
|
2
|
+
export declare const PLATFORM_DOC_REL: string;
|
|
3
|
+
export declare function everyDeckBullets(deckDir: string): string[];
|
|
4
|
+
export declare const PLATFORM_SECTION_HEADING = "### from the Castle platform (every deck)";
|
|
5
|
+
export declare function platformSection(deckDir: string): string;
|
|
6
|
+
export declare function quickReferenceFor(deckDir: string, quickReference: string, backend: 'claude' | 'cursor' | 'smith'): string;
|
|
7
|
+
export declare function platformGuide(deckDir: string): string;
|
|
8
|
+
export declare function writePlatformDocs(deckDir: string): void;
|
|
9
|
+
export declare const CLAUDE_MD_IMPORT_LINE: string;
|
|
10
|
+
export declare const CLAUDE_MD_PLATFORM_SECTION: string;
|
|
11
|
+
export type ClaudeMdMigration = 'absent' | 'current' | 'migrated' | 'added' | 'kept' | 'gated';
|
|
12
|
+
export declare function migrateClaudeMd(deckDir: string): ClaudeMdMigration;
|
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
import * as crypto from 'crypto';
|
|
2
|
+
import * as fs from 'fs';
|
|
3
|
+
import * as path from 'path';
|
|
4
|
+
import { NO_DECK_DOCS } from './agent-prompts.js';
|
|
5
|
+
import { resolveFileTypes } from './editorConfig.js';
|
|
6
|
+
// The platform's own guidance to agents -- the rules identical in a bare deck
|
|
7
|
+
// and a kit deck: the card, touch, assets and formats, imports, reloading,
|
|
8
|
+
// editors. Its one home is here. The serve writes it under the deck's .castle/
|
|
9
|
+
// at every start (runtime state: not saved, not versioned, never edited), the
|
|
10
|
+
// deck's root CLAUDE.md `@`-imports the compact copy so any agent that
|
|
11
|
+
// auto-loads CLAUDE.md gets it for free, and backends that read no CLAUDE.md
|
|
12
|
+
// (cursor-agent, smith) get the same bullets in their composed prompt. Kits
|
|
13
|
+
// state only what is theirs; nothing below is restated in a kit's guide.
|
|
14
|
+
//
|
|
15
|
+
// The text is what was always in context before it had one home: the four
|
|
16
|
+
// sections `init` used to append to every CLAUDE.md, verbatim, plus the rules
|
|
17
|
+
// the kits' quick references used to restate (formats, install, reloading,
|
|
18
|
+
// editors) in their original wording. Nothing that was inlined became
|
|
19
|
+
// tool-call-only in the move, and nothing tool-call-only became inlined --
|
|
20
|
+
// that split is deliberate (memo 26-08-24-17-54) and the eval legs measured
|
|
21
|
+
// the vehicle, not a rewrite.
|
|
22
|
+
export const PLATFORM_DOCS_DIR = path.join('.castle', 'docs');
|
|
23
|
+
export const PLATFORM_DOC_REL = path.join(PLATFORM_DOCS_DIR, 'platform.md');
|
|
24
|
+
const MEDIA = {
|
|
25
|
+
images: ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg'],
|
|
26
|
+
audio: ['.mp3', '.wav', '.m4a'],
|
|
27
|
+
video: ['.mp4'],
|
|
28
|
+
};
|
|
29
|
+
const code = (exts) => exts.map((e) => `\`${e}\``).join(' ');
|
|
30
|
+
// What this deck can hold: the formats that survive publishing, plus whatever
|
|
31
|
+
// the deck or its imports declared as a file type (a declaration is the deck
|
|
32
|
+
// saying it handles that format -- see editorConfig.ts). Computed per deck so
|
|
33
|
+
// no kit has to restate the list and no list goes stale on a deck that adds a
|
|
34
|
+
// type.
|
|
35
|
+
function mediaList(deckDir) {
|
|
36
|
+
const defaults = new Set([...MEDIA.images, ...MEDIA.audio, ...MEDIA.video]);
|
|
37
|
+
const own = (resolveFileTypes(deckDir) ?? [])
|
|
38
|
+
.filter((t) => !t.unsupported && !defaults.has(t.ext))
|
|
39
|
+
.map((t) => t.ext);
|
|
40
|
+
const base = `images ${code(MEDIA.images)}, audio ${code(MEDIA.audio)}, video \`.mp4\` (H.264)`;
|
|
41
|
+
return own.length ? `${base}, plus its own declared types ${code(own)}` : base;
|
|
42
|
+
}
|
|
43
|
+
// The ratified mode bullet (prompt-evals deliverable 4: the 169-byte line that
|
|
44
|
+
// is the whole difference between offering and building unasked). Verbatim.
|
|
45
|
+
const MODE_BULLET = "- Unprompted, an editor is an offer, never a build: when the same data keeps getting edited by hand, propose one and build on the user's yes. Never during a first build.";
|
|
46
|
+
// The rules that reached agents through a kit's quick reference before the
|
|
47
|
+
// kits stopped restating them: the physics-2d / blank wording, with the media
|
|
48
|
+
// list computed per deck.
|
|
49
|
+
export function everyDeckBullets(deckDir) {
|
|
50
|
+
return [
|
|
51
|
+
`- **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
|
+
"- 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
|
+
"- 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.",
|
|
54
|
+
"- 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
|
+
'- 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
|
+
MODE_BULLET,
|
|
57
|
+
];
|
|
58
|
+
}
|
|
59
|
+
// The guide as a section of the prompt's "how this deck works", for the
|
|
60
|
+
// backends that read no CLAUDE.md. Same heading shape as an import's section.
|
|
61
|
+
export const PLATFORM_SECTION_HEADING = '### from the Castle platform (every deck)';
|
|
62
|
+
export function platformSection(deckDir) {
|
|
63
|
+
return `${PLATFORM_SECTION_HEADING}\n\n${platformGuide(deckDir)}`;
|
|
64
|
+
}
|
|
65
|
+
// ------------------------------------------------------------------- the gate
|
|
66
|
+
// Whether this serve may rewrite an EXISTING deck's root CLAUDE.md onto the
|
|
67
|
+
// @import. That rewrite is the one irreversible thing here, so it reaches decks
|
|
68
|
+
// on a gate rather than all at once; off unless the serve was told otherwise.
|
|
69
|
+
// Everything else is unconditional -- the guide written under .castle/docs, the
|
|
70
|
+
// section a new deck scaffolds with, the block spawned agents get -- because
|
|
71
|
+
// the kits are one shared artifact and stopped restating these rules for
|
|
72
|
+
// everyone at once, gate or no gate. The cloud editor sets it per user from a
|
|
73
|
+
// feature gate; see serveOnPort in castle-www's cloudSandbox.ts.
|
|
74
|
+
function mayMigrateClaudeMd() {
|
|
75
|
+
return process.env.CASTLE_PLATFORM_DOC === 'on';
|
|
76
|
+
}
|
|
77
|
+
// The line has to stand on its own to count: this repo's CLAUDE.md names the
|
|
78
|
+
// path inside a sentence, and prose about the import must not read as a deck
|
|
79
|
+
// carrying one.
|
|
80
|
+
function claudeMdImportsGuide(deckDir) {
|
|
81
|
+
try {
|
|
82
|
+
return fs
|
|
83
|
+
.readFileSync(path.join(deckDir, 'CLAUDE.md'), 'utf8')
|
|
84
|
+
.split('\n')
|
|
85
|
+
.some((line) => line.trim() === CLAUDE_MD_IMPORT_LINE);
|
|
86
|
+
}
|
|
87
|
+
catch {
|
|
88
|
+
return false;
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
// Resolved ONCE per deck and cached, for the reason planSession is (agent.ts):
|
|
92
|
+
// it decides what sits in the prompt's cached prefix, and answering a
|
|
93
|
+
// mid-session edit would split that cache. The serve migrates before it builds
|
|
94
|
+
// any prompt, so the first answer here is the post-migration one.
|
|
95
|
+
const guideLoaders = new Map();
|
|
96
|
+
function deckLoadsGuide(deckDir) {
|
|
97
|
+
const cached = guideLoaders.get(deckDir);
|
|
98
|
+
if (cached !== undefined)
|
|
99
|
+
return cached;
|
|
100
|
+
const loads = claudeMdImportsGuide(deckDir);
|
|
101
|
+
guideLoaders.set(deckDir, loads);
|
|
102
|
+
return loads;
|
|
103
|
+
}
|
|
104
|
+
// A sentence from the bullets the kits used to restate, distinctive enough to
|
|
105
|
+
// tell a kit guide that still carries them from one that stopped.
|
|
106
|
+
const RESTATEMENT_MARKER = '**Supported media formats are exactly**';
|
|
107
|
+
// The every-deck bullets after a quick reference that lacks them. Skipped when
|
|
108
|
+
// the deck's kit is pinned to a version that still restates them, which would
|
|
109
|
+
// otherwise say all of it twice.
|
|
110
|
+
function withEveryDeckBullets(deckDir, quickReference) {
|
|
111
|
+
const own = quickReference.trim();
|
|
112
|
+
if (own.includes(RESTATEMENT_MARKER))
|
|
113
|
+
return quickReference;
|
|
114
|
+
const bullets = everyDeckBullets(deckDir).join('\n');
|
|
115
|
+
return own ? `${own}\n\n${bullets}` : bullets;
|
|
116
|
+
}
|
|
117
|
+
// A deck's quick reference as one backend sees it. cursor-agent and smith read
|
|
118
|
+
// no CLAUDE.md, so the whole block goes in their prompt. claude auto-loads the
|
|
119
|
+
// root CLAUDE.md -- but only a deck whose file carries the @import line has the
|
|
120
|
+
// guide that way. A deck the migration has not reached (gated off) or refused
|
|
121
|
+
// ('kept' -- someone edited its sections) still has the four legacy sections
|
|
122
|
+
// inline and is missing just the every-deck bullets, which left the kits'
|
|
123
|
+
// quick reference in the same change that added the guide.
|
|
124
|
+
export function quickReferenceFor(deckDir, quickReference, backend) {
|
|
125
|
+
if (backend === 'claude') {
|
|
126
|
+
return deckLoadsGuide(deckDir) ? quickReference : withEveryDeckBullets(deckDir, quickReference);
|
|
127
|
+
}
|
|
128
|
+
const own = quickReference.trim();
|
|
129
|
+
return `${platformSection(deckDir)}\n\n${own || NO_DECK_DOCS}`;
|
|
130
|
+
}
|
|
131
|
+
// The four sections `init` appended to every deck's CLAUDE.md until 2026-08-25
|
|
132
|
+
// (COMMON_INSTRUCTIONS), verbatim; only the "(every deck)" heading suffix is
|
|
133
|
+
// gone, since the whole file is that now.
|
|
134
|
+
const COMMON_SECTIONS = `## Imports are read-only
|
|
135
|
+
|
|
136
|
+
- **\`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.
|
|
137
|
+
- **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.
|
|
138
|
+
- **\`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.
|
|
139
|
+
- **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.
|
|
140
|
+
- **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.
|
|
141
|
+
|
|
142
|
+
## Assets
|
|
143
|
+
|
|
144
|
+
- **Load static assets (drawings, audio, etc.) through the bundler — never runtime-\`fetch\` a loose file path.** Use a static \`import\`, \`import.meta.glob('./drawings/*.svg', { eager: true, import: 'default' })\`, or inline the asset directly. The dev serve happens to serve loose files over HTTP, so \`fetch('drawings/qb.svg')\` looks like it works locally — but \`save-deck\` bundles the whole deck into a single file, loose files are no longer served, and the fetch silently fails on every platform. Kit decks: use the kit's own drawing/asset-loading APIs instead of a raw \`fetch\`.
|
|
145
|
+
|
|
146
|
+
## Touch controls
|
|
147
|
+
|
|
148
|
+
- **Playable on a touchscreen, with only the controls the game actually needs.** Castle decks are played on phones, so whatever input a game does use must work by touch — direct tap/drag on the game itself wherever possible, and on-screen buttons only where the mechanics genuinely call for them. Do NOT add controls a game doesn't need: never drop in a generic d-pad or movement overlay by default. Prefer touching the game directly over an overlay that just mirrors keyboard keys. Keyboard input is fine to support on top for desktop play. Match the controls to the actual mechanics — a game with no directional movement should have no movement controls at all.
|
|
149
|
+
|
|
150
|
+
## Fit the card
|
|
151
|
+
|
|
152
|
+
- **The deck plays inside a fixed 5:7 portrait card, not the full window.** The card is sized to fit the screen (at most about 450x630px), clips overflow, and does not scroll. Design the whole layout to fit inside that portrait box: size UI relative to the card with percentages, flex/grid, \`min()\`, \`clamp()\`, or viewport-relative units instead of fixed tall panels. Let playfields scale down on smaller cards rather than overflowing; anything outside the card edges is cut off. The SDK exports \`CARD_RATIO\` (= 5 / 7) if you need the exact ratio.
|
|
153
|
+
- **Hand-rolled \`<canvas>\` elements must account for devicePixelRatio, or the game looks blurry on phones.** Size the backing store to the CSS layout size times \`devicePixelRatio\` (e.g. \`canvas.width = rect.width * dpr\`), keep the CSS width/height as the layout size, and scale the 2D context (\`ctx.scale(dpr, dpr)\`) so drawing code stays in CSS units — re-apply on resize. Kit decks don't need to do this by hand; the kit's engine already configures its canvas for DPR.
|
|
154
|
+
- Exception: deliberate pixel art wants a fixed low-resolution backing store with \`image-rendering: pixelated\` CSS instead — don't DPR-scale that; the crisp chunky look is the point.
|
|
155
|
+
`;
|
|
156
|
+
export function platformGuide(deckDir) {
|
|
157
|
+
return `${COMMON_SECTIONS.trimEnd()}
|
|
158
|
+
|
|
159
|
+
## Formats, reloading, editors
|
|
160
|
+
|
|
161
|
+
${everyDeckBullets(deckDir).join('\n')}
|
|
162
|
+
`;
|
|
163
|
+
}
|
|
164
|
+
function platformDoc(deckDir) {
|
|
165
|
+
return `# Castle platform
|
|
166
|
+
|
|
167
|
+
How every Castle deck works, from the Castle CLI. Written fresh at every serve
|
|
168
|
+
start; the deck's own guide (its kit's CLAUDE.md under imports/) adds what its
|
|
169
|
+
kit provides on top of this.
|
|
170
|
+
|
|
171
|
+
${platformGuide(deckDir)}`;
|
|
172
|
+
}
|
|
173
|
+
// Written by the serve at every start, so the copy in a deck is exactly as
|
|
174
|
+
// fresh as the CLI serving it.
|
|
175
|
+
export function writePlatformDocs(deckDir) {
|
|
176
|
+
fs.mkdirSync(path.join(deckDir, PLATFORM_DOCS_DIR), { recursive: true });
|
|
177
|
+
fs.writeFileSync(path.join(deckDir, PLATFORM_DOC_REL), platformDoc(deckDir));
|
|
178
|
+
}
|
|
179
|
+
// What the deck's root CLAUDE.md carries for the platform: one @import line
|
|
180
|
+
// (which claude auto-loads) inside a short section that says what it is, for
|
|
181
|
+
// the agents that read the file as plain text.
|
|
182
|
+
export const CLAUDE_MD_IMPORT_LINE = `@${PLATFORM_DOC_REL}`;
|
|
183
|
+
export const CLAUDE_MD_PLATFORM_SECTION = `## Platform
|
|
184
|
+
|
|
185
|
+
The rules every Castle deck plays by -- the card and touch, assets and
|
|
186
|
+
formats, imports, reloading, editors -- are the Castle CLI's, not this deck's.
|
|
187
|
+
The serve writes them fresh at every start to \`${PLATFORM_DOC_REL}\`, loaded here:
|
|
188
|
+
|
|
189
|
+
${CLAUDE_MD_IMPORT_LINE}
|
|
190
|
+
`;
|
|
191
|
+
// ---------------------------------------------------------------- migration
|
|
192
|
+
// Every version of the "(every deck)" sections that `init` ever appended to a
|
|
193
|
+
// deck's CLAUDE.md (COMMON_INSTRUCTIONS, 2026-07 to 2026-08), as sha256 of the
|
|
194
|
+
// trimmed section. A deck whose sections all match one of these carried the
|
|
195
|
+
// platform text untouched, and the serve may replace them with the @import;
|
|
196
|
+
// any other section body is the deck's own and is left exactly as it is.
|
|
197
|
+
const LEGACY_SECTION_HASHES = new Set([
|
|
198
|
+
'0b7db63866c07f8346201493c45fab2ca3419f1502456dffd00a833024bc3d47', // ## Assets (every deck) @ e11bd8c
|
|
199
|
+
'6500b701989fb6b4dd0c2b09c7b3d38f189480c5fa7148563af894098609d5cb', // ## Castle rules (every deck) @ 289055f
|
|
200
|
+
'44ec1f1565f6be49f914bb7513bab37acc18ddfcb24c4d91f447a7b157d6d477', // ## Fit the card (every deck) @ 8552d0e
|
|
201
|
+
'97913fb5e98d7707a78db22927e8fc4a06cae8393cfdd6c61880aa100498356b', // ## Fit the card (every deck) @ 31e6897
|
|
202
|
+
'8a03a1826d10ba2e37ac3fc2aadc3a478051b125abf98f33073e2314e32eeae1', // ## Imports are read-only (every deck) @ 1b94488
|
|
203
|
+
'daf5c57e0b14bde423efaa5c30f6f4531743be13293639b9085c14e4da0689f3', // ## Imports are read-only (every deck) @ f2d8a41
|
|
204
|
+
'78f0dc79715876bfb4b3b9f5f0a5469ecf8b424d995680ef28a8454293a2ff84', // ## Imports are read-only (every deck) @ 7e4a9f9
|
|
205
|
+
'0ae557e6602d9a03c71f45ed7516bc4808c8d166c5023512c0e6d68254704f85', // ## Touch controls (every deck) @ c9c749f
|
|
206
|
+
'132f2c4c13685d17cb45d775c2cce55dfbc54c79d8f9821eaea8e147567592b9', // ## Touch controls (every deck) @ bc5fbe0
|
|
207
|
+
]);
|
|
208
|
+
const LEGACY_HEADING = /^## .*\(every deck\)\s*$/m;
|
|
209
|
+
const hash = (s) => crypto.createHash('sha256').update(s.trim()).digest('hex');
|
|
210
|
+
// Move an existing deck's root CLAUDE.md onto the @import: remove the legacy
|
|
211
|
+
// sections when every one of them is byte-for-byte a version this CLI shipped,
|
|
212
|
+
// then append the platform section. Text outside those sections is never
|
|
213
|
+
// touched, and a section anyone edited keeps the whole file as it is ('kept'
|
|
214
|
+
// -- the deck chose its text; the prompt-side block still reaches spawned
|
|
215
|
+
// agents). A file with no legacy sections at all just gains the section.
|
|
216
|
+
export function migrateClaudeMd(deckDir) {
|
|
217
|
+
if (!mayMigrateClaudeMd())
|
|
218
|
+
return 'gated';
|
|
219
|
+
const claudePath = path.join(deckDir, 'CLAUDE.md');
|
|
220
|
+
let md;
|
|
221
|
+
try {
|
|
222
|
+
md = fs.readFileSync(claudePath, 'utf8');
|
|
223
|
+
}
|
|
224
|
+
catch {
|
|
225
|
+
return 'absent';
|
|
226
|
+
}
|
|
227
|
+
if (md.includes(CLAUDE_MD_IMPORT_LINE))
|
|
228
|
+
return 'current';
|
|
229
|
+
const parts = md.split(/(?=^## )/m);
|
|
230
|
+
const legacy = parts.filter((p) => LEGACY_HEADING.test(p.split('\n')[0]));
|
|
231
|
+
if (legacy.some((p) => !LEGACY_SECTION_HASHES.has(hash(p))))
|
|
232
|
+
return 'kept';
|
|
233
|
+
const rest = parts.filter((p) => !legacy.includes(p)).join('').trimEnd();
|
|
234
|
+
fs.writeFileSync(claudePath, `${rest}\n\n${CLAUDE_MD_PLATFORM_SECTION}`);
|
|
235
|
+
return legacy.length ? 'migrated' : 'added';
|
|
236
|
+
}
|
package/dist/serve.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
export declare function appendCapped(file: string, line: string): void;
|
|
2
2
|
export declare function isAllowedShellHost(hostHeader: string | undefined, configuredHost?: string): boolean;
|
|
3
|
+
export declare function isAllowedContentFilesRequest(role: 'edit' | 'play' | null, method: string | undefined, reqPath: string): boolean;
|
|
3
4
|
export declare function serve(dir: string, options?: {
|
|
4
5
|
port?: string;
|
|
5
6
|
host?: string;
|
package/dist/serve.js
CHANGED
|
@@ -10,6 +10,8 @@ import { createAgentServer } from './agent.js';
|
|
|
10
10
|
import { sceneFilesPlugin, importsAliasPlugin, forksOverlayPlugin } from './vitePlugins.js';
|
|
11
11
|
import { installFilesChangedWatcher } from './filesChanged.js';
|
|
12
12
|
import { autoUpdateImports, IMPORTS_DIR, lockImportTree } from './imports.js';
|
|
13
|
+
import { ensureAgentsSymlink } from './init.js';
|
|
14
|
+
import { migrateClaudeMd, PLATFORM_DOC_REL, writePlatformDocs } from './platformDoc.js';
|
|
13
15
|
import { FORKS_DIR, ownForkFile, splitImportRel } from './forks.js';
|
|
14
16
|
import * as config from './config.js';
|
|
15
17
|
import { graphql as castleGraphql } from './api.js';
|
|
@@ -100,6 +102,16 @@ export function isAllowedShellHost(hostHeader, configuredHost) {
|
|
|
100
102
|
const configured = configuredHost ? hostnameFromHeader(configuredHost) : '';
|
|
101
103
|
return configured !== '' && configured !== '0.0.0.0' && configured !== '::' && host === configured;
|
|
102
104
|
}
|
|
105
|
+
const EDIT_CONTENT_READ_ENDPOINTS = new Set([
|
|
106
|
+
'/__castle/files/raw',
|
|
107
|
+
'/__castle/files/read',
|
|
108
|
+
'/__castle/files/info',
|
|
109
|
+
'/__castle/files/list',
|
|
110
|
+
'/__castle/files/forks',
|
|
111
|
+
]);
|
|
112
|
+
export function isAllowedContentFilesRequest(role, method, reqPath) {
|
|
113
|
+
return role === 'edit' && method === 'GET' && EDIT_CONTENT_READ_ENDPOINTS.has(reqPath);
|
|
114
|
+
}
|
|
103
115
|
function castlePlugin(security, ideServer, agentServer, configuredHost) {
|
|
104
116
|
return {
|
|
105
117
|
name: 'castle-dev',
|
|
@@ -162,14 +174,14 @@ window.__castleShellOrigin=(function(){
|
|
|
162
174
|
if (content) {
|
|
163
175
|
if (reqPath === '/')
|
|
164
176
|
req.url = `/index.html${req.url?.includes('?') ? req.url.slice(req.url.indexOf('?')) : ''}`;
|
|
165
|
-
const
|
|
177
|
+
const allowedFilesRequest = isAllowedContentFilesRequest(verifiedRole, req.method, reqPath);
|
|
166
178
|
const allowedVendor = reqPath.startsWith('/__castle/vendor/');
|
|
167
179
|
const allowedFavicon = FAVICON_FILES.some((name) => reqPath === `/${name}`);
|
|
168
|
-
if (reqPath.startsWith('/__castle/') && !
|
|
180
|
+
if (reqPath.startsWith('/__castle/') && !allowedFilesRequest && !allowedVendor) {
|
|
169
181
|
res.writeHead(403).end('content capability does not allow this endpoint');
|
|
170
182
|
return;
|
|
171
183
|
}
|
|
172
|
-
if ((
|
|
184
|
+
if ((allowedFilesRequest || allowedVendor || allowedFavicon) && ideServer.handleHttpRequest(req, res, reqPath))
|
|
173
185
|
return;
|
|
174
186
|
next();
|
|
175
187
|
return;
|
|
@@ -397,6 +409,18 @@ export async function serve(dir, options = {}) {
|
|
|
397
409
|
const castleDir = path.join(projectDir, '.castle');
|
|
398
410
|
if (!fs.existsSync(castleDir))
|
|
399
411
|
fs.mkdirSync(castleDir, { recursive: true });
|
|
412
|
+
// The platform guide, fresh from this CLI, and the root CLAUDE.md's @import
|
|
413
|
+
// of it (platformDoc.ts). After autoUpdateImports, so the guide's media list
|
|
414
|
+
// sees the imports this serve will run with.
|
|
415
|
+
writePlatformDocs(projectDir);
|
|
416
|
+
const migration = migrateClaudeMd(projectDir);
|
|
417
|
+
ensureAgentsSymlink(projectDir);
|
|
418
|
+
if (migration === 'migrated' || migration === 'added') {
|
|
419
|
+
console.log(`CLAUDE.md now loads the platform guide from ${PLATFORM_DOC_REL}`);
|
|
420
|
+
}
|
|
421
|
+
else if (migration === 'kept') {
|
|
422
|
+
console.log(`CLAUDE.md has hand-edited platform sections; left as they are (the platform guide is at ${PLATFORM_DOC_REL})`);
|
|
423
|
+
}
|
|
400
424
|
const logFile = path.join(castleDir, 'logs.txt');
|
|
401
425
|
const screenshotsDir = path.join(castleDir, 'screenshots');
|
|
402
426
|
const serveJsonPath = path.join(castleDir, 'serve.json');
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# blank kit
|
|
2
|
+
|
|
3
|
+
The authoring guide for a deck built on no framework -- a plain browser
|
|
4
|
+
project. This kit ships no code, only this document: `## Files` covers what the
|
|
5
|
+
deck holds, `## Editors` covers building a visual editor for a file type the
|
|
6
|
+
deck defines. The rules that hold for every Castle deck are the platform's, in
|
|
7
|
+
`.castle/docs/platform.md` (written by the serve at every start).
|
|
8
|
+
|
|
9
|
+
## Quick reference
|
|
10
|
+
|
|
11
|
+
<!-- Injected into Castle's create assistant every turn; keep this compact and factual. -->
|
|
12
|
+
|
|
13
|
+
- A plain browser project: `index.html` + `game.js` (an ES module) + `package.json` + `castle.json` (editor config). No kit: nothing in this deck comes from a framework, and there is no scene, behavior, sprite, or level format unless the deck defines one. Build directly with DOM, canvas, WebGL, React, Pixi, Three, or any installed package.
|
|
14
|
+
- `import { setup, initCard } from 'castle-web-sdk'`. Call `setup()` first, once; `initCard()` returns the element to render into (a React tree mounted at `#root` needs no `initCard`). Castle services — `Storage`, `SharedStorage`, `Leaderboard`, `Time`, `User`, `Haptics`, `Pass`, `Portal`, `Lifecycle` — come from the same package; the full reference is `node_modules/castle-web-sdk/README.md`.
|
|
15
|
+
- Vite serves and bundles the deck: ES modules, JSX, JSON, CSS and npm packages all work with no build step of your own — don't add one.
|
|
16
|
+
- Call `Lifecycle.ready()` once the first real frame is painted, so the Castle feed reveals the deck right away instead of after a timeout.
|
|
17
|
+
- There is no `check` script: verifying a change means the Play panel, the forwarded console in `.castle/logs.txt`, and `npm run screenshot` (needs a live panel; a canvas needs `preserveDrawingBuffer: true` or the capture is blank).
|
|
18
|
+
- Details: `## Files` and `## Editors` in this file (`imports/castle.blank/CLAUDE.md`). The rules every deck plays by -- the card, touch, assets and formats, imports, reloading -- are the platform's: `.castle/docs/platform.md`, written by the serve.
|
|
19
|
+
|
|
20
|
+
## Files
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
index.html entry page; loads game.js as a module
|
|
24
|
+
game.js the game (any layout of modules under it is fine)
|
|
25
|
+
package.json scripts + dependencies
|
|
26
|
+
castle.json editor config + import pins; gets a deckId on first save-deck
|
|
27
|
+
imports/ other decks this one imports, read-only. `castle.blank` (this
|
|
28
|
+
guide) is always here; `castle-web add-import` adds more
|
|
29
|
+
.castle/ runtime state: serve.json (the live serve), logs.txt (forwarded
|
|
30
|
+
console output), screenshots/
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
`castle.json` → `editor`:
|
|
34
|
+
|
|
35
|
+
- `initialPanels` — what the workspace opens with (`files`, `playtest`).
|
|
36
|
+
- `visiblePaths` / `hiddenPaths` — the Files panel filter. `[]` shows every
|
|
37
|
+
file, which is a bare deck's default; nothing needs adding for new files to
|
|
38
|
+
appear.
|
|
39
|
+
- `fileTypes` — the deck's own file types; see `## Editors`.
|
|
40
|
+
- `defaultPlayFile` — what the play panel opens with. A bare deck has none: it
|
|
41
|
+
plays `index.html`.
|
|
42
|
+
|
|
43
|
+
Scripts: `npm run screenshot` captures the open page; `npm run save-deck`
|
|
44
|
+
publishes (the deck is then at `https://castle.xyz/d/<deckId>`) and also
|
|
45
|
+
photographs the running deck for its cover; `npm run restart` reloads every
|
|
46
|
+
panel (`.castle/docs/platform.md` says when not to).
|
|
47
|
+
|
|
48
|
+
## Editors
|
|
49
|
+
|
|
50
|
+
An editor is a visual authoring surface for a file type. This deck has none
|
|
51
|
+
built in — the code editor opens everything — but it can add its own: declare
|
|
52
|
+
a file type in `castle.json`, write one module, and have the entry answer the
|
|
53
|
+
editor route. The Files panel then opens that type in your editor with a
|
|
54
|
+
code/visual toggle. Reach for one when the deck accumulates content someone
|
|
55
|
+
will keep iterating on by hand — level layouts, dialogue, item or word
|
|
56
|
+
catalogs, tuning values — where editing raw JSON in the code editor is the
|
|
57
|
+
bottleneck.
|
|
58
|
+
|
|
59
|
+
### The three steps
|
|
60
|
+
|
|
61
|
+
1. **Declare the type** in `castle.json` under `editor.fileTypes`:
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
"editor": {
|
|
65
|
+
"fileTypes": [
|
|
66
|
+
{ "ext": ".dialogue", "label": "Dialogue", "new": "New dialogue",
|
|
67
|
+
"icon": "file", "editor": "editors/DialogueEditor.js", "data": "json" }
|
|
68
|
+
]
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
These are ALL the fields that exist — do not invent others:
|
|
73
|
+
- `ext` — the extension, with the dot. One entry per extension. Pick one
|
|
74
|
+
that is the deck's own (`.dialogue`, `.levels`), not `.json`: a type
|
|
75
|
+
claims every file with that extension.
|
|
76
|
+
- `label` — display name in the tab and pickers.
|
|
77
|
+
- `new` — the entry in the Files panel's New menu; omit it and the type
|
|
78
|
+
can't be created there.
|
|
79
|
+
- `icon` — for that entry and the file's tree row, from the shell's set:
|
|
80
|
+
`globe`, `layer-group`, `code`, `file`, `image`, `music`, `film`. An
|
|
81
|
+
unknown name falls back to a generic icon.
|
|
82
|
+
- `editor` — the module that edits this type, as a path from the deck
|
|
83
|
+
root, under `editors/`. Omit it to leave the type to the code editor.
|
|
84
|
+
- `data` — how the file behaves when a module imports it: `"json"` (the
|
|
85
|
+
import yields the parsed object) or `"text"` (the raw string). Omit for
|
|
86
|
+
an ordinary JS module. See the gotcha below before relying on it.
|
|
87
|
+
- `unsupported` — a refusal: why this deck must NOT be built on this
|
|
88
|
+
format, shown when someone tries to upload one. Only for formats you
|
|
89
|
+
recognize and reject.
|
|
90
|
+
|
|
91
|
+
2. **Write the module** at the declared path. There is no host component
|
|
92
|
+
here, so the shape is yours; a default export that mounts into an element
|
|
93
|
+
is the simplest:
|
|
94
|
+
|
|
95
|
+
```js
|
|
96
|
+
// editors/DialogueEditor.js
|
|
97
|
+
const EMPTY = { lines: [] };
|
|
98
|
+
|
|
99
|
+
export default function mount(el, { path, text, onChange }) {
|
|
100
|
+
let doc;
|
|
101
|
+
try { doc = text.trim() ? JSON.parse(text) : EMPTY; } catch { doc = EMPTY; }
|
|
102
|
+
const save = (next) => onChange(JSON.stringify(next, null, 2));
|
|
103
|
+
// ...render doc into el, call save(next) on every edit...
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
3. **Answer the editor route in the entry.** The shell opens a declared type
|
|
108
|
+
as an iframe of the deck's own page at
|
|
109
|
+
`/index.html?file=<path>&editorModule=<module>`, so `game.js` has to branch
|
|
110
|
+
on `file` before it starts the game:
|
|
111
|
+
|
|
112
|
+
```js
|
|
113
|
+
import { setup, initCard, isEdit, writeFile, fileUrl } from 'castle-web-sdk';
|
|
114
|
+
|
|
115
|
+
const editors = import.meta.glob('./editors/*.js');
|
|
116
|
+
|
|
117
|
+
async function mountEditor(file, editorModule) {
|
|
118
|
+
const load = editors[`./${editorModule}`];
|
|
119
|
+
if (!load) throw new Error(`no editor module ${editorModule}`);
|
|
120
|
+
const [mod, text] = await Promise.all([load(), fetch(fileUrl(file)).then((r) => r.text())]);
|
|
121
|
+
let pending;
|
|
122
|
+
const onChange = (next) => {
|
|
123
|
+
clearTimeout(pending);
|
|
124
|
+
pending = setTimeout(() => writeFile(file, next), 300);
|
|
125
|
+
};
|
|
126
|
+
document.body.style.margin = '0';
|
|
127
|
+
mod.default(document.body, { path: file, text, onChange });
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
setup();
|
|
131
|
+
const params = new URLSearchParams(location.search);
|
|
132
|
+
const file = params.get('file');
|
|
133
|
+
if (isEdit() && file) {
|
|
134
|
+
mountEditor(file, params.get('editorModule'));
|
|
135
|
+
} else {
|
|
136
|
+
startGame(initCard());
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Read the file with `fetch(fileUrl(path))` and save it with
|
|
141
|
+
`writeFile(path, text)`, debounced — both are SDK calls that only work
|
|
142
|
+
while editing on the serve, which is the only place an editor runs. Load
|
|
143
|
+
the module through `import.meta.glob` so the bundler knows about it; a
|
|
144
|
+
dynamic `import(editorModule)` of a runtime string does not bundle. The
|
|
145
|
+
editor branch skips `initCard()`: it fills the panel, not a 5:7 card.
|
|
146
|
+
|
|
147
|
+
That's the whole integration. Nothing auto-reloads: the person opens the file
|
|
148
|
+
(or reloads its panel) when they are ready.
|
|
149
|
+
|
|
150
|
+
### Gotchas
|
|
151
|
+
|
|
152
|
+
- **Declare the glob and the mount function ABOVE the branch that calls them.**
|
|
153
|
+
A `const` is in its temporal dead zone until its own line runs, so a
|
|
154
|
+
`mountEditor(...)` called from higher up throws `Cannot access 'editors'
|
|
155
|
+
before initialization` the moment it reads the map -- the function hoists, the
|
|
156
|
+
`const` does not. Keep the dispatch last, as above.
|
|
157
|
+
- **A `new:`-created file starts EMPTY.** Your editor must render a sensible
|
|
158
|
+
default on empty text (as `EMPTY` above) and write the real document back
|
|
159
|
+
on first edit — a module that throws on `""` is a blank panel.
|
|
160
|
+
- **`data:` takes effect at serve start.** The serve reads the declared data
|
|
161
|
+
types once, when it starts — and `init` started it before your type
|
|
162
|
+
existed — so play code that `import`s a `.dialogue` file gets a parse error
|
|
163
|
+
until the serve process restarts. Either import the content as text and
|
|
164
|
+
parse it yourself (`import raw from './dialogue/main.dialogue?raw'`, or
|
|
165
|
+
`import.meta.glob('./dialogue/*.dialogue', { query: '?raw', import: 'default', eager: true })`
|
|
166
|
+
— no declaration needed, and it bundles), or declare `data` and accept that
|
|
167
|
+
the module import works after the next serve start. The editor route is
|
|
168
|
+
unaffected: it reads through `fileUrl`.
|
|
169
|
+
- **Editors are edit-time only.** They must never run in play, and play code
|
|
170
|
+
must never import from `editors/`. Keep logic both sides need (parsing,
|
|
171
|
+
defaults) in a plain module both import.
|
|
172
|
+
- **Reading media/binary files:** point an `<img>`/`<audio>` at
|
|
173
|
+
`fileUrl(path)`; `fetch(fileUrl(path))` is for text.
|
|
174
|
+
- **Design for a phone.** The editor renders in a panel that is often
|
|
175
|
+
phone-width. Touch first: direct tap/drag on the content, big hit targets,
|
|
176
|
+
no hover-only or keyboard-only affordances, no fixed-wide toolbars. Scroll
|
|
177
|
+
vertically inside the panel rather than overflowing it. The shell is dark;
|
|
178
|
+
nothing of its theme reaches the iframe, so set your own background and
|
|
179
|
+
text colors rather than inheriting the page default.
|
|
180
|
+
- **The code view stays reachable** (the tab's view toggle), so don't build
|
|
181
|
+
a raw-JSON fallback mode into the editor itself.
|
|
182
|
+
- **Imported editors.** If this deck imports another deck that declares a
|
|
183
|
+
type, the shell hands the entry that deck's module as
|
|
184
|
+
`editorModule=imports/<alias>/editors/...`. A second
|
|
185
|
+
`import.meta.glob('./imports/*/editors/*.{js,jsx}')` alongside the deck's
|
|
186
|
+
own lets the same dispatcher load it. `imports/` is read-only: to change an
|
|
187
|
+
imported editor, copy it into your own `editors/` and declare the same
|
|
188
|
+
`ext` yourself — the deck's own declaration wins.
|
|
189
|
+
|
|
190
|
+
### When to build one
|
|
191
|
+
|
|
192
|
+
Content the creator (or you) keeps returning to edit by hand — a catalog of
|
|
193
|
+
entities, level data, sequences, dialogue — earns an editor once it's clear
|
|
194
|
+
iteration will continue. Data that is written once, or generated by code,
|
|
195
|
+
stays code. A value that is tuned while playing belongs in the game's own UI
|
|
196
|
+
or a debug overlay, not in a file editor. Never let building one delay a
|
|
197
|
+
playable change the user asked for — it rides alongside, and it needs the
|
|
198
|
+
user's yes first.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html>
|
|
3
|
+
<head>
|
|
4
|
+
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />
|
|
5
|
+
<meta name="color-scheme" content="dark" />
|
|
6
|
+
<title>blank kit</title>
|
|
7
|
+
<style>
|
|
8
|
+
html {
|
|
9
|
+
color-scheme: dark;
|
|
10
|
+
background: #0a0a0a;
|
|
11
|
+
}
|
|
12
|
+
body {
|
|
13
|
+
margin: 0;
|
|
14
|
+
height: 100vh;
|
|
15
|
+
display: flex;
|
|
16
|
+
flex-direction: column;
|
|
17
|
+
align-items: center;
|
|
18
|
+
justify-content: center;
|
|
19
|
+
gap: 12px;
|
|
20
|
+
font-family: system-ui, sans-serif;
|
|
21
|
+
color: #fff;
|
|
22
|
+
text-align: center;
|
|
23
|
+
padding: 24px;
|
|
24
|
+
box-sizing: border-box;
|
|
25
|
+
}
|
|
26
|
+
p {
|
|
27
|
+
margin: 0;
|
|
28
|
+
max-width: 22em;
|
|
29
|
+
color: #999;
|
|
30
|
+
font-size: 15px;
|
|
31
|
+
line-height: 1.5;
|
|
32
|
+
}
|
|
33
|
+
</style>
|
|
34
|
+
</head>
|
|
35
|
+
<body>
|
|
36
|
+
<h1>blank</h1>
|
|
37
|
+
<p>
|
|
38
|
+
The authoring guide for a Castle deck built on no framework. Decks import this for
|
|
39
|
+
<code>CLAUDE.md</code>; there is no code here to run.
|
|
40
|
+
</p>
|
|
41
|
+
</body>
|
|
42
|
+
</html>
|
|
@@ -22,14 +22,10 @@ Do you already know what you want to make, or do you want to figure it out toget
|
|
|
22
22
|
- Every actor is an instance of a **blueprint** (`blueprints/*.scene`) — see `## Blueprints` below. Always author the blueprint file yourself and reference it via `"blueprint"`. Don't write inline actors (full `components`, no `blueprint` field): the editor auto-migrates each one into its own new blueprint file on open, one per actor with no dedup, which litters the deck with junk blueprints.
|
|
23
23
|
- Real game objects and scenery should usually be editable sprites: generate `.sprite` with `npm run draw -- name`, then place it via a `Sprite` component pointing at `drawings/name.sprite`. Dynamic UI/effects stay procedural.
|
|
24
24
|
- A deck can also hold uploaded media (the Files panel's Upload button): `Sprite` draws image files as well as `.sprite`, and `Video` plays video files. Point their `file` at the deck path (`assets/logo.png`). For audio see `## Sound` below -- sound effects need no component at all.
|
|
25
|
-
- **Supported media formats are exactly**: `.png` `.jpg` `.jpeg` `.gif` `.webp` `.svg` images, `.mp3` `.wav` `.m4a` audio, `.mp4` (H.264) video. 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.
|
|
26
25
|
- This kit is plain JavaScript. Use `.jsx` for files with JSX, `.js` otherwise; do not add TypeScript files or a new build step.
|
|
27
|
-
- Do not reload the deck after an edit. Nothing auto-reloads any more: the person applies your changes when they are ready, from the Play panel's restart button or a panel's own reload control.
|
|
28
26
|
- Space is reserved by the editor for play/stop; do not bind Space to gameplay.
|
|
29
27
|
- Do not read `engine/`, `editors/`, or built-in behaviors (`Layout.jsx`, `Sprite.jsx`, `Collider.jsx`, `Camera.jsx`, and the physics ones — `RigidBody.jsx`, `Joints.jsx`, `Draggable.jsx`, `Slingshot.jsx`, `AnalogStick.jsx`) to build a game. Their public API is documented below. Forking is the exception: when you're deliberately copying a kit file into the deck to change it — an editor (see `## Editors`) or a behavior you're shadowing — read the original. `engine/` stays off-limits either way.
|
|
30
|
-
- 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 in `## Editors` below. Kit editors under `imports/` are read-only; add or fork, don't edit.
|
|
31
28
|
- An editor is for content FILES the creator keeps coming back to (catalogs, dialogue, level tables) that nothing already opens. Scenes, sprites and styles have editors; per-actor settings belong on behavior props in the inspector — not in a new editor.
|
|
32
|
-
- Unprompted, an editor is an offer, never a build: when the same data keeps getting edited by hand, propose one and build on the user's yes. Never during a first build.
|
|
33
29
|
- Details below: `## Behavior shape`, `## Scene file`, `## Blueprints`, `## Built-in behaviors`, `## Creating pixel art`, `## SceneRuntime API`, and `## Input shortcuts`.
|
|
34
30
|
|
|
35
31
|
## Editors
|
|
@@ -64,8 +64,7 @@ export class Sprite {
|
|
|
64
64
|
const sequence = frameSequence(sprite, tag);
|
|
65
65
|
const state = ensureAnimState(actor, sprite, this.props, sequence);
|
|
66
66
|
if (!this.props.playing) {
|
|
67
|
-
resetAnimState(state
|
|
68
|
-
state.frameIndex = 0;
|
|
67
|
+
if (state.done) resetAnimState(state);
|
|
69
68
|
return;
|
|
70
69
|
}
|
|
71
70
|
advanceAnim(state, sprite, sequence, tag, dt);
|
|
@@ -389,12 +388,11 @@ function ensureAnimState(actor, sprite, props, sequence) {
|
|
|
389
388
|
return state;
|
|
390
389
|
}
|
|
391
390
|
|
|
392
|
-
function resetAnimState(state
|
|
391
|
+
function resetAnimState(state) {
|
|
393
392
|
state.pos = 0;
|
|
394
393
|
state.elapsedMs = 0;
|
|
395
394
|
state.loops = 0;
|
|
396
395
|
state.done = false;
|
|
397
|
-
state.frameIndex = sequence[0];
|
|
398
396
|
}
|
|
399
397
|
|
|
400
398
|
// Advance the playhead by `dt` seconds, stepping frames by their durationMs and
|
|
@@ -74,9 +74,8 @@ bottom }`; any ref can pick a frame of a multi-frame pxart with
|
|
|
74
74
|
- Controls are tank-style: W/S (or up/down) walk forward/back along facing,
|
|
75
75
|
A/D (or left/right) turn; a pointer/touch drag is a virtual stick where the
|
|
76
76
|
drag angle blends walking and turning. Space jumps.
|
|
77
|
-
-
|
|
78
|
-
|
|
79
|
-
reloading a panel someone is working in loses their place.
|
|
77
|
+
- Data edits (scenes, drawings, models) appear in the open editors on their
|
|
78
|
+
own; a code edit shows when the person applies it.
|
|
80
79
|
- After a coherent change: `npm run check` (lint + duplicate gate +
|
|
81
80
|
single-file bundle) must pass.
|
|
82
81
|
|
package/package.json
CHANGED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export declare const COMMON_INSTRUCTIONS = "## Imports are read-only (every deck)\n\n- **`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\" \u2014 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.\n- **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.\n- **`castle-web list-decks [--kind mine|saved|kits]` is how you find out WHAT can be imported** \u2014 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.\n- **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.\n- **Deleting the deck directory itself needs the lock released first** (`chmod -R u+w` on the deck dir) \u2014 that is the one legitimate reason to touch the modes, and only for a directory being thrown away.\n\n## Assets (every deck)\n\n- **Load static assets (drawings, audio, etc.) through the bundler \u2014 never runtime-`fetch` a loose file path.** Use a static `import`, `import.meta.glob('./drawings/*.svg', { eager: true, import: 'default' })`, or inline the asset directly. The dev serve happens to serve loose files over HTTP, so `fetch('drawings/qb.svg')` looks like it works locally \u2014 but `save-deck` bundles the whole deck into a single file, loose files are no longer served, and the fetch silently fails on every platform. Kit decks: use the kit's own drawing/asset-loading APIs instead of a raw `fetch`.\n\n## Touch controls (every deck)\n\n- **Playable on a touchscreen, with only the controls the game actually needs.** Castle decks are played on phones, so whatever input a game does use must work by touch \u2014 direct tap/drag on the game itself wherever possible, and on-screen buttons only where the mechanics genuinely call for them. Do NOT add controls a game doesn't need: never drop in a generic d-pad or movement overlay by default. Prefer touching the game directly over an overlay that just mirrors keyboard keys. Keyboard input is fine to support on top for desktop play. Match the controls to the actual mechanics \u2014 a game with no directional movement should have no movement controls at all.\n\n## Fit the card (every deck)\n\n- **The deck plays inside a fixed 5:7 portrait card, not the full window.** The card is sized to fit the screen (at most about 450x630px), clips overflow, and does not scroll. Design the whole layout to fit inside that portrait box: size UI relative to the card with percentages, flex/grid, `min()`, `clamp()`, or viewport-relative units instead of fixed tall panels. Let playfields scale down on smaller cards rather than overflowing; anything outside the card edges is cut off. The SDK exports `CARD_RATIO` (= 5 / 7) if you need the exact ratio.\n- **Hand-rolled `<canvas>` elements must account for devicePixelRatio, or the game looks blurry on phones.** Size the backing store to the CSS layout size times `devicePixelRatio` (e.g. `canvas.width = rect.width * dpr`), keep the CSS width/height as the layout size, and scale the 2D context (`ctx.scale(dpr, dpr)`) so drawing code stays in CSS units \u2014 re-apply on resize. Kit decks don't need to do this by hand; the kit's engine already configures its canvas for DPR.\n - Exception: deliberate pixel art wants a fixed low-resolution backing store with `image-rendering: pixelated` CSS instead \u2014 don't DPR-scale that; the crisp chunky look is the point.\n";
|
|
@@ -1,26 +0,0 @@
|
|
|
1
|
-
// Common agent guidance appended by `castle-web init` to every scaffolded
|
|
2
|
-
// deck's CLAUDE.md, regardless of kit (or no kit). Single source of truth —
|
|
3
|
-
// edit here, not in the kits. Keep it truly kit-agnostic; kit-specific rules
|
|
4
|
-
// (e.g. Space being reserved for play/stop) live in each kit's own CLAUDE.md.
|
|
5
|
-
export const COMMON_INSTRUCTIONS = `## Imports are read-only (every deck)
|
|
6
|
-
|
|
7
|
-
- **\`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.
|
|
8
|
-
- **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.
|
|
9
|
-
- **\`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.
|
|
10
|
-
- **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.
|
|
11
|
-
- **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.
|
|
12
|
-
|
|
13
|
-
## Assets (every deck)
|
|
14
|
-
|
|
15
|
-
- **Load static assets (drawings, audio, etc.) through the bundler — never runtime-\`fetch\` a loose file path.** Use a static \`import\`, \`import.meta.glob('./drawings/*.svg', { eager: true, import: 'default' })\`, or inline the asset directly. The dev serve happens to serve loose files over HTTP, so \`fetch('drawings/qb.svg')\` looks like it works locally — but \`save-deck\` bundles the whole deck into a single file, loose files are no longer served, and the fetch silently fails on every platform. Kit decks: use the kit's own drawing/asset-loading APIs instead of a raw \`fetch\`.
|
|
16
|
-
|
|
17
|
-
## Touch controls (every deck)
|
|
18
|
-
|
|
19
|
-
- **Playable on a touchscreen, with only the controls the game actually needs.** Castle decks are played on phones, so whatever input a game does use must work by touch — direct tap/drag on the game itself wherever possible, and on-screen buttons only where the mechanics genuinely call for them. Do NOT add controls a game doesn't need: never drop in a generic d-pad or movement overlay by default. Prefer touching the game directly over an overlay that just mirrors keyboard keys. Keyboard input is fine to support on top for desktop play. Match the controls to the actual mechanics — a game with no directional movement should have no movement controls at all.
|
|
20
|
-
|
|
21
|
-
## Fit the card (every deck)
|
|
22
|
-
|
|
23
|
-
- **The deck plays inside a fixed 5:7 portrait card, not the full window.** The card is sized to fit the screen (at most about 450x630px), clips overflow, and does not scroll. Design the whole layout to fit inside that portrait box: size UI relative to the card with percentages, flex/grid, \`min()\`, \`clamp()\`, or viewport-relative units instead of fixed tall panels. Let playfields scale down on smaller cards rather than overflowing; anything outside the card edges is cut off. The SDK exports \`CARD_RATIO\` (= 5 / 7) if you need the exact ratio.
|
|
24
|
-
- **Hand-rolled \`<canvas>\` elements must account for devicePixelRatio, or the game looks blurry on phones.** Size the backing store to the CSS layout size times \`devicePixelRatio\` (e.g. \`canvas.width = rect.width * dpr\`), keep the CSS width/height as the layout size, and scale the 2D context (\`ctx.scale(dpr, dpr)\`) so drawing code stays in CSS units — re-apply on resize. Kit decks don't need to do this by hand; the kit's engine already configures its canvas for DPR.
|
|
25
|
-
- Exception: deliberate pixel art wants a fixed low-resolution backing store with \`image-rendering: pixelated\` CSS instead — don't DPR-scale that; the crisp chunky look is the point.
|
|
26
|
-
`;
|