castle-web-cli 0.4.121 → 0.4.123

package/dist/versions.js

@@ -0,0 +1,446 @@
+// save-version / list-versions / restore-version.
+//
+// A version is a manual commit of the deck's files. Storage details are in
+// versionStore.ts; this file is the behavior:
+//
+//   save-version              hashes the whole tree and records what moved
+//   save-version <paths...>   records ONLY those paths -- a curated state, not
+//                             the working tree at that moment
+//   list-versions [<id>]      walks back from head (or from the given version)
+//   restore-version <id>      puts the working tree back to that version,
+//                             touching only paths some later version touched
+import * as fs from 'fs';
+import * as path from 'path';
+import { customAlphabet } from 'nanoid';
+import { looksBinary, unifiedDiff } from './diffText.js';
+import { COVER_FILE } from './localPaths.js';
+import * as store from './versionStore.js';
+// Version ids are alphanumeric on purpose: they are filenames, command-line
+// positionals and (later) url segments, and nanoid's default alphabet includes
+// `-`, which reads as a flag wherever an id is typed.
+const newVersionId = customAlphabet('0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ', 12);
+function resolveProjectDir(dir) {
+    const projectDir = path.resolve(dir);
+    if (!fs.existsSync(projectDir))
+        throw new Error(`No such directory: ${projectDir}`);
+    return projectDir;
+}
+// A path on the command line may name a directory, which stands for every
+// tracked file under it -- on disk AND in the parent manifest, so deleting a
+// whole directory and saving it still records the deletions.
+function expandSelection(projectDir, given, parentFiles) {
+    const workingFiles = store.walkDeckFiles(projectDir);
+    const selected = new Set();
+    for (const raw of given) {
+        const rel = store.toDeckRelative(projectDir, raw);
+        if (!rel)
+            throw new Error(`Path is outside the deck: ${raw}`);
+        if (store.isIgnoredPath(rel))
+            throw new Error(`Path is not tracked: ${rel}`);
+        const isDir = fs.existsSync(path.join(projectDir, rel)) && fs.statSync(path.join(projectDir, rel)).isDirectory();
+        if (isDir) {
+            const prefix = `${rel}/`;
+            for (const p of workingFiles)
+                if (p.startsWith(prefix))
+                    selected.add(p);
+            for (const p of Object.keys(parentFiles))
+                if (p.startsWith(prefix))
+                    selected.add(p);
+            continue;
+        }
+        if (!fs.existsSync(path.join(projectDir, rel)) && !(rel in parentFiles)) {
+            throw new Error(`No such file: ${rel}`);
+        }
+        selected.add(rel);
+    }
+    return [...selected].sort();
+}
+// The whole tree becomes the manifest. Content is stored as we go, so an
+// unchanged file costs a read and a hash and writes nothing new.
+function manifestFromTree(projectDir) {
+    const files = {};
+    for (const rel of store.walkDeckFiles(projectDir)) {
+        const hash = store.storeWorkingFile(projectDir, rel);
+        if (hash)
+            files[rel] = hash;
+    }
+    return files;
+}
+// The parent's manifest with only the selected paths overridden. Everything
+// else keeps the parent's hash -- so the version describes a curated state, and
+// the paths left out stay dirty on disk for the next save to pick up.
+function manifestFromSelection(projectDir, parentFiles, selected) {
+    const files = { ...parentFiles };
+    for (const rel of selected) {
+        const hash = store.storeWorkingFile(projectDir, rel);
+        if (hash)
+            files[rel] = hash;
+        else
+            delete files[rel];
+    }
+    return files;
+}
+// The save itself, with no output -- what the CLI command and the editor's
+// Save version button both run.
+export function createVersion(projectDir, opts = {}) {
+    const parentId = store.readHead(projectDir);
+    const parentFiles = store.parentManifest(projectDir, parentId);
+    const given = opts.paths ?? [];
+    const selected = given.length > 0 ? expandSelection(projectDir, given, parentFiles) : null;
+    const files = selected
+        ? manifestFromSelection(projectDir, parentFiles, selected)
+        : manifestFromTree(projectDir);
+    const changes = store.diffManifests(parentFiles, files, selected ?? undefined);
+    if (Object.keys(changes).length === 0)
+        return { version: null, partial: selected !== null };
+    const version = {
+        id: newVersionId(),
+        parentId,
+        createdAt: new Date().toISOString(),
+        message: opts.message ?? '',
+        files,
+        changes,
+    };
+    store.writeVersion(projectDir, version);
+    store.writeHead(projectDir, version.id);
+    return { version, partial: selected !== null };
+}
+export function saveVersion(dir, opts = {}) {
+    const projectDir = resolveProjectDir(dir);
+    const { version, partial } = createVersion(projectDir, opts);
+    if (!version) {
+        console.log(partial ? 'No changes in the selected paths. Nothing saved.' : 'No changes. Nothing saved.');
+        return;
+    }
+    const changes = version.changes;
+    const count = Object.keys(changes).length;
+    console.log(`Saved version ${version.id} (${count} file${count === 1 ? '' : 's'} changed).`);
+    for (const [p, change] of Object.entries(changes)) {
+        const mark = change.before === null ? 'added' : change.after === null ? 'deleted' : 'changed';
+        console.log(`  ${mark}  ${p}`);
+    }
+    if (partial) {
+        console.log('Partial save: unselected files are still dirty on disk.');
+    }
+}
+// The deck cover is rewritten every time the deck is played, so it is
+// permanently dirty. It is versioned and restored like any other file, but it
+// never counts as a change worth reporting and never blocks a restore -- the
+// old cover it writes back regenerates on the next play. Without this, every
+// restore refused on a file nobody edited.
+function isReportableChange(path) {
+    return path !== COVER_FILE;
+}
+function changeKind(change) {
+    if (change.before === null)
+        return 'added';
+    if (change.after === null)
+        return 'deleted';
+    return 'changed';
+}
+/**
+ * What has changed on disk since head, in the same shape a version's `changes`
+ * takes. Hashes the tree WITHOUT storing anything -- asking what is outstanding
+ * must not write to the store.
+ */
+export function pendingChanges(projectDir) {
+    const headFiles = store.parentManifest(projectDir, store.readHead(projectDir));
+    const current = {};
+    for (const rel of store.walkDeckFiles(projectDir)) {
+        const hash = store.hashWorkingFile(projectDir, rel);
+        if (hash)
+            current[rel] = hash;
+    }
+    return Object.entries(store.diffManifests(headFiles, current))
+        .filter(([path]) => isReportableChange(path))
+        .map(([path, change]) => ({ path, kind: changeKind(change) }));
+}
+function toSummary(version, later) {
+    return {
+        id: version.id,
+        parentId: version.parentId,
+        createdAt: version.createdAt,
+        message: version.message,
+        changes: Object.entries(version.changes)
+            .filter(([path]) => isReportableChange(path))
+            .map(([path, change]) => ({ path, kind: changeKind(change) })),
+        later,
+    };
+}
+/**
+ * The deck's history newest first. From head (no `fromId`): the chain forward
+ * from head -- marked `later` -- then head, then its ancestors. From a named
+ * version: that version and its ancestors, as it has always been.
+ *
+ * The forward walk is why a restore no longer makes the versions after it
+ * vanish from the panel and from `list-versions`. It follows one chain of
+ * children, newest child at each step. After a save there is nothing to follow,
+ * because the new version is a leaf, so the forward rows drop away on their own
+ * -- the abandoned versions are still on disk, just no longer reachable forward
+ * from head.
+ *
+ * Naming a version asks a different question -- how did THIS version come to be
+ * -- so that form stays a walk back and is unchanged.
+ */
+export function versionSummaries(projectDir, fromId) {
+    const startId = fromId ?? store.readHead(projectDir);
+    if (!startId)
+        return [];
+    if (!store.versionExists(projectDir, startId))
+        throw new Error(`No such version: ${startId}`);
+    const forward = fromId ? [] : store.forwardChain(projectDir, startId);
+    return [
+        // Nearest child first out of the walk, so reverse it: the furthest
+        // descendant is the newest thing there is.
+        ...[...forward].reverse().map((v) => toSummary(v, true)),
+        ...store.versionChain(projectDir, startId).map((v) => toSummary(v, false)),
+    ];
+}
+export function listVersions(dir, version) {
+    const summaries = versionSummaries(resolveProjectDir(dir), version);
+    if (summaries.length === 0) {
+        console.log('No versions yet.');
+        return;
+    }
+    for (const v of summaries) {
+        const count = v.changes.length;
+        const message = v.message ? `  ${v.message}` : '';
+        // The same history the panel shows, marked the same way, so the two never
+        // disagree about what happened.
+        const later = v.later ? '  (later)' : '';
+        console.log(`${v.id}  ${v.createdAt}  ${count} file${count === 1 ? '' : 's'}${later}${message}`);
+    }
+}
+// One file's side of a change, as text -- or null when it wasn't there (an add
+// or a delete) and `binary: true` when it must not be rendered as a patch.
+function blobText(projectDir, hash) {
+    if (hash === null)
+        return null;
+    const content = store.getBlob(projectDir, hash);
+    return looksBinary(content) ? { text: '', binary: true } : { text: content.toString('utf8'), binary: false };
+}
+function showFileChange(projectDir, filePath, change) {
+    const kind = changeKind(change);
+    const before = blobText(projectDir, change.before);
+    const after = blobText(projectDir, change.after);
+    // A sprite or an image must never come out as a garbled patch; a line saying
+    // what happened to it is the whole useful answer.
+    if (before?.binary || after?.binary) {
+        console.log(`${filePath}  ${kind}, binary`);
+        return;
+    }
+    console.log(`${filePath}  ${kind}`);
+    const hunks = unifiedDiff(before?.text ?? '', after?.text ?? '');
+    if (!hunks) {
+        console.log('  (too large to show as a diff)');
+        return;
+    }
+    for (const line of hunks)
+        console.log(line);
+}
+/**
+ * What one version changed, as diffs of the CHANGED FILES ONLY -- built from the
+ * two blobs each entry in `changes` already names, so nothing new is stored and
+ * the whole tree is never read. The CLI counterpart of the panel's row
+ * expansion, for an agent working out what a change did.
+ */
+export function showVersion(dir, versionId) {
+    const projectDir = resolveProjectDir(dir);
+    if (!store.versionExists(projectDir, versionId))
+        throw new Error(`No such version: ${versionId}`);
+    const version = store.readVersion(projectDir, versionId);
+    const paths = Object.keys(version.changes).sort();
+    console.log(`${version.id}  ${version.createdAt}  ${paths.length} file${paths.length === 1 ? '' : 's'}`);
+    if (version.message)
+        console.log(version.message);
+    console.log('');
+    for (const filePath of paths) {
+        showFileChange(projectDir, filePath, version.changes[filePath]);
+        console.log('');
+    }
+}
+/**
+ * The versions from `from` back to `to`, exclusive of `to`, newest first -- or
+ * null when `to` is not an ancestor of `from`. Only `parentId` is stored, so
+ * this is the only direction the history can be walked directly.
+ */
+function chainDownTo(projectDir, from, to) {
+    const chain = [];
+    const seen = new Set();
+    let cursor = from;
+    while (cursor && cursor !== to) {
+        if (seen.has(cursor))
+            throw new Error(`Version history loops at ${cursor}`);
+        seen.add(cursor);
+        const version = store.readVersion(projectDir, cursor);
+        chain.push(version);
+        cursor = version.parentId;
+    }
+    return cursor === to ? chain : null;
+}
+/**
+ * What a restore should write, and what it expects to find on disk first.
+ *
+ * The two directions are mirrors of each other over the SAME set of versions --
+ * the ones between head and the target -- read from opposite ends:
+ *
+ *   backward (the target is an ancestor of head): put back the EARLIEST
+ *     `before`, the state closest to the target; expect the LATEST `after`, the
+ *     state closest to head.
+ *   forward (the target is a descendant of head): put back the LATEST `after`,
+ *     again the state closest to the target; expect the EARLIEST `before`,
+ *     again the state closest to head.
+ *
+ * Either way a path no version between the two touched never enters the plan,
+ * so unsaved work on it survives.
+ */
+function planRestore(projectDir, targetId) {
+    const head = store.readHead(projectDir);
+    if (!head)
+        throw new Error('No versions yet.');
+    const backward = chainDownTo(projectDir, head, targetId);
+    if (backward)
+        return planFromChain(backward, 'backward');
+    const forward = chainDownTo(projectDir, targetId, head);
+    if (forward)
+        return planFromChain(forward, 'forward');
+    throw new NotOnThisLine(targetId, head);
+}
+// `chain` is always newest first, so "first seen wins" reads the end nearest the
+// newer version and "last write wins" reads the end nearest the older one.
+function planFromChain(chain, direction) {
+    const plan = {
+        wanted: {},
+        expected: {},
+        offChain: direction === 'backward' ? chain.length : 0,
+    };
+    for (const version of chain) {
+        for (const [p, change] of Object.entries(version.changes)) {
+            if (direction === 'backward') {
+                plan.wanted[p] = change.before;
+                if (!(p in plan.expected))
+                    plan.expected[p] = change.after;
+            }
+            else {
+                if (!(p in plan.wanted))
+                    plan.wanted[p] = change.after;
+                plan.expected[p] = change.before;
+            }
+        }
+    }
+    return plan;
+}
+function removeEmptyParents(projectDir, relPath) {
+    let dir = path.dirname(path.join(projectDir, relPath));
+    while (dir.startsWith(projectDir) && dir !== projectDir) {
+        try {
+            if (fs.readdirSync(dir).length > 0)
+                return;
+            fs.rmdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        dir = path.dirname(dir);
+    }
+}
+function applyRestore(projectDir, actions) {
+    for (const [rel, hash] of actions) {
+        const abs = path.join(projectDir, rel);
+        if (hash === null) {
+            fs.rmSync(abs, { force: true });
+            removeEmptyParents(projectDir, rel);
+            continue;
+        }
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, store.getBlob(projectDir, hash));
+    }
+}
+// Work no version has recorded, which a restore would overwrite. The paths ARE
+// the answer to "what would I lose", so they ride on the error and each caller
+// says what to do about it -- the CLI offers `--force`, the panel has no such
+// thing and says to save a version first.
+export class UnsavedChanges extends Error {
+    paths;
+    constructor(paths) {
+        const count = paths.length;
+        super(`Unsaved changes would be lost in ${count} file${count === 1 ? '' : 's'}:\n` +
+            paths.map((p) => `  ${p}`).join('\n'));
+        this.name = 'UnsavedChanges';
+        this.paths = paths;
+    }
+}
+// A version on a different branch: neither an ancestor of head nor a descendant
+// of it. Restore moves along one line in either direction; getting from here to
+// there would mean merging, which is not something this build does silently.
+export class NotOnThisLine extends Error {
+    constructor(targetId, head) {
+        super(`Version ${targetId} is on a different branch than ${head}. ` +
+            'Restore moves back or forward along one line, not across a fork.');
+        this.name = 'NotOnThisLine';
+    }
+}
+// The restore itself, with no output. Throws on unsaved changes unless forced --
+// the message names every conflicting path, since that list IS the answer to
+// "what would I lose".
+export function applyVersionRestore(projectDir, targetId, opts = {}) {
+    if (!store.versionExists(projectDir, targetId))
+        throw new Error(`No such version: ${targetId}`);
+    if (store.readHead(projectDir) === targetId) {
+        return { alreadyThere: true, applied: [], offChain: 0 };
+    }
+    const plan = planRestore(projectDir, targetId);
+    // Only paths whose content would actually move are checked and applied: a
+    // path already holding what the restore wants is neither a conflict nor work.
+    const actions = [];
+    const conflicts = [];
+    for (const [rel, wanted] of Object.entries(plan.wanted)) {
+        const current = store.hashWorkingFile(projectDir, rel);
+        if (current === wanted)
+            continue;
+        // The cover is exempt: it is dirty by construction, so refusing on it would
+        // refuse every restore. It still gets written back.
+        if (current !== plan.expected[rel] && isReportableChange(rel))
+            conflicts.push(rel);
+        actions.push([rel, wanted]);
+    }
+    if (conflicts.length > 0 && !opts.force)
+        throw new UnsavedChanges(conflicts.sort());
+    applyRestore(projectDir, actions.sort((a, b) => a[0].localeCompare(b[0])));
+    // Head moves to the target, so the next save continues from there and the
+    // versions we walked past fork off. They stay on disk and stay loadable by
+    // id -- they are just no longer on head's chain.
+    store.writeHead(projectDir, targetId);
+    return { alreadyThere: false, applied: actions, offChain: plan.offChain };
+}
+export function restoreVersion(dir, targetId, opts = {}) {
+    const projectDir = resolveProjectDir(dir);
+    let outcome;
+    try {
+        outcome = applyVersionRestore(projectDir, targetId, opts);
+    }
+    catch (e) {
+        // Only the command line has a --force, so only the command line mentions it.
+        if (e instanceof UnsavedChanges) {
+            throw new Error(`${e.message}\nSave a version first, or pass --force to restore anyway.`);
+        }
+        throw e;
+    }
+    if (outcome.alreadyThere) {
+        console.log(`Already at version ${targetId}. Nothing to restore.`);
+        return;
+    }
+    const applied = outcome.applied;
+    if (applied.length === 0) {
+        console.log(`The working tree already matched version ${targetId}.`);
+    }
+    else {
+        console.log(`Restored ${applied.length} file${applied.length === 1 ? '' : 's'} to version ${targetId}.`);
+        for (const [rel, hash] of applied)
+            console.log(`  ${hash === null ? 'deleted' : 'restored'}  ${rel}`);
+    }
+    // A silent head move is the thing people discover a week later. What the move
+    // left behind needs no announcement: `list-versions` shows those versions,
+    // marked `(later)`.
+    console.log(`head is now ${targetId}.`);
+}

package/dist/vitePlugins.js

@@ -1,7 +1,7 @@
 import * as path from 'path';
 import * as fs from 'fs';
 import { IMPORTS_DIR } from './imports.js';
-import { resolveFileTypes } from './editorConfig.js';
+import { dataModeOf, resolveFileTypes } from './editorConfig.js';
 // Mirrors castle-web-sdk's IMPORTS_PREFIX, which is the definition deck code
 // uses. Duplicated rather than imported: the CLI compiles under node16 module
 // resolution and the SDK's published types don't, and one short string is not
@@ -25,13 +25,22 @@ const IMPORTS_PREFIX = '@imports/';
 // declares anything, kept so decks written before the declaration existed behave
 // as they did.
 const FALLBACK_DATA_FILE_EXTS = ['.scene', '.drawing', '.pxart', '.sprite'];
-function dataFileExts(root) {
+// Extension -> how to hand it back when a module imports it. "json" parses it,
+// "text" returns the raw string; a format that is neither (a `.md` an editor
+// owns, say) simply isn't in here and stays an ordinary module.
+function dataFileModes(root) {
     const resolved = resolveFileTypes(root);
     // Declared file types with no data entries mean exactly that: a deck whose
     // files are all modules. Only "nobody said anything" falls back.
     if (!resolved)
-        return FALLBACK_DATA_FILE_EXTS;
-    return resolved.filter((t) => t.data === true).map((t) => t.ext);
+        return new Map(FALLBACK_DATA_FILE_EXTS.map((ext) => [ext, 'json']));
+    const modes = new Map();
+    for (const type of resolved) {
+        const mode = dataModeOf(type);
+        if (mode)
+            modes.set(type.ext, mode);
+    }
+    return modes;
 }
 // `@imports/<alias>/...` is how a deck names a file of another deck it imports,
 // in JS as in everything else (see castle-web-sdk's resolveDeckFile). Imports are
@@ -62,19 +71,23 @@ export function importsAliasPlugin() {
 export function sceneFilesPlugin() {
     // Resolved once per plugin instance, from the root vite is configured with --
     // the deck being served or bundled.
-    let exts = FALLBACK_DATA_FILE_EXTS;
+    let modes = new Map(FALLBACK_DATA_FILE_EXTS.map((ext) => [ext, 'json']));
     return {
         name: 'castle-scene-files',
         configResolved(config) {
-            exts = dataFileExts(config.root);
+            modes = dataFileModes(config.root);
         },
         load(id) {
             const [filePath, query] = id.split('?');
             if (query !== undefined)
                 return null;
-            if (exts.some((ext) => filePath.endsWith(ext))) {
+            for (const [ext, mode] of modes) {
+                if (!filePath.endsWith(ext))
+                    continue;
                 const text = fs.readFileSync(filePath, 'utf-8');
-                return `export default JSON.parse(${JSON.stringify(text)});\n`;
+                return mode === 'text'
+                    ? `export default ${JSON.stringify(text)};\n`
+                    : `export default JSON.parse(${JSON.stringify(text)});\n`;
             }
             return null;
         },

package/kits/physics-2d/castle.json

@@ -123,5 +123,5 @@
   "main": "main.jsx",
   "autoUpdateWhenImported": true,
   "title": "physics-2d",
-  "publishedVersion": "2026-08-14T21:20:31.152Z"
+  "publishedVersion": "2026-08-16T04:02:06.732Z"
 }

package/kits/physics-2d/editors/SingleEditor.jsx

@@ -7,6 +7,7 @@
 import React, { useEffect, useRef, useState } from 'react';
 import { onBeforeRestart, onSaveReloadState, takeReloadState, writeFile } from 'castle-web-sdk';
 import { getFileKind } from '../engine/files';
+import { hasEditorModule, loadEditorModule } from './editorRegistry';
 import { useLiveDeckFiles } from '../engine/liveReload';
 import { collectAssets } from '../engine/assets';
 import { MainEditor, styles } from '../engine/ui';
@@ -65,7 +66,33 @@ function useFileSaver() {
   return { schedule, hasPending };
 }
 
-export function SingleEditor({ path, editor }) {
+// A file type whose declaring deck named an editor module: load that module and
+// render it, rather than matching the path against this kit's own list. This is
+// what lets a deck hold two kits -- each type reaches its own declarer's editor,
+// and neither kit has to know the other exists.
+function DeclaredEditor({ path, module: modulePath, text, onChange, files, onChangeFile }) {
+  const [Editor, setEditor] = useState(null);
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    let alive = true;
+    setEditor(null);
+    setError(null);
+    loadEditorModule(modulePath).then(
+      (loaded) => alive && setEditor(() => loaded),
+      (e) => alive && setError(e instanceof Error ? e.message : String(e)),
+    );
+    return () => {
+      alive = false;
+    };
+  }, [modulePath]);
+  if (error) return <div className={styles.editorBody}>{error}</div>;
+  if (!Editor) return <div className={styles.editorBody}>loading editor…</div>;
+  return (
+    <Editor path={path} text={text} onChange={onChange} files={files} onChangeFile={onChangeFile} />
+  );
+}
+
+export function SingleEditor({ path, editor, editorModule }) {
   // Selection survives a code-change reload: stashed via the SDK's save-state
   // hook right before the reload, picked back up here on boot.
   const stashKey = `single-editor:${path}`;
@@ -96,7 +123,21 @@ export function SingleEditor({ path, editor }) {
   const kind = editor || getFileKind(path);
   const text = files[path] ?? '';
   let body = null;
-  if (kind === 'scene') {
+  // A declared module wins over this kit's own extension matching -- including
+  // over its own types, so the kit's editors are reachable the same way anyone
+  // else's are once physics-2d names them in castle.json.
+  if (editorModule && hasEditorModule(editorModule)) {
+    body = (
+      <DeclaredEditor
+        path={path}
+        module={editorModule}
+        text={text}
+        onChange={onChange}
+        files={files}
+        onChangeFile={onChangeFile}
+      />
+    );
+  } else if (kind === 'scene') {
     body = (
       <SceneEditor
         path={path}

package/kits/physics-2d/editors/editorRegistry.jsx

@@ -0,0 +1,34 @@
+// Every editor module any deck here declares -- this deck's own and each
+// import's -- keyed by its path from the deck root, which is exactly what
+// `castle.json` `editor` resolves to (see resolveFileTypes in the CLI).
+//
+// A glob rather than a dynamic `import(path)`: the specifier has to be static
+// for the module to survive bundling into a deck's single published file, the
+// same reason behaviorRegistry and files.js glob. NOT eager, so an editor is a
+// separate chunk that the play route never evaluates.
+//
+// Editors live under `editors/` by convention; that is what makes a third
+// party's editor reachable from here without this kit knowing it exists.
+const modules = {
+  ...import.meta.glob('/imports/*/editors/**/*.{jsx,js}'),
+  ...import.meta.glob('/editors/**/*.{jsx,js}'),
+};
+
+export function hasEditorModule(path) {
+  return Boolean(path && modules[`/${path}`]);
+}
+
+// Load one, returning its default export. Throws a legible error rather than
+// letting the caller see `undefined is not a function` three frames later.
+export async function loadEditorModule(path) {
+  const load = modules[`/${path}`];
+  if (!load) {
+    throw new Error(
+      `No editor module at "${path}". Editors must live under editors/ so the registry glob can reach them.`,
+    );
+  }
+  const mod = await load();
+  const Editor = mod.default ?? mod.Editor;
+  if (!Editor) throw new Error(`"${path}" has no default export to render as an editor.`);
+  return Editor;
+}

package/kits/physics-2d/main.jsx

@@ -12,13 +12,22 @@ if (!root) throw new Error('Missing root element');
 // File browsing and the code/text editor are now builtin shell panels, so the
 // kit only renders the deck (play) and its rich per-file editors (scene/pxart):
 //   (no edit / ?edit=0)        -> play the deck (playtest panel)
-//   ?file=<path>[&editor=<id>] -> a single rich editor for that file
+//   ?file=<path>[&editorModule=<path>] -> a single rich editor for that file
 const params = new URLSearchParams(window.location.search);
 function pick() {
   const initialScene = params.get('scene') ?? undefined;
   if (!isEdit()) return <PlayOnly initialScene={initialScene} />;
   const file = params.get('file');
-  if (file) return <SingleEditor path={file} editor={params.get('editor') ?? undefined} />;
+  if (file)
+    return (
+      <SingleEditor
+        path={file}
+        editor={params.get('editor') ?? undefined}
+        // Which module edits this file, resolved by the serve from whichever
+        // deck declared the type -- see `editor` in castle.json.
+        editorModule={params.get('editorModule') ?? undefined}
+      />
+    );
   return <PlayOnly initialScene={initialScene} />;
 }
 createRoot(root).render(<ErrorBoundary>{pick()}</ErrorBoundary>);

package/kits/physics-2d/package-lock.json

@@ -28,7 +28,7 @@
     },
     "../../sdk": {
       "name": "castle-web-sdk",
-      "version": "0.4.13",
+      "version": "0.4.12",
       "devDependencies": {
         "eslint": "^9.0.0",
         "jscpd": "^4.0.5",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.4.121",
+  "version": "0.4.123",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"