castle-web-cli 0.4.114 → 0.4.116

package/kits/physics-2d/editors/pxArtTimeline.module.css

@@ -171,8 +171,19 @@
    each owned by exactly one element (no two borders meet), so there are no
    doubled/thicker seams. The grid's outer top is the toolbar's existing bottom
    divider; outer right/bottom come from the last cells. */
-.corner {
+/* Shared sticky left-column width: corner and layer heads must match or
+   frame columns drift out of alignment. Content may not force growth
+   (min-width:auto would otherwise expand past the flex basis). */
+.corner,
+.layerHead {
   flex: 0 0 168px;
+  width: 168px;
+  min-width: 168px;
+  max-width: 168px;
+  box-sizing: border-box;
+}
+
+.corner {
   border-right: 1px solid var(--castle-inspector-divider);
   border-bottom: 1px solid var(--castle-inspector-divider);
   background: var(--castle-workspace-bg);
@@ -225,11 +236,10 @@
 }
 
 .layerHead {
-  flex: 0 0 168px;
   display: flex;
   flex-direction: column;
   justify-content: center;
-  gap: 4px;
+  gap: 0;
   padding: 4px 8px;
   border-right: 1px solid var(--castle-inspector-divider);
   border-bottom: 1px solid var(--castle-inspector-divider);
@@ -250,6 +260,12 @@
   gap: 6px;
 }
 
+.layerBottomRow {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
 .visBtn {
   flex: 0 0 auto;
   width: 22px;
@@ -305,7 +321,9 @@
 /* Slim opacity slider: a thin custom track + small thumb so the layer header
    cell stays no taller than the art (thumbnail) cells in its row. */
 .opacity {
-  width: 100%;
+  flex: 1 1 auto;
+  min-width: 0;
+  width: auto;
   height: 12px;
   margin: 0;
   cursor: pointer;
@@ -390,6 +408,13 @@
   display: block;
 }
 
+.thumbCanvasSmooth {
+  width: 100%;
+  height: 100%;
+  image-rendering: auto;
+  display: block;
+}
+
 /* Empty/absent cell: plain and empty. The cell's own grid separators (see the
    .corner/.cell border rules) still bound it; there's no dashed interior. */
 .empty {
@@ -427,7 +452,8 @@
 /* Fade only the linked cell's thumbnail IMAGE (the canvas) to signal a shared
    image. Scoped to the canvas inside a linked thumb, so the blue ring
    (.linkRing box-shadow) and the link badge (.linkBadge) stay full opacity. */
-.linkRing .thumbCanvas {
+.linkRing .thumbCanvas,
+.linkRing .thumbCanvasSmooth {
   opacity: 0.5;
 }
 

package/kits/physics-2d/engine/ScenePlayer.jsx

@@ -74,6 +74,7 @@ export function ScenePlayer({ sceneData, sprites, files, behaviorClasses, onFirs
     const stopLoop = startPlayerLoop(canvas, ctx, runtime, onFirstFrame, onLoopError);
     return () => {
       stopLoop();
+      runtime.dispose();
       window.removeEventListener('keydown', onKeyDown);
       window.removeEventListener('keyup', onKeyUp);
       canvas.removeEventListener('pointerdown', onPointerDown);

package/kits/physics-2d/engine/art.js

@@ -0,0 +1,105 @@
+// "Art" is anything a Sprite can draw: a parsed `.pxart` sprite, or a raster
+// image file (png / jpg / gif / webp / svg) the deck uploaded. Both shapes are
+// handed around in the same `scene.sprites` map, so everything downstream --
+// the Sprite behavior, collider auto-fit, blueprint thumbnails, the editor's
+// empty-actor placeholder -- is written once against this module instead of
+// twice against two formats.
+//
+// An image art carries the same fields a pxart sprite exposes to those readers
+// (`resolution`, `frames`, `tags`, `cornerRadius`), so a reader that only needs
+// geometry or a frame count needs no branch at all. The two functions that
+// really do differ -- rendering a frame, and how many frames there are -- are
+// `renderArtFrame` / `artFrameCount` here.
+
+import { frameCount, renderSpriteFrame } from './pxart';
+
+// An image is one frame, held for as long as anyone asks (a still).
+const STILL_FRAME = Object.freeze({ durationMs: 0 });
+// Before the browser has decoded the file there is no size to lay out against.
+// Zero, rather than a guess, so a sprite drawn early is skipped rather than
+// drawn at the wrong aspect ratio and snapping into place a frame later.
+const PENDING_SIZE = Object.freeze({ width: 0, height: 0 });
+
+// Image arts by URL. Identity has to be stable: the asset map is rebuilt on
+// every editor render, and a fresh object each time would restart the download
+// and miss every cache keyed on the art (frame canvases, opaque bounds).
+const imageArts = new Map();
+
+const listeners = new Set();
+
+// Called when an image finishes decoding. The play loop and the editor's canvas
+// redraw every frame and pick it up on their own; this is for the surfaces that
+// only draw when something changes (blueprint thumbnails).
+export function onArtLoaded(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function imageArt(path, url) {
+  const existing = imageArts.get(url);
+  if (existing) return existing;
+  const image = new Image();
+  const art = {
+    kind: 'image',
+    path,
+    url,
+    image,
+    ready: false,
+    failed: false,
+    resolution: PENDING_SIZE,
+    // pxart-shaped fields, so readers that only want geometry or frame counts
+    // don't have to know which kind of art they were handed.
+    frames: [STILL_FRAME],
+    layers: [],
+    palette: [],
+    tags: [],
+    defaultTag: '',
+    defaultDurationMs: 0,
+    cornerRadius: 0,
+  };
+  image.onload = () => {
+    art.resolution = { width: image.naturalWidth, height: image.naturalHeight };
+    art.ready = art.resolution.width > 0 && art.resolution.height > 0;
+    for (const listener of listeners) listener();
+  };
+  image.onerror = () => {
+    art.failed = true;
+    for (const listener of listeners) listener();
+  };
+  image.src = url;
+  imageArts.set(url, art);
+  return art;
+}
+
+export function isImageArt(art) {
+  return Boolean(art) && art.kind === 'image';
+}
+
+// False while an image is still downloading (or after it failed). Callers use
+// it to skip work that would otherwise be cached against an empty render --
+// there is nothing wrong with the art, it just isn't here yet.
+export function artReady(art) {
+  return isImageArt(art) ? art.ready : Boolean(art);
+}
+
+export function artFrameCount(art) {
+  return isImageArt(art) ? 1 : frameCount(art);
+}
+
+// Draw one frame into `canvas` at the art's native resolution, resizing it to
+// match. Returns false when there was nothing to draw yet (an image still
+// loading), so callers don't cache the blank result.
+export function renderArtFrame(art, frameIndex, canvas) {
+  if (!isImageArt(art)) {
+    renderSpriteFrame(art, frameIndex, canvas);
+    return true;
+  }
+  if (!art.ready) return false;
+  canvas.width = art.resolution.width;
+  canvas.height = art.resolution.height;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return false;
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+  ctx.drawImage(art.image, 0, 0);
+  return true;
+}

package/kits/physics-2d/engine/assets.js

@@ -1,12 +1,20 @@
 import { parseFull } from './pxart';
+import { imageArt } from './art';
+import { initialMedia, isImageFile } from './files';
 
-// Build the runtime asset map from a path->text file map: parsed `.pxart`
-// Sprites keyed by file path (nulls skipped). Shared by the editor App and the
-// play-only entry point so both hand the SceneRuntime the same map.
+// Build the runtime asset map from a path->text file map: everything a Sprite
+// can draw, keyed by file path. Two sources feed one map -- `.pxart` sprites
+// parsed from the text files, and image files from the media manifest (which is
+// URLs, not text, so it comes straight from the bundler rather than through the
+// live file map). Shared by the editor App and the play-only entry point so both
+// hand the SceneRuntime the same map.
 export function collectAssets(files) {
   const sprites = {};
+  for (const [path, url] of Object.entries(initialMedia)) {
+    if (isImageFile(path)) sprites[path] = imageArt(path, url);
+  }
   for (const [path, text] of Object.entries(files)) {
-    if (path.endsWith('.pxart')) {
+    if (path.endsWith('.sprite') || path.endsWith('.pxart')) {
       const sprite = parseFull(text);
       if (sprite) sprites[path] = sprite;
     }

package/kits/physics-2d/engine/audioContext.js

@@ -0,0 +1,34 @@
+// One WebAudio context for the whole deck, made on first use.
+//
+// Most decks never need one: a `<audio>` element plays on its own, and that is
+// the whole Sound behavior until someone asks for something the element can't do
+// -- panning a sound in space, or synthesizing a note that was never a file.
+// Those go through here.
+//
+// A context starts SUSPENDED until the page has been interacted with, exactly
+// like autoplay, so `resumeAudioContext` is called from the same unlock path
+// that retries a refused play (engine/media.js).
+
+let context = null;
+
+export function getAudioContext() {
+  if (context) return context;
+  const Ctor = window.AudioContext || window.webkitAudioContext;
+  if (!Ctor) return null;
+  context = new Ctor();
+  return context;
+}
+
+// The context, only if one already exists -- for callers that shouldn't create
+// one just by asking (the unlock handler, teardown).
+export function existingAudioContext() {
+  return context;
+}
+
+export function resumeAudioContext() {
+  if (context && context.state === 'suspended') {
+    context.resume().catch(() => {
+      /* still blocked; the next gesture tries again */
+    });
+  }
+}

package/kits/physics-2d/engine/blueprint.js

@@ -372,16 +372,16 @@ export function blankPxArtText() {
   return serializeCompact({ palette: {}, grid });
 }
 
-// `drawings/drawing-N.pxart` -- next free numbered slug, so repeated adds don't
+// `drawings/drawing-N.sprite` -- next free numbered slug, so repeated adds don't
 // collide and a deleted drawing's number isn't reused.
 function mintDrawingPath(files) {
-  const re = new RegExp(`^${DRAWINGS_DIR}/drawing-(\\d+)\\.pxart$`);
+  const re = new RegExp(`^${DRAWINGS_DIR}/drawing-(\\d+)\\.(?:pxart|sprite)$`);
   let max = 0;
   for (const path of Object.keys(files ?? {})) {
     const m = path.match(re);
     if (m) max = Math.max(max, Number(m[1]));
   }
-  return `${DRAWINGS_DIR}/drawing-${max + 1}.pxart`;
+  return `${DRAWINGS_DIR}/drawing-${max + 1}.sprite`;
 }
 
 // The z that draws on top of every current actor: max effective z + 1 (0 for

package/kits/physics-2d/engine/collider.js

@@ -16,7 +16,7 @@
 //
 // Shapes are in the UNROTATED box frame; the draw pipeline (scene.js) and the
 // matter body (matterBridge) apply Layout.rotation, so nothing here rotates.
-import { frameCount, renderSpriteFrame } from './pxart';
+import { artFrameCount, artReady, renderArtFrame } from './art';
 import { spriteDestRect } from './spriteGeometry';
 
 // ---------------------------------------------------------------------------
@@ -41,13 +41,17 @@ function accumulateOpaquePixels(acc, ctx, canvas) {
 
 function opaqueBoundsFraction(sprite) {
   if (opaqueBoundsCache.has(sprite)) return opaqueBoundsCache.get(sprite);
+  // An image that hasn't decoded has no pixels to scan yet. Report "unknown"
+  // without caching, so the answer is computed once it does rather than a
+  // never-revisited null.
+  if (!artReady(sprite)) return undefined;
   const { width, height } = sprite.resolution;
   const canvas = document.createElement('canvas');
   const ctx = canvas.getContext('2d');
   const acc = { minX: Infinity, minY: Infinity, maxX: -Infinity, maxY: -Infinity };
-  const total = frameCount(sprite);
+  const total = artFrameCount(sprite);
   for (let frame = 0; frame < total; frame++) {
-    renderSpriteFrame(sprite, frame, canvas);
+    renderArtFrame(sprite, frame, canvas);
     accumulateOpaquePixels(acc, ctx, canvas);
   }
   const bounds =
@@ -63,7 +67,9 @@ function opaqueBoundsFraction(sprite) {
   return bounds;
 }
 
-// True when a resolved sprite has no opaque pixels across any frame.
+// True when a resolved sprite has no opaque pixels across any frame. An image
+// still decoding is NOT empty -- it just isn't here yet, and flashing the
+// editor's placeholder box under it while it loads would be a lie.
 export function spriteIsEmpty(sprite) {
   return !sprite || opaqueBoundsFraction(sprite) === null;
 }
@@ -160,21 +166,26 @@ export function getColliderShape(actor) {
   return shapes && shapes.length ? shapes[0] : null;
 }
 
+// Bounding box of a point list, as [x0, y0, x1, y1]. Shared with the physics
+// bridge, which needs the same box to fall back to when matter can't build a
+// body from the vertices.
+export function pointsBounds(points) {
+  let x0 = Infinity;
+  let y0 = Infinity;
+  let x1 = -Infinity;
+  let y1 = -Infinity;
+  for (const p of points) {
+    if (p.x < x0) x0 = p.x;
+    if (p.y < y0) y0 = p.y;
+    if (p.x > x1) x1 = p.x;
+    if (p.y > y1) y1 = p.y;
+  }
+  return [x0, y0, x1, y1];
+}
+
 function shapeAabb(s) {
   if (s.type === 'circle') return [s.cx - s.radius, s.cy - s.radius, s.cx + s.radius, s.cy + s.radius];
-  if (s.type === 'triangle' || s.type === 'polygon') {
-    let x0 = Infinity;
-    let y0 = Infinity;
-    let x1 = -Infinity;
-    let y1 = -Infinity;
-    for (const p of s.points) {
-      if (p.x < x0) x0 = p.x;
-      if (p.y < y0) y0 = p.y;
-      if (p.x > x1) x1 = p.x;
-      if (p.y > y1) y1 = p.y;
-    }
-    return [x0, y0, x1, y1];
-  }
+  if (s.type === 'triangle' || s.type === 'polygon') return pointsBounds(s.points);
   const ang = ((s.angle ?? 0) * Math.PI) / 180;
   if (!ang) return [s.x, s.y, s.x + s.width, s.y + s.height];
   // AABB of a box rotated about its center: project the half-extents onto the axes.

package/kits/physics-2d/engine/files.js

@@ -19,12 +19,13 @@ const rawModules = {
       '/imports/*/scenes/**/*.scene',
       '/imports/*/blueprints/**/*.scene',
       '/imports/*/drawings/**/*.pxart',
+      '/imports/*/drawings/**/*.sprite',
       '/imports/*/behaviors/**/*.jsx',
     ],
     { query: '?raw', import: 'default', eager: true }
   ),
   ...import.meta.glob(
-    ['/scenes/**/*.scene', '/blueprints/**/*.scene', '/drawings/**/*.pxart', '/behaviors/**/*.jsx'],
+    ['/scenes/**/*.scene', '/blueprints/**/*.scene', '/drawings/**/*.pxart', '/drawings/**/*.sprite', '/behaviors/**/*.jsx'],
     { query: '?raw', import: 'default', eager: true }
   ),
 };
@@ -33,9 +34,84 @@ export const initialFiles = Object.fromEntries(
     .map(([globPath, text]) => [globPath.replace(/^\//, ''), text])
     .sort(([a], [b]) => a.localeCompare(b))
 );
+
+// Media files -- images, sounds, videos -- as path -> URL. These are BYTES, not
+// text: the bundler hands back a URL (a real one while serving, a data: URI in a
+// saved deck, which is why loading one through this rather than fetching a path
+// keeps working once the deck is a single file).
+//
+// Unlike the text globs above these aren't scoped to a folder: media arrives by
+// upload and lands wherever the person uploading put it, so the pattern is the
+// whole deck minus what is never deck content. (Both patterns and options must
+// be literals -- import.meta.glob is a compile-time transform.)
+const mediaModules = import.meta.glob(
+  [
+    '/**/*.{png,jpg,jpeg,gif,webp,svg,mp3,wav,m4a,mp4}',
+    '!/node_modules/**',
+    '!/dist/**',
+    '!/.castle/**',
+  ],
+  { eager: true, import: 'default' }
+);
+export const initialMedia = Object.fromEntries(
+  Object.entries(mediaModules)
+    .map(([globPath, url]) => [globPath.replace(/^\//, ''), url])
+    .sort(([a], [b]) => a.localeCompare(b))
+);
+
+// What a media path is, by extension.
+//
+// This list is deliberately short. A deck is published as a single file, where
+// every asset becomes a `data:` URI -- and a data URI's declared type is taken
+// at face value, unlike a served file whose bytes the browser will sniff. So a
+// format the browser merely tolerates when served can fail once published, and
+// a format one browser plays can be silently dead on another. Both failures land
+// on the player, after the creator has stopped looking.
+//
+// So: h264/aac mp4 for video, mp3/wav/m4a for audio, and the image formats every
+// browser has agreed on for a decade. Anything else is something to convert, and
+// castle.json says so by name (see the `unsupported` file types there).
+const IMAGE_EXTS = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg'];
+const AUDIO_EXTS = ['.mp3', '.wav', '.m4a'];
+const VIDEO_EXTS = ['.mp4'];
+
+const hasExt = (path, exts) => exts.some((ext) => path.toLowerCase().endsWith(ext));
+
+export function isImageFile(path) {
+  return hasExt(path, IMAGE_EXTS);
+}
+export function isAudioFile(path) {
+  return hasExt(path, AUDIO_EXTS);
+}
+export function isVideoFile(path) {
+  return hasExt(path, VIDEO_EXTS);
+}
+
+// Deck-relative paths of every media file of one kind, sorted. What the
+// inspectors' file pickers list.
+export function mediaFilesOfKind(kind) {
+  const matches = { image: isImageFile, audio: isAudioFile, video: isVideoFile }[kind];
+  return Object.keys(initialMedia).filter((path) => matches(path));
+}
+// Which editor a file opens in. The image / audio kinds are VIEWERS -- an
+// uploaded asset is content this kit shows but doesn't edit (art you can edit is
+// `.pxart`). Each extension gets its own line: the serve parses this function to
+// learn which extensions the kit owns an editor for, and only matches one
+// `endsWith` per `return`.
 export function getFileKind(path) {
   if (path.endsWith('.scene')) return 'scene';
+  if (path.endsWith('.sprite')) return 'pxart';
   if (path.endsWith('.pxart')) return 'pxart';
+  if (path.endsWith('.png')) return 'image';
+  if (path.endsWith('.jpg')) return 'image';
+  if (path.endsWith('.jpeg')) return 'image';
+  if (path.endsWith('.gif')) return 'image';
+  if (path.endsWith('.webp')) return 'image';
+  if (path.endsWith('.svg')) return 'image';
+  if (path.endsWith('.mp3')) return 'audio';
+  if (path.endsWith('.wav')) return 'audio';
+  if (path.endsWith('.m4a')) return 'audio';
+  if (path.endsWith('.mp4')) return 'video';
   if (path.endsWith('.js') || path.endsWith('.jsx')) return 'code';
   return 'text';
 }

package/kits/physics-2d/engine/liveReload.js

@@ -9,7 +9,7 @@ import { useEffect, useRef, useState } from 'react';
 import { onFilesChanged, requestReload } from 'castle-web-sdk';
 import { initialFiles } from './files';
 
-const DATA_EXTS = ['.scene', '.pxart', '.drawing'];
+const DATA_EXTS = ['.scene', '.pxart', '.sprite', '.drawing'];
 const CODE_EXTS = ['.js', '.jsx', '.ts', '.tsx', '.css'];
 
 export function isDataFile(path) {

package/kits/physics-2d/engine/media.js

@@ -0,0 +1,212 @@
+// The pool of playing media elements: one `<audio>` / `<video>` per actor per
+// file. Behaviors (Sound, Video) ask for theirs each frame and set the state
+// they want on it; this module owns creating, reusing, and reaping them.
+//
+// The pool is MODULE-level, not per-SceneRuntime, because the editor builds a
+// throwaway runtime every frame to draw the edit preview -- a per-runtime pool
+// would mean a new <video> element sixty times a second. Keyed by actor + file
+// instead, entries survive that churn and are reaped by disuse: anything not
+// asked for in the last few frames belongs to an actor that was despawned, a
+// scene that was left, or a file prop that changed, and gets stopped and
+// dropped. `stopAll` is the hard version, for leaving play mode.
+//
+// Nothing here plays anything on its own. A behavior's `update` only runs in
+// play mode, so a deck's sound stays silent in the editor by construction; the
+// editor's video preview draws a paused element's first frame.
+
+import { initialMedia } from './files';
+import { getAudioContext, resumeAudioContext } from './audioContext';
+
+// Reaped after this long without being asked for. Long enough to survive a
+// scene's worth of frames where an actor is briefly not drawn (offscreen,
+// behind a `playing: false`), short enough that a despawned actor's sound stops
+// promptly.
+const IDLE_REAP_MS = 1500;
+
+const entries = new Map();
+// One-shot plays: copies of an element that overlap the original instead of
+// cutting it off (a sound effect fired again before the last one finished).
+// They are not keyed by anything -- they exist until they end.
+const oneShots = new Set();
+// Elements routed through WebAudio for panning, and their panner nodes. An
+// element can only be connected to the graph ONCE, so this is also the record
+// of which ones already are.
+const panners = new WeakMap();
+// Elements whose play() was refused for want of a user gesture. The browser
+// blocks audio until someone has interacted with the page, and a deck's first
+// sound is often on load, so they're retried on the first real input.
+const blocked = new Set();
+let unlockBound = false;
+
+function now() {
+  return typeof performance !== 'undefined' ? performance.now() : Date.now();
+}
+
+// Resolve a deck-relative media path to the URL the bundler gave it. Returns
+// null for a path the deck doesn't have, which is how a cleared or misspelled
+// file prop stays silent instead of throwing every frame.
+export function mediaUrl(path) {
+  return (path && initialMedia[path]) || null;
+}
+
+function bindUnlock() {
+  if (unlockBound || typeof window === 'undefined') return;
+  unlockBound = true;
+  const retry = () => {
+    resumeAudioContext();
+    for (const element of blocked) {
+      element.play().then(
+        () => blocked.delete(element),
+        () => {
+          /* still refused -- keep it queued for the next gesture */
+        }
+      );
+    }
+  };
+  window.addEventListener('pointerdown', retry, { passive: true });
+  window.addEventListener('keydown', retry, { passive: true });
+}
+
+// Play, tolerating the autoplay policy: a refused play is queued for the next
+// user gesture rather than thrown away or logged every frame.
+export function playMedia(element) {
+  if (!element.paused) return;
+  bindUnlock();
+  const started = element.play();
+  if (started && typeof started.catch === 'function') {
+    started.then(
+      () => blocked.delete(element),
+      () => blocked.add(element)
+    );
+  }
+}
+
+// Pan a sound left/right (-1..1). The element has no panning of its own, so the
+// first non-zero pan routes it through a WebAudio graph -- permanently, since a
+// media element can only be connected once. Which is why pan 0 (the default)
+// touches none of this: a deck that doesn't pan never builds an audio graph.
+export function setMediaPan(element, pan) {
+  const wanted = Number.isFinite(pan) ? Math.min(1, Math.max(-1, pan)) : 0;
+  let node = panners.get(element);
+  if (!node) {
+    if (wanted === 0) return;
+    const ctx = getAudioContext();
+    if (!ctx || !ctx.createStereoPanner) return;
+    try {
+      const source = ctx.createMediaElementSource(element);
+      node = ctx.createStereoPanner();
+      source.connect(node);
+      node.connect(ctx.destination);
+      panners.set(element, node);
+    } catch {
+      // Already connected elsewhere, or the browser refused -- play unpanned.
+      return;
+    }
+  }
+  node.pan.value = wanted;
+  resumeAudioContext();
+}
+
+// Play a copy of this sound, overlapping whatever is already playing. Returns a
+// promise that resolves when the copy finishes, so a caller can wait for it.
+// Copies are never reused: a one-shot is done when it's done.
+export function playOneShot(path, { volume = 1, playbackRate = 1, pan = 0 } = {}) {
+  const url = mediaUrl(path);
+  if (!url) return Promise.resolve();
+  const element = document.createElement('audio');
+  element.src = url;
+  element.volume = volume;
+  element.playbackRate = playbackRate;
+  oneShots.add(element);
+  const finished = new Promise((resolve) => {
+    const done = () => {
+      oneShots.delete(element);
+      element.removeAttribute('src');
+      resolve();
+    };
+    element.addEventListener('ended', done, { once: true });
+    element.addEventListener('error', done, { once: true });
+  });
+  if (pan !== 0) setMediaPan(element, pan);
+  playMedia(element);
+  return finished;
+}
+
+export function stopMedia(element) {
+  blocked.delete(element);
+  element.pause();
+  try {
+    element.currentTime = 0;
+  } catch {
+    // A element that never loaded has no seekable timeline; nothing to reset.
+  }
+}
+
+// The element for one actor's media prop, created on first ask. `kind` is
+// 'audio' or 'video'. Returns null when the path names no file in the deck.
+// Asking is also what keeps it alive -- see the reap above.
+export function mediaElement(actorId, kind, path) {
+  const url = mediaUrl(path);
+  if (!url) return null;
+  const key = `${actorId}|${kind}|${path}`;
+  const existing = entries.get(key);
+  if (existing) {
+    existing.usedAt = now();
+    return existing.element;
+  }
+  const element = document.createElement(kind);
+  element.src = url;
+  element.preload = 'auto';
+  element.crossOrigin = 'anonymous';
+  if (kind === 'video') {
+    // Decode a first frame without playing, so the editor preview and a
+    // `playing: false` video show the picture rather than nothing. `playsInline`
+    // keeps iOS from taking a played video fullscreen over the deck.
+    element.playsInline = true;
+    element.muted = true;
+    element.addEventListener('loadedmetadata', () => {
+      try {
+        element.currentTime = 0;
+      } catch {
+        // Seeking before the stream is ready; the first frame arrives anyway.
+      }
+    });
+  }
+  entries.set(key, { element, actorId, usedAt: now() });
+  return element;
+}
+
+// Stop and drop what no longer belongs to the running scene. Called once a
+// frame by the media system, with the live actor ids.
+//
+// A despawned actor is reaped on the spot -- its sound has to stop the moment
+// the thing making it is gone, not a beat later. Everything else goes by
+// disuse, which is what catches a `file` prop that changed under an actor that
+// is still there.
+export function reapUnusedMedia(liveActorIds) {
+  const cutoff = now() - IDLE_REAP_MS;
+  for (const [key, entry] of entries) {
+    const gone = liveActorIds ? !liveActorIds.has(entry.actorId) : false;
+    if (!gone && entry.usedAt >= cutoff) continue;
+    stopMedia(entry.element);
+    entry.element.removeAttribute('src');
+    entries.delete(key);
+  }
+}
+
+// Stop and drop everything, now: leaving play mode, loading another scene,
+// tearing the player down. Silence has to be immediate here -- a sound that
+// outlives the scene that started it is the worst version of this feature.
+export function stopAllMedia() {
+  for (const [, entry] of entries) {
+    stopMedia(entry.element);
+    entry.element.removeAttribute('src');
+  }
+  for (const element of oneShots) {
+    stopMedia(element);
+    element.removeAttribute('src');
+  }
+  entries.clear();
+  oneShots.clear();
+  blocked.clear();
+}