omnius 1.0.882 → 1.0.883

package/dist/omni-setup-worker.js

@@ -246907,12 +246907,16 @@ async function hostFacts(d) {
     {},
     false
   ).catch(() => ({ code: -1, stdout: "", stderr: "" }));
-  const discovery = discovered.code === 0 && Buffer.byteLength(discovered.stdout) <= 1024 * 1024 ? json(discovered.stdout) : void 0;
-  const installedBytes = await d.readHostFile("/usr/local/share/ollama-unify/gpu-negotiator.json").catch(() => Buffer.alloc(0));
+  const discovery = Buffer.byteLength(discovered.stdout) <= 1024 * 1024 ? json(discovered.stdout) : void 0;
+  let installationAbsent = false;
+  const installedBytes = await d.readHostFile("/usr/local/share/ollama-unify/gpu-negotiator.json").catch((error2) => {
+    installationAbsent = error2.code === "ENOENT";
+    return Buffer.alloc(0);
+  });
   const installed = installedBytes.length <= 1024 * 1024 ? json(installedBytes.toString()) : void 0;
-  const brokerDetected = discovered.code === 0 || installed?.protocol === BROKER_PROTOCOL;
-  const broker = discovery?.protocol === BROKER_PROTOCOL && discovery.available === true && typeof discovery.control_socket === "string" && discovery.control_socket.startsWith("/");
-  const ollamaHost = broker ? loopbackOllama(discovery?.public_ollama_api) ?? (installed?.protocol === BROKER_PROTOCOL ? loopbackOllama(installed.public_ollama_api) : void 0) : !brokerDetected && capableTegra ? "http://127.0.0.1:11434" : void 0;
+  const brokerDetected = discovered.code === 0 || discovery?.protocol === BROKER_PROTOCOL || !installationAbsent;
+  const broker = discovered.code === 0 && discovery?.protocol === BROKER_PROTOCOL && discovery.available === true && typeof discovery.control_socket === "string" && discovery.control_socket.startsWith("/");
+  const ollamaHost = broker ? loopbackOllama(discovery?.public_ollama_api) ?? (installed?.protocol === BROKER_PROTOCOL ? loopbackOllama(installed.public_ollama_api) : void 0) : !brokerDetected ? "http://127.0.0.1:11434" : void 0;
   const warnings = Array.isArray(discovery?.warnings) ? discovery.warnings.slice(0, 12).map((warning) => safeSummary(warning)) : [];
   const activeLeases = Array.isArray(discovery?.active_leases) ? discovery.active_leases : [];
   const summaries = activeLeases.slice(0, 12).map(
@@ -246947,7 +246951,7 @@ async function hostFacts(d) {
       );
       const capable = Number.isFinite(Number(memory)) && Number(memory) >= OMNI_RUNTIME_RESERVATIONS_MIB.ornith15 && Number.isFinite(Number(compute)) && Number(compute) >= 7;
       const eligible = Boolean(
-        policyReady && selected && capable && !held && !quarantined && !missing && !transitioning && ollamaHost
+        capable && !held && (!brokerDetected && !tegra || policyReady && selected && !quarantined && !missing && !transitioning) && ollamaHost
       );
       devices.push({
         uuid,
@@ -246955,7 +246959,7 @@ async function hostFacts(d) {
         eligible,
         ...Number.isFinite(Number(memory)) ? { memoryMiB: Number(memory) } : {},
         ...!eligible ? {
-          reason: held ? "Operator inference hold is active." : !broker ? "GPU broker discovery is unavailable or invalid." : !policyReady ? "GPU broker health or admission metadata does not permit new work." : !selected || missing ? "GPU is outside the healthy broker-selected scope." : quarantined ? "GPU has quarantined unregistered work." : transitioning ? "GPU has a pending or revoking lease." : !capable ? "Requires compute capability 7.0+ and at least 24,000 MiB VRAM; Qwen requires 45,000 MiB." : "A verified loopback Ollama service endpoint is required."
+          reason: !brokerDetected && tegra ? "Integrated Tegra deployments require the supported SoC admission path." : held ? "Operator inference hold is active." : brokerDetected && !broker ? "GPU broker discovery is unavailable or invalid." : brokerDetected && !policyReady ? "GPU broker health or admission metadata does not permit new work." : brokerDetected && (!selected || missing) ? "GPU is outside the healthy broker-selected scope." : brokerDetected && quarantined ? "GPU has quarantined unregistered work." : brokerDetected && transitioning ? "GPU has a pending or revoking lease." : !capable ? "Requires compute capability 7.0+ and at least 24,000 MiB VRAM; Qwen requires 45,000 MiB." : "A verified loopback Ollama service endpoint is required."
         } : {}
       });
     }
@@ -246991,6 +246995,7 @@ async function inspectOmniHost(input, options = {}) {
     `Derived speech GGUF cache: ${join13(p.runtime, "components")} (additional local disk usage, retained on cancellation).`,
     "GPU reservation: Ornith 24,000 MiB; Qwen 45,000 MiB. Download size is not a VRAM promise; Tegra uses upstream UMA admission.",
     `Verified local Ollama endpoint: ${facts.ollamaHost ?? "unavailable"}`,
+    facts.brokerDetected ? "GPU admission uses the installed broker; invalid discovery, holds and lease transitions block setup." : "No GPU broker installation was found. The upstream direct supervisor requires the chosen accelerator, current capacity and actual owned-runner residency proof; it does not coordinate external GPU workloads.",
     `Private operation diagnostics: ${join13(p.root, "setup-<operationId>.log")} (bounded, owner-only).`,
     ...facts.warnings.map((warning) => `Broker warning: ${warning}`),
     ...facts.summaries
@@ -247008,7 +247013,8 @@ async function inspectOmniHost(input, options = {}) {
     "ffmpeg",
     "ollama",
     "systemctl",
-    ...facts.broker ? ["docker", "jq", "curl", "openssl", "setsid", "ss", "nvidia-smi"] : []
+    ...!facts.tegra || facts.broker ? ["nvidia-smi"] : [],
+    ...facts.broker ? ["docker", "jq", "curl", "openssl", "setsid", "ss"] : []
   ]) {
     const found = await command(
       d,
@@ -247032,10 +247038,6 @@ async function inspectOmniHost(input, options = {}) {
   ).catch(() => ({ code: -1, stdout: "", stderr: "" }));
   if (!["running", "degraded"].includes(userBus.stdout.trim()))
     blockedReasons.push("A working systemd user manager is required.");
-  if (!facts.brokerDetected && !facts.tegra)
-    blockedReasons.push(
-      "Discrete CUDA deployment requires the ollama-unify GPU broker; direct or CPU fallback is disabled."
-    );
   if (facts.brokerDetected && !facts.broker)
     blockedReasons.push(
       "Installed GPU broker discovery is unavailable or invalid; direct fallback is disabled."
@@ -247243,7 +247245,7 @@ async function proof(d, p, model, gpuUuid, direct, startedAt, signal) {
     const state = json(
       (await optionalFile(join13(p.runtime, "state", "daemon-status.json")))?.toString() ?? ""
     );
-    if (state?.schema !== "robit.qwen-omni-daemon.status.v1" || state.state !== "ready" || state.model !== model || state.pid !== status.pid || state.updated_at * 1e3 < startedAt || state.startup_smoke !== false)
+    if (state?.schema !== "robit.qwen-omni-daemon.status.v1" || state.state !== "ready" || state.model !== model || state.pid !== status.pid || !Number.isFinite(state.updated_at) || state.updated_at * 1e3 < startedAt || state.startup_smoke !== false)
       return false;
     const child = Array.isArray(state.children) ? state.children.find((item) => item.name === "comprehension") : void 0;
     if (!child || !Number.isSafeInteger(child.pid) || !pids.includes(child.pid))
@@ -247253,14 +247255,17 @@ async function proof(d, p, model, gpuUuid, direct, startedAt, signal) {
       p.python,
       [
         "-c",
-        "import json,sys; from qwen_omni_adapters.accelerator import process_is_gpu_resident,residency_backend; print(json.dumps({'resident':process_is_gpu_resident(int(sys.argv[1])),'backend':residency_backend()}))",
-        String(child.pid)
+        "import json,sys; from qwen_omni_adapters.accelerator import process_is_gpu_resident,residency_backend; print(json.dumps({'resident':process_is_gpu_resident(int(sys.argv[1]),sys.argv[2]),'backend':residency_backend()}))",
+        String(child.pid),
+        gpuUuid === "tegra-integrated" ? "" : gpuUuid
       ],
       { signal, timeoutMs: 5e3 },
       false
     );
     const resident = json(result.stdout);
-    return resident?.resident === true && resident.backend === "tegra-device-handles";
+    if (result.code !== 0 || resident?.resident !== true) return false;
+    if (gpuUuid === "tegra-integrated") return resident.backend === "tegra-device-handles";
+    return resident.backend === "nvidia-smi-compute-apps" && await discreteResidency(d, p, pids, gpuUuid, signal, child.pid);
   }
   const ready = await command(
     d,
@@ -247297,6 +247302,9 @@ async function proof(d, p, model, gpuUuid, direct, startedAt, signal) {
     (lease) => lease.owner === p.ownerName && lease.state === "active" && Array.isArray(lease.gpu_uuids) && lease.gpu_uuids.length === 1 && lease.gpu_uuids[0] === gpuUuid
   ))
     return false;
+  return discreteResidency(d, p, pids, gpuUuid, signal);
+}
+async function discreteResidency(d, p, pids, gpuUuid, signal, requiredPid) {
   const processes = await command(
     d,
     "nvidia-smi",
@@ -247318,7 +247326,7 @@ async function proof(d, p, model, gpuUuid, direct, startedAt, signal) {
         "Owned CUDA work was observed outside the designated accelerator."
       );
     const cmd = (await d.readHostFile(`/proc/${pid}/cmdline`)).toString().split("\0"), env = (await d.readHostFile(`/proc/${pid}/environ`)).toString().split("\0");
-    if (cmd[0] === join13(
+    if ((requiredPid === void 0 || requiredPid === pid) && cmd[0] === join13(
       p.checkout,
       "vendor",
       "llama.cpp",
@@ -247330,6 +247338,13 @@ async function proof(d, p, model, gpuUuid, direct, startedAt, signal) {
   }
   return seen;
 }
+async function admitDirectDiscrete(d, gpuUuid, requiredMiB, signal) {
+  const result = await command(d, "nvidia-smi", ["--query-gpu=uuid,memory.free", "--format=csv,noheader,nounits"], { signal, timeoutMs: 5e3 }, false);
+  const rows = result.stdout.split("\n").map((line) => line.split(",").map((value) => value.trim())).filter((row) => row[0] === gpuUuid);
+  const freeMiB = rows.length === 1 && rows[0].length === 2 ? Number(rows[0][1]) : NaN;
+  if (result.code !== 0 || !Number.isFinite(freeMiB) || freeMiB < requiredMiB)
+    fail("accelerator_not_admitted", "The chosen GPU does not currently report sufficient free VRAM for the selected profile. No service was started; no external workload was stopped.");
+}
 async function verifySource(d, p, signal) {
   const revision = await command(
     d,
@@ -247571,7 +247586,8 @@ ${diagnostic.stderr.slice(-65536)}` : ""}`,
         "An existing healthy Omni stack must be attached explicitly; it will not be replaced."
       );
     const facts = await hostFacts(d);
-    direct = facts.tegra && !facts.brokerDetected;
+    direct = !facts.brokerDetected;
+    const directTegra = direct && facts.tegra;
     if (facts.held)
       return {
         state: "held-paused",
@@ -247586,7 +247602,7 @@ ${diagnostic.stderr.slice(-65536)}` : ""}`,
         "accelerator_required",
         "Choose an exact eligible accelerator from the current plan."
       );
-    if (direct && input.gpuUuid !== "tegra-integrated" || !direct && !GPU_UUID.test(input.gpuUuid))
+    if (directTegra && input.gpuUuid !== "tegra-integrated" || !directTegra && !GPU_UUID.test(input.gpuUuid))
       fail(
         "accelerator_required",
         "The selected accelerator does not match this host's deployment mode."
@@ -247594,7 +247610,7 @@ ${diagnostic.stderr.slice(-65536)}` : ""}`,
     const selectedDevice = facts.devices.find(
       (device) => device.uuid === input.gpuUuid
     );
-    if (!direct && (selectedDevice.memoryMiB ?? 0) < OMNI_RUNTIME_RESERVATIONS_MIB[input.profile])
+    if (!directTegra && (selectedDevice.memoryMiB ?? 0) < OMNI_RUNTIME_RESERVATIONS_MIB[input.profile])
       fail(
         "insufficient_vram",
         `The selected profile requires at least ${OMNI_RUNTIME_RESERVATIONS_MIB[input.profile].toLocaleString("en-US")} MiB total GPU memory before any build or model download.`
@@ -247747,7 +247763,7 @@ ${diagnostic.stderr.slice(-65536)}` : ""}`,
       OMNI_LANGUAGE_MODEL: profile.model,
       OMNI_PORTAL_RUNTIME_ROOT: p.runtime,
       OMNI_COMPREHENSION_GPU_UUID: input.gpuUuid,
-      CUDA_VISIBLE_DEVICES: direct ? "0" : input.gpuUuid,
+      CUDA_VISIBLE_DEVICES: directTegra ? "0" : input.gpuUuid,
       HIP_VISIBLE_DEVICES: "-1",
       ROCR_VISIBLE_DEVICES: "-1",
       OMNI_ENABLE_POINTING: "0",
@@ -247756,7 +247772,7 @@ ${diagnostic.stderr.slice(-65536)}` : ""}`,
       OMNI_STARTUP_SMOKE: "0",
       OMNI_PRINT_ACCESS_URL: "0",
       OMNI_KEEP_CACHE: "1",
-      OMNI_COMPREHENSION_CONTEXT_TOKENS: direct && input.profile === "qwen38" ? "16384" : "65536",
+      OMNI_COMPREHENSION_CONTEXT_TOKENS: directTegra && input.profile === "qwen38" ? "16384" : "65536",
       OMNI_COMPREHENSION_VRAM_MIB: String(
         OMNI_RUNTIME_RESERVATIONS_MIB[input.profile]
       ),
@@ -247797,13 +247813,13 @@ ${diagnostic.stderr.slice(-65536)}` : ""}`,
         message: "Runtime source and private configuration are installed; operator pause is preserved and no readiness is claimed."
       };
     if (fresh.broker !== facts.broker || fresh.brokerDetected !== facts.brokerDetected || fresh.ollamaHost !== facts.ollamaHost || !fresh.devices.some(
-      (device) => device.uuid === input.gpuUuid && device.eligible && (direct || (device.memoryMiB ?? 0) >= OMNI_RUNTIME_RESERVATIONS_MIB[input.profile])
+      (device) => device.uuid === input.gpuUuid && device.eligible && (directTegra || (device.memoryMiB ?? 0) >= OMNI_RUNTIME_RESERVATIONS_MIB[input.profile])
     ))
       fail(
         "accelerator_policy_changed",
         "Accelerator admission changed before service activation."
       );
-    if (direct) {
+    if (directTegra) {
       const admission = await command(
         d,
         p.python,
@@ -247821,7 +247837,7 @@ ${diagnostic.stderr.slice(-65536)}` : ""}`,
           "accelerator_not_admitted",
           "Tegra memory and utilization admission did not pass."
         );
-    }
+    } else if (direct) await admitDirectDiscrete(d, input.gpuUuid, OMNI_RUNTIME_RESERVATIONS_MIB[input.profile], options.signal);
     linked = true;
     await command(d, "systemctl", ["--user", "link", p.unitPath], {
       signal: options.signal
@@ -247859,6 +247875,7 @@ ${diagnostic.stderr.slice(-65536)}` : ""}`,
           adapterUrl: "http://127.0.0.1:8910",
           profile: input.profile,
           sourceRevision: OMNI_SETUP_SOURCE.revision,
+          accelerator: { mode: direct ? directTegra ? "direct-tegra" : "direct-discrete" : "broker", gpuUuid: input.gpuUuid },
           verified: {
             adapterContract: true,
             runtime: true,
@@ -300707,8 +300724,14 @@ function stored(root, id2) {
   if (!value) throw error("setup_job_missing", "Omni setup job was not found.", 404);
   if (value.version !== 1 || value.job?.id !== id2 || value.job.schema !== "omnius.omni-setup-job.v1" || !states.has(value.job.state) || !phases.has(value.job.phase) || !ID2.test(value.owner?.token ?? "") || !/^\d+$/.test(value.owner.start) || !Number.isInteger(value.owner.pid) || value.owner.pid <= 0 || !/^[0-9a-f]{64}$/.test(value.configurationRevision) || typeof value.gpuUuid !== "string" || !Number.isFinite(Date.parse(value.job.createdAt)) || !Number.isFinite(Date.parse(value.job.updatedAt)) || value.job.sourceRevision !== OMNI_SETUP_SOURCE.revision || !OMNI_SETUP_PROFILES.some((p) => p.id === value.job.profile && p.model === value.job.model)) throw error("invalid_setup_state", "Omni setup state has an invalid identity.");
   if (value.job.state === "ready" && (!value.job.receipt || value.job.receipt.model !== value.job.model || value.job.receipt.sourceRevision !== OMNI_SETUP_SOURCE.revision || value.job.receipt.action !== "deployed" || !value.job.receipt.verified?.adapterContract || !value.job.receipt.verified.runtime || !value.job.receipt.verified.accelerator)) throw error("invalid_setup_state", "Omni setup state is missing its readiness proof.");
+  if (value.job.receipt?.accelerator && !publicAccelerator(value.job.receipt.accelerator, value.gpuUuid)) throw error("invalid_setup_state", "Omni setup accelerator proof does not match the selected device.");
   return value;
 }
+function publicAccelerator(value, selected) {
+  if (!value || value.gpuUuid !== selected || !["broker", "direct-discrete", "direct-tegra"].includes(value.mode)) return;
+  if (value.mode === "direct-tegra" ? selected !== "tegra-integrated" : !/^GPU-[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(selected)) return;
+  return { mode: value.mode, gpuUuid: selected };
+}
 async function runOmniSetupJob(rootPath, id2) {
   const root = resolve11(rootPath), path3 = join14(root, "jobs", id2 + ".json");
   directory(root);
@@ -300787,6 +300810,7 @@ async function runOmniSetupJob(rootPath, id2) {
           throw new DOMException("Setup cancelled before commit", "AbortError");
         }
         if (receipt.model !== value.job.model || receipt.sourceRevision !== OMNI_SETUP_SOURCE.revision || receipt.action !== "deployed" || !receipt.verified.adapterContract || !receipt.verified.runtime || !receipt.verified.accelerator) throw error("setup_readiness_unverified", "Setup did not return complete runtime and accelerator proof.");
+        if (receipt.accelerator && !publicAccelerator(receipt.accelerator, value.gpuUuid)) throw error("setup_readiness_unverified", "Setup accelerator proof does not match the selected device.");
         const previous = readSavedOmniConfiguration(config.path);
         const revision = saveOmniConfiguration({ version: 1, model: receipt.model, adapterUrl: receipt.adapterUrl }, value.configurationRevision, config.path);
         try {

package/dist/tui/native/worker.js

@@ -248,13 +248,13 @@ import { spawn, execFile } from "node:child_process";
 import { realpath, lstat } from "node:fs/promises";
 import { extname, relative, resolve } from "node:path";
 import { Audio } from "@opentui/core";
-async function validateMediaFile(path, root) {
+async function validateMediaFile(path, root, allowSvg = false) {
   const info = await lstat(path);
   if (!info.isFile() || info.isSymbolicLink()) throw new Error("Media must be a regular local file");
   const canonical = await realpath(path), project = await realpath(root);
   const local = relative(project, canonical);
   if (local === ".." || local.startsWith("../") || resolve(project, local) !== canonical) throw new Error("Media is outside its project");
-  if (!/\.(png|jpe?g|webp|gif|mp4|webm|mov|mkv|wav|mp3|flac|ogg|opus|m4a|aiff?)$/i.test(extname(canonical))) throw new Error("Unsupported media file");
+  if (!/\.(png|jpe?g|webp|gif|mp4|webm|mov|mkv|wav|mp3|flac|ogg|opus|m4a|aiff?)$/i.test(extname(canonical)) && !(allowSvg && extname(canonical).toLowerCase() === ".svg")) throw new Error("Unsupported media file");
   return canonical;
 }
 async function probeMedia(spec, signal) {
@@ -585,7 +585,7 @@ var NativeMediaView = class extends BoxRenderable {
     }
     if (this.image) {
       this.image.visible = spec.kind === "image" || spec.kind === "video";
-      const source = spec.kind === "image" ? spec.path : spec.previewPath;
+      const source = spec.kind === "image" ? spec.previewPath ?? spec.path : spec.previewPath;
       if (source && this.image.source !== source && !this.playback.playing) {
         const epoch = this.sourceEpoch;
         void validateMediaFile(source, spec.projectRoot).then((path) => {
@@ -703,7 +703,7 @@ var NativeMediaView = class extends BoxRenderable {
   }
   async open() {
     try {
-      const path = await validateMediaFile(this.spec.path, this.spec.projectRoot);
+      const path = await validateMediaFile(this.spec.path, this.spec.projectRoot, this.spec.kind === "image" && !!this.spec.previewPath);
       if (this.isDestroyed) return;
       this.sendEvent({ type: "action", action: "media-open", id: this.mediaId, text: path });
       if (process.env["OMNIUS_MEDIA_TEST_NO_OPEN"] === "1") {
@@ -744,7 +744,7 @@ var NativeMediaView = class extends BoxRenderable {
 // packages/cli/src/tui/native/components/model3d.ts
 import { constants } from "node:fs";
 import { open } from "node:fs/promises";
-import { BoxRenderable as BoxRenderable2, FrameBufferRenderable, OptimizedBuffer, TextRenderable as TextRenderable2 } from "@opentui/core";
+import { BoxRenderable as BoxRenderable2, FrameBufferRenderable, OptimizedBuffer, RGBA as RGBA2, TextRenderable as TextRenderable2 } from "@opentui/core";
 
 // packages/cli/src/tui/native/model3d.ts
 var MODEL3D_MAX_BYTES = 16 * 1024 * 1024;
@@ -1008,7 +1008,7 @@ async function createEngine(renderer2, width, height, background2) {
   if (!process.versions["bun"] || !(process.platform === "linux" && process.arch === "x64" || process.platform === "darwin" || process.platform === "win32" && process.arch === "x64")) throw new Error("WebGPU is not packaged for this runtime.");
   const packageName = "@opentui/three";
   const { ThreeCliRenderer, SuperSampleType } = await import(packageName);
-  return new ThreeCliRenderer(renderer2, { width, height, autoResize: false, superSample: SuperSampleType.NONE, backgroundColor: background2 });
+  return new ThreeCliRenderer(renderer2, { width, height, autoResize: false, superSample: SuperSampleType.CPU, alpha: true, backgroundColor: RGBA2.fromValues(background2.r, background2.g, background2.b, 0) });
 }
 async function readCapture(path) {
   const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
@@ -1032,7 +1032,7 @@ async function readCapture(path) {
 }
 var NativeModel3DView = class extends BoxRenderable2 {
   constructor(renderer2, modelId, spec, colors, options = {}) {
-    super(renderer2, { id: `model3d:${modelId}`, width: "100%", flexDirection: "column", flexShrink: 0 });
+    super(renderer2, { id: `model3d:${modelId}`, width: "100%", flexDirection: "column", flexShrink: 0, shouldFill: false });
     this.renderer = renderer2;
     this.modelId = modelId;
     this.colors = colors;
@@ -1080,7 +1080,19 @@ var NativeModel3DView = class extends BoxRenderable2 {
     };
     this.cpu = new TextRenderable2(renderer2, { id: `model3d-cpu:${modelId}`, width: "100%", height: 12, flexShrink: 0, wrapMode: "none", content: "", fg: colors.accent, selectable: false, ...pointer });
     this.cpu.focusable = true;
-    this.surface = new FrameBufferRenderable(renderer2, { id: `model3d-surface:${modelId}`, width: 1, height: 12, flexShrink: 0, visible: false, ...pointer });
+    this.surface = new FrameBufferRenderable(renderer2, {
+      id: `model3d-surface:${modelId}`,
+      width: 1,
+      height: 12,
+      flexShrink: 0,
+      visible: false,
+      respectAlpha: true,
+      onSizeChange: () => {
+        this.dirty = true;
+        if (!this.closing) this.renderer.requestRender();
+      },
+      ...pointer
+    });
     this.surface.focusable = true;
     this.controls = new BoxRenderable2(renderer2, { id: `model3d-controls:${modelId}`, width: "100%", flexDirection: "row", flexWrap: "wrap", gap: 2, flexShrink: 0 });
     for (const [id, label3, action] of [
@@ -1140,6 +1152,8 @@ var NativeModel3DView = class extends BoxRenderable2 {
   loading;
   drawing;
   cleanup;
+  /** Bounded local diagnostic; a failed preview cleanup must not kill its TUI. */
+  cleanupDiagnostic;
   resolveClosed;
   closed;
   closing = false;
@@ -1268,11 +1282,14 @@ ${model.warnings.join(" ")}` : ""}`;
       this.camera.updateProjectionMatrix();
       this.status.content = `WebGPU · ${stats}${model.warnings.length ? `
 ${model.warnings.join(" ")}` : ""}`;
-      const staging = OptimizedBuffer.create(width, height, this.renderer.widthMethod, { owner: this.renderer.nativeScene, id: `model3d-stage:${this.modelId}` });
+      const staging = OptimizedBuffer.create(width, height, this.renderer.widthMethod, { owner: this.renderer.nativeScene, respectAlpha: true, id: `model3d-stage:${this.modelId}` });
+      staging.clear(RGBA2.fromValues(0, 0, 0, 0));
       this.engine.setSize(width, height);
       this.drawing = this.engine.drawScene(this.scene, staging, 0).then(() => {
-        if (!this.closing && !this.surface.isDestroyed && width === this.pixelWidth && height === this.pixelHeight) this.surface.frameBuffer.drawFrameBuffer(0, 0, staging);
-        else if (!this.closing) this.dirty = true;
+        if (!this.closing && !this.surface.isDestroyed && width === this.pixelWidth && height === this.pixelHeight) {
+          this.surface.frameBuffer.clear(RGBA2.fromValues(0, 0, 0, 0));
+          this.surface.frameBuffer.drawFrameBuffer(0, 0, staging);
+        } else if (!this.closing) this.dirty = true;
       }).catch(() => {
         if (!this.closing) {
           this.releaseScene();
@@ -1356,7 +1373,9 @@ ${model.warnings.join(" ")}` : ""}`;
           }
         }
       }
-    })();
+    })().catch((error) => {
+      this.cleanupDiagnostic = plainText(error instanceof Error ? error.message : "3D preview cleanup failed").slice(0, 200);
+    });
     return this.cleanup;
   }
   destroySelf() {
@@ -1933,13 +1952,17 @@ var NativeBlockView = class {
   applyTheme() {
     const colors = this.context.colors;
     this.root.backgroundColor = colors.background;
+    this.root.shouldFill = this.spec.kind !== "model3d";
     if (this.spec.kind === "card") this.root.borderColor = colors.border;
     else this.root.border = false;
     if (this.title) {
       this.title.fg = colors.foreground;
       this.title.bg = colors.background;
     }
-    if (this.body) this.body.backgroundColor = colors.background;
+    if (this.body) {
+      this.body.backgroundColor = colors.background;
+      this.body.shouldFill = this.spec.kind !== "model3d";
+    }
     if (this.text) {
       this.text.fg = colors.foreground;
       this.text.bg = colors.background;
@@ -2575,6 +2598,7 @@ var NativeModalView = class {
     this.hints.maxHeight = 2;
     this.actions = new BoxRenderable5(renderer2, { id: `modal-actions:${spec.id}`, flexDirection: "row", flexWrap: "wrap", flexShrink: 0, gap: 1, width: "100%", marginTop: 0 });
     this.panel.add(this.actions);
+    this.panel.renderBefore = this.paintModelChrome;
     this.update(spec);
     renderer2.on(CliRenderEvents3.RESIZE, this.fit);
     this.panel.on("resize", this.fit);
@@ -2615,6 +2639,31 @@ var NativeModalView = class {
   revealFocused = false;
   mediaViews = /* @__PURE__ */ new Set();
   modelViews = /* @__PURE__ */ new Set();
+  transparentModel = false;
+  paintModelChrome = (buffer) => {
+    if (!this.transparentModel || this.disposed || this.frame.animating) return;
+    const left = this.panel.x + 1, right = this.panel.x + this.panel.width - 1;
+    const top = this.panel.y + 1, bottom = this.panel.y + this.panel.height - 1;
+    if (right <= left || bottom <= top) return;
+    const viewport = this.body.viewport;
+    const canvases = [...this.modelViews].flatMap((model) => {
+      const canvas = [model.findDescendantById(`model3d-surface:${model.modelId}`), model.findDescendantById(`model3d-cpu:${model.modelId}`)].find((node) => node?.visible && !node.isDestroyed);
+      if (!canvas) return [];
+      const x = Math.max(left, viewport.x, canvas.x), y = Math.max(top, viewport.y, canvas.y);
+      const endX = Math.min(right, viewport.x + viewport.width, canvas.x + canvas.width);
+      const endY = Math.min(bottom, viewport.y + viewport.height, canvas.y + canvas.height);
+      return endX > x && endY > y ? [{ x, y, endX, endY }] : [];
+    }).sort((a, b) => a.x - b.x);
+    for (let y = top; y < bottom; y++) {
+      let x = left;
+      for (const canvas of canvases) {
+        if (y < canvas.y || y >= canvas.endY) continue;
+        if (canvas.x > x) buffer.fillRect(x, y, canvas.x - x, 1, this.context.colors.background);
+        x = Math.max(x, canvas.endX);
+      }
+      if (right > x) buffer.fillRect(x, y, right - x, 1, this.context.colors.background);
+    }
+  };
   addText(id, parent = this.body) {
     const text = new TextRenderable4(this.context.renderer, { id, content: "", width: "100%", wrapMode: "word", flexShrink: 0, fg: this.context.colors.foreground, selectable: true });
     parent.add(text);
@@ -2762,6 +2811,13 @@ var NativeModalView = class {
       this.refreshMask();
       this.refreshOptions(patch.selectedIndex);
       this.blocks?.replace(spec.blocks ?? []);
+      const transparentModel = spec.kind === "document" && Boolean(spec.blocks?.some((block) => block.kind === "model3d"));
+      if (transparentModel !== this.transparentModel) {
+        for (const box of [this.body, this.body.wrapper, this.body.viewport, this.body.content, this.blocks?.parent])
+          if (box instanceof BoxRenderable5) box.shouldFill = !transparentModel;
+        this.frame.chrome.shouldFill = !transparentModel;
+        this.transparentModel = transparentModel;
+      }
       if (this.progress) {
         this.progress.visible = spec.progress !== null;
         this.progress.content = nativeProgressText(spec.progress ?? void 0, true);
@@ -3120,6 +3176,14 @@ var NativeModalStack = class {
   restoreFocus;
   views = [];
   byId = /* @__PURE__ */ new Map();
+  pendingMedia = /* @__PURE__ */ new Set();
+  trackMedia(promises) {
+    for (const promise of promises) {
+      if (this.pendingMedia.has(promise)) continue;
+      this.pendingMedia.add(promise);
+      void promise.then(() => this.pendingMedia.delete(promise), () => this.pendingMedia.delete(promise));
+    }
+  }
   dimUnderlay = (buffer) => {
     const panel = this.active?.panel;
     if (!panel || panel.isDestroyed || !panel.visible) return;
@@ -3154,7 +3218,7 @@ var NativeModalStack = class {
   close(id, result, notify = false) {
     const view = this.byId.get(id);
     if (!view) return;
-    view.pauseMedia();
+    this.trackMedia(view.pauseMedia());
     view.frame.close(() => {
       const wasActive = view === this.active;
       view.destroy();
@@ -3176,11 +3240,17 @@ var NativeModalStack = class {
     for (const view of this.views) view.reconcileMedia(view === this.active);
   }
   pauseMedia() {
-    return this.views.flatMap((view) => view.pauseMedia());
+    return [...this.pendingMedia, ...this.views.flatMap((view) => view.pauseMedia())];
+  }
+  async settleMedia() {
+    while (this.pendingMedia.size) await Promise.allSettled([...this.pendingMedia]);
   }
   destroy() {
     this.context.renderer.removePostProcessFn(this.dimUnderlay);
-    for (const view of this.views) view.destroy();
+    for (const view of this.views) {
+      this.trackMedia(view.pauseMedia());
+      view.destroy();
+    }
     this.views = [];
     this.byId.clear();
   }
@@ -9202,6 +9272,7 @@ var NativeFrontend = class {
     this.content.destroy();
     this.tasks.destroy();
     await Promise.allSettled(mediaClosed);
+    await this.modals.settleMedia();
     this.root.destroyRecursively();
     this.context.syntax.destroy();
     await this.clipboard.dispose();