rig-parts 1.62.0 → 1.64.0

package/README.md

@@ -546,9 +546,12 @@ bun run typecheck        # tsc --noEmit, strict
 bun run lint             # one rule: no explicit any
 bun run fetch-examples   # the public examples' paintings and layers, into examples/*/inputs (needs a network); each file held to its blob id at the pinned commit, a stale one replaced by name
 bun run selftest         # every gate's controls; with the examples fetched, build on each of them against its expected/
+bun run selftest -- --summary-json summary.json  # also write rig-selftest-summary/1 (per-suite PASS/FAIL/SKIP counts, holes, partial flag and exit)
 bun run smoke            # pack, install into an empty directory, run from the install (needs a network)
 ```
 
+`bun run selftest -- --summary-json <file>` writes a machine-readable summary (`spec: "rig-selftest-summary/1"`, `tool: "rig-parts"`) derived from the same `RunTally` that prints the console summary: `exit` (`0 | 1 | 2`), `partial` (`boolean`), `only` (`string[] | null`), `faults`, `totals` (`suites`, `ran`, `skipped_suites`, `controls`, `passed`, `failed`, `skipped`, `holes`), per-suite `suites` entries (`suite`, `ran`, `controls`, `passed`, `failed`, `skipped`, `status`, `reason`), `skips` (`{ suite, name, reason, hole }`), and `holes` (`{ suite, name, reason }`). See [AUTHORING §8](docs/AUTHORING.md#machine-readable-selftest-summary---summary-json-issue-725) for the full shape.
+
 The generated `foot-ownership` suite can be run alone with
 `bun run selftest -- --only foot-ownership` (exit 2 means a green partial run,
 not a full-tree verdict). Issue #638's revised acceptance requires zero foreign-leg

package/docs/AUTHORING.md

@@ -726,8 +726,10 @@ with the selected lower one. A target limb is its whole exclusive block; a targe
 part uses its actual generated slot family, including a still piece, without
 suffix matching. A requested segment or target with mixed bindings is refused.
 
-Only disjoint placements are supported. Self, reciprocal, chained/shared-slot,
-and pair/part conflicts name both declaration paths and the shared slot; no
+Several placements may share one stationary target (a star); between same-side
+co-movers base draw order decides, and a depth-driven order among them is not
+provided. Self, reciprocal, chained, shared-mover, mover-as-target, and partially
+overlapping target conflicts name both declaration paths and the shared slot; no
 constraint solver chooses a winner. Internal block order and all unselected
 slots' mutual order are stable. Declaring placement may change visible occlusion;
 assembly's part/PNG/recomposite order and every setup seam bar remain unchanged,
@@ -1014,7 +1016,7 @@ still judges the mesh before the rig stage publishes anything.
 
 `segments` is required in this mode too, but names bones directly: first the
 accepted slot bone, then any other weighted bones. All weight bones must be
-listed. A declared stopped link may be named by its emitted `<link>_d` name; no other unknown name resolves by suffix. Chain shorthand and coordinate segments are refused here. These names
+listed. A declared stopped link may be named by its emitted `<link>_d` name; no other unknown name resolves by suffix (`RIG_EXPLICIT_BINDING` refuses a raw stopped link that `stops` would rewrite). When the part is also in `turn.depths` (issue #740), state `segments`, `weights` and any island `bone` in those pre-turn bone names; `turn` wraps them into `turn_<part>_<bone>` at zero offset (`x: 0, y: 0`) after the stop-binding check, leaving the bone-local bind coordinates `(x, y, weight)` unchanged. Chain shorthand and coordinate segments are refused here. These names
 are bindings, not a recipe to generate geometry. Do not supply `r`, `grid`,
 `contour`, `auto`, `influence`, `exponent`, `rule`, `ribs`, `influences` or `stray`
 beside `explicit` (`CONFIG_EXPLICIT_MODE`). `gather: false` retains its usual
@@ -1044,6 +1046,21 @@ influence counts and art coverage and records the verified guards. It does not
 carry an earlier generator's report. Consumer provenance, formatting and files
 written by other tools are not reproduced by declaring a mesh payload.
 
+When an accepted rig splits one part across island slots (`<part>` and
+`<part>__island2`, `<part>__island3`, …; issue #734), state `explicit.islands`
+(at least two entries) in place of top-level `uvs`, `triangles`, `hull` and
+`weights` (`CONFIG_EXPLICIT_ISLANDS`). Entry `i` (`0`-based) carries `slot`
+(`"<part>"` at `i = 0`, `"<part>__island<i+1>"` at `i >= 1`;
+`CONFIG_EXPLICIT_ISLAND_SLOT`), optional `bone` (defaulting to `segments[0]`;
+must be declared in `segments`), optional `before` on `i >= 1` (the base part
+slot in `rig.json` to splice `<part>__island<i+1>` immediately before; when
+omitted, `<part>__island<i+1>` sits immediately after the part's previous
+island slot), and that island's `uvs`, `triangles`, `hull` and `weights`. On
+`<part>__island2` and later, `rig` writes `"path": "<part>"` alongside
+`"image": "<part>.png"` so the slot name and atlas region stay distinct, and
+refuses when the declared island count disagrees with the non-dust 4-connected
+art islands in `parts/<part>.png` (`RIG_EXPLICIT_ISLAND_COUNT`).
+
 ### The weight cut (`meshes.<part>.influences`, issue #284)
 
 This section and the mesh sections after it are for parts with no joints; a limb is cut at
@@ -1738,6 +1755,8 @@ exactly a value rig-c accepts, a field the mode does not have (`CONFIG_FIELD_PRE
 | <a id="CONFIG_EXPLICIT_MODE"></a>`CONFIG_EXPLICIT_MODE` | a generator field beside `explicit`; remove it to transfer the accepted payload without generation |
 | <a id="CONFIG_EXPLICIT_HASH"></a>`CONFIG_EXPLICIT_HASH` | an explicit image or region guard is not 64 lowercase hexadecimal SHA-256 digits; derive both from the immutable accepted input as stated in §3 |
 | <a id="CONFIG_EXPLICIT_SHAPE"></a>`CONFIG_EXPLICIT_SHAPE` | unpaired UVs, non-triple or out-of-range triangle indices, a hull past the vertex count or a weights row count unlike the vertices; transfer the whole accepted payload together |
+| <a id="CONFIG_EXPLICIT_ISLANDS"></a>`CONFIG_EXPLICIT_ISLANDS` | `explicit.islands` declared beside top-level `uvs`, `triangles`, `hull` or `weights`, or with fewer than 2 entries, or `before` declared on island 1 (`<part>`); state either a single-slot payload or at least two `islands` entries |
+| <a id="CONFIG_EXPLICIT_ISLAND_SLOT"></a>`CONFIG_EXPLICIT_ISLAND_SLOT` | `explicit.islands[i].slot` is not `"<part>"` for `i = 0` or `"<part>__island<i+1>"` for `i >= 1` |
 | <a id="CONFIG_MESH_MODE"></a>`CONFIG_MESH_MODE` | two of `grid`, `contour`, `auto`, `influence` and `explicit`, or no mode at all |
 | <a id="CONFIG_REGION_NAME_UNIQUE"></a>`CONFIG_REGION_NAME_UNIQUE` | a region named twice in one mesh's `regions` (or `bust_r` / `bust_l` declared in `contour.regions` alongside `contour.bust`) — every one named in one run |
 | <a id="CONFIG_REGION_BAND_NEEDS_BONE"></a><a id="CONFIG_REGION_BONE_NEEDS_BAND"></a>`CONFIG_REGION_BAND_NEEDS_BONE`, `CONFIG_REGION_BONE_NEEDS_BAND` | a region with a `band` and no `bone`, or a `bone` and no `band`: write both for a region that weights its bone, neither for a density-only region (issue #155) |
@@ -3819,12 +3838,13 @@ says why each requirement exists and what breaks without it.
 | <a id="RIG_SET_FRONT_BOTH"></a>`RIG_SET_FRONT_BOTH` | a `parts.json` alternate record (issue #664) maps both a part's slot and its front slot `<part>_front`; the detail names the set and the part | re-run `assemble`, which maps one or the other |
 | <a id="RIG_LAYOUT_NONEXCLUSIVE"></a>`RIG_LAYOUT_NONEXCLUSIVE` | a requested segment family/target, or an accepted replay's bindings, span owners or leave the selected segment scope across base/alternate attachments | correct the named bindings or scope; mixed ownership is never forced and no stale proof is emitted |
 | <a id="RIG_LAYOUT_UNREPRESENTABLE"></a>`RIG_LAYOUT_UNREPRESENTABLE` | the named slot family is absent, a target is not contiguous, the accepted slot population/adjacency changed, or final rig text is stale | use an emitted contiguous target and the exact final accepted source; unrelated slots are not absorbed |
-| <a id="RIG_LAYOUT_CONFLICT"></a>`RIG_LAYOUT_CONFLICT` | layout declarations share a slot, target themselves, or form a reciprocal/chained pair; both field paths are printed | declare one disjoint pair, with each participating slot in only that placement |
+| <a id="RIG_LAYOUT_CONFLICT"></a>`RIG_LAYOUT_CONFLICT` | layout declarations share a moving slot, use a moving slot as a target, target themselves, form a reciprocal/chained pair, or partially overlap a shared target block; both field paths are printed | move each participating slot in at most one placement, and share only a stationary target block |
 | <a id="RIG_STILL_ROW_INSIDE_PART"></a><a id="RIG_STILL_ROW_CLEAR"></a><a id="RIG_STILL_PIECES_HAVE_ART"></a><a id="RIG_STILL_NAME_FREE"></a>`RIG_STILL_ROW_INSIDE_PART`, `RIG_STILL_ROW_CLEAR`, `RIG_STILL_PIECES_HAVE_ART`, `RIG_STILL_NAME_FREE` | a `motion.blink.still` row that is not strictly inside the part, that crosses art (a cut through art changes the render even at rest), that leaves one piece with no art, or whose `<part>_still` slot name another part already has | that entry's `row` — a row with no art between the crease and the lash line — or rename the other part |
 | <a id="RIG_SET_COVERS_BONE"></a>`RIG_SET_COVERS_BONE` | `assemble.alternates[i].drawn.<bone>` (issue #476): a subset set in `parts.json` `alternates` (`parts` present) states a `drawn` world angle for a bone none of its covered slots ride; the detail names the bone, the set, and the covered bones | remove the uncovered bone from that set's `drawn`, or add the part that rides it to `parts` |
-| <a id="RIG_EXPLICIT_BINDING"></a>`RIG_EXPLICIT_BINDING` | the declared stops or turn would change the accepted payload's bindings | transfer the accepted final emitted bone names and local coordinates, or use a generated mesh; no normalization is applied |
+| <a id="RIG_EXPLICIT_BINDING"></a>`RIG_EXPLICIT_BINDING` | the declared stops would change the accepted payload's bindings | transfer the accepted final emitted bone names and local coordinates, or use a generated mesh; no normalization is applied |
 | <a id="RIG_EXPLICIT_IMAGE_HASH"></a>`RIG_EXPLICIT_IMAGE_HASH` | the decoded part RGBA differs from `explicit.image_sha256`; both digests are named | restore the accepted image or transfer its matching accepted payload and guard; nothing is written |
 | <a id="RIG_EXPLICIT_REGION_HASH"></a>`RIG_EXPLICIT_REGION_HASH` | the canvas or placed part rectangle differs from `explicit.region_sha256`; both digests are named | restore the accepted region or transfer a payload bound to this placement; nothing is written |
+| <a id="RIG_EXPLICIT_ISLAND_COUNT"></a>`RIG_EXPLICIT_ISLAND_COUNT` | `explicit.islands.length` differs from the non-dust 4-connected art island count of `parts/<part>.png`; the missing or extra `<part>__island<N>` slot names and island pixel counts are named | supply one `explicit.islands` entry per non-dust art island (`<part>`, `<part>__island2`, …); nothing is written |
 | <a id="RIG_EXPLICIT_ALTERNATE"></a>`RIG_EXPLICIT_ALTERNATE` | an alternate set replaces a part bound to one accepted explicit payload | use a generated mesh for alternate artwork; no alternate is inferred from a base payload |
 | <a id="RIG_INFLUENCE_REACH"></a>`RIG_INFLUENCE_REACH` | an influence mesh's `radius` is at or under the distance from its farthest lattice vertex to that vertex's nearest link (issue #378): a link pulls only when it is nearer than `radius`, so that vertex would be pulled by none. The vertex, where it is and the distance are named | a `radius` above the distance named, or a segment nearer that part of the art |
 | <a id="RIG_INFLUENCE_LATTICE"></a>`RIG_INFLUENCE_LATTICE` | rig-c's segments lattice refused the part at the declared `cell` (no pixel of the part holds art, or the cell is not a whole number of at least 1); rig-c's message is quoted | a part with art, or a whole `cell` of at least 1 |
@@ -5084,3 +5104,66 @@ machine under a load average of 5 to 11, the difference in user + sys was +5.6 a
 the load moves the same build by (the pre-change reference-demo build alone took 43.6 to
 45.8 s there). Since issue #123 that build and render are gone again — the still regions read the
 idle's geometry — and the `build` row was not re-measured for it either.
+
+### Machine-readable selftest summary (`--summary-json`, issue #725)
+
+`bun run selftest -- --summary-json <file>` writes a JSON summary beside the normal console output
+so automated lanes and reports read the run's own `RunTally` rather than regex-parsing logs. It is
+supported on full runs, partial `--only` runs, and `--merge` runs (and refused with exit `2` when
+missing a path, given twice, or combined with `--shard`):
+
+```json
+{
+  "spec": "rig-selftest-summary/1",
+  "tool": "rig-parts",
+  "exit": 0,
+  "partial": false,
+  "only": null,
+  "faults": [],
+  "totals": {
+    "suites": 63,
+    "ran": 62,
+    "skipped_suites": 1,
+    "controls": 2250,
+    "passed": 2250,
+    "failed": 0,
+    "skipped": 1,
+    "holes": 1
+  },
+  "suites": [
+    {
+      "suite": "png",
+      "ran": true,
+      "controls": 2,
+      "passed": 2,
+      "failed": 0,
+      "skipped": 0,
+      "status": "pass",
+      "reason": null
+    }
+  ],
+  "skips": [
+    {
+      "suite": "corpus",
+      "name": "corpus",
+      "reason": "no --corpus <dir>, no RIG_PARTS_CORPUS (or SPINE_PARTS_CORPUS) and no fetched examples/*/inputs",
+      "hole": true
+    }
+  ],
+  "holes": [
+    {
+      "suite": "corpus",
+      "name": "corpus",
+      "reason": "no --corpus <dir>, no RIG_PARTS_CORPUS (or SPINE_PARTS_CORPUS) and no fetched examples/*/inputs"
+    }
+  ]
+}
+```
+
+- Every count in `totals` and `suites` is read from the same `RunTally` instance that prints the
+  console summary (`RT15`).
+- Only two-space-indented `SKIP` gutter lines enter `skips`, and only those followed by a
+  `This is a HOLE in this run` continuation line (or a suite returning `null` outside `--only`)
+  enter `holes`; check names or indented detail lines containing `HOLE` or `SKIP` (such as
+  `RG82_BLINK_NO_HOLE_…` or `SO21_ZERO_SETUP_BANDS_REMAIN_NAMED_SKIPS_…`) are counted as `PASS` or
+  `FAIL` controls and never as `skips` or `holes` (`RT16`, `RT17`).

package/docs/STABILITY.md

@@ -143,7 +143,8 @@ part name, `[i]` an entry of a list):
 - **stops[i]** — required: `chain`, `against`, `at`, `inward`, `outward`; optional: `links`, `lower` (issue #404)
 - **stops[i].lower** — required: `inward`, `outward`
 - **meshes.<part>** — exactly one of `grid`, `contour`, `auto`, `influence`, `explicit`; required in every mode: `segments`, and `r` in generated modes other than `influence`; `explicit` refuses generation fields and uses direct bone names in `segments`, the first the slot bone; optional in every mode: `exponent`, `rule`, `gather` (issue #680, false only: preserve an exclusive non-segment rider's authored draw position without changing its binding; absent, output bytes unchanged); optional with `contour` or `auto`: `ribs`; optional with `grid` or `contour`: `influences` (issue #284; beside `auto` it is refused, CONFIG_INFLUENCES_MODE); optional with `grid`: `stray` (issue #303; beside `contour` or `auto` it is refused, CONFIG_STRAY_MODE)
-- **meshes.&lt;part&gt;.explicit** — required: `image_sha256`, `region_sha256`, `uvs`, `triangles`, `hull`, `weights` (issue #658); direct payload numbers are transferred without normalization; weights require `bone`, `x`, `y`, `weight`. Image SHA-256 is over decoded unpadded RGBA bytes; region SHA-256 is over JSON.stringify([rig width, rig height, part x, part y, part w, part h]). Both must match before output. All weighted bones must occur in segments; declared stopped links may use their emitted `<link>_d` names. Other unknown names remain refused. Alternate artwork for this part is refused; use a generated mesh for it.
+- **meshes.&lt;part&gt;.explicit** — required: `image_sha256`, `region_sha256`, and either `uvs`, `triangles`, `hull`, `weights` (single-slot, issue #658) or `islands` (at least two island entries, issue #734); direct payload numbers are transferred without normalization; weights require `bone`, `x`, `y`, `weight`. Image SHA-256 is over decoded unpadded RGBA bytes; region SHA-256 is over JSON.stringify([rig width, rig height, part x, part y, part w, part h]). Both must match before output, and when `islands` is declared its entry count must match the part's non-dust 4-connected art island count. All weighted and island slot bones must occur in segments; declared stopped links may use their emitted `<link>_d` names. Other unknown names remain refused. Alternate artwork for this part is refused; use a generated mesh for it.
+- **meshes.&lt;part&gt;.explicit.islands[i]** — required: `slot` (`<part>` at index 0, `<part>__island<i+1>` at index i >= 1), `uvs`, `triangles`, `hull`, `weights`; optional: `bone` (defaults to `segments[0]`), `before` (index i >= 1 only: the base part slot in `rig.json` to splice `<part>__island<i+1>` immediately before; absent, immediately after the part's previous island slot)
 - **meshes.&lt;part&gt;.influence** — required: `cell`, `radius`, `across`, `max`, `shape` (issue #378); optional: `hold_tip` (issue #615, the value true only); beside it `r`, `exponent`, `rule`, `influences`, `stray` and `ribs` are refused by name
 - **meshes.&lt;part&gt;.influences** — optional, at least one: `maxInfluences` (a whole number, 1 or more, or null for no cap), `floor` ("cut" or "continuous")
 - **meshes.&lt;part&gt;.ribs.&lt;chain&gt;** — required: `stations`
@@ -289,8 +290,10 @@ in the package.
 
 ## rig-c
 
-`dependencies` takes `rig-c` `^2.69.0`: 2.69.0 or any later 2.x. Bun 1.2 or later
-runs the package (`engines`). What this package relies on in rig-c, every import
+`dependencies` takes `rig-c` `^2.69.0`: 2.69.0 or any later 2.x. Bun 1.4 or later
+is the declared floor (`engines.bun` `>=1.4.0`; older 1.4 releases are not tested in
+CI, which runs `latest`, and compatibility with an older 1.4 release is handled when
+reported as an issue). What this package relies on in rig-c, every import
 read off `src/` and `cli.ts`:
 
 - the named entries `rig-c/mesh` (the outline functions, `measureAuthoredMeshFit`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.62.0",
+  "version": "1.64.0",
   "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": {
@@ -8,7 +8,7 @@
     "spine-parts": "./bin/rig-parts.cjs"
   },
   "engines": {
-    "bun": ">=1.2.0"
+    "bun": ">=1.4.0"
   },
   "license": "MIT",
   "author": "firejune",

package/skills/rig-parts/SKILL.md

@@ -2,7 +2,7 @@
 name: rig-parts
 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 check a painting before See-through (rig-parts 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 lip-sync or swapping a part's image, or for running See-through itself.
 license: MIT
-compatibility: Requires Bun 1.2 or later. The tool is the npm package @rig-c/parts (npm i -D @rig-c/parts, or bun add -d @rig-c/parts), whose command is rig-parts; rig-c is installed with it. See-through is run separately.
+compatibility: Requires Bun 1.4 or later (declared in engines.bun >=1.4.0; CI tests latest only). The tool is the npm package @rig-c/parts (npm i -D @rig-c/parts, or bun add -d @rig-c/parts), whose command is rig-parts; rig-c is installed with it. See-through is run separately.
 ---
 
 # rig-parts — a painting to a Spine rig, for agents

package/src/check.ts

@@ -164,7 +164,10 @@ import {
 import { RIG_BONE_INHERIT, type RigSpec as RigcRigSpec } from 'rig-c/src/rig.ts';
 import { expandStops } from 'rig-c/src/stop.ts';
 import { ENVIRONMENT_SPEC, EnvironmentError, environmentResponse, readEnvironmentSchedule } from 'rig-c/src/environment.ts';
+import { ART_ALPHA } from './mesh.ts';
+import { connectedComponents } from './raster/components.ts';
 import { alphaComposite } from './raster/composite.ts';
+import { alphaAbove } from './raster/index.ts';
 import { readPng, writePng } from './raster/png.ts';
 import { newFloatImage, newRaster, type Raster } from './raster/types.ts';
 import type { BaseTag } from './tags.ts';
@@ -1240,16 +1243,180 @@ export interface SeamFigures {
   map: { sx: number; sy: number; tx: number; ty: number };
 }
 
+/**
+ * Partition a multi-island part's raster into one raster per declared island
+ * slot (`<part>`, `<part>__island2..<part>__island<N>`), ordered by descending
+ * `alpha > ART_ALPHA` 4-connected component area (tie-broken by ascending
+ * row-major label). Anti-aliased fringe pixels (`1 <= alpha <= ART_ALPHA`)
+ * propagate from their connected island seed via 4-connected BFS over
+ * `alpha > 0`, with any disconnected sub-threshold pixel assigned to the
+ * nearest seed centroid so every non-transparent pixel of `image` lands in
+ * exactly one island raster.
+ */
+export function splitPartIslands(image: Raster, count: number): Raster[] {
+  if (count <= 1) return [image];
+  const { width, height, data } = image;
+  const cc = connectedComponents(alphaAbove(image, ART_ALPHA), 4);
+  const seeds = cc.stats
+    .slice(1)
+    .sort((a, b) => b.area - a.area || a.label - b.label)
+    .slice(0, count);
+  if (seeds.length <= 1) return [image];
+  const owner = new Int16Array(width * height).fill(-1);
+  const labelToSeed = new Int16Array(cc.count + 1).fill(-1);
+  seeds.forEach((s, idx) => {
+    labelToSeed[s.label] = idx;
+  });
+  const queue = new Int32Array(width * height);
+  let head = 0;
+  let tail = 0;
+  for (let i = 0; i < width * height; i++) {
+    const seedIdx = labelToSeed[cc.labels[i]];
+    if (seedIdx >= 0) {
+      owner[i] = seedIdx;
+      queue[tail++] = i;
+    }
+  }
+  while (head < tail) {
+    const cur = queue[head++];
+    const seedIdx = owner[cur];
+    const x = cur % width;
+    const y = (cur - x) / width;
+    if (x > 0) {
+      const n = cur - 1;
+      if (owner[n] < 0 && data[n * 4 + 3] > 0) {
+        owner[n] = seedIdx;
+        queue[tail++] = n;
+      }
+    }
+    if (x + 1 < width) {
+      const n = cur + 1;
+      if (owner[n] < 0 && data[n * 4 + 3] > 0) {
+        owner[n] = seedIdx;
+        queue[tail++] = n;
+      }
+    }
+    if (y > 0) {
+      const n = cur - width;
+      if (owner[n] < 0 && data[n * 4 + 3] > 0) {
+        owner[n] = seedIdx;
+        queue[tail++] = n;
+      }
+    }
+    if (y + 1 < height) {
+      const n = cur + width;
+      if (owner[n] < 0 && data[n * 4 + 3] > 0) {
+        owner[n] = seedIdx;
+        queue[tail++] = n;
+      }
+    }
+  }
+  const out = Array.from({ length: count }, () => newRaster(width, height));
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const i = y * width + x;
+      const p = i * 4;
+      if (data[p + 3] === 0) continue;
+      let idx = owner[i];
+      if (idx < 0) {
+        let best = 0;
+        let bestD2 = Infinity;
+        seeds.forEach((s, si) => {
+          const dx = x - s.cx;
+          const dy = y - s.cy;
+          const d2 = dx * dx + dy * dy;
+          if (d2 < bestD2) {
+            bestD2 = d2;
+            best = si;
+          }
+        });
+        idx = best;
+      }
+      out[idx].data.set(data.subarray(p, p + 4), p);
+    }
+  }
+  return out;
+}
+
+export interface ReferencePlacement {
+  name: string;
+  png: string;
+  box: PartRecord;
+  islandIndex?: number;
+  islandCount?: number;
+}
+
+function partIslandSlots(part: string, slotOrder?: readonly string[]): string[] {
+  if (slotOrder === undefined || !slotOrder.includes(`${part}__island2`)) return [part];
+  const out = [part];
+  for (let k = 2; slotOrder.includes(`${part}__island${k}`); k++) {
+    out.push(`${part}__island${k}`);
+  }
+  return out;
+}
+
+export function resolvePlacedAlpha(placements: readonly ReferencePlacement[], partsDir: string): PlacedAlpha[] {
+  const rawCache = new Map<string, Raster>();
+  const splitCache = new Map<string, Raster[]>();
+  const readRaw = (png: string): Raster => {
+    const hit = rawCache.get(png);
+    if (hit !== undefined) return hit;
+    const img = readPng(join(partsDir, `${png}.png`));
+    rawCache.set(png, img);
+    return img;
+  };
+  return placements.map((pl) => {
+    const raw = readRaw(pl.png);
+    if (pl.islandCount !== undefined && pl.islandCount > 1 && pl.islandIndex !== undefined) {
+      const key = `${pl.png}:${pl.islandCount}`;
+      let islands = splitCache.get(key);
+      if (islands === undefined) {
+        islands = splitPartIslands(raw, pl.islandCount);
+        splitCache.set(key, islands);
+      }
+      return { name: pl.name, from: pl.box.from, x: pl.box.x, y: pl.box.y, image: islands[pl.islandIndex] ?? raw };
+    }
+    return { name: pl.name, from: pl.box.from, x: pl.box.x, y: pl.box.y, image: raw };
+  });
+}
+
+export function basePlacements(parts: PartsFile, slotOrder?: readonly string[]): ReferencePlacement[] {
+  return setPlacements(
+    parts,
+    {
+      name: '',
+      slots: {},
+      records: [],
+      ghost_px: {},
+      recomposite: parts.recomposite ?? {
+        mean_abs: 0,
+        within_limit: 0,
+        within_share: 1,
+        error_limit: 0,
+        error_px: 0,
+        covered_alpha: 0,
+        uncovered_error_px: 0,
+        hole_count: 0,
+        holes_listed: 0,
+        holes: [],
+      },
+    },
+    slotOrder,
+  );
+}
+
 /**
  * The flat stack of parts over the background, in rig pixels: PIL's
- * `alpha_composite` of every part at its `x, y`, in parts.json order, over an
- * opaque canvas of the render's own background colour.
+ * `alpha_composite` of every part at its `x, y`, in parts.json order (with
+ * multi-island explicit slots placed at their declared `slotOrder` positions
+ * when `slotOrder` is supplied), over an opaque canvas of the render's own
+ * background colour.
  */
-export function flatComposite(parts: PartsFile, partsDir: string, background: readonly [number, number, number, number]): Raster {
+export function flatComposite(parts: PartsFile, partsDir: string, background: readonly [number, number, number, number], slotOrder?: readonly string[]): Raster {
   const [W, H] = parts.rig_size;
   let canvas = newRaster(W, H);
   for (let i = 0; i < W * H; i++) canvas.data.set(background, i * 4);
-  for (const p of parts.parts) canvas = alphaComposite(canvas, readPng(join(partsDir, `${p.name}.png`)), p.x, p.y);
+  for (const p of resolvePlacedAlpha(basePlacements(parts, slotOrder), partsDir)) canvas = alphaComposite(canvas, p.image, p.x, p.y);
   return canvas;
 }
 
@@ -1260,9 +1427,11 @@ export function flatComposite(parts: PartsFile, partsDir: string, background: re
  * slot (`alt.front`) is drawn from its record although `alt.hides` names it (the
  * hide is its base slot's) — with `slotOrder`, the rig's final setup slot names,
  * right after the nearest part slot before `<part>_front` there; without it (or
- * with no such slot), in its own place, as the base slot would draw it.
+ * with no such slot), in its own place, as the base slot would draw it. When
+ * `slotOrder` names multi-island explicit slots (`<part>__island2..<part>__island<N>`),
+ * each island's placement follows its declared slot position in `slotOrder`.
  */
-export function setPlacements(parts: PartsFile, alt: AlternatePartsRecord, slotOrder?: readonly string[]): Array<{ name: string; png: string; box: PartRecord }> {
+export function setPlacements(parts: PartsFile, alt: AlternatePartsRecord, slotOrder?: readonly string[]): ReferencePlacement[] {
   const hides = new Set(alt.hides ?? []);
   const front = new Set(alt.front ?? []);
   const byName = new Map(alt.records.map((r) => [r.name, r]));
@@ -1281,18 +1450,73 @@ export function setPlacements(parts: PartsFile, alt: AlternatePartsRecord, slotO
     }
   }
   const moved = [...after.keys()].sort((a, b) => (slotOrder as readonly string[]).indexOf(`${a}${FRONT_SUFFIX}`) - (slotOrder as readonly string[]).indexOf(`${b}${FRONT_SUFFIX}`));
-  const out: Array<{ name: string; png: string; box: PartRecord }> = [];
+  type PlacedIslandEntry = ReferencePlacement & { at: number };
+  const inlineIslands = new Map<string, PlacedIslandEntry[]>();
+  const beforeTarget = new Map<string | null, PlacedIslandEntry[]>();
+  if (slotOrder !== undefined) {
+    for (const p of parts.parts) {
+      if (byName.has(p.name)) continue;
+      const islandSlots = partIslandSlots(p.name, slotOrder);
+      if (islandSlots.length <= 1) continue;
+      const baseIdx = slotOrder.indexOf(p.name);
+      for (let k = 1; k < islandSlots.length; k++) {
+        const islSlot = islandSlots[k];
+        if ((hides.has(p.name) && !front.has(p.name)) || hides.has(islSlot)) continue;
+        const at = slotOrder.indexOf(islSlot);
+        let reordered = at < baseIdx;
+        if (!reordered) {
+          for (let j = baseIdx + 1; j < at; j++) {
+            if (partNames.has(slotOrder[j]) && !after.has(slotOrder[j])) {
+              reordered = true;
+              break;
+            }
+          }
+        }
+        const entry: PlacedIslandEntry = { name: islSlot, png: p.name, box: p, islandIndex: k, islandCount: islandSlots.length, at };
+        if (!reordered) {
+          const list = inlineIslands.get(p.name) ?? [];
+          list.push(entry);
+          inlineIslands.set(p.name, list);
+        } else {
+          let target: string | null = null;
+          for (let j = at + 1; j < slotOrder.length; j++) {
+            if (partNames.has(slotOrder[j]) && !after.has(slotOrder[j])) {
+              target = slotOrder[j];
+              break;
+            }
+          }
+          const list = beforeTarget.get(target) ?? [];
+          list.push(entry);
+          beforeTarget.set(target, list);
+        }
+      }
+    }
+    for (const list of inlineIslands.values()) list.sort((a, b) => a.at - b.at);
+    for (const list of beforeTarget.values()) list.sort((a, b) => a.at - b.at);
+  }
+  const out: ReferencePlacement[] = [];
+  const pushIsland = ({ at: _at, ...pl }: PlacedIslandEntry): void => {
+    out.push(pl);
+  };
   const draw = (name: string, base: PartRecord): void => {
     if (hides.has(name) && !front.has(name)) return;
     const rec = byName.get(name);
+    const islandSlots = rec === undefined ? partIslandSlots(name, slotOrder) : [name];
+    if (islandSlots.length > 1) {
+      out.push({ name, png: name, box: base, islandIndex: 0, islandCount: islandSlots.length });
+      for (const isl of inlineIslands.get(name) ?? []) pushIsland(isl);
+      return;
+    }
     out.push({ name, png: rec === undefined ? name : `${alt.name}_${rec.name}`, box: rec ?? base });
   };
   const baseOf = new Map(parts.parts.map((p) => [p.name, p]));
   for (const p of parts.parts) {
     if (after.has(p.name)) continue;
+    for (const isl of beforeTarget.get(p.name) ?? []) pushIsland(isl);
     draw(p.name, p);
     for (const m of moved) if (after.get(m) === p.name) draw(m, baseOf.get(m) as PartRecord);
   }
+  for (const isl of beforeTarget.get(null) ?? []) pushIsland(isl);
   return out;
 }
 
@@ -1328,16 +1552,17 @@ export function flatCompositeForSet(parts: PartsFile, alt: AlternatePartsRecord,
   const [W, H] = parts.rig_size;
   let canvas = newRaster(W, H);
   for (let i = 0; i < W * H; i++) canvas.data.set(background, i * 4);
-  for (const { png, box } of setPlacements(parts, alt, slotOrder)) canvas = alphaComposite(canvas, readPng(join(partsDir, `${png}.png`)), box.x, box.y);
+  for (const p of resolvePlacedAlpha(setPlacements(parts, alt, slotOrder), partsDir)) canvas = alphaComposite(canvas, p.image, p.x, p.y);
   return canvas;
 }
 
 /**
  * The setup-pose rig spec with an alternate set applied (issues #454, #465):
- * hidden slots (and `<slot>_still` for any hidden or covered slot) have no
- * setup attachment, covered slots have `alt.slots[slot]`, and when the set
- * carries `drawn` bone rotations its bones are posed at those world rotations
- * so the throwaway still renders the alternate in the pose it was painted in.
+ * hidden slots (and `<slot>_still` or `<slot>__island<k>` for any hidden or
+ * covered slot) have no setup attachment, covered slots have `alt.slots[slot]`,
+ * and when the set carries `drawn` bone rotations its bones are posed at those
+ * world rotations so the throwaway still renders the alternate in the pose it
+ * was painted in.
  */
 export function stillRigForSet(
   rig: Record<string, unknown>,
@@ -1348,7 +1573,13 @@ export function stillRigForSet(
   const slots = (Array.isArray(rig.slots) ? rig.slots : []).map((s) => {
     if (!isRecord(s) || typeof s.name !== 'string') return s;
     const stillBase = s.name.endsWith('_still') ? s.name.slice(0, -'_still'.length) : null;
-    if (hides.has(s.name) || (stillBase !== null && (hides.has(stillBase) || Object.hasOwn(alt.slots, stillBase)))) {
+    const islandMatch = /^(.+)__island[2-9]\d*$/.exec(s.name);
+    const islandBase = islandMatch !== null ? islandMatch[1] : null;
+    if (
+      hides.has(s.name) ||
+      (stillBase !== null && (hides.has(stillBase) || Object.hasOwn(alt.slots, stillBase))) ||
+      (islandBase !== null && (hides.has(islandBase) || Object.hasOwn(alt.slots, islandBase)))
+    ) {
       return { ...s, attachment: null };
     }
     if (Object.hasOwn(alt.slots, s.name)) return { ...s, attachment: alt.slots[s.name] };
@@ -5110,7 +5341,15 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
       const checkedAlt = set !== undefined && !allSets && inp.parts !== null ? (inp.parts.alternates ?? []).find((a) => a.name === set) : undefined;
       const subsetFoldSlots =
         checkedAlt !== undefined && checkedAlt.parts !== undefined
-          ? new Set<string>([...Object.keys(checkedAlt.slots), ...(checkedAlt.hides ?? [])])
+          ? (() => {
+              const baseSet = new Set<string>([...Object.keys(checkedAlt.slots), ...(checkedAlt.hides ?? [])]);
+              for (const sl of (Array.isArray(inp.rig.slots) ? inp.rig.slots : []).filter(isRecord)) {
+                if (typeof sl.name !== 'string') continue;
+                const m = /^(.+)__island[2-9]\d*$/.exec(sl.name);
+                if (m !== null && baseSet.has(m[1])) baseSet.add(sl.name);
+              }
+              return baseSet;
+            })()
           : null;
       const filterFolds = (map: Map<string, FoldingMesh[]>): Map<string, FoldingMesh[]> => {
         if (subsetFoldSlots === null) return map;
@@ -5526,9 +5765,10 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
         const canonicalSet = canonical(join(stillDir, 'build'), join(stillDir, 'seam'));
         seamViewport = canonicalSet.viewport;
         if (keepStills) cpSync(join(stillDir, 'seam'), keptDir, { recursive: true });
-        const composite = flatComposite(inp.parts, inp.partsDir, stillSet.background);
+        const rigSlotOrder = (Array.isArray(inp.rig.slots) ? inp.rig.slots : []).filter(isRecord).map((sl) => String(sl.name));
+        const composite = flatComposite(inp.parts, inp.partsDir, stillSet.background, rigSlotOrder);
         const autoSeam = seamFigures(composite, stillSet.frames[0].image, inp.stage, stillSet.viewport, stillSet.background, undefined, inp.parts.scene !== undefined);
-        const placed = inp.parts.parts.map(p => ({ name: p.name, from: p.from, x: p.x, y: p.y, image: readPng(join(inp.partsDir, `${p.name}.png`)) }));
+        const placed = resolvePlacedAlpha(basePlacements(inp.parts, rigSlotOrder), inp.partsDir);
         const basePopulation = createSeamPopulation(placed, inp.parts.rig_size, canonicalSet.viewport);
         seam = seamFigures(composite, canonicalSet.frames[0].image, inp.stage, canonicalSet.viewport, canonicalSet.background, undefined, inp.parts.scene !== undefined, undefined, true, basePopulation.observe);
         seamScope = { mode: 'source-grid/base', domain, denominator_px: canonicalDenominator(seam), auto_frame_raw: seamReading(autoSeam, stillSet.viewport), whole: seamReading(seam, canonicalSet.viewport), population: basePopulation.finish() };
@@ -5547,11 +5787,10 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
             if (asr.status !== 0) refuseIfAny(rigcFailed(`render (the setup-pose still of set "${alt.name}")`, asr, asr.out.split('\n').filter((l) => l.includes('FAIL'))));
             const altStillSet = readFrameSet(join(setDir, 'render'));
             if (keepStills) cpSync(join(setDir, 'render'), join(out, 'setup_still_auto', alt.name), { recursive: true });
-            const rigSlotOrder = (Array.isArray(inp.rig.slots) ? inp.rig.slots : []).filter(isRecord).map((sl) => String(sl.name));
             const altComposite = flatCompositeForSet(inp.parts, alt, inp.partsDir, altStillSet.background, rigSlotOrder);
             const altCanonical = canonical(join(setDir, 'build'), join(setDir, 'seam'));
             if (keepStills) cpSync(join(setDir, 'seam'), join(keptDir, alt.name), { recursive: true });
-            const altPlaced = setPlacements(inp.parts, alt, rigSlotOrder).map(({ name, png, box }) => ({ name, from: box.from, x: box.x, y: box.y, image: readPng(join(inp.partsDir, `${png}.png`)) }));
+            const altPlaced = resolvePlacedAlpha(setPlacements(inp.parts, alt, rigSlotOrder), inp.partsDir);
             const altSupport = seamSupport(join(setDir, 'build'), join(setDir, 'rig.json'), altCanonical, altPlaced, seamStacks, inp.stage);
             const effects = seamEffectSelection(baseSupport, altSupport);
             const autoAltSeam = seamFigures(altComposite, altStillSet.frames[0].image, inp.stage, altStillSet.viewport, altStillSet.background, undefined, alt.scene !== undefined);