castle-web-cli 0.4.115 → 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/assets.js

@@ -14,7 +14,7 @@ export function collectAssets(files) {
     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/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/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 }
   ),
 };
@@ -99,6 +100,7 @@ export function mediaFilesOfKind(kind) {
 // `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';

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/physics/jointArt.js

@@ -7,9 +7,9 @@
 // a small WeakMap caches the native-resolution frame canvas per sprite object.
 
 import { resolveDeckFile } from 'castle-web-sdk';
-import { renderSpriteFrame } from '../pxart';
+import { displayFinish, renderSpriteFrame } from '../pxart';
 
-export const DEFAULT_JOINT_SPRITE = 'drawings/joint-rope.pxart';
+export const DEFAULT_JOINT_SPRITE = 'drawings/joint-rope.sprite';
 
 const canvasCache = new WeakMap();
 function frameCanvas(sprite) {
@@ -40,7 +40,7 @@ export function drawJointArt(ctx, scene, joint, a, b) {
   ctx.save();
   ctx.translate(a.x, a.y);
   ctx.rotate(Math.atan2(dy, dx));
-  ctx.imageSmoothingEnabled = sprite.cornerRadius > 0;
+  ctx.imageSmoothingEnabled = displayFinish(sprite).smooth;
   const top = -thickness / 2;
   if ((joint.fit ?? 'tile') === 'stretch') {
     ctx.drawImage(canvas, 0, top, len, thickness);

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

@@ -1,3 +1,11 @@
+import {
+  isEmptyPathData,
+  parsePathData,
+  serializePathData,
+  translatePathData,
+  bakePathCell,
+} from './pxartPath.js';
+
 // ============================================================================
 // Castle pixel-art format — COMPACT form ("flat" sprite)
 // ============================================================================
@@ -41,45 +49,104 @@ export const FULL_FORM = 'full';
 export const TRANSPARENT = '.';
 
 // ---------------------------------------------------------------------------
-// cornerRadius (file-level corner-rounding radius, in native-pixel units)
+// Finish: `renderer` (which renderer) + `cornerRadius` (how much rounding)
 // ---------------------------------------------------------------------------
 //
-// `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.
+// Two orthogonal file-level fields:
+//
+//   renderer      "grid" (default) draws the baked `grid`; "vector" draws each
+//                 path layer analytically from its shape stack and each pixel
+//                 layer with the corner kernel at MAX_CORNER_RADIUS.
+//   cornerRadius  ALWAYS a number, in native-pixel units, clamped to
+//                 [0, MAX_CORNER_RADIUS]. 0 renders sharp/nearest-neighbor.
+//
+// These were briefly one field: `cornerRadius` held either a number or the
+// string "smooth". That union is retired because a categorical mode and a
+// continuous amount do not share a slot cleanly — `'smooth' > 0` is false (NaN
+// comparison), so every `cornerRadius > 0` test in the codebase silently read a
+// smooth sprite as sharp unless it special-cased the string, and
+// clampCornerRadius had to return a string to stay lossless. Splitting them
+// restores the invariant that cornerRadius is a number EVERYWHERE, which is what
+// makes "a value, not a flag" actually hold: the amount of rounding stays part
+// of the portable format instead of a fixed, code-side constant.
 
 /** 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 const GRID_RENDERER = 'grid';
+export const VECTOR_RENDERER = 'vector';
+
+/** True when the sprite draws from vector geometry rather than the baked grid. */
+export function isVectorRenderer(renderer) {
+  return renderer === VECTOR_RENDERER;
+}
+
+/** Always returns a number in [0, MAX_CORNER_RADIUS]; any non-number is 0. */
 export function clampCornerRadius(radius) {
+  if (typeof radius !== 'number' || !Number.isFinite(radius)) return 0;
   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.
+/**
+ * How a sprite wants to be shown, for callers that draw it.
+ *
+ * `smooth` is the one every display site needs: it says the supersampled
+ * render is in charge, so the native 1px/cell blit must stay out of the way.
+ * Testing `cornerRadius` alone is NOT enough — the vector renderer carries a
+ * radius of 0, so a `cornerRadius === 0` test reads a Smooth sprite as Pixel
+ * and paints the blocky bake over the analytic render.
+ *
+ * `cornerRadius` is the radius to actually draw with: pixel layers still go
+ * through the corner kernel under the vector renderer, at maximum rounding
+ * (see renderSmoothCompositeFrame), so this is not always the sprite's field.
+ */
+export function displayFinish(sprite) {
+  const vector = isVectorRenderer(sprite?.renderer);
+  const cornerRadius = vector ? MAX_CORNER_RADIUS : clampCornerRadius(sprite?.cornerRadius);
+  return { vector, cornerRadius, smooth: vector || cornerRadius > 0 };
+}
+
+// Legacy encodings, all migrating on read. None of these are structural signals,
+// so compact-vs-full detection is unaffected.
+//
+//   cornerRadius: "smooth"    the retired union   -> vector renderer, radius 0
+//   render: "smooth"          the oldest enum     -> grid renderer, radius 0.25
+//   render: <number>          a brief numeric era -> grid renderer, that radius
+//
+// Old files therefore keep rendering rounded rather than silently reverting to
+// sharp, and a file written before the split still selects the vector renderer.
+// The enum never carried an amount of its own, hence the fixed value here.
 const LEGACY_SMOOTH_RADIUS = 0.25;
+const LEGACY_SMOOTH = 'smooth';
+
+/** Read `renderer` off a parsed JSON object. Anything unrecognized — missing,
+ *  null, a typo, a future value — reads as the grid renderer. */
+function parseRenderer(data) {
+  if (data.renderer === VECTOR_RENDERER) return VECTOR_RENDERER;
+  if (data.renderer === GRID_RENDERER) return GRID_RENDERER;
+  // Pre-split files spelled the vector renderer as cornerRadius: "smooth".
+  if (data.cornerRadius === LEGACY_SMOOTH) return VECTOR_RENDERER;
+  return GRID_RENDERER;
+}
 
-/** 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). */
+/** Read `cornerRadius` off a parsed JSON object. Never yields a non-number, so
+ *  downstream `cornerRadius > 0` tests are always meaningful. */
 function parseCornerRadius(data) {
-  if (typeof data.cornerRadius === 'number' && Number.isFinite(data.cornerRadius)) {
-    return clampCornerRadius(data.cornerRadius);
-  }
+  if (typeof data.cornerRadius === 'number') return clampCornerRadius(data.cornerRadius);
+  // cornerRadius: "smooth" carried no amount — it becomes renderer: "vector".
+  if (data.cornerRadius === LEGACY_SMOOTH) return 0;
   const legacy = data.render;
-  if (typeof legacy === 'number' && Number.isFinite(legacy)) return clampCornerRadius(legacy);
-  if (legacy === 'smooth') return LEGACY_SMOOTH_RADIUS;
+  if (typeof legacy === 'number') return clampCornerRadius(legacy);
+  if (legacy === LEGACY_SMOOTH) return LEGACY_SMOOTH_RADIUS;
   return 0;
 }
 
+/** The finish fields for a parsed sprite, both always well-typed. */
+function parseFinish(data) {
+  return { renderer: parseRenderer(data), cornerRadius: parseCornerRadius(data) };
+}
+
 /** 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 `"."`
@@ -101,7 +168,7 @@ export function parseCompact(content) {
         if (typeof v === 'string') palette[k] = v;
         else if (v === null) palette[k] = null;
       }
-      return { palette, grid: data.grid, cornerRadius: parseCornerRadius(data) };
+      return { palette, grid: data.grid, ...parseFinish(data) };
     }
   } catch {
     /* not valid pxart json */
@@ -109,15 +176,26 @@ export function parseCompact(content) {
   return null;
 }
 
+/** Finish fields for serialization: each omitted at its default, so a plain
+ *  pixel sprite carries neither and stays byte-identical to its pre-finish
+ *  shape. */
+function finishFields(art) {
+  const radius = clampCornerRadius(art?.cornerRadius);
+  return {
+    ...(isVectorRenderer(art?.renderer) ? { renderer: VECTOR_RENDERER } : {}),
+    ...(radius > 0 ? { cornerRadius: radius } : {}),
+  };
+}
+
 /** Serialize a compact PxArt record to a .pxart string. Always stamps
- *  `format: "compact"`. `cornerRadius` is omitted when it's 0 (sharp), so
+ *  `format: "compact"`. Finish fields are omitted at their defaults, 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 } : {}),
+    ...finishFields(art),
   };
   return JSON.stringify(out, null, 2) + '\n';
 }
@@ -416,7 +494,20 @@ function parseCell(raw) {
   if (raw == null) return null;
   if (isPlainObject(raw)) {
     if (Array.isArray(raw.grid) && raw.grid.every((r) => typeof r === 'string')) {
-      return makeGridCell(raw.grid, raw.x, raw.y);
+      const cell = makeGridCell(raw.grid, raw.x, raw.y);
+      const path = parsePathData(raw.path);
+      if (isEmptyPathData(path)) return cell;
+      // Cel offset is a pixel-cell mechanism: a path cell's placement lives in
+      // its points, so x/y must be 0 (§6.1.1). A file that carries both is
+      // normalized by folding the offset into the source, which keeps the art
+      // where it was rather than snapping it to the origin.
+      const { x = 0, y = 0 } = cell;
+      if (!x && !y) return { ...cell, path };
+      return {
+        grid: cell.grid,
+        path: translatePathData(path, x, y),
+        _pathNeedsRebake: true,
+      };
     }
     if (typeof raw.link === 'number' && Number.isInteger(raw.link)) {
       return { link: raw.link };
@@ -517,7 +608,7 @@ export function parseFull(content) {
           ? Math.min(1, Math.max(0, l.opacity))
           : 1,
       blendMode: 'normal',
-      kind: 'pixel',
+      kind: l.kind === 'path' ? 'path' : 'pixel',
       cells: rawCells.map(parseCell),
     };
   });
@@ -571,6 +662,18 @@ export function parseFull(content) {
     resolution = inferDimsFromLayers(layers);
   }
 
+  for (const layer of layers) {
+    for (let fi = 0; fi < layer.cells.length; fi++) {
+      const cell = layer.cells[fi];
+      if (cell?._pathNeedsRebake && cell.path) {
+        layer.cells[fi] = {
+          grid: bakePathCell(cell.path, resolution.width, resolution.height),
+          path: cell.path,
+        };
+      }
+    }
+  }
+
   const tags = (Array.isArray(data.tags) ? data.tags : [])
     .filter(isPlainObject)
     .map((t) => ({
@@ -590,7 +693,7 @@ export function parseFull(content) {
     defaultDurationMs,
     tags,
     defaultTag,
-    cornerRadius: parseCornerRadius(data),
+    ...parseFinish(data),
     layers,
   };
 }
@@ -624,7 +727,8 @@ export function upgradeCompactToFull(art) {
     defaultDurationMs: DEFAULT_DURATION_MS,
     tags: [],
     defaultTag: undefined,
-    cornerRadius: art.cornerRadius,
+    renderer: art.renderer ?? GRID_RENDERER,
+    cornerRadius: clampCornerRadius(art.cornerRadius),
     layers: [
       {
         id: 'layer-0',
@@ -643,13 +747,19 @@ export function upgradeCompactToFull(art) {
 // full-form serialize
 // ---------------------------------------------------------------------------
 
-/** Collect the set of palette keys actually used by any { grid } cell. */
+/** Collect palette keys used by grids and editable path source data. */
 function usedKeysOf(sprite) {
   const used = new Set();
   for (const layer of sprite.layers) {
     for (const cell of layer.cells) {
       if (cell && 'grid' in cell) {
         for (const row of cell.grid) for (const ch of row) used.add(ch);
+        if (cell.path) {
+          for (const shape of cell.path.shapes ?? []) {
+            if (shape.fill) used.add(shape.fill);
+            if (shape.stroke) used.add(shape.stroke);
+          }
+        }
       }
     }
   }
@@ -685,16 +795,16 @@ 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 } : {}),
+    // Each omitted at its default, so pixel-mode files stay byte-identical to
+    // their pre-finish shape.
+    ...finishFields(sprite),
     layers: sprite.layers.map((l) => ({
       id: l.id,
       name: l.name,
       visible: l.visible,
       opacity: l.opacity,
       blendMode: l.blendMode,
-      kind: l.kind,
+      ...(l.kind === 'path' ? { kind: 'path' } : {}),
       cells: l.cells.map((c) => {
         if (c == null) return null;
         if ('grid' in c) {
@@ -703,6 +813,10 @@ export function serializeFull(sprite) {
           const cell = { grid: c.grid };
           if (c.x) cell.x = c.x;
           if (c.y) cell.y = c.y;
+          if (c.path) {
+            const path = serializePathData(c.path);
+            if (path) cell.path = path;
+          }
           return cell;
         }
         return { link: c.link };
@@ -757,7 +871,7 @@ export function resolveCell(layer, frameIndex) {
     visited.add(idx);
     const cell = layer.cells[idx];
     if (cell == null) return null;
-    if ('grid' in cell) return { grid: cell.grid, x: cell.x ?? 0, y: cell.y ?? 0 };
+    if ('grid' in cell) return { grid: cell.grid, x: cell.x ?? 0, y: cell.y ?? 0, path: cell.path };
     idx = cell.link;
   }
   return null;
@@ -966,7 +1080,7 @@ function normalizeSvgRect(raw, ctx) {
  *  Euclidean distance. Alpha is ignored for distance. Returns the chosen
  *  "#rrggbb" (lowercase), or null when the input is invalid or fully
  *  transparent (alpha === 00). */
-function quantizeToPalette(hex, palette) {
+export function quantizeToPalette(hex, palette) {
   const norm = normalizeHex(hex);
   if (!norm) return null;
   const body = norm.slice(1);
@@ -1000,6 +1114,10 @@ function quantizeToPalette(hex, palette) {
  * RGB Euclidean distance. The returned palette contains only the quantized
  * colors actually used; transparent cells stay transparent ("."). Returns null
  * if the svg has no usable rects.
+ *
+ * For vector SVG (paths, circles, strokes), use `scripts/import-svg.mjs` which
+ * produces a path layer with baked grid, or pass `--pixel` for compact pixel-only
+ * output. svg-rect remains the fast path for one-rect-per-pixel emissions.
  */
 export function svgRectToPxArt(svg, opts) {
   const resolution = opts?.resolution ?? DEFAULT_RESOLUTION;