castle-web-cli 0.4.115 → 0.4.117

package/kits/physics-2d/docs/pxart-format.md

@@ -1,15 +1,15 @@
-# `.pxart` Pixel-Art Format (basic-2d kit)
+# Sprite format (`.sprite`, physics-2d kit)
 
-This documents the `.pxart` sprite format as integrated into the `basic-2d`
+This documents the Castle sprite format as integrated into the `physics-2d`
 kit. The format and its parser/serializer/renderer live in the kit itself, in
 `engine/pxart.js` (`parseFull`, `serializeFull`, `renderSpriteFrame`, plus
 the compact-form helpers `parseCompact` / `serializeCompact` / `renderToCanvas`).
-`.pxart` is a pure kit-layer concern — the harness (`castle-web-sdk`, the CLI)
+The on-disk JSON format is a pure kit-layer concern — the harness (`castle-web-sdk`, the CLI)
 has no knowledge of it.
 
 A sprite is modeled on Aseprite conventions: a `layers × frames` spreadsheet of
 cells, one resolution per sprite, an ordered indexed palette, named animation
-tags, and Aseprite-style linked cells. A `.pxart` file is a single JSON object.
+tags, and Aseprite-style linked cells. A sprite file is a single JSON object.
 
 The format has two **coexisting on-disk forms** — capability tiers, *not*
 temporal versions — that the kit treats as one in-memory model:
@@ -19,8 +19,9 @@ temporal versions — that the kit treats as one in-memory model:
   absent). The parser upgrades it into a degenerate one-layer / one-frame
   Sprite in memory.
 
-> Files in this kit use the extension `.pxart`. They live under `drawings/`
-> and are discovered by `engine/files.js`.
+> Files in this kit use the extension `.sprite` under `drawings/`. The legacy
+> extension `.pxart` names the same format and remains readable; create new art
+> as `.sprite`.
 
 ---
 
@@ -104,7 +105,7 @@ only affects what the editor writes back.) The swatch UI renders as an 8-column
 grid (8 rows for the 64 colors) that scrolls within the inspector.
 
 **Agent subset — 16 colors (`AGENT_PALETTE_16`): what the LLM generates with.**
-The agent generation path (the `draw` svg-rect → `.pxart` quantizer and the
+The agent generation path (the `draw` svg-rect → `.sprite` quantizer and the
 prompt the model receives) is constrained to a **fixed 16-color subset of
 Endesga-64**, so generated art stays coherent. Every color below is a member of
 `EDG64`. In order:
@@ -188,10 +189,386 @@ When the `playing` prop is `false`, the behavior holds frame 0.
 - `layers`: an **ordered** array, **bottom → top** (`layers[0]` drawn first).
 - Each layer: `id`, `name`, `visible` (skipped when hidden), `opacity`
   (`0.0`–`1.0`), `blendMode` (**`"normal"` only** for now), `kind`
-  (**`"pixel"` only** for now), and `cells` (its row of the spreadsheet).
+  (**`"pixel"` or `"path"`**; missing/unknown values default to `"pixel"`),
+  and `cells` (its row of the spreadsheet).
 
 `renderSpriteFrame` composites visible layers bottom→top, applying per-layer
-opacity, at 1px/cell with `imageSmoothingEnabled = false`.
+opacity, at 1px/cell with `imageSmoothingEnabled = false`. This render path is
+kind-agnostic: every consumer can read the baked `grid`. **Pixels are truth.**
+
+### 6.1 Path layers (stacked shapes)
+
+A `"path"` layer may attach editable vector source to any grid cell. The vector
+model is an **ordered stack of shapes** painted back-to-front (painter's
+order).
+
+```json
+{
+  "grid": ["...."],
+  "path": {
+    "shapes": [
+      {
+        "fill": "a",
+        "stroke": null,
+        "subpaths": [
+          {
+            "closed": true,
+            "start": [4, 8],
+            "segs": [
+              { "to": [12, 8], "c1": [2.2917, 2], "c2": [-2.2917, 2] },
+              { "to": [4, 8], "c1": [-2.2917, -2], "c2": [2.2917, -2] }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+- `shapes` is an ordered array (index 0 = back; later shapes overwrite earlier
+  pixels). Each shape has:
+  - `fill`: palette key or `null` (no fill).
+  - `stroke`: palette key or `null` (no stroke). Stroke is per-shape — whole
+    outline or none; there are no per-segment strokes.
+  - either `subpaths` — one or more rings/chains, described below — or a `prim`
+    key, whose geometry is generated from parameters instead
+    ([§6.1.3](#613-primitive-shapes-normative)).
+- A subpath is `{ closed, start, segs }`: one starting anchor and an ordered
+  list of segments leaving it. Its anchors are `start` followed by each `to`,
+  except that a curved closing segment's `to` restates `start` rather than
+  adding an anchor — see closure below.
+- A segment is `{ to, c1?, c2? }`:
+  - `to` is the segment's end anchor, in absolute cell units.
+  - `c1` and `c2` are **cubic Bézier control offsets, stored relative** — `c1`
+    from the segment's start anchor, `c2` from `to`. Relative handles are what
+    let an anchor drag move a curve rigidly without rewriting its controls.
+  - A segment with neither is a straight line. There is no other curve form:
+    circular arcs are materialized into cubics on the way in.
+- **Closure is implicit when it is straight, explicit when it is curved.** This
+  is SVG's `Z` with one addition, and it is the canonical form: a straight
+  closing segment is never stored.
+  - A four-corner rectangle stores **three** segments and reports **four**
+    anchors and **four** edges. The edge from the last anchor back to `start` is
+    synthesized by `subpathEdgeCount` / `subpathEdgeFrom` /
+    `edgeObjectsForSubpath`, so it is fully editable — bend it, split it, stroke
+    it — without being on disk.
+  - A **curved** close cannot be implied, because handles have nowhere to live.
+    It stays as a final segment whose `to` duplicates `start` — the second
+    segment in the example above (a lens is two curved edges between two
+    anchors).
+  - `subpathClosesOnStart` distinguishes the two. When it is true the duplicate
+    is **not a distinct anchor**; `subpathVertexCount` and `subpathPoints` omit
+    it, and anything that **rebuilds segments by index** must map that segment
+    back to vertex 0. Indexing it as `segIndex + 1` puts it past the last vertex,
+    so a drag strands it at the old coordinate: the ring gains a phantom anchor
+    and a spike back to where the shape used to be. Implicit closure removes this
+    hazard for straight closes by removing the duplicate, but curved closes still
+    have it.
+  - Canonicalization happens in `normalizeSubpath` and at the parse boundary, so
+    a redundant straight closing segment from an in-memory constructor is dropped
+    on read rather than tolerated. Two forms of the same ring never coexist and
+    disagree about edge count.
+  - Path data built in memory rather than loaded — a fixture, a generator — has
+    not been through that boundary, so anything consuming it must read through
+    `normalizeSubpath` or hand it to `parsePathData` first.
+- Multi-subpath fills use **even-odd** winding (donuts / holes). Open subpaths
+  are skipped when filling, so a limb strokes but never bounds a region.
+- An open subpath with stroke and no fill is a 1px polyline.
+- **A shape may mix a closed outline with open subpaths, and that is how art
+  with internal divisions is written.** The closed ones bound the fill; the open
+  ones only stroke. One outline around the whole silhouette, plus a line for
+  each internal division:
+
+  ```json
+  {
+    "fill": "b",
+    "stroke": "a",
+    "subpaths": [
+      { "closed": true, "start": [5, 5], "segs": [
+          { "to": [16, 5] }, { "to": [16, 9] }, { "to": [24, 9] },
+          { "to": [24, 19] }, { "to": [16, 19] }, { "to": [16, 23] },
+          { "to": [5, 23] } ] },
+      { "closed": false, "start": [16, 9], "segs": [{ "to": [16, 19] }] }
+    ]
+  }
+  ```
+
+  The alternative — two abutting closed shapes — carries two fill keys that have
+  to be kept in step, and seams where they meet, because each strokes its own
+  side of the shared border. One shape with a divider has a single fill, one
+  stroke down the middle, and nothing to keep in step. Anchors shared between
+  subpaths are held together by coordinate: the editor moves and deletes every
+  anchor sitting on a site as one, so a divider stays welded to the outline it
+  divides.
+
+  The editor writes exactly this when a pen run that starts and ends on an
+  outline is spliced into it: the outline takes in the new run, and the stretch
+  it displaced is kept as an open subpath rather than discarded.
+- **A boundary is stored once.** An open subpath that a closed subpath in the
+  same shape already walks in full is dropped rather than kept beside it
+  (`absorbRetracedSubpaths`). The match is a contiguous run of the loop's edges,
+  beginning anywhere on it and read either way round, comparing anchor positions
+  **and** curvature — so a divider counts as retraced only when it lies exactly
+  on the outline, not merely near it.
+
+  This is the dual of splice, and the pair is what stops editing from
+  ratcheting. Splice lifts a run out of a loop and keeps it because it has become
+  interior; absorb puts it back when the loop comes round to retrace it, which is
+  what deleting the vertex that made it interior does. Without both, every such
+  round trip leaves a second copy of an edge that already exists, and the copies
+  stroke twice and drift apart on the next drag. Dropping one is safe precisely
+  because `stroke` is per-shape, so coincident edges paint identically.
+
+  Unlike the closure rules above, this is **not** applied at the parse boundary.
+  A file keeps a retraced run until an edit commits, so it renders as authored
+  right up until the shape is first touched — which means **authored files must
+  not rely on one surviving**. Write a division only where it departs from the
+  outline; where it coincides, the outline's own edge is already the stroke.
+- Because only closed subpaths bound the fill, **an outline that is opened stops
+  filling**. Removing an edge from a ring does exactly that — there is no
+  representation for a ring with a gap, so the survivors become an open subpath.
+  The shape keeps its `fill` key while open, so closing it again restores the
+  fill it had rather than leaving it to be picked a second time.
+- Coordinates are finite floats in cell units, **framed to the canvas**
+  ([§6.1.1](#611-coordinate-model-normative)) and rounded to four decimals on
+  serialize. The half-cell lattice is authoring guidance, not a storage
+  invariant ([§6.1.2](#612-the-half-cell-lattice-authoring-guidance)).
+  Off-canvas points are legal and clip during baking.
+- Sagitta/bow ratio detents are an authoring **gesture** only (the bend tool
+  magnetizes toward bow/chord ratios at eighth-turn central angles). Storage is
+  always cubic segments.
+- Shape objects may carry additional keys for forward-compatible variants. v1
+  only understands `fill` / `stroke` / `subpaths` / `prim`.
+
+#### 6.1.1 Coordinate model (normative)
+
+A sprite cell has **two** ways to say "where": the cel offset (`x`/`y` on the
+cell, see [§7](#7-cells)) and the coordinates inside the cell's content. For a
+pixel cell those compose — a small `grid` placed at an offset. For a path cell
+they would double-count, so the format fixes it:
+
+- **Path point coordinates are CANVAS-framed**, not cel-local: `[0, 0]` is the
+  canvas origin, and the bake output covers the full `resolution`, never a
+  tight bounding box.
+- **A path cell's `x` and `y` MUST be `0`.** Serializers omit them. A nonzero
+  offset on a path cell is malformed, not a second positioning mechanism.
+  Rather than discard a malformed offset — which would jump the art to the
+  origin — the parser FOLDS it into the source, translating every point by
+  `(x, y)` and then clearing it. The cell lands in the canonical form with its
+  appearance unchanged, so an old or hand-edited file migrates silently and
+  correctly.
+
+The offset mechanism exists so a pixel cel can retain content pushed outside
+the canvas window without storing a canvas-sized grid of transparency. Path
+cells don't need it: the vector source retains off-canvas geometry exactly (as
+plain numbers) and clips only when baking, so nothing is lost without it.
+
+Every cell on a path layer — including freshly converted layers with no
+`path` key yet — MUST carry offset `(0, 0)`. Serializers omit `x`/`y`; nonzero
+offsets on path layers are malformed.
+
+**Resize** (`resizeSprite`) reframes and never crops. Pixel cells keep their
+grid and shift their offset by the centered delta. Path cells have no offset
+to shift, so they translate instead: every point moves by the same
+`(dx, dy)` (via `translatePathData`) and the cell re-bakes at the new
+resolution. Segment handles are stored relative and so are unaffected. A path layer
+therefore survives any sequence of resizes losslessly — the source is
+resolution-independent and only the derived `grid` changes.
+
+#### 6.1.2 The half-cell lattice (authoring guidance)
+
+The **half-cell lattice** — multiples of `0.5`, where integers are pixel
+corners and half-integers are pixel centers — is the natural grid for pixel
+art. Authoring tools **magnetize** toward it when the pointer is close (within
+a screen-space radius, so the pull feels constant regardless of zoom). Alt
+extends magnetism to pixel corners as well as centers.
+
+**Storage does not enforce the lattice.** Coordinates round to four decimal
+places on serialize; off-lattice values load faithfully. This lets imported SVG
+and continuous ellipse parameters keep their geometry while still offering a
+predictable snap feel in the editor.
+
+For clean rasterization: stroked outlines degrade at exact integer coordinates;
+filled regions are cleanest at integer corners. The SVG emission guide advises
+agents on optimal phases — see `scripts/svg-emission-guide.md`.
+
+`bows` are **not** stored — curves are cubic segments (`c1`/`c2` relative
+offsets). The bend tool uses ratio detents as a **gesture** with magnetic pull.
+
+Worth knowing before reaching for the curve vocabulary to fix a shape: it is
+usually not what is limiting. Measured against a true ellipse, eight free arcs
+on *exact* anchors land within 0.04 cells, but snapping those anchors to the
+half-cell lattice costs 0.17 — several times more than the vocabulary ceiling.
+The same measurement shows adding anchors can make a shape worse, not better:
+a 4-anchor circle is exact to 0.006 cells, while an 8-anchor one is off by
+0.343, because the intermediate anchors do not land on the lattice.
+
+#### 6.1.3 Primitive shapes (normative)
+
+A shape may carry a `prim` key instead of `subpaths`, in which case its geometry
+is **generated from parameters** rather than authored. One primitive exists:
+
+```json
+{ "prim": "ellipse", "cx": 8, "cy": 8, "rx": 7, "ry": 4, "fill": "q", "stroke": null }
+```
+
+`cx`, `cy`, `rx`, `ry` are finite floats like any other coordinate, rounded to
+four decimals on serialize; the radii are clamped to `MIN_ELLIPSE_RADIUS`.
+Authoring magnetizes them toward the lattice the way it magnetizes points, but
+storage does not enforce it, so a resize is continuous rather than stepped.
+`fill` and `stroke` mean what they mean for any other shape.
+
+**A primitive's `subpaths` are derived on parse and never serialized.** This is
+the whole point of the construct, and it follows from the measurement in §6.1.2:
+anchor placement — not the arc vocabulary — is what deforms an oval, so a
+primitive stores only its *parameters* and lets the curve derived from them run
+free. Writing that curve to disk would expose every intermediate anchor to
+rounding and to any tool that quantizes points, undoing the gain. A 7×4 oval
+derived this way sits within 0.005 cells of a true ellipse against 0.174 for the
+same oval with hand-placed anchors.
+
+The ring is traced by sixteen circular arcs whose sagittae are fitted to the
+true ellipse. A circle comes out to a thousandth of a cell — every span really
+is a circular arc — and an oval to about four times that, which is still far
+below the lattice error it replaces.
+
+Because the geometry is regenerated, **only the parameters are editable.** The
+four anchors on the ellipse's own axes are exposed as radius handles; the rest
+of the ring is not grabbable, and anchor insertion, deletion, bending, opening,
+and hole-punching are all refused rather than allowed to appear to work and then
+vanish on the next derive. **Detach-to-paths** (materialize the derived ring as
+ordinary subpaths) is planned; until then the refusal is intentional.
+Whole-shape operations — move, flip, quarter-turn,
+duplicate, recolor, reorder — act on the parameters and behave normally.
+
+Dragging a radius handle holds the opposite edge still, as in Figma and
+Illustrator; Alt resizes about the centre instead. The difference is felt when
+the pointer is near a lattice site and magnetism engages: anchoring the far edge
+spends the whole snap at the handle, so it advances a cell at a time, while
+resizing about the centre splits it across both sides and the handle tracks the
+pointer twice as finely.
+
+Consumers other than the editor need to know none of this: parse hands them an
+ordinary shape with subpaths, so bake, stroke tracing, hit-testing, and the
+vector renderer are unchanged.
+
+#### 6.1.4 Stroke canonicality (normative)
+
+A stroke exists in three forms, and it matters which one is authoritative for
+what, because they are not cell-identical:
+
+| Form | Where | Authoritative for |
+| --- | --- | --- |
+| **Source** — anchors + cubic segments | the `path` object | **all geometry queries**: hit-testing, snapping, selection, measurement |
+| **Traced chain** — 8-connected 1px cells | `traceEdgePixels`, in the bake | the stored `grid` (what every consumer reads) |
+| **Analytic stroke** — 1-cell round-cap/join | `renderer: "vector"` only | display, that frame only |
+
+Both the traced chain and the analytic stroke are **derived** from the source;
+neither derives from the other, and they are not required to agree cell for
+cell. The traced chain quantizes to keep 1px stroke discipline; the analytic
+stroke follows the true curve.
+
+**Layer invariant:** anything answering "what does this look like / where is it"
+(fill bake, stroke trace, hit-testing, marquee, vector render) flattens the
+stored cubic segments. Sagitta/bow is a **gesture vocabulary only** — the bend
+tool reads and writes it, but representation queries never re-derive a circular
+arc from measured sagitta when true handles are present.
+
+The rule that falls out: **never hit-test against baked pixels or against the
+analytic stroke.** Editor queries measure distance to the flattened source
+curve, so selection behaves identically at every finish setting.
+`forEachStrokePixel` is a bake primitive and must not be used for hit-testing —
+under `renderer: "vector"` it reports cells the user isn't looking at.
+
+**Normative bake** (`bakePathCell` in `engine/pxartPath.js`):
+
+This defines the bake's **output**, not its algorithm. Any implementation that
+produces an identical grid is conformant — bounding-box culling, active-edge
+scanline fills, and dirty-region re-bakes are all permitted and expected, since
+the reference formulation below is superlinear in `resolution` and the format
+allows canvases up to 512. The observable contract is the grid.
+
+The kit takes that latitude: it culls each shape to its bounding box and fills
+by scanline, computing edge crossings once per supersample row instead of
+testing every subpixel against every edge. Read literally, step 2a costs
+`area × supersample² × edges` per shape — and since the supersample is squared,
+that grows with the FOURTH power of resolution. A stack that bakes in a
+millisecond at 16×16 took **31 seconds** at 128×128 before the change and takes
+under 100 ms after. Keep the reference formulation as the definition of the
+output; do not implement it literally.
+
+1. Conceptually, one supersampled composite raster covers the whole layer at 4×
+   (`FILL_SUPERSAMPLE`).
+2. For each shape in stack order: (a) its fill covers every subpixel whose
+   center is inside the shape under even-odd winding over the flattened
+   subpaths (curves via the stored cubic segments), overwriting; (b) its 1px
+   stroke chain is computed at **native** resolution by flattening the same
+   cubic segments with symmetric quantization (`flattenEdge`), 8-connected
+   tracing (`traceEdgePixels`), and direction-invariant `cleanupCorners`, and
+   each stroke cell occupies a full `scale×scale` block of that key.
+3. After all shapes: majority-downsample the composite once to native cells —
+   a cell paints only when painted subpixels cover ≥ half of it (ties paint);
+   color is the majority key among painted subpixels; on key-count ties prefer
+   the key painted **later** in stack order (painter's-order tiebreak).
+
+The bake is a **pure function** of `(path, width, height)`: deterministic, with
+no dependence on iteration order, floating-point accumulation across shapes, or
+prior grid contents. Two bakes of equal input produce equal output.
+
+Rationale: compositing fills at supersample before the single downsample means
+two abutting shapes' subpixels union across the shared boundary, so boundary
+cells go to whoever owns the majority — no 1px transparent gutters. Stroke
+cells stamped as full blocks keep 1px stroke discipline while still letting a
+later shape's fill cover an earlier shape's stroke.
+
+Per-shape order within a shape is fill then stroke (stroke wins over that
+shape's own fill). The bake has no anti-aliasing: every output cell remains an
+exact palette key. Pixels remain the source of truth — `grid` is always baked
+on serialization; runtime and non-path-aware consumers read only pixels.
+
+**Finish semantics** (file-level `renderer` + `cornerRadius`, see
+[§10](#10-finish)):
+
+- `renderer: "grid"`, `cornerRadius: 0` (Pixel): render the baked `grid`
+  nearest-neighbor.
+- `renderer: "grid"`, `cornerRadius > 0` (`¼` / `½`): corner-kernel smoothing on
+  the baked grid (same kernel as pixel layers — works for both kinds). The grid
+  itself is unchanged.
+- `renderer: "vector"` (Smooth): paint the shape stack **analytically** into the
+  supersampled canvas — fills as even-odd canvas paths, strokes as 1-cell-wide
+  analytic strokes with round caps and round joins along the true curves,
+  shapes in stack order.
+
+Only the last one departs from the baked grid, and only for display — see
+[§6.1.4](#614-stroke-canonicality-normative) for which form is authoritative
+for what.
+
+Parser degradation is local and tolerant: a missing/non-array `shapes` drops
+the path object while the baked grid remains valid; malformed shapes/subpaths
+drop individually. `path` and `kind` round-trip through full parse/serialize.
+Palette pruning includes shape fill/stroke keys.
+
+Links share the whole resolved cell, including `path`. Each materialized cell
+owns its own copy — resolving a link or re-linking after a frame op must deep
+copy `path`, never alias one object across cells. A path layer always
+serializes in full form (the `kind` mismatch fails compact eligibility on its
+own; nothing hand-maintained enforces it).
+
+**Layer-kind conversion is lossy in both directions**, and neither direction is
+reversible except via Undo:
+
+- **Pixel → Path** discards the layer's pixels on every frame. There is no
+  vectorization; the new path source starts empty and the grid re-bakes
+  transparent. The editor confirms first when the layer has opaque pixels.
+- **Path → Pixel** discards the vector source and keeps the baked grid as
+  truth. The art survives; its editability does not.
+
+Interactive shape editing is **shipped** (`editors/pathTools.js` — pen, select,
+bend, punch, anchor edit, flip/rotate, z-order, recolor), alongside the render
+path (bake + finishes + overlay). The path unit and check suites live in the
+`shape-layers` lab deck, which is where this engine is developed; run them there
+after format, bake, parser, serializer, or model changes.
 
 ---
 
@@ -213,6 +590,24 @@ cell index `f` is the layer's content for frame `f`. A cell is one of:
 - **Faithful storage:** grids are stored as **packed strings** of palette keys.
   Generation-only emission shapes (svg-rect, etc.) normalize into this packed
   form and are never the thing of record.
+- **Cel offset** (`x`/`y` on a `{ grid }` cell, omitted when `0`) places a grid
+  that is smaller than — or shifted out of — the canvas window, so a resize can
+  reframe without cropping. It applies to **pixel cells only**: a cell carrying
+  `path` must have `x`/`y` of `0`
+  ([§6.1.1](#611-coordinate-model-normative)).
+- Any helper that rebuilds a cell must **carry `path` through**, and each
+  rebuilt cell must own its own **deep copy** — resolving a link chain hands
+  several slots the same object, so materializing them without copying leaves
+  independent frames sharing one source. Rebuilding via a grid-only constructor
+  silently strips the vector source and leaves a stale baked grid behind it.
+- A rebuild that MOVES a path cel (resize, cel-offset change) translates the
+  source and re-bakes rather than carrying the grid across unchanged, so the
+  grid never disagrees with the points it came from.
+- A rebuild that would **write pixels directly into a path cel** — a paint
+  merge — must instead refuse. There is no correct outcome: keeping the source
+  desyncs it from the grid (the next path edit reverts the paint), and dropping
+  the source destroys the vector art. The pixel tools are gated off path layers
+  in the UI, so this is a guard, not a workflow.
 
 ---
 
@@ -224,6 +619,12 @@ cell index `f` is the layer's content for frame `f`. A cell is one of:
   happen **outside** the file — in this kit, the actor's `Layout` box. The
   `Sprite` behavior blits the native-resolution frame into the Layout rectangle
   with smoothing disabled and an optional `tint` multiply.
+- **Path source shares this space**, continuously rather than by cell index: a
+  point of `[3, 5]` is the corner where pixels `(2,4)`, `(3,4)`, `(2,5)` and
+  `(3,5)` meet, and `[3.5, 5.5]` is the center of pixel `(3,5)`. Both are on
+  the half-cell lattice ([§6.1.2](#612-the-half-cell-lattice-normative)).
+  Coordinates outside `[0, width] × [0, height]` are legal and retained; they
+  clip when baking.
 
 ---
 
@@ -282,51 +683,106 @@ case).
 
 ---
 
-## 10. Corner rounding
+## 10. Finish
 
 ```json
 "cornerRadius": 0.25
 ```
 
-- A top-level **number**: a corner-rounding radius, in native-pixel units.
-  `0` (the default) renders sharp/nearest-neighbor, same as before this field
-  existed. Any value `> 0` renders rounded, by that amount — see "Rendering"
-  below. **File-level** — a property of the sprite asset itself, not a
-  per-actor/per-placement override. There is no equivalent `Sprite` behavior
-  prop.
+```json
+"renderer": "vector"
+```
+
+The finish is **two orthogonal fields**: *which renderer* draws the sprite, and
+*how much* corner rounding the grid renderer applies.
+
+- **`renderer`**: `"grid"` (default, omitted when default) or `"vector"`.
+  `"grid"` renders from the baked `grid`. `"vector"` renders each path layer
+  analytically from its shape stack and each pixel layer with the corner kernel
+  at `MAX_CORNER_RADIUS` — see [§6.1](#61-path-layers-stacked-shapes).
+- **`cornerRadius`**: **always a number**, in native-pixel units, clamped to
+  `[0, MAX_CORNER_RADIUS]` on read. Default `0`, omitted when `0`. It is the
+  rounding amount the grid renderer applies; the vector renderer uses it for
+  its pixel layers.
+
+Both are **file-level** — properties of the sprite asset itself, not
+per-actor/per-placement overrides. There is no equivalent `Sprite` behavior
+prop for either.
+
+> **Why two fields.** These were briefly one: `cornerRadius` held either a
+> number or the string `"smooth"`. That union is retired because a categorical
+> mode and a continuous amount don't share a slot cleanly — every
+> `cornerRadius > 0` test in the codebase silently read `"smooth"` as *false*
+> (`'smooth' > 0` is `NaN`-comparison false), so a smooth sprite took the sharp
+> branch anywhere the string wasn't special-cased, 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 the
+> "a value, not a flag" argument below actually hold.
+
 - **A value, not a flag**, deliberately: the amount of rounding is itself
   part of the portable file format, not a fixed code-side constant every
-  smooth sprite would otherwise be stuck with. `MAX_CORNER_RADIUS` (0.5, in
+  rounded sprite would otherwise be stuck with. `MAX_CORNER_RADIUS` (0.5, in
   `engine/pxart.js`) is the ceiling — two corner cuts on the same
-  1-native-pixel edge must not overlap — and any value is clamped to
-  `[0, MAX_CORNER_RADIUS]` on read. The `PxArtEditor` UI curates this down to
-  a 3-way segmented control (`0` / `¼` / `½`, see `CornerRadiusBar` in
-  `editors/pixelInspector.jsx`) so picking a value never means hunting a
-  slider, but the format itself isn't limited to those three — any in-range
-  number is valid, e.g. from hand-edited JSON or a future finer-grained UI.
-- **`0` is the default** and is never written to disk: `serializeFull` and
-  `serializeCompact` both OMIT the field when it's `0`, so existing (and
-  newly authored, unsmoothed) files stay byte-identical to their
-  pre-`cornerRadius`-field shape.
-- **Present in BOTH on-disk forms.** `parseCompact` reads a top-level
-  `cornerRadius` alongside `palette`/`grid`; `parseFull`'s native-full branch
-  reads it alongside `resolution`/`layers`; `upgradeCompactToFull` carries a
-  compact file's `cornerRadius` through into the upgraded Sprite. This means
-  the kit's save path — which picks compact vs. full by a serialize →
-  re-parse round-trip (`serializeModel` in `editors/pxArtEditorModel.js`, see
-  [§9](#9-compact-shorthand)) — never drops the field: a single-layer/frame
+  1-native-pixel edge must not overlap. The `PxArtEditor` UI curates the pair
+  down to a 4-way segmented control (`Pixel` / `¼` / `½` / `Smooth`, see
+  `FinishBar` in `editors/pixelInspector.jsx`) so picking a finish never means
+  hunting a slider, but the format itself isn't limited to those four: any
+  in-range radius is valid under either renderer, e.g. from hand-edited JSON or
+  a future finer-grained UI.
+
+  | UI preset | `renderer` | `cornerRadius` |
+  | --- | --- | --- |
+  | Pixel | omitted (`"grid"`) | omitted (`0`) |
+  | ¼ | omitted (`"grid"`) | `0.25` |
+  | ½ | omitted (`"grid"`) | `0.5` |
+  | Smooth | `"vector"` | omitted (`0`) |
+- **Defaults are never written to disk:** `serializeFull` and
+  `serializeCompact` both OMIT `cornerRadius` when it's `0` and `renderer` when
+  it's `"grid"`, so existing (and newly authored, unsmoothed) files stay
+  byte-identical to their pre-finish shape. A plain pixel sprite carries
+  neither field.
+- **Present in BOTH on-disk forms.** `parseCompact` reads both fields
+  alongside `palette`/`grid`; `parseFull`'s native-full branch reads them
+  alongside `resolution`/`layers`; `upgradeCompactToFull` carries a compact
+  file's finish through into the upgraded Sprite. This means the kit's save
+  path — which picks compact vs. full by a serialize → re-parse round-trip
+  (`serializeModel` in `editors/pxArtEditorModel.js`, see
+  [§9](#9-compact-shorthand)) — never drops them: a single-layer/frame
   rounded sprite still serializes compact, with `cornerRadius: 0.25` alongside
-  `palette`/`grid`.
-- **Parser tolerance:** any non-finite-number value (missing field, `null`, a
-  typo) defaults to `0`. Numbers are clamped to `[0, MAX_CORNER_RADIUS]`.
-  **Legacy back-compat:** 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: a legacy `render: "smooth"`
-  becomes a fixed radius (`0.25`); a legacy numeric `render` value is read
-  as-is; anything else (including the original `render: "pixel"`) defaults to
-  `0`. This keeps old files rendering rounded rather than silently reverting
-  to sharp. Detection of compact vs. full form ([§1](#1-form-discriminator))
-  is unaffected — neither key is ever used as a structural signal.
+  `palette`/`grid`. The compact candidate must be built with BOTH fields and
+  the eligibility check must compare BOTH: that check compares an explicit list
+  of fields rather than the whole parsed object, so a field it does not name is
+  a field the compact form is free to silently drop. A mismatch on either one
+  forces the full form.
+- **Parser tolerance:** `renderer` is the exact string `"vector"` or else
+  `"grid"` (missing, `null`, a typo — anything unrecognized reads as `"grid"`).
+  `cornerRadius` reads as a number clamped to `[0, MAX_CORNER_RADIUS]`, and
+  **any non-number defaults to `0`**; the parser never yields a non-numeric
+  `cornerRadius`, so downstream `cornerRadius > 0` tests are always meaningful.
+  **Legacy back-compat**, all migrating on read and none of them structural
+  signals (compact-vs-full detection, [§1](#1-form-discriminator), is
+  unaffected):
+
+  | Legacy on disk | Reads as |
+  | --- | --- |
+  | `cornerRadius: "smooth"` | `renderer: "vector"`, `cornerRadius: 0` |
+  | `cornerRadius: <number>` | `cornerRadius` clamped, `renderer: "grid"` |
+  | `render: "smooth"` (oldest enum) | `cornerRadius: 0.25`, `renderer: "grid"` |
+  | `render: <number>` (brief numeric phase) | that radius, `renderer: "grid"` |
+  | `render: "pixel"`, or anything else | `cornerRadius: 0`, `renderer: "grid"` |
+
+  Old files therefore keep rendering rounded rather than silently reverting to
+  sharp, and a file written before the split still selects the vector renderer.
+- **Asking "is this sprite smoothed?"** Use `displayFinish(sprite)` from
+  `engine/pxart.js`, never a bare `cornerRadius` test. The vector renderer
+  carries `cornerRadius: 0`, so `cornerRadius === 0` reads a Smooth sprite as
+  Pixel. In `PxArtEditor` that predicate decides whether the native 1px/cell
+  canvas paints at all, and getting it wrong drew the blocky bake on top of the
+  analytic render — both finishes visible at once. `displayFinish` also returns
+  the radius to draw with, which is `MAX_CORNER_RADIUS` under the vector
+  renderer (pixel layers still go through the corner kernel there), not the
+  sprite's own field. `finish-check` guards this by asserting the interactive
+  canvas is empty at every non-Pixel finish.
 - **Rendering.** `cornerRadius === 0` renders as before: 1px/cell,
   nearest-neighbor (`renderSpriteFrame`, `imageSmoothingEnabled = false`).
   `cornerRadius > 0` renders through `engine/pxartSmooth.js`'s
@@ -348,8 +804,29 @@ case).
   a corner is always a same-block recoloring, never a shape that could leave
   a gap against its neighbors. This suits small pixel-art sprites, not
   general raster upscaling.
-- `behaviors/Sprite.jsx` blits a `cornerRadius > 0` sprite's cached canvas
-  with `imageSmoothingEnabled = true` (vs. `false` for `cornerRadius === 0`),
+- **Rendering, `renderer: "vector"`.** `renderSmoothCompositeFrame` renders each
+  layer as smoothly as its data allows at one shared supersample scale, then
+  composites bottom-to-top with visibility and opacity. Path layers paint
+  their shape stack analytically (even-odd fills + 1-cell-wide round-cap
+  strokes in stack order) — see §6.1. Canvas anti-aliasing is intentional in
+  this display-only stage and never changes the stored grid. Pixel layers use
+  the corner kernel at `MAX_CORNER_RADIUS`. Under `renderer: "grid"` — at every
+  `cornerRadius`, including `¼` and `½` — path layers render the normative
+  `bakePathCell` grid unchanged.
+- **Timeline thumbnails show the sprite's chosen finish**, via
+  `renderSmoothLayerCell` — a Smooth sprite reads as Smooth in the timeline
+  rather than as its bake. Only the plain Pixel finish takes the nearest-neighbor
+  blit. Measured at a 43px thumb, the analytic path render is *cheaper* than the
+  blit (0.06 ms vs 0.09 ms), because it draws shapes straight into the thumb
+  instead of baking a frame and upscaling it; the corner kernel behind `¼` / `½`
+  is the expensive one at ~0.4 ms, roughly 4-14x the blit. That cost is only
+  affordable because thumbs redraw on cel content and nothing else — see the
+  dependency list on `CellThumb`'s layout effect, which is load-bearing, not
+  incidental. It gates on the serialized `text`, since `deriveSprite` hands back
+  a fresh `sprite` object every render.
+- `behaviors/Sprite.jsx` blits a smoothed sprite's cached canvas
+  with `imageSmoothingEnabled = true` (vs. `false` for the plain
+  `renderer: "grid"`, `cornerRadius === 0` case),
   passing the sprite's own `cornerRadius` value through as
   `renderSmoothSpriteFrame`'s `cornerRadius` option; the offscreen canvas
   cache itself is unaffected (still one WeakMap entry per sprite object —
@@ -363,15 +840,24 @@ case).
 ## 11. Reserved / out of scope
 
 Named so the format can grow without a breaking change, but **not built**:
-tilemap/tileset layers (a future `kind`), slices, layer groups, vector/avatar
-layers, and rich blend modes (beyond `"normal"`). Reserving the `kind` and
-`blendMode` discriminators keeps these additive later, not breaking.
+tilemap/tileset layers (a future `kind`), slices, layer groups, avatar layers,
+and rich blend modes (beyond `"normal"`). Reserving the `kind` and `blendMode`
+discriminators keeps these additive later, not breaking — `kind: "path"`
+([§6.1](#61-path-layers-stacked-shapes)) is the first cash-in on that
+reservation and shipped without a format break, which is the intended pattern
+for the rest.
+
+Within path layers specifically, **not built**: per-segment strokes, stroke
+widths other than 1 cell, stroke alignment (inside/center/outside), gradients,
+and non-circular curve types. The `shapes[]` entries tolerate unknown keys
+precisely so variants like these stay additive; v1 understands only
+`fill` / `stroke` / `subpaths`.
 
 ---
 
 ## Appendix — sample
 
-`drawings/cauldron.pxart` is a 16×16 multi-layer animated sprite referenced by
+`drawings/cauldron.sprite` is a 16×16 multi-layer animated sprite referenced by
 the `pig` actor in `scenes/main.scene` (via `blueprints/cauldron.scene`)
 through the `Sprite` behavior — a working rendered example of the format in
 this kit.