spine-parts 2.27.0 → 2.27.1

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` |
@@ -5377,9 +5377,11 @@ plate pass from this command is a recorded source step, not a repair.
5377
5377
  | rule | means | change |
5378
5378
  | --- | --- | --- |
5379
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 |
5380
+ | <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 | re-run `assemble` with the source config to regenerate `run.json` and its `rig/` files together |
5381
+ | <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 | use the original `--painting` file for this source, or re-run `assemble` to regenerate `parts.json` and `painting_in_rig.png` together |
5380
5382
  | <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
5383
  | <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 |
5384
+ | <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
5385
  | <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
5386
 
5385
5387
  ### assemble
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "spine-parts",
3
- "version": "2.27.0",
3
+ "version": "2.27.1",
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": {
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
  }
@@ -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);
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.
@@ -91,16 +92,14 @@ export async function runSeeThrough(client: ComfyClient, run: SeeThroughRun, say
91
92
  refuseIfAny(checkGraph(fillSeeThrough(template, params), info, client.host, new Set(['1.image'])));
92
93
  say(` box: every node and input of workflows/seethrough.json is on its /object_info`);
93
94
 
94
- const waited = await client.waitQueueEmpty(run.wait, say);
95
- say(` queue empty${waited > 0.05 ? ` after ${waited.toFixed(1)} s` : ''}`);
96
95
  const ref = await client.uploadImage(bytes, uploadName);
97
96
  say(` uploaded ${run.image} (${img.width}x${img.height}) as input/${ref}`);
98
97
  const graph = fillSeeThrough(template, { ...params, image: ref });
99
98
  const vramBefore = await client.vramFree();
100
99
  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`);
100
+ say(` appended prompt ${id} (prefix ${prefix}) to the queue (behind any other job; nothing reordered or cancelled)`);
101
+ const { entry, vramLow, elapsed } = await client.waitBehind(id, run.wait, run.timeout, say);
102
+ say(` GPU job finished ${elapsed.toFixed(1)} s after it was queued`);
104
103
  const previews = historyImages(entry);
105
104
  if (previews.length === 0) {
106
105
  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`);
@@ -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
@@ -29,10 +29,11 @@
29
29
  import { createHash } from 'node:crypto';
30
30
  import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
31
31
  import { basename, dirname, join, relative, resolve } from 'node:path';
32
+ import { sourceInRig } from './assemble.ts';
32
33
  import { PartsError, type Problem } from './errors.ts';
33
34
  import type { Graph } from './graphs.ts';
34
35
  import { OPAQUE_ALPHA_ABOVE, readWrapperLayers } from './layers.ts';
35
- import { FIGURE_MASK_FILE } from './parts.ts';
36
+ import { FIGURE_MASK_FILE, PAINTING_IN_RIG_FILE } from './parts.ts';
36
37
  import { decodePngBytes, encodePngBytes } from './raster/png.ts';
37
38
  import { newRaster, type Raster } from './raster/types.ts';
38
39
 
@@ -104,13 +105,76 @@ export interface FigureMask {
104
105
  inside: Uint8Array;
105
106
  }
106
107
 
108
+ function maskRecord(path: string, code: string): { record: Record<string, unknown>; bytes: Uint8Array } {
109
+ try {
110
+ const bytes = new Uint8Array(readFileSync(path));
111
+ const value: unknown = JSON.parse(new TextDecoder().decode(bytes));
112
+ if (typeof value === 'object' && value !== null && !Array.isArray(value)) return { record: value as Record<string, unknown>, bytes };
113
+ } catch (err) {
114
+ fail(code, path, `cannot read a JSON object (${(err as Error).message}); re-run assemble`);
115
+ }
116
+ return fail(code, path, 'requires a JSON object; re-run assemble');
117
+ }
118
+
119
+ /**
120
+ * Assemble writes run.json above rig/. A missing stamp is refused, including
121
+ * legacy outputs: their current mask bytes cannot be tied to a completed run.
122
+ * Bind parts.json too, so an old manifest cannot substitute another painting.
123
+ * The config hash identifies config bytes, not painting bytes. The existing
124
+ * painting_in_rig declaration binds those through assemble's RGB conversion.
125
+ */
126
+ function bindFigureSource(dir: string, parts: Record<string, unknown>, partsBytes: Uint8Array, maskBytes: Uint8Array, painting: Raster | undefined): void {
127
+ const root = dirname(resolve(dir));
128
+ const stampPath = join(root, 'run.json');
129
+ const { record: stamp } = maskRecord(stampPath, 'PLATE_MASK_RUN');
130
+ if (stamp.spec !== 'rig-run/1' || stamp.command !== 'assemble' || !Array.isArray(stamp.outputs)) {
131
+ fail('PLATE_MASK_RUN', stampPath, 'requires spec "rig-run/1", command "assemble" and outputs; re-run assemble');
132
+ }
133
+ const outputs = stamp.outputs as unknown[];
134
+ const checkOutput = (path: string, bytes: Uint8Array): void => {
135
+ const key = relative(root, path).split('\\').join('/');
136
+ const entries = outputs.filter((entry): entry is Record<string, unknown> =>
137
+ typeof entry === 'object' && entry !== null && 'path' in entry && entry.path === key);
138
+ const actual = sha256(bytes);
139
+ if (entries.length !== 1 || entries[0].sha256 !== actual) {
140
+ 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`);
141
+ }
142
+ };
143
+ checkOutput(join(dir, FIGURE_MASK_FILE), maskBytes);
144
+ checkOutput(join(dir, 'parts.json'), partsBytes);
145
+ // Legacy manifests may omit this additive declaration. When recorded, it
146
+ // must bind the supplied painting before either plate mode writes or connects.
147
+ if (parts.painting_in_rig === undefined) return;
148
+ const declared = parts.painting_in_rig;
149
+ if (typeof declared !== 'object' || declared === null || !('path' in declared) || declared.path !== PAINTING_IN_RIG_FILE ||
150
+ !('sha256' in declared) || typeof declared.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(declared.sha256) ||
151
+ !('resample' in declared) || declared.resample !== 'lanczos3-rgb-opaque') {
152
+ 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');
153
+ }
154
+ const path = join(dir, PAINTING_IN_RIG_FILE);
155
+ let bytes: Uint8Array;
156
+ try { bytes = new Uint8Array(readFileSync(path)); }
157
+ catch (err) { return fail('PLATE_MASK_PAINTING', path, `cannot read declared painting (${(err as Error).message}); re-run assemble`); }
158
+ checkOutput(path, bytes);
159
+ const found = sha256(bytes);
160
+ if (found !== declared.sha256) fail('PLATE_MASK_PAINTING', path, `sha256 is ${found}; parts.json records ${declared.sha256}; re-run assemble`);
161
+ if (painting === undefined) fail('PLATE_MASK_PAINTING', path, 'the supplied painting raster is required to compare with painting_in_rig');
162
+ let recorded: Raster;
163
+ try { recorded = decodePngBytes(bytes, path); }
164
+ catch (err) { return fail('PLATE_MASK_PAINTING', path, `cannot decode declared painting (${(err as Error).message}); re-run assemble`); }
165
+ const actual = sourceInRig(painting, painting.width, painting.height);
166
+ if (recorded.width !== actual.width || recorded.height !== actual.height || !recorded.data.every((v, i) => v === actual.data[i])) {
167
+ 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`);
168
+ }
169
+ }
170
+
107
171
  /**
108
172
  * The figure mask from its source, on its own grid. Refused by name: a source
109
173
  * directory that holds no mask (the missing tool named), a grid that is not
110
174
  * `width`x`height`, a `figure_rig.png` that is not the two values assemble
111
175
  * writes, and a mask with no figure pixel.
112
176
  */
113
- export function readSourceMask(source: MaskSource, dir: string, width: number, height: number): FigureMask {
177
+ export function readSourceMask(source: MaskSource, dir: string, width: number, height: number, painting?: Raster): FigureMask {
114
178
  if (!existsSync(dir) || !statSync(dir).isDirectory()) {
115
179
  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
180
  }
@@ -136,18 +200,16 @@ export function readSourceMask(source: MaskSource, dir: string, width: number, h
136
200
  } else {
137
201
  const partsPath = join(dir, 'parts.json');
138
202
  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
- }
203
+ const { record: parts, bytes: partsBytes } = maskRecord(partsPath, 'PLATE_MASK_SOURCE');
204
+ const scene = parts.scene;
145
205
  if (typeof scene !== 'object' || scene === null || (scene as Record<string, unknown>).figure_mask !== FIGURE_MASK_FILE) {
146
206
  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
207
  }
148
208
  const maskPath = join(dir, FIGURE_MASK_FILE);
149
209
  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);
210
+ const maskBytes = new Uint8Array(readFileSync(maskPath));
211
+ bindFigureSource(dir, parts, partsBytes, maskBytes, painting);
212
+ const r = decodePngBytes(maskBytes, maskPath);
151
213
  if (r.width !== width || r.height !== height) {
152
214
  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
215
  }
@@ -439,7 +501,7 @@ export interface ForegroundRun {
439
501
  export function runForeground(run: ForegroundRun): PlateReceipt {
440
502
  const from = parseMaskFrom(run.maskFrom);
441
503
  const painting = readPlatePainting(run.painting);
442
- const mask = readSourceMask(from.source, from.dir, painting.raster.width, painting.raster.height);
504
+ const mask = readSourceMask(from.source, from.dir, painting.raster.width, painting.raster.height, painting.raster);
443
505
  assertPlateOutFree(run.out);
444
506
  return publishPlate({
445
507
  out: run.out,