castle-web-cli 0.4.115 → 0.4.117

package/dist/castleJson.d.ts

@@ -10,7 +10,13 @@ export interface CastleJson {
     cardId?: string;
     imports?: Record<string, DeckImport>;
     autoUpdateWhenImported?: boolean;
+    main?: string;
+    starterScene?: string;
     [key: string]: unknown;
 }
+export declare const DEFAULT_STARTER_SCENE = "scenes/main.scene";
+export declare function deckStarterScene(dir: string): string;
+export declare const DEFAULT_MAIN = "main.jsx";
+export declare function deckMainFile(dir: string): string;
 export declare function readCastleJson(dir: string): CastleJson | null;
 export declare function readCastleJsonOrThrow(dir: string): CastleJson | null;

package/dist/castleJson.js

@@ -1,5 +1,15 @@
 import * as fs from 'fs';
 import * as path from 'path';
+export const DEFAULT_STARTER_SCENE = 'scenes/main.scene';
+export function deckStarterScene(dir) {
+    const declared = readCastleJson(dir)?.starterScene;
+    return typeof declared === 'string' && declared.trim() ? declared.trim() : DEFAULT_STARTER_SCENE;
+}
+export const DEFAULT_MAIN = 'main.jsx';
+export function deckMainFile(dir) {
+    const declared = readCastleJson(dir)?.main;
+    return typeof declared === 'string' && declared.trim() ? declared.trim() : DEFAULT_MAIN;
+}
 // A missing castle.json is normal (a deck has none until its first save), so it
 // reads as `null` rather than an error. An unparseable one is not -- `onInvalid`
 // is how a caller says whether that should be fatal here or just another `null`.

package/dist/editorConfig.js

@@ -10,8 +10,9 @@
 // sits there like any other), so resolving is a read of each import's own
 // castle.json -- there is no graph to walk.
 //
-// Everything else in the block (`initialPanels`, `visiblePaths`/`hiddenPaths`,
-// `defaultPlayFile`) stays the deck's own, read from the deck root only.
+// `initialPanels` and `visiblePaths`/`hiddenPaths` stay the deck's own, read from
+// the deck root only. `defaultPlayFile` falls back to an import's when the deck
+// names none -- see `importedDefaultPlayFile`.
 import * as fs from 'fs';
 import * as path from 'path';
 import { readCastleJson } from './castleJson.js';
@@ -48,9 +49,32 @@ export function readEditorConfig(deckDir) {
         visiblePaths: asStringArray(editor.visiblePaths),
         fileTypes: asFileTypes(editor.fileTypes),
         extensions: asStringArray(editor.extensions) ?? asStringArray(data.editorExtensions),
-        defaultPlayFile: typeof editor.defaultPlayFile === 'string' ? editor.defaultPlayFile : undefined,
+        defaultPlayFile: typeof editor.defaultPlayFile === 'string'
+            ? editor.defaultPlayFile
+            : importedDefaultPlayFile(deckDir),
     };
 }
+// Which scene the play panel opens with, when the deck names none itself. Only a
+// scene kit has the concept, and a deck that imported one has its scenes without
+// having said so -- without this the panel loads the kit's runtime with no scene
+// and paints nothing, which reads as "the deck is broken".
+//
+// The deck's own value always wins; this is the fallback, and it is deliberately
+// the only other field resolved across imports, because it names a file that
+// must exist in THIS deck (the starter scene the kit's own scaffold wrote).
+function importedDefaultPlayFile(deckDir) {
+    for (const alias of importAliases(deckDir)) {
+        const value = readCastleJson(path.join(deckDir, IMPORTS_DIR, alias))?.editor;
+        const declared = value && typeof value === 'object'
+            ? value.defaultPlayFile
+            : undefined;
+        if (typeof declared !== 'string' || !declared.trim())
+            continue;
+        if (fs.existsSync(path.join(deckDir, declared.trim())))
+            return declared.trim();
+    }
+    return undefined;
+}
 // The deck's imports, in the order the deck pinned them (its castle.json
 // `imports` map), then anything on disk that isn't pinned. Pin order puts an
 // import the deck asked for ahead of one that came in behind it, which is the

package/dist/imports.d.ts

@@ -26,6 +26,10 @@ export interface AddImportResult {
     transitive: string[];
     /** `name@range (from alias)` entries merged into the deck's package.json. */
     dependencies: string[];
+    /** The import's declared main, when this deck adopted it as its entry. */
+    adoptedMain: string | null;
+    /** Set when the import declares a main but this deck already has work in it. */
+    offersMain: string | null;
 }
 export declare function addImportTo(dir: string, options?: {
     deckRef?: string;

package/dist/imports.js

@@ -80,11 +80,7 @@ function slugifyAlias(name) {
 // An explicit `--as` may already be qualified (`someone.their-deck`); slugify
 // each part so the separator survives.
 function slugifyGivenAlias(name) {
-    return name
-        .split('.')
-        .map(slugifyAlias)
-        .filter(Boolean)
-        .join('.');
+    return name.split('.').map(slugifyAlias).filter(Boolean).join('.');
 }
 // Aliases are qualified by author -- `lovefromtom.fish-town` -- because deck
 // titles are not unique across users (nor even within one), and an import's name
@@ -255,7 +251,8 @@ export async function restoreMissingImports(deckDir) {
             fs.cpSync(kitDir, destDir, {
                 recursive: true,
                 verbatimSymlinks: true,
-                filter: (src) => src === kitDir || !['node_modules', '.castle', 'dist', '.git'].includes(path.basename(src)),
+                filter: (src) => src === kitDir ||
+                    !['node_modules', '.castle', 'dist', '.git'].includes(path.basename(src)),
             });
         }
         else {
@@ -438,7 +435,9 @@ async function addTransitiveImports(deckDir, viaAlias, seen) {
 // loop on a cycle.
 export function importedDeckIds(deckDir) {
     const pins = readCastleJson(deckDir)?.imports ?? {};
-    return new Set(Object.values(pins).map((p) => p?.deckId).filter((id) => !!id));
+    return new Set(Object.values(pins)
+        .map((p) => p?.deckId)
+        .filter((id) => !!id));
 }
 // The import itself. Throws ImportError rather than exiting, because this also
 // runs inside the serve (from the editor's Import panel), where taking the
@@ -477,7 +476,52 @@ export async function addImportTo(dir, options = {}) {
     const { replaced } = await placeImport(targetDir, alias, deckId, source);
     const transitive = await addTransitiveImports(targetDir, alias, importedDeckIds(targetDir));
     const dependencies = syncImportDependencies(targetDir);
-    return { deckId, alias, replaced, transitive, dependencies };
+    // A kit declares its entry module (castle.json `main`). Importing one into a
+    // deck that is still the untouched `--kit none` scaffold means "start from this
+    // kit", so adopt its entry -- otherwise the deck keeps booting its own stub and
+    // the kit's runtime and editors never mount. A deck with any work in it is left
+    // alone and just told the option exists, since repointing it would go dark.
+    const importDir = path.join(targetDir, IMPORTS_DIR, alias);
+    const declaredMain = tryReadCastleJson(importDir)?.main;
+    let adoptedMain = null;
+    if (typeof declaredMain === 'string' && declaredMain.trim()) {
+        const { isPristineBareDeck, adoptImportEntry, writeStarterScene } = await import('./init.js');
+        if (isPristineBareDeck(targetDir)) {
+            adoptImportEntry(targetDir, alias, declaredMain.trim());
+            adoptedMain = declaredMain.trim();
+            // A kit's runtime with no scene to run is a blank screen, and the agent
+            // has nothing to edit. Give the deck the kit's own starter, same as
+            // `init --kit`. Only when the deck has no scenes -- never overwrite.
+            if (!fs.existsSync(path.join(targetDir, 'scenes'))) {
+                try {
+                    writeStarterScene(targetDir, importDir, alias);
+                }
+                catch (e) {
+                    console.warn(`Adopted ${alias} but could not write its starter scene: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+        }
+    }
+    // An import's packages have to be ON DISK, not just named in package.json:
+    // the deck fails to load the moment its code imports one. Telling the caller
+    // to run `castle-web install` only worked for the CLI -- an import taken from
+    // the editor left the deck broken with no visible reason why.
+    if (dependencies.length > 0) {
+        try {
+            // Imported here rather than at the top: install.ts imports THIS module,
+            // and a top-level import back would be a cycle.
+            const { installDeps } = await import('./install.js');
+            await installDeps(targetDir, false);
+        }
+        catch (e) {
+            // Never fail the import over this: the files are already in place, and a
+            // hand-run install still fixes it.
+            console.warn(`Imported ${alias}, but installing its dependencies failed -- run \`castle-web install\`. ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    const trimmedMain = typeof declaredMain === 'string' && declaredMain.trim() ? declaredMain.trim() : null;
+    const offersMain = trimmedMain && !adoptedMain ? trimmedMain : null;
+    return { deckId, alias, replaced, transitive, dependencies, adoptedMain, offersMain };
 }
 export async function addImport(dir, options = {}) {
     let result;
@@ -500,8 +544,13 @@ export async function addImport(dir, options = {}) {
     }
     for (const dep of result.dependencies)
         console.log(`Added dependency ${dep}`);
-    if (result.dependencies.length > 0)
-        console.log('Run `castle-web install` to install them.');
+    if (result.adoptedMain) {
+        console.log(`This deck now runs ${result.alias} (index.html -> ${result.adoptedMain}).`);
+    }
+    else if (result.offersMain) {
+        console.log(`${result.alias} is a kit. To run this deck on it, point index.html at ` +
+            `/${IMPORTS_DIR}/${result.alias}/${result.offersMain}.`);
+    }
 }
 // Take one import's update: replace its files with the version the server has
 // now, then follow that version's own pins for anything newly required. Both

package/dist/init.d.ts

@@ -5,7 +5,10 @@ export declare function resolveScaffoldRefs(): {
     cliDistAbs: string | null;
     sdkPathPosix: string | null;
 };
+export declare function isPristineBareDeck(dir: string): boolean;
+export declare function adoptImportEntry(deckDir: string, alias: string, mainFile: string): void;
 export declare function getCliVersion(): string;
+export declare function writeStarterScene(projectDir: string, kitDir: string, alias: string): void;
 export declare function init(dir: string, opts?: {
     kit?: string;
     serve?: boolean;

package/dist/init.js

@@ -1,10 +1,11 @@
-import * as fs from "fs";
-import * as path from "path";
-import { COMMON_INSTRUCTIONS } from "./commonInstructions.js";
-import { installDeps } from "./install.js";
-import { IMPORTS_DIR, lockImportTree } from "./imports.js";
-import { getCliEntryPath, getKitsDir, getRepoRoot, getSdkPackagePath, toPosixPath, } from "./localPaths.js";
-import { serve } from "./serve.js";
+import * as fs from 'fs';
+import * as path from 'path';
+import { COMMON_INSTRUCTIONS } from './commonInstructions.js';
+import { installDeps } from './install.js';
+import { deckMainFile, deckStarterScene } from './castleJson.js';
+import { IMPORTS_DIR, lockImportTree } from './imports.js';
+import { getCliEntryPath, getKitsDir, getRepoRoot, getSdkPackagePath, toPosixPath, } from './localPaths.js';
+import { serve } from './serve.js';
 const INDEX_HTML = `<!DOCTYPE html>
 <html>
 <head>
@@ -32,27 +33,22 @@ card.appendChild(el);
 `;
 // Default kit imported by `init` when no --kit is given. `none`/`bare` skip the
 // kit and produce the minimal index.html + game.js stub above.
-const DEFAULT_KIT = "physics-2d";
+const DEFAULT_KIT = 'physics-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.12";
+const PUBLISHED_SDK_VERSION = '0.4.12';
 // The account the first-party kits are (to be) published under, so a kit
 // imported from the CLI's copy is named the same as one fetched from the server.
-const KIT_AUTHOR = "castle";
+const KIT_AUTHOR = 'castle';
 // Never copied into a deck's import: build/dependency junk.
-const KIT_COPY_EXCLUDE = new Set([
-    "node_modules",
-    ".castle",
-    "dist",
-    ".git",
-]);
+const KIT_COPY_EXCLUDE = new Set(['node_modules', '.castle', 'dist', '.git']);
 // The bare (`--kit none`) deck's default editor config: just the Files panel and
 // a Play panel. No file filtering -- a bare deck is hand-rolled, so the author
 // knows what's there; show everything for now.
 const BARE_CASTLE_JSON = {
     editor: {
-        initialPanels: [{ type: "files" }, { type: "playtest" }],
+        initialPanels: [{ type: 'files' }, { type: 'playtest' }],
         hiddenPaths: [],
         visiblePaths: [],
     },
@@ -70,17 +66,11 @@ export function resolveScaffoldRefs() {
     // npm package and need the published refs + `castle-web` binary.
     const workspaceMode = fs.existsSync(sdkPath);
     const sdkPathPosix = workspaceMode ? toPosixPath(sdkPath) : null;
-    const cliDistAbs = workspaceMode
-        ? toPosixPath(path.dirname(getCliEntryPath()))
-        : null;
+    const cliDistAbs = workspaceMode ? toPosixPath(path.dirname(getCliEntryPath())) : null;
     return {
         workspaceMode,
-        sdkRef: workspaceMode
-            ? `file:${sdkPathPosix}`
-            : `^${PUBLISHED_SDK_VERSION}`,
-        cliCommand: workspaceMode
-            ? `node ${toPosixPath(getCliEntryPath())}`
-            : "castle-web",
+        sdkRef: workspaceMode ? `file:${sdkPathPosix}` : `^${PUBLISHED_SDK_VERSION}`,
+        cliCommand: workspaceMode ? `node ${toPosixPath(getCliEntryPath())}` : 'castle-web',
         cliDistAbs,
         sdkPathPosix,
     };
@@ -90,9 +80,9 @@ function makeClaudeMd() {
     // castle-experimental-web checkout, but breaks when the scaffold lives
     // outside the repo (the relative path no longer resolves).
     const repoRoot = getRepoRoot();
-    const upstream = path.join(repoRoot, "CLAUDE.md");
+    const upstream = path.join(repoRoot, 'CLAUDE.md');
     try {
-        return fs.readFileSync(upstream, "utf8").trimEnd() + "\n";
+        return fs.readFileSync(upstream, 'utf8').trimEnd() + '\n';
     }
     catch {
         return `# Castle Experimental Web\n\nSee https://github.com/castle-xyz/castle-experimental-web for the agent guide.\n`;
@@ -102,15 +92,15 @@ function makeClaudeMd() {
 // the kit's (or bare) CLAUDE.md is written; the AGENTS.md symlink picks the
 // appended content up for free.
 function appendCommonInstructions(projectDir) {
-    const claudePath = path.join(projectDir, "CLAUDE.md");
+    const claudePath = path.join(projectDir, 'CLAUDE.md');
     const existing = fs.existsSync(claudePath)
-        ? fs.readFileSync(claudePath, "utf8").trimEnd() + "\n\n"
-        : "";
+        ? fs.readFileSync(claudePath, 'utf8').trimEnd() + '\n\n'
+        : '';
     fs.writeFileSync(claudePath, existing + COMMON_INSTRUCTIONS);
 }
 function tryMakeAgentsSymlink(agentsPath) {
     try {
-        fs.symlinkSync("CLAUDE.md", agentsPath);
+        fs.symlinkSync('CLAUDE.md', agentsPath);
     }
     catch {
         // symlink already exists / unsupported FS — non-fatal
@@ -124,11 +114,11 @@ function makeKitDeckScripts(kitDir, alias, cliCommand) {
     const scripts = {
         restart: `${cliCommand} restart .`,
         screenshot: `${cliCommand} screenshot .`,
-        "save-deck": `${cliCommand} save-deck .`,
+        'save-deck': `${cliCommand} save-deck .`,
     };
     // `draw` is a kit script, not a CLI one, so it only exists if this kit ships
     // it -- and it runs from the deck root, where the sprites belong.
-    if (fs.existsSync(path.join(kitDir, "scripts", "draw.mjs"))) {
+    if (fs.existsSync(path.join(kitDir, 'scripts', 'draw.mjs'))) {
         scripts.draw = `node ${IMPORTS_DIR}/${alias}/scripts/draw.mjs`;
     }
     return scripts;
@@ -138,38 +128,63 @@ function makePackageJson(projectDir) {
     return {
         name: path.basename(projectDir),
         private: true,
-        type: "module",
+        type: 'module',
         scripts: {
             restart: `${cliCommand} restart .`,
             screenshot: `${cliCommand} screenshot .`,
-            "save-deck": `${cliCommand} save-deck .`,
+            'save-deck': `${cliCommand} save-deck .`,
         },
         dependencies: {
-            "castle-web-sdk": sdkRef,
+            'castle-web-sdk': sdkRef,
         },
     };
 }
 // Some coding agents read AGENTS.md by convention. Symlink so they get the
 // same guidance without a duplicate copy.
 function ensureAgentsSymlink(projectDir) {
-    const agentsPath = path.join(projectDir, "AGENTS.md");
+    const agentsPath = path.join(projectDir, 'AGENTS.md');
     if (fs.lstatSync(agentsPath, { throwIfNoEntry: false }))
         return;
     // Don't create a dangling link — only symlink when CLAUDE.md is present.
-    if (!fs.existsSync(path.join(projectDir, "CLAUDE.md")))
+    if (!fs.existsSync(path.join(projectDir, 'CLAUDE.md')))
         return;
     tryMakeAgentsSymlink(agentsPath);
 }
 // Bare scaffold: a plain code-only deck with no kit framework.
+// Whether a deck is still exactly what `--kit none` produced -- both the entry
+// and the stub game it boots, untouched. `addImportTo` asks before repointing a
+// deck's entry at an imported kit: on a pristine scaffold there is nothing to
+// lose, and one edited character anywhere makes this false, so a deck someone
+// has actually worked in is never quietly taken over.
+export function isPristineBareDeck(dir) {
+    try {
+        return (fs.readFileSync(path.join(dir, 'index.html'), 'utf8') === INDEX_HTML &&
+            fs.readFileSync(path.join(dir, 'game.js'), 'utf8') === GAME_JS);
+    }
+    catch {
+        return false;
+    }
+}
+// Repoint a deck's entry at an imported deck's main module.
+//
+// Writes the SAME index.html `init --kit` writes, rather than swapping the bare
+// stub's script tag: a kit mounts React into `<div id="root">`, which the bare
+// page has no element for -- the result was a deck that loaded the kit and
+// rendered nothing -- and the bare page also lacks the dark color-scheme
+// declaration, so it painted white before the kit's CSS arrived.
+export function adoptImportEntry(deckDir, alias, mainFile) {
+    writeDeckIndexHtml(deckDir, alias, path.basename(deckDir), mainFile);
+    fs.rmSync(path.join(deckDir, 'game.js'), { force: true });
+}
 function scaffoldBare(projectDir) {
     fs.mkdirSync(projectDir, { recursive: true });
-    fs.writeFileSync(path.join(projectDir, "index.html"), INDEX_HTML);
-    fs.writeFileSync(path.join(projectDir, "game.js"), GAME_JS);
-    fs.writeFileSync(path.join(projectDir, "castle.json"), JSON.stringify(BARE_CASTLE_JSON, null, 2) + "\n");
-    fs.writeFileSync(path.join(projectDir, "CLAUDE.md"), makeClaudeMd());
+    fs.writeFileSync(path.join(projectDir, 'index.html'), INDEX_HTML);
+    fs.writeFileSync(path.join(projectDir, 'game.js'), GAME_JS);
+    fs.writeFileSync(path.join(projectDir, 'castle.json'), JSON.stringify(BARE_CASTLE_JSON, null, 2) + '\n');
+    fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), makeClaudeMd());
     appendCommonInstructions(projectDir);
     ensureAgentsSymlink(projectDir);
-    fs.writeFileSync(path.join(projectDir, "package.json"), JSON.stringify(makePackageJson(projectDir), null, 2) + "\n");
+    fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify(makePackageJson(projectDir), null, 2) + '\n');
 }
 // Copy a framework kit from kits/<kit>/ into the new deck dir, dropping
 // build/dependency junk and castle.json.
@@ -180,7 +195,7 @@ function requireKitDir(kit) {
     if (fs.existsSync(kitDir) && fs.statSync(kitDir).isDirectory())
         return kitDir;
     console.error(`Kit "${kit}" not found at ${kitDir}.`);
-    console.error("Available kits:");
+    console.error('Available kits:');
     try {
         const kits = fs
             .readdirSync(getKitsDir())
@@ -189,34 +204,34 @@ function requireKitDir(kit) {
             for (const name of kits)
                 console.error(`  ${name}`);
         else
-            console.error("  (none)");
+            console.error('  (none)');
     }
     catch {
-        console.error("  (none — kits/ directory is missing)");
+        console.error('  (none — kits/ directory is missing)');
     }
-    console.error("Or use `--kit none` for a bare code-only deck.");
+    console.error('Or use `--kit none` for a bare code-only deck.');
     return process.exit(1);
 }
 function readJsonFile(file) {
     try {
-        return JSON.parse(fs.readFileSync(file, "utf8"));
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
     }
     catch {
         return null;
     }
 }
 function writeJsonFile(file, value) {
-    fs.writeFileSync(file, JSON.stringify(value, null, 2) + "\n", "utf8");
+    fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n', 'utf8');
 }
 export function getCliVersion() {
-    const pkg = readJsonFile(path.join(getKitsDir(), "..", "package.json"));
-    return typeof pkg?.version === "string" ? pkg.version : "0.0.0";
+    const pkg = readJsonFile(path.join(getKitsDir(), '..', 'package.json'));
+    return typeof pkg?.version === 'string' ? pkg.version : '0.0.0';
 }
 // The deck's entry point is the KIT's -- the deck has no engine code of its own
 // -- so index.html points into the import. Everything the kit's main.jsx imports
 // is relative to itself, so it needs no rewriting to run from there.
-function writeDeckIndexHtml(projectDir, alias, title) {
-    fs.writeFileSync(path.join(projectDir, "index.html"), `<!doctype html>
+function writeDeckIndexHtml(projectDir, alias, title, mainFile) {
+    fs.writeFileSync(path.join(projectDir, 'index.html'), `<!doctype html>
 <html>
   <head>
     <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />
@@ -236,31 +251,34 @@ function writeDeckIndexHtml(projectDir, alias, title) {
     <div id="root"></div>
     <!-- Engine and editors come from the imported kit; this deck holds its own
          scenes, drawings and behaviors. -->
-    <script type="module" src="/${IMPORTS_DIR}/${alias}/main.jsx"></script>
+    <script type="module" src="/${IMPORTS_DIR}/${alias}/${mainFile}"></script>
   </body>
 </html>
-`, "utf8");
+`, 'utf8');
 }
 // The deck starts with its own copy of the kit's starter scene, so there is
 // something to open and edit on the first run. Refs inside it are rewritten to
 // point at the kit's copies of what they name (the scene is the deck's now, but
 // the blueprint and art it places still live in the import).
-function writeStarterScene(projectDir, kitDir, alias) {
-    const scene = readJsonFile(path.join(kitDir, "scenes", "main.scene"));
+// Give a deck the scene its kit says to start from, with every path that names a
+// kit file rewritten to reach it through the import. Exported because both
+// scaffold paths need it: `init --kit`, and adopting a kit via `add-import`.
+export function writeStarterScene(projectDir, kitDir, alias) {
+    const scene = readJsonFile(path.join(kitDir, deckStarterScene(kitDir)));
     const prefix = `${IMPORTS_DIR}/${alias}/`;
     const rewrite = (value) => {
-        if (typeof value === "string") {
+        if (typeof value === 'string') {
             return fs.existsSync(path.join(kitDir, value)) ? prefix + value : value;
         }
         if (Array.isArray(value))
             return value.map(rewrite);
-        if (value && typeof value === "object") {
+        if (value && typeof value === 'object') {
             return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, rewrite(v)]));
         }
         return value;
     };
-    fs.mkdirSync(path.join(projectDir, "scenes"), { recursive: true });
-    writeJsonFile(path.join(projectDir, "scenes", "main.scene"), scene ? rewrite(scene) : { name: "Main", actors: [] });
+    fs.mkdirSync(path.join(projectDir, 'scenes'), { recursive: true });
+    writeJsonFile(path.join(projectDir, 'scenes', 'main.scene'), scene ? rewrite(scene) : { name: 'Main', actors: [] });
 }
 function makeImportedKitClaudeMd(alias) {
     return `# Castle deck
@@ -291,10 +309,10 @@ something in the kit behaves, define your own behavior of the same name in
 function makeKitPin(kitConfig, kit) {
     const deckId = kitConfig.deckId;
     const version = kitConfig.publishedVersion;
-    if (typeof deckId === "string" && typeof version === "string") {
+    if (typeof deckId === 'string' && typeof version === 'string') {
         return { deckId, version };
     }
-    return { source: "builtin", kit, version: getCliVersion() };
+    return { source: 'builtin', kit, version: getCliVersion() };
 }
 // The kit's editor block minus `fileTypes` -- the layout and file filters a new
 // deck starts from, without the vocabulary it resolves from the kit itself.
@@ -330,10 +348,10 @@ function scaffoldFromKitImport(kit, projectDir) {
         verbatimSymlinks: true,
         filter: (src) => src === kitDir || !KIT_COPY_EXCLUDE.has(path.basename(src)),
     });
-    const kitConfig = readJsonFile(path.join(kitDir, "castle.json")) ?? {};
-    const kitPkg = readJsonFile(path.join(kitDir, "package.json")) ?? {};
-    const title = typeof kitConfig.title === "string" ? kitConfig.title : kit;
-    writeDeckIndexHtml(projectDir, alias, title);
+    const kitConfig = readJsonFile(path.join(kitDir, 'castle.json')) ?? {};
+    const kitPkg = readJsonFile(path.join(kitDir, 'package.json')) ?? {};
+    const title = typeof kitConfig.title === 'string' ? kitConfig.title : kit;
+    writeDeckIndexHtml(projectDir, alias, title, deckMainFile(kitDir));
     writeStarterScene(projectDir, kitDir, alias);
     // The deck's own castle.json: the kit's editor config (panel layout, file
     // filters) as a starting point -- it is the deck's to edit from here -- plus
@@ -344,7 +362,7 @@ function scaffoldFromKitImport(kit, projectDir) {
     // editorConfig.resolveFileTypes) -- so the kit keeps owning it, a kit fix
     // reaches the deck like any other, and a kit imported LATER contributes its
     // types too, which a copy taken at scaffold time never could.
-    writeJsonFile(path.join(projectDir, "castle.json"), {
+    writeJsonFile(path.join(projectDir, 'castle.json'), {
         ...(kitConfig.editor ? { editor: withoutFileTypes(kitConfig.editor) } : {}),
         imports: { [alias]: makeKitPin(kitConfig, kit) },
     });
@@ -355,18 +373,16 @@ function scaffoldFromKitImport(kit, projectDir) {
     const dependencies = {};
     for (const [name, range] of Object.entries(kitPkg.dependencies ?? {})) {
         dependencies[name] =
-            name === "castle-web-sdk" && String(range).startsWith("file:")
-                ? sdkRef
-                : String(range);
+            name === 'castle-web-sdk' && String(range).startsWith('file:') ? sdkRef : String(range);
     }
-    writeJsonFile(path.join(projectDir, "package.json"), {
+    writeJsonFile(path.join(projectDir, 'package.json'), {
         name: path.basename(projectDir),
         private: true,
-        type: "module",
+        type: 'module',
         scripts: makeKitDeckScripts(kitDir, alias, cliCommand),
         dependencies,
     });
-    fs.writeFileSync(path.join(projectDir, "CLAUDE.md"), makeImportedKitClaudeMd(alias));
+    fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), makeImportedKitClaudeMd(alias));
     appendCommonInstructions(projectDir);
     lockImportTree(importDir);
 }
@@ -377,14 +393,14 @@ export async function init(dir, opts = {}) {
         process.exit(1);
     }
     const kit = opts.kit ?? DEFAULT_KIT;
-    const bare = kit === "none" || kit === "bare";
+    const bare = kit === 'none' || kit === 'bare';
     if (bare) {
         scaffoldBare(projectDir);
     }
     else {
         scaffoldFromKitImport(kit, projectDir);
     }
-    console.log(`Created project in ${projectDir}/${bare ? "" : ` (from kit "${kit}")`}`);
+    console.log(`Created project in ${projectDir}/${bare ? '' : ` (from kit "${kit}")`}`);
     // Always install deps so the deck is ready to serve/edit immediately.
     // `--no-serve` only skips the serve step below (callers like the cloud
     // launcher run their own serve, but still want deps in place).
@@ -394,18 +410,18 @@ export async function init(dir, opts = {}) {
     // decks rewrite the sdk to file:../../sdk, which the shipped (published)
     // lockfile won't match -> drop it and let pnpm resolve. Bare decks have no
     // lockfile -> non-frozen.
-    const lockPath = path.join(projectDir, "pnpm-lock.yaml");
+    const lockPath = path.join(projectDir, 'pnpm-lock.yaml');
     if (resolveScaffoldRefs().workspaceMode)
         fs.rmSync(lockPath, { force: true });
     const frozen = fs.existsSync(lockPath);
-    console.log("");
+    console.log('');
     let installed = false;
     try {
-        installDeps(projectDir, frozen);
+        await installDeps(projectDir, frozen);
         installed = true;
     }
     catch {
-        console.error("dependency install failed; re-run `pnpm install` (or `npm install`) in the deck.");
+        console.error('dependency install failed; re-run `pnpm install` (or `npm install`) in the deck.');
     }
     const autoServe = opts.serve !== false;
     if (autoServe && installed) {
@@ -415,16 +431,16 @@ export async function init(dir, opts = {}) {
         // the served page; users can override host on a subsequent serve call.
         // Open in the user's default browser unless we're clearly headless (SSH
         // session) or the user has opted out via CASTLE_WEB_CLI_NO_OPEN=1.
-        const noOpen = process.env.CASTLE_WEB_CLI_NO_OPEN === "1" ||
+        const noOpen = process.env.CASTLE_WEB_CLI_NO_OPEN === '1' ||
             !!process.env.SSH_CONNECTION ||
             !!process.env.SSH_TTY;
-        await serve(projectDir, { host: "0.0.0.0", detach: true, open: !noOpen });
+        await serve(projectDir, { host: '0.0.0.0', detach: true, open: !noOpen });
         return;
     }
-    console.log("");
-    console.log("Next steps:");
+    console.log('');
+    console.log('Next steps:');
     console.log(`  cd ${dir}`);
     if (!installed)
-        console.log("  pnpm install   # or: npm install");
-    console.log("  castle-web serve .   # & in your shell to background it");
+        console.log('  pnpm install   # or: npm install');
+    console.log('  castle-web serve .   # & in your shell to background it');
 }

package/dist/install.d.ts

@@ -1,2 +1,2 @@
-export declare function installDeps(projectDir: string, frozen: boolean): void;
+export declare function installDeps(projectDir: string, frozen: boolean): Promise<void>;
 export declare function install(dir: string): Promise<void>;