castle-web-cli 0.4.141 → 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.
@@ -10,8 +10,8 @@
10
10
  <link rel="icon" type="image/png" sizes="32x32" href="/__castle/ide/favicon-32x32.png" />
11
11
  <link rel="icon" type="image/png" sizes="16x16" href="/__castle/ide/favicon-16x16.png" />
12
12
  <link rel="icon" href="/__castle/ide/favicon.ico" sizes="any" />
13
- <script type="module" crossorigin src="/__castle/ide/assets/index-BiZuc7mo.js"></script>
14
- <link rel="stylesheet" crossorigin href="/__castle/ide/assets/index-CAN0bnXn.css">
13
+ <script type="module" crossorigin src="/__castle/ide/assets/index-qbygvQIx.js"></script>
14
+ <link rel="stylesheet" crossorigin href="/__castle/ide/assets/index-CcVJjnL3.css">
15
15
  </head>
16
16
  <body>
17
17
  <div id="root"></div>
@@ -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,8 @@
1
+ {
2
+ "editor": {
3
+ "hiddenPaths": [],
4
+ "visiblePaths": ["CLAUDE.md"]
5
+ },
6
+ "autoUpdateWhenImported": true,
7
+ "title": "blank"
8
+ }
@@ -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>
@@ -0,0 +1,10 @@
1
+ {
2
+ "name": "blank",
3
+ "lockfileVersion": 3,
4
+ "requires": true,
5
+ "packages": {
6
+ "": {
7
+ "name": "blank"
8
+ }
9
+ }
10
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "name": "blank",
3
+ "private": true,
4
+ "type": "module",
5
+ "scripts": {
6
+ "check": "node --input-type=module -e \"const { bundleProject } = await import('../../cli/dist/bundle.js'); await bundleProject('.');\""
7
+ },
8
+ "dependencies": {}
9
+ }
@@ -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, sequence);
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, sequence) {
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
- - Do not reload. Data edits (scenes, drawings, models) appear in the open
78
- editors on their own. Code edits wait for the person to apply them --
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
 
@@ -30,7 +30,7 @@
30
30
  },
31
31
  "../../sdk": {
32
32
  "name": "castle-web-sdk",
33
- "version": "0.4.16",
33
+ "version": "0.4.14",
34
34
  "devDependencies": {
35
35
  "eslint": "^9.0.0",
36
36
  "jscpd": "^4.0.5",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "castle-web-cli",
3
- "version": "0.4.141",
3
+ "version": "0.4.144",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "castle-web": "./dist/index.js"
@@ -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
- `;