spine-parts 2.27.0 → 2.27.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -229,8 +229,8 @@ control skeleton it draws itself — and records the prompts verbatim beside it.
229
229
  wrapper on one image and writes the wrapper form `layers` reads. The host comes
230
230
  from `--host` or `COMFY_HOST` and has no default; before anything is uploaded
231
231
  the graph is checked against the box's `/object_info`, so a missing node class
232
- or model is refused by name, and the adapter waits for an empty queue rather
233
- than queueing behind someone else's job.
232
+ or model is refused by name, and the adapter appends the job behind any other in
233
+ the queue.
234
234
 
235
235
  The painting graph uses `4x-AnimeSharp.pth`, then Lanczos resizing. The
236
236
  [creator's card](https://huggingface.co/Kim2091/AnimeSharp/blob/7696d95ced82b0c1f2a41f6ac73336133f0a90e1/README.md)
package/cli.ts CHANGED
@@ -843,9 +843,11 @@ usage:
843
843
  wrapper installed, and write the wrapper form \`layers\` reads into <out>
844
844
  (absent or empty): layers.json, parts/<tag>.png, meta.json, previews/.
845
845
  The host is --host or COMFY_HOST and has no default. Checks every node and
846
- input against the box's /object_info before uploading, waits for an empty
847
- queue (at most --wait s), polls /history (at most --timeout s), and
848
- writes <out> only after the layer reader accepts what came back.
846
+ input against the box's /object_info before uploading, appends the job
847
+ behind any other (never in front, nothing cancelled; a job still pending
848
+ after --wait s is refused with its queue place), polls /history (at most
849
+ --timeout s), and writes <out> only after the layer reader accepts what
850
+ came back.
849
851
  --lama turns the wrapper's LaMa inpainting on and --nf4 its nf4
850
852
  quantisation; both are off unless given. Resolution, steps, seed and offload
851
853
  use explicit flags first, then --config's seethrough block, then defaults
package/docs/AUTHORING.md CHANGED
@@ -5330,7 +5330,7 @@ those settings. Changing a config seed alone cannot change a no-config run.
5330
5330
  | --- | --- | --- |
5331
5331
  | <a id="COMFY_HOST_GIVEN"></a><a id="COMFY_REACHABLE"></a><a id="COMFY_REQUEST_OK"></a>`COMFY_HOST_GIVEN`, `COMFY_REACHABLE`, `COMFY_REQUEST_OK` | no `--host`/`COMFY_HOST`, nothing answering there, or a non-200 answer | the host, or the box |
5332
5332
  | <a id="COMFY_NODE_PRESENT"></a><a id="COMFY_INPUT_KNOWN"></a><a id="COMFY_INPUT_SET"></a><a id="COMFY_CHOICE_PRESENT"></a>`COMFY_NODE_PRESENT`, `COMFY_INPUT_KNOWN`, `COMFY_INPUT_SET`, `COMFY_CHOICE_PRESENT` | the box's `/object_info` lacks a node class the graph uses, an input it sets, an input it must set, or a model file it names | install the node or model on the box, or the config value naming it |
5333
- | <a id="COMFY_QUEUE_EMPTY"></a><a id="COMFY_PROMPT_ACCEPTED"></a><a id="COMFY_HISTORY_WITHIN"></a><a id="COMFY_RUN_OK"></a>`COMFY_QUEUE_EMPTY`, `COMFY_PROMPT_ACCEPTED`, `COMFY_HISTORY_WITHIN`, `COMFY_RUN_OK` | someone else's job kept the queue busy past `--wait`, the box rejected the graph, the job did not finish within `--timeout`, or it ended in error (quoted) | `--wait`/`--timeout`, or what the quoted error names |
5333
+ | <a id="COMFY_QUEUE_BEHIND"></a><a id="COMFY_PROMPT_ACCEPTED"></a><a id="COMFY_HISTORY_WITHIN"></a><a id="COMFY_RUN_OK"></a>`COMFY_QUEUE_BEHIND`, `COMFY_PROMPT_ACCEPTED`, `COMFY_HISTORY_WITHIN`, `COMFY_RUN_OK` | the job was still pending after `--wait` (its queue place is named; it is left on the box), the box rejected the graph, the job did not finish within `--timeout`, or it ended in error (quoted) | `--wait`/`--timeout`, or what the quoted error names |
5334
5334
  | <a id="COMFY_HISTORY_OUTPUTS"></a><a id="COMFY_VIEW_PRESENT"></a><a id="COMFY_MANIFEST_NAMED"></a><a id="COMFY_MANIFEST_IS_THIS_RUN"></a><a id="COMFY_LAYER_NAME"></a>`COMFY_HISTORY_OUTPUTS`, `COMFY_VIEW_PRESENT`, `COMFY_MANIFEST_NAMED`, `COMFY_MANIFEST_IS_THIS_RUN`, `COMFY_LAYER_NAME` | the job's outputs are missing, unreadable, belong to another run, or name a layer that is not a plain file name | the wrapper's version on the box; report it |
5335
5335
  | <a id="COMFY_IMAGE_PRESENT"></a><a id="COMFY_OUT_EMPTY"></a><a id="COMFY_OUT_FREE"></a>`COMFY_IMAGE_PRESENT`, `COMFY_OUT_EMPTY`, `COMFY_OUT_FREE` | no `--image`, an `--out` that already holds files, or a seed whose painting is already on disk | `--image`, `--out`, `--seed0` |
5336
5336
  | <a id="COMFY_PAINTING_SIZE"></a>`COMFY_PAINTING_SIZE` | the painting `comfy paint` got back is not twice the latent (a config with no `generation` block is `CONFIG_FIELD_PRESENT`, §6 *The config*) | `config.generation` |
@@ -5363,7 +5363,9 @@ or a joint.
5363
5363
  nothing cancelled. A job still pending after `--wait` seconds is refused with
5364
5364
  its place in the queue and left there. The box's image is pasted into the
5365
5365
  painting inside the mask only, so every pixel outside it is the painting's,
5366
- byte for byte. `--checkpoint-sha256` (64 hex characters) is required: the box
5366
+ byte for byte (for 16-bit or EXIF-oriented paintings, the byte-exact claim
5367
+ holds against the decoded 8-bit raster, and ComfyUI's `LoadImage` applies the
5368
+ EXIF transpose). `--checkpoint-sha256` (64 hex characters) is required: the box
5367
5369
  does not report a hash, so the receipt records the value **as declared, not
5368
5370
  measured**.
5369
5371
  - **foreground** runs no box and no model. The plate is the painting's pixels
@@ -5374,12 +5376,30 @@ inside, opaque black outside) and `receipt.json`, spec
5374
5376
  `rig-parts-plate-receipt/1` ([STABILITY](STABILITY.md#plate-receipt)). A receipted
5375
5377
  plate pass from this command is a recorded source step, not a repair.
5376
5378
 
5379
+ ### See-through mask grid mapping
5380
+
5381
+ For non-square paintings, `comfy seethrough` prepares the configured square
5382
+ before upload and records `input_transform` in `meta.json`, bound to the
5383
+ original PNG by `image_sha256`. `seethrough:` samples the union of layer
5384
+ alpha masks at transformed painting pixel centres with nearest sampling,
5385
+ using the recorded offsets and scale. Exactness holds for representable
5386
+ masks, and detail below the See-through grid's resolution is not recovered.
5387
+ The model receives the padded area as opaque black RGB because LoadImage
5388
+ separates alpha and GenerateLayers adds opaque alpha. The old wrapper-internal
5389
+ pad was transparent, so non-square model inputs differ from before.
5390
+ Square uploads omit the transform and retain the existing path. A legacy
5391
+ run on another grid still refuses `PLATE_MASK_GRID`; regenerate it through
5392
+ `comfy seethrough` to obtain a recorded transform. The record fields and
5393
+ sampling formula are specified in [STABILITY](STABILITY.md).
5394
+
5377
5395
  | rule | means | change |
5378
5396
  | --- | --- | --- |
5379
- | <a id="PLATE_MASK_SOURCE"></a><a id="PLATE_MASK_GRID"></a><a id="PLATE_MASK_VALUES"></a><a id="PLATE_MASK_EMPTY"></a>`PLATE_MASK_SOURCE`, `PLATE_MASK_GRID`, `PLATE_MASK_VALUES`, `PLATE_MASK_EMPTY` | no `--mask-from`, or a source directory holding no See-through run or no scene figure mask; a source on another grid than the painting; a `figure_rig.png` holding other than opaque white and black; a mask with no figure pixel | run `comfy seethrough` on the painting, or `assemble` with `config.scene`, at the painting's own size |
5397
+ | <a id="PLATE_MASK_SOURCE"></a><a id="PLATE_MASK_GRID"></a><a id="PLATE_MASK_VALUES"></a><a id="PLATE_MASK_EMPTY"></a>`PLATE_MASK_SOURCE`, `PLATE_MASK_GRID`, `PLATE_MASK_VALUES`, `PLATE_MASK_EMPTY` | no `--mask-from`, or a source directory holding no See-through run or no scene figure mask; a source on another grid without a valid recorded `input_transform`; a `figure_rig.png` holding other than opaque white and black; a mask with no figure pixel | run `comfy seethrough` on the original painting to record its input transform, or `assemble` with `config.scene` at the painting grid |
5398
+ | <a id="PLATE_MASK_RUN"></a>`PLATE_MASK_RUN` | the figure source has no readable `rig-run/1` assemble `run.json`, or its `figure_rig.png`, `parts.json` or declared `painting_in_rig.png` lacks exactly one matching output hash; or the See-through source has no readable `meta.json` with `image_sha256` and `layers` hashes, or a layer PNG on disk lacks a matching `layers` entry | re-run `assemble` with the source config to regenerate `run.json` and its `rig/` files together, or re-run `comfy seethrough` on the painting to regenerate `meta.json` and `parts/` together |
5399
+ | <a id="PLATE_MASK_PAINTING"></a>`PLATE_MASK_PAINTING` | `parts.json` has an invalid `painting_in_rig` declaration, its recorded painting is missing, undecodable or differs from its declared hash, or the supplied painting differs from the recorded opaque RGB; or the supplied painting's SHA-256 differs from a See-through source's `meta.json` `image_sha256` | use the original `--painting` file for this source, or re-run `assemble` or `comfy seethrough` on this painting |
5380
5400
  | <a id="PLATE_CHECKPOINT_SHA256"></a><a id="PLATE_MODEL_GIVEN"></a><a id="PLATE_CORE_GRID"></a>`PLATE_CHECKPOINT_SHA256`, `PLATE_MODEL_GIVEN`, `PLATE_CORE_GRID` | `--checkpoint-sha256` absent or not 64 hex characters; `--graph core` without `--model`; a painting off the multiple-of-8 grid under `--graph core` | the flag, or `--graph lama` |
5381
5401
  | <a id="PLATE_PAINTING_PRESENT"></a><a id="PLATE_OUT_EMPTY"></a>`PLATE_PAINTING_PRESENT`, `PLATE_OUT_EMPTY` | no `--painting` file, or an `--out` that already holds entries | `--painting`, `--out` |
5382
- | <a id="COMFY_QUEUE_BEHIND"></a><a id="COMFY_GPU_NAMED"></a><a id="COMFY_PLATE_SIZE"></a>`COMFY_QUEUE_BEHIND`, `COMFY_GPU_NAMED`, `COMFY_PLATE_SIZE` | the job was still pending after `--wait` (its queue place is named; it is left on the box); `/system_stats` does not name exactly one device; the box's image is not the painting's size | `--wait`, or the box |
5402
+ | <a id="COMFY_GPU_NAMED"></a><a id="COMFY_PLATE_SIZE"></a>`COMFY_GPU_NAMED`, `COMFY_PLATE_SIZE` | `/system_stats` does not name exactly one device; the box's image is not the painting's size | the box |
5383
5403
  | <a id="PLATE_RECEIPT_READ"></a><a id="PLATE_RECEIPT_SPEC"></a><a id="PLATE_RECEIPT_KEYS"></a><a id="PLATE_RECEIPT_FILE"></a><a id="PLATE_RECEIPT_HASH"></a>`PLATE_RECEIPT_READ`, `PLATE_RECEIPT_SPEC`, `PLATE_RECEIPT_KEYS`, `PLATE_RECEIPT_FILE`, `PLATE_RECEIPT_HASH` | the receipt read back before it is published is not JSON, not this spec, not in its key order, names a file that is gone, or records a sha256 that is not the file's | nothing to change by hand: the run is refused and `<out>` is not written |
5384
5404
 
5385
5405
  ### assemble
package/docs/STABILITY.md CHANGED
@@ -562,6 +562,34 @@ Painting generation metadata includes `upscale: {model, then}` (issue #698),
562
562
  read from the same `UPSCALE_MODEL` and `UPSCALE_THEN` constants as the graph.
563
563
  This adds provenance; it does not change model selection.
564
564
 
565
+ See-through run metadata (`meta.json`, written by `comfy seethrough`) includes
566
+ `image_sha256` (the SHA-256 of the original `--image` PNG bytes) and `layers`
567
+ (each written layer PNG's `{path, sha256}`, `path` relative to the run
568
+ directory) (issue #1188, additive under *What "stable" means here*). `comfy
569
+ plate` with `--mask-from seethrough:<dir>` binds every layer file read and
570
+ `--painting` against those hashes and refuses a legacy `meta.json` that lacks
571
+ them.
572
+
573
+ Non-square inputs are prepared by parts before upload (issue #1197).
574
+ Their additive `input_transform` records `source: [width,height]`,
575
+ `padded: [side,side]`, `pad: [left,top]` in padded pixels, `scale` (target
576
+ side divided by padded side), `resample: "parts-lanczos3-rgba"`,
577
+ `pad_fill: "rgb-black-opaque"`, `target: [resolution,resolution]` and `inverse: "nearest-pixel-centres"`.
578
+ The enclosing `image_sha256` is the single source-image hash. Preparation
579
+ zero-fills the square, places the source at floor-centred offsets, and runs
580
+ parts' RGBA Lanczos3 resampler. The wrapper receives the configured square.
581
+ LoadImage separates the PNG's alpha from RGB, and GenerateLayers adds opaque
582
+ alpha to that RGB. The model therefore receives the padded area as opaque
583
+ black RGB. The old wrapper-internal pad was transparent, so non-square model
584
+ inputs differ from before.
585
+ Square inputs keep the existing upload bytes and omit `input_transform`.
586
+ For each source pixel `(x,y)`, the inverse samples the layer union at
587
+ `floor((x+left+0.5)*scale), floor((y+top+0.5)*scale)`.
588
+ Exactness holds for representable masks, and detail below the See-through
589
+ grid's resolution is not recovered. Missing records on another grid and
590
+ invalid records refuse `PLATE_MASK_GRID`, while mismatched source bytes
591
+ refuse `PLATE_MASK_PAINTING`. Existing runs are never backfilled.
592
+
565
593
  Revision ancestry is additive (issue #531): a previous root `remesh.json` or
566
594
  `retune.json` is preserved at `provenance/<command>-<sha256>.json`, and optional
567
595
  `input.provenance` rows name its source, path, bytes and SHA-256. The chain survives
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "spine-parts",
3
- "version": "2.27.0",
3
+ "version": "2.27.2",
4
4
  "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.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -68,7 +68,7 @@
68
68
  },
69
69
  "dependencies": {
70
70
  "ag-psd": "^31.0.2",
71
- "@rig-c/core": "3.4.1"
71
+ "@rig-c/core": "3.5.0"
72
72
  },
73
73
  "devDependencies": {
74
74
  "@esotericsoftware/spine-core": "4.3.13",
package/src/assemble.ts CHANGED
@@ -4792,7 +4792,7 @@ export interface AssembleResult {
4792
4792
 
4793
4793
  /** Issue #953: the edge pixels `paintingEdges` resolved, the part pixels it changed, and the edge pixels it left, by reason. */
4794
4794
  export interface PaintingEdgeReading {
4795
- allocation?: PaintingAllocationReading;
4795
+ allocation: PaintingAllocationReading;
4796
4796
  resolved: number;
4797
4797
  unseparated: number;
4798
4798
  changed: number;
@@ -5912,7 +5912,7 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
5912
5912
  order.forEach((d, i) => {
5913
5913
  if (!('patch' in d) && e.changed[i].data.some((v) => v === 1)) edged.set(pieceAt(d).name, e.changed[i]);
5914
5914
  });
5915
- edgeReading = { resolved: e.resolved, unseparated: e.unseparated, changed: e.changed.reduce((a, m) => a + m.data.reduce((x, v) => x + v, 0), 0), skipped: e.skipped, allocation: e.allocation };
5915
+ edgeReading = { resolved: e.resolved, unseparated: e.unseparated, changed: e.changed.reduce((a, m) => a + m.data.reduce((x, v) => x + v, 0), 0), skipped: e.skipped, allocation: e.allocation as PaintingAllocationReading };
5916
5916
  }
5917
5917
  const pushedOf: FringePushed[][] = plan.map(() => []);
5918
5918
  const pushedOfCut: FringePushed[][] = cuts.map(() => []);
package/src/build.ts CHANGED
@@ -939,21 +939,24 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
939
939
  if (result.edgeResiduals === undefined) rmSync(residualPath, { force: true });
940
940
  else writeFileSync(residualPath, JSON.stringify(result.edgeResiduals, null, 2) + '\n');
941
941
  const allocation = result.paintingEdges?.allocation;
942
- if (allocation === undefined) rmSync(allocationPath, { force: true });
943
- else writeFileSync(allocationPath, JSON.stringify({ spec: 'rig-parts-painting-allocation/1',
944
- code: PAINTING_EDGE_COVERAGE_TRANSFER,
945
- stage: 'paintingEdges after piece guarding and restoration', grid: result.parts.rig_size,
946
- ...allocation, written_reports: allocationReports.map(report => report.file) }, null, 2) + '\n');
947
- const currentAllocationFiles = new Set(allocationReports.map(report => foldName(report.file)));
942
+ const currentAllocationFiles = new Set(allocation === undefined ? [] : allocationReports.map(report => foldName(report.file)));
948
943
  for (const file of previousAllocationFiles) {
949
944
  if (!currentAllocationFiles.has(foldName(file)) && !outputFiles.has(foldName(resolve(dirname(outs.partsJson), file)))) {
950
945
  rmSync(join(dirname(outs.partsJson), file), { force: true });
951
946
  }
952
947
  }
953
- for (const { file, report } of allocationReports) {
954
- writeFileSync(join(dirname(outs.partsJson), file), JSON.stringify(report, null, 2) + '\n');
955
- const count = report.coverageTransfers.reduce((n, row) => n + row.pixels.count, 0);
956
- log(`${PAINTING_EDGE_COVERAGE_TRANSFER}: set "${report.set}" ${count} native rig px; membership in ${file}`);
948
+ if (allocation === undefined) {
949
+ rmSync(allocationPath, { force: true });
950
+ } else {
951
+ writeFileSync(allocationPath, JSON.stringify({ spec: 'rig-parts-painting-allocation/1',
952
+ code: PAINTING_EDGE_COVERAGE_TRANSFER,
953
+ stage: 'paintingEdges after piece guarding and restoration', grid: result.parts.rig_size,
954
+ ...allocation, written_reports: allocationReports.map(report => report.file) }, null, 2) + '\n');
955
+ for (const { file, report } of allocationReports) {
956
+ writeFileSync(join(dirname(outs.partsJson), file), JSON.stringify(report, null, 2) + '\n');
957
+ const count = report.coverageTransfers.reduce((n, row) => n + row.pixels.count, 0);
958
+ log(`${PAINTING_EDGE_COVERAGE_TRANSFER}: set "${report.set}" ${count} native rig px; membership in ${file}`);
959
+ }
957
960
  }
958
961
  for (const { record, image, depthImage } of result.images) {
959
962
  writePng(join(outs.partsDir, `${record.name}.png`), image);
@@ -988,13 +991,11 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
988
991
  if (result.paintingEdges !== undefined) {
989
992
  const e = result.paintingEdges;
990
993
  log(`painting edges: ${e.resolved} edge px resolved from the painting (${e.unseparated} against the two reference colours where the window's far sides overlap), ${e.changed} part px changed; left as they were: ${e.skipped.cover} under a part the two-layer model does not carry, ${e.skipped.contrast} where the painting draws no edge (contrast below ${EDGE_CONTRAST}), ${e.skipped.locked} kept, feathered, a patch or a turn's moving pair, ${e.skipped.noBehind} with no behind pixel in the window; ${e.skipped.pieces} part px not written so a part's art keeps its pieces`);
991
- if (e.allocation !== undefined) {
992
- const a = e.allocation;
993
- log(`painting owner: ${a.supplier}; ${a.fallbackHeld} clean-fallback part px held by piece preservation`);
994
- log(`${PAINTING_EDGE_COVERAGE_TRANSFER}: ${a.coverageTransfers.reduce((n, row) => n + row.pixels.count, 0)} native rig px; membership in ${PAINTING_ALLOCATION_FILE}`);
995
- for (const [reason, px] of Object.entries(a.refused)) log(` painting owner refused: ${reason}, ${px} edge px`);
996
- for (const fault of a.lineage) log(` painting receiver refused: "${fault.receiver}", ${fault.reason}; one declared raw-plan ancestor is required`);
997
- }
994
+ const a = e.allocation;
995
+ log(`painting owner: ${a.supplier}; ${a.fallbackHeld} clean-fallback part px held by piece preservation`);
996
+ log(`${PAINTING_EDGE_COVERAGE_TRANSFER}: ${a.coverageTransfers.reduce((n, row) => n + row.pixels.count, 0)} native rig px; membership in ${PAINTING_ALLOCATION_FILE}`);
997
+ for (const [reason, px] of Object.entries(a.refused)) log(` painting owner refused: ${reason}, ${px} edge px`);
998
+ for (const fault of a.lineage) log(` painting receiver refused: "${fault.receiver}", ${fault.reason}; one declared raw-plan ancestor is required`);
998
999
  // Issue #996: under a declared busy ground, what the two ground rules left.
999
1000
  if (fields.ground === 'busy') log(` busy ground (assemble.ground): ${e.skipped.mix} behind-side px left that are not a mix of the two reference colours, ${e.skipped.support} part px not raised outside the part's own support`);
1000
1001
  }
@@ -2594,13 +2595,20 @@ export interface BuildResult {
2594
2595
  */
2595
2596
  export const RIGC_MODEL_DOCUMENT = 'skeleton.model.json';
2596
2597
 
2598
+ /**
2599
+ * rigc's run stamp (`rigc-run/1`), which `build` writes beside the artifact
2600
+ * since rig-c 3.5.0: a record of the run, not a Spine file, so it is not
2601
+ * counted as a second skeleton JSON either.
2602
+ */
2603
+ export const RIGC_RUN_STAMP = 'run.json';
2604
+
2597
2605
  /** The three artifact files of a packed build, each refused by name when absent. */
2598
2606
  export function artifactPaths(buildDir: string, pack: readonly PackLine[]): string[] {
2599
2607
  const problems: Problem[] = [];
2600
2608
  const names = existsSync(buildDir) ? readdirSync(buildDir).sort() : [];
2601
- const json = names.filter((n) => n.endsWith('.json') && n !== RIGC_MODEL_DOCUMENT);
2609
+ const json = names.filter((n) => n.endsWith('.json') && n !== RIGC_MODEL_DOCUMENT && n !== RIGC_RUN_STAMP);
2602
2610
  const atlas = names.filter((n) => n.endsWith('.atlas'));
2603
- if (json.length !== 1) problems.push({ code: 'BUILD_ARTIFACT_PRESENT', object: `${buildDir} skeleton JSON`, detail: `holds ${json.length} .json file(s) [${json.join(', ')}]; the packed build writes exactly one besides rigc's ${RIGC_MODEL_DOCUMENT}` });
2611
+ if (json.length !== 1) problems.push({ code: 'BUILD_ARTIFACT_PRESENT', object: `${buildDir} skeleton JSON`, detail: `holds ${json.length} .json file(s) [${json.join(', ')}]; the packed build writes exactly one besides rigc's ${RIGC_MODEL_DOCUMENT} and ${RIGC_RUN_STAMP}` });
2604
2612
  if (atlas.length !== 1) problems.push({ code: 'BUILD_ARTIFACT_PRESENT', object: `${buildDir} atlas`, detail: `holds ${atlas.length} .atlas file(s) [${atlas.join(', ')}]; the packed build writes exactly one` });
2605
2613
  if (pack.length === 0) problems.push({ code: 'BUILD_ARTIFACT_PRESENT', object: `${buildDir} packed page`, detail: 'rigc printed no pack line, so no packed page is named; the build runs with --pack and must print one' });
2606
2614
  for (const p of pack) {
@@ -14,8 +14,8 @@
14
14
  * into an output file.
15
15
  *
16
16
  * Every failure is a `PartsError` whose problem names the call, the value found
17
- * and the value required: a box that does not answer, a queue that does not
18
- * empty within the wait, a `/prompt` the box rejected (with its own
17
+ * and the value required: a box that does not answer, a job still pending in the
18
+ * queue past the wait, a `/prompt` the box rejected (with its own
19
19
  * `node_errors`), a job that does not reach `/history` within the timeout, a
20
20
  * job that ended in error, a history entry with no outputs.
21
21
  */
@@ -44,11 +44,6 @@ export interface ClientTiming {
44
44
  request: number;
45
45
  }
46
46
 
47
- export interface QueueState {
48
- running: number;
49
- pending: number;
50
- }
51
-
52
47
  export interface OutputImage {
53
48
  filename: string;
54
49
  subfolder: string;
@@ -118,36 +113,6 @@ export class ComfyClient {
118
113
  return out;
119
114
  }
120
115
 
121
- async queue(): Promise<QueueState> {
122
- const q = asObject(await this.json('GET', '/queue'));
123
- if (q === null || !Array.isArray(q.queue_running) || !Array.isArray(q.queue_pending)) {
124
- refuse('COMFY_REQUEST_OK', `GET ${this.host}/queue`, 'answered without queue_running and queue_pending arrays');
125
- }
126
- return { running: (q.queue_running as unknown[]).length, pending: (q.queue_pending as unknown[]).length };
127
- }
128
-
129
- /** Wait until nothing is running or pending, for at most `wait` seconds. Returns the seconds waited. */
130
- async waitQueueEmpty(wait: number, say: (line: string) => void): Promise<number> {
131
- const t0 = Date.now();
132
- let last: QueueState = await this.queue();
133
- let reported = false;
134
- while (last.running > 0 || last.pending > 0) {
135
- const waited = (Date.now() - t0) / 1000;
136
- if (waited >= wait) {
137
- refuse(
138
- 'COMFY_QUEUE_EMPTY',
139
- `${this.host}/queue`,
140
- `still held ${last.running} running and ${last.pending} pending after ${waited.toFixed(1)} s; an empty queue within --wait ${wait} s is required, and this adapter never queues behind someone else's job`,
141
- );
142
- }
143
- if (!reported) say(` queue busy (running ${last.running}, pending ${last.pending}) — waiting up to ${wait} s`);
144
- reported = true;
145
- await sleep(Math.min(this.timing.poll, Math.max(0, wait - waited)));
146
- last = await this.queue();
147
- }
148
- return (Date.now() - t0) / 1000;
149
- }
150
-
151
116
  /**
152
117
  * Where a queued prompt stands: `running` when the box is running it,
153
118
  * `pending` with its 1-based place among the pending jobs (and how many are
@@ -180,14 +145,19 @@ export class ComfyClient {
180
145
  const t0 = Date.now();
181
146
  let started: number | null = null;
182
147
  let lastPlace = -1;
148
+ // The minimum free VRAM while this job runs: sampled on every running poll,
149
+ // then merged with what `waitHistory` reads, so it is not a post-run reading.
150
+ const vramLow: Record<string, number> = {};
183
151
  for (;;) {
184
152
  const place = await this.queuePlace(id);
185
153
  if (place.state === 'absent') {
186
154
  const done = await this.waitHistory(id, Math.max(this.timing.request, this.timing.poll * 2));
187
- return { ...done, elapsed: (Date.now() - t0) / 1000 };
155
+ for (const [k, v] of Object.entries(done.vramLow)) if (!(k in vramLow) || v < vramLow[k]) vramLow[k] = v;
156
+ return { entry: done.entry, vramLow, elapsed: (Date.now() - t0) / 1000 };
188
157
  }
189
158
  const now = Date.now();
190
159
  if (place.state === 'running') {
160
+ for (const [k, v] of Object.entries(await this.vramFree())) if (!(k in vramLow) || v < vramLow[k]) vramLow[k] = v;
191
161
  if (started === null) {
192
162
  started = now;
193
163
  say(` prompt ${id} is running`);
@@ -13,11 +13,13 @@
13
13
  * or upscale model the box does not list is refused by name, not discovered
14
14
  * as a failed job.
15
15
  *
16
- * Every seed waits for an empty queue, and each painting is written only after
17
- * its job is in `/history`, not in error, and the image it saved decodes at
18
- * twice the latent size (4x-AnimeSharp then 0.5). A seed whose file already
19
- * exists in `--out` is refused before the first job, so no painting is
20
- * overwritten.
16
+ * Every seed is appended to the queue behind any other job — never in front,
17
+ * nothing reordered and nothing cancelled; a wait past `--wait` while pending
18
+ * is refused naming the job's place (`COMFY_QUEUE_BEHIND`) — and each painting
19
+ * is written only after its job is in `/history`, not in error, and the image
20
+ * it saved decodes at twice the latent size (4x-AnimeSharp then 0.5). A seed
21
+ * whose file already exists in `--out` is refused before the first job, so no
22
+ * painting is overwritten.
21
23
  *
22
24
  * The meta file holds the positive and negative prompts verbatim, what was
23
25
  * dropped as `DUP_WORDS`, where the pose words came from, the checkpoint, the
@@ -75,23 +77,19 @@ export async function runPainting(client: ComfyClient, run: PaintRun, say: (line
75
77
  refuseIfAny(checkGraph(probe, await client.objectInfo(), client.host, new Set(['30.image'])));
76
78
  say(' box: every node, input and model of the painting graph is on its /object_info');
77
79
 
78
- mkdirSync(run.out, { recursive: true });
79
80
  let skeletonRef: string | null = null;
80
81
  if (control !== null && drawn !== null && skeletonName !== null) {
81
82
  const local = join(run.out, `control_${drawn.label}.png`);
82
- writeFileSync(local, drawn.png);
83
83
  skeletonRef = await client.uploadImage(drawn.png, skeletonName);
84
84
  say(` control: ${drawn.from} at ${w}x${h} -> ${local}, uploaded as input/${skeletonRef}; ${control.model} strength ${control.strength} end ${control.end_percent}`);
85
85
  }
86
86
 
87
87
  const done: Painted[] = [];
88
88
  for (const seed of seeds) {
89
- const waited = await client.waitQueueEmpty(run.wait, say);
90
- if (waited > 0.05) say(` queue empty after ${waited.toFixed(1)} s`);
91
89
  const graph = paintingGraph(g, seed, prompts, `spine_parts_${run.config.key}_${seed}`, skeletonRef);
92
90
  const id = await client.submit(graph, 'rig-parts');
93
- say(` seed ${seed}: queued prompt ${id}; GPU job started`);
94
- const { entry, elapsed } = await client.waitHistory(id, run.timeout);
91
+ say(` seed ${seed}: appended prompt ${id} to the queue (behind any other job; nothing reordered or cancelled)`);
92
+ const { entry, elapsed } = await client.waitBehind(id, run.wait, run.timeout, say);
95
93
  const image = historyImages(entry).find((im) => im.type === 'output');
96
94
  if (image === undefined) {
97
95
  refuse('COMFY_HISTORY_OUTPUTS', `prompt ${id}`, `lists outputs from node(s) ${Object.keys(entry.outputs).join(', ')} and no image of type "output"; SaveImage (node 9) is required to have saved one`);
@@ -101,6 +99,10 @@ export async function runPainting(client: ComfyClient, run: PaintRun, say: (line
101
99
  if (img.width !== 2 * w || img.height !== 2 * h) {
102
100
  refuse('COMFY_PAINTING_SIZE', `output/${image.filename}`, `is ${img.width}x${img.height}; ${2 * w}x${2 * h} is required (latent ${w}x${h}, 4x-AnimeSharp then 0.5)`);
103
101
  }
102
+ if (done.length === 0) {
103
+ mkdirSync(run.out, { recursive: true });
104
+ if (control !== null && drawn !== null) writeFileSync(join(run.out, `control_${drawn.label}.png`), drawn.png);
105
+ }
104
106
  const file = join(run.out, `painting_${seed}.png`);
105
107
  writeFileSync(file, bytes);
106
108
  const meta = {
@@ -19,9 +19,6 @@
19
19
  * 6. the box's image is read back, required at the painting's size, pasted
20
20
  * into the painting inside the mask only, and written with its receipt
21
21
  * through `publishPlate` (staged, read back, then moved).
22
- *
23
- * ⚠️ This is a different queue policy from `comfy paint` and `comfy
24
- * seethrough`, which wait for an empty queue and never queue behind anyone.
25
22
  */
26
23
  import { refuseIfAny } from '../errors.ts';
27
24
  import { checkGraph, type Graph } from '../graphs.ts';
@@ -84,7 +81,7 @@ export async function runBackground(connect: () => ComfyClient, run: BackgroundR
84
81
  const from = parseMaskFrom(run.maskFrom);
85
82
  const painting = readPlatePainting(run.painting);
86
83
  const { width: W, height: H } = painting.raster;
87
- const source: FigureMask = readSourceMask(from.source, from.dir, W, H);
84
+ const source: FigureMask = readSourceMask(from.source, from.dir, W, H, painting.raster, painting.bytes);
88
85
  const checkpoint = declaredChecksum(run.checkpointSha256);
89
86
  if (run.graph === 'core') {
90
87
  if (run.model === undefined) refuse('PLATE_MODEL_GIVEN', '--model', 'is absent; the core graph needs the checkpoint the box loads, by its name on the box — there is no default checkpoint');
@@ -10,18 +10,19 @@
10
10
  * 2. every node and input of `workflows/seethrough.json` is on the box's
11
11
  * `/object_info` (`checkGraph`) — the wrapper not installed is refused
12
12
  * here, before anything is uploaded;
13
- * 3. the queue is empty within `--wait` (this never queues behind someone
14
- * else's job);
15
- * 4. the image is uploaded to the box's input directory and the graph queued;
16
- * 5. `/history/<id>` holds the job within `--timeout`, not in error, with
17
- * outputs;
18
- * 6. the manifest is found the way the wrapper leaves it: SavePSD writes the
13
+ * 3. the image is uploaded to the box's input directory and the graph is
14
+ * appended to the queue: behind every other job, never in front, nothing
15
+ * reordered and nothing cancelled; a wait past `--wait` while pending is
16
+ * refused naming the job's place (`COMFY_QUEUE_BEHIND`);
17
+ * 4. `/history/<id>` holds the job within `--timeout` once running, not in
18
+ * error, with outputs;
19
+ * 5. the manifest is found the way the wrapper leaves it: SavePSD writes the
19
20
  * layer PNGs and the manifest into the output directory but reports only
20
21
  * the previews to `/history`, and records the manifest's file name in
21
22
  * `output/seethrough_psd_info.log`. That log is overwritten by every run, so
22
23
  * the manifest it names must carry THIS run's prefix — a prefix with a
23
24
  * random suffix per run — or it is refused as another run's;
24
- * 7. everything is written into a staging directory beside `--out`, read back
25
+ * 6. everything is written into a staging directory beside `--out`, read back
25
26
  * through `readWrapperLayers`, and only then moved to `--out`. Emit only
26
27
  * after green: a directory the layer reader would refuse is never left at
27
28
  * the path the next stage reads.
@@ -32,7 +33,9 @@ import { refuseIfAny } from '../errors.ts';
32
33
  import { checkGraph, fillSeeThrough, type SeeThroughParams } from '../graphs.ts';
33
34
  import { readWrapperLayers } from '../layers.ts';
34
35
  import type { DepthBinding } from '../depthsheets.ts';
35
- import { decodePngBytes } from '../raster/png.ts';
36
+ import { sha256 } from '../plate.ts';
37
+ import { prepareSeeThroughInput } from '../seethrough-transform.ts';
38
+ import { decodePngBytes, encodePngBytes } from '../raster/png.ts';
36
39
  import { ComfyClient, historyImages, refuse } from './client.ts';
37
40
 
38
41
  export const SEETHROUGH_WORKFLOW = new URL('../../workflows/seethrough.json', import.meta.url);
@@ -81,6 +84,8 @@ export async function runSeeThrough(client: ComfyClient, run: SeeThroughRun, say
81
84
  const bytes = new Uint8Array(readFileSync(run.image));
82
85
  const img = decodePngBytes(bytes, run.image);
83
86
  assertOutFree(run.out);
87
+ const prepared = prepareSeeThroughInput(img, run.resolution);
88
+ const uploadBytes = prepared.transform === undefined ? bytes : encodePngBytes(prepared.image);
84
89
 
85
90
  await client.systemStats();
86
91
  const prefix = `${run.prefix}_${crypto.randomUUID().slice(0, 8)}`;
@@ -91,16 +96,14 @@ export async function runSeeThrough(client: ComfyClient, run: SeeThroughRun, say
91
96
  refuseIfAny(checkGraph(fillSeeThrough(template, params), info, client.host, new Set(['1.image'])));
92
97
  say(` box: every node and input of workflows/seethrough.json is on its /object_info`);
93
98
 
94
- const waited = await client.waitQueueEmpty(run.wait, say);
95
- say(` queue empty${waited > 0.05 ? ` after ${waited.toFixed(1)} s` : ''}`);
96
- const ref = await client.uploadImage(bytes, uploadName);
97
- say(` uploaded ${run.image} (${img.width}x${img.height}) as input/${ref}`);
99
+ const ref = await client.uploadImage(uploadBytes, uploadName);
100
+ say(` uploaded ${run.image} (${prepared.image.width}x${prepared.image.height}) as input/${ref}`);
98
101
  const graph = fillSeeThrough(template, { ...params, image: ref });
99
102
  const vramBefore = await client.vramFree();
100
103
  const id = await client.submit(graph, 'rig-parts');
101
- say(` queued prompt ${id} (prefix ${prefix}); GPU job started`);
102
- const { entry, vramLow, elapsed } = await client.waitHistory(id, run.timeout);
103
- say(` GPU job finished in ${elapsed.toFixed(1)} s`);
104
+ say(` appended prompt ${id} (prefix ${prefix}) to the queue (behind any other job; nothing reordered or cancelled)`);
105
+ const { entry, vramLow, elapsed } = await client.waitBehind(id, run.wait, run.timeout, say);
106
+ say(` GPU job finished ${elapsed.toFixed(1)} s after it was queued`);
104
107
  const previews = historyImages(entry);
105
108
  if (previews.length === 0) {
106
109
  refuse('COMFY_HISTORY_OUTPUTS', `prompt ${id}`, `lists outputs from node(s) ${Object.keys(entry.outputs).join(', ')} and no image; the graph's two preview SaveImage nodes are required to have saved`);
@@ -138,13 +141,23 @@ export async function runSeeThrough(client: ComfyClient, run: SeeThroughRun, say
138
141
  mkdirSync(join(stage, 'previews'), { recursive: true });
139
142
  try {
140
143
  for (const p of previews) writeFileSync(join(stage, 'previews', basename(p.filename)), await client.view(p.filename, p.subfolder, p.type));
141
- for (const l of layers) writeFileSync(join(stage, 'parts', `${l.name as string}.png`), await client.view(l.filename as string));
144
+ const layerHashes: Array<{ path: string; sha256: string }> = [];
145
+ for (const l of layers) {
146
+ const rel = `parts/${l.name as string}.png`;
147
+ const layerBytes = await client.view(l.filename as string);
148
+ writeFileSync(join(stage, rel), layerBytes);
149
+ layerHashes.push({ path: rel, sha256: sha256(layerBytes) });
150
+ }
142
151
  if (depth !== undefined) for (const l of layers) if ('depth_filename' in l) writeFileSync(join(stage, 'parts', `${l.name as string}_depth.png`), await client.view(l.depth_filename as string));
143
152
  writeFileSync(join(stage, 'layers.json'), manifestBytes);
144
153
  const set = readWrapperLayers(stage, depth);
154
+ if (prepared.transform !== undefined && (set.canvas.w !== run.resolution || set.canvas.h !== run.resolution)) {
155
+ refuse('COMFY_MANIFEST_NAMED', `output/${infoLog}`, `canvas is ${set.canvas.w}x${set.canvas.h}; the prepared ${run.resolution}x${run.resolution} input grid is required`);
156
+ }
145
157
  const meta = {
146
158
  prompt_id: id,
147
159
  image: run.image,
160
+ image_sha256: sha256(bytes),
148
161
  elapsed_s: Math.round(elapsed * 10) / 10,
149
162
  vram_free_before_gb: vramBefore,
150
163
  vram_free_low_gb: vramLow,
@@ -157,7 +170,9 @@ export async function runSeeThrough(client: ComfyClient, run: SeeThroughRun, say
157
170
  lama: run.lama,
158
171
  layer_count: layers.length,
159
172
  layer_names: layers.map((l) => l.name as string),
173
+ layers: layerHashes,
160
174
  canvas: [set.canvas.w, set.canvas.h],
175
+ ...(prepared.transform === undefined ? {} : { input_transform: prepared.transform }),
161
176
  };
162
177
  writeFileSync(join(stage, 'meta.json'), `${JSON.stringify(meta, null, 2)}\n`);
163
178
  if (existsSync(run.out)) rmdirSync(run.out);
@@ -732,8 +732,10 @@ function applyPaintingEdges(
732
732
  });
733
733
  if (held.length > 0) {
734
734
  if (!held.includes(event.target) && event.target === event.behind && held.every(i => i === event.front)) {
735
- // A held clear retains FRONT; BEHIND keeps its accepted own paint.
736
- planned[event.front].delete(event.p);
735
+ // Keep the original FRONT colour at the least coverage that preserves
736
+ // the guarded art bridge. BEHIND already carries its accepted own P.
737
+ const front = parts[event.front].data;
738
+ planned[event.front].set(event.p, [front[offset], front[offset + 1], front[offset + 2], OPAQUE_ALPHA_ABOVE + 1]);
737
739
  event.status = 'retained-front';
738
740
  } else {
739
741
  for (const i of event.affected) planned[i].delete(event.p);
package/src/plate.ts CHANGED
@@ -26,13 +26,15 @@
26
26
  * of every file it names; `verifyPlateReceipt` reads it back against the bytes
27
27
  * on disk. Every path in it is relative to the receipt's own directory.
28
28
  */
29
+ import { isSeeThroughTransform, inverseSeeThroughMask } from './seethrough-transform.ts';
29
30
  import { createHash } from 'node:crypto';
30
- import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
31
+ import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
31
32
  import { basename, dirname, join, relative, resolve } from 'node:path';
33
+ import { sourceInRig } from './assemble.ts';
32
34
  import { PartsError, type Problem } from './errors.ts';
33
35
  import type { Graph } from './graphs.ts';
34
- import { OPAQUE_ALPHA_ABOVE, readWrapperLayers } from './layers.ts';
35
- import { FIGURE_MASK_FILE } from './parts.ts';
36
+ import { type LayerSet, OPAQUE_ALPHA_ABOVE, readWrapperLayers } from './layers.ts';
37
+ import { FIGURE_MASK_FILE, PAINTING_IN_RIG_FILE } from './parts.ts';
36
38
  import { decodePngBytes, encodePngBytes } from './raster/png.ts';
37
39
  import { newRaster, type Raster } from './raster/types.ts';
38
40
 
@@ -104,50 +106,165 @@ export interface FigureMask {
104
106
  inside: Uint8Array;
105
107
  }
106
108
 
109
+ function maskRecord(path: string, code: string, remedy = 're-run assemble'): { record: Record<string, unknown>; bytes: Uint8Array } {
110
+ try {
111
+ const bytes = new Uint8Array(readFileSync(path));
112
+ const value: unknown = JSON.parse(new TextDecoder().decode(bytes));
113
+ if (typeof value === 'object' && value !== null && !Array.isArray(value)) return { record: value as Record<string, unknown>, bytes };
114
+ } catch (err) {
115
+ fail(code, path, `cannot read a JSON object (${(err as Error).message}); ${remedy}`);
116
+ }
117
+ return fail(code, path, `requires a JSON object; ${remedy}`);
118
+ }
119
+
120
+ /**
121
+ * comfy seethrough writes meta.json with image_sha256 and per-layer {path, sha256}.
122
+ * A missing or legacy meta without hashes is refused by name, every layer file
123
+ * readWrapperLayers read must match its recorded entry in meta.json, and the
124
+ * supplied --painting bytes must match image_sha256.
125
+ */
126
+ function bindSeeThroughSource(dir: string, set: LayerSet, paintingBytes: Uint8Array | undefined): Record<string, unknown> {
127
+ const root = resolve(dir);
128
+ const metaPath = join(root, 'meta.json');
129
+ const { record: meta } = maskRecord(metaPath, 'PLATE_MASK_RUN', 're-run comfy seethrough');
130
+ if (typeof meta.image_sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(meta.image_sha256) || !Array.isArray(meta.layers) || meta.layers.length === 0) {
131
+ fail('PLATE_MASK_RUN', metaPath, 'requires lowercase 64-hex image_sha256 and non-empty layers [{path, sha256}] from comfy seethrough; legacy or unstamped runs are refused — re-run comfy seethrough');
132
+ }
133
+ const entries = meta.layers as unknown[];
134
+ for (let i = 0; i < entries.length; i++) {
135
+ const e = entries[i];
136
+ if (typeof e !== 'object' || e === null || !('path' in e) || typeof e.path !== 'string' || e.path === '' ||
137
+ !('sha256' in e) || typeof e.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(e.sha256)) {
138
+ fail('PLATE_MASK_RUN', metaPath, `layers[${i}] requires a relative path and lowercase 64-hex sha256; re-run comfy seethrough`);
139
+ }
140
+ }
141
+ const typedEntries = entries as Array<{ path: string; sha256: string }>;
142
+ const readFiles = [...set.layers, ...set.hidden];
143
+ for (const layer of readFiles) {
144
+ if (layer.file === null) {
145
+ fail('PLATE_MASK_RUN', metaPath, `layer "${layer.name}" has no file on disk; re-run comfy seethrough`);
146
+ }
147
+ const key = relative(root, resolve(layer.file)).split('\\').join('/');
148
+ const matches = typedEntries.filter((e) => e.path === key);
149
+ const actual = sha256(new Uint8Array(readFileSync(layer.file)));
150
+ if (matches.length !== 1 || matches[0].sha256 !== actual) {
151
+ fail('PLATE_MASK_RUN', layer.file, `sha256 is ${actual}; ${metaPath} must record exactly one layers entry for ${JSON.stringify(key)} with that hash (found ${matches.length}, hashes ${JSON.stringify(matches.map((e) => e.sha256))}); re-run comfy seethrough`);
152
+ }
153
+ }
154
+ if (typedEntries.length !== readFiles.length) {
155
+ fail('PLATE_MASK_RUN', metaPath, `records ${typedEntries.length} layer hash(es), while layers.json has ${readFiles.length}; re-run comfy seethrough`);
156
+ }
157
+ if (paintingBytes === undefined) {
158
+ fail('PLATE_MASK_PAINTING', metaPath, 'the supplied painting bytes are required to compare with meta.json image_sha256');
159
+ }
160
+ const actualPainting = sha256(paintingBytes);
161
+ if (actualPainting !== meta.image_sha256) {
162
+ fail('PLATE_MASK_PAINTING', metaPath, `records image_sha256 ${meta.image_sha256}; the supplied painting has sha256 ${actualPainting} — use the painting this comfy seethrough run read`);
163
+ }
164
+ return meta;
165
+ }
166
+
167
+ /**
168
+ * Assemble writes run.json above rig/. A missing stamp is refused, including
169
+ * legacy outputs: their current mask bytes cannot be tied to a completed run.
170
+ * Bind parts.json too, so an old manifest cannot substitute another painting.
171
+ * The config hash identifies config bytes, not painting bytes. The existing
172
+ * painting_in_rig declaration binds those through assemble's RGB conversion.
173
+ */
174
+ function bindFigureSource(dir: string, parts: Record<string, unknown>, partsBytes: Uint8Array, maskBytes: Uint8Array, painting: Raster | undefined): void {
175
+ const root = dirname(resolve(dir));
176
+ const stampPath = join(root, 'run.json');
177
+ const { record: stamp } = maskRecord(stampPath, 'PLATE_MASK_RUN');
178
+ if (stamp.spec !== 'rig-run/1' || stamp.command !== 'assemble' || !Array.isArray(stamp.outputs)) {
179
+ fail('PLATE_MASK_RUN', stampPath, 'requires spec "rig-run/1", command "assemble" and outputs; re-run assemble');
180
+ }
181
+ const outputs = stamp.outputs as unknown[];
182
+ const checkOutput = (path: string, bytes: Uint8Array): void => {
183
+ const key = relative(root, path).split('\\').join('/');
184
+ const entries = outputs.filter((entry): entry is Record<string, unknown> =>
185
+ typeof entry === 'object' && entry !== null && 'path' in entry && entry.path === key);
186
+ const actual = sha256(bytes);
187
+ if (entries.length !== 1 || entries[0].sha256 !== actual) {
188
+ fail('PLATE_MASK_RUN', path, `sha256 is ${actual}; ${stampPath} must record exactly one outputs entry for ${JSON.stringify(key)} with that hash (found ${entries.length}, hashes ${JSON.stringify(entries.map(e => e.sha256))}); re-run assemble`);
189
+ }
190
+ };
191
+ checkOutput(join(dir, FIGURE_MASK_FILE), maskBytes);
192
+ checkOutput(join(dir, 'parts.json'), partsBytes);
193
+ // Legacy manifests may omit this additive declaration. When recorded, it
194
+ // must bind the supplied painting before either plate mode writes or connects.
195
+ if (parts.painting_in_rig === undefined) return;
196
+ const declared = parts.painting_in_rig;
197
+ if (typeof declared !== 'object' || declared === null || !('path' in declared) || declared.path !== PAINTING_IN_RIG_FILE ||
198
+ !('sha256' in declared) || typeof declared.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(declared.sha256) ||
199
+ !('resample' in declared) || declared.resample !== 'lanczos3-rgb-opaque') {
200
+ fail('PLATE_MASK_PAINTING', join(dir, 'parts.json'), 'painting_in_rig requires path "painting_in_rig.png", lowercase 64-hex sha256 and resample "lanczos3-rgb-opaque"; re-run assemble');
201
+ }
202
+ const path = join(dir, PAINTING_IN_RIG_FILE);
203
+ let bytes: Uint8Array;
204
+ try { bytes = new Uint8Array(readFileSync(path)); }
205
+ catch (err) { return fail('PLATE_MASK_PAINTING', path, `cannot read declared painting (${(err as Error).message}); re-run assemble`); }
206
+ checkOutput(path, bytes);
207
+ const found = sha256(bytes);
208
+ if (found !== declared.sha256) fail('PLATE_MASK_PAINTING', path, `sha256 is ${found}; parts.json records ${declared.sha256}; re-run assemble`);
209
+ if (painting === undefined) fail('PLATE_MASK_PAINTING', path, 'the supplied painting raster is required to compare with painting_in_rig');
210
+ let recorded: Raster;
211
+ try { recorded = decodePngBytes(bytes, path); }
212
+ catch (err) { return fail('PLATE_MASK_PAINTING', path, `cannot decode declared painting (${(err as Error).message}); re-run assemble`); }
213
+ const actual = sourceInRig(painting, painting.width, painting.height);
214
+ if (recorded.width !== actual.width || recorded.height !== actual.height || !recorded.data.every((v, i) => v === actual.data[i])) {
215
+ fail('PLATE_MASK_PAINTING', path, `records ${recorded.width}x${recorded.height} opaque RGB (file sha256 ${declared.sha256}); the supplied painting is ${actual.width}x${actual.height} with different decoded RGB; use the painting this assemble run read`);
216
+ }
217
+ }
218
+
107
219
  /**
108
220
  * The figure mask from its source, on its own grid. Refused by name: a source
109
221
  * directory that holds no mask (the missing tool named), a grid that is not
110
222
  * `width`x`height`, a `figure_rig.png` that is not the two values assemble
111
223
  * writes, and a mask with no figure pixel.
112
224
  */
113
- export function readSourceMask(source: MaskSource, dir: string, width: number, height: number): FigureMask {
225
+ export function readSourceMask(source: MaskSource, dir: string, width: number, height: number, painting?: Raster, paintingBytes?: Uint8Array): FigureMask {
114
226
  if (!existsSync(dir) || !statSync(dir).isDirectory()) {
115
227
  fail('PLATE_MASK_SOURCE', `${source}:${dir}`, `is not a directory; ${source === 'seethrough' ? 'a See-through run directory (from `rig-parts comfy seethrough`)' : 'an assemble output directory with parts.json and figure_rig.png'} is required`);
116
228
  }
117
- const inside = new Uint8Array(width * height);
229
+ let inside: Uint8Array = new Uint8Array(width * height);
118
230
  if (source === 'seethrough') {
119
231
  if (!existsSync(join(dir, 'layers.json'))) fail('PLATE_MASK_SOURCE', `${source}:${dir}`, 'holds no layers.json; the figure layers of a See-through run are required — run `rig-parts comfy seethrough` on the painting first');
120
232
  const set = readWrapperLayers(dir);
121
- if (set.canvas.w !== width || set.canvas.h !== height) {
122
- fail('PLATE_MASK_GRID', `${source}:${dir}`, `is a ${set.canvas.w}x${set.canvas.h} canvas; the painting's ${width}x${height} is required — the mask is never fitted, so run See-through on the painting at its own size`);
233
+ const meta = bindSeeThroughSource(dir, set, paintingBytes);
234
+ const transform = meta.input_transform;
235
+ const mapped = transform !== undefined && isSeeThroughTransform(transform, width, height, set.canvas.w, set.canvas.h);
236
+ if ((transform !== undefined && !mapped) || (!mapped && (set.canvas.w !== width || set.canvas.h !== height))) {
237
+ fail('PLATE_MASK_GRID', `${source}:${dir}`, `is a ${set.canvas.w}x${set.canvas.h} canvas; the painting's ${width}x${height} is required — a valid recorded input_transform is required for another grid; re-run comfy seethrough on the painting`);
123
238
  }
239
+ const maskWidth = set.canvas.w;
240
+ const maskHeight = set.canvas.h;
241
+ inside = new Uint8Array(maskWidth * maskHeight);
124
242
  for (const l of set.layers) {
125
243
  const w = l.right - l.left;
126
244
  for (let y = 0; y < l.bottom - l.top; y++) {
127
245
  const cy = l.top + y;
128
- if (cy < 0 || cy >= height) continue;
246
+ if (cy < 0 || cy >= maskHeight) continue;
129
247
  for (let x = 0; x < w; x++) {
130
248
  const cx = l.left + x;
131
- if (cx < 0 || cx >= width) continue;
132
- if (l.pixels.data[(y * w + x) * 4 + 3] > OPAQUE_ALPHA_ABOVE) inside[cy * width + cx] = 1;
249
+ if (cx < 0 || cx >= maskWidth) continue;
250
+ if (l.pixels.data[(y * w + x) * 4 + 3] > OPAQUE_ALPHA_ABOVE) inside[cy * maskWidth + cx] = 1;
133
251
  }
134
252
  }
135
253
  }
254
+ if (mapped) inside = inverseSeeThroughMask(inside, transform);
136
255
  } else {
137
256
  const partsPath = join(dir, 'parts.json');
138
257
  if (!existsSync(partsPath)) fail('PLATE_MASK_SOURCE', `${source}:${dir}`, 'holds no parts.json; an assemble output with config.scene is required — run `assemble` on the painting first');
139
- let scene: unknown;
140
- try {
141
- scene = (JSON.parse(readFileSync(partsPath, 'utf8')) as Record<string, unknown>).scene;
142
- } catch (err) {
143
- return fail('PLATE_MASK_SOURCE', partsPath, `does not parse as JSON (${(err as Error).message})`);
144
- }
258
+ const { record: parts, bytes: partsBytes } = maskRecord(partsPath, 'PLATE_MASK_SOURCE');
259
+ const scene = parts.scene;
145
260
  if (typeof scene !== 'object' || scene === null || (scene as Record<string, unknown>).figure_mask !== FIGURE_MASK_FILE) {
146
261
  fail('PLATE_MASK_SOURCE', partsPath, `declares no scene figure mask; a parts.json whose scene.figure_mask is "${FIGURE_MASK_FILE}" is required — assemble writes it under config.scene`);
147
262
  }
148
263
  const maskPath = join(dir, FIGURE_MASK_FILE);
149
264
  if (!existsSync(maskPath)) fail('PLATE_MASK_SOURCE', maskPath, 'no such file; parts.json declares it, and assemble writes it beside parts.json');
150
- const r = decodePngBytes(new Uint8Array(readFileSync(maskPath)), maskPath);
265
+ const maskBytes = new Uint8Array(readFileSync(maskPath));
266
+ bindFigureSource(dir, parts, partsBytes, maskBytes, painting);
267
+ const r = decodePngBytes(maskBytes, maskPath);
151
268
  if (r.width !== width || r.height !== height) {
152
269
  fail('PLATE_MASK_GRID', maskPath, `is ${r.width}x${r.height}; the painting's ${width}x${height} is required — the rig grid is not the painting's when the rig is scaled, and the mask is never fitted`);
153
270
  }
@@ -378,6 +495,8 @@ export interface PlateWrite {
378
495
  gpu: string | null;
379
496
  }
380
497
 
498
+ let foregroundStageSeq = 0;
499
+
381
500
  /**
382
501
  * Write `mask.png`, `plate.png` and `receipt.json` into a staging directory
383
502
  * beside `out`, read the receipt back against the bytes on disk, and only
@@ -387,8 +506,7 @@ export interface PlateWrite {
387
506
  export function publishPlate(w: PlateWrite): PlateReceipt {
388
507
  const parent = dirname(resolve(w.out));
389
508
  mkdirSync(parent, { recursive: true });
390
- const stage = join(parent, `.${basename(resolve(w.out))}.partial-${w.stageTag}`);
391
- mkdirSync(stage, { recursive: true });
509
+ const stage = mkdtempSync(join(parent, `.${basename(resolve(w.out))}.partial-${w.stageTag}-`));
392
510
  try {
393
511
  const mask = pngWithHash(maskImage(w.mask));
394
512
  const plate = pngWithHash(w.plate);
@@ -408,8 +526,17 @@ export function publishPlate(w: PlateWrite): PlateReceipt {
408
526
  writeFileSync(join(stage, PLATE_RECEIPT_FILE), receiptText(receipt));
409
527
  const problems = verifyPlateReceipt(join(stage, PLATE_RECEIPT_FILE));
410
528
  if (problems.length > 0) throw new PartsError(problems);
411
- if (existsSync(w.out)) rmdirSync(w.out);
412
- renameSync(stage, w.out);
529
+ assertPlateOutFree(w.out);
530
+ try {
531
+ if (existsSync(w.out)) rmdirSync(w.out);
532
+ renameSync(stage, w.out);
533
+ } catch (err) {
534
+ const code = (err as NodeJS.ErrnoException).code;
535
+ if (code === 'ENOTEMPTY' || code === 'EEXIST' || code === 'ENOTDIR' || code === 'EISDIR') {
536
+ fail('PLATE_OUT_EMPTY', w.out, 'is a file or a directory that holds entries; an absent or empty directory is required');
537
+ }
538
+ throw err;
539
+ }
413
540
  return receipt;
414
541
  } finally {
415
542
  if (existsSync(stage)) rmSync(stage, { recursive: true, force: true });
@@ -439,11 +566,11 @@ export interface ForegroundRun {
439
566
  export function runForeground(run: ForegroundRun): PlateReceipt {
440
567
  const from = parseMaskFrom(run.maskFrom);
441
568
  const painting = readPlatePainting(run.painting);
442
- const mask = readSourceMask(from.source, from.dir, painting.raster.width, painting.raster.height);
569
+ const mask = readSourceMask(from.source, from.dir, painting.raster.width, painting.raster.height, painting.raster, painting.bytes);
443
570
  assertPlateOutFree(run.out);
444
571
  return publishPlate({
445
572
  out: run.out,
446
- stageTag: 'foreground',
573
+ stageTag: `foreground-${process.pid}-${++foregroundStageSeq}`,
447
574
  mode: 'foreground',
448
575
  paintingPath: run.painting,
449
576
  paintingBytes: painting.bytes,
@@ -0,0 +1,62 @@
1
+ import { newRaster, type Raster } from './raster/types.ts';
2
+ import { resize } from './raster/resize.ts';
3
+
4
+ /** image_sha256 in the enclosing run record binds the source PNG bytes. */
5
+ export interface SeeThroughTransform {
6
+ source: [number, number];
7
+ padded: [number, number];
8
+ pad: [number, number];
9
+ scale: number;
10
+ resample: 'parts-lanczos3-rgba';
11
+ pad_fill: 'rgb-black-opaque';
12
+ target: [number, number];
13
+ inverse: 'nearest-pixel-centres';
14
+ }
15
+
16
+ /** Prepare only non-square images. Square inputs keep their original upload bytes. */
17
+ export function prepareSeeThroughInput(source: Raster, resolution: number): { image: Raster; transform?: SeeThroughTransform } {
18
+ if (source.width === source.height) return { image: source };
19
+ const side = Math.max(source.width, source.height);
20
+ const left = Math.floor((side - source.width) / 2);
21
+ const top = Math.floor((side - source.height) / 2);
22
+ const padded = newRaster(side, side);
23
+ for (let y = 0; y < source.height; y++) {
24
+ padded.data.set(source.data.subarray(y * source.width * 4, (y + 1) * source.width * 4), ((y + top) * side + left) * 4);
25
+ }
26
+ return {
27
+ image: resize(padded, resolution, resolution, 'lanczos3'),
28
+ transform: {
29
+ source: [source.width, source.height], padded: [side, side], pad: [left, top],
30
+ scale: resolution / side, resample: 'parts-lanczos3-rgba', pad_fill: 'rgb-black-opaque', target: [resolution, resolution], inverse: 'nearest-pixel-centres',
31
+ },
32
+ };
33
+ }
34
+
35
+ /** Validate all geometry before allocating or indexing a mapped mask. Offsets are read, never inferred. */
36
+ export function isSeeThroughTransform(value: unknown, width: number, height: number, targetWidth: number, targetHeight: number): value is SeeThroughTransform {
37
+ if (typeof value !== 'object' || value === null) return false;
38
+ const v = value as Record<string, unknown>;
39
+ const pair = (p: unknown): p is [number, number] => Array.isArray(p) && p.length === 2 && p.every(n => Number.isSafeInteger(n));
40
+ if (!pair(v.source) || !pair(v.padded) || !pair(v.pad) || !pair(v.target)) return false;
41
+ const side = v.padded[0];
42
+ return v.source[0] === width && v.source[1] === height && width !== height &&
43
+ side === Math.max(width, height) && v.padded[1] === side &&
44
+ v.pad[0] >= 0 && v.pad[1] >= 0 && v.pad[0] + width <= side && v.pad[1] + height <= side &&
45
+ v.target[0] === targetWidth && v.target[1] === targetHeight && targetWidth > 0 && targetWidth === targetHeight &&
46
+ v.scale === targetWidth / side && v.resample === 'parts-lanczos3-rgba' && v.pad_fill === 'rgb-black-opaque' && v.inverse === 'nearest-pixel-centres';
47
+ }
48
+
49
+ /** Sample the union at transformed source pixel centres. Sub-grid detail cannot be recovered. */
50
+ export function inverseSeeThroughMask(mask: Uint8Array, transform: SeeThroughTransform): Uint8Array {
51
+ const [width, height] = transform.source;
52
+ const [targetWidth, targetHeight] = transform.target;
53
+ const out = new Uint8Array(width * height);
54
+ for (let y = 0; y < height; y++) {
55
+ const ty = Math.min(targetHeight - 1, Math.floor((y + transform.pad[1] + 0.5) * transform.scale));
56
+ for (let x = 0; x < width; x++) {
57
+ const tx = Math.min(targetWidth - 1, Math.floor((x + transform.pad[0] + 0.5) * transform.scale));
58
+ out[y * width + x] = mask[ty * targetWidth + tx];
59
+ }
60
+ }
61
+ return out;
62
+ }