castle-web-cli 0.4.84 → 0.4.85

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

@@ -0,0 +1,686 @@
+import { initialFiles, parseJsonFile } from './files';
+import { getBlueprintTemplate, mergeComponents } from './blueprint';
+import { installPhysics } from '../physics';
+import { getColliderRect, intersects, spriteIsEmpty } from './collider';
+
+const CARD_WIDTH = 500;
+const CARD_HEIGHT = 700;
+const DEFAULT_VIEWPORT = {
+  width: CARD_WIDTH,
+  height: CARD_HEIGHT,
+  originX: 0,
+  originY: 0,
+};
+
+export const cardSize = { width: CARD_WIDTH, height: CARD_HEIGHT };
+
+// Resolve a scene-file name to its key in the loaded file map. Accepts
+// 'main.scene', 'scenes/main.scene', './scenes/main.scene', or 'main' -- the
+// `.scene` extension and a leading `scenes/` are both optional.
+function resolveSceneFileKey(name) {
+  const key = String(name).replace(/^\.?\//, '');
+  const candidates = [key];
+  if (!key.endsWith('.scene')) candidates.push(`${key}.scene`);
+  for (const candidate of [...candidates]) {
+    if (!candidate.startsWith('scenes/')) candidates.push(`scenes/${candidate}`);
+  }
+  return candidates.find((candidate) => initialFiles[candidate] !== undefined) ?? key;
+}
+
+export class SceneRuntime {
+  // `files` is the live deck files map (path -> text), used to resolve every
+  // actor's `blueprint` ref against the CURRENT blueprint file content -- not
+  // a load-time snapshot -- so a blueprint edit propagates to every scene that
+  // places it, in both the editor and play mode / `PlayOnly`.
+  constructor(sceneData, behaviors, sprites, files) {
+    this.behaviors = new Map(behaviors.map((Behavior) => [Behavior.behaviorName, Behavior]));
+    this.sprites = sprites ?? {};
+    this.files = files ?? {};
+    this.time = 0;
+    this.keys = new Set();
+    this.pointer = { x: 0, y: 0, down: false };
+    this.data = { actors: [] };
+    this.actors = new Map();
+    this.camera = undefined;
+    this.status = undefined;
+    // Registered systems run once per frame after all behavior `update`s (see
+    // `update`). A system is a plain object with an optional
+    // `afterBehaviors(scene, dt)` hook; this is the seam the physics module
+    // plugs into so it stays decoupled from the core runtime and portable to
+    // other kits.
+    this.systems = [];
+    this.load(sceneData);
+  }
+
+  // Register a per-frame system (e.g. the physics simulation). Systems step in
+  // registration order, after behaviors, every `update`. Returns the system.
+  registerSystem(system) {
+    this.systems.push(system);
+    return system;
+  }
+
+  load(sceneData) {
+    this.data = structuredClone(sceneData);
+    this.actors = new Map();
+    for (const actor of this.data.actors ?? []) {
+      actor.runtime = {};
+      if (actor.blueprint) {
+        const template = getBlueprintTemplate(this.files, actor.blueprint);
+        actor.components = mergeComponents(template?.components, actor.components);
+      }
+      this.actors.set(actor.id, actor);
+      for (const [behaviorName, Behavior] of this.behaviors) {
+        const component = actor.components[behaviorName];
+        if (component) {
+          actor.components[behaviorName] = {
+            ...Behavior.defaultProps,
+            ...component,
+          };
+        }
+      }
+    }
+  }
+
+  // Read and parse a scene file by name, returning its scene data. Use this
+  // instead of `import x from './scenes/foo.scene'` -- scene files are data, not
+  // JS modules, so importing them is unsupported.
+  readFromFile(name) {
+    const key = resolveSceneFileKey(name);
+    const text = initialFiles[key];
+    if (text === undefined) {
+      throw new Error(`scene file not found: ${name}`);
+    }
+    const { value, error } = parseJsonFile(key, text);
+    if (error) throw new Error(error);
+    return value;
+  }
+
+  // Transition the running scene to the scene stored in the named file (read it
+  // fresh, then load it). The building block for "go to scene" / restart.
+  loadFromFile(name) {
+    this.load(this.readFromFile(name));
+  }
+
+  clone() {
+    // Route through makeScene so the clone gets the same registered systems
+    // (physics) as a freshly-made runtime.
+    return makeScene(this.serialize(), [...this.behaviors.values()], this.sprites, this.files);
+  }
+
+  serialize() {
+    return structuredClone(this.data);
+  }
+
+  getActor(actorId) {
+    return this.actors.get(actorId);
+  }
+
+  getActors() {
+    return [...this.actors.values()].sort((a, b) => {
+      const az = getLayout(a)?.z ?? 0;
+      const bz = getLayout(b)?.z ?? 0;
+      return az - bz;
+    });
+  }
+
+  getComponent(actor, behaviorName) {
+    return actor?.components?.[behaviorName] ?? null;
+  }
+
+  actorWith(behaviorName) {
+    for (const actor of this.actors.values()) {
+      if (actor.components?.[behaviorName]) return actor;
+    }
+    return null;
+  }
+
+  actorsWith(behaviorName) {
+    const out = [];
+    for (const actor of this.getActors()) {
+      if (actor.components?.[behaviorName]) out.push(actor);
+    }
+    return out;
+  }
+
+  colliderRect(actorOrId) {
+    const actor = typeof actorOrId === 'string' ? this.getActor(actorOrId) : actorOrId;
+    return getColliderRect(actor, this.sprites);
+  }
+
+  overlaps(first, second) {
+    const a = this.colliderRect(first);
+    const b = this.colliderRect(second);
+    return Boolean(a && b && intersects(a, b));
+  }
+
+  // Raw spawn: `actor.components` is used as-is (already-resolved values),
+  // just filled out with each behavior's defaultProps. Internal use -- prefer
+  // `spawnFromBlueprint` so a runtime-spawned actor is a blueprint instance
+  // like every other actor.
+  spawnActor(actor) {
+    const id = actor.id ?? mintActorId(new Set(this.actors.keys()));
+    const components = {};
+    for (const [name, props] of Object.entries(actor.components ?? {})) {
+      const Behavior = this.behaviors.get(name);
+      components[name] = Behavior ? { ...Behavior.defaultProps, ...props } : { ...props };
+    }
+    const next = { ...actor, id, components, runtime: {} };
+    this.data.actors.push(next);
+    this.actors.set(id, next);
+    return next;
+  }
+
+  // The blessed spawn path: resolve `blueprintPath` from the live `files`,
+  // merge with `overrides.components` (sparse, same shape as a placed
+  // instance's file overrides), and spawn the result. `overrides.id`, when
+  // given, is used as the new actor's id.
+  spawnFromBlueprint(blueprintPath, overrides = {}) {
+    const template = getBlueprintTemplate(this.files, blueprintPath);
+    const components = mergeComponents(template?.components, overrides.components);
+    return this.spawnActor({ id: overrides.id, blueprint: blueprintPath, components });
+  }
+
+  despawnActor(actorId) {
+    const actor = this.actors.get(actorId);
+    if (!actor) return false;
+    this.actors.delete(actorId);
+    const idx = this.data.actors.findIndex((a) => a.id === actorId);
+    if (idx !== -1) this.data.actors.splice(idx, 1);
+    return true;
+  }
+
+  // Translate a screen-space pointer event into the scene's world-space
+  // `pointer`. The runtime owns this mapping (it knows the camera) so every
+  // input path -- the standalone ScenePlayer and the editor's play mode --
+  // agree on it; behaviors read `scene.pointer` in world coordinates. Pass
+  // `down` to also update the press state.
+  setPointerFromScreen(canvas, clientX, clientY, down) {
+    const point = screenToCard(canvas, clientX, clientY);
+    this.pointer.x = point.x + (this.camera?.x ?? 0);
+    this.pointer.y = point.y + (this.camera?.y ?? 0);
+    if (down !== undefined) this.pointer.down = down;
+  }
+
+  update(dt) {
+    this.time += dt;
+    for (const actor of this.getActors()) {
+      this.forEachBehavior(actor, (instance) => instance.update?.(actor, this, dt));
+    }
+    // Behaviors have expressed their intent (velocities, forces) for this
+    // frame; now let registered systems advance (physics integrates, writes
+    // results back to Layout, and dispatches collision callbacks).
+    for (const system of this.systems) {
+      system.afterBehaviors?.(this, dt);
+    }
+  }
+
+  forEachBehavior(actor, callback) {
+    for (const [behaviorName, props] of Object.entries(actor.components)) {
+      if (!props) continue;
+      const Behavior = this.behaviors.get(behaviorName);
+      if (!Behavior) continue;
+      callback(new Behavior(props));
+    }
+  }
+
+  draw(ctx, options = {}) {
+    const viewport = options.viewport ?? DEFAULT_VIEWPORT;
+    ctx.clearRect(0, 0, viewport.width, viewport.height);
+    const camera = options.useCamera && this.camera ? this.camera : { x: 0, y: 0 };
+    // When a blueprint is selected in the editor, its instances stay at full
+    // opacity and everything else -- the background and every other actor --
+    // dims, so the selection stands out.
+    const dimBlueprintPath = options.dimBlueprintPath ?? null;
+    if (options.showCropOutline) {
+      ctx.fillStyle = this.data.background ?? '#0f2a1d';
+      ctx.fillRect(0, 0, viewport.width, viewport.height);
+      if (dimBlueprintPath) {
+        ctx.fillStyle = 'rgba(0, 0, 0, 0.55)';
+        ctx.fillRect(0, 0, viewport.width, viewport.height);
+      }
+    } else {
+      ctx.fillStyle = this.data.background ?? '#0f2a1d';
+      ctx.fillRect(0, 0, CARD_WIDTH, CARD_HEIGHT);
+      if (dimBlueprintPath) {
+        ctx.fillStyle = 'rgba(0, 0, 0, 0.55)';
+        ctx.fillRect(0, 0, CARD_WIDTH, CARD_HEIGHT);
+      }
+    }
+
+    ctx.save();
+    if (options.useCamera && camera) {
+      ctx.translate(
+        Math.round(viewport.originX - (camera.x ?? 0)),
+        Math.round(viewport.originY - (camera.y ?? 0))
+      );
+    }
+    if (options.showGrid) drawDotGrid(ctx, options.gridSize, viewport, camera);
+    for (const actor of this.getActors()) {
+      // Per-actor transform: Layout's `rotation` (degrees) rotates every draw
+      // behavior of the actor about its center.
+      ctx.save();
+      if (dimBlueprintPath && actor.blueprint !== dimBlueprintPath) {
+        ctx.globalAlpha = 0.2;
+      }
+      applyLayoutRotation(ctx, getLayout(actor));
+      if (options.editPlaceholders && shouldDrawEditPlaceholder(actor, this.sprites)) {
+        drawEditPlaceholder(ctx, actor);
+      }
+      this.forEachBehavior(actor, (instance) => instance.draw?.(actor, this, ctx, options));
+      ctx.restore();
+    }
+
+    if (options.selectedActorIds) {
+      for (const id of options.selectedActorIds) {
+        const actor = this.getActor(id);
+        if (actor) drawSelection(ctx, actor);
+      }
+    }
+    if (options.marquee) drawMarquee(ctx, options.marquee);
+    if (options.showCropOutline) drawCropOutline(ctx);
+    ctx.restore();
+  }
+
+  actorAt(x, y) {
+    const actors = this.getActors().slice().reverse();
+    for (const actor of actors) {
+      const layout = getLayout(actor);
+      if (!layout) continue;
+      if (
+        x >= layout.x &&
+        x <= layout.x + layout.width &&
+        y >= layout.y &&
+        y <= layout.y + layout.height
+      ) {
+        return actor;
+      }
+    }
+    return null;
+  }
+
+  actorIdsInRect(rect) {
+    const minX = rect.x;
+    const minY = rect.y;
+    const maxX = rect.x + rect.width;
+    const maxY = rect.y + rect.height;
+    const ids = [];
+    for (const actor of this.getActors()) {
+      const layout = getLayout(actor);
+      if (!layout) continue;
+      if (
+        layout.x + layout.width >= minX &&
+        layout.x <= maxX &&
+        layout.y + layout.height >= minY &&
+        layout.y <= maxY
+      ) {
+        ids.push(actor.id);
+      }
+    }
+    return ids;
+  }
+}
+
+export function makeScene(sceneData, behaviors, sprites, files) {
+  const runtime = new SceneRuntime(sceneData, behaviors, sprites, files);
+  // Physics is a self-contained module registered as a runtime system. The
+  // matter engine is created lazily on the first simulation step, so draw-only
+  // editor previews (which never call update) stay free.
+  installPhysics(runtime);
+  return runtime;
+}
+
+export function setActorComponent(sceneData, actorId, behaviorName, nextProps) {
+  const next = structuredClone(sceneData);
+  const actor = next.actors.find((candidate) => candidate.id === actorId);
+  if (!actor) return sceneData;
+  actor.components[behaviorName] = {
+    ...(actor.components[behaviorName] ?? {}),
+    ...nextProps,
+  };
+  return next;
+}
+
+export function removeActorComponent(sceneData, actorId, behaviorName) {
+  const next = structuredClone(sceneData);
+  const actor = next.actors.find((candidate) => candidate.id === actorId);
+  if (!actor || !(behaviorName in actor.components)) return sceneData;
+  delete actor.components[behaviorName];
+  return next;
+}
+
+export function moveActors(sceneData, actorIds, dx, dy) {
+  if (actorIds.length === 0) return sceneData;
+  const next = structuredClone(sceneData);
+  let changed = false;
+  for (const id of actorIds) {
+    const actor = next.actors.find((candidate) => candidate.id === id);
+    const layout = actor ? actor.components.Layout : null;
+    if (!actor || !layout) continue;
+    actor.components.Layout = {
+      ...layout,
+      x: Math.round(layout.x + dx),
+      y: Math.round(layout.y + dy),
+    };
+    changed = true;
+  }
+  return changed ? next : sceneData;
+}
+
+export function removeActors(sceneData, actorIds) {
+  if (actorIds.length === 0) return sceneData;
+  const toRemove = new Set(actorIds);
+  const next = structuredClone(sceneData);
+  next.actors = next.actors.filter((actor) => !toRemove.has(actor.id));
+  return next.actors.length === sceneData.actors.length ? sceneData : next;
+}
+
+export function duplicateActors(sceneData, actorIds) {
+  if (actorIds.length === 0) return { sceneData, newIds: [] };
+  const next = structuredClone(sceneData);
+  const existingIds = new Set(next.actors.map((actor) => actor.id));
+  const offset = duplicateOffset(sceneData);
+  const newIds = [];
+  for (const id of actorIds) {
+    const source = next.actors.find((candidate) => candidate.id === id);
+    if (!source) continue;
+    const copy = structuredClone(source);
+    copy.id = dedupeActorId(existingIds, stripDupSuffix(source.id));
+    existingIds.add(copy.id);
+    const layout = copy.components.Layout;
+    if (layout) {
+      copy.components.Layout = {
+        ...layout,
+        x: Math.round(layout.x + offset),
+        y: Math.round(layout.y + offset),
+      };
+    }
+    next.actors.push(copy);
+    newIds.push(copy.id);
+  }
+  return { sceneData: next, newIds };
+}
+
+function duplicateOffset(sceneData) {
+  const gridSize = sceneData.editor?.gridSize;
+  return Number.isFinite(gridSize) && gridSize > 0 ? gridSize : 50;
+}
+
+export function arrangeActors(sceneData, actorIds, action) {
+  if (actorIds.length === 0) return sceneData;
+  const selected = new Set(actorIds);
+  const ordered = sceneData.actors
+    .map((actor, index) => ({ actor, index, layout: getLayout(actor) }))
+    .filter((entry) => entry.layout)
+    .sort((a, b) => (a.layout.z ?? 0) - (b.layout.z ?? 0) || a.index - b.index);
+  if (!ordered.some((entry) => selected.has(entry.actor.id))) return sceneData;
+  const arranged = arrangeOrderedActors(ordered, selected, action);
+  if (arranged === ordered) return sceneData;
+  return applyActorOrder(sceneData, arranged);
+}
+
+function arrangeOrderedActors(ordered, selected, action) {
+  if (action === 'front') return moveSelectionToEdge(ordered, selected, 'front');
+  if (action === 'back') return moveSelectionToEdge(ordered, selected, 'back');
+  if (action === 'forward') return moveSelectionOneStep(ordered, selected, 1);
+  if (action === 'backward') return moveSelectionOneStep(ordered, selected, -1);
+  return ordered;
+}
+
+function moveSelectionToEdge(ordered, selected, edge) {
+  const picked = ordered.filter((entry) => selected.has(entry.actor.id));
+  const rest = ordered.filter((entry) => !selected.has(entry.actor.id));
+  const next = edge === 'front' ? [...rest, ...picked] : [...picked, ...rest];
+  return sameActorOrder(ordered, next) ? ordered : next;
+}
+
+function moveSelectionOneStep(ordered, selected, direction) {
+  const next = [...ordered];
+  if (direction > 0) {
+    for (let index = next.length - 2; index >= 0; index--) {
+      if (!selected.has(next[index].actor.id) || selected.has(next[index + 1].actor.id)) continue;
+      [next[index], next[index + 1]] = [next[index + 1], next[index]];
+    }
+  } else {
+    for (let index = 1; index < next.length; index++) {
+      if (!selected.has(next[index].actor.id) || selected.has(next[index - 1].actor.id)) continue;
+      [next[index], next[index - 1]] = [next[index - 1], next[index]];
+    }
+  }
+  return sameActorOrder(ordered, next) ? ordered : next;
+}
+
+function sameActorOrder(a, b) {
+  return a.length === b.length && a.every((entry, index) => entry.actor.id === b[index].actor.id);
+}
+
+function applyActorOrder(sceneData, ordered) {
+  const zById = new Map(ordered.map((entry, index) => [entry.actor.id, index]));
+  const next = structuredClone(sceneData);
+  let changed = false;
+  for (const actor of next.actors) {
+    const z = zById.get(actor.id);
+    const layout = getLayout(actor);
+    if (z === undefined || !layout || layout.z === z) continue;
+    actor.components.Layout = { ...layout, z };
+    changed = true;
+  }
+  return changed ? next : sceneData;
+}
+
+// Axis-aligned layout box of a single actor in world (card) units, or null.
+// Ignores Layout.rotation -- v1 selection bounds are axis-aligned (the canvas
+// `drawSelection` still draws the rotated outline for per-actor feedback).
+export function getLayoutRect(actor) {
+  const layout = getLayout(actor);
+  if (!layout) return null;
+  return { x: layout.x, y: layout.y, width: layout.width, height: layout.height };
+}
+
+// Union axis-aligned bounding box of the given actors in world units, or null
+// when none of them have a Layout. Used to anchor the on-canvas selection
+// toolbar to the whole multi-selection.
+export function getSelectionBounds(sceneData, actorIds) {
+  if (!sceneData || !actorIds || actorIds.length === 0) return null;
+  const wanted = new Set(actorIds);
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let found = false;
+  for (const actor of sceneData.actors) {
+    if (!wanted.has(actor.id)) continue;
+    const rect = getLayoutRect(actor);
+    if (!rect) continue;
+    found = true;
+    minX = Math.min(minX, rect.x);
+    minY = Math.min(minY, rect.y);
+    maxX = Math.max(maxX, rect.x + rect.width);
+    maxY = Math.max(maxY, rect.y + rect.height);
+  }
+  if (!found) return null;
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
+
+export function mintActorId(existing) {
+  for (let attempt = 0; attempt < 64; attempt++) {
+    const candidate = Math.floor(Math.random() * 0xffffffff)
+      .toString(16)
+      .padStart(8, '0');
+    if (!existing.has(candidate)) return candidate;
+  }
+  return `${Date.now().toString(16)}${Math.floor(Math.random() * 0xffff).toString(16)}`;
+}
+
+// Slug-suffix dedup: return `base`, else `base-2`, `base-3`, ... -- the first
+// not already in `existing`. Callers pass an already-formed base (a blueprint
+// name's slug for fresh placements, an existing id for clones) so newly created
+// actors read as `cauldron` / `cauldron-2` instead of opaque hex. Falls back to
+// a random hex id in the pathological case (100k straight collisions) so the
+// caller always gets a unique id.
+export function dedupeActorId(existing, base) {
+  const safe = typeof base === 'string' && base.length ? base : 'actor';
+  if (!existing.has(safe)) return safe;
+  for (let attempt = 2; attempt < 100000; attempt += 1) {
+    const candidate = `${safe}-${attempt}`;
+    if (!existing.has(candidate)) return candidate;
+  }
+  return mintActorId(existing);
+}
+
+// Strip a trailing `-<n>` dedup suffix so a clone of `brick-3` bases off
+// `brick` (yielding the next free `brick-N`) instead of nesting `brick-3-2`.
+function stripDupSuffix(id) {
+  return typeof id === 'string' ? id.replace(/-\d+$/, '') : id;
+}
+
+export function screenToCard(canvas, clientX, clientY) {
+  const rect = canvas.getBoundingClientRect();
+  const viewport = readCanvasViewport(canvas);
+  return {
+    x: ((clientX - rect.left) / rect.width) * viewport.width - viewport.originX,
+    y: ((clientY - rect.top) / rect.height) * viewport.height - viewport.originY,
+  };
+}
+
+export function configureSceneCanvas(canvas, ctx = canvas.getContext('2d'), viewport = DEFAULT_VIEWPORT) {
+  if (!ctx) return null;
+  const rect = canvas.getBoundingClientRect();
+  const dpr = window.devicePixelRatio || 1;
+  const displayWidth = rect.width || CARD_WIDTH;
+  const displayHeight = rect.height || CARD_HEIGHT;
+  const pixelWidth = Math.max(1, Math.round(displayWidth * dpr));
+  const pixelHeight = Math.max(1, Math.round(displayHeight * dpr));
+  if (canvas.width !== pixelWidth) canvas.width = pixelWidth;
+  if (canvas.height !== pixelHeight) canvas.height = pixelHeight;
+  canvas.dataset.viewportWidth = String(viewport.width);
+  canvas.dataset.viewportHeight = String(viewport.height);
+  canvas.dataset.viewportOriginX = String(viewport.originX);
+  canvas.dataset.viewportOriginY = String(viewport.originY);
+  ctx.setTransform(pixelWidth / viewport.width, 0, 0, pixelHeight / viewport.height, 0, 0);
+  ctx.imageSmoothingEnabled = true;
+  return ctx;
+}
+
+function readCanvasViewport(canvas) {
+  return {
+    width: Number(canvas.dataset.viewportWidth) || CARD_WIDTH,
+    height: Number(canvas.dataset.viewportHeight) || CARD_HEIGHT,
+    originX: Number(canvas.dataset.viewportOriginX) || 0,
+    originY: Number(canvas.dataset.viewportOriginY) || 0,
+  };
+}
+
+function drawDotGrid(ctx, gridSize = 25, viewport = DEFAULT_VIEWPORT, camera = { x: 0, y: 0 }) {
+  const size = Number.isFinite(gridSize) && gridSize > 0 ? gridSize : 25;
+  const minX = (camera.x ?? 0) - viewport.originX;
+  const minY = (camera.y ?? 0) - viewport.originY;
+  const maxX = minX + viewport.width;
+  const maxY = minY + viewport.height;
+  const startX = Math.floor(minX / size) * size;
+  const startY = Math.floor(minY / size) * size;
+  ctx.save();
+  ctx.fillStyle = 'rgba(255, 255, 255, 0.18)';
+  for (let x = startX; x <= maxX; x += size) {
+    for (let y = startY; y <= maxY; y += size) {
+      ctx.beginPath();
+      ctx.arc(x, y, 1.35, 0, Math.PI * 2);
+      ctx.fill();
+    }
+  }
+  ctx.restore();
+}
+
+// Per-actor edit bounding box visibility: show it only when the actor lacks a
+// real sprite to look at (no Sprite behavior, or a Sprite with no .pxart file).
+// This gray box is purely the "sprite-less actor" indicator -- selection is
+// represented separately by the DOM SelectionOverlay's solid white box, so a
+// Sprite-backed actor never shows this box, selected or not.
+function shouldDrawEditPlaceholder(actor, sprites) {
+  const sprite = actor?.components?.Sprite;
+  if (!sprite || !sprite.file) return true;
+  const resolved = sprites?.[sprite.file];
+  // An unresolved file falls back to Sprite.jsx's own placeholder art, so it's
+  // not invisible -- only draw the editor placeholder when the file resolves
+  // to fully-transparent (empty) art.
+  if (!resolved) return false;
+  return spriteIsEmpty(resolved);
+}
+
+function drawEditPlaceholder(ctx, actor) {
+  const layout = getLayout(actor);
+  if (!layout) return;
+  ctx.save();
+  ctx.fillStyle = 'rgba(255, 255, 255, 0.04)';
+  ctx.fillRect(layout.x, layout.y, layout.width, layout.height);
+  ctx.strokeStyle = 'rgba(255, 255, 255, 0.25)';
+  ctx.lineWidth = 1;
+  ctx.strokeRect(layout.x + 0.5, layout.y + 0.5, layout.width - 1, layout.height - 1);
+  ctx.restore();
+}
+
+function drawMarquee(ctx, rect) {
+  if (rect.width === 0 || rect.height === 0) return;
+  ctx.save();
+  ctx.fillStyle = 'rgba(255, 255, 255, 0.12)';
+  ctx.fillRect(rect.x, rect.y, rect.width, rect.height);
+  ctx.strokeStyle = 'rgba(255, 255, 255, 0.4)';
+  ctx.lineWidth = 1;
+  ctx.setLineDash([4, 3]);
+  ctx.strokeRect(rect.x + 0.5, rect.y + 0.5, rect.width - 1, rect.height - 1);
+  ctx.restore();
+}
+
+function drawCropOutline(ctx) {
+  ctx.save();
+  ctx.strokeStyle = 'rgba(255, 255, 255, 0.4)';
+  ctx.lineWidth = 2;
+  ctx.setLineDash([]);
+  const transform = ctx.getTransform();
+  const dpr = window.devicePixelRatio || 1;
+  const cssRadius = 12;
+  const radius = transform.a ? (cssRadius * dpr) / transform.a : cssRadius;
+  roundedRect(ctx, 1, 1, CARD_WIDTH - 2, CARD_HEIGHT - 2, radius);
+  ctx.stroke();
+  ctx.restore();
+}
+
+function roundedRect(ctx, x, y, width, height, radius) {
+  const r = Math.min(radius, width / 2, height / 2);
+  ctx.beginPath();
+  ctx.moveTo(x + r, y);
+  ctx.lineTo(x + width - r, y);
+  ctx.quadraticCurveTo(x + width, y, x + width, y + r);
+  ctx.lineTo(x + width, y + height - r);
+  ctx.quadraticCurveTo(x + width, y + height, x + width - r, y + height);
+  ctx.lineTo(x + r, y + height);
+  ctx.quadraticCurveTo(x, y + height, x, y + height - r);
+  ctx.lineTo(x, y + r);
+  ctx.quadraticCurveTo(x, y, x + r, y);
+  ctx.closePath();
+}
+
+function drawSelection(ctx, actor) {
+  const layout = getLayout(actor);
+  if (!layout) return;
+  ctx.save();
+  applyLayoutRotation(ctx, layout);
+  ctx.strokeStyle = '#fff';
+  ctx.lineWidth = 2;
+  ctx.setLineDash([6, 4]);
+  ctx.strokeRect(layout.x + 1, layout.y + 1, layout.width - 2, layout.height - 2);
+  ctx.restore();
+}
+
+function applyLayoutRotation(ctx, layout) {
+  const rotation = layout?.rotation ?? 0;
+  if (!rotation || !layout) return;
+  const cx = layout.x + layout.width / 2;
+  const cy = layout.y + layout.height / 2;
+  ctx.translate(cx, cy);
+  ctx.rotate((rotation * Math.PI) / 180);
+  ctx.translate(-cx, -cy);
+}
+
+function getLayout(actor) {
+  return actor?.components?.Layout;
+}