castle-web-cli 0.4.76 → 0.4.77

package/dist/commonInstructions.d.ts

@@ -1 +1 @@
-export declare const COMMON_INSTRUCTIONS = "## 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";
+export declare const COMMON_INSTRUCTIONS = "## 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";

package/dist/commonInstructions.js

@@ -2,11 +2,17 @@
 // deck's CLAUDE.md, regardless of kit (or no kit). Single source of truth —
 // edit here, not in the kits. Keep it truly kit-agnostic; kit-specific rules
 // (e.g. Space being reserved for play/stop) live in each kit's own CLAUDE.md.
-export const COMMON_INSTRUCTIONS = `## Touch controls (every deck)
+export const COMMON_INSTRUCTIONS = `## Assets (every deck)
+
+- **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\`.
+
+## Touch controls (every deck)
 
 - **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.
 
 ## Fit the card (every deck)
 
 - **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.
+- **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.
+  - 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.
 `;

package/dist/filesChanged.d.ts

@@ -0,0 +1,25 @@
+import type { ViteDevServer } from 'vite';
+export interface FileChangeEntry {
+    /** Deck-relative POSIX path. */
+    path: string;
+    event: 'add' | 'change' | 'delete';
+    /**
+     * Deck-relative paths of modules affected via the Vite import graph: the
+     * changed file itself (when it's part of the module graph) plus every
+     * transitive importer. Empty when the file isn't imported by anything.
+     */
+    affected: string[];
+}
+export interface FilesChangedMessage {
+    type: 'files_changed';
+    changes: FileChangeEntry[];
+    /** Union of every change's path + affected set, deduped. */
+    affected: string[];
+}
+export declare function installFilesChangedWatcher(opts: {
+    vite: ViteDevServer;
+    projectDir: string;
+    broadcast: (msg: FilesChangedMessage) => void;
+    /** Drop Vite transform caches (so `import.meta.glob` rescans new files). */
+    invalidate: () => void;
+}): void;

package/dist/filesChanged.js

@@ -0,0 +1,140 @@
+// Serve-side files-changed broadcast. Watches the deck dir through Vite's own
+// chokidar watcher (one watcher for everything), coalesces bursts of fs events
+// into a single `files_changed` message, and folds in the Vite module graph:
+// each change carries the transitive importer closure of the changed file, so
+// consumers can tell "code my bundle depends on changed" apart from "a loose
+// file changed". Vite's own HMR stays fully OFF (`server.hmr: false` in
+// serve.ts) — reload decisions belong to consumers (the kit engine, editors,
+// the shell), not to Vite.
+import * as path from 'path';
+const IGNORED_SEGMENTS = new Set(['node_modules', '.castle', '.git']);
+// Coalescing: a burst of writes (agent editing several files, an editor's
+// debounced saves landing together) becomes one message. DEBOUNCE resets per
+// event; MAX bounds total latency under a sustained stream.
+const DEBOUNCE_MS = 100;
+const MAX_WAIT_MS = 500;
+export function installFilesChangedWatcher(opts) {
+    const { vite, projectDir, broadcast, invalidate } = opts;
+    const pending = new Map();
+    let debounceTimer = null;
+    let maxTimer = null;
+    const flush = () => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        if (maxTimer)
+            clearTimeout(maxTimer);
+        debounceTimer = null;
+        maxTimer = null;
+        if (pending.size === 0)
+            return;
+        const changes = [...pending.entries()]
+            .map(([relPath, change]) => ({
+            path: relPath,
+            event: change.event,
+            affected: [...change.affected].sort(),
+        }))
+            .sort((a, b) => a.path.localeCompare(b.path));
+        pending.clear();
+        // New/deleted files can be picked up by `import.meta.glob` importers whose
+        // cached transforms wouldn't rescan; drop caches like `restart` does.
+        if (changes.some((c) => c.event !== 'change'))
+            invalidate();
+        const affected = new Set();
+        for (const change of changes) {
+            affected.add(change.path);
+            for (const p of change.affected)
+                affected.add(p);
+        }
+        broadcast({ type: 'files_changed', changes, affected: [...affected].sort() });
+    };
+    const schedule = () => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(flush, DEBOUNCE_MS);
+        if (!maxTimer)
+            maxTimer = setTimeout(flush, MAX_WAIT_MS);
+    };
+    vite.watcher.on('all', (watchEvent, absFile) => {
+        const event = watchEvent === 'add' || watchEvent === 'change'
+            ? watchEvent
+            : watchEvent === 'unlink'
+                ? 'delete'
+                : null;
+        if (!event)
+            return; // addDir / unlinkDir
+        const relPath = deckRelative(projectDir, absFile);
+        if (!relPath)
+            return;
+        // Compute the importer closure at event time: for deletes, Vite prunes the
+        // file's graph entry shortly after the event, so waiting until flush would
+        // lose the edges.
+        const affected = importerClosure(vite, projectDir, absFile);
+        const existing = pending.get(relPath);
+        if (existing) {
+            // Merge events: a file created then edited within the window is still an
+            // 'add' for consumers; otherwise the newest event wins.
+            if (!(existing.event === 'add' && event === 'change'))
+                existing.event = event;
+            for (const p of affected)
+                existing.affected.add(p);
+        }
+        else {
+            pending.set(relPath, { event, affected: new Set(affected) });
+        }
+        schedule();
+    });
+}
+// Deck-relative POSIX path, or null when the file is outside the deck or under
+// an ignored directory.
+function deckRelative(projectDir, absFile) {
+    const rel = path.relative(projectDir, absFile);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+        return null;
+    const posix = rel.split(path.sep).join('/');
+    if (posix.split('/').some((segment) => IGNORED_SEGMENTS.has(segment)))
+        return null;
+    return posix;
+}
+function clientModuleGraph(vite) {
+    try {
+        const graph = vite
+            .environments?.client?.moduleGraph ?? vite.moduleGraph;
+        return graph ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// Deck-relative paths of the changed file's modules plus all transitive
+// importers. Empty when the file isn't part of the module graph.
+function importerClosure(vite, projectDir, absFile) {
+    const graph = clientModuleGraph(vite);
+    if (!graph)
+        return [];
+    let start;
+    try {
+        start = graph.getModulesByFile(absFile);
+    }
+    catch {
+        return [];
+    }
+    if (!start || start.size === 0)
+        return [];
+    const seen = new Set();
+    const files = new Set();
+    const queue = [...start];
+    while (queue.length > 0) {
+        const mod = queue.pop();
+        if (seen.has(mod))
+            continue;
+        seen.add(mod);
+        if (mod.file) {
+            const rel = deckRelative(projectDir, mod.file);
+            if (rel)
+                files.add(rel);
+        }
+        for (const importer of mod.importers ?? [])
+            queue.push(importer);
+    }
+    return [...files];
+}

package/dist/init.js

@@ -35,7 +35,7 @@ const DEFAULT_KIT = "basic-2d";
 // Registry version of castle-web-sdk to inject when scaffolding from a
 // globally-installed castle-web (not from inside the workspace). Bumped
 // alongside cli/sdk version bumps.
-const PUBLISHED_SDK_VERSION = "0.4.8";
+const PUBLISHED_SDK_VERSION = "0.4.9";
 // Never copied into a fresh deck: build/dependency junk. castle.json IS copied
 // (the kit ships a config-only one with the editor layout / file filters), but
 // `scaffoldFromKit` strips any identity fields off it first -- a fresh deck has

package/dist/serve.js

@@ -7,6 +7,7 @@ import { WebSocketServer, WebSocket } from 'ws';
 import { createIdeServer } from './ide.js';
 import { createAgentServer } from './agent.js';
 import { sceneFilesPlugin } from './vitePlugins.js';
+import { installFilesChangedWatcher } from './filesChanged.js';
 import * as config from './config.js';
 import { graphql as castleGraphql } from './api.js';
 import { executeCommand } from './castle-host/host.js';
@@ -240,7 +241,7 @@ export async function serve(dir, options = {}) {
     // The WS server forwards `restart` to the browser, but it also needs the
     // Vite instance so it can drop transform caches first (see invalidateModuleCaches).
     const viteHolder = { vite: null };
-    startWSServer(wsPort, projectDir, logFile, screenshotsDir, viteHolder);
+    const { broadcast } = startWSServer(wsPort, projectDir, logFile, screenshotsDir, viteHolder);
     // The deck root `/` serves a split-view shell: the deck in an iframe plus a
     // toggle button for an xterm.js terminal. The terminal's PTY is lazy -- it
     // spawns only when a browser first opens the PTY WebSocket.
@@ -279,6 +280,14 @@ export async function serve(dir, options = {}) {
         logLevel: 'info',
     });
     viteHolder.vite = vite;
+    // File changes from ANY source (editors, agents, terminal) become one
+    // coalesced `files_changed` broadcast; consumers decide what to reload.
+    installFilesChangedWatcher({
+        vite,
+        projectDir,
+        broadcast,
+        invalidate: () => invalidateModuleCaches(vite),
+    });
     await vite.listen();
     // The PTY WebSocket upgrade is handled directly on Vite's HTTP server rather
     // than through Vite's proxy (Vite's ws proxy didn't forward this path).
@@ -374,6 +383,13 @@ async function serveDetached(projectDir, options) {
 function startWSServer(port, projectDir, logFile, screenshotsDir, viteHolder) {
     const wss = new WebSocketServer({ port });
     const clients = new Set();
+    const broadcast = (msg) => {
+        const data = JSON.stringify(msg);
+        for (const c of clients) {
+            if (c.readyState === WebSocket.OPEN)
+                c.send(data);
+        }
+    };
     // For round-trip requests (e.g. screenshot), remember which socket issued a
     // given requestId so the matching response is routed back to just that
     // client instead of broadcast to every tab/CLI. Mirrors how `write_file`
@@ -491,7 +507,7 @@ function startWSServer(port, projectDir, logFile, screenshotsDir, viteHolder) {
             }
         });
     });
-    return wss;
+    return { wss, broadcast };
 }
 function writeProjectFile(projectDir, requestedPath, contents) {
     if (typeof requestedPath !== 'string' || requestedPath.trim() === '') {