rig-parts 1.0.0 → 1.1.1

package/README.md

@@ -1,6 +1,6 @@
 # rig-parts
 
-**AI-authored Spine 2D character rigs from one anime painting, verified before they
+**AI-authored 2D character rigs from one anime painting, verified before they
 are written.** rig-parts takes a single character painting and the layers
 [See-through](https://github.com/shitagaki-lab/see-through) decomposed it into,
 merges them into measured rig-space parts, authors weighted meshes, bone chains
@@ -15,7 +15,7 @@ input is silent.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/firejune/rig-parts/main/assets/demo-source.png" alt="The demo painting: a generated full-body character in a white and pink frilled dress with long pink twin tails, standing with her hands clasped" height="420" />
-  <img src="https://raw.githubusercontent.com/firejune/rig-parts/main/assets/demo-idle.png" alt="The same character as a Spine rig, breathing, blinking once and swaying her hair, sleeves and skirt in a four-second loop" height="420" />
+  <img src="https://raw.githubusercontent.com/firejune/rig-parts/main/assets/demo-idle.png" alt="The same character rigged, breathing, blinking once and swaying her hair, sleeves and skirt in a four-second loop" height="420" />
 </p>
 
 <p align="center">
@@ -150,7 +150,7 @@ atlas written by anything else would have no oracle behind it.
 | --- | --- | --- |
 | painting + See-through layers → parts and specs | **rig-parts** | the merge of two runs, the measurements, the rig spec and motion spec |
 | specs → Spine skeleton data | **[rig-c](https://github.com/firejune/rigc)** | compile, the gate (rigc's own validator in an install; the round trip through `spine-core` where the runtime is beside it, as in this repository's CI), the named assertions, the packer, the renderer |
-| skeleton data → a page | **[spine-html](https://github.com/firejune/spine-html)**, a sibling project | a DOM renderer; rigc's `spine-html` profile is its policy, and every build here is gated under that profile as well as under `spine` |
+| skeleton data → a page | **[rig-play](https://github.com/firejune/rig-play)** (formerly spine-html), a sibling project | a DOM renderer; rigc's `spine-html` profile is its policy, and every build here is gated under that profile as well as under `spine` |
 
 rig-parts never writes Spine data itself. Everything on disk under `check/build/`
 was written by rig-c after its own gate passed.

package/docs/AUTHORING.md

@@ -83,7 +83,7 @@ read by no CPU stage).
 | `assemble.extend_below_crop` | assemble | **proposed** with the plan: `{part, run, tag}` — a head-run part that reaches the bottom of the head crop is continued from a full-run layer, whole connected components |
 | `assemble.patches` | assemble; `meshes`/`regions` keys may name them too | **authored**, optional: `[{name, box, alpha, draw}]` — an extra part cut from the **painting** itself, for figure no See-through layer holds (a hem both runs dropped). `box` is `[x0, y0, x1, y1]` in **rig** pixels, `x1`/`y1` exclusive — the space of `parts.json` and `recomposite_rig.png`, where the hole is found; `alpha` is `"silhouette"` (the painting's figure silhouette inside the box, the one `--seam silhouette` uses) or `"box"` (the whole box); `draw` is `"back"`, `"front"` or `{"before": "<plan part>"}`. A patch is always a region: its bone is `regions.<name>`, in the one place every region's bone lives, and a `meshes` entry for it is refused. See §5 for how to place one |
 | `bones` | rig; `propose --from-config` | **proposed** by `propose`, then corrected. A single bone `{name, parent, at, tip?}` or a chain `{chain, parent, points, tip}` whose links are named `<chain>0 … <chain>n`. Parents come before children. In `rig.json` each link is **turned along its chain** — `rotation` is the direction from its origin to the next link's (the last link's to `tip`) and `length` that distance (issue #73), so a physics constraint added downstream finds a lever; under `--idle-keys ctl` the link's `<link>_ctl` carries the turn and the length and the link sits at local rotation 0 beneath it. A single bone is never turned; one whose parent is a link is turned back upright |
-| `meshes.<part>` | rig | **proposed**, then corrected. Exactly one of `grid` (the lattice: cell size, px — what `propose` writes), `contour` (the outline mode, authored; the next row and "A contour mesh" below) or `auto` (the automatic mode, authored; "An automatic mesh" below) — two, or none, is `CONFIG_MESH_MODE`. In every mode: `r` (added to every distance before weighting: `w = 1/(d + r)²`), `segments` (a chain name, a bone name with a `tip`, or `[bone, [x0,y0], [x1,y1]]`). The segment list is the one authored decision about a layer: which bones may pull it. The slot's bone is the first segment's |
+| `meshes.<part>` | rig | **proposed**, then corrected. Exactly one of `grid` (the lattice: cell size, px — what `propose` writes), `contour` (the outline mode, authored; the next row and "A contour mesh" below) or `auto` (the automatic mode, authored; "An automatic mesh" below) — two, or none, is `CONFIG_MESH_MODE`. In every mode: `r` (added to every distance before weighting: `w = 1/(d + r)²`), `segments` (a chain name, a bone name with a `tip`, or `[bone, [x0,y0], [x1,y1]]`), and, **authored**, optional, `exponent` (issue #161): a number above 0 that replaces the 2 in that rule, `w = 1/(d + r)^exponent` — a larger one hands each vertex more fully to its nearest bone; absent is 2 and changes no byte, a value that is not a number above 0 is `CONFIG_FIELD_TYPE` at `meshes.<part>.exponent`, and a declared one is echoed as `exponent` in the mesh's `mesh_report.json` row; the exponent is the distance rule's, so declared beside `rule: "heat"` it is refused (`CONFIG_FIELD_TYPE` at `meshes.<part>.exponent`). The segment list is the one authored decision about a layer: which bones may pull it. The slot's bone is the first segment's. Optional `rule` (issue #161): `"distance"` — the rule above, and what an absent `rule` means (every byte is the same) — or `"heat"`, bone heat over the part's own silhouette, in every mode: the lattice's art (alpha above 8) with holes filled, or for `contour` and `auto` the silhouette their outline is traced from (that mode's art — alpha above 8 for `contour`, alpha 1 and above for `auto` — less any island a declared `stray` left out, holes filled, grown by its `margin`); each bound bone's sources are the silhouette pixels whose centre lies within 0.75 px of its segment (a pixel two bones reach goes to the nearer, a tie to the first listed), held at 1 for that bone and 0 for the others; the field is solved by row-major Gauss–Seidel over-relaxation to a sweep change under 1e-7 within 20000 sweeps; a vertex reads the nearest silhouette pixel and takes the same cap and floor (and `regions`) as the distance rule; `r` is not read. The mesh's `mesh_report.json` row gains `heat` (the constants, each bone's sources and sweeps, the residual). Any other value is `CONFIG_FIELD_TYPE`; a bound bone with no source pixel is `RIG_HEAT_BONE_SOURCE`, an island no bone has a source in `RIG_HEAT_ISLAND_SOURCE`, a solve past its sweep bound `RIG_HEAT_CONVERGED` — none is weighted 0 |
 | `meshes.<part>.contour` | rig | **authored**, optional (issue #84): `{tolerance, margin, spacing, budget?, stray?, regions?}`. `tolerance` — rig-c's Douglas–Peucker tolerance on the traced outline, px, 0 or more; `margin` — how far the silhouette grows before it is traced, px: 0, or 1 or more (a pixel joins when its centre lies within `margin` of an art pixel's centre; a value above 0 and below 1 adds nothing and is refused, `CONFIG_FIELD_TYPE`); `spacing` — the background interior spacing, px, above 0; `budget` — the most vertices the mesh may have (refused above it, nothing thinned); `stray` — the largest island, in art pixels, that may be left out of the mesh (absent: none is); `regions` — local deformation regions, each `{name, shape, bone, spacing, band}` with `shape` `"circle"` (`cx, cy, r`) or `"polygon"` (`points`, 3 or more): `bone` is the region's control bone (any bone `bones` declares), `spacing` the interior spacing inside the region and its band, `band` the width the bone's weight falls across. Every length and position is **rig px**, like every other in the config; the part image is the rig less `(x − 4, y − 4)` (its box less the pad), a translation, so a length is the same number in both. A region's `cx`, `cy`, `r`, `band` and `points` are multiples of 1/256 px (`CONFIG_FIELD_TYPE` otherwise); region names are unique per mesh (`CONFIG_REGION_NAME_UNIQUE`). The alpha threshold is not a field: art is alpha above 8, the lattice's and `check`'s |
 | `regions.<part>` | rig | **proposed**: the bone a rigid part rides. Every plan part is exactly one of a mesh or a region (`CONFIG_PART_ATTACHED`) |
 | `motion.duration` | rig; check (the loop is measured at this time) | proposed as 4 s; a whole number of 1/12 s ticks, because `check` renders at 12 fps |

package/docs/STABILITY.md

@@ -111,7 +111,7 @@ part name, `[i]` an entry of a list):
 - **assemble.patches[i].draw**, when an object — required: `before`
 - **bones[i]**, a single bone — required: `name`, `parent`, `at`; optional: `tip`
 - **bones[i]**, a chain — required: `chain`, `parent`, `points`, `tip`
-- **meshes.<part>** — exactly one of `grid`, `contour`, `auto`; required in every mode: `r`, `segments`
+- **meshes.<part>** — exactly one of `grid`, `contour`, `auto`; required in every mode: `r`, `segments`; optional in every mode: `exponent`, `rule`
 - **meshes.<part>.contour** — required: `tolerance`, `margin`, `spacing`; optional: `budget`, `stray`, `regions`
 - **meshes.<part>.contour.regions[i]** — required: `name`, `shape`, `bone`, `spacing`, `band`, and `cx`, `cy`, `r` for a circle or `points` for a polygon
 - **meshes.<part>.auto** — required: `source`, `sourceBounds`, `targets`, `influences`, `budget`, `minArtSamples`, `motion`; optional: `protect`, `regions`, and the three Stage B opt-ins `boundaryRuns`, `retriangulate`, `removalOrder`
@@ -151,7 +151,7 @@ every number) are AUTHORING §3's tables, and the loader refuses any other by na
 | --- | --- | --- |
 | `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from`, the box `x`, `y`, `w`, `h` (rig px), the pixel counts `src/parts.ts` documents (`opaque_px`, `visible_px`, `occluded_px`, `projected_core_px`, `source_px_taken`, `visible_not_projected_px`, `refused_drift_px`, `merged_px`, `seam_override_px`, and `fringe_pushed_back` when not empty); `rig_size`, `scale_rig_per_source`, `ghost_px`, `recomposite` |
 | `rig/rig.json`, `rig/motion.json`, `rig/images/` | `rig`, `build`, `compose` | rig-c's rig spec and motion spec, `spec` `rigc-rig/1` and `rigc-motion/1`: the format is rig-c's, and this package writes only what rig-c's parser accepts |
-| `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones`, `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); `mode` "contour" with `params`, `contour`, `regions`; or `mode` "auto" with `settings`, `source`, `result`, `residuals`, `worst_residual`, `worst_region`, `motion_amplitude`, `termination`, `weights`, `regions`, `deformation`, `quality_report` (rig-c's `mesh-quality-report/1` document whole), `motion_report`, and, only when they apply, `stray_cleared` (after `source`, when `source.stray` is declared), `skinning_residual` and `replay` (`AutoMeshReport` in `src/rig.ts`) |
+| `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones`, `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); `mode` "contour" with `params`, `contour`, `regions`; or `mode` "auto" with `settings`, `source`, `result`, `residuals`, `worst_residual`, `worst_region`, `motion_amplitude`, `termination`, `weights`, `regions`, `deformation`, `quality_report` (rig-c's `mesh-quality-report/1` document whole), `motion_report`, and, only when they apply, `stray_cleared` (after `source`, when `source.stray` is declared), `skinning_residual` and `replay` (`AutoMeshReport` in `src/rig.ts`); in every mode, `exponent` when the mesh declares one (after `grid`, or after `mode`) |
 | `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode`, `loop_max_diff`, the seam figures), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `RECOMPOSITE_HOLES`, `SETUP_POSE_VS_SOURCE`, `skipped`, a `requirements` block under `--requirements`, and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes |
 | `proposal.json`, `render/landmarks*.png` | `propose` | the config's four rig sections and `notes` |
 | `basis.json` | `propose` | spec `spine-parts-basis/1` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rig-parts",
-  "version": "1.0.0",
-  "description": "AI-authored Spine 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
+  "version": "1.1.1",
+  "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {
     "rig-parts": "./bin/rig-parts.cjs",

package/skills/rig-parts/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rig-parts
-description: Turn one anime character painting and its See-through layer decomposition into a verified Spine 4.3 rig — measured parts, weighted meshes, bone chains and a looping idle — with rig-parts, which gates everything through rig-c before it is written. Use for a request to rig or animate a single character painting in Spine, to run or read rig-parts layers, sheet, assemble, propose, rig, check, loop or build, or to write or fix a rig-parts config.json. Not for cutting art into parts by hand, for authoring a rig from loose PNGs (that is the rigc skill), for expressions or lip-sync, or for running See-through itself.
+description: Turn one anime character painting and its See-through layer decomposition into a verified 2D character rig (Spine 4.3 skeleton data) — measured parts, weighted meshes, bone chains and a looping idle — with rig-parts, which gates everything through rig-c before it is written. Use for a request to rig or animate a single character painting, to run or read rig-parts layers, sheet, assemble, propose, rig, check, loop or build, or to write or fix a rig-parts config.json. Not for cutting art into parts by hand, for authoring a rig from loose PNGs (that is the rigc skill), for expressions or lip-sync, or for running See-through itself.
 license: MIT
 compatibility: Requires Bun 1.2 or later. The tool is the npm package rig-parts (bunx rig-parts, or bun add -d rig-parts); rig-c is installed with it. See-through is run separately.
 ---

package/src/automesh.ts

@@ -85,11 +85,12 @@ import {
 } from 'rig-c/mesh';
 import { type AutoRegionSpec, type AutoSpec, type AutoWeightRegionSpec, type Point, weightsABone } from './config.ts';
 import { type ContourMesh, contourMesh, type ContourReport, GRID } from './contour.ts';
+import { type HeatField, heatInfluences } from './heat.ts';
 import type { Problem } from './errors.ts';
 import { type LocalInfluence, localInfluences, type RegionOverlap } from './localweights.ts';
 import { ART_ALPHA } from './mesh.ts';
 import { pyRound } from './round.ts';
-import type { Influence, Segment } from './weights.ts';
+import { DISTANCE_EXPONENT, type Influence, type Segment } from './weights.ts';
 
 /** The final threshold of the automatic mode: art is alpha 1 and above (P4). `contourMesh` reads "above", so it is handed one less. */
 export const AUTO_THRESHOLD = 1;
@@ -185,7 +186,9 @@ export function autoSource(part: string, mask: AlphaMask, spec: AutoSpec): Conto
  * that weight a bone are read (issue #155): a density-only region gives no vertex a `g`, so a source vertex
  * inside it is weighted as one no region reaches, it can never be one of an overlap's two, and the weights are
  * the same numbers the part has with the region left out. Region indices in the result (`local[].region`, the
- * overlap's `first` and `second`) are indices into `spec.regions`, every form counted.
+ * overlap's `first` and `second`) are indices into `spec.regions`, every form counted. `exponent` is the mesh's
+ * distance-rule exponent (issue #161), which the rig stage always passes. With `heat` (issue #161,
+ * `rule: "heat"`), each vertex's segment shares are bone heat's at its pixel, under the author's influence limits.
  */
 export function sourceWeights(
   vertices: ReadonlyArray<readonly [number, number]>,
@@ -194,6 +197,8 @@ export function sourceWeights(
   segs: readonly Segment[],
   r: number,
   spec: AutoSpec,
+  exponent: number = DISTANCE_EXPONENT,
+  heat: HeatField | null = null,
 ): { weights: Influence[][]; local: LocalInfluence[] } | { overlap: RegionOverlap; vertex: number; at: Point } {
   const all = spec.regions ?? [];
   const index: number[] = [];
@@ -207,7 +212,7 @@ export function sourceWeights(
   const local: LocalInfluence[] = [];
   for (let v = 0; v < vertices.length; v++) {
     const at: Point = [vertices[v][0] + ox, vertices[v][1] + oy];
-    const li = localInfluences(at, segs, r, regions, spec.influences);
+    const li = localInfluences(at, segs, r, regions, spec.influences, exponent, heat === null ? undefined : heatInfluences(heat, [vertices[v][0], vertices[v][1]], spec.influences));
     if ('first' in li) return { overlap: { ...li, first: index[li.first], second: index[li.second] }, vertex: v, at };
     weights.push(li.influences.map((e) => ({ bone: e.bone, weight: e.weight })));
     local.push(li.region < 0 ? li : { ...li, region: index[li.region] });

package/src/config.ts

@@ -185,16 +185,33 @@ export type Segment = string | [string, Point, Point];
  */
 export type MeshSpec = LatticeMeshSpec | ContourMeshSpec | AutoMeshSpec;
 
+/**
+ * `meshes.<part>.rule` (issue #161): how a mesh's vertices are weighted. `"distance"` is `influences()`
+ * (`src/weights.ts`), and what an absent field means; `"heat"` is bone heat over the part's silhouette
+ * (`src/heat.ts`), in every mode. Nothing else is a rule.
+ */
+export type WeightRule = 'distance' | 'heat';
+
+export const WEIGHT_RULES: readonly WeightRule[] = ['distance', 'heat'];
+
 export interface LatticeMeshSpec {
   grid: number;
   r: number;
   segments: Segment[];
+  /** The distance rule's exponent, `w = 1/(d + r)^exponent`, above 0 (issue #161); absent is 2, the rule as it always was. */
+  exponent?: number;
+  /** Absent: `"distance"`. */
+  rule?: WeightRule;
 }
 
 export interface ContourMeshSpec {
   contour: ContourSpec;
   r: number;
   segments: Segment[];
+  /** The distance rule's exponent, `w = 1/(d + r)^exponent`, above 0 (issue #161); absent is 2, the rule as it always was. */
+  exponent?: number;
+  /** Absent: `"distance"`. */
+  rule?: WeightRule;
 }
 
 /**
@@ -246,6 +263,10 @@ export interface AutoMeshSpec {
   auto: AutoSpec;
   r: number;
   segments: Segment[];
+  /** The distance rule's exponent, `w = 1/(d + r)^exponent`, above 0 (issue #161); absent is 2, the rule as it always was. */
+  exponent?: number;
+  /** Absent: `"distance"`. */
+  rule?: WeightRule;
 }
 
 export interface AutoSpec {
@@ -1151,7 +1172,7 @@ function checkMeshes(c: Check, v: Json, bones: Set<string>, chains: Map<string,
     const at = `config.meshes.${part}`;
     // The known keys keep their old order (grid, r, segments) with contour after them, and `r` and `segments` are
     // required in the place and words the object check uses, so a lattice mesh's refusals read as they did.
-    const m = c.object(at, spec, [], ['grid', 'r', 'segments', 'contour', 'auto']);
+    const m = c.object(at, spec, [], ['grid', 'r', 'segments', 'contour', 'auto', 'exponent', 'rule']);
     if (m === null) continue;
     for (const key of ['r', 'segments']) if (!(key in m)) c.fail('CONFIG_FIELD_PRESENT', `${at}.${key}`, 'is absent and required');
     const modes = ['grid', 'contour', 'auto'].filter((k) => k in m);
@@ -1166,6 +1187,15 @@ function checkMeshes(c: Check, v: Json, bones: Set<string>, chains: Map<string,
     if ('contour' in m) checkContour(c, `${at}.contour`, m.contour, bones);
     if ('auto' in m) checkAuto(c, `${at}.auto`, m.auto, bones);
     if ('r' in m) c.number(`${at}.r`, m.r, 'non-negative');
+    // issue #161: the distance rule's exponent, in every mode; absent is 2 (src/weights.ts), nothing is filled in here.
+    if ('exponent' in m) c.number(`${at}.exponent`, m.exponent, 'positive');
+    if ('rule' in m && !WEIGHT_RULES.includes(m.rule as WeightRule)) {
+      c.fail('CONFIG_FIELD_TYPE', `${at}.rule`, `is ${show(m.rule)}; "distance" (the distance rule, what an absent rule means) or "heat" (bone heat over the part's silhouette) is required`);
+    }
+    // issue #161: the exponent is the distance rule's; bone heat has none, so declaring both is refused rather than ignored.
+    if ('exponent' in m && m.rule === 'heat') {
+      c.fail('CONFIG_FIELD_TYPE', `${at}.exponent`, `is ${show(m.exponent)} on a mesh that declares rule "heat"; the exponent belongs to the distance rule (w = 1/(d + r)^exponent) and bone heat reads none — remove exponent, or declare rule "distance"`);
+    }
     if ('segments' in m && c.array(`${at}.segments`, m.segments, true)) {
       (m.segments as Json[]).forEach((s, i) => {
         const sp = `${at}.segments[${i}]`;

package/src/heat.ts

@@ -0,0 +1,313 @@
+/**
+ * Bone heat: a mesh's weights as the heat equilibrium over the part's own
+ * silhouette (issue #161, the reduced shape). An author opts a mesh in with
+ * `meshes.<part>.rule: "heat"`; absent, or `"distance"`, the mesh is weighted
+ * by `influences()` (`src/weights.ts`) and nothing here runs.
+ *
+ * ## The rule, as a definition
+ *
+ * 1. **The domain** is a set of the part image's pixels, the silhouette the
+ *    mesh's mode reads (the rig stage hands it in): the lattice's art — alpha
+ *    above 8 — with its holes filled ({@link latticeSilhouette}); for the
+ *    contour and the automatic modes, the silhouette the outline was traced
+ *    from, which is the kept art with its holes filled and grown by the
+ *    declared margin ({@link tracedSilhouette}, the same calls
+ *    `contourOutline` makes). Neighbours are 4-connected; a neighbour off the
+ *    silhouette is no neighbour, so no heat crosses the boundary.
+ * 2. **Sources.** A silhouette pixel whose centre lies within
+ *    {@link HEAT_SOURCE_BAND} px of one of a bound bone's segments is that
+ *    bone's source; a pixel two bones reach goes to the bone whose segment is
+ *    nearer its centre, a tie to the bone listed first among the segments.
+ *    The band is above √2 / 2, so every pixel a segment passes through is
+ *    reached. Per bone, the field is 1 on its own sources, 0 on every other
+ *    bone's, and the discrete Laplace equation (each free pixel the mean of
+ *    its neighbours) everywhere else.
+ * 3. **The solve** is successive over-relaxation — Gauss–Seidel, sweeping the
+ *    free pixels in row-major order, each update over-relaxed by
+ *    `omega = 2 / (1 + π / L)`, L the image's longer side (the small-angle
+ *    form of the optimum `2 / (1 + sin(π / L))`: `sin`'s last bit is the
+ *    engine's, a division is IEEE's) — from 0, until the largest change in
+ *    one sweep is under {@link HEAT_TOLERANCE}. A bone that has not got there
+ *    in {@link HEAT_MAX_ITERATIONS} sweeps is refused (`RIG_HEAT_CONVERGED`),
+ *    never written half-solved. Float64 throughout; distances are
+ *    `segmentDistance`'s, not `Math.hypot`.
+ * 4. **A vertex** reads every bone's field at the silhouette pixel whose
+ *    centre is nearest it (a tie to the first in raster order) — a vertex on a
+ *    pixel corner, as every lattice vertex is, touches four — keeps the bones
+ *    whose value there is above 0, and takes the cap and the floor the distance
+ *    rule takes (`capAndFloor`, the mesh's `InfluenceLimits`).
+ *
+ * ## What is refused rather than weighted 0
+ *
+ * - `RIG_HEAT_BONE_SOURCE`: a bound bone that holds no source pixel — a
+ *   zero-length control bone off the art, a segment wholly off the
+ *   silhouette, or one whose every reached pixel is nearer another bone. A
+ *   bone named in `segments` is a bone the author said may pull the layer;
+ *   giving it 0 everywhere would be a silent answer to a question the
+ *   config asked.
+ * - `RIG_HEAT_ISLAND_SOURCE`: a 4-connected island of the silhouette that no
+ *   bone has a source in. With no fixed temperature the equation has no
+ *   answer there; nothing nearest is borrowed.
+ * - `RIG_HEAT_CONVERGED`: above.
+ *
+ * Two runs on the same input write the same bytes: the claims, the sweep
+ * order and the arithmetic are fixed, and nothing reads a clock.
+ */
+import type { Point } from './config.ts';
+import { artMask, growSilhouette } from './contour.ts';
+import type { Problem } from './errors.ts';
+import { connectedComponents, fillHoles, type Mask } from './raster/index.ts';
+import { capAndFloor, type Influence, type InfluenceLimits, type Segment, segmentDistance } from './weights.ts';
+
+/** The solve stops when the largest change in one sweep is under this — Stage A's figure (`tools/weight_rule_survey.ts`). */
+export const HEAT_TOLERANCE = 1e-7;
+
+/** The most sweeps one bone's field may take; past it the mesh is refused (`RIG_HEAT_CONVERGED`). Stage A's figure. */
+export const HEAT_MAX_ITERATIONS = 20000;
+
+/** A pixel is a bone's source when its centre lies within this of the bone's segment, px: above √2 / 2, so every pixel a segment crosses is reached. Stage A's figure. */
+export const HEAT_SOURCE_BAND = 0.75;
+
+/** The sweep, in the words the report row echoes. */
+export const HEAT_SWEEP = 'gauss-seidel, row-major, over-relaxed';
+
+export interface HeatLimits {
+  tolerance: number;
+  maxIterations: number;
+}
+
+export const HEAT_LIMITS: HeatLimits = { tolerance: HEAT_TOLERANCE, maxIterations: HEAT_MAX_ITERATIONS };
+
+/** The lattice's silhouette: its art (alpha above 8, the mask `latticeMesh` reads) with holes filled, as the lattice fills them. */
+export function latticeSilhouette(art: Mask): Mask {
+  return fillHoles(art);
+}
+
+/** The contour and automatic modes' silhouette: the traced mask's art at `threshold`, holes filled, grown by `margin` — the silhouette `contourOutline` traces. */
+export function tracedSilhouette(mask: { width: number; height: number; alpha: Uint8Array }, threshold: number, margin: number): Mask {
+  return growSilhouette(fillHoles(artMask(mask, threshold)), margin).mask;
+}
+
+/** One mesh's solved fields. */
+export interface HeatField {
+  silhouette: Mask;
+  /** Bound bones, in first-appearance order among the segments. */
+  bones: string[];
+  /** One field per bone, row-major over the image; 0 off the silhouette. */
+  fields: Float64Array[];
+  /** Per bone: source pixels held, and sweeps taken. */
+  sources: number[];
+  iterations: number[];
+  omega: number;
+  /** The largest |value − mean of its neighbours| over the free pixels, over every bone, after the solve. */
+  residual: number;
+  islands: number;
+}
+
+/** The row a heat mesh adds to its `mesh_report.json` entry, so the declaration and the solve it ran are read back. */
+export interface HeatRow {
+  rule: 'heat';
+  tolerance: number;
+  max_iterations: number;
+  source_band: number;
+  sweep: string;
+  omega: number;
+  silhouette_pixels: number;
+  islands: number;
+  bones: Array<{ bone: string; sources: number; iterations: number }>;
+  residual: number;
+}
+
+const fmt = (v: number): string => String(Math.round(v * 1000) / 1000);
+
+/**
+ * Solve bone heat over `sil` (part-image pixels) for `segs` (rig px; the image is the rig less `(ox, oy)`).
+ * `object` names the mesh in every refusal. Every problem found is returned at once.
+ */
+export function boneHeat(object: string, sil: Mask, segs: readonly Segment[], ox: number, oy: number, limits: HeatLimits = HEAT_LIMITS): HeatField | Problem[] {
+  const { width: w, height: h, data } = sil;
+  const n = w * h;
+  const bones: string[] = [];
+  for (const s of segs) if (!bones.includes(s.bone)) bones.push(s.bone);
+  const K = bones.length;
+  const local = segs.map((s) => ({ k: bones.indexOf(s.bone), a: [s.a[0] - ox, s.a[1] - oy] as Point, b: [s.b[0] - ox, s.b[1] - oy] as Point }));
+  const owner = new Int32Array(n).fill(-1);
+  const ownD = new Float64Array(n).fill(Infinity);
+  const reached = new Array<number>(K).fill(0);
+  let silPixels = 0;
+  for (let i = 0; i < n; i++) {
+    if (data[i] !== 1) continue;
+    silPixels++;
+    const p: Point = [(i % w) + 0.5, Math.floor(i / w) + 0.5];
+    const near = new Float64Array(K).fill(Infinity);
+    for (const s of local) {
+      const d = segmentDistance(p, s.a, s.b);
+      if (d < near[s.k]) near[s.k] = d;
+    }
+    for (let k = 0; k < K; k++) {
+      if (near[k] > HEAT_SOURCE_BAND) continue;
+      reached[k]++;
+      if (near[k] < ownD[i]) {
+        owner[i] = k;
+        ownD[i] = near[k];
+      }
+    }
+  }
+  const sources = new Array<number>(K).fill(0);
+  for (let i = 0; i < n; i++) if (owner[i] >= 0) sources[owner[i]]++;
+  const problems: Problem[] = [];
+  bones.forEach((bone, k) => {
+    if (sources[k] > 0) return;
+    const where = local
+      .filter((s) => s.k === k)
+      .map((s) => `(${fmt(s.a[0] + ox)}, ${fmt(s.a[1] + oy)})->(${fmt(s.b[0] + ox)}, ${fmt(s.b[1] + oy)})`)
+      .join(', ');
+    const why = reached[k] === 0 ? 'reaches no pixel of the silhouette' : `reaches ${reached[k]} silhouette pixel(s), every one nearer another bound bone's segment`;
+    problems.push({
+      code: 'RIG_HEAT_BONE_SOURCE',
+      object,
+      detail: `bone "${bone}" — its segment ${where} (rig px) ${why}, so it holds no source pixel; under rule "heat" every bound bone needs at least one: a silhouette pixel (${silPixels} px) whose centre lies within ${HEAT_SOURCE_BAND} px of the segment and nearer it than any other bound bone's. A bone with no source is not weighted 0 — move its segment onto the art, or take the bone out of segments`,
+    });
+  });
+  const cc = connectedComponents(sil, 4);
+  const sourced = new Uint8Array(cc.count);
+  for (let i = 0; i < n; i++) if (owner[i] >= 0) sourced[cc.labels[i]] = 1;
+  for (let c = 1; c < cc.count; c++) {
+    if (sourced[c]) continue;
+    const st = cc.stats[c];
+    problems.push({
+      code: 'RIG_HEAT_ISLAND_SOURCE',
+      object,
+      detail: `the silhouette's 4-connected island of ${st.area} px at rig (${st.left + ox}, ${st.top + oy}) holds no bound bone's source pixel, so the heat equation has no fixed temperature there and no answer; under rule "heat" every island needs a segment within ${HEAT_SOURCE_BAND} px of one of its pixel centres — nothing is borrowed from the nearest island`,
+    });
+  }
+  if (problems.length > 0) return problems;
+
+  // The free pixels in raster order, each with its 4-neighbours on the silhouette (left, right, up, down: the order the sum is taken in).
+  const free: number[] = [];
+  const start: number[] = [0];
+  const nbr: number[] = [];
+  for (let i = 0; i < n; i++) {
+    if (data[i] !== 1 || owner[i] >= 0) continue;
+    const x = i % w;
+    const y = Math.floor(i / w);
+    if (x > 0 && data[i - 1] === 1) nbr.push(i - 1);
+    if (x < w - 1 && data[i + 1] === 1) nbr.push(i + 1);
+    if (y > 0 && data[i - w] === 1) nbr.push(i - w);
+    if (y < h - 1 && data[i + w] === 1) nbr.push(i + w);
+    free.push(i);
+    start.push(nbr.length);
+  }
+  const F = Int32Array.from(free);
+  const S = Int32Array.from(start);
+  const N = Int32Array.from(nbr);
+  const omega = 2 / (1 + Math.PI / Math.max(w, h));
+  const fields: Float64Array[] = [];
+  const iterations: number[] = [];
+  let residual = 0;
+  for (let k = 0; k < K; k++) {
+    const x = new Float64Array(n);
+    for (let i = 0; i < n; i++) if (owner[i] === k) x[i] = 1;
+    let it = 0;
+    let done = F.length === 0;
+    let last = 0;
+    while (!done && it < limits.maxIterations) {
+      it++;
+      let maxD = 0;
+      for (let j = 0; j < F.length; j++) {
+        const i = F[j];
+        const a = S[j];
+        const b = S[j + 1];
+        let s = 0;
+        for (let q = a; q < b; q++) s += x[N[q]];
+        const nx = x[i] + omega * (s / (b - a) - x[i]);
+        const d = Math.abs(nx - x[i]);
+        if (d > maxD) maxD = d;
+        x[i] = nx;
+      }
+      last = maxD;
+      if (maxD < limits.tolerance) done = true;
+    }
+    if (!done) {
+      problems.push({
+        code: 'RIG_HEAT_CONVERGED',
+        object,
+        detail: `bone "${bones[k]}"'s field still changed by ${last} in its sweep ${it}; the solve stops at a change under ${limits.tolerance} within ${limits.maxIterations} sweeps (${F.length} free pixel(s), omega ${omega}). Nothing half-solved is written — a smaller part, or the distance rule, is what remains`,
+      });
+    }
+    for (let j = 0; j < F.length; j++) {
+      let s = 0;
+      for (let q = S[j]; q < S[j + 1]; q++) s += x[N[q]];
+      const r = Math.abs(x[F[j]] - s / (S[j + 1] - S[j]));
+      if (r > residual) residual = r;
+    }
+    fields.push(x);
+    iterations.push(it);
+  }
+  if (problems.length > 0) return problems;
+  return { silhouette: sil, bones, fields, sources, iterations, omega, residual, islands: cc.count - 1 };
+}
+
+/** The silhouette pixel whose centre is nearest `p` (part-image px), a tie to the first in raster order; -1 on an empty silhouette. */
+export function nearestSilhouettePixel(sil: Mask, p: Point): number {
+  const { width: w, height: h, data } = sil;
+  const fx = Math.floor(p[0]);
+  const fy = Math.floor(p[1]);
+  let best = -1;
+  let bd = Infinity;
+  // A pixel in the ring at Chebyshev distance k from (fx, fy) lies at least k − 0.5 from p, so once the best is
+  // strictly nearer than that, no ring further out can hold a nearer or an equally near pixel.
+  const reach = w + h + Math.abs(fx) + Math.abs(fy);
+  for (let k = 0; k <= reach; k++) {
+    if (best >= 0 && k > 0 && bd < (k - 0.5) * (k - 0.5)) break;
+    for (let y = fy - k; y <= fy + k; y++) {
+      if (y < 0 || y >= h) continue;
+      const edgeRow = y === fy - k || y === fy + k;
+      for (let x = fx - k; x <= fx + k; x += edgeRow ? 1 : 2 * k) {
+        if (x >= 0 && x < w) {
+          const i = y * w + x;
+          if (data[i] === 1) {
+            const dx = x + 0.5 - p[0];
+            const dy = y + 0.5 - p[1];
+            const d = dx * dx + dy * dy;
+            if (d < bd || (d === bd && i < best)) {
+              bd = d;
+              best = i;
+            }
+          }
+        }
+        if (k === 0) break;
+      }
+    }
+  }
+  return best;
+}
+
+/** Bone heat's influences on the vertex at `p` (part-image px): the fields at its pixel above 0, capped and floored as the distance rule's are. */
+export function heatInfluences(field: HeatField, p: Point, limits: InfluenceLimits): Influence[] {
+  const i = nearestSilhouettePixel(field.silhouette, p);
+  const raw: Array<[string, number]> = [];
+  if (i >= 0) field.bones.forEach((bone, k) => {
+    const v = field.fields[k][i];
+    if (v > 0) raw.push([bone, v]);
+  });
+  return capAndFloor(raw, limits);
+}
+
+/** The report row of a solved field. */
+export function heatRow(field: HeatField, limits: HeatLimits = HEAT_LIMITS): HeatRow {
+  let px = 0;
+  for (const v of field.silhouette.data) if (v === 1) px++;
+  return {
+    rule: 'heat',
+    tolerance: limits.tolerance,
+    max_iterations: limits.maxIterations,
+    source_band: HEAT_SOURCE_BAND,
+    sweep: HEAT_SWEEP,
+    omega: field.omega,
+    silhouette_pixels: px,
+    islands: field.islands,
+    bones: field.bones.map((bone, k) => ({ bone, sources: field.sources[k], iterations: field.iterations[k] })),
+    residual: field.residual,
+  };
+}

package/src/localweights.ts

@@ -27,7 +27,8 @@
  *
  * ## The vertex's weights (see {@link localInfluences})
  *
- * With `S = influences(p, segments, r, limits)` — today's, unchanged. The
+ * With `S = influences(p, segments, r, limits, exponent)` — today's, under the
+ * mesh's declared exponent (issue #161; 2 where none is declared). The
  * cap and the floor are `limits`: `MAX_INFLUENCES` (4) and `MIN_WEIGHT`
  * (0.03) for the contour mode, the author's `influences` for the automatic
  * mode (issue #126, P19):
@@ -64,7 +65,7 @@
  */
 import type { Point } from './config.ts';
 import { GRID } from './contour.ts';
-import { DEFAULT_LIMITS, type Influence, influences, type InfluenceLimits, type Segment, segmentDistance } from './weights.ts';
+import { DEFAULT_LIMITS, DISTANCE_EXPONENT, type Influence, influences, type InfluenceLimits, type Segment, segmentDistance } from './weights.ts';
 
 /**
  * A region as the weights read it: rig px (or any frame, as long as the point
@@ -170,12 +171,23 @@ export interface LocalInfluence {
 }
 
 /**
- * A vertex's weights under the mesh's regions (module header). Returns the
+ * A vertex's weights under the mesh's regions (module header). `shares`, when
+ * given, is `S` from another rule — bone heat's shares at the vertex
+ * (`src/heat.ts`, issue #161), already capped and floored by `limits` — and
+ * the regions apply to it exactly as to the distance rule's. Returns the
  * overlap instead when two regions both reach the vertex. Order: with no
  * region, `S`'s own order; with a region, the region's bone first, then `S`'s
  * bones in `S`'s order.
  */
-export function localInfluences(p: Point, segments: readonly Segment[], r: number, regions: readonly WeightRegion[], limits: InfluenceLimits = DEFAULT_LIMITS): LocalInfluence | RegionOverlap {
+export function localInfluences(
+  p: Point,
+  segments: readonly Segment[],
+  r: number,
+  regions: readonly WeightRegion[],
+  limits: InfluenceLimits = DEFAULT_LIMITS,
+  exponent: number = DISTANCE_EXPONENT,
+  shares?: Influence[],
+): LocalInfluence | RegionOverlap {
   let region = -1;
   let g = 0;
   for (let k = 0; k < regions.length; k++) {
@@ -185,7 +197,7 @@ export function localInfluences(p: Point, segments: readonly Segment[], r: numbe
     region = k;
     g = gk;
   }
-  const S = influences(p, segments, r, limits);
+  const S = shares ?? influences(p, segments, r, limits, exponent);
   if (region < 0) return { influences: S, region, g: 0 };
   const bone = regions[region].bone;
   if (g >= 1) return { influences: [{ bone, weight: 1 }], region, g };

package/src/rig.ts

@@ -81,7 +81,7 @@
  * touches the disk, and the same inputs give the same bytes (key order is the
  * order the objects are built in, and every number is rounded by `pyRound`).
  */
-import { type AutoSpec, type BoneEntry, type CharacterConfig, type ConfigConstraint, CONSTRAINT_FOLLOWS, constraintForRig, type ContourSpec, type Point, ROOT_BONE, weightsABone } from './config.ts';
+import { type AutoSpec, type BoneEntry, type WeightRule, type CharacterConfig, type ConfigConstraint, CONSTRAINT_FOLLOWS, constraintForRig, type ContourSpec, type Point, ROOT_BONE, weightsABone } from './config.ts';
 import { type BoneTransform, computeExactFrameTransforms, cropToSpineY, normaliseDegrees, toBoneLocal, toWorld } from './coords.ts';
 import { type Problem, refuseIfAny } from './errors.ts';
 import type { MeshCounts, MeshQualityReport, MeshReductionInput, MotionAmplitude, ReducedMesh, Termination } from 'rig-c/mesh';
@@ -115,7 +115,8 @@ import { BLINK, blinkHoldMisses, blinkSpan, CONTROL_SUFFIX, controlledBones, IDL
 import { PAINTING_RUN, type PartsFile, readFrom } from './parts.ts';
 import { alphaAbove, crop, pad, type Raster } from './raster/index.ts';
 import { pyRound } from './round.ts';
-import { type Influence, influences, type Segment } from './weights.ts';
+import { boneHeat, heatInfluences, heatRow, type HeatRow, latticeSilhouette, tracedSilhouette } from './heat.ts';
+import { DEFAULT_LIMITS, DISTANCE_EXPONENT, type Influence, influences, type Segment } from './weights.ts';
 
 /** Transparent pixels added round every part image — the reference's `PAD`. */
 export const PAD = 4;
@@ -356,6 +357,10 @@ export interface LatticeMeshReport {
   mean_influences: number;
   art_coverage: number;
   grid: number;
+  /** The distance rule's exponent the mesh declared (issue #161); absent when it declared none and ran at 2. */
+  exponent?: number;
+  /** Only under `rule: "heat"` (issue #161): the rule and the solve it ran. Absent otherwise, so a distance mesh writes the row it always wrote. */
+  heat?: HeatRow;
 }
 
 /**
@@ -375,9 +380,13 @@ export interface ContourMeshReport {
   mean_influences: number;
   art_coverage: number;
   mode: 'contour';
+  /** The distance rule's exponent the mesh declared (issue #161); absent when it declared none and ran at 2. */
+  exponent?: number;
   params: { tolerance: number; margin: number; spacing: number; budget: number | null; stray: number | null };
   contour: ContourReport;
   regions: Array<{ name: string; bone: string; reached: number; whole: number }>;
+  /** Only under `rule: "heat"` (issue #161), as the lattice row's. */
+  heat?: HeatRow;
 }
 
 /** What a declared `source.stray` cleared from an automatic part's art (issue #172): islands, their pixels, and the art they were part of. */
@@ -413,6 +422,8 @@ export interface AutoMeshReport {
   mean_influences: number;
   art_coverage: number;
   mode: 'auto';
+  /** The distance rule's exponent the mesh declared (issue #161); absent when it declared none and ran at 2. */
+  exponent?: number;
   settings: {
     threshold: number;
     source: { tolerance: number; margin: number; spacing: number; stray: number | null };
@@ -483,6 +494,8 @@ export interface AutoMeshReport {
    * was not measured and passed is refused.
    */
   deformation: string | MotionDeformation;
+  /** Only under `rule: "heat"` (issue #161): the rule and the solve the source's weights came from. */
+  heat?: HeatRow;
   quality_report: unknown;
   motion_report?: unknown;
 }
@@ -860,7 +873,9 @@ export function buildRig(
     file: string,
     spec: ContourSpec,
     r: number,
+    exponent: number | undefined,
     segs: Segment[],
+    rule: WeightRule,
     out: Problem[],
   ): { attachment: MeshAttachment; report: ContourMeshReport } | null => {
     const ox = p.x - PAD;
@@ -880,6 +895,13 @@ export function buildRig(
       out.push(...cm);
       return null;
     }
+    // issue #161: under rule "heat", the field over the silhouette the outline was traced from (art above 8, holes
+    // filled, grown by the margin), and every vertex's segment shares read off it instead of the distance rule.
+    const heat = rule === 'heat' ? boneHeat(`config.meshes.${p.name}`, tracedSilhouette(cm.mask, ART_ALPHA, spec.margin), segs, ox, oy) : null;
+    if (Array.isArray(heat)) {
+      out.push(...heat);
+      return null;
+    }
     const weights: WeightEntry[][] = [];
     const reached = regions.map(() => 0);
     const whole = regions.map(() => 0);
@@ -889,7 +911,7 @@ export function buildRig(
     cm.vertices.forEach(([vx, vy], vi) => {
       const wx = vx + ox;
       const wy = vy + oy;
-      const li = localInfluences([wx, wy], segs, r, regions);
+      const li = localInfluences([wx, wy], segs, r, regions, DEFAULT_LIMITS, exponent ?? DISTANCE_EXPONENT, heat === null ? undefined : heatInfluences(heat, [vx, vy], DEFAULT_LIMITS));
       if ('first' in li) {
         if (!overlapped) {
           out.push({
@@ -932,9 +954,11 @@ export function buildRig(
         mean_influences: pyRound(infl / cm.vertices.length, 2),
         art_coverage: pyRound(rep.coveredArtPixels / (rep.artPixels + rep.strayPixels), 5),
         mode: 'contour',
+        ...(exponent === undefined ? {} : { exponent }),
         params: { tolerance: spec.tolerance, margin: spec.margin, spacing: spec.spacing, budget: spec.budget ?? null, stray: spec.stray ?? null },
         contour: rep,
         regions: regions.map((rg, k) => ({ name: rg.name, bone: rg.bone, reached: reached[k], whole: whole[k] })),
+        ...(heat === null ? {} : { heat: heatRow(heat) }),
       },
     };
   };
@@ -959,7 +983,9 @@ export function buildRig(
     file: string,
     spec: AutoSpec,
     r: number,
+    exponent: number | undefined,
     segs: Segment[],
+    rule: WeightRule,
     out: Problem[],
   ): { attachment: MeshAttachment; report: AutoMeshReport; motion: AutoMotionCase } | null => {
     const ox = p.x - PAD;
@@ -981,7 +1007,14 @@ export function buildRig(
     // `contourMesh` traced. Nothing left out, it is `mask` itself, so a part without stray reads what it always read.
     // The image written for the part is not touched (the reason is in docs/AUTHORING.md's `stray` row).
     const art = source.mask;
-    const sw = sourceWeights(source.vertices, ox, oy, segs, r, spec);
+    // issue #161: under rule "heat", the field over the silhouette the source was traced from (the same mask, at the
+    // automatic mode's alpha 1 and above, holes filled, grown by source.margin).
+    const heat = rule === 'heat' ? boneHeat(`config.meshes.${p.name}`, tracedSilhouette(art, AUTO_THRESHOLD - 1, spec.source.margin), segs, ox, oy) : null;
+    if (Array.isArray(heat)) {
+      out.push(...heat);
+      return null;
+    }
+    const sw = sourceWeights(source.vertices, ox, oy, segs, r, spec, exponent ?? DISTANCE_EXPONENT, heat);
     if ('overlap' in sw) {
       out.push({
         code: 'RIG_CONTOUR_REGIONS_OVERLAP',
@@ -1078,6 +1111,7 @@ export function buildRig(
           mean_influences: pyRound(infl / mesh.points.length, 2),
           art_coverage: pyRound(legacyArtCoverage(art, mesh.points, mesh.triangles), 5),
           mode: 'auto',
+          ...(exponent === undefined ? {} : { exponent }),
           settings: {
             threshold: input.art.threshold,
             source: { tolerance: spec.source.tolerance, margin: spec.source.margin, spacing: spec.source.spacing, stray: spec.source.stray ?? null },
@@ -1112,6 +1146,7 @@ export function buildRig(
           ...(residualSpec === undefined || envelope === null ? {} : { skinning_residual: residualRow(residualSpec.maxResidual, envelope.reference, envelope.derivation, report, segs[0].bone) }),
           termination: report.termination as Termination,
           weights: { sharesDroppedOnGrid: candidate.changes?.sharesDroppedOnGrid ?? 0, sharesPruned: candidate.changes?.sharesPruned ?? 0, droppedAtFivePlaces },
+          ...(heat === null ? {} : { heat: heatRow(heat) }),
           regions: regions.map((rg, k) => ({ name: rg.name, bone: weightsABone(rg) ? rg.bone : null, reached: reached[k], whole: whole[k], bound_in_result: boundTo[k] })),
           deformation: DEFORMATION_UNMEASURED,
           quality_report: qualityDocument(report),
@@ -1184,7 +1219,7 @@ export function buildRig(
     }
     const segs = meshSegments.get(p.name) as Segment[];
     if ('auto' in mesh) {
-      const row = autoAttachment(p, img, file, mesh.auto, mesh.r, segs, problems);
+      const row = autoAttachment(p, img, file, mesh.auto, mesh.r, mesh.exponent, segs, mesh.rule ?? 'distance', problems);
       if (row === null) continue;
       skin[p.name] = { [p.name]: row.attachment };
       slots.push({ name: p.name, bone: segs[0].bone, attachment: p.name });
@@ -1193,7 +1228,7 @@ export function buildRig(
       continue;
     }
     if ('contour' in mesh) {
-      const row = contourAttachment(p, img, file, mesh.contour, mesh.r, segs, problems);
+      const row = contourAttachment(p, img, file, mesh.contour, mesh.r, mesh.exponent, segs, mesh.rule ?? 'distance', problems);
       if (row === null) continue;
       skin[p.name] = { [p.name]: row.attachment };
       slots.push({ name: p.name, bone: segs[0].bone, attachment: p.name });
@@ -1209,6 +1244,12 @@ export function buildRig(
     loopPasses[p.name] = lm.passes;
     const ox = p.x - PAD;
     const oy = p.y - PAD;
+    // issue #161: under rule "heat", the field over the lattice's art (alpha above 8) with its holes filled.
+    const heat = mesh.rule === 'heat' ? boneHeat(`config.meshes.${p.name}`, latticeSilhouette(art), segs, ox, oy) : null;
+    if (Array.isArray(heat)) {
+      problems.push(...heat);
+      continue;
+    }
     const w = img.width;
     const h = img.height;
     const weights: WeightEntry[][] = [];
@@ -1217,7 +1258,7 @@ export function buildRig(
     for (const [vx0, vy0] of lm.vertices) {
       const wx = vx0 + ox;
       const wy = vy0 + oy;
-      const ent: WeightEntry[] = influences([wx, wy], segs, mesh.r).map(({ bone, weight }) => {
+      const ent: WeightEntry[] = (heat === null ? influences([wx, wy], segs, mesh.r, undefined, mesh.exponent ?? DISTANCE_EXPONENT) : heatInfluences(heat, [vx0, vy0], DEFAULT_LIMITS)).map(({ bone, weight }) => {
         const [x, y] = toBoneLocal(world.get(bone) as BoneTransform, spineX(wx), spineY(wy));
         return { bone, x: places(x), y: places(y), weight: pyRound(weight, 5) };
       });
@@ -1242,6 +1283,8 @@ export function buildRig(
       mean_influences: pyRound(infl / lm.vertices.length, 2),
       art_coverage: pyRound(artCoverage(lm, art), 5),
       grid: mesh.grid,
+      ...(mesh.exponent === undefined ? {} : { exponent: mesh.exponent }),
+      ...(heat === null ? {} : { heat: heatRow(heat) }),
     });
   }
   refuseIfAny(problems);

package/src/weights.ts

@@ -7,9 +7,11 @@
  * one authored decision about a layer: which bones may pull it. The weights
  * then follow from the geometry and nothing else:
  *
- *     w = 1 / (d + r)^2          d = distance from the vertex to the segment
+ *     w = 1 / (d + r)^e          d = distance from the vertex to the segment
  *
- * per candidate; a bone named by two segments keeps the larger; the top
+ * per candidate, with `e` the mesh's declared `exponent` (issue #161) and 2 —
+ * {@link DISTANCE_EXPONENT}, the rule as it always was — where none is
+ * declared; a bone named by two segments keeps the larger; the top
  * {@link MAX_INFLUENCES} are kept, normalised, any below {@link MIN_WEIGHT}
  * dropped, the rest normalised again, rounded to 5 decimals, and the last
  * weight written as `1 - sum(others)` so every vertex sums to exactly 1 after
@@ -35,6 +37,16 @@ export const MAX_INFLUENCES = 4;
 /** A normalised weight under this is dropped before the final normalisation — the reference's `>= 0.03`. */
 export const MIN_WEIGHT = 0.03;
 
+/**
+ * The exponent of the distance rule where a mesh declares none: `1/(d + r)²`,
+ * the reference's rule. At this value the weight is computed as
+ * `(d + r) * (d + r)`, the reference's operations, and never through
+ * `Math.pow`, which the language does not promise to round as one multiply
+ * does — so a mesh that declares nothing, or declares 2, writes the bytes it
+ * always wrote.
+ */
+export const DISTANCE_EXPONENT = 2;
+
 export interface Segment {
   bone: string;
   a: Point;
@@ -78,16 +90,31 @@ export interface InfluenceLimits {
 
 export const DEFAULT_LIMITS: InfluenceLimits = { maxInfluences: MAX_INFLUENCES, minWeight: MIN_WEIGHT };
 
-/** The influences on one vertex at `p` (rig pixels), before rounding. */
-export function influences(p: Point, segments: readonly Segment[], r: number, limits: InfluenceLimits = DEFAULT_LIMITS): Influence[] {
+/**
+ * The influences on one vertex at `p` (rig pixels), before rounding, under
+ * `w = 1/(d + r)^exponent`. The rig stage passes every mesh's exponent
+ * explicitly; the default is for readers of today's rule (the tools, the
+ * selftest's older controls).
+ */
+export function influences(p: Point, segments: readonly Segment[], r: number, limits: InfluenceLimits = DEFAULT_LIMITS, exponent: number = DISTANCE_EXPONENT): Influence[] {
   const agg = new Map<string, number>();
   for (const s of segments) {
     const d = segmentDistance(p, s.a, s.b);
-    const w = 1.0 / ((d + r) * (d + r));
+    // 2 is the reference's multiply, bit for bit (DISTANCE_EXPONENT); any other declared exponent is Math.pow.
+    const w = 1.0 / (exponent === DISTANCE_EXPONENT ? (d + r) * (d + r) : Math.pow(d + r, exponent));
     const was = agg.get(s.bone);
     agg.set(s.bone, was === undefined ? w : Math.max(was, w));
   }
-  const top = [...agg.entries()].sort((x, y) => y[1] - x[1]).slice(0, limits.maxInfluences);
+  return capAndFloor([...agg.entries()], limits);
+}
+
+/**
+ * The cap and the floor, on raw per-bone values in first-appearance order: sorted (stable), the top
+ * `maxInfluences` normalised, those under `minWeight` dropped, the rest normalised again. The distance rule
+ * above and bone heat (`src/heat.ts`, issue #161) both end here, so the two rules share one cap and one floor.
+ */
+export function capAndFloor(raw: ReadonlyArray<readonly [string, number]>, limits: InfluenceLimits): Influence[] {
+  const top = [...raw].sort((x, y) => y[1] - x[1]).slice(0, limits.maxInfluences);
   let s = 0;
   for (const [, v] of top) s += v;
   const kept = top.map(([bone, v]) => ({ bone, weight: v / s })).filter((e) => e.weight >= limits.minWeight);