castle-web-cli 0.4.166 → 0.4.168

package/kits/blank/.castle/agent/messages.json

@@ -0,0 +1,9 @@
+[
+  {
+    "id": "YzUYA2mw",
+    "role": "assistant",
+    "text": "Welcome to an early test of Castle's new engine! You're starting with a blank deck, without the official art or scene editors, but if HTML and JavaScript can do it then I can help you build it.\n\nDo you already know what you want to make, or do you want to figure it out together?",
+    "at": "2026-08-27T19:05:49.289Z",
+    "status": "done"
+  }
+]

package/kits/blank/.castle/agent/pending-sends.json

@@ -0,0 +1 @@
+[]

package/kits/blank/.castle/agent/tasks/index.md

@@ -0,0 +1,2 @@
+# tasks
+# <task-id> | <item> | <title> | <created> | <status> | <touching>

package/kits/blank/.castle/docs/platform.md

@@ -0,0 +1,36 @@
+# Castle platform
+
+How every Castle deck works, from the Castle CLI. Written fresh at every serve
+start; the deck's own guide (its kit's CLAUDE.md under imports/) adds what its
+kit provides on top of this.
+
+## Imports are read-only
+
+- **`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.
+- **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.
+- **`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.
+- **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.
+- **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.
+
+## Assets
+
+- **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
+
+- **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
+
+- **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.
+
+## Formats, reloading, editors
+
+- **Supported media formats are exactly**: images `.png` `.jpg` `.jpeg` `.gif` `.webp` `.svg`, audio `.mp3` `.wav` `.m4a`, video `.mp4` (H.264). 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.
+- To add an npm package, put it in `package.json` `dependencies` and run `castle-web install .` (the install `init` ran; it uses whichever package manager made the lockfile).
+- Do not reload the deck after an edit. Nothing auto-reloads: the person applies your changes when they are ready, from the Play panel's restart button or a panel's own reload control. `npm run restart` reloads every open panel at once and breaks their flow — only when asked.
+- The deck can define its own editors: declare a file type in `castle.json` (`editor.fileTypes`: ext, label, icon, and an `editors/` module) and the Files panel opens that type in it — whole recipe under `## Editors` in the deck's guide (its kit's `CLAUDE.md` under `imports/`). Editors under `imports/` are read-only; add or fork, don't edit.
+- An editor is for content FILES the creator keeps coming back to (catalogs, dialogue, level tables) that nothing already opens. One-off or generated data stays code.
+- 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.

package/kits/blank/node_modules/.vite/deps/_metadata.json

@@ -0,0 +1,8 @@
+{
+  "hash": "39e56a5d",
+  "configHash": "5ff7cbd8",
+  "lockfileHash": "78d11399",
+  "browserHash": "61f2844b",
+  "optimized": {},
+  "chunks": {}
+}

package/kits/blank/node_modules/.vite/deps/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/kits/multiplayer-2d/CLAUDE.md

@@ -137,6 +137,12 @@ and then, all optional, all found by root-anchored glob in
 | `code/server/game.js`           | the game, as six hooks on a default export          |
 | `code/server/deckComponents.js` | `export const componentDefaults = { Cargo: {...} }` |
 
+The kit draws no HUD, with one exception: when the join fell back to solo,
+`castle.real-time`'s `soloBadge.js` shows a small fixed badge naming why
+(`status().soloReason`: a private deck, no published server, or plain
+unavailable), so a creator testing their own deck is told rather than left to
+guess. A deck's `soloBadge(status)` client hook hides (`false`) or rewords it.
+
 The six server hooks: `ready(sim)`, `message(session, player, data)`,
 `place(sim, handovers)`, `step(sim, handovers)`, `join(sim)`, `delta(sim)`.
 `place` runs BEFORE the physics step, which is where a write that only reaches a

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

@@ -15,7 +15,7 @@
   "imports": {
     "castle.real-time": {
       "deckId": "xFVr-afOLuUQ",
-      "version": "2026-09-01T20:54:44.750Z"
+      "version": "2026-09-05T01:31:28.578Z"
     },
     "castle.physics-2d": {
       "deckId": "ckRZGFW4iPrx",
@@ -23,7 +23,7 @@
     },
     "castle.base": {
       "deckId": "yRcmH4_aYllE",
-      "version": "2026-09-01T01:02:34.326Z"
+      "version": "2026-09-05T01:31:11.287Z"
     }
   },
   "autoUpdateWhenImported": true,
@@ -35,5 +35,5 @@
   },
   "deckId": "oiFu96LkwZ09",
   "cardId": "nkJgrvrCby3H",
-  "publishedVersion": "2026-09-02T05:55:09.684Z"
+  "publishedVersion": "2026-09-05T01:32:45.261Z"
 }

package/kits/multiplayer-2d/code/systems/multiplayer.js

@@ -14,6 +14,7 @@ import * as Ownership from '@imports/castle.real-time/code/client/ownership.js';
 import * as Smoothing from '@imports/castle.real-time/code/client/smooth.js';
 import * as Poses from '../client/poses.js';
 import { connectSession } from '@imports/castle.real-time/code/client/connection.js';
+import { showSoloBadge, updateSoloBadge } from '@imports/castle.real-time/code/client/soloBadge.js';
 import { STATE, WORLD } from '@imports/castle.real-time/code/client/messages.js';
 import { game } from '@imports/castle.real-time/code/client/gameHooks.js';
 
@@ -111,6 +112,7 @@ class MultiplayerSystem {
     }
     game.afterFrame?.(scene, dt, this);
     this.publish(scene, local);
+    updateSoloBadge(this.net.status(), game);
   }
 
   // Join the public session once. Scene resets retain this transport.
@@ -378,6 +380,9 @@ class MultiplayerSystem {
     this.reset(scene);
     this.net?.close();
     this.net = null;
+    // The badge is a fixed element outside the scene, so a disposed runtime
+    // (an editor preview closing, say) has to take it down explicitly.
+    showSoloBadge(null);
   }
 }
 

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

@@ -29,7 +29,7 @@
     },
     "../../sdk": {
       "name": "castle-web-sdk",
-      "version": "0.4.23",
+      "version": "0.4.26",
       "dev": true,
       "devDependencies": {
         "eslint": "^9.0.0",
@@ -151,6 +151,7 @@
       "resolved": "https://registry.npmjs.org/@dnd-kit/core/-/core-6.3.1.tgz",
       "integrity": "sha512-xkGBRQQab4RLwgXxoqETICr6S5JlogafbhNsidmrkVv2YRs5MLwpjoF2qpiGjQt8S9AoxtIV603s0GIUpY5eYQ==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@dnd-kit/accessibility": "^3.1.1",
         "@dnd-kit/utilities": "^3.2.2",
@@ -307,6 +308,7 @@
       "resolved": "https://registry.npmjs.org/react/-/react-19.2.8.tgz",
       "integrity": "sha512-PWaYA1L/q9u2u7xYQi+Y3L3Yfnie7XyLeaJICV1MGD6LprsBxcAqGjYyr0eY3p+QdsA+x/Irkt4Qif8D63+Sbw==",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -316,6 +318,7 @@
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.8.tgz",
       "integrity": "sha512-rVprimfGBG3DR+Tq0IQG2DT5PxKth1WIGDmj5yPmlzr4YBe7uyE+Du4oVqTDXZSHGGGXRtTJEGSSePyQCMBglQ==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "scheduler": "^0.27.0"
       },

package/kits/multiplayer-3d/CLAUDE.md

@@ -238,7 +238,12 @@ Map())` — and the next `showPlayer` respawns it.
 - **The player blueprint itself.** The kit spawns a scene from the deck's own
   root; the deck ships it. `blueprints/other-player.scene` is only the name it
   looks for when the deck names none.
-- **Any HUD.** Five decks wrote five HUDs with no shared lines.
+- **Any HUD.** Five decks wrote five HUDs with no shared lines. The one
+  on-screen element the kit does draw is the solo badge
+  (`castle.real-time`'s `soloBadge.js`): when the join fell back to solo it
+  names why (`status().soloReason`), so a creator testing a private or
+  unpublished deck is told rather than left to guess. A deck's
+  `soloBadge(status)` client hook hides or rewords it.
 - **Gameplay verbs** — carry, vehicle, round, lobby. Measured across six decks
   and none of them survived contact; see the audit.
 

package/kits/multiplayer-3d/castle.json

@@ -14,7 +14,7 @@
   "imports": {
     "castle.real-time": {
       "deckId": "xFVr-afOLuUQ",
-      "version": "2026-09-01T20:54:44.750Z"
+      "version": "2026-09-05T01:31:28.578Z"
     },
     "castle.physics-3d": {
       "deckId": "JH0SclbPVP0y",
@@ -27,13 +27,13 @@
     },
     "castle.base": {
       "deckId": "yRcmH4_aYllE",
-      "version": "2026-09-01T01:02:34.326Z"
+      "version": "2026-09-05T01:31:11.287Z"
     }
   },
   "autoUpdateWhenImported": true,
   "deckId": "ZwA_P_-VO-Qh",
   "cardId": "bvRmCzyUpt_a",
-  "publishedVersion": "2026-09-02T05:55:13.845Z",
+  "publishedVersion": "2026-09-05T01:32:53.625Z",
   "main": "main.jsx",
   "server": {
     "main": "code/server/index.js",

package/kits/multiplayer-3d/code/systems/multiplayer.js

@@ -9,6 +9,7 @@ import * as Ownership from '@imports/castle.real-time/code/client/ownership.js';
 import * as Smoothing from '@imports/castle.real-time/code/client/smooth.js';
 import * as Poses from '../client/poses.js';
 import { connectSession } from '@imports/castle.real-time/code/client/connection.js';
+import { showSoloBadge, updateSoloBadge } from '@imports/castle.real-time/code/client/soloBadge.js';
 import { STATE, WORLD } from '@imports/castle.real-time/code/client/messages.js';
 import { game } from '@imports/castle.real-time/code/client/gameHooks.js';
 
@@ -115,6 +116,7 @@ class MultiplayerSystem {
       };
     }
     this.publish(scene, local);
+    updateSoloBadge(this.net.status(), game);
   }
 
   // Join the Castle public session once and retain the transport across scene loads.
@@ -394,6 +396,9 @@ class MultiplayerSystem {
     this.reset(scene);
     this.net?.close();
     this.net = null;
+    // The badge is a fixed element outside the scene, so a disposed runtime
+    // (an editor preview closing, say) has to take it down explicitly.
+    showSoloBadge(null);
   }
 }
 

package/kits/multiplayer-3d/package-lock.json

@@ -31,7 +31,7 @@
     },
     "../../sdk": {
       "name": "castle-web-sdk",
-      "version": "0.4.23",
+      "version": "0.4.26",
       "dev": true,
       "devDependencies": {
         "eslint": "^9.0.0",

package/kits/physics-2d/behaviors/Joints.jsx

@@ -1,5 +1,6 @@
 import React, { useState } from 'react';
-import { Panel, SelectField, NumberField, CheckboxField, Button, FileField } from '../engine/ui';
+import { Panel, SelectField, NumberField, CheckboxField, Button } from '../engine/ui';
+import { SpriteField } from '../engine/spriteField';
 import { centerOf, inActorWorldSpace } from '../engine/physics/controls';
 import { JOINT_TYPES } from '../engine/physics/joints';
 import { drawJointArt } from '../engine/physics/jointArt';
@@ -75,9 +76,12 @@ export class Joints {
     });
   }
 
-  static Inspector({ component, setComponent, override, beginPick, pickActive, files }) {
+  static Inspector({ component, setComponent, override, beginPick, pickActive, sprites }) {
     const list = Array.isArray(component.list) ? component.list : [];
-    const spriteFiles = Object.keys(files ?? {}).filter((f) => f.endsWith('.sprite') || f.endsWith('.pxart'));
+    // Joint art is drawings-only (tile/stretch along a link); images stay out.
+    const spriteFiles = Object.keys(sprites ?? {})
+      .filter((f) => f.endsWith('.sprite') || f.endsWith('.pxart'))
+      .sort();
     // Which entry's target-pick is live. Combined with the editor's global
     // `pickActive` so a cancel (Esc/empty click) clears every entry's state.
     const [pickingIndex, setPickingIndex] = useState(null);
@@ -95,6 +99,7 @@ export class Joints {
             key={i}
             index={i}
             joint={joint}
+            sprites={sprites}
             spriteFiles={spriteFiles}
             active={pickActive && pickingIndex === i}
             onPickToggle={() => onPickToggle(i)}
@@ -114,7 +119,7 @@ function defaultJoint() {
 
 // One editable link in the list: type, target picker, type-specific fields, and
 // how it renders in play (line / hidden / sprite art along the joint).
-function JointEntry({ index, joint, spriteFiles, active, onPickToggle, onPatch, onRemove }) {
+function JointEntry({ index, joint, sprites, spriteFiles, active, onPickToggle, onPatch, onRemove }) {
   const [showAnchors, setShowAnchors] = useState(false);
   const type = joint.type ?? 'spring';
   const isPivot = type === 'weld';
@@ -180,10 +185,11 @@ function JointEntry({ index, joint, spriteFiles, active, onPickToggle, onPatch,
       <SelectField label="Show in play" value={render} onChange={(v) => onPatch({ render: v })} options={RENDER_MODES} />
       {render === 'sprite' ? (
         <>
-          <FileField
+          <SpriteField
             label="Art"
             value={joint.sprite || ''}
             onChange={(v) => onPatch({ sprite: v })}
+            sprites={sprites}
             files={spriteFiles}
             allowEmpty
           />

package/kits/physics-2d/behaviors/Sprite.jsx

@@ -1,10 +1,10 @@
 import { resolveDeckFile } from 'castle-web-sdk';
 import React from 'react';
-import { artFrameCount, isImageArt, renderArtFrame } from '../engine/art';
+import { artFrameCount, isImageArt, renderDisplayFrame } from '../engine/art';
 import { isVectorRenderer } from '../engine/pxart';
-import { renderSmoothCompositeFrame, renderSmoothSpriteFrame } from '../engine/pxartSmooth';
 import { spriteDestRect } from '../engine/spriteGeometry';
-import { FileField, Panel, SelectField } from '../engine/ui';
+import { Panel, SelectField } from '../engine/ui';
+import { SpriteField } from '../engine/spriteField';
 import { AutoFields, overrideProps } from '../engine/autoInspector';
 import { parseTint, tintCanvas } from './tint';
 
@@ -166,14 +166,13 @@ export class Sprite {
   }
 
   static Inspector({ component, setComponent, sprites, override }) {
-    const spriteFiles = getSpriteFiles(sprites);
     return (
       <Panel title="Sprite" overridden={override?.anyOverridden()}>
-        <FileField
+        <SpriteField
           label="File"
           value={component.file}
           onChange={(file) => setComponent({ file })}
-          files={spriteFiles}
+          sprites={sprites}
           {...overrideProps(override, 'file')}
         />
         <SelectField
@@ -270,15 +269,7 @@ const MAX_CACHE_LONG_SIDE = 2048;
 function frameSource(sprite, frameIndex) {
   if (isImageArt(sprite)) return sprite.ready ? sprite.image : null;
   const canvas = document.createElement('canvas');
-  if (isVectorRenderer(sprite.renderer)) {
-    renderSmoothCompositeFrame(sprite, frameIndex, canvas);
-    return canvas;
-  }
-  if (sprite.cornerRadius > 0) {
-    renderSmoothSpriteFrame(sprite, frameIndex, canvas, { cornerRadius: sprite.cornerRadius });
-    return canvas;
-  }
-  return renderArtFrame(sprite, frameIndex, canvas) ? canvas : null;
+  return renderDisplayFrame(sprite, frameIndex, canvas) ? canvas : null;
 }
 
 function sourceSize(source) {
@@ -431,9 +422,3 @@ function advanceAnim(state, sprite, sequence, tag, dt) {
   }
   state.frameIndex = sequence[state.pos];
 }
-
-// Everything the deck can point a Sprite at: `.pxart` drawings and image files
-// alike, which is exactly what the resolved art map holds.
-function getSpriteFiles(sprites) {
-  return Object.keys(sprites ?? {}).sort();
-}

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

@@ -63,66 +63,6 @@
         "icon": "file",
         "editor": "kit",
         "data": true
-      },
-      {
-        "ext": ".png",
-        "label": "Image",
-        "icon": "image",
-        "editor": "kit"
-      },
-      {
-        "ext": ".jpg",
-        "label": "Image",
-        "icon": "image",
-        "editor": "kit"
-      },
-      {
-        "ext": ".jpeg",
-        "label": "Image",
-        "icon": "image",
-        "editor": "kit"
-      },
-      {
-        "ext": ".gif",
-        "label": "Image",
-        "icon": "image",
-        "editor": "kit"
-      },
-      {
-        "ext": ".webp",
-        "label": "Image",
-        "icon": "image",
-        "editor": "kit"
-      },
-      {
-        "ext": ".svg",
-        "label": "Image",
-        "icon": "image",
-        "editor": "kit"
-      },
-      {
-        "ext": ".mp3",
-        "label": "Audio",
-        "icon": "music",
-        "editor": "kit"
-      },
-      {
-        "ext": ".wav",
-        "label": "Audio",
-        "icon": "music",
-        "editor": "kit"
-      },
-      {
-        "ext": ".m4a",
-        "label": "Audio",
-        "icon": "music",
-        "editor": "kit"
-      },
-      {
-        "ext": ".mp4",
-        "label": "Video",
-        "icon": "film",
-        "editor": "kit"
       }
     ],
     "defaultPlayFile": "scenes/main.scene"
@@ -132,7 +72,7 @@
   "main": "main.jsx",
   "autoUpdateWhenImported": true,
   "title": "physics-2d",
-  "publishedVersion": "2026-09-04T18:30:34.333Z",
+  "publishedVersion": "2026-09-05T00:07:35.112Z",
   "imports": {
     "castle.base": {
       "deckId": "yRcmH4_aYllE",

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

@@ -1,5 +1,5 @@
-import React, { useEffect, useRef, useState } from 'react';
-import { isImageArt, onArtLoaded, renderArtFrame } from '../engine/art';
+import React, { useRef, useState } from 'react';
+import { ArtThumbnail } from '../engine/artThumbnail';
 import { screenToCard } from '../engine/scene';
 import { countBlueprintInstances, listBlueprints } from '../engine/blueprint';
 import { ConfirmDialog, ContextMenu, cx, Icon, styles, useWheelToHorizontal } from '../engine/ui';
@@ -235,77 +235,17 @@ function BlueprintDragPreview({ preview, sprites }) {
   );
 }
 
-// Asked of the CANVAS, not the source art: counting non-transparent grid chars
-// would call a path-drawn sprite blank. Skipped for image art, whose native
-// resolution is whatever was uploaded.
-function rendersNothing(sprite, canvas) {
-  if (isImageArt(sprite)) return false;
-  try {
-    const ctx = canvas.getContext('2d', { willReadFrequently: true });
-    const { data } = ctx.getImageData(0, 0, canvas.width, canvas.height);
-    for (let i = 3; i < data.length; i += 4) if (data[i] !== 0) return false;
-    return true;
-  } catch {
-    // Tainted or zero-sized canvas: assume it draws something rather than
-    // mislabeling real art as blank.
-    return false;
-  }
-}
-
-// A blueprint's slot art, falling back to its NAME when there is nothing to
-// show -- no Sprite, a file that doesn't resolve, or art that is entirely
-// transparent (a "Draw new" sprite nobody has drawn in yet). Without it a belt
-// of not-yet-drawn actors is a row of identical placeholders.
-// `showName={false}` for callers that already print the name right beside the
-// thumbnail (the creation modal's tiles) -- otherwise a sprite-less blueprint
-// renders its name inside the tile AND under it, reading as "GoalGoal".
+// A blueprint's slot art — delegates to ArtThumbnail so the belt and the
+// sprite picker share blank-name fallback. `showName={false}` for callers that
+// already print the name right beside the thumbnail (the creation modal's
+// tiles) -- otherwise a sprite-less blueprint renders its name inside the tile
+// AND under it, reading as "GoalGoal".
 export function BlueprintThumbnail({ blueprint, sprites, preview = false, showName = true }) {
-  const canvasRef = useRef(null);
   const spritePath = blueprint.components?.Sprite?.file;
   const sprite = spritePath ? sprites?.[spritePath] : null;
-  // Thumbnails draw on change, not on a frame loop, so an image that finishes
-  // decoding after this rendered has to say so or the slot stays blank.
-  const [loadTick, setLoadTick] = useState(0);
-  const [blank, setBlank] = useState(false);
-  useEffect(() => onArtLoaded(() => setLoadTick((tick) => tick + 1)), []);
-  useEffect(() => {
-    const canvas = canvasRef.current;
-    if (!canvas || !sprite) return;
-    const drew = renderArtFrame(sprite, 0, canvas);
-    // `false` means "not here yet" (an image still loading), not blank.
-    if (drew !== false) setBlank(rendersNothing(sprite, canvas));
-  }, [sprite, loadTick]);
   const name = showName && typeof blueprint.name === 'string' ? blueprint.name.trim() : '';
-  // The canvas stays mounted underneath, so art arriving later clears this.
-  // The inner span is load-bearing, not decoration: bare text inside a flex
-  // container becomes an anonymous item sized to max-content, so it never
-  // "overflows a line" and `overflow-wrap` never fires -- a long single-word
-  // name silently clipped at both edges instead of wrapping. A real child can
-  // be held to the box's width, which is what gives the wrap something to
-  // break against.
-  const label = name ? (
-    <span className={cx(styles.bpSlotName, preview && styles.bpSlotNamePreview)} title={name}>
-      <span className={styles.bpSlotNameText}>{name}</span>
-    </span>
-  ) : (
-    <span className={styles.bpSlotFallback}>
-      <Icon name="clone" />
-    </span>
-  );
-  if (!sprite) return label;
   return (
-    <span className={styles.bpSlotArt}>
-      <canvas
-        ref={canvasRef}
-        className={cx(
-          styles.bpSlotThumb,
-          preview && styles.bpPreviewThumb,
-          blank && styles.bpSlotThumbHidden
-        )}
-        aria-hidden="true"
-      />
-      {blank ? label : null}
-    </span>
+    <ArtThumbnail art={sprite} name={name} preview={preview} fallbackIcon="clone" />
   );
 }
 

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

@@ -27,8 +27,6 @@ import { hasEditorModule, loadEditorModule } from './editorRegistry';
 import { useLiveDeckFiles } from '../engine/liveReload';
 import { collectAssets } from '../engine/assets';
 import { MainEditor, styles } from '../engine/ui';
-import { ImageViewer } from './ImageViewer';
-import { MediaPlayer } from './MediaPlayer';
 import { PxArtEditor } from './PxArtEditor';
 import { SceneEditor } from './SceneEditor';
 import { StyleEditor } from './StyleEditor';
@@ -321,15 +319,10 @@ export function SingleEditor({ path, editor, editorModule }) {
         readOnly={readOnly}
       />
     );
-  } else if (kind === 'image') {
-    // Viewers read their file's BYTES over the serve, not the text file map --
-    // `files` holds source, and an image decoded as utf-8 is nothing.
-    body = <ImageViewer path={path} />;
-  } else if (kind === 'audio' || kind === 'video') {
-    body = <MediaPlayer path={path} kind={kind} />;
   }
-  // No `else`: code/text files are handled by the builtin shell code editor, so
-  // the shell never routes them here. `body` stays null for any other kind.
+  // Image / audio / video are declared by castle.base and land in the
+  // DeclaredEditor branch above via editorModule. No `else`: code/text files
+  // are handled by the builtin shell code editor.
   return (
     <div className={styles.panelBare} style={{ position: 'relative' }}>
       <MainEditor>{body}</MainEditor>

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

@@ -9,6 +9,8 @@
 //
 // Editors live under `editors/` by convention; that is what makes a third
 // party's editor reachable from here without this kit knowing it exists.
+import { createElement, useEffect, useRef } from 'react';
+
 const modules = {
   ...import.meta.glob('/imports/*/editors/**/*.{jsx,js}'),
   ...import.meta.glob('/imports/*/code/editors/**/*.{jsx,js}'),
@@ -20,7 +22,35 @@ export function hasEditorModule(path) {
   return Boolean(path && modules[`/${path}`]);
 }
 
-// Load one, returning its default export. Throws a legible error rather than
+// Base-kit (and bare-deck) editors default-export `mount(el, props)`. This kit's
+// DeclaredEditor expects a React component. Arity distinguishes them: a mount
+// takes the host element first; a React editor takes props only.
+function wrapMountEditor(mount) {
+  return function MountEditorBridge(props) {
+    const ref = useRef(null);
+    const propsRef = useRef(props);
+    propsRef.current = props;
+    useEffect(() => {
+      const node = ref.current;
+      if (!node) return undefined;
+      node.textContent = '';
+      // Mount once per open file. Callers that need live prop updates should
+      // read them themselves; remounting on every onChange identity would wipe
+      // viewers that hold zoom/pan state.
+      const cleanup = mount(node, propsRef.current);
+      return () => {
+        if (typeof cleanup === 'function') cleanup();
+        else node.textContent = '';
+      };
+    }, [props.path, mount]);
+    return createElement('div', {
+      ref,
+      style: { display: 'flex', flex: 1, width: '100%', height: '100%', minHeight: 0 },
+    });
+  };
+}
+
+// Load one, returning a React component. 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}`];
@@ -30,7 +60,11 @@ export async function loadEditorModule(path) {
     );
   }
   const mod = await load();
-  const Editor = mod.default ?? mod.Editor;
+  const Editor = mod.default ?? mod.Editor ?? mod.mount;
   if (!Editor) throw new Error(`"${path}" has no default export to render as an editor.`);
+  // Mount editors (base kit): (el, props) => void|cleanup. React editors: (props) => node.
+  if (typeof Editor === 'function' && Editor.length >= 2) {
+    return wrapMountEditor(Editor);
+  }
   return Editor;
 }