spine-rigc 2.55.0 → 2.57.0

package/src/cli/shared.ts

@@ -39,10 +39,11 @@ import { compile, CompileError, droppedStateReason, headerBoundsOf, type Compile
 import { depthStepLevels, type FoldLimit, type TurnCeiling } from '../depth.ts';
 import { FOLDS_FILE } from '../folds.ts';
 import { PASS_THROUGH_FILE, PASS_THROUGH_RUN } from '../passthrough.ts';
+import { readViewportBox, ViewportError } from '../viewportpin.ts';
 import { parseJsonWithPosition } from '../json-position.ts';
 import { RUNG_IDS } from '../ladder.ts';
 import { MODEL_DOCUMENT_FILE, MODEL_DOCUMENT_SPEC, modelDocument, spineFileSha256 } from '../model.ts';
-import { compileErrorLine } from '../guide.ts';
+import { compileErrorLine, nearestNames } from '../guide.ts';
 import { PACKAGE_ROOT, readPackageMeta, readVersion } from '../package_meta.ts';
 import { DEFAULT_MAX_RESIDUAL, DEFAULT_SCALE_MAX, DEFAULT_SCALE_MIN } from '../pose.ts';
 import {
@@ -64,6 +65,7 @@ import { InspectError, DEFAULT_SHOW, DIM_KEEP, INSPECT_DEFAULT_FPS, ON_GRID_FRAM
 import { NotAPngError } from '../png.ts';
 import { PoseError } from '../pose.ts';
 import { RepackError } from '../repack.ts';
+import { SplitError } from '../meshsplit.ts';
 import { SpineRuntimeError, SPINE_SIDE_ABSENT } from '../spine_side.ts';
 import type { CompileResult, DroppedState } from '../types.ts';
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
@@ -675,12 +677,12 @@ function readCheckFlags(
     out.fps = fps;
   }
   if (flags.viewport !== undefined) {
-    const parts = flags.viewport.split(',').map((s) => Number(s.trim()));
-    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
-      throw new UsageError('--viewport takes four numbers: <x>,<y>,<width>,<height> — the world box, y up');
+    try {
+      out.viewport = readViewportBox(flags.viewport);
+    } catch (err) {
+      if (err instanceof ViewportError) throw new UsageError(err.message);
+      throw err;
     }
-    if (parts[2] <= 0 || parts[3] <= 0) throw new UsageError('--viewport width and height must be positive');
-    out.viewport = { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
   }
   if (flags.as !== undefined) out.as = flags.as;
   // The name is not checked against the candidate here: `check` owns that
@@ -1021,6 +1023,17 @@ const FLAG_MEANINGS: Record<string, string> = {
     'world units, one texel of the coarser drawing to a step — each with the depth and the world box. One line per pair, and one per frame that passes through. ' +
     'The order is the declaration: the first name must draw over the second for a frame to be read. A reading, not a gate. ' +
     'An unknown slot, a slot that draws on no frame, a malformed list and a pair named twice are refused by name. Not with --slot/--hide',
+  'angle-range':
+    'also read, for each <bone>:<relative-to> pair, the range of the first bone\'s world direction against the second\'s over each set\'s ' +
+    'frames — its rotationX less the other\'s, followed from frame to frame so a sweep past ±180° reads as itself — and print one line per ' +
+    'pair per set: the lowest and the highest angle in degrees, the span, and the frame each was first reached on. Read on the frames\' own ' +
+    'grid, so a peak between two frames is not read. A reading, not a gate: nothing is written. An unknown bone, a bone against itself, ' +
+    'a malformed list and a pair named twice are refused by name, and so is a bone with no direction on a frame (a world matrix of zero)',
+  'viewport-from':
+    "draw on an earlier render's grid exactly — the box, the scale and the pixel size its frames.json records (the file, or the " +
+    'directory `render --out` wrote it into) — so a world point lands on the same pixel in both renders. A slot that reaches past ' +
+    'the box is named as under --viewport, and frames.json records the same under `pinned`. Not with --viewport, and not with --max: ' +
+    'the file fixes the pixel size',
   environment:
     'the world the rig\'s physics answers, in time: a file { "spec": "rigc-environment/1", "steps": [{ "t": <seconds>, ' +
     '"wind"?: [x, y], "gravity"?: [x, y] }, …] }, x right and y down, each step holding from its t until the next and set ' +
@@ -1035,6 +1048,12 @@ const FLAG_MEANINGS: Record<string, string> = {
     'line of the render or the check report says which and why. `--poser core` on an input that cannot carry it is refused by name. ' +
     "`explain`: which reads and poses the DEFORM block's survey — `core` (the model document the compile writes, spine-core untouched) or " +
     '`spine` (the Spine skeleton parsed and posed by spine-core); default `core`, and `spine` where the core refuses the document, which the block names',
+  'lever-fold':
+    '`explain` only: also read, on the turn lines\' walk, the steps where a physics constraint that drives scaleX has its inertia lever ' +
+    'divide by less than this fraction (above 0, at most 1) of the divisor it takes at the setup pose — the bone\'s length times its world x-axis ' +
+    'length, less scaleLag × shown on a drive that does not rotate — and the steps where the scale factor it applies moves by more than the ' +
+    'bone\'s setup scale in one step: each line the constraint, the steps, the extreme value and its step. No default: without it the reading ' +
+    'is not taken, and says so; a value that is not such a fraction is refused by name. A reading, not a gate',
   'texture-from':
     "also measure this run through this atlas's texels, keeping the candidate's own geometry, and report how much " +
     'of the MAE is texture resampling rather than the rig — pass the atlas the reference frames were rendered ' +
@@ -1080,6 +1099,9 @@ const FLAG_MEANINGS: Record<string, string> = {
     `printed (default ${DEFAULT_MIN_LEVER_PX}); below it the bone is refused \`no-bracket\` naming the measured ` +
     'lever, because an angle read across a short lever turns a half-pixel anchor error into several degrees',
   animation: 'which animation to show; the default is every one for `render` and the first for `preview`',
+  attachment:
+    "the placeholder the mesh is filed under in its slot, as the rig spec's skin names it. Absent, the slot's one " +
+    'authored mesh in that skin; a slot holding none or several is refused naming them',
   skin:
     'pose under this skin, by the name the skeleton declares. Without it NO skin is set — every slot resolves ' +
     'through the default skin alone, so a slot whose art lives only in a named skin draws nothing. A name the ' +
@@ -1211,6 +1233,8 @@ const FLAG_VALUES: Record<string, string> = {
   poser: 'core|spine',
   environment: '<schedule.json>',
   'pass-through': '<cloth>:<leg>[,<cloth>:<leg>…]',
+  'angle-range': '<bone>:<relative-to>[,…]',
+  'viewport-from': '<frames.json|dir>',
   reference: '<dir|skeleton.json>',
   'reference-atlas': '<path>',
   bones: `<correspondence.json|${IDENTITY_CORRESPONDENCE}>`,
@@ -1225,6 +1249,7 @@ const FLAG_VALUES: Record<string, string> = {
   scale: '<min,max>',
   rotation: '<min,max>',
   'max-residual': '<0..1>',
+  'lever-fold': '<fraction>',
   anchor: '<pose.json>',
   hinge: '<min,max>',
   stretch: '<ratio>',
@@ -1233,6 +1258,7 @@ const FLAG_VALUES: Record<string, string> = {
   'anchor-residual': '<0..1>',
   'inward-lever': '<px>',
   animation: '<name>',
+  attachment: '<name>',
   skin: '<name>',
   slot: '<name[,name…]>',
   hide: '<name[,name…]>',
@@ -1476,8 +1502,9 @@ export const COMMANDS: CommandDoc[] = [
       'rigc explain --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>] [--poser core|spine]   (it never gates, and writes nothing)',
       'rigc explain … --atlas-in <skeleton.atlas>                  (resolve the parts against a pack somebody already made, as build does)',
       'rigc explain --cut <name> --cuts <cuts.json>',
+      'rigc explain … --lever-fold <fraction>                     (also name the steps a scaleX lever divides by a collapsed length)',
     ],
-    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'atlas-in', 'cut', 'cuts', 'poser'],
+    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'atlas-in', 'cut', 'cuts', 'poser', 'lever-fold'],
     notes: [
       'this line said "the same arguments as build, minus --profile" and was false in both',
       'directions (issue #697): --atlas-in was not listed here, so the one flag that lets this',
@@ -1518,6 +1545,46 @@ export const COMMANDS: CommandDoc[] = [
       },
     },
   },
+  {
+    name: 'split',
+    runtime: false,
+    spineFormat: false,
+    usage: ['rigc split --rig <path> --motion <path> --slot <name> [--attachment <name>] [--skin <name>] --out <dir>'],
+    flags: ['rig', 'motion', 'slot', 'attachment', 'skin', 'out'],
+    overrides: {
+      out: {
+        value: '<dir>',
+        meaning:
+          'directory to write the proposal into — rig.json and motion.json, the two specs with the mesh split, and ' +
+          'split.json, where every original vertex and triangle went. Absent or empty, and refused otherwise: the ' +
+          "proposal never lands on top of a file, the author's own specs included",
+      },
+      slot: {
+        value: '<name>',
+        meaning: 'the slot whose mesh to split, as the rig spec declares it. A name it does not declare is refused with every one it does',
+      },
+      skin: {
+        meaning:
+          'the skin the mesh is filed under in the rig spec (default: default). A name the rig spec does not declare ' +
+          'is refused with the ones it does',
+      },
+    },
+    notes: [
+      'split reads the two specs — not a build: a mesh of several pieces does not build —',
+      'and finds the pieces of one authored mesh: triangles that share a vertex are one piece.',
+      'A mesh of one piece is said so on one line, exit 0, and nothing is written. Otherwise it',
+      'writes one mesh per piece: piece 1 (the piece whose first triangle is listed first) stays',
+      'in the slot, piece k gets a new slot <slot>_<k> on the same bone, after it in the draw',
+      "order, under the same placeholder. Each piece carries the original's uvs and weights (or",
+      'vertices) unchanged and its triangles renumbered — outline first where the hull rule',
+      'needs it — and every deform key is re-sliced to the new indices; colour and attachment',
+      'tracks on the slot are copied to the new slots. Nothing is invented: a deform index the',
+      'original run did not cover is written 0, which is what the parser held there. What the',
+      'split cannot carry is refused by name, exit 1 (docs/AUTHORING.md §3.4.11 lists it); a',
+      'name the specs do not have is refused with the names they do, exit 2. Nothing is ever',
+      'written over the specs it read: build the proposal, look at it, then adopt it.',
+    ],
+  },
   {
     name: 'diff',
     runtime: false,
@@ -1618,11 +1685,24 @@ export const COMMANDS: CommandDoc[] = [
       'rigc render … --slot <name[,name…]> | --hide <name[,name…]>   (a subset of the slots, on the whole rig\'s grid)',
       'rigc render … --environment <schedule.json>   (the wind and gravity the physics answers, in time)',
       'rigc render … --pass-through <cloth>:<leg>[,…]   (the frames where a cloth drawn over a leg passes through it)',
+      'rigc render … --angle-range <bone>:<relative-to>[,…]   (how far a bone turns against another, per animation)',
+      'rigc render … --viewport <x,y,w,h> | --viewport-from <frames.json>   (a box given, not fitted: two renders on one pixel grid)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'geometry', 'folds', 'pass-through', 'environment', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'pass-through', 'angle-range', 'environment', 'poser', 'out'],
     overrides: {
       out: { value: '<dir>', meaning: 'directory to write the frame series into (default `render/`)' },
-      fps: { meaning: `frames per second to sample the animation at (default ${PROTOCOL_FPS})` },
+      fps: {
+        meaning:
+          `frames per second to sample the animation at (default ${PROTOCOL_FPS}). A set drawn at any rate but the default is written to ` +
+          '`<anim>@<fps>fps/` rather than `<anim>/`, so two rates sit side by side: `--fps 24` writes `<anim>@24fps/`, and the default 12 writes `<anim>/`',
+      },
+      viewport: {
+        meaning:
+          'draw every frame over this world box, y up — x,y its bottom-left corner, the numbers frames.json\'s `viewport` records — ' +
+          'instead of the box fitted to the rig; its pixel size follows from --max. A slot that reaches past the box is named by set and ' +
+          'frame, with how far and on which side: what lies past it is not drawn, since each frame is the box. frames.json records that ' +
+          'the box was given, and those slots, under `pinned`. Not with --viewport-from',
+      },
     },
   },
   {
@@ -1910,6 +1990,16 @@ const USAGE_PARAGRAPHS: ReadonlyArray<{ about: readonly string[] | { flag: strin
       'is missing from it beats no spec at all.',
     ],
   },
+  {
+    about: ['split'],
+    lines: () => [
+      "split answers the refusal a mesh of several pieces meets at compile — the triangles'",
+      'outline is not one closed loop — with one mesh per piece, its uvs, weights, triangles',
+      'and deform keys renumbered, written beside the specs and never over them:',
+      '  rigc split --rig rig.json --motion motion.json --slot legs --out split/',
+      'Build what it wrote. See `rigc split --help`.',
+    ],
+  },
   {
     about: ['pose'],
     lines: () => [
@@ -1995,6 +2085,7 @@ export function usageText(docs: readonly CommandDoc[], checkout: string, rules:
     ...docs.flatMap((c) => c.usage.map((u) => `  ${u}`)),
     '',
     '  rigc <command> --help    that command\'s own flag table',
+    ...HELP_DOC.usage.map((u) => `  ${u}`),
     '  rigc --version           print the installed version (-v works too)',
   ];
   // Read only by the --profile paragraph, which only an entry running a command that takes --profile prints.
@@ -2748,6 +2839,46 @@ function commandNeedsRuntime(doc: CommandDoc, runs: readonly string[], args: rea
   );
 }
 
+/**
+ * `rigc help` documented as a command is (issue #1440): on the usage of both
+ * entries, and its own page for `rigc help --help` and `rigc help help`, as
+ * every listed command answers `--help`. Not a row of `COMMANDS`, because it
+ * has no body of its own: it is the dispatch reading another spelling of
+ * `--help` (`helpArgv`), on every entry alike.
+ */
+const HELP_DOC: CommandDoc = {
+  name: 'help',
+  usage: ['rigc help [<command>]    the same page as rigc [<command>] --help, and the same exit'],
+  flags: [],
+  runtime: false,
+  spineFormat: false,
+};
+
+/**
+ * `rigc help [<command>]` (issue #1440): the command line it stands for, which
+ * the dispatch then runs in its place — `rigc --help` for `help` alone,
+ * `rigc <command> --help` for a command the table documents — or `null` for
+ * `help`'s own page (`help --help`, `help help`). Rewritten rather than
+ * printed here, so the page and the exit code are the ones that spelling gets
+ * on this entry and cannot come apart from them: a command this entry does not
+ * run is refused as `<command> --help` is.
+ *
+ * ⚠️ A name the table does not document is refused by name with the nearest
+ * one, as a `UsageError` — printed and exited as an unknown command is, exit 2
+ * — and so is more than one name, rather than a guess at which was meant.
+ */
+export function helpArgv(rest: readonly string[]): string[] | null {
+  if (rest.length === 0) return ['--help'];
+  if (rest.length > 1) {
+    throw new UsageError(`help takes one command name and was given ${rest.length}: ${rest.join(' ')} — \`rigc help <command>\` is \`rigc <command> --help\``);
+  }
+  const [name] = rest;
+  if (name === HELP_DOC.name || name === '--help' || name === '-h') return null;
+  if (KNOWN_COMMANDS.includes(name)) return [name, '--help'];
+  const [nearest] = nearestNames(name, [...KNOWN_COMMANDS, HELP_DOC.name], 1);
+  throw new UsageError(`unknown command: ${name} — the nearest command is ${nearest} (\`rigc help ${nearest}\`)`);
+}
+
 /**
  * Run `argv` (`process.argv` without the runtime and the script) through
  * `entry`: the usage, `--version`, a command's `--help`, the command, and
@@ -2762,6 +2893,20 @@ export function runCli(entry: CliEntry, argv: readonly string[]): void {
     throw new Error(`internal: this entry runs [${known.join(', ')}] by the command table and registers [${registered.join(', ')}]`);
   }
   const USAGE = usageText(docs, entry.checkout, entry.profileRules);
+  if (argv[0] === 'help') {
+    let target: string[] | null;
+    try {
+      target = helpArgv(argv.slice(1));
+    } catch (err) {
+      refuse(err, 'help', USAGE, entry);
+    }
+    if (target === null) {
+      console.log(commandHelp(HELP_DOC.name, [HELP_DOC]));
+      process.exit(0);
+    }
+    runCli(entry, target);
+    return;
+  }
   const [command, ...rest] = argv;
   try {
     if (command === undefined) {
@@ -2878,6 +3023,12 @@ function refuse(err: unknown, command: string | undefined, USAGE: string, entry:
     console.error(`rigc repack: ${err.message}`);
     process.exit(err.status);
   }
+  // A split refused (issue #1414): a name the specs do not have (2 — the invocation has to change), or something
+  // the specs hold that the split cannot carry (1). The message names it, and the usage under it would bury that.
+  if (err instanceof SplitError) {
+    console.error(`rigc split: ${err.message}`);
+    process.exit(err.status);
+  }
   // A page or frame that is not a PNG rigc can read, from any command that
   // opens one (`render`, `check`, `preview`, …) — issue #732. The sentence is
   // the one reader's and already names the file, what it is and what rigc

package/src/compile.ts

@@ -99,6 +99,7 @@ import {
   type MeshGeometry,
   type MeshVertexWeight,
 } from './mesh.ts';
+import { meshPieces, shellWord } from './meshsplit.ts';
 import { Plate, readPlate } from '../tools/plate.ts';
 import {
   extractRegion,
@@ -120,7 +121,7 @@ import {
   type PhysicsPoseRule,
   type SlotColorChannel,
 } from './timelines.ts';
-import { evaluateDeformTransform } from './deformgen.ts';
+import { evaluateDeformTransform, type DeformSoftMask } from './deformgen.ts';
 import { evaluateTrackDerive, TRACK_DERIVE_PROJECTIONS, type TrackDeriveMember } from './trackgen.ts';
 import {
   computeExactFrameTransforms,
@@ -2875,6 +2876,9 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   // `skin/slot/attachment` -> per-vertex z, for the attachments that named a
   // depth map. Read at deform-key time; never emitted. See `AttachmentContext`.
   const attachmentDepths = new Map<string, number[]>();
+  // The same for a `soft` mask's per-vertex level, which a deform envelope's
+  // `mask` reads (issue #1413). Never emitted either.
+  const attachmentSoftMasks = new Map<string, DeformSoftMask>();
 
   for (const rigSlot of rig.slots) {
     const part = partBySlot.get(rigSlot.name);
@@ -3042,6 +3046,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
           skinName,
           imagesDir,
           depths: attachmentDepths,
+          softMasks: attachmentSoftMasks,
           slotNames: new Set(rig.slots.map((s) => s.name)),
           atlasRegions: atlasIn === null ? null : atlasIn.byName,
           links: pendingLinks,
@@ -3201,6 +3206,17 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
       if (!boneNames.has(spec.bone)) {
         throw new CompileError(`physics constraint "${name}" targets unknown bone "${spec.bone}"`);
       }
+      // A stop's copy and clamps sit right after the rig constraint that swings
+      // each link (`src/stop.ts`); this table is emitted after every rig
+      // constraint, so a swing here would run after the clamp meant to hold it.
+      const stop = (rig.stops ?? []).find((s) => s.links.includes(spec.bone));
+      if (stop !== undefined) {
+        throw new CompileError(
+          `physics constraint "${name}" drives "${spec.bone}", a link stop "${stop.chain}" holds, from the physics table — ` +
+            "the table is emitted after every rig constraint, past the stop's copy and clamp, which would read the link " +
+            'before this swings it; declare the constraint in the rig spec\'s "constraints"',
+        );
+      }
       // Every component and parameter the table states is held, 0 and the
       // parser's default included; which of them Spine leaves out is the
       // emitter's (`emitConstraint`). `components` is the report's list of the
@@ -3544,6 +3560,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
           {
             ...deformGeometryOf(attachment, at, transforms),
             depth: attachmentDepths.get(`${skinName}/${track.slot}/${track.attachment}`) ?? null,
+            soft: attachmentSoftMasks.get(`${skinName}/${track.slot}/${track.attachment}`) ?? null,
           },
           deformTransforms,
         );
@@ -4174,6 +4191,12 @@ interface AttachmentContext {
    * read by `evaluateDeformTransform` at key time and never emitted at all.
    */
   depths: Map<string, number[]>;
+  /**
+   * A `soft` mask's file and its sampled level per vertex, keyed like `depths`
+   * — what a deform envelope's `mask` reads at key time (issue #1413). Never
+   * emitted, for `depths`' reason.
+   */
+  softMasks: Map<string, DeformSoftMask>;
   /** Every slot the rig declares — a clipping attachment's `end` resolves here. */
   slotNames: Set<string>;
   /**
@@ -5477,6 +5500,7 @@ function authoredHullAndEdges(
   vertexCount: number,
   triangles: number[],
   where: string,
+  named: { skin: string; slot: string; placeholder: string },
 ): { hull: number; edges: number[] } {
   try {
     const outline = traceOutline(vertexCount, triangles);
@@ -5489,11 +5513,31 @@ function authoredHullAndEdges(
     checkHullOrder(outline, vertexCount);
     return { hull: outline.hull, edges: att.edges ?? meshEdges(vertexCount, triangles, outline.hull) };
   } catch (err) {
-    if (err instanceof MeshError) throw new CompileError(`${where}: ${err.message}`);
+    if (err instanceof MeshError) throw new CompileError(`${where}: ${err.message}${splitPointer(vertexCount, triangles, named)}`);
     throw err;
   }
 }
 
+/**
+ * The command that answers an outline refusal whose cause is pieces that share
+ * no vertex (issue #1414): one mesh is one outline, so the fix is one mesh per
+ * piece, and `rigc split` writes that proposal. Empty for every other cause —
+ * a pinch, a hole, a doubled triangle — whose fix is the triangles, and for a
+ * list the refusal is about because its indices are not vertices at all.
+ */
+function splitPointer(vertexCount: number, triangles: readonly number[], named: { skin: string; slot: string; placeholder: string }): string {
+  if (triangles.length % 3 !== 0 || triangles.some((v) => !Number.isInteger(v) || v < 0 || v >= vertexCount)) return '';
+  const count = meshPieces(vertexCount, triangles).pieces.length;
+  if (count < 2) return '';
+  // Each name one shell word (issue #1442): the command is copied into a shell, and a bare `left legs` is two arguments.
+  const skin = named.skin === 'default' ? '' : ` --skin ${shellWord(named.skin)}`;
+  return (
+    ` — the triangles are ${count} pieces that share no vertex, and one mesh is one outline: ` +
+    `\`rigc split --rig <rig> --motion <motion> --slot ${shellWord(named.slot)} --attachment ${shellWord(named.placeholder)}${skin} --out <dir>\` ` +
+    'writes one mesh per piece, its deform keys renumbered (AUTHORING §3.4.11)'
+  );
+}
+
 /**
  * The same two fields for geometry rigc built. The generators already put the
  * outline first and in order — a contour is all outline, a ring's outer ring
@@ -5577,7 +5621,7 @@ function buildRigMesh(
       vertices = { weighted: false, xy: raw.map(f32) };
     }
   }
-  const { hull, edges } = authoredHullAndEdges(att, uvCount / 2, att.triangles, where);
+  const { hull, edges } = authoredHullAndEdges(att, uvCount / 2, att.triangles, where, { skin: ctx.skinName, slot: ctx.slotName, placeholder });
   // `width`/`height` are the size of the image the mesh is drawn on. Stated
   // wins; otherwise the PNG the attachment names, already measured for the
   // atlas — the same `CompiledImage.width` a region reads, so a page with a
@@ -6292,7 +6336,7 @@ function softRegionWeights(
   grid: SheetGrid,
   where: string,
   ctx: AttachmentContext,
-): { weights: MeshVertexWeight[][]; bone: string; mask: string; digest: string; carried: number; ramped: number } {
+): { weights: MeshVertexWeight[][]; levels: number[]; bone: string; mask: string; digest: string; carried: number; ramped: number } {
   const { bone } = spec;
   if (typeof bone !== 'string' || bone.length === 0) {
     throw new CompileError(`${where}: the "soft" block has no "bone"; it is the bone the soft region is carried by`);
@@ -6316,8 +6360,10 @@ function softRegionWeights(
   const [toSheetX, toSheetY] = sheetRatio(grid);
   let carried = 0;
   let ramped = 0;
+  const levels: number[] = [];
   const weights = points.map(([x, y]) => {
     const w = sampleLevel(sheet, x * toSheetX, y * toSheetY) / 255;
+    levels.push(w);
     if (w >= 1) carried++;
     else if (w > 0) ramped++;
     if (w <= 0) return [{ bone: 'anchor', weight: 1 }] as MeshVertexWeight[];
@@ -6334,7 +6380,7 @@ function softRegionWeights(
         'check that the mask is painted where the mesh actually is, and that it is white where the art is soft.',
     );
   }
-  return { weights, bone, mask: spec.mask, digest: depthDigest(sheet), carried, ramped };
+  return { weights, levels, bone, mask: spec.mask, digest: depthDigest(sheet), carried, ramped };
 }
 
 /**
@@ -6461,6 +6507,7 @@ function buildGridAttachment(
   ctx.meshBones.add(ctx.anchorBone);
   if (bound) ctx.meshBones.add(bound.bone);
   if (depth !== undefined) ctx.depths.set(`${ctx.skinName}/${ctx.slotName}/${placeholder}`, depth.z);
+  if (bound) ctx.softMasks.set(`${ctx.skinName}/${ctx.slotName}/${placeholder}`, { mask: bound.mask, levels: bound.levels });
   ctx.meshes.push({
     slot: ctx.slotName,
     kind: 'grid',
@@ -8520,6 +8567,12 @@ export interface DeformGeometry {
    * caller, which is where the skin, slot and attachment names live.
    */
   depth: readonly number[] | null;
+  /**
+   * The attachment's `soft` mask and its level per vertex, when its generator
+   * named one — what a deform envelope's `mask` reads (issue #1413). Filled in
+   * by the caller, as `depth` is, and for the same reason.
+   */
+  soft: DeformSoftMask | null;
 }
 
 /**
@@ -8596,8 +8649,9 @@ export function deformGeometryOf(
       influenceBones: null,
       setupWhy: null,
       // Filled in by the caller; `deformGeometryOf` reads the attachment's
-      // record, and the depth is deliberately not in it.
+      // record, and the depth is deliberately not in it — nor the soft mask.
       depth: null,
+      soft: null,
     };
   }
   // Walk the bindings for the per-vertex influence counts. Their shape is
@@ -8631,7 +8685,7 @@ export function deformGeometryOf(
   // LOADED attachment, which is where the `/3*2` in the parser comes from.
   let influences = 0;
   for (const n of boneCounts) influences += n;
-  const common = { weighted, deformLength: influences * 2, vertexCount: boneCounts.length, boneCounts, depth: null };
+  const common = { weighted, deformLength: influences * 2, vertexCount: boneCounts.length, boneCounts, depth: null, soft: null };
   // -- one bind space, unchanged -------------------------------------------
   //
   // Every vertex a single influence of a single bone: the run IS that bone's
@@ -8874,7 +8928,14 @@ function compileDeformTrack(
             'yourself and start the run with "offset".',
         );
       }
-      const report = evaluateDeformTransform(key.transform, geometry.setup, onModelGrid, `${where} (t=${key.t})`, geometry.depth);
+      const report = evaluateDeformTransform(
+        key.transform,
+        geometry.setup,
+        onModelGrid,
+        `${where} (t=${key.t})`,
+        geometry.depth,
+        geometry.soft,
+      );
       if (report.offsets.length !== geometry.vertexCount * 2) {
         // Unreachable while `setup` is one pair per vertex, which is the whole
         // reason both are derived from the same walk. Stated rather than

package/src/core/entry.ts

@@ -20,7 +20,11 @@
  * `openTracks`, issue #1336; `physicsClockStep` and `PHYSICS_CLOCK_LEAD`,
  * the clock a live track's `clock` option takes, issue #1396;
  * `PhysicsEnvironment`, what a live track's `setEnvironment` takes, issue
- * #1416).
+ * #1416; `bezierPolyline` and `BEZIER_PIECES`, the polyline the poser draws
+ * a Bézier segment as, so that a fitter holds its tolerance to the poser's
+ * own evaluation rather than to a mirror of it, issue #1417 — re-exported,
+ * never copied, because a copy is the drift the request exists to remove;
+ * `CA12` holds the identity).
  * The list is `scripts/install_smoke.ts`'s `OBSERVED_SYMBOLS` rows for
  * `./core`, and a symbol added here and not there is not promised.
  */
@@ -39,4 +43,5 @@ export type { DrawnRegion, UvPage, UvRegion, UvSource } from './uvs.ts';
 export { clipThrough, clipShapeOf, convexWhy, REGION_UVS, REGION_TRIANGLES } from './clipping.ts';
 export type { ClipShape, ClipResult } from './clipping.ts';
 export { eventsFired } from './events.ts';
+export { bezierPolyline, BEZIER_PIECES } from './animation.ts';
 export type { ModelPage, ModelPageRegion } from '../model.ts';