Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

28.9 KB
Raw Blame
/**
 * Pixal3D (local NVIDIA / CUDA) target — install detection, pure command builders,
 * and a guarded generate runner.
 *
 * `TencentARC/Pixal3D` (SIGGRAPH 2026, MIT) is a pixel-aligned image→3D model built
 * on the TRELLIS.2 backbone: it back-projects pixel features into 3D instead of
 * injecting them through attention, which is what buys it near-reconstruction-level
 * geometry and PBR texture at 1536³. This lane is the CUDA sibling of
 * `trellis2Cuda.js` and deliberately mirrors its shape — the subprocess machinery
 * (install sequencing with transient retry, cancel, the generate child driver) is
 * shared through `laneRunner.js`, so this file is only what is Pixal3D-specific.
 * Everything is either pure or exercised through injectable `exists`/`spawnImpl`, so
 * the wiring is unit-testable WITHOUT an NVIDIA box, a ~40 GB install, or a live
 * render. `runPixal3dCudaGenerate` is the one real subprocess boundary and NEVER
 * auto-runs (AGENTS.md no-cold-bootstrap policy).
 *
 * **Four things differ from the TRELLIS.2 CUDA lane, and each drives the design:**
 *
 * 1. **Upstream SHIPS a CLI.** Unlike `microsoft/TRELLIS.2` (whose `example.py` has
 *    hard-coded paths, forcing PortOS to ship `trellis2CudaGenerateRunner.py`),
 *    Pixal3D's `inference.py` is a real image→GLB entrypoint. So there is no PortOS
 *    Python runner here — re-implementing it would mean re-deriving its MoGe-2 camera
 *    estimation and FOV/distance solve, which is exactly the domain code most likely
 *    to be got subtly wrong.
 *
 * 2. **`--output` is a full path, NOT a stem.** TRELLIS.2's runners take a stem and
 *    append `.glb`; `inference.py` writes precisely the path it is given. So this lane
 *    must NOT route `outputPath` through `trellis2OutputStem` — doing so would silently
 *    produce `model` with no extension.
 *
 * 3. **Its own conda env, and its own TRELLIS.2 checkout.** Pixal3D's install is
 *    "set up TRELLIS.2's environment, then add our deps", and those deps pin
 *    `transformers`/`diffusers`/`pillow` versions. Installing them into the existing
 *    `trellis2` env would mutate a working target's dependency set — a change that
 *    degrades a *different* lane is the worst kind, so this lane pays ~15 GB of extra
 *    disk for isolation. Upstream's `setup.sh --new-env` hard-codes
 *    `conda create -n trellis2`, so the env is created here (named `pixal3d`) and
 *    `setup.sh` is sourced WITHOUT `--new-env` so it installs into the active env.
 *
 * 4. **No gated Hugging Face repos.** `trellis2Cuda` needs `facebook/dinov3` accepted;
 *    Pixal3D loads DINOv3 from the `camenduru/...` mirror and MoGe from
 *    `Ruicheng/moge-2-vitl`, both ungated. Its descriptor therefore declares no
 *    `gatedRepos` — a token still helps with rate limits, but nothing needs accepting.
 *
 * Clone layout: `~/.portos/pixal3d/{TRELLIS.2,Pixal3D}`, conda env `pixal3d`. The env's
 * interpreter is resolved by the shared `resolveCondaEnvPython` (`lib/condaEnv.js`),
 * which both CUDA lanes use — the `CONDA_PREFIX` walk-up it encodes is subtle enough
 * that a second copy would be a liability.
 */

import { existsSync } from 'node:fs';
import { cpus, homedir } from 'node:os';
import { join } from 'node:path';
import { spawn } from '../../lib/childProcess.js';
import { resolveCondaEnvPython } from '../../lib/condaEnv.js';
import { appendMissingModules } from './degradedInstall.js';
import { rewriteGlbMaterialsOpaque } from './glbMaterials.js';
import {
  hfGatedRepoHelp,
  isHfAuthError,
  isTransientInstallError,
  parseGenerateProgress,
} from './trellis2.js';
import { isCudaOomError, TRELLIS2_CUDA_REPO } from './trellis2Cuda.js';
import {
  textMatcher, runInstallSteps, runGenerateSubprocess, probePythonModules,
} from './laneRunner.js';
import { validateRenderOptions } from './renderOptions.js';

const HOME = homedir();

/** Error-code namespace and user-facing name for this lane's subprocess failures. */
const CODE_PREFIX = 'PIXAL3D_CUDA';
const LABEL = 'Pixal3D (CUDA)';

/**
 * Upstream TencentARC/Pixal3D.
 *
 * **Cloned at its DEFAULT branch (`master`), deliberately not `main`.** Upstream's
 * README carries a "Branches" table naming `main` as the TRELLIS.2-backbone version
 * and `paper` as the Direct3D-S2 original — but there is no `main` branch on the
 * remote (only `master`, `paper`, `pr-12`), and `master` is the TRELLIS.2-backbone
 * code. Pinning `-b main` from the README would make the clone step fail outright.
 */
export const PIXAL3D_REPO = 'https://github.com/TencentARC/Pixal3D.git';

/** The conda environment this lane builds. Named to avoid colliding with `trellis2`. */
export const PIXAL3D_CONDA_ENV = 'pixal3d';

/** Python the env is created with — matches what TRELLIS.2's `setup.sh` uses. */
export const PIXAL3D_PYTHON_VERSION = '3.10';

/** NATTEN pin from upstream's install guide (neighborhood attention for the NAF upsampler). */
export const PIXAL3D_NATTEN_VERSION = '0.21.0';

/** The `utils3d` wheel upstream pins by URL (not on PyPI at this version). */
export const PIXAL3D_UTILS3D_WHEEL = 'https://github.com/LDYang694/Storages/releases/download/20260430/utils3d-0.0.2-py3-none-any.whl';

/** Clone/install root. `base` overridable for tests. */
export function pixal3dRoot(base = join(HOME, '.portos')) {
  return join(base, 'pixal3d');
}

/** Where TRELLIS.2 is cloned — sourced only for its `setup.sh` + extension submodules. */
export function pixal3dTrellisDir(base) {
  return join(pixal3dRoot(base), 'TRELLIS.2');
}

/** Where Pixal3D itself is cloned — the code this lane actually runs. */
function pixal3dRepoDir(base) {
  return join(pixal3dRoot(base), 'Pixal3D');
}

/** Upstream's shipped entrypoint. */
function pixal3dInferenceScript(base) {
  return join(pixal3dRepoDir(base), 'inference.py');
}

/**
 * The conda Python for this lane, or null when its env doesn't exist. A one-line
 * wrapper over the shared resolver so the env name lives in exactly one place.
 * @param {{exists?: (p: string) => boolean, env?: object}} [opts]
 * @returns {string|null}
 */
export function pixal3dPython({ exists = existsSync, env } = {}) {
  return resolveCondaEnvPython(PIXAL3D_CONDA_ENV, { exists, env });
}

/**
 * Installed ⇔ the conda env's Python exists AND upstream's entrypoint is on disk.
 * Both halves matter: the env can be created and then the dependency build can fail,
 * which would otherwise read as a complete install (the lesson `trellis2Cuda`'s verify
 * step encodes).
 * @param {{base?: string, exists?: (p: string) => boolean, env?: object}} [opts]
 * @returns {boolean}
 */
export function isPixal3dCudaInstalled({ base, exists = existsSync, env } = {}) {
  if (!pixal3dPython({ exists, env })) return false;
  return exists(pixal3dInferenceScript(base));
}

/**
 * TRELLIS.2 `setup.sh` flags for this lane — the same extension set the
 * `trellis2Cuda` lane builds, MINUS `--new-env` (see the file header: the env is
 * created separately so it can be named `pixal3d`).
 *
 * Pixal3D imports `o_voxel` (the GLB exporter) and `flex_gemm` directly, and defaults
 * `ATTN_BACKEND` to `flash_attn`, so `--o-voxel`, `--flexgemm` and `--flash-attn` are
 * load-bearing rather than optional; `--nvdiffrast`/`--nvdiffrec`/`--cumesh` back the
 * texture bake and mesh ops the exporter calls.
 */
export const PIXAL3D_SETUP_FLAGS = Object.freeze([
  '--basic', '--flash-attn', '--nvdiffrast', '--nvdiffrec',
  '--cumesh', '--o-voxel', '--flexgemm',
]);

/** Build workers for the NATTEN compile — bounded so it can't monopolize the box. */
export function nattenWorkerCount(cpuCount = cpus().length) {
  const n = Number.isFinite(cpuCount) && cpuCount > 0 ? cpuCount : 4;
  return Math.max(1, Math.min(8, Math.floor(n / 2)));
}

/**
 * The install as an ordered list of `{stage, command, args, cwd?, optional?}` steps.
 *
 * Every step is skippable/idempotent so a run that died partway re-reaches the rest
 * rather than aborting on "already exists" — the resume property both TRELLIS.2 lanes
 * rely on. `conda create` is skipped when the env's Python is already present, and
 * each clone is skipped when its `.git` is there.
 *
 * Same sourcing mechanics as `buildCudaInstallSteps` (`. ./setup.sh` inside `bash -lc`,
 * so `conda activate` has the hooks `conda init` wrote); the one difference is that our
 * env is activated FIRST, because `--new-env` is omitted — see the file header.
 *
 * **The NATTEN step is `optional`.** It compiles CUDA kernels for a specific arch, and
 * a failure there is survivable: without NATTEN the pipeline takes upstream's
 * documented NAF fallback path — slower and lower quality, but it renders. Failing the
 * whole ~40 GB install over it would be a worse outcome than a degraded one the
 * install-state probe then reports. `computeCap` comes from
 * `detectCudaComputeCapability()`; when it could not be determined the env var is
 * omitted entirely rather than guessed, letting NATTEN pick its own default.
 *
 * `env` is threaded through so the "does the conda env already exist?" question gets
 * the SAME answer here as in the install's `verify` hook — reading `process.env` here
 * while `verify` reads an injected env would let this prepend a redundant `conda create`
 * that `verify` then disagrees with.
 *
 * @param {string} [base]
 * @param {{exists?: (p: string) => boolean, env?: object, computeCap?: string|null}} [opts]
 * @returns {Array<{stage: string, command: string, args: string[], cwd?: string, optional?: boolean}>}
 */
export function buildPixal3dInstallSteps(base, { exists = existsSync, env, computeCap = null } = {}) {
  const trellisDir = pixal3dTrellisDir(base);
  const repoDir = pixal3dRepoDir(base);
  const steps = [];

  if (!pixal3dPython({ exists, env })) {
    steps.push({
      stage: 'env',
      command: 'conda',
      args: ['create', '-n', PIXAL3D_CONDA_ENV, `python=${PIXAL3D_PYTHON_VERSION}`, '-y'],
    });
  }
  // Recursive: TRELLIS.2 vendors its CUDA extensions as submodules, and a shallow
  // clone yields empty extension dirs and a setup that fails deep in a compile.
  if (!exists(join(trellisDir, '.git'))) {
    steps.push({
      stage: 'clone-trellis',
      command: 'git',
      args: ['clone', '--recursive', TRELLIS2_CUDA_REPO, trellisDir],
    });
  }
  if (!exists(join(repoDir, '.git'))) {
    steps.push({ stage: 'clone', command: 'git', args: ['clone', PIXAL3D_REPO, repoDir] });
  }
  // Every remaining step is "activate our env, then run one command", so only the
  // command, the cwd and the optional-ness are worth reading per step.
  const condaStep = (stage, script, extra = {}) => ({
    stage,
    command: 'bash',
    args: ['-lc', `conda activate ${PIXAL3D_CONDA_ENV} && ${script}`],
    cwd: repoDir,
    ...extra,
  });
  const nattenEnv = [
    ...(computeCap ? [`NATTEN_CUDA_ARCH=${computeCap}`] : []),
    `NATTEN_N_WORKERS=${nattenWorkerCount()}`,
  ].join(' ');
  steps.push(
    condaStep('setup', `. ./setup.sh ${PIXAL3D_SETUP_FLAGS.join(' ')}`, { cwd: trellisDir }),
    condaStep('deps', 'pip install -r requirements.txt'),
    condaStep(
      'natten',
      `${nattenEnv} pip install natten==${PIXAL3D_NATTEN_VERSION} --no-build-isolation`,
      { optional: true },
    ),
    condaStep('utils3d', `pip install ${PIXAL3D_UTILS3D_WHEEL}`),
  );
  return steps;
}

export const PIXAL3D_STANDARD_MODE_MIN_VRAM_GB = 36;
export const PIXAL3D_HIGH_RES_MIN_VRAM_GB = 24;
/** Upstream's two supported pipeline resolutions, low to high. */
export const PIXAL3D_RESOLUTIONS = [1024, 1536];
const [PIXAL3D_RES_FLOOR, PIXAL3D_RES_FULL] = PIXAL3D_RESOLUTIONS;

/**
 * Resolution / offload lane, picked from the card's VRAM.
 *
 * Upstream documents three usable combinations, and they are genuinely three tiers
 * rather than a single quality knob (Pixal3D issue #7 measured "18–36 GB depending on
 * settings"; the merged low-VRAM PR brings peak to ~10–12 GB by loading one pipeline
 * stage onto the GPU at a time):
 *
 *  - `>= PIXAL3D_STANDARD_MODE_MIN_VRAM_GB` → standard mode at full resolution. No
 *    offload, so it is also the fastest.
 *  - `>= PIXAL3D_HIGH_RES_MIN_VRAM_GB` → full resolution with `--low_vram`. Upstream
 *    explicitly supports forcing full resolution in low-VRAM mode; the stage-at-a-time
 *    offload pays for it in wall-clock rather than quality.
 *  - otherwise → the floor resolution with `--low_vram`, the least this lane supports.
 *
 * An unknown/unparseable VRAM reading degrades to the floor rather than overcommitting
 * a card we failed to size (AGENTS.md sentinel rule).
 *
 * @param {number|null} vramGb
 * @returns {{lowVram: boolean, resolution: number}}
 */
export function selectPixal3dRenderBudget(vramGb) {
  const gb = Number(vramGb);
  if (gb >= PIXAL3D_STANDARD_MODE_MIN_VRAM_GB) return { lowVram: false, resolution: PIXAL3D_RES_FULL };
  if (gb >= PIXAL3D_HIGH_RES_MIN_VRAM_GB) return { lowVram: true, resolution: PIXAL3D_RES_FULL };
  return { lowVram: true, resolution: PIXAL3D_RES_FLOOR };
}

/**
 * The generate invocation:
 * `<conda-python> inference.py --image <src> --output <dst.glb> [--resolution N] [--low_vram] …`
 *
 * Pure. Throws on a missing image (a render with no input is a bug, not an empty run)
 * and on a resolution outside upstream's accepted set — better to fail here than to
 * have argparse abort a job we already queued.
 *
 * `outputPath` is passed THROUGH, not reduced to a stem: `inference.py --output` is a
 * full file path (see the file header).
 *
 * `steps`/`seed` are validated against the shared ranges so they cannot drift from the
 * TRELLIS.2 lanes — but upstream's `inference.py` exposes no per-phase step override, so
 * `steps` is validated and NOT emitted (an unrecognized flag would make argparse abort a
 * job we already queued). The target descriptor declares that with
 * `supportsRenderOptions.steps: false`, which is what stops the UI offering a control
 * that does nothing and stops the run ledger recording a value that never applied.
 *
 * @param {{imagePath: string, outputPath?: string, base?: string, python?: string,
 *          resolution?: number, lowVram?: boolean,
 *          steps?: number|null, seed?: number|null}} opts
 * @returns {{command: string, args: string[]}}
 */
export function buildPixal3dGenerateArgs({
  imagePath,
  outputPath,
  base,
  python,
  resolution = PIXAL3D_RES_FLOOR,
  lowVram = true,
  steps = null,
  seed = null,
} = {}) {
  if (!imagePath) throw new Error('buildPixal3dGenerateArgs: imagePath is required');
  if (!PIXAL3D_RESOLUTIONS.includes(resolution)) {
    throw new Error(
      `buildPixal3dGenerateArgs: resolution must be one of ${PIXAL3D_RESOLUTIONS.join(', ')}`,
    );
  }
  // Both are range-checked at the same boundary as the other lanes; only seed is emitted.
  validateRenderOptions('buildPixal3dGenerateArgs', { steps, seed });
  const args = [
    pixal3dInferenceScript(base),
    '--image', imagePath,
    '--resolution', String(resolution),
  ];
  if (outputPath) args.push('--output', outputPath);
  if (lowVram) args.push('--low_vram');
  if (seed !== null) args.push('--seed', String(seed));
  return { command: python || pixal3dPython({}) || 'python', args };
}

/**
 * Upstream's own progress banners, mapped to the shared stage/percent vocabulary.
 *
 * Pixal3D prints `[Pipeline]`/`[Inference]`/`[MoGe-2]`/`[NAF]`-prefixed lines rather
 * than the banners `parseGenerateProgress` was written for, so this table covers them
 * — kept HERE rather than added to `GENERATE_STAGE_SIGNATURES` so the two TRELLIS.2
 * lanes' parsing cannot regress from a Pixal3D change. Percents follow the same bands
 * (load < 10, sampling 10–50, texture ~65, export 92) so the bar stays monotonic.
 */
const PIXAL3D_STAGE_SIGNATURES = [
  { re: /^\[Pipeline\] Loading from/i, stage: 'loading', percent: 2 },
  { re: /^\[ImageCond\]/i, stage: 'loading', percent: 3 },
  { re: /^\[NAF\]/i, stage: 'loading', percent: 4 },
  { re: /^\[Pipeline\] (Low-VRAM|Standard) mode/i, stage: 'loading', percent: 5 },
  { re: /^\[Inference\] Processing image/i, stage: 'loading', percent: 6 },
  { re: /^\[MoGe-2\]/i, stage: 'loading', percent: 7 },
  { re: /^\[Inference\] (Estimating camera|Using manual FOV)/i, stage: 'loading', percent: 8 },
  { re: /^\[Inference\] Running 3D generation/i, stage: 'generating', percent: 10 },
  { re: /^\[Inference\] Using pipeline_type/i, stage: 'generating', percent: 11 },
  { re: /^\[Inference\] Extracting GLB/i, stage: 'texturing', percent: 65 },
];

/**
 * Parse one line of `inference.py` output into a progress frame, or null.
 *
 * Delegates to the shared `parseGenerateProgress` FIRST, which is what handles the two
 * signals both lanes share: a written `.glb` path (the terminal export frame, matched
 * by `[Done] GLB saved to: …`) and a bare `tqdm` percentage scaled into the sampling
 * band. Only lines it finds no signal in are matched against Pixal3D's own banners, so
 * the terminal export frame can never be shadowed by a banner rule.
 *
 * @param {string} line
 * @returns {{stage: string, percent?: number, assetPath?: string, message: string}|null}
 */
export function parsePixal3dProgress(line) {
  const shared = parseGenerateProgress(line);
  if (shared) return shared;
  const text = String(line ?? '').trim();
  if (!text) return null;
  for (const sig of PIXAL3D_STAGE_SIGNATURES) {
    if (sig.re.test(text)) return { stage: sig.stage, percent: sig.percent, message: text };
  }
  return null;
}

/**
 * Modules Pixal3D imports directly — absent means the install did not complete, not
 * that quality degrades. `o_voxel` is the GLB exporter and `flex_gemm` the sparse GEMM
 * its autotuner configures on import. Upstream's own `pixal3d` package is deliberately
 * NOT probed: it resolves only with the clone root on `sys.path`, which the render
 * subprocess gets from its `cwd` and this probe does not, so it would always read as
 * missing.
 */
export const PIXAL3D_REQUIRED_MODULES = ['o_voxel', 'flex_gemm'];

/** NATTEN backs the NAF upsampler. Absent ⇒ renders take upstream's fallback path. */
export const PIXAL3D_NAF_MODULES = ['natten'];

/**
 * The remedy for a REQUIRED extension that did not build — and only the remedy: which
 * extensions failed rides the `degraded.detail` line the adapter builds (#4741). Lives
 * next to its NAF sibling rather than inlined at the registry so both readings of a
 * half-built install come from one place.
 */
export const PIXAL3D_INCOMPLETE_INSTALL_HELP = 'Pixal3D is installed but not every required '
  + 'CUDA extension built, so renders will fail in the mesh exporter. Repair install '
  + 'rebuilds the CUDA extensions; your downloaded models are kept.';

export const PIXAL3D_NAF_FALLBACK_HELP = 'Pixal3D is installed, but NATTEN is missing, '
  + 'so its NAF refinement step falls back to DINO projection features — slower, and '
  + 'geometry/texture detail is a notch lower than upstream. Repair install rebuilds '
  + 'NATTEN for this GPU; your downloaded models are kept.';

/**
 * Probe which of the env's modules resolve, for the install-state card. The spawn and
 * its find_spec one-liner are shared (`probePythonModules`); only the classification
 * below is Pixal3D-specific.
 *
 * **`naf: 'available'` means the NATTEN PACKAGE resolves — it does NOT prove the CUDA
 * `libnatten` kernels built.** Confirming that needs `import natten` to read
 * `HAS_LIBNATTEN`, which costs a torch import; paying that per `/targets` request is
 * not worth it, so the deep check is left to render time, where
 * `isPixal3dNafError` classifies the failure into an actionable message. Reported as
 * `'unknown'` when the probe itself could not run — deliberately distinct from
 * `'unavailable'`, so a broken probe never renders a warning about a fine install
 * (AGENTS.md sentinel rule: "failed to determine" ≠ "determined to be bad").
 *
 * @param {{execFileImpl?: Function, exists?: (p: string) => boolean,
 *          env?: NodeJS.ProcessEnv}} [opts]
 * @returns {Promise<{naf: 'available'|'unavailable'|'unknown', missing: string[], help?: string}>}
 */
export async function probePixal3dModules({
  execFileImpl,
  exists = existsSync,
  env,
} = {}) {
  const modules = await probePythonModules({
    python: pixal3dPython({ exists, env }),
    modules: [...PIXAL3D_REQUIRED_MODULES, ...PIXAL3D_NAF_MODULES],
    execFileImpl,
  });
  if (!modules) return { naf: 'unknown', missing: [] };
  const nafPresent = PIXAL3D_NAF_MODULES.every((m) => modules[m]);
  return {
    naf: nafPresent ? 'available' : 'unavailable',
    missing: PIXAL3D_REQUIRED_MODULES.filter((m) => !modules[m]),
    ...(nafPresent ? {} : { help: PIXAL3D_NAF_FALLBACK_HELP }),
  };
}

/**
 * A NATTEN / NAF-upsampler failure. Distinct from a generic crash because it is
 * user-actionable: repair the install to rebuild NATTEN for this card.
 */
export const isPixal3dNafError = textMatcher([
  'libnatten', 'HAS_LIBNATTEN', "No module named 'natten'", 'NATTEN was not compiled',
]);

const NAF_ERROR_HELP = 'This render failed inside Pixal3D\'s NAF upsampler, which needs '
  + 'NATTEN built with CUDA kernels for this GPU. Run Repair install to rebuild it.';

/**
 * The WSL2 NAF crash. Upstream issue #31 reports a reproducible
 * `CUDA driver error: device not ready` inside the NAF upsampler's encoder on WSL2,
 * on passes where `use_naf_upsample=True` — while the same NATTEN build works in
 * isolation. It is classified separately from a NATTEN *build* problem because the
 * remedy is different and Repair install will not help: PortOS points Windows users at
 * WSL2 for the TRELLIS.2 CUDA lane, and that advice does not carry over here.
 */
export const isPixal3dWslNafError = textMatcher(['CUDA driver error: device not ready']);

const WSL_NAF_HELP = 'The GPU driver reported "device not ready" inside Pixal3D\'s NAF '
  + 'upsampler. This is a known upstream failure under WSL2 (Pixal3D issue #31) that a '
  + 'reinstall does not fix — render on a native Linux host, or use the TRELLIS.2 (CUDA) '
  + 'target on this machine instead.';

const CUDA_OOM_HELP = 'The GPU ran out of memory during this render. Close other GPU '
  + 'workloads and try again, or render at a lower resolution — Pixal3D needs ~12 GB at '
  + '1024 and up to ~36 GB for full-quality 1536.';

/**
 * Run the install as a killable, event-emitting job: conda env → TRELLIS.2 clone +
 * `setup.sh` → Pixal3D clone → deps → NATTEN → utils3d (~40 GB and a long CUDA
 * extension build). Real subprocesses — user-triggered only. Retry/cancel/backoff
 * semantics come from the shared `runInstallSteps`.
 *
 * `computeCap` is resolved by the caller (the adapter, via
 * `detectCudaComputeCapability`) rather than probed here, keeping this function's
 * inputs explicit and its steps deterministic in tests.
 *
 * **Post-install verification.** `setup.sh` is SOURCED and exits 0 even when a CUDA
 * extension failed to compile, so the env and the checkout can both be on disk while
 * `o_voxel` never built. After the presence check the install therefore runs the same
 * module probe the card uses (`probeModules`, injectable so the suite never spawns a
 * Python against the developer machine) and reports a half-built install BEFORE the
 * terminal `complete` frame — otherwise a user watching the install finish sees a clean
 * success and only learns it is incomplete on a later visit to the card (#4741).
 *
 * @param {{base?: string, onEvent?: (ev: object) => void, spawnImpl?: Function,
 *          maxRetries?: number, sleep?: (ms: number) => Promise<void>,
 *          exists?: (p: string) => boolean, env?: NodeJS.ProcessEnv,
 *          computeCap?: string|null, probeModules?: Function}} [opts]
 * @returns {{promise: Promise<{ok: true}>, kill: () => void}}
 */
export function installPixal3dCuda({
  base,
  onEvent = () => {},
  spawnImpl = spawn,
  maxRetries = 3,
  sleep,
  exists = existsSync,
  env,
  computeCap = null,
  probeModules = probePixal3dModules,
} = {}) {
  return runInstallSteps({
    steps: buildPixal3dInstallSteps(base, { exists, env, computeCap }),
    label: LABEL,
    codePrefix: CODE_PREFIX,
    isTransient: isTransientInstallError,
    onEvent,
    spawnImpl,
    maxRetries,
    sleep,
    env,
    // Steps can leave a usable env behind while a build failed, so confirm what
    // actually landed rather than trusting exit 0 (#2952's lesson).
    verify: async (emit) => {
      if (!isPixal3dCudaInstalled({ base, exists, env })) {
        const err = new Error(
          `${LABEL} setup finished but its conda environment or the Pixal3D checkout is `
          + 'missing — check the setup log above for a failed extension build.',
        );
        err.code = `${CODE_PREFIX}_INSTALL_INCOMPLETE`;
        err.stage = 'verify';
        throw err;
      }
      // Present ≠ complete. A missing REQUIRED extension is a `⚠️`, not a throw: the
      // install genuinely produced a usable env for everything but the mesh exporter,
      // and the card's Repair action is the remedy — failing the whole ~40 GB run would
      // discard work the user can keep. Same reading, and the same precedence
      // (incomplete outranks the NAF fallback), as the card's `describeInstallState`.
      // A probe that could not RUN (`naf: 'unknown'`, nothing missing) still reports the
      // clean line: "failed to determine" must never render as "determined to be bad".
      const probe = await probeModules({ exists, env });
      if (probe.missing?.length) {
        emit({
          type: 'log',
          stage: 'verify',
          message: `⚠️ ${appendMissingModules(PIXAL3D_INCOMPLETE_INSTALL_HELP, probe.missing)}`,
        });
      } else if (probe.naf === 'unavailable') {
        // Nothing to name — NATTEN is absent as a whole, not half-built.
        emit({ type: 'log', stage: 'verify', message: `⚠️ ${PIXAL3D_NAF_FALLBACK_HELP}` });
      } else {
        emit({ type: 'log', stage: 'verify', message: '✅ Pixal3D CUDA environment is present.' });
      }
    },
  });
}

/**
 * Run a single image→GLB generation. Same contract as `runTrellis2CudaGenerate`: the one
 * real-subprocess boundary, GUARDED (rejects `PIXAL3D_CUDA_NOT_INSTALLED` unless the
 * environment is present, so it can never run from a cold boot), returning
 * `{ promise, kill }` so a caller can terminate the render mid-flight, and normalizing
 * the result to opaque so low-alpha prediction noise doesn't become visible holes.
 * `spawnImpl`/`exists` are injectable so the wiring is unit-testable without a render.
 *
 * Cancellation matters more here than on the TRELLIS.2 lanes: a full-quality Pixal3D
 * render is measured in minutes, not seconds.
 *
 * `vramGb` is the size of the card this host will render on, passed down from the host
 * capabilities resolved at the request boundary; it selects the resolution/offload
 * tier. Null/unknown degrades to the floor.
 *
 * `cwd` is the Pixal3D checkout, which is load-bearing rather than tidiness: upstream's
 * `inference.py` imports its own `pixal3d` package relative to the checkout and writes
 * its `flex_gemm` autotune cache next to the script.
 *
 * @param {{imagePath: string, outputPath?: string, base?: string, resolution?: number,
 *          lowVram?: boolean, vramGb?: number|null,
 *          steps?: number|null, seed?: number|null,
 *          onProgress?: (frame: object) => void, spawnImpl?: Function,
 *          exists?: (p: string) => boolean, env?: NodeJS.ProcessEnv,
 *          postprocessGlb?: (path: string) => void|Promise<void>}} opts
 * @returns {{promise: Promise<{assetPath: string}>, kill: () => void}}
 */
export function runPixal3dCudaGenerate({
  imagePath,
  outputPath,
  base,
  resolution,
  lowVram,
  vramGb = null,
  steps = null,
  seed = null,
  onProgress,
  spawnImpl = spawn,
  exists = existsSync,
  env,
  postprocessGlb = rewriteGlbMaterialsOpaque,
} = {}) {
  // Resolve the interpreter once and reuse it as the "is the env there?" answer.
  const python = pixal3dPython({ exists, env });
  if (!python || !exists(pixal3dInferenceScript(base))) {
    const err = new Error(`${LABEL} is not installed — install it before generating.`);
    err.code = `${CODE_PREFIX}_NOT_INSTALLED`;
    return { promise: Promise.reject(err), kill: () => {} };
  }
  const budget = selectPixal3dRenderBudget(vramGb);
  const { command, args } = buildPixal3dGenerateArgs({
    imagePath,
    outputPath,
    base,
    python,
    resolution: resolution ?? budget.resolution,
    lowVram: lowVram ?? budget.lowVram,
    steps,
    seed,
  });
  return runGenerateSubprocess({
    command,
    args,
    cwd: pixal3dRepoDir(base),
    env,
    label: LABEL,
    codePrefix: CODE_PREFIX,
    parseProgress: parsePixal3dProgress,
    assetPath: outputPath || null,
    onProgress,
    spawnImpl,
    postprocessGlb,
    // Order matters: the WSL2 driver fault and a missing NATTEN build both surface from
    // the NAF stage but have different remedies, so the more specific one is tested
    // first and never collapses into "rebuild NATTEN" (which would not help).
    classifiers: [
      { test: isPixal3dWslNafError, code: `${CODE_PREFIX}_NAF_DEVICE_NOT_READY`, help: WSL_NAF_HELP },
      { test: isPixal3dNafError, code: `${CODE_PREFIX}_NAF_UNAVAILABLE`, help: NAF_ERROR_HELP },
      { test: isHfAuthError, code: `${CODE_PREFIX}_HF_AUTH_REQUIRED`, help: () => hfGatedRepoHelp('pixal3dCuda') },
      { test: isCudaOomError, code: `${CODE_PREFIX}_OUT_OF_MEMORY`, help: CUDA_OOM_HELP },
    ],
  });
}