castle-web-cli 0.4.77 → 0.4.79

package/kits/basic-2d/editors/pixelInspector.jsx

@@ -113,6 +113,45 @@ export function CanvasSizeBar({ width, height, onResize }) {
   );
 }
 
+// The 3 corner-radius presets offered by CornerRadiusBar. 0 is sharp/pixel;
+// the other two are "nice" rounded amounts. The file format itself isn't
+// limited to these three (any value up to MAX_CORNER_RADIUS is valid — see
+// pxart.js) — this is just the curated set the editor's segmented control
+// exposes, so hand-picking a value never means hunting a slider.
+const CORNER_RADIUS_STEPS = [
+  { value: 0, label: '0' },
+  { value: 0.25, label: '¼' },
+  { value: 0.5, label: '½' },
+];
+
+// Corner-radius segmented control, meant to sit next to CanvasSizeBar above
+// the artboard. Sets the sprite's file-level `cornerRadius` field (a property
+// of the .pxart asset — see docs/pxart-format.md — not a per-actor Sprite
+// prop). `radius` is a plain number (0 = sharp/pixel corners); highlights
+// whichever preset it exactly matches, or none if it's a value from outside
+// this set (e.g. hand-edited JSON).
+export function CornerRadiusBar({ radius, onChange }) {
+  return (
+    <div className={styles.cornerRadiusBar} aria-label="Corner rounding">
+      <span>Round</span>
+      <div className={styles.cornerRadiusSegments} role="radiogroup" aria-label="Corner radius">
+        {CORNER_RADIUS_STEPS.map((step) => (
+          <button
+            key={step.value}
+            type="button"
+            role="radio"
+            aria-checked={radius === step.value ? 'true' : 'false'}
+            className={cx(styles.cornerRadiusSegment, radius === step.value && styles.cornerRadiusSegmentOn)}
+            title={step.value === 0 ? 'Sharp (pixel) corners' : `Round corners, radius ${step.value}`}
+            onClick={() => onChange(step.value)}>
+            {step.label}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
+
 function ResolutionSelect({ label, value, onChange }) {
   const options = RESOLUTION_STEPS.includes(value)
     ? RESOLUTION_STEPS

package/kits/basic-2d/editors/pxArtEditorModel.js

@@ -1,4 +1,5 @@
 import {
+  clampCornerRadius,
   colorForKeyV2,
   DEFAULT_DURATION_MS,
   DEFAULT_RESOLUTION,
@@ -77,10 +78,19 @@ function blankSprite() {
     defaultDurationMs: DEFAULT_DURATION_MS,
     tags: [],
     defaultTag: undefined,
+    cornerRadius: 0,
     layers: [makeLayer('layer-0', 'Layer 1', [null])],
   };
 }
 
+// Set the file-level corner-rounding radius (0 = sharp/pixel). A no-op if
+// it's already that value (keeps identical sprites from producing spurious
+// history entries).
+export function setCornerRadius(sprite, radius) {
+  const clamped = clampCornerRadius(radius);
+  return sprite.cornerRadius === clamped ? sprite : { ...sprite, cornerRadius: clamped };
+}
+
 function makeLayer(id, name, cells) {
   return { id, name, visible: true, opacity: 1, blendMode: 'normal', kind: 'pixel', cells };
 }
@@ -635,7 +645,10 @@ function shiftCellOffset(cell, dx, dy) {
 // later needs no change here: if it survives the round-trip it was already
 // representable; if not, it correctly forces the full form.
 export function serializeModel(sprite) {
-  const compact = serializeCompact(fromCells(EDITOR_PALETTE, cellsAt(sprite, 0, 0)));
+  const compact = serializeCompact({
+    ...fromCells(EDITOR_PALETTE, cellsAt(sprite, 0, 0)),
+    cornerRadius: sprite.cornerRadius,
+  });
   const roundTripped = parseFull(compact);
   if (roundTripped && losslesslyCompact(sprite, roundTripped)) return compact;
   return serializeFull(sprite);
@@ -659,6 +672,7 @@ function losslesslyCompact(sprite, roundTripped) {
   if (frameCount(sprite) !== frameCount(roundTripped)) return false;
   if (sprite.tags.length !== roundTripped.tags.length) return false;
   if ((sprite.defaultTag ?? null) !== (roundTripped.defaultTag ?? null)) return false;
+  if (sprite.cornerRadius !== roundTripped.cornerRadius) return false;
   if (sprite.layers.length !== roundTripped.layers.length) return false;
 
   const lookupA = paletteLookup(sprite.palette);

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

@@ -6,7 +6,7 @@ import { SceneUI } from './SceneUI';
 // behavior-driven UI overlay. No game logic lives here -- behaviors and
 // scenes are the place for that. The dev logs drawer is a builtin shell panel
 // now (cli/src/shell), not rendered here.
-export function ScenePlayer({ sceneData, sprites, behaviorClasses, onFirstFrame }) {
+export function ScenePlayer({ sceneData, sprites, files, behaviorClasses, onFirstFrame }) {
   const canvasRef = useRef(null);
   const runtimeRef = useRef(null);
   const getRuntime = useCallback(() => runtimeRef.current, []);
@@ -16,7 +16,7 @@ export function ScenePlayer({ sceneData, sprites, behaviorClasses, onFirstFrame
     const ctx = canvas.getContext('2d');
     if (!ctx) return undefined;
     configureSceneCanvas(canvas, ctx);
-    const runtime = makeScene(sceneData, behaviorClasses, sprites).clone();
+    const runtime = makeScene(sceneData, behaviorClasses, sprites, files).clone();
     runtimeRef.current = runtime;
     // Store BOTH the physical code ('KeyX', 'ArrowLeft', 'Space') and the
     // logical key ('x', 'ArrowLeft', ' ') so behaviors can match either. Codes

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

@@ -0,0 +1,423 @@
+// Blueprint system: every actor in a scene is an instance of a blueprint (a
+// `.scene` file under `blueprints/` whose `actors[0]` is the template, with no
+// `id`). An instance stores only sparse per-property overrides in its own
+// `components`; blueprint template values are the base, merged live from the
+// current `files` map (never a load-time snapshot) so a blueprint edit in one
+// panel propagates to every scene that places it. Shared by the runtime
+// (`scene.js`, so play mode and `PlayOnly` resolve blueprints too) and the
+// editors (which also mint/fork/migrate/cascade-delete blueprint files).
+import { formatJson } from './files';
+import { DEFAULT_RESOLUTION, TRANSPARENT, serializeCompact } from './pxart';
+import { cardSize, mintActorId } from './scene';
+
+export const BLUEPRINTS_DIR = 'blueprints';
+export const DRAWINGS_DIR = 'drawings';
+
+export function isBlueprintPath(path) {
+  return typeof path === 'string' && path.startsWith(`${BLUEPRINTS_DIR}/`) && path.endsWith('.scene');
+}
+
+// Per-property inherit metadata for a behavior prop. Behaviors opt a prop out
+// of inheritance via `static propertyMeta = { propName: { inherit: false } }`
+// (see behaviors/Layout.jsx for x/y/rotation); anything absent defaults to
+// inherited. A non-inherited prop is always written as an instance value at
+// placement time -- the blueprint's value for it is only a default for newly
+// placed instances, and future blueprint edits never move an existing
+// instance's copy of that prop.
+export function getPropertyMeta(Behavior, prop) {
+  return Behavior?.propertyMeta?.[prop] ?? { inherit: true };
+}
+
+export function isInheritedProp(Behavior, prop) {
+  return getPropertyMeta(Behavior, prop).inherit !== false;
+}
+
+// Parse a blueprint file's text into { name, components } (the template
+// actor's components), or null if the text isn't a valid blueprint (used to
+// treat a tombstoned/deleted blueprint file as absent).
+function parseBlueprintText(text) {
+  if (typeof text !== 'string') return null;
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  const actor = data?.actors?.[0];
+  if (!actor || typeof actor !== 'object' || !actor.components) return null;
+  const name = typeof data.name === 'string' && data.name.trim() ? data.name : 'Blueprint';
+  return { name, components: actor.components };
+}
+
+// Resolve a blueprint's template from the LIVE files map -- the load-bearing
+// call for live propagation. Returns null when the file is missing, deleted,
+// or malformed (a dangling `blueprint` ref degrades to "no template" rather
+// than throwing).
+export function getBlueprintTemplate(files, blueprintPath) {
+  return parseBlueprintText(files?.[blueprintPath]);
+}
+
+// Every blueprint currently in the deck, for the library/hotbar. Skips
+// unparseable / tombstoned files (see `cascadeDeleteBlueprint`).
+export function listBlueprints(files) {
+  const out = [];
+  for (const path of Object.keys(files ?? {})) {
+    if (!isBlueprintPath(path)) continue;
+    const template = parseBlueprintText(files[path]);
+    if (!template) continue;
+    out.push({ path, name: template.name, components: template.components });
+  }
+  out.sort((a, b) => a.path.localeCompare(b.path));
+  return out;
+}
+
+// Per-property merge: the blueprint template is the base, instance overrides
+// win per-property within each component (not whole-component replacement). A
+// component present on only one side appears whole.
+export function mergeComponents(templateComponents, instanceComponents) {
+  const merged = {};
+  const names = new Set([
+    ...Object.keys(templateComponents ?? {}),
+    ...Object.keys(instanceComponents ?? {}),
+  ]);
+  for (const name of names) {
+    const templateProps = templateComponents?.[name];
+    const instanceProps = instanceComponents?.[name];
+    if (templateProps === undefined) merged[name] = { ...instanceProps };
+    else if (instanceProps === undefined) merged[name] = { ...templateProps };
+    else merged[name] = { ...templateProps, ...instanceProps };
+  }
+  return merged;
+}
+
+// The fully resolved components for one actor: its blueprint's template
+// merged with its own sparse overrides, or its raw components when it carries
+// no `blueprint` ref (the blueprint's own template actor, or a not-yet
+// migrated legacy actor).
+export function resolveActorComponents(files, actor) {
+  if (!actor?.blueprint) return actor?.components ?? {};
+  const template = getBlueprintTemplate(files, actor.blueprint);
+  return mergeComponents(template?.components, actor.components);
+}
+
+function countMatches(text, regex) {
+  let max = 0;
+  const re = new RegExp(regex);
+  const m = re.exec(text ?? '');
+  return m ? Number(m[1]) : max;
+}
+
+// "Blueprint N" -- N is one more than the highest existing "Blueprint <n>"
+// name (not just existing.length + 1, so a gap left by a deleted blueprint
+// doesn't get reused and collide with intent elsewhere).
+function mintBlueprintName(existingNames) {
+  let max = 0;
+  for (const name of existingNames) max = Math.max(max, countMatches(name, /^Blueprint (\d+)$/));
+  return `Blueprint ${max + 1}`;
+}
+
+// `blueprints/blueprint-N.scene` -- the filename is a stable slug minted once
+// at creation; nothing ever renames it afterward (renaming edits only `name`).
+function mintBlueprintPath(existingPaths) {
+  let max = 0;
+  for (const path of existingPaths) {
+    max = Math.max(max, countMatches(path, new RegExp(`^${BLUEPRINTS_DIR}/blueprint-(\\d+)\\.scene$`)));
+  }
+  return `${BLUEPRINTS_DIR}/blueprint-${max + 1}.scene`;
+}
+
+export function formatBlueprintFileText(name, components) {
+  return formatJson({ name, actors: [{ components }] });
+}
+
+// Rename a blueprint: replace its top-level `name`, preserving actors and any
+// hand-added extras. Returns the next file text, or null when the file is
+// missing/unparseable (caller should treat that as "blueprint gone" and skip
+// the write). Empty/whitespace names are stored as-is; readers fall back to
+// "Blueprint" for display (see getBlueprintTemplate).
+export function setBlueprintName(files, blueprintPath, name) {
+  let data;
+  try {
+    data = JSON.parse(files?.[blueprintPath] ?? '');
+  } catch {
+    return null;
+  }
+  if (!data || typeof data !== 'object') return null;
+  data.name = name;
+  return formatJson(data);
+}
+
+// Replace a blueprint file's template components, preserving every other
+// top-level field (name, hand-added extras). Returns the next file text, or
+// null when the file is missing/unparseable/tombstoned (caller should treat
+// that as "blueprint gone" and skip the write).
+export function setBlueprintTemplateComponents(files, blueprintPath, components) {
+  let data;
+  try {
+    data = JSON.parse(files?.[blueprintPath] ?? '');
+  } catch {
+    return null;
+  }
+  if (!data?.actors?.[0]) return null;
+  data.actors[0].components = components;
+  return formatJson(data);
+}
+
+// Mint a brand new blueprint file descriptor ({ path, name, text }) for the
+// given template components. Does not write the file -- callers write it
+// (via the SDK's `writeFile`) and, for the current scene, place an instance
+// referencing `path`.
+export function mintBlueprintFile(files, components) {
+  const existing = listBlueprints(files);
+  const name = mintBlueprintName(existing.map((blueprint) => blueprint.name));
+  const path = mintBlueprintPath(existing.map((blueprint) => blueprint.path));
+  return { path, name, text: formatBlueprintFileText(name, components) };
+}
+
+// Split a resolved component's props into { inherited, overridden } by each
+// prop's propertyMeta. Used by migration and fork to decide what belongs in a
+// new blueprint template vs. what must stay an explicit instance value.
+function splitByInherit(Behavior, props) {
+  const inherited = {};
+  const overridden = {};
+  for (const [prop, value] of Object.entries(props ?? {})) {
+    if (isInheritedProp(Behavior, prop)) inherited[prop] = value;
+    else overridden[prop] = value;
+  }
+  return { inherited, overridden };
+}
+
+function findBehavior(behaviors, name) {
+  return behaviors.find((candidate) => candidate.behaviorName === name);
+}
+
+// Apply an inspector-style partial patch (`{ propName: value, ... }`) to one
+// actor's component, IN PLACE. For a blueprint's own template actor (no
+// `blueprint` ref) this is a plain merge -- there's no baseline to diff
+// against. For an instance, each patched prop is diffed against the
+// blueprint's current value (falling back to the behavior's defaultProps):
+// an inherited prop that becomes equal to the blueprint again drops its
+// override (so it goes back to tracking blueprint edits); anything else is
+// recorded as an override. Never writes a full component copy.
+export function applyComponentPatch(files, behaviors, actor, behaviorName, nextProps) {
+  actor.components ??= {};
+  if (!actor.blueprint) {
+    actor.components[behaviorName] = { ...(actor.components[behaviorName] ?? {}), ...nextProps };
+    return;
+  }
+  const template = getBlueprintTemplate(files, actor.blueprint);
+  const templateProps = template?.components?.[behaviorName] ?? {};
+  const Behavior = findBehavior(behaviors, behaviorName);
+  const defaultProps = Behavior?.defaultProps ?? {};
+  const overrides = { ...(actor.components[behaviorName] ?? {}) };
+  for (const [prop, value] of Object.entries(nextProps)) {
+    const baseline = prop in templateProps ? templateProps[prop] : defaultProps[prop];
+    if (isInheritedProp(Behavior, prop) && Object.is(value, baseline)) delete overrides[prop];
+    else overrides[prop] = value;
+  }
+  if (Object.keys(overrides).length === 0) delete actor.components[behaviorName];
+  else actor.components[behaviorName] = overrides;
+}
+
+// Single-actor convenience wrapper around `applyComponentPatch` for the
+// inspector: clones the scene, patches the one actor's component, returns the
+// next scene (or the original when the actor is missing).
+export function setInstanceComponent(files, behaviors, sceneData, actorId, behaviorName, nextProps) {
+  const next = structuredClone(sceneData);
+  const actor = next.actors?.find((candidate) => candidate.id === actorId);
+  if (!actor) return sceneData;
+  applyComponentPatch(files, behaviors, actor, behaviorName, nextProps);
+  return next;
+}
+
+function snapValue(value, snap) {
+  if (!snap?.enabled) return Math.round(value);
+  return Math.round(value / snap.gridSize) * snap.gridSize;
+}
+
+// "Add actor" = mint a new blueprint AND place its first instance in one
+// gesture. Returns the next scene, the new instance id, and the new
+// blueprint's { path, name, text } for the caller to write to disk.
+// A blank 16x16 (DEFAULT_RESOLUTION) compact `.pxart`: all-transparent grid,
+// empty palette. This is what a brand-new blueprint's sprite points at, so the
+// "add actor" button always yields a fresh empty canvas to draw into rather
+// than reusing whatever art happened to be first in drawings/.
+export function blankPxArtText() {
+  const { width, height } = DEFAULT_RESOLUTION;
+  const grid = Array.from({ length: height }, () => TRANSPARENT.repeat(width));
+  return serializeCompact({ palette: {}, grid });
+}
+
+// `drawings/drawing-N.pxart` -- 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$`);
+  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`;
+}
+
+export function addActorWithBlueprint(sceneData, files) {
+  const width = 64;
+  const height = 64;
+  const drawingFile = { path: mintDrawingPath(files), text: blankPxArtText() };
+  const components = {
+    Layout: { width, height, z: 0 },
+    Sprite: { file: drawingFile.path },
+  };
+  const blueprintFile = mintBlueprintFile(files, components);
+  const next = structuredClone(sceneData);
+  const existingIds = new Set(next.actors.map((actor) => actor.id));
+  const newId = mintActorId(existingIds);
+  const x = Math.round((cardSize.width - width) / 2);
+  const y = Math.round((cardSize.height - height) / 2);
+  next.actors.push({ id: newId, blueprint: blueprintFile.path, components: { Layout: { x, y } } });
+  return { sceneData: next, newId, blueprintFile, drawingFile };
+}
+
+// Centered, grid-snapped Layout x/y for a blueprint's template at a
+// card-space point. Shared by initial drag-in placement and the subsequent
+// moves while the drag is still in progress, so both snap identically.
+export function blueprintDropXY(files, blueprintPath, position, snap) {
+  const template = getBlueprintTemplate(files, blueprintPath);
+  const layout = template?.components?.Layout ?? {};
+  const width = layout.width ?? 64;
+  const height = layout.height ?? 64;
+  const dropX = position?.x ?? cardSize.width / 2;
+  const dropY = position?.y ?? cardSize.height / 2;
+  return {
+    x: snapValue(dropX - width / 2, snap),
+    y: snapValue(dropY - height / 2, snap),
+  };
+}
+
+// Place a new instance of an existing blueprint at a drop point (card units,
+// pre-snap), grid-snapped and centered on the point using the template's
+// Layout size. Only Layout x/y are written on the instance -- everything else
+// inherits from the blueprint.
+export function placeBlueprintInstance(sceneData, files, blueprintPath, position, snap) {
+  const next = structuredClone(sceneData);
+  const existingIds = new Set(next.actors.map((actor) => actor.id));
+  const newId = mintActorId(existingIds);
+  const { x, y } = blueprintDropXY(files, blueprintPath, position, snap);
+  next.actors.push({ id: newId, blueprint: blueprintPath, components: { Layout: { x, y } } });
+  return { sceneData: next, newId };
+}
+
+// "New blueprint from this actor": mint a blueprint whose template is the
+// instance's fully merged components, with non-inherited props reset to their
+// behavior defaults in the TEMPLATE (a fresh blueprint has no instances yet to
+// carry position, so its own template position is a neutral default).
+// Reparent the instance to the new blueprint, keeping only its non-inherited
+// prop values (Layout position et al) as instance overrides -- everything
+// else now matches the new template exactly, so no override is needed for it.
+export function forkActorToBlueprint(files, behaviors, sceneData, actorId) {
+  const next = structuredClone(sceneData);
+  const actor = next.actors?.find((candidate) => candidate.id === actorId);
+  if (!actor) return null;
+  const merged = resolveActorComponents(files, actor);
+  const templateComponents = {};
+  const instanceOverrides = {};
+  for (const [behaviorName, props] of Object.entries(merged)) {
+    if (!props) continue;
+    const Behavior = findBehavior(behaviors, behaviorName);
+    const { inherited, overridden } = splitByInherit(Behavior, props);
+    if (Object.keys(overridden).length > 0) instanceOverrides[behaviorName] = overridden;
+    // The new template's non-inherited props reset to the behavior's default
+    // (a fresh blueprint has no instances yet to carry a real position); its
+    // inherited props keep the actor's current (merged) values verbatim.
+    const defaultProps = Behavior?.defaultProps ?? {};
+    const resetOverridden = Object.fromEntries(
+      Object.keys(overridden).map((prop) => [prop, prop in defaultProps ? defaultProps[prop] : overridden[prop]])
+    );
+    if (Object.keys(inherited).length > 0 || Object.keys(resetOverridden).length > 0) {
+      templateComponents[behaviorName] = { ...inherited, ...resetOverridden };
+    }
+  }
+  const blueprintFile = mintBlueprintFile(files, templateComponents);
+  actor.blueprint = blueprintFile.path;
+  actor.components = instanceOverrides;
+  return { sceneData: next, blueprintFile };
+}
+
+// Every `scenes/*.scene` file's parsed data, for callers that need to scan
+// every scene in the deck (cascade delete, the instance-count badge/confirm).
+// Skips unparseable files rather than throwing -- a mid-edit scene with
+// invalid JSON just doesn't count towards these scans.
+function parseSceneFiles(files) {
+  const out = [];
+  for (const [path, text] of Object.entries(files ?? {})) {
+    if (!path.startsWith('scenes/') || !path.endsWith('.scene')) continue;
+    try {
+      out.push({ path, data: JSON.parse(text) });
+    } catch {
+      // skip
+    }
+  }
+  return out;
+}
+
+// Every `scenes/*.scene` file's actor count referencing a blueprint, for the
+// delete-confirm dialog and the library's per-blueprint badge.
+export function countBlueprintInstances(files, blueprintPath) {
+  let count = 0;
+  for (const { data } of parseSceneFiles(files)) {
+    for (const actor of data?.actors ?? []) {
+      if (actor?.blueprint === blueprintPath) count += 1;
+    }
+  }
+  return count;
+}
+
+// Cascade-delete a blueprint: every instance in every scene is removed, and
+// the blueprint file itself is tombstoned (overwritten with an empty scene --
+// `listBlueprints` skips it and it stops resolving). Returns the list of
+// { path, text } writes for the caller to apply (the currently open scene
+// should go through that editor's own history/onChange so undo still works
+// for it; every other file is a direct `writeFile`).
+export function cascadeDeleteBlueprint(files, blueprintPath) {
+  const writes = [];
+  for (const { path, data } of parseSceneFiles(files)) {
+    const actors = data.actors ?? [];
+    const filtered = actors.filter((actor) => actor?.blueprint !== blueprintPath);
+    if (filtered.length !== actors.length) {
+      writes.push({ path, text: formatJson({ ...data, actors: filtered }) });
+    }
+  }
+  writes.push({ path: blueprintPath, text: formatJson({}) });
+  return writes;
+}
+
+// Auto-migrate a scene's orphan actors (no `blueprint` field -- the pre-v1
+// shape) into blueprint instances: mint one blueprint per orphan (its
+// authored components split by propertyMeta, same as fork), rewrite the actor
+// to reference it with only the non-inherited props as overrides. Mechanical
+// and safe: never touches an actor that already has a `blueprint`.
+export function migrateOrphanActors(files, behaviors, sceneData) {
+  const next = structuredClone(sceneData);
+  const newBlueprintFiles = [];
+  let knownBlueprints = listBlueprints(files);
+  for (const actor of next.actors ?? []) {
+    if (actor.blueprint) continue;
+    const templateComponents = {};
+    const instanceOverrides = {};
+    for (const [behaviorName, props] of Object.entries(actor.components ?? {})) {
+      if (!props) continue;
+      const Behavior = findBehavior(behaviors, behaviorName);
+      const { inherited, overridden } = splitByInherit(Behavior, props);
+      if (Object.keys(inherited).length > 0) templateComponents[behaviorName] = inherited;
+      if (Object.keys(overridden).length > 0) instanceOverrides[behaviorName] = overridden;
+    }
+    const name = mintBlueprintName(knownBlueprints.map((blueprint) => blueprint.name));
+    const path = mintBlueprintPath(knownBlueprints.map((blueprint) => blueprint.path));
+    const text = formatBlueprintFileText(name, templateComponents);
+    newBlueprintFiles.push({ path, text });
+    knownBlueprints = [...knownBlueprints, { path, name, components: templateComponents }];
+    actor.blueprint = path;
+    actor.components = instanceOverrides;
+  }
+  return { sceneData: next, newBlueprintFiles };
+}

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

@@ -1,7 +1,7 @@
 // Seed the file map by scanning the deck dir. Vite module-cache is invalidated
 // on restart, so a newly-created file just shows up on the next reload.
 const rawModules = import.meta.glob(
-  ['../scenes/*.scene', '../drawings/*.pxart', '../behaviors/*.jsx'],
+  ['../scenes/*.scene', '../blueprints/*.scene', '../drawings/*.pxart', '../behaviors/*.jsx'],
   { query: '?raw', import: 'default', eager: true }
 );
 export const initialFiles = Object.fromEntries(

package/kits/basic-2d/engine/pxart.js

@@ -40,6 +40,46 @@ export const COMPACT_FORM = 'compact';
 export const FULL_FORM = 'full';
 export const TRANSPARENT = '.';
 
+// ---------------------------------------------------------------------------
+// cornerRadius (file-level corner-rounding radius, in native-pixel units)
+// ---------------------------------------------------------------------------
+//
+// `cornerRadius` is a plain number: 0 renders sharp/nearest-neighbor (the
+// historical/default look, 1px/cell); anything > 0 is a corner-rounding
+// radius passed straight through to `pxartSmooth.js`'s local corner kernel.
+// A VALUE rather than a "pixel" | "smooth" flag, so the amount of rounding is
+// itself part of the portable file format instead of a fixed, code-side
+// constant every smooth sprite is stuck with.
+
+/** Corner cuts on the same 1-native-pixel edge must not overlap, so radii
+ *  above this are clamped on parse (and by the editor's UI). */
+export const MAX_CORNER_RADIUS = 0.5;
+
+export function clampCornerRadius(radius) {
+  return Math.min(MAX_CORNER_RADIUS, Math.max(0, radius));
+}
+
+// This field used to be called `render`: first a "pixel" | "smooth" string
+// enum, then (briefly) a bare numeric radius under that same key. Both
+// migrate on read so files from either era keep rendering rounded rather
+// than silently reverting to sharp; "smooth" specifically migrates to this
+// fixed value, since the string enum never carried an amount of its own.
+const LEGACY_SMOOTH_RADIUS = 0.25;
+
+/** Read the corner radius off a parsed JSON object, preferring the current
+ *  `cornerRadius` key and falling back to the legacy `render` key (see
+ *  above). Defaults to 0 (sharp) for anything else (missing field, typo, a
+ *  future value this parser doesn't know yet). */
+function parseCornerRadius(data) {
+  if (typeof data.cornerRadius === 'number' && Number.isFinite(data.cornerRadius)) {
+    return clampCornerRadius(data.cornerRadius);
+  }
+  const legacy = data.render;
+  if (typeof legacy === 'number' && Number.isFinite(legacy)) return clampCornerRadius(legacy);
+  if (legacy === 'smooth') return LEGACY_SMOOTH_RADIUS;
+  return 0;
+}
+
 /** Parse a .pxart string into a compact PxArt record, or null if it isn't the
  *  compact shape. Detects by STRUCTURE (object `palette` + `grid`); the on-disk
  *  `format` discriminator is optional. Tolerant of ragged rows and a `"."`
@@ -61,7 +101,7 @@ export function parseCompact(content) {
         if (typeof v === 'string') palette[k] = v;
         else if (v === null) palette[k] = null;
       }
-      return { palette, grid: data.grid };
+      return { palette, grid: data.grid, cornerRadius: parseCornerRadius(data) };
     }
   } catch {
     /* not valid pxart json */
@@ -70,12 +110,14 @@ export function parseCompact(content) {
 }
 
 /** Serialize a compact PxArt record to a .pxart string. Always stamps
- *  `format: "compact"`. */
+ *  `format: "compact"`. `cornerRadius` is omitted when it's 0 (sharp), so
+ *  existing (pixel) files stay byte-identical. */
 export function serializeCompact(art) {
   const out = {
     format: COMPACT_FORM,
     palette: art.palette,
     grid: art.grid,
+    ...(art.cornerRadius > 0 ? { cornerRadius: art.cornerRadius } : {}),
   };
   return JSON.stringify(out, null, 2) + '\n';
 }
@@ -548,6 +590,7 @@ export function parseFull(content) {
     defaultDurationMs,
     tags,
     defaultTag,
+    cornerRadius: parseCornerRadius(data),
     layers,
   };
 }
@@ -581,6 +624,7 @@ export function upgradeCompactToFull(art) {
     defaultDurationMs: DEFAULT_DURATION_MS,
     tags: [],
     defaultTag: undefined,
+    cornerRadius: art.cornerRadius,
     layers: [
       {
         id: 'layer-0',
@@ -641,6 +685,9 @@ export function serializeFull(sprite) {
       repeat: t.repeat,
     })),
     ...(sprite.defaultTag !== undefined ? { defaultTag: sprite.defaultTag } : {}),
+    // Omitted when it's 0 (sharp), so pixel-mode files stay byte-identical to
+    // their pre-smoothing shape.
+    ...(sprite.cornerRadius > 0 ? { cornerRadius: sprite.cornerRadius } : {}),
     layers: sprite.layers.map((l) => ({
       id: l.id,
       name: l.name,