@rig-c/parts 0.0.0-stage → 1.5.4

package/src/comfy/client.ts

@@ -0,0 +1,245 @@
+/**
+ * A ComfyUI HTTP client: the six calls the adapter makes, each refusing by
+ * name.
+ *
+ * `src/comfy/` is the one directory under `src/` allowed a network and a clock
+ * (CLAUDE.md, *Conventions*): driving a GPU box is a network call with a
+ * wall-clock wait. What is decided — the words, the graph, the check of a
+ * graph against the box — is pure and lives in `src/graphs.ts`; this file only
+ * carries it.
+ *
+ * 🔒 **The host is the user's, given at run time, and nothing else.** It comes
+ * from `--host` or `COMFY_HOST`; with neither, `resolveHost` refuses. There is
+ * no default address anywhere in this package, and the host is never written
+ * into an output file.
+ *
+ * Every failure is a `PartsError` whose problem names the call, the value found
+ * and the value required: a box that does not answer, a queue that does not
+ * empty within the wait, a `/prompt` the box rejected (with its own
+ * `node_errors`), a job that does not reach `/history` within the timeout, a
+ * job that ended in error, a history entry with no outputs.
+ */
+import { PartsError } from '../errors.ts';
+
+export function refuse(code: string, object: string, detail: string): never {
+  throw new PartsError([{ code, object, detail }]);
+}
+
+/** The host from `--host`, else `COMFY_HOST`; refused when neither is set. A trailing slash is dropped. */
+export function resolveHost(flag: string | undefined, env: string | undefined): string {
+  const host = flag ?? (env !== undefined && env !== '' ? env : undefined);
+  if (host === undefined) {
+    refuse('COMFY_HOST_GIVEN', 'the ComfyUI host', 'is absent: neither --host nor COMFY_HOST is set; a URL such as http://<address>:8188 is required, and there is no default');
+  }
+  if (!/^https?:\/\/[^/\s]+/.test(host)) {
+    refuse('COMFY_HOST_GIVEN', 'the ComfyUI host', `is ${JSON.stringify(host)}; an http:// or https:// URL is required`);
+  }
+  return host.replace(/\/+$/, '');
+}
+
+export interface ClientTiming {
+  /** Seconds between two polls of /queue or /history. */
+  poll: number;
+  /** Seconds one plain request may take. */
+  request: number;
+}
+
+export interface QueueState {
+  running: number;
+  pending: number;
+}
+
+export interface OutputImage {
+  filename: string;
+  subfolder: string;
+  type: string;
+}
+
+export interface HistoryEntry {
+  outputs: Record<string, { images?: OutputImage[] }>;
+  status: { status_str?: string; completed?: boolean; messages?: unknown[] } | null;
+}
+
+const sleep = (s: number): Promise<void> => new Promise((r) => setTimeout(r, s * 1000));
+
+function asObject(v: unknown): Record<string, unknown> | null {
+  return typeof v === 'object' && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+}
+
+function brief(text: string, n = 600): string {
+  const t = text.replace(/\s+/g, ' ').trim();
+  return t.length > n ? `${t.slice(0, n - 3)}...` : t;
+}
+
+export class ComfyClient {
+  constructor(
+    readonly host: string,
+    readonly timing: ClientTiming,
+  ) {}
+
+  private async call(method: 'GET' | 'POST', path: string, body?: string | FormData, headers?: Record<string, string>, seconds = this.timing.request): Promise<Response> {
+    try {
+      return await fetch(`${this.host}${path}`, { method, body, headers, signal: AbortSignal.timeout(seconds * 1000) });
+    } catch (err) {
+      const e = err as Error;
+      const what = e.name === 'TimeoutError' ? `did not answer within ${seconds} s` : `could not be reached (${e.message})`;
+      return refuse('COMFY_REACHABLE', `${method} ${this.host}${path}`, `${what}; a running ComfyUI at this host is required`);
+    }
+  }
+
+  private async json(method: 'GET' | 'POST', path: string, body?: string | FormData, headers?: Record<string, string>): Promise<unknown> {
+    const res = await this.call(method, path, body, headers);
+    const text = await res.text();
+    if (!res.ok) refuse('COMFY_REQUEST_OK', `${method} ${this.host}${path}`, `answered HTTP ${res.status}: ${brief(text)}; HTTP 200 is required`);
+    try {
+      return JSON.parse(text);
+    } catch {
+      return refuse('COMFY_REQUEST_OK', `${method} ${this.host}${path}`, `answered HTTP ${res.status} with a body that is not JSON: ${brief(text, 200)}`);
+    }
+  }
+
+  /** `GET /system_stats`, or a refusal naming the host. */
+  async systemStats(): Promise<Record<string, unknown>> {
+    const s = asObject(await this.json('GET', '/system_stats'));
+    if (s === null) refuse('COMFY_REQUEST_OK', `GET ${this.host}/system_stats`, 'answered with something that is not an object');
+    return s;
+  }
+
+  /** Free VRAM per device in GB (two decimals), keyed by the device name's first word; empty when the box does not say. */
+  async vramFree(): Promise<Record<string, number>> {
+    const s = await this.systemStats();
+    const out: Record<string, number> = {};
+    const devices = Array.isArray(s.devices) ? s.devices : [];
+    for (const d of devices) {
+      const o = asObject(d);
+      if (o === null || typeof o.name !== 'string' || typeof o.vram_free !== 'number') continue;
+      out[o.name.split(' ')[0]] = Math.round((o.vram_free / 1024 ** 3) * 100) / 100;
+    }
+    return out;
+  }
+
+  async queue(): Promise<QueueState> {
+    const q = asObject(await this.json('GET', '/queue'));
+    if (q === null || !Array.isArray(q.queue_running) || !Array.isArray(q.queue_pending)) {
+      refuse('COMFY_REQUEST_OK', `GET ${this.host}/queue`, 'answered without queue_running and queue_pending arrays');
+    }
+    return { running: (q.queue_running as unknown[]).length, pending: (q.queue_pending as unknown[]).length };
+  }
+
+  /** Wait until nothing is running or pending, for at most `wait` seconds. Returns the seconds waited. */
+  async waitQueueEmpty(wait: number, say: (line: string) => void): Promise<number> {
+    const t0 = Date.now();
+    let last: QueueState = await this.queue();
+    let reported = false;
+    while (last.running > 0 || last.pending > 0) {
+      const waited = (Date.now() - t0) / 1000;
+      if (waited >= wait) {
+        refuse(
+          'COMFY_QUEUE_EMPTY',
+          `${this.host}/queue`,
+          `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`,
+        );
+      }
+      if (!reported) say(`  queue busy (running ${last.running}, pending ${last.pending}) — waiting up to ${wait} s`);
+      reported = true;
+      await sleep(Math.min(this.timing.poll, Math.max(0, wait - waited)));
+      last = await this.queue();
+    }
+    return (Date.now() - t0) / 1000;
+  }
+
+  /** `GET /object_info`: every node class the box has, with its inputs. */
+  async objectInfo(): Promise<Record<string, unknown>> {
+    const o = asObject(await this.json('GET', '/object_info'));
+    if (o === null) refuse('COMFY_REQUEST_OK', `GET ${this.host}/object_info`, 'answered with something that is not an object of node classes');
+    return o;
+  }
+
+  /** `POST /upload/image` into the box's input directory, overwriting; returns the name LoadImage takes. */
+  async uploadImage(bytes: Uint8Array, name: string): Promise<string> {
+    const form = new FormData();
+    form.append('image', new Blob([bytes], { type: 'image/png' }), name);
+    form.append('overwrite', 'true');
+    form.append('type', 'input');
+    form.append('subfolder', '');
+    const res = asObject(await this.json('POST', '/upload/image', form));
+    if (res === null || typeof res.name !== 'string') refuse('COMFY_REQUEST_OK', `POST ${this.host}/upload/image`, 'answered without the uploaded file\'s name');
+    return typeof res.subfolder === 'string' && res.subfolder !== '' ? `${res.subfolder}/${res.name}` : res.name;
+  }
+
+  /** `POST /prompt`; returns the prompt id. A rejection is refused with the box's own error text. */
+  async submit(graph: unknown, clientId: string): Promise<string> {
+    const res = await this.call('POST', '/prompt', JSON.stringify({ prompt: graph, client_id: clientId }), { 'Content-Type': 'application/json' });
+    const text = await res.text();
+    if (!res.ok) refuse('COMFY_PROMPT_ACCEPTED', `POST ${this.host}/prompt`, `rejected the graph with HTTP ${res.status}: ${brief(text, 1500)}`);
+    let id: unknown;
+    try {
+      id = asObject(JSON.parse(text))?.prompt_id;
+    } catch {
+      id = undefined;
+    }
+    if (typeof id !== 'string') refuse('COMFY_PROMPT_ACCEPTED', `POST ${this.host}/prompt`, `answered without a prompt_id: ${brief(text, 300)}`);
+    return id;
+  }
+
+  /**
+   * Poll `/history/<id>` until the job is there, for at most `timeout`
+   * seconds, and check the box is still answering between polls. Returns the
+   * entry and the lowest free VRAM seen per device. An entry whose status is
+   * an error is refused with the box's messages; so is an entry with no
+   * outputs at all, because a finished job that saved nothing is not a result.
+   */
+  async waitHistory(id: string, timeout: number): Promise<{ entry: HistoryEntry; vramLow: Record<string, number>; elapsed: number }> {
+    const t0 = Date.now();
+    const vramLow: Record<string, number> = {};
+    for (;;) {
+      for (const [k, v] of Object.entries(await this.vramFree())) if (!(k in vramLow) || v < vramLow[k]) vramLow[k] = v;
+      const h = asObject(await this.json('GET', `/history/${encodeURIComponent(id)}`));
+      const raw = h === null ? null : asObject(h[id]);
+      if (raw !== null) {
+        const entry: HistoryEntry = {
+          outputs: (asObject(raw.outputs) ?? {}) as HistoryEntry['outputs'],
+          status: asObject(raw.status) as HistoryEntry['status'],
+        };
+        const elapsed = (Date.now() - t0) / 1000;
+        if (entry.status?.status_str === 'error') {
+          refuse('COMFY_RUN_OK', `prompt ${id}`, `ended with status "error": ${brief(JSON.stringify(entry.status.messages ?? []), 2000)}`);
+        }
+        if (Object.keys(entry.outputs).length === 0) {
+          refuse(
+            'COMFY_HISTORY_OUTPUTS',
+            `prompt ${id}`,
+            `reached /history with status ${JSON.stringify(entry.status?.status_str ?? null)} and no outputs; a finished job lists what its save nodes wrote, and one that lists nothing is not a result`,
+          );
+        }
+        return { entry, vramLow, elapsed };
+      }
+      const waited = (Date.now() - t0) / 1000;
+      if (waited >= timeout) {
+        refuse('COMFY_HISTORY_WITHIN', `prompt ${id}`, `was not in /history after ${waited.toFixed(1)} s; it is required within --timeout ${timeout} s (the job was left on the box, not cancelled)`);
+      }
+      await sleep(Math.min(this.timing.poll, Math.max(0, timeout - waited)));
+    }
+  }
+
+  /** `GET /view` of one file in the box's output (or input) directory. */
+  async view(filename: string, subfolder = '', type = 'output'): Promise<Uint8Array> {
+    const q = new URLSearchParams({ filename, subfolder, type }).toString();
+    const res = await this.call('GET', `/view?${q}`, undefined, undefined, Math.max(this.timing.request, 180));
+    if (!res.ok) {
+      refuse('COMFY_VIEW_PRESENT', `${type}/${subfolder === '' ? '' : `${subfolder}/`}${filename}`, `answered HTTP ${res.status} on /view; the file the job reported is required`);
+    }
+    return new Uint8Array(await res.arrayBuffer());
+  }
+}
+
+/** The images a history entry lists, in node-id order then list order. */
+export function historyImages(entry: HistoryEntry): OutputImage[] {
+  const out: OutputImage[] = [];
+  for (const id of Object.keys(entry.outputs).sort((a, b) => Number(a) - Number(b) || a.localeCompare(b))) {
+    for (const im of entry.outputs[id]?.images ?? []) {
+      if (typeof im?.filename === 'string') out.push({ filename: im.filename, subfolder: typeof im.subfolder === 'string' ? im.subfolder : '', type: typeof im.type === 'string' ? im.type : 'output' });
+    }
+  }
+  return out;
+}

package/src/comfy/index.ts

@@ -0,0 +1,19 @@
+/**
+ * The optional ComfyUI adapter: the painting and the See-through run, driven
+ * on a GPU box the user names at run time (`--host` or `COMFY_HOST`).
+ *
+ * `src/` is pure — no clock, no randomness, no network — and this directory is
+ * the one exception it has, because driving a GPU box IS a network call with a
+ * wall-clock wait. Keeping the exception to one named directory is what keeps
+ * the rule checkable: the selftest's purity control (`TY06`) scans every file
+ * in `src/` except this directory, and a network call that appears anywhere
+ * else is refused by name. What can be pure is kept out of here — the words
+ * and the graphs are `src/graphs.ts`, the control skeleton `src/skeleton.ts`,
+ * the two See-through inputs `src/inputs.ts` — so the purity scan covers them.
+ *
+ * ComfyUI is optional: See-through can be run by any route in the README, and
+ * everything after it reads files.
+ */
+export { ComfyClient, type ClientTiming, resolveHost } from './client.ts';
+export { runPainting, type PaintRun, type Painted } from './painting.ts';
+export { runSeeThrough, type SeeThroughResult, type SeeThroughRun } from './seethrough.ts';

package/src/comfy/painting.ts

@@ -0,0 +1,136 @@
+/**
+ * The painting, generated on a ComfyUI box from the config's inline
+ * `generation` block: `painting_<seed>.png` and `painting_<seed>_meta.json`
+ * per seed, and `control_<skeleton>.png` when the config asks for structural
+ * control — `<skeleton>` is the built-in's name, or for a pose file (issue
+ * #198) `pose-` and the first 12 hex digits of the image's sha256, so two pose
+ * files drawn at one size never share a name on the box.
+ *
+ * The words and the graph are `src/graphs.ts` (`buildPrompts`,
+ * `paintingGraph`) and the skeleton is `src/skeleton.ts`; this file carries
+ * them to the box and back. Before anything is uploaded the whole graph is
+ * checked against the box's `/object_info` — a checkpoint, LoRA, ControlNet
+ * or upscale model the box does not list is refused by name, not discovered
+ * as a failed job.
+ *
+ * Every seed waits for an empty queue, and each painting is written only after
+ * its job is in `/history`, not in error, and the image it saved decodes at
+ * twice the latent size (4x-AnimeSharp then 0.5). A seed whose file already
+ * exists in `--out` is refused before the first job, so no painting is
+ * overwritten.
+ *
+ * The meta file holds the positive and negative prompts verbatim, what was
+ * dropped as `DUP_WORDS`, where the pose words came from, the checkpoint, the
+ * LoRAs, control and sampler as the graph used them (defaults resolved, each
+ * by its named fields, so an annotation or an `x-` record its author wrote in
+ * the config never reaches the meta), the elapsed seconds and the prompt id —
+ * never the host.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ControlPose, PaintConfig } from '../config.ts';
+import { type Problem, refuseIfAny } from '../errors.ts';
+import { buildPrompts, checkGraph, paintingGraph, resolvedControl, resolvedLoras, resolvedSampler } from '../graphs.ts';
+import { decodePngBytes, encodePngBytes } from '../raster/png.ts';
+import { isSkeletonName, renderSkeleton } from '../skeleton.ts';
+import { ComfyClient, historyImages, refuse } from './client.ts';
+
+export interface PaintRun {
+  /** Read through `loadPaintConfig(path)`, which has already required and checked `generation`. */
+  config: PaintConfig;
+  /** The pose file `generation.control.skeleton` names, as `loadPaintConfig` read it; null for a built-in or no control. */
+  pose: ControlPose | null;
+  out: string;
+  seeds: number;
+  seed0: number;
+  wait: number;
+  timeout: number;
+}
+
+export interface Painted {
+  seed: number;
+  file: string;
+  elapsed: number;
+  size: [number, number];
+}
+
+export async function runPainting(client: ComfyClient, run: PaintRun, say: (line: string) => void): Promise<Painted[]> {
+  const g = run.config.generation;
+  const seeds = Array.from({ length: run.seeds }, (_, i) => run.seed0 + i);
+  const taken: Problem[] = seeds
+    .filter((s) => existsSync(join(run.out, `painting_${s}.png`)))
+    .map((s) => ({ code: 'COMFY_OUT_FREE', object: join(run.out, `painting_${s}.png`), detail: 'already exists; a seed whose painting is on disk is not generated again over it' }));
+  refuseIfAny(taken);
+  const prompts = buildPrompts(g);
+  const [w, h] = g.latent;
+  say(`  positive (${prompts.positive.length} chars, pose words from ${prompts.poseFrom}${prompts.dropped.length > 0 ? `, dropped ${prompts.dropped.join(' | ')}` : ''}): ${prompts.positive}`);
+  say(`  negative (${prompts.negative.length} chars): ${prompts.negative}`);
+
+  await client.systemStats();
+  const control = g.control === undefined ? null : resolvedControl(g.control);
+  const drawn = control === null ? null : controlImage(control.skeleton, run.pose, w, h);
+  const skeletonName = drawn === null ? null : `spine_parts_${drawn.label}_${w}x${h}.png`;
+  const probe = paintingGraph(g, seeds[0], prompts, `spine_parts_${run.config.key}_${seeds[0]}`, skeletonName);
+  refuseIfAny(checkGraph(probe, await client.objectInfo(), client.host, new Set(['30.image'])));
+  say('  box: every node, input and model of the painting graph is on its /object_info');
+
+  mkdirSync(run.out, { recursive: true });
+  let skeletonRef: string | null = null;
+  if (control !== null && drawn !== null && skeletonName !== null) {
+    const local = join(run.out, `control_${drawn.label}.png`);
+    writeFileSync(local, drawn.png);
+    skeletonRef = await client.uploadImage(drawn.png, skeletonName);
+    say(`  control: ${drawn.from} at ${w}x${h} -> ${local}, uploaded as input/${skeletonRef}; ${control.model} strength ${control.strength} end ${control.end_percent}`);
+  }
+
+  const done: Painted[] = [];
+  for (const seed of seeds) {
+    const waited = await client.waitQueueEmpty(run.wait, say);
+    if (waited > 0.05) say(`  queue empty after ${waited.toFixed(1)} s`);
+    const graph = paintingGraph(g, seed, prompts, `spine_parts_${run.config.key}_${seed}`, skeletonRef);
+    const id = await client.submit(graph, 'rig-parts');
+    say(`  seed ${seed}: queued prompt ${id}; GPU job started`);
+    const { entry, elapsed } = await client.waitHistory(id, run.timeout);
+    const image = historyImages(entry).find((im) => im.type === 'output');
+    if (image === undefined) {
+      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`);
+    }
+    const bytes = await client.view(image.filename, image.subfolder, image.type);
+    const img = decodePngBytes(bytes, `output/${image.filename}`);
+    if (img.width !== 2 * w || img.height !== 2 * h) {
+      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)`);
+    }
+    const file = join(run.out, `painting_${seed}.png`);
+    writeFileSync(file, bytes);
+    const meta = {
+      seed,
+      elapsed_s: Math.round(elapsed * 10) / 10,
+      latent: [w, h],
+      size: [img.width, img.height],
+      key: run.config.key,
+      checkpoint: g.checkpoint,
+      loras: resolvedLoras(g.loras),
+      sampler: resolvedSampler(g.sampler),
+      control,
+      pose_from: prompts.poseFrom,
+      dropped: prompts.dropped,
+      positive: prompts.positive,
+      negative: prompts.negative,
+      prompt_id: id,
+    };
+    writeFileSync(join(run.out, `painting_${seed}_meta.json`), `${JSON.stringify(meta, null, 1)}\n`);
+    say(`  seed ${seed}: GPU job finished in ${elapsed.toFixed(1)} s -> ${file} (${img.width}x${img.height})`);
+    done.push({ seed, file, elapsed, size: [img.width, img.height] });
+  }
+  return done;
+}
+
+/** The control image for a built-in skeleton or the pose file read beside the config, with the name it is written and uploaded under. */
+function controlImage(skeleton: string, pose: ControlPose | null, w: number, h: number): { png: Uint8Array; label: string; from: string } {
+  if (isSkeletonName(skeleton)) return { png: encodePngBytes(renderSkeleton(skeleton, w, h)), label: skeleton, from: `${skeleton} skeleton` };
+  // loadPaintConfig reads the file a non-built-in skeleton names, or refuses; a run without it skipped the loader.
+  if (pose === null) throw new Error(`runPainting: generation.control.skeleton names the pose file "${skeleton}" and no pose was read; load the config through loadPaintConfig`);
+  const png = encodePngBytes(renderSkeleton(pose.points, w, h));
+  return { png, label: `pose-${createHash('sha256').update(png).digest('hex').slice(0, 12)}`, from: `pose file ${pose.file}` };
+}

package/src/comfy/seethrough.ts

@@ -0,0 +1,171 @@
+/**
+ * One See-through run on a ComfyUI box, into a directory in the wrapper form
+ * `src/layers.ts` reads: `layers.json` (the wrapper's manifest, the bytes the
+ * box wrote), `parts/<tag>.png` (one RGBA PNG per layer), `meta.json` (this
+ * run's record) and `previews/` (the two preview sheets the graph saves).
+ *
+ * The route, in order, each step refusing by name:
+ *
+ * 1. the box answers `/system_stats`;
+ * 2. every node and input of `workflows/seethrough.json` is on the box's
+ *    `/object_info` (`checkGraph`) — the wrapper not installed is refused
+ *    here, before anything is uploaded;
+ * 3. the queue is empty within `--wait` (this never queues behind someone
+ *    else's job);
+ * 4. the image is uploaded to the box's input directory and the graph queued;
+ * 5. `/history/<id>` holds the job within `--timeout`, not in error, with
+ *    outputs;
+ * 6. the manifest is found the way the wrapper leaves it: SavePSD writes the
+ *    layer PNGs and the manifest into the output directory but reports only
+ *    the previews to `/history`, and records the manifest's file name in
+ *    `output/seethrough_psd_info.log`. That log is overwritten by every run, so
+ *    the manifest it names must carry THIS run's prefix — a prefix with a
+ *    random suffix per run — or it is refused as another run's;
+ * 7. everything is written into a staging directory beside `--out`, read back
+ *    through `readWrapperLayers`, and only then moved to `--out`. Emit only
+ *    after green: a directory the layer reader would refuse is never left at
+ *    the path the next stage reads.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { refuseIfAny } from '../errors.ts';
+import { checkGraph, fillSeeThrough, type SeeThroughParams } from '../graphs.ts';
+import { readWrapperLayers } from '../layers.ts';
+import { decodePngBytes } from '../raster/png.ts';
+import { ComfyClient, historyImages, refuse } from './client.ts';
+
+export const SEETHROUGH_WORKFLOW = new URL('../../workflows/seethrough.json', import.meta.url);
+export const PSD_INFO_LOG = 'seethrough_psd_info.log';
+
+export interface SeeThroughRun {
+  image: string;
+  out: string;
+  /** The prefix before the per-run suffix. */
+  prefix: string;
+  resolution: number;
+  steps: number;
+  seed: number;
+  offload: boolean;
+  lama: boolean;
+  quant: 'none' | 'nf4';
+  wait: number;
+  timeout: number;
+}
+
+export interface SeeThroughResult {
+  promptId: string;
+  prefix: string;
+  elapsed: number;
+  layers: string[];
+  canvas: [number, number];
+  previews: string[];
+}
+
+/** An out directory that is absent or empty; anything else is refused, because mixing two runs' layers is a set nobody can read. */
+export function assertOutFree(out: string): void {
+  if (existsSync(out) && readdirSync(out).length > 0) {
+    refuse('COMFY_OUT_EMPTY', out, `holds ${readdirSync(out).length} entr(ies); an absent or empty directory is required, so one run's layers are never mixed with another's`);
+  }
+}
+
+function safeName(name: string): boolean {
+  return name !== '' && !name.startsWith('.') && !/[\\/]/.test(name);
+}
+
+export async function runSeeThrough(client: ComfyClient, run: SeeThroughRun, say: (line: string) => void): Promise<SeeThroughResult> {
+  if (!existsSync(run.image)) refuse('COMFY_IMAGE_PRESENT', run.image, 'no such file; the PNG See-through is to decompose is required');
+  const bytes = new Uint8Array(readFileSync(run.image));
+  const img = decodePngBytes(bytes, run.image);
+  assertOutFree(run.out);
+
+  await client.systemStats();
+  const prefix = `${run.prefix}_${crypto.randomUUID().slice(0, 8)}`;
+  const uploadName = `${prefix}_input.png`;
+  const template: unknown = JSON.parse(readFileSync(SEETHROUGH_WORKFLOW, 'utf8'));
+  const params: SeeThroughParams = { image: uploadName, seed: run.seed, resolution: run.resolution, steps: run.steps, quant: run.quant, offload: run.offload, lama: run.lama, prefix };
+  const info = await client.objectInfo();
+  refuseIfAny(checkGraph(fillSeeThrough(template, params), info, client.host, new Set(['1.image'])));
+  say(`  box: every node and input of workflows/seethrough.json is on its /object_info`);
+
+  const waited = await client.waitQueueEmpty(run.wait, say);
+  say(`  queue empty${waited > 0.05 ? ` after ${waited.toFixed(1)} s` : ''}`);
+  const ref = await client.uploadImage(bytes, uploadName);
+  say(`  uploaded ${run.image} (${img.width}x${img.height}) as input/${ref}`);
+  const graph = fillSeeThrough(template, { ...params, image: ref });
+  const vramBefore = await client.vramFree();
+  const id = await client.submit(graph, 'rig-parts');
+  say(`  queued prompt ${id} (prefix ${prefix}); GPU job started`);
+  const { entry, vramLow, elapsed } = await client.waitHistory(id, run.timeout);
+  say(`  GPU job finished in ${elapsed.toFixed(1)} s`);
+  const previews = historyImages(entry);
+  if (previews.length === 0) {
+    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`);
+  }
+
+  const infoLog = new TextDecoder().decode(await client.view(PSD_INFO_LOG)).trim();
+  if (infoLog === '' || /[\\/]/.test(infoLog)) {
+    refuse('COMFY_MANIFEST_NAMED', `output/${PSD_INFO_LOG}`, `holds ${JSON.stringify(infoLog.slice(0, 200))}; the file name of the manifest SavePSD wrote is required`);
+  }
+  const manifestBytes = await client.view(infoLog);
+  let manifest: Record<string, unknown>;
+  try {
+    manifest = JSON.parse(new TextDecoder().decode(manifestBytes)) as Record<string, unknown>;
+  } catch (err) {
+    return refuse('COMFY_MANIFEST_NAMED', `output/${infoLog}`, `does not parse as JSON (${(err as Error).message})`);
+  }
+  if (manifest.prefix !== prefix) {
+    refuse(
+      'COMFY_MANIFEST_IS_THIS_RUN',
+      `output/${infoLog}`,
+      `carries prefix ${JSON.stringify(manifest.prefix)}; this run's prefix ${JSON.stringify(prefix)} is required — ${PSD_INFO_LOG} names the last manifest any run wrote, and this one is not ours`,
+    );
+  }
+  const layers = Array.isArray(manifest.layers) ? (manifest.layers as Array<Record<string, unknown>>) : [];
+  if (layers.length === 0) refuse('COMFY_MANIFEST_NAMED', `output/${infoLog}`, 'lists no layers; a See-through run writes one per tag');
+  const bad = layers.filter((l) => typeof l.name !== 'string' || !safeName(l.name) || typeof l.filename !== 'string' || !safeName(l.filename));
+  if (bad.length > 0) {
+    refuse('COMFY_LAYER_NAME', `output/${infoLog}`, `names ${bad.length} layer(s) whose name or filename is not a plain file name (first ${JSON.stringify(bad[0]).slice(0, 200)}); each becomes parts/<name>.png`);
+  }
+
+  const parent = dirname(run.out);
+  mkdirSync(parent, { recursive: true });
+  const stage = join(parent, `.${basename(run.out)}.partial-${prefix}`);
+  mkdirSync(join(stage, 'parts'), { recursive: true });
+  mkdirSync(join(stage, 'previews'), { recursive: true });
+  try {
+    for (const p of previews) writeFileSync(join(stage, 'previews', basename(p.filename)), await client.view(p.filename, p.subfolder, p.type));
+    for (const l of layers) writeFileSync(join(stage, 'parts', `${l.name as string}.png`), await client.view(l.filename as string));
+    writeFileSync(join(stage, 'layers.json'), manifestBytes);
+    const set = readWrapperLayers(stage);
+    const meta = {
+      prompt_id: id,
+      image: run.image,
+      elapsed_s: Math.round(elapsed * 10) / 10,
+      vram_free_before_gb: vramBefore,
+      vram_free_low_gb: vramLow,
+      prefix,
+      seed: run.seed,
+      resolution: run.resolution,
+      steps: run.steps,
+      quant: run.quant,
+      offload: run.offload,
+      lama: run.lama,
+      layer_count: layers.length,
+      layer_names: layers.map((l) => l.name as string),
+      canvas: [set.canvas.w, set.canvas.h],
+    };
+    writeFileSync(join(stage, 'meta.json'), `${JSON.stringify(meta, null, 2)}\n`);
+    if (existsSync(run.out)) rmdirSync(run.out);
+    renameSync(stage, run.out);
+    return {
+      promptId: id,
+      prefix,
+      elapsed,
+      layers: layers.map((l) => l.name as string),
+      canvas: [set.canvas.w, set.canvas.h],
+      previews: previews.map((p) => basename(p.filename)),
+    };
+  } finally {
+    if (existsSync(stage)) rmSync(stage, { recursive: true, force: true });
+  }
+}