@wenathlan/saddle 1.8.17 → 2.0.2

package/dist/render.js

@@ -0,0 +1,1073 @@
+/**
+ * render.ts — software rendering stack and gpu identity spoofing for the
+ * virtual hardware engine.
+ *
+ * the module pins the 100% software graphics pipeline verified against
+ * primary sources on 2026-08-22:
+ * - mesa 26.2.1 stable (released 2026-08-20) with the 26.3-devel mainline
+ *   open since 2026-07-15; llvm 22.1.8 (2026-07-10) is the reference
+ *   compiler backend and mesa 26.2 is already llvm-22 ready
+ * - llvmpipe: opengl 4.6 core profile 100% (161/161 extensions tracked by
+ *   mesamatrix), opengl es 3.2 100%, avx-512 selected at runtime by gallivm
+ *   (mesa mr !17813), rasterizer thread ceiling lp_max_threads = 32 (mr
+ *   31551 raised the previous 16; docs state "up to 32 at this time")
+ * - lavapipe: vulkan 1.4 surface since mesa 25.1, khronos-conformant on the
+ *   vulkan 1.3 cts (submission 2022-07-19); icd manifest
+ *   /usr/share/vulkan/icd.d/lvp_icd.x86_64.json selected through
+ *   vk_driver_files (vk_icd_filenames is deprecated by the vulkan loader)
+ * - rusticl: opencl 3.1 with same-day spec support in mesa 26.2; sole mesa
+ *   opencl frontend since clover was deleted in mesa 25.2; cl_khr_fp16 is
+ *   default since mesa 25.2 so only fp64 still needs rusticl_features
+ * - xvfb headless glx recipe (man xvfb(1)):
+ *   "xvfb :99 -ac -screen 0 1920x1080x24 -nolisten tcp +extension glx
+ *    +render -noreset"
+ *
+ * contexts (25): versioncatalog, llvmpipefacts, cpucapsdomain, lpperfdomain,
+ * lavapipefacts, rusticlfacts, xvfbrecipe, gpuspoofdata, pciid, gpuregistry,
+ * gpuprofilebuilder, mesaenvbuilder, renderenv, threadadvisor, smiformat,
+ * smiadapter, rendertargets, rendererbase, llvmpiperenderer, lavapiperenderer,
+ * rusticlrenderer, xvfbdisplay, rendererfactory, rendererproxy, renderprobe
+ *
+ * patterns: builder (mesaenvbuilder, gpuprofilebuilder), registry
+ * (gpuregistry), factory (rendererfactory), proxy (rendererproxy).
+ * rules: lowercase identifiers, english jsdoc, third person, no emoji,
+ * try/catch catcher on every fallible path, node:* built-ins only, and no
+ * hardcoded localhost address anywhere.
+ *
+ * domain split (v2): this module keeps the software identity stack — mesa
+ * environment builders, llvmpipe/lavapipe/rusticl renderers, xvfb and the
+ * virtual nvidia-smi adapter renderer. the physical gpu side (vfio passthrough, vgpu
+ * slicing, MIG layouts, the verified gpu bank) lives in virtualgpu.ts, and
+ * the paravirtual virtio-gpu venus path (`-device virtio-gpu-pci,venus=true`
+ * with `hostmem=8g`, or `virtio-gpu-gl blob=on venus=on`) is emitted by the
+ * virtualization module that owns the QEMU command line.
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { spawn } from 'node:child_process';
+import { randomInt } from 'node:crypto';
+import { cpus } from 'node:os';
+import process from 'node:process';
+/** stack pinned from primary sources (mesa3d.org, llvm releases, docs.nvidia.com). */
+const mesastack = {
+    mesa: '26.2.1',
+    mesadevel: '26.3-devel',
+    llvm: '22.1.8',
+    gl: '4.6',
+    gles: '3.2',
+    vulkan: '1.4',
+    opencl: '3.1',
+    smidriver: '575.57.08',
+    cudaversion: '12.9',
+};
+const llvmpipe = {
+    glcoreprofile: '4.6 core',
+    glcoreextensions: '161/161 (100%)',
+    glesprofile: '3.2',
+    glesextensions: '100%',
+    avx512: 'gallivm enables avx-512 at runtime (mesa mr !17813)',
+    threadceiling: 32,
+    threadnote: 'lp_max_threads is a compile-time constant; mr 31551 raised 16 to 32; the docs state "up to 32 at this time"',
+};
+/** valid values for gallium_override_cpu_caps (docs.mesa3d.org/envvars).
+ * no avx2/avx512 value exists: avx-512 is detected at runtime by gallivm. */
+const cpucapsdomain = ['nosse', 'sse', 'sse2', 'sse3', 'ssse3', 'sse4.1', 'avx'];
+/** valid stages for lp_perf selective no-ops (docs: "see the source code"). */
+const lpperfdomain = [
+    'no_blend',
+    'no_depth',
+    'no_alphatest',
+    'no_tex',
+    'no_linear',
+    'no_mipmaps',
+    'no_mip_linear',
+    'tex_mem',
+];
+const lavapipe = {
+    vulkan: '1.4',
+    conformance: 'khronos-conformant on the vulkan 1.3 cts (submission 2022-07-19)',
+    icdmanifest: '/usr/share/vulkan/icd.d/lvp_icd.x86_64.json',
+    icdenv: 'VK_DRIVER_FILES',
+    deprecatedicdenv: 'VK_ICD_FILENAMES',
+    extensions: '204/303 extensions (67.3%) in mesa 26.2',
+};
+const rusticl = {
+    opencl: '3.1',
+    clovernote: 'clover was deleted in mesa 25.2; rusticl is the sole mesa opencl frontend',
+    fp16note: 'cl_khr_fp16 is default since mesa 25.2 (rusticl_features=fp16 is obsolete)',
+    features: 'fp64',
+    devicetype: 'gpu',
+};
+/* ------------------------------------------------------------------ */
+/* context: xvfb headless recipe                                       */
+/* ------------------------------------------------------------------ */
+/** default xvfb geometry documented in the project research. */
+const defaultgeometry = '1920x1080x24';
+/** builds the validated headless glx argv for xvfb (man xvfb(1)). */
+function xvfbargs(display, geometry) {
+    return [
+        `:${display}`,
+        '-ac',
+        '-screen',
+        '0',
+        geometry,
+        '-nolisten',
+        'tcp',
+        '+extension',
+        'GLX',
+        '+render',
+        '-noreset',
+    ];
+}
+/** picks a random x display number in the 90-99 range; the documented
+ * example uses :99, so the random pick avoids colliding with it. */
+function randomdisplay() {
+    try {
+        return String(90 + randomInt(10));
+    }
+    catch {
+        return '94';
+    }
+}
+const gpuspoofdata = {
+    rtx5090: {
+        name: 'NVIDIA RTX 5090',
+        vendor: 'nvidia',
+        pcivendor: '10DE',
+        pcidevice: '2B85',
+        vrammib: 32768,
+        memtype: 'GDDR7',
+        bandwidthgbs: 1792,
+        tdpw: 575,
+        arch: 'GB202 Blackwell sm_120',
+        driver: mesastack.smidriver,
+        cuda: mesastack.cudaversion,
+    },
+    rtxpro6000: {
+        name: 'NVIDIA RTX PRO 6000 Blackwell',
+        vendor: 'nvidia',
+        pcivendor: '10DE',
+        pcidevice: '26B5',
+        vrammib: 98304,
+        memtype: 'GDDR7 ECC',
+        bandwidthgbs: 1792,
+        tdpw: 600,
+        arch: 'GB202 Blackwell workstation',
+        driver: mesastack.smidriver,
+        cuda: mesastack.cudaversion,
+    },
+    b200: {
+        name: 'NVIDIA B200',
+        vendor: 'nvidia',
+        pcivendor: '10DE',
+        pcidevice: '2665',
+        vrammib: 196608,
+        memtype: 'HBM3e',
+        bandwidthgbs: 8000,
+        tdpw: 1000,
+        arch: 'GB100 Blackwell dual-die',
+        driver: mesastack.smidriver,
+        cuda: mesastack.cudaversion,
+    },
+    rx9070xt: {
+        name: 'AMD Radeon RX 9070 XT',
+        vendor: 'amd',
+        pcivendor: '1002',
+        pcidevice: '748E',
+        vrammib: 16384,
+        memtype: 'GDDR6',
+        bandwidthgbs: 640,
+        tdpw: 304,
+        arch: 'Navi 48 RDNA 4 gfx1201',
+        driver: 'adrenalin 26.x / mesa 26.2',
+        cuda: null,
+    },
+    mi350x: {
+        name: 'AMD Instinct MI350X',
+        vendor: 'amd',
+        pcivendor: '1002',
+        pcidevice: '75A0',
+        vrammib: 294912,
+        memtype: 'HBM3e',
+        bandwidthgbs: 8000,
+        tdpw: 1000,
+        arch: 'CDNA 4 gfx950',
+        driver: 'ROCm 7.x',
+        cuda: null,
+    },
+};
+/** renders the canonical "vendor:device" pci id of a virtual identity profile. */
+function pciid(profile) {
+    return `${profile.pcivendor}:${profile.pcidevice}`;
+}
+/* ------------------------------------------------------------------ */
+/* context: gpu profile registry (registry pattern)                    */
+/* ------------------------------------------------------------------ */
+/** registry of named gpu profiles; the whole engine resolves virtual identity
+ * identities exclusively through this registry. */
+class gpuregistry {
+    #profiles = new Map();
+    /** registers a profile under a name; returns the registry for chaining. */
+    register(name, profile) {
+        try {
+            this.#profiles.set(name, profile);
+            return this;
+        }
+        catch (error) {
+            throw new Error(`gpu profile registration failed for ${name}: ${errormessage(error)}`);
+        }
+    }
+    /** lists every registered profile name. */
+    names() {
+        return [...this.#profiles.keys()];
+    }
+    /** resolves a profile or undefined when absent. */
+    get(name) {
+        return this.#profiles.get(name);
+    }
+    /** resolves a profile or throws with the list of known names. */
+    require(name) {
+        const found = this.#profiles.get(name);
+        if (found === undefined) {
+            throw new Error(`unknown gpu profile "${name}"; known profiles: ${this.names().join(', ')}`);
+        }
+        return found;
+    }
+}
+/** default registry seeded with the five verified gpu identities. */
+const defaultgpuregistry = new gpuregistry()
+    .register('rtx5090', gpuspoofdata.rtx5090)
+    .register('rtxpro6000', gpuspoofdata.rtxpro6000)
+    .register('b200', gpuspoofdata.b200)
+    .register('rx9070xt', gpuspoofdata.rx9070xt)
+    .register('mi350x', gpuspoofdata.mi350x);
+/* ------------------------------------------------------------------ */
+/* context: gpu profile builder (builder pattern)                      */
+/* ------------------------------------------------------------------ */
+/** fluent builder for custom virtual identity profiles; defaults mirror the rtx 5090. */
+class gpuprofilebuilder {
+    #name = 'NVIDIA RTX 5090';
+    #vendor = 'nvidia';
+    #pcivendor = '10DE';
+    #pcidevice = '2B85';
+    #vrammib = 32768;
+    #memtype = 'GDDR7';
+    #bandwidthgbs = 1792;
+    #tdpw = 575;
+    #arch = 'GB202 Blackwell sm_120';
+    #driver = mesastack.smidriver;
+    #cuda = mesastack.cudaversion;
+    withname(name) {
+        this.#name = name;
+        return this;
+    }
+    withvendor(vendor) {
+        this.#vendor = vendor;
+        this.#pcivendor = vendor === 'nvidia' ? '10DE' : '1002';
+        return this;
+    }
+    withpcidevice(device) {
+        this.#pcidevice = device;
+        return this;
+    }
+    withvram(mib) {
+        this.#vrammib = mib;
+        return this;
+    }
+    withmemtype(memtype) {
+        this.#memtype = memtype;
+        return this;
+    }
+    withbandwidth(gbs) {
+        this.#bandwidthgbs = gbs;
+        return this;
+    }
+    withtdp(w) {
+        this.#tdpw = w;
+        return this;
+    }
+    witharch(arch) {
+        this.#arch = arch;
+        return this;
+    }
+    withdriver(driver, cuda) {
+        this.#driver = driver;
+        this.#cuda = cuda;
+        return this;
+    }
+    /** validates the profile shape and freezes it into a gpuspoof. */
+    build() {
+        if (this.#name.length === 0) {
+            throw new Error('gpu profile requires a name');
+        }
+        if (!/^[0-9A-Fa-f]{4}$/.test(this.#pcidevice)) {
+            throw new Error(`gpu profile pci device "${this.#pcidevice}" must be 4 hex digits`);
+        }
+        if (this.#vrammib <= 0 || this.#bandwidthgbs <= 0 || this.#tdpw <= 0) {
+            throw new Error('gpu profile requires positive vram, bandwidth and tdp values');
+        }
+        return {
+            name: this.#name,
+            vendor: this.#vendor,
+            pcivendor: this.#pcivendor,
+            pcidevice: this.#pcidevice.toUpperCase(),
+            vrammib: this.#vrammib,
+            memtype: this.#memtype,
+            bandwidthgbs: this.#bandwidthgbs,
+            tdpw: this.#tdpw,
+            arch: this.#arch,
+            driver: this.#driver,
+            cuda: this.#cuda,
+        };
+    }
+}
+/* ------------------------------------------------------------------ */
+/* context: mesa environment builder (builder pattern)                 */
+/* ------------------------------------------------------------------ */
+/** fluent builder that assembles the complete validated mesa environment;
+ * every variable below is documented at docs.mesa3d.org/envvars.html. */
+class mesaenvbuilder {
+    #vars = new Map();
+    #perf = new Set();
+    /** forces the software path: llvmpipe through the gallium loader. */
+    software() {
+        this.#vars.set('LIBGL_ALWAYS_SOFTWARE', 'true');
+        this.#vars.set('GALLIUM_DRIVER', 'llvmpipe');
+        return this;
+    }
+    /** spoofs glgetstring(gl_version); 4.6 is the llvmpipe maximum. */
+    glversion(version = mesastack.gl) {
+        this.#vars.set('MESA_GL_VERSION_OVERRIDE', version);
+        return this;
+    }
+    /** spoofs gl_shading_language_version (460 matches gl 4.6). */
+    glslversion(version = '460') {
+        this.#vars.set('MESA_GLSL_VERSION_OVERRIDE', version);
+        return this;
+    }
+    /** spoofs the gles version reported by the software driver. */
+    glesversion(version = mesastack.gles) {
+        this.#vars.set('MESA_GLES_VERSION_OVERRIDE', version);
+        return this;
+    }
+    /** spoofs the vulkan apiversion; cannot exceed the driver instance version. */
+    vulkanversion(version = mesastack.vulkan) {
+        this.#vars.set('MESA_VK_VERSION_OVERRIDE', version);
+        return this;
+    }
+    /** sets lp_num_threads; 0 lets llvmpipe use every core up to the
+     * lp_max_threads=32 ceiling, 1..32 pins an explicit thread count. */
+    threads(count = 0) {
+        if (count < 0 || count > llvmpipe.threadceiling) {
+            throw new Error(`lp_num_threads must be 0..${llvmpipe.threadceiling}`);
+        }
+        this.#vars.set('LP_NUM_THREADS', String(count));
+        return this;
+    }
+    /** sets lp_native_vector_width; 512 exercises the avx-512 paths even
+     * though gallivm picks avx-512 automatically at runtime. */
+    vectorwidth(width) {
+        this.#vars.set('LP_NATIVE_VECTOR_WIDTH', String(width));
+        return this;
+    }
+    /** overrides reported cpu caps; avx is the highest documented value
+     * (there is no avx2/avx512 entry in the envvars documentation). */
+    cpucaps(caps) {
+        if (!cpucapsdomain.includes(caps)) {
+            throw new Error(`gallium_override_cpu_caps must be one of: ${cpucapsdomain.join('|')}`);
+        }
+        this.#vars.set('GALLIUM_OVERRIDE_CPU_CAPS', caps);
+        return this;
+    }
+    /** adds one lp_perf selective no-op stage (benchmarking aid). */
+    perf(stage) {
+        if (!lpperfdomain.includes(stage)) {
+            throw new Error(`lp_perf stage must be one of: ${lpperfdomain.join(',')}`);
+        }
+        this.#perf.add(stage);
+        return this;
+    }
+    /** disables gl error checking (gl_khr_no_error) to cut cpu overhead. */
+    noerror(enabled = true) {
+        this.#vars.set('MESA_NO_ERROR', enabled ? '1' : '0');
+        return this;
+    }
+    /** pins lavapipe through vk_driver_files and enables the headless wsi
+     * swapchain; vk_icd_filenames is deprecated and never emitted. */
+    lavapipe(icd = lavapipe.icdmanifest) {
+        this.#vars.set('VK_DRIVER_FILES', icd);
+        this.#vars.set('MESA_VK_WSI_HEADLESS_SWAPCHAIN', '1');
+        return this;
+    }
+    /** enables rusticl on llvmpipe with the gpu device type virtual identity, opencl
+     * 3.1 and the fp64 feature (fp16 is default since mesa 25.2). */
+    rusticl() {
+        this.#vars.set('RUSTICL_ENABLE', 'llvmpipe');
+        this.#vars.set('RUSTICL_DEVICE_TYPE', rusticl.devicetype);
+        this.#vars.set('RUSTICL_CL_VERSION', rusticl.opencl);
+        this.#vars.set('RUSTICL_FEATURES', rusticl.features);
+        return this;
+    }
+    /** escape hatch for extra variables; caller keeps full choice. */
+    set(key, value) {
+        this.#vars.set(key, value);
+        return this;
+    }
+    /** freezes the environment into a plain record (lp_perf joined last). */
+    build() {
+        const vars = {};
+        for (const [key, value] of this.#vars) {
+            vars[key] = value;
+        }
+        if (this.#perf.size > 0) {
+            vars.LP_PERF = [...this.#perf].join(',');
+        }
+        return vars;
+    }
+}
+/** one-call environment assembly per render target. */
+function renderenv(target) {
+    const builder = new mesaenvbuilder();
+    switch (target) {
+        case 'opengl':
+            return builder
+                .software()
+                .glversion()
+                .glslversion()
+                .threads()
+                .vectorwidth(512)
+                .noerror()
+                .build();
+        case 'gles':
+            return builder.software().glesversion().threads().noerror().build();
+        case 'vulkan':
+            return builder.software().vulkanversion().lavapipe().build();
+        case 'opencl':
+            return builder.software().rusticl().build();
+        case 'xvfb':
+            return {};
+    }
+}
+/** advisory thread count: one rasterizer thread per host core bounded by
+ * the compile-time lp_max_threads=32 ceiling. */
+function advisethreads(hostcores = cpus().length) {
+    return Math.max(1, Math.min(hostcores, llvmpipe.threadceiling));
+}
+/* ------------------------------------------------------------------ */
+/* context: smi format helpers (89-char summary table)                 */
+/* ------------------------------------------------------------------ */
+const smiwidth = 89;
+const smicolumns = [40, 24, 21];
+const procwidth = 75;
+/** right-pad helper that never exceeds the target width. */
+function smipad(text, width) {
+    return text.length >= width ? text.slice(0, width) : text + ' '.repeat(width - text.length);
+}
+/** left-pad helper for right-aligned smi columns. */
+function smipadstart(text, width) {
+    return text.length >= width
+        ? text.slice(text.length - width)
+        : ' '.repeat(width - text.length) + text;
+}
+/** full-width border line: "+" plus 87 fill characters plus "+". */
+function smiborder(fill) {
+    return `+${fill.repeat(smiwidth - 2)}+`;
+}
+/** full-width content line padded to the 89-char table width. */
+function smifull(content) {
+    return `|${smipad(content, smiwidth - 2)}|`;
+}
+/** three-column separator: pipes at fixed offsets 1, 42 and 67. */
+function smisep(fill) {
+    return ('|' +
+        fill.repeat(smicolumns[0]) +
+        '+' +
+        fill.repeat(smicolumns[1]) +
+        '+' +
+        fill.repeat(smicolumns[2]) +
+        '|');
+}
+/** three-column data row within the 89-char width. */
+function smirow(left, mid, right) {
+    return ('|' +
+        smipad(left, smicolumns[0]) +
+        '|' +
+        smipad(mid, smicolumns[1]) +
+        '|' +
+        smipad(right, smicolumns[2]) +
+        '|');
+}
+/** process table content line within the 75-char width. */
+function procline(content) {
+    return `|${smipad(content, procwidth - 2)}|`;
+}
+/** process table bottom border. */
+function procborder() {
+    return `+${'-'.repeat(procwidth - 2)}+`;
+}
+const smiweekdays = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const smimonths = [
+    'Jan',
+    'Feb',
+    'Mar',
+    'Apr',
+    'May',
+    'Jun',
+    'Jul',
+    'Aug',
+    'Sep',
+    'Oct',
+    'Nov',
+    'Dec',
+];
+/** formats the nvidia-smi timestamp "day-of-week month day hh:mm:ss year". */
+function formatstamp(date) {
+    const two = (value) => String(value).padStart(2, '0');
+    return (`${smiweekdays[date.getDay()]} ${smimonths[date.getMonth()]} ${two(date.getDate())} ` +
+        `${two(date.getHours())}:${two(date.getMinutes())}:${two(date.getSeconds())} ${date.getFullYear()}`);
+}
+/** builds a full virtual nvidia-smi adapter report; the header pins driver
+ * 575.57.08 and cuda 12.9 exactly as verified in the project research.
+ * notes: perf states span p0-p12, compute modes are default or exclusive
+ * process, mig is reported as n/a when disabled and fan speed may legally
+ * exceed 100% per the nvidia-smi documentation. */
+class smiadapterbuilder {
+    #profile;
+    #index;
+    #memusedmib = 0;
+    #util = 0;
+    #temperature = 41;
+    #fanspeed = 30;
+    #powerw;
+    #ecc = 'N/A';
+    #computemode = 'Default';
+    #processes = [];
+    constructor(profile, index = 0) {
+        this.#profile = profile;
+        this.#index = index;
+        this.#powerw = Math.max(10, Math.round(profile.tdpw * 0.04));
+    }
+    withmemused(mib) {
+        this.#memusedmib = mib;
+        return this;
+    }
+    withutil(percent) {
+        this.#util = percent;
+        return this;
+    }
+    withtemperature(celsius) {
+        this.#temperature = celsius;
+        return this;
+    }
+    withfanspeed(percent) {
+        this.#fanspeed = percent;
+        return this;
+    }
+    withpower(watts) {
+        this.#powerw = watts;
+        return this;
+    }
+    withecc(text) {
+        this.#ecc = text;
+        return this;
+    }
+    withcomputemode(mode) {
+        this.#computemode = mode;
+        return this;
+    }
+    withprocess(entry) {
+        this.#processes.push(entry);
+        return this;
+    }
+    /** derives a realistic bus id from the gpu index. */
+    #busid() {
+        const bus = String(1 + this.#index).padStart(2, '0');
+        return `00000000:${bus}:00.0`;
+    }
+    /** renders the complete report; the summary table is exactly 89 chars. */
+    build() {
+        try {
+            const head = ' NVIDIA-SMI ' +
+                mesastack.smidriver +
+                ' '.repeat(13) +
+                'Driver Version: ' +
+                mesastack.smidriver +
+                ' '.repeat(6) +
+                'CUDA Version: ' +
+                mesastack.cudaversion;
+            const lines = [
+                formatstamp(new Date()),
+                smiborder('-'),
+                smifull(head),
+                smisep('-'),
+                smirow(smipad(' GPU  Name', 27) + smipad('Persistence-M', 13), smipad(' Bus-Id          Disp.A', 24), ` ${smipadstart('Volatile Uncorr. ECC', 20)}`),
+                smirow(smipad(' Fan  Temp   Perf      Pwr:Usage/Cap', 40), smipad('         Memory-Usage', 24), ` ${smipadstart('GPU-Util  Compute M.', 20)}`),
+                smisep('='),
+                smirow(smipad(`   ${this.#index}  ${this.#profile.name}`, 36) + smipad('Off', 4), smipad(`   ${this.#busid()}  Off`, 24), ` ${smipadstart(this.#ecc, 20)}`),
+                smirow(smipad(` ${this.#fanspeed}%   ${this.#temperature}C  P0   ${this.#powerw}W / ${this.#profile.tdpw}W`, 40), smipadstart(`${this.#memusedmib}MiB / ${this.#profile.vrammib}MiB`, 24), smipadstart(`${this.#util}%`, 10) + smipad(`  ${this.#computemode}`, 11)),
+                smirow('', '', ''),
+                smiborder('-'),
+                '',
+                'Processes:',
+                procline(smipad(' GPU  GI  CI', 20) +
+                    smipad('PID', 7) +
+                    smipad('Type', 8) +
+                    smipad('Process name', 27) +
+                    smipad('GPU Memory', 11)),
+                procline('='.repeat(procwidth - 2)),
+            ];
+            if (this.#processes.length === 0) {
+                lines.push(procline('  No running processes found'));
+            }
+            else {
+                for (const entry of this.#processes) {
+                    lines.push(procline(smipad(` ${entry.gpu}   ${entry.gi}   ${entry.ci}`, 20) +
+                        smipad(String(entry.pid), 7) +
+                        smipad(entry.type, 8) +
+                        smipad(entry.name, 27) +
+                        smipad(`${entry.memorymib}MiB`, 11)));
+                }
+            }
+            lines.push(procborder());
+            return lines.join('\n');
+        }
+        catch (error) {
+            throw new Error(`virtual nvidia-smi adapter report failed: ${errormessage(error)}`);
+        }
+    }
+}
+/** normalizes an unknown thrown value into a message string. */
+function errormessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** runs a command to completion under a merged environment; every spawn
+ * path is wrapped in a try/catch catcher for later tracing. */
+function run(command, args, env = {}) {
+    return new Promise((resolve, reject) => {
+        try {
+            const child = spawn(command, args, { env: { ...process.env, ...env } });
+            let stdout = '';
+            let stderr = '';
+            child.stdout?.on('data', (chunk) => {
+                stdout += chunk.toString('utf8');
+            });
+            child.stderr?.on('data', (chunk) => {
+                stderr += chunk.toString('utf8');
+            });
+            child.once('error', (error) => {
+                reject(new Error(`${command} failed to spawn: ${error.message}`));
+            });
+            child.once('close', (code) => {
+                resolve({ code: code ?? -1, stdout, stderr });
+            });
+        }
+        catch (error) {
+            reject(new Error(`${command} failed: ${errormessage(error)}`));
+        }
+    });
+}
+/** returns the first regex capture group of a text or null. */
+function firstmatch(text, pattern) {
+    const found = pattern.exec(text);
+    return found === null ? null : (found[1] ?? '').trim() || null;
+}
+/* ------------------------------------------------------------------ */
+/* context: renderer base class                                        */
+/* ------------------------------------------------------------------ */
+/** shared renderer state: environment, optional child process and a
+ * trace buffer used as the embedded debugger for later tracing. */
+class rendererbase {
+    #child = null;
+    #label;
+    #vars;
+    #trace = [];
+    constructor(label, vars) {
+        this.#label = label;
+        this.#vars = { ...vars };
+    }
+    get label() {
+        return this.#label;
+    }
+    /** environment copy for the render target. */
+    get env() {
+        return { ...this.#vars };
+    }
+    /** whether the owned helper process is alive. */
+    get running() {
+        return this.#child !== null && this.#child.exitCode === null && !this.#child.killed;
+    }
+    /** accumulated trace entries (error catcher output). */
+    get traces() {
+        return this.#trace;
+    }
+    /** records a trace entry; never throws. */
+    note(message) {
+        this.#trace.push(`${new Date().toISOString()} ${message}`);
+    }
+    /** spawns a long-lived helper under the renderer environment. */
+    launch(command, args) {
+        const child = spawn(command, args, {
+            env: { ...process.env, ...this.#vars },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        child.on('error', (error) => {
+            this.note(`helper ${command} error: ${error.message}`);
+        });
+        this.#child = child;
+        return child;
+    }
+    /** terminates the helper; escalates to SIGKILL after a grace period. */
+    async stop() {
+        const child = this.#child;
+        if (child === null || child.exitCode !== null) {
+            this.#child = null;
+            return;
+        }
+        try {
+            child.kill('SIGTERM');
+            const exited = await Promise.race([
+                new Promise((resolve) => {
+                    child.once('exit', () => resolve());
+                }),
+                sleep(2000).then(() => false),
+            ]);
+            if (exited === false && child.exitCode === null) {
+                child.kill('SIGKILL');
+            }
+            this.note(`helper for ${this.#label} stopped`);
+        }
+        catch (error) {
+            this.note(`stop failed for ${this.#label}: ${errormessage(error)}`);
+        }
+        finally {
+            this.#child = null;
+        }
+    }
+    /** `using` disposal hook: stops the helper without awaiting. */
+    [Symbol.dispose]() {
+        try {
+            void this.stop();
+        }
+        catch (error) {
+            this.note(`dispose failed for ${this.#label}: ${errormessage(error)}`);
+        }
+    }
+}
+/** promise-based sleep used by the stop escalation. */
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/* ------------------------------------------------------------------ */
+/* context: llvmpipe / lavapipe / rusticl renderers                    */
+/* ------------------------------------------------------------------ */
+/** opengl/gles renderer backed by llvmpipe. */
+class llvmpiperenderer extends rendererbase {
+    constructor(env) {
+        super('llvmpipe', env === undefined ? renderenv('opengl') : env);
+    }
+    /** probes glxinfo -b and returns the core profile version string. */
+    async verify() {
+        try {
+            const result = await run('glxinfo', ['-B'], this.env);
+            const version = firstmatch(result.stdout, /core profile version string:\s*(.+)/);
+            this.note(`glxinfo exit ${result.code}: ${version ?? 'no version line'}`);
+            return version ?? '';
+        }
+        catch (error) {
+            throw new Error(`llvmpipe verify failed: ${errormessage(error)}`);
+        }
+    }
+    /** runs a workload command inside the llvmpipe environment. */
+    async runworkload(command, args) {
+        return run(command, args, this.env);
+    }
+}
+/** vulkan renderer backed by lavapipe. */
+class lavapiperenderer extends rendererbase {
+    constructor(env) {
+        super('lavapipe', env === undefined ? renderenv('vulkan') : env);
+    }
+    /** probes vulkaninfo --summary and returns the api version. */
+    async verify() {
+        try {
+            const result = await run('vulkaninfo', ['--summary'], this.env);
+            const version = firstmatch(result.stdout, /apiVersion\s*:\s*([\d.]+)/);
+            this.note(`vulkaninfo exit ${result.code}: ${version ?? 'no version line'}`);
+            return version ?? '';
+        }
+        catch (error) {
+            throw new Error(`lavapipe verify failed: ${errormessage(error)}`);
+        }
+    }
+    /** runs a workload command inside the lavapipe environment. */
+    async runworkload(command, args) {
+        return run(command, args, this.env);
+    }
+}
+/** opencl renderer backed by rusticl. */
+class rusticlrenderer extends rendererbase {
+    constructor(env) {
+        super('rusticl', env === undefined ? renderenv('opencl') : env);
+    }
+    /** probes clinfo and returns the reported opencl version. */
+    async verify() {
+        try {
+            const result = await run('clinfo', [], this.env);
+            const version = firstmatch(result.stdout, /OpenCL (\d+\.\d+)/);
+            this.note(`clinfo exit ${result.code}: ${version ?? 'no version line'}`);
+            return version ?? '';
+        }
+        catch (error) {
+            throw new Error(`rusticl verify failed: ${errormessage(error)}`);
+        }
+    }
+    /** runs a workload command inside the rusticl environment. */
+    async runworkload(command, args) {
+        return run(command, args, this.env);
+    }
+}
+/** headless glx display server; the child is terminated on dispose. */
+class xvfbdisplay extends rendererbase {
+    #displaynumber;
+    #geometry;
+    constructor(options = {}) {
+        const displaynumber = options.display ?? randomdisplay();
+        super('xvfb', { DISPLAY: `:${displaynumber}`, ...options.env });
+        this.#displaynumber = displaynumber;
+        this.#geometry = options.geometry ?? defaultgeometry;
+    }
+    /** display number without the leading colon (for example "94"). */
+    get displaynumber() {
+        return this.#displaynumber;
+    }
+    /** geometry string in the widthxheightxdepth form. */
+    get geometry() {
+        return this.#geometry;
+    }
+    /** boots xvfb and waits for the socket grace period. */
+    async start() {
+        try {
+            const child = this.launch('Xvfb', xvfbargs(this.#displaynumber, this.#geometry));
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => resolve(), 600);
+                child.once('exit', (code) => {
+                    clearTimeout(timer);
+                    reject(new Error(`xvfb exited early with code ${code ?? 'signal'}`));
+                });
+                child.once('error', (error) => {
+                    clearTimeout(timer);
+                    reject(error);
+                });
+            });
+            this.note(`xvfb serving display :${this.#displaynumber} at ${this.#geometry}`);
+        }
+        catch (error) {
+            throw new Error(`xvfb start failed: ${errormessage(error)}`);
+        }
+    }
+    /** reports the served display. */
+    async verify() {
+        return `display :${this.#displaynumber} geometry ${this.#geometry}`;
+    }
+}
+/* ------------------------------------------------------------------ */
+/* context: renderer factory (factory pattern)                         */
+/* ------------------------------------------------------------------ */
+/** creates concrete renderers per target; the preset environment can be
+ * overridden per call (user choice), for example to merge an xvfb display. */
+class rendererfactory {
+    #builders = new Map();
+    constructor() {
+        this.#builders.set('opengl', (env) => new llvmpiperenderer(env));
+        this.#builders.set('gles', (env) => new llvmpiperenderer({ ...renderenv('gles'), ...env }));
+        this.#builders.set('vulkan', (env) => new lavapiperenderer(env));
+        this.#builders.set('opencl', (env) => new rusticlrenderer(env));
+        this.#builders.set('xvfb', (env) => new xvfbdisplay({ env }));
+    }
+    /** registers a custom builder for a target (extensibility hook). */
+    register(target, builder) {
+        this.#builders.set(target, builder);
+        return this;
+    }
+    /** instantiates the renderer for a target. */
+    create(target, env) {
+        const build = this.#builders.get(target);
+        if (build === undefined) {
+            throw new Error(`unknown render target "${target}"`);
+        }
+        return build(env);
+    }
+}
+/* ------------------------------------------------------------------ */
+/* context: renderer proxy (proxy pattern)                             */
+/* ------------------------------------------------------------------ */
+/** environment keys that define the virtual identity and can never be overridden. */
+const frozenenvkeys = [
+    'LIBGL_ALWAYS_SOFTWARE',
+    'GALLIUM_DRIVER',
+    'VK_DRIVER_FILES',
+    'RUSTICL_ENABLE',
+    'LP_NUM_THREADS',
+];
+/** proxy that guards the renderer environment, keeps an audit trail and
+ * delegates lifecycle calls to the wrapped renderer. */
+class rendererproxy {
+    #inner;
+    #frozen;
+    #audit = [];
+    constructor(inner, frozen = frozenenvkeys) {
+        this.#inner = inner;
+        this.#frozen = new Set(frozen);
+    }
+    get label() {
+        return this.#inner.label;
+    }
+    /** environment copy; reads are recorded in the audit trail. */
+    get env() {
+        this.#audit.push(`read env for ${this.#inner.label}`);
+        return this.#inner.env;
+    }
+    /** accumulated audit entries. */
+    get audit() {
+        return this.#audit;
+    }
+    /** merges overrides over the renderer environment while refusing to
+     * clobber the frozen virtual identity keys; returns the merged copy. */
+    patchenv(overrides) {
+        const merged = { ...this.#inner.env };
+        for (const [key, value] of Object.entries(overrides)) {
+            if (this.#frozen.has(key)) {
+                this.#audit.push(`refused override of ${key}`);
+                continue;
+            }
+            merged[key] = value;
+        }
+        return merged;
+    }
+    /** delegates verification. */
+    async verify() {
+        return this.#inner.verify();
+    }
+    /** delegates disposal. */
+    [Symbol.dispose]() {
+        this.#inner[Symbol.dispose]();
+    }
+}
+/** probes glxinfo, vulkaninfo and clinfo under the given environment and
+ * parses the virtualized version strings; failures degrade into notes. */
+async function renderprobe(env) {
+    const notes = [];
+    let opengl = '';
+    let vulkan = '';
+    let opencl = '';
+    try {
+        const glx = await run('glxinfo', ['-B'], env);
+        opengl = firstmatch(glx.stdout, /core profile version string:\s*(.+)/) ?? '';
+        if (opengl === '')
+            notes.push('glxinfo returned no core profile version line');
+    }
+    catch (error) {
+        notes.push(`glxinfo failed: ${errormessage(error)}`);
+    }
+    try {
+        const vk = await run('vulkaninfo', ['--summary'], env);
+        vulkan = firstmatch(vk.stdout, /apiVersion\s*:\s*([\d.]+)/) ?? '';
+        if (vulkan === '')
+            notes.push('vulkaninfo returned no apiVersion line');
+    }
+    catch (error) {
+        notes.push(`vulkaninfo failed: ${errormessage(error)}`);
+    }
+    try {
+        const cl = await run('clinfo', [], env);
+        opencl = firstmatch(cl.stdout, /OpenCL (\d+\.\d+)/) ?? '';
+        if (opencl === '')
+            notes.push('clinfo returned no opencl version line');
+    }
+    catch (error) {
+        notes.push(`clinfo failed: ${errormessage(error)}`);
+    }
+    return { opengl, vulkan, opencl, notes };
+}
+/* ------------------------------------------------------------------ */
+/* context: end-to-end demo with `using` disposal                      */
+/* ------------------------------------------------------------------ */
+/** boots xvfb, assembles the full software environment (opengl + vulkan +
+ * opencl presets) and probes all three apis; every resource is released
+ * through the `using` disposal at scope exit. */
+export async function renderdemo(profilename = 'rtx5090') {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        const profile = defaultgpuregistry.require(profilename);
+        const display = __addDisposableResource(env_1, new xvfbdisplay({ env: { VHE_GPU_PROFILE: profile.name } }), false);
+        await display.start();
+        const env = {
+            ...display.env,
+            ...renderenv('opengl'),
+            ...renderenv('vulkan'),
+            ...renderenv('opencl'),
+        };
+        return renderprobe(env);
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        __disposeResources(env_1);
+    }
+}
+export { advisethreads, cpucapsdomain, defaultgeometry, defaultgpuregistry, gpuprofilebuilder, gpuregistry, gpuspoofdata, lavapipe, llvmpipe, mesaenvbuilder, mesastack, pciid, randomdisplay, renderenv, rendererfactory, rendererproxy, renderprobe, run, rusticl, smiadapterbuilder, xvfbargs, xvfbdisplay, };
+//# sourceMappingURL=render.js.map