@floless/app 0.19.0 → 0.21.0

package/dist/floless-server.cjs

@@ -50958,6 +50958,17 @@ function appProvider(id) {
     return "other";
   }
 }
+function appBaked(id) {
+  try {
+    const dir = appDir(id);
+    const sourcePath = firstWithExt(dir, ".app") ?? firstWithExt(dir, ".flo");
+    if (!sourcePath) return false;
+    const src = asRecord((0, import_yaml.parse)((0, import_node_fs3.readFileSync)(sourcePath, "utf8")));
+    return src["exposes-as-agent"] === true;
+  } catch {
+    return false;
+  }
+}
 function readApp(id) {
   const dir = appDir(id);
   const sourcePath = firstWithExt(dir, ".app") ?? firstWithExt(dir, ".flo");
@@ -51933,6 +51944,41 @@ var aware = {
     if (code !== 0) throw new AwareError(`aware app uninstall failed (exit ${code})`, { stdout, stderr });
     return { output: stdout.trim() };
   },
+  /**
+   * Rename an installed app in place (`aware app rename <old> <new>`, CLI ≥ 0.68).
+   * AWARE owns the whole move — the app dir, the source `app:` field, the
+   * regenerated lock (so the Run gate stays green, no drift), and the synthesized
+   * agent of a baked (`exposes-as-agent`) app. `compiled` reflects whether AWARE
+   * refreshed the lock (false → the app needs a manual Compile). Throws
+   * AwareUnsupportedError on a pre-0.68 CLI so app-lifecycle can say "update AWARE"
+   * instead of treating an old CLI as a hard fault.
+   */
+  async rename(oldId, newId) {
+    const { code, stdout, stderr } = await runRaw(["app", "rename", assertId(oldId), assertId(newId)]);
+    if (code !== 0) {
+      if (isInvokeUnsupported({ stdout, stderr })) {
+        throw new AwareUnsupportedError("aware CLI does not support `app rename` (needs \u2265 0.68) \u2014 update AWARE", { stdout, stderr });
+      }
+      throw new AwareError(`aware app rename ${oldId} \u2192 ${newId} failed (exit ${code})`, { stdout, stderr, code });
+    }
+    return { compiled: /lock refreshed/i.test(stdout), output: stdout.trim() };
+  },
+  /**
+   * Duplicate an installed app into an independent copy (`aware app duplicate
+   * <src> <new>`, CLI ≥ 0.68). The original is untouched; a baked copy gets its
+   * own synthesized agent. Same `compiled` + unsupported-degradation contract as
+   * rename.
+   */
+  async duplicate(srcId, newId) {
+    const { code, stdout, stderr } = await runRaw(["app", "duplicate", assertId(srcId), assertId(newId)]);
+    if (code !== 0) {
+      if (isInvokeUnsupported({ stdout, stderr })) {
+        throw new AwareUnsupportedError("aware CLI does not support `app duplicate` (needs \u2265 0.68) \u2014 update AWARE", { stdout, stderr });
+      }
+      throw new AwareError(`aware app duplicate ${srcId} \u2192 ${newId} failed (exit ${code})`, { stdout, stderr, code });
+    }
+    return { compiled: /lock refreshed/i.test(stdout), output: stdout.trim() };
+  },
   /**
    * Install a first-party agent by registry id (`aware agent install <id>`). The
    * registry install pulls a large tarball (~200s observed) — far over runRaw's 60s
@@ -52683,7 +52729,7 @@ function appVersion() {
   return resolveVersion({
     isSea: isSea2(),
     sqVersionXml: readSqVersionXml(),
-    define: true ? "0.19.0" : void 0,
+    define: true ? "0.21.0" : void 0,
     pkgVersion: readPkgVersion()
   });
 }
@@ -52693,7 +52739,7 @@ function resolveChannel(s) {
   return "dev";
 }
 function appChannel() {
-  return resolveChannel({ isSea: isSea2(), define: true ? "0.19.0" : void 0 });
+  return resolveChannel({ isSea: isSea2(), define: true ? "0.21.0" : void 0 });
 }
 
 // oauth-presets.ts
@@ -54104,49 +54150,15 @@ function appDirPath(id) {
 function appInstalled(id) {
   return APP_ID3.test(id) && (0, import_node_fs16.existsSync)(appDirPath(id));
 }
-function findSource(dir) {
-  const files = (0, import_node_fs16.readdirSync)(dir);
-  const hit = files.find((f) => f.toLowerCase().endsWith(".app")) ?? files.find((f) => f.toLowerCase().endsWith(".flo"));
-  return hit ? (0, import_node_path14.join)(dir, hit) : null;
-}
-function rewriteAppId(text, newId) {
-  const re = /^(app:[ \t]*)(["']?)([^"'#\r\n]+?)\2([ \t]*(?:#[^\r\n]*)?)$/m;
-  if (!re.test(text)) throw new AppLifecycleError("source has no top-level app: field", 422);
-  return text.replace(re, (_m, pre, quote, _id, trail) => `${pre}${quote}${newId}${quote}${trail}`);
-}
-function isExposedAsAgent(dir) {
-  const src = findSource(dir);
-  return src ? /^exposes-as-agent:[ \t]*true\b/m.test((0, import_node_fs16.readFileSync)(src, "utf8")) : false;
-}
 function logCascade(what, e) {
   console.error(`[app-lifecycle] cascade step failed (${what}):`, e instanceof Error ? e.message : e);
 }
-function removeLocks(dir) {
-  for (const f of (0, import_node_fs16.readdirSync)(dir)) {
-    const lower = f.toLowerCase();
-    if (lower.endsWith(".lock") || lower === "lockfile.yaml") {
-      try {
-        (0, import_node_fs16.unlinkSync)((0, import_node_path14.join)(dir, f));
-      } catch {
-      }
-    }
-  }
-}
-function restampSource(dir, newId) {
-  const src = findSource(dir);
-  if (!src) throw new AppLifecycleError("app has no source file", 422);
-  const text = rewriteAppId((0, import_node_fs16.readFileSync)(src, "utf8"), newId);
-  const ext = src.toLowerCase().endsWith(".flo") ? ".flo" : ".app";
-  const newSrc = (0, import_node_path14.join)(dir, `${newId}${ext}`);
-  (0, import_node_fs16.writeFileSync)(newSrc, text);
-  if (src !== newSrc) {
-    try {
-      (0, import_node_fs16.unlinkSync)(src);
-    } catch {
-    }
-  }
-  removeLocks(dir);
-  return newSrc;
+function mapAwareError(e) {
+  const code = e instanceof AwareError ? e.detail?.code : void 0;
+  if (code === 8) throw new AppLifecycleError("a workflow with that name already exists", 409);
+  if (code === 7) throw new AppLifecycleError("workflow not found", 404);
+  if (code === 3) throw new AppLifecycleError(e instanceof Error ? e.message : "invalid name", 400);
+  throw e;
 }
 function assertNewId(newId) {
   if (!newId || !APP_ID3.test(newId) || !safeSegment(newId)) {
@@ -54154,39 +54166,16 @@ function assertNewId(newId) {
   }
 }
 var defaultDeps2 = {
-  compile: (p) => aware.compile(p),
+  rename: (oldId, newId) => aware.rename(oldId, newId),
+  duplicate: (srcId, newId) => aware.duplicate(srcId, newId),
   uninstall: (id) => aware.uninstall(id)
 };
-async function tryCompile(deps, sourcePath) {
-  try {
-    await deps.compile(sourcePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
 async function renameApp(oldId, newId, deps = defaultDeps2) {
   if (!appInstalled(oldId)) throw new AppLifecycleError(`workflow not found: ${oldId}`, 404);
   assertNewId(newId);
   if (newId === oldId) throw new AppLifecycleError("that is already its name", 400);
   if (appInstalled(newId)) throw new AppLifecycleError(`a workflow named "${newId}" already exists`, 409);
-  if (isExposedAsAgent(appDirPath(oldId))) {
-    throw new AppLifecycleError("this workflow is baked into an agent \u2014 rename isn\u2019t supported yet (the agent wouldn\u2019t follow). Un-bake it first, or rename it from the terminal.", 409);
-  }
-  const oldDir = appDirPath(oldId);
-  const newDir = appDirPath(newId);
-  (0, import_node_fs16.renameSync)(oldDir, newDir);
-  let newSrc;
-  try {
-    newSrc = restampSource(newDir, newId);
-  } catch (e) {
-    try {
-      (0, import_node_fs16.renameSync)(newDir, oldDir);
-    } catch {
-    }
-    throw e;
-  }
-  const compiled = await tryCompile(deps, newSrc);
+  const { compiled } = await deps.rename(oldId, newId).catch(mapAwareError);
   try {
     renameVisualInputs(oldId, newId);
   } catch (e) {
@@ -54203,27 +54192,7 @@ async function duplicateApp(srcId, newId, deps = defaultDeps2) {
   if (!appInstalled(srcId)) throw new AppLifecycleError(`workflow not found: ${srcId}`, 404);
   assertNewId(newId);
   if (appInstalled(newId)) throw new AppLifecycleError(`a workflow named "${newId}" already exists`, 409);
-  if (isExposedAsAgent(appDirPath(srcId))) {
-    throw new AppLifecycleError("this workflow is baked into an agent \u2014 duplicate isn\u2019t supported yet (the copy\u2019s agent wouldn\u2019t be installed). Un-bake it first, or copy it from the terminal.", 409);
-  }
-  const newDir = appDirPath(newId);
-  try {
-    (0, import_node_fs16.mkdirSync)(newDir);
-  } catch {
-    throw new AppLifecycleError(`a workflow named "${newId}" already exists`, 409);
-  }
-  let newSrc;
-  try {
-    (0, import_node_fs16.cpSync)(appDirPath(srcId), newDir, { recursive: true });
-    newSrc = restampSource(newDir, newId);
-  } catch (e) {
-    try {
-      (0, import_node_fs16.rmSync)(newDir, { recursive: true, force: true });
-    } catch {
-    }
-    throw e;
-  }
-  const compiled = await tryCompile(deps, newSrc);
+  const { compiled } = await deps.duplicate(srcId, newId).catch(mapAwareError);
   try {
     copyVisualInputs(srcId, newId);
   } catch (e) {
@@ -54233,7 +54202,7 @@ async function duplicateApp(srcId, newId, deps = defaultDeps2) {
 }
 async function deleteApp(id, deps = defaultDeps2) {
   if (!appInstalled(id)) throw new AppLifecycleError(`workflow not found: ${id}`, 404);
-  await deps.uninstall(id);
+  await deps.uninstall(id).catch(mapAwareError);
   try {
     deleteVisualInputs(id);
   } catch (e) {
@@ -57273,7 +57242,7 @@ async function startServer() {
     }
   });
   await app.register(import_static.default, { root: WEB_ROOT, prefix: "/" });
-  const MIN_AWARE = "0.51.0";
+  const MIN_AWARE = "0.68.0";
   const isWin3 = process.platform === "win32";
   const has = (cmd) => {
     try {
@@ -57499,7 +57468,7 @@ async function startServer() {
   onSeatLost((reason) => broadcast({ type: "seat-taken", reason }));
   app.get("/api/apps", async () => {
     const apps = await aware.list();
-    return { ok: true, apps: apps.map((a) => ({ ...a, provider: appProvider(a.id) })) };
+    return { ok: true, apps: apps.map((a) => ({ ...a, provider: appProvider(a.id), baked: appBaked(a.id) })) };
   });
   app.get("/api/agents", async () => {
     const agents = await aware.agentList();
@@ -57810,7 +57779,16 @@ async function startServer() {
       broadcast({ type: "run-started", id, dryRun: !!dryRun, simulate: !!simulate, runId: result.runId });
       for (const ev of events) broadcast({ type: "trace", id, event: ev });
       broadcast({ type: "run-ended", id, runId: result.runId });
-      const report = withBadge(extractReportHtml(events));
+      const extracted = extractReportHtml(events);
+      let report = null;
+      if (extracted) {
+        let interactive = false;
+        try {
+          interactive = readApp(id).nodes.find((n) => n.id === extracted.nodeId)?.agent === "viewer-3d";
+        } catch {
+        }
+        report = { ...interactive ? extracted : withBadge(extracted), interactive };
+      }
       const credentialIssue = !simulate && hasAuthFailure(events) ? await detectCredentialIssue(id) : null;
       return { ok: true, runId: result.runId, tracePath: result.tracePath, events, report, credentialIssue };
     }

package/dist/web/app.css

@@ -2209,7 +2209,9 @@ body {
 .report-actions button.report-stop:hover { background: color-mix(in srgb, var(--warn) 16%, transparent); border-color: var(--warn); color: var(--text); }
 #report-close { font-size: 18px; line-height: 1; padding: 4px 10px; }
 .report-stage { position: relative; flex: 1; background: #0f172a; }
-#report-frame { width: 100%; height: 100%; border: 0; display: block; background: #0f172a; }
+/* Only the SHOWN frame fills the stage — `:not([hidden])` so `display:block` never defeats the
+   `hidden` attribute on the inactive frame (else it keeps its height and pushes the other off-screen). */
+#report-frame:not([hidden]), #report-frame-3d:not([hidden]) { width: 100%; height: 100%; border: 0; display: block; background: #0f172a; }
 
 /* Live "On trigger" report: a pulsing pip in the viewer subtitle + a brief edge
    flash on the stage when a trigger routine (e.g. tekla-selection-report) pushes a

package/dist/web/aware.js

@@ -18,6 +18,7 @@
   const $notesStrip = document.getElementById('notes-strip');
   const $reportModal = document.getElementById('report-modal');
   const $reportFrame = document.getElementById('report-frame');
+  const $reportFrame3d = document.getElementById('report-frame-3d');
   const $reportOverlay = document.getElementById('report-overlay');
   const $reportTitle = document.getElementById('report-title');
   const $reportSub = document.getElementById('report-sub');
@@ -582,7 +583,7 @@
         // <button>s without nesting interactive elements (#85). Selection stays driven by
         // the delegated $wfList click + comboMove highlight (aria-activedescendant).
         const aid = escapeAttr(a.id);
-        html += `<div class="wf-option" role="option" id="wf-opt-${aid}" data-id="${aid}" data-search="${escapeAttr((a.id + ' ' + p).toLowerCase())}" tabindex="-1" aria-selected="false">`
+        html += `<div class="wf-option" role="option" id="wf-opt-${aid}" data-id="${aid}" data-baked="${a.baked ? '1' : ''}" data-search="${escapeAttr((a.id + ' ' + p).toLowerCase())}" tabindex="-1" aria-selected="false">`
           + `<span class="wf-option-name">${escapeHtml(a.id)}</span><span class="wf-option-meta">${meta}</span>`
           + `<span class="wf-option-actions">`
           + `<button type="button" class="wf-act act-edit" data-wf-act="rename" data-id="${aid}" tabindex="-1" data-tip="Rename" aria-label="Rename ${aid}">✎</button>`
@@ -708,7 +709,7 @@
       const act = e.target.closest('[data-wf-act]');
       if (act) {
         const id = act.dataset.id;
-        if (act.dataset.wfAct === 'rename') openRenameWorkflow(id);
+        if (act.dataset.wfAct === 'rename') openRenameWorkflow(id, act.closest('.wf-option')?.dataset.baked === '1');
         else if (act.dataset.wfAct === 'duplicate') openDuplicateWorkflow(id);
         else if (act.dataset.wfAct === 'delete') confirmDeleteWorkflow(id);
         return;
@@ -737,11 +738,17 @@
     appInputValues.delete(id); dirtyBaseline.delete(id); apps.delete(id);
   }
 
-  async function openRenameWorkflow(oldId) {
+  async function openRenameWorkflow(oldId, baked = false) {
     closeCombo(false);
+    // A baked workflow is a reusable agent; renaming it also renames that agent, so any
+    // OTHER workflow that uses it as a node will reference the old name and need updating.
+    // Warn (informed consent) — not a blocker; the user may be renaming an unreferenced
+    // one (#226 UX review).
+    const sub = 'This is the name you pick here, and what .flo files and your terminal AI use to refer to it.'
+      + (baked ? ' Renaming a baked workflow also renames its synthesized agent — other workflows that use it as a node will need updating.' : '');
     const res = await formModal({
       title: 'Rename workflow',
-      sub: 'This is the name you pick here, and what .flo files and your terminal AI use to refer to it.',
+      sub,
       fields: [{ name: 'name', label: 'New name', type: 'text', value: oldId, placeholder: 'e.g. tekla-bom-by-phase' }],
       okLabel: 'Rename',
     });
@@ -838,10 +845,10 @@
   function reportNodeId() {
     const app = currentId && apps.get(currentId);
     if (!app || !app.nodes.length) return null;
-    // An html-report agent node renders report HTML — its `render` command returns
-    // an `html` field, which is exactly what extractReportHtml keys on. So it's a
-    // report producer regardless of exec code; prefer it directly as the viewer node.
-    const htmlReportNode = app.nodes.find((n) => n.agent === 'html-report');
+    // An html-report (static) or viewer-3d (interactive 3D) agent node renders HTML — its
+    // `render` command returns an `html` field, exactly what extractReportHtml keys on. So
+    // it's a report producer regardless of exec code; prefer it directly as the viewer node.
+    const htmlReportNode = app.nodes.find((n) => n.agent === 'html-report' || n.agent === 'viewer-3d');
     if (htmlReportNode) return htmlReportNode.id;
     // Otherwise, qualify the app only if some node actually PRODUCES report HTML — its exec
     // code returns an `html` field (the `data.result.html` extractReportHtml keys
@@ -953,7 +960,11 @@
       // clear anything we injected last render, so re-renders never stack
       card.querySelectorAll('.node-action, .node-inputs').forEach((b) => b.remove());
       if (isInput) addNodeInputs(card); // current values, above the button
-      if (isReport) addNodeAction(card, 'View report ▸', () => showReport(id));
+      if (isReport) {
+        const rNode = app && app.nodes.find((n) => n.id === rid);
+        const viewLabel = rNode && rNode.agent === 'viewer-3d' ? 'View 3D ▸' : 'View report ▸';
+        addNodeAction(card, viewLabel, () => showReport(id));
+      }
       if (isInput) addNodeAction(card, 'Set inputs ▸', () => openInputsDialog());
       if (isRebake) addNodeAction(card, 'Re-read & re-bake ▸', () => openRebakeDialog());
     });
@@ -1245,7 +1256,37 @@
 
   // Share is visible exactly when the frame holds a report (the empty state HIDES it —
   // never a disabled affordance with no path forward).
-  function paintReport(html) { $reportFrame.srcdoc = html; $reportOverlay.hidden = true; $reportOverlay.replaceChildren(); $reportShare.hidden = false; }
+  // The last HTML painted (static or 3D) — so ↗ Open works for both surfaces.
+  let lastPaintedHtml = '';
+  // Paint a report into the viewer. A STATIC report uses the scriptless srcdoc frame; an
+  // INTERACTIVE 3D doc (viewer-3d) uses the script-enabled frame via a data: URL (opaque
+  // origin, cannot touch the app page) and keeps a "Loading 3D view…" overlay until the doc
+  // posts `viewer-ready`. Exactly one frame is shown at a time.
+  function paintReport(html, interactive) {
+    lastPaintedHtml = html || '';
+    if (interactive) {
+      $reportFrame.hidden = true; $reportFrame.srcdoc = '';
+      $reportFrame3d.hidden = false;
+      $reportFrame3d.src = 'data:text/html;charset=utf-8,' + encodeURIComponent(html);
+      $reportShare.hidden = true; // a script doc can't be statically hosted — hide, don't disable
+      $reportOverlay.hidden = false; $reportOverlay.replaceChildren();
+      $reportOverlay.append(mkEl('div', 'spinner'), mkEl('div', null, 'Loading 3D view…'));
+    } else {
+      $reportFrame3d.hidden = true; $reportFrame3d.removeAttribute('src');
+      $reportFrame.hidden = false; $reportFrame.srcdoc = html;
+      $reportOverlay.hidden = true; $reportOverlay.replaceChildren();
+      $reportShare.hidden = false;
+    }
+  }
+
+  // Reset the viewer to "no report shown": clear BOTH frames + the Open buffer, so a stale
+  // interactive 3D doc can't linger (its WebGL loop running) behind an overlay, and ↗ Open
+  // can't reopen a previous app's report. Used by every empty / transition state.
+  function clearReportFrames() {
+    $reportFrame.srcdoc = ''; $reportFrame.hidden = false;
+    $reportFrame3d.hidden = true; $reportFrame3d.removeAttribute('src');
+    lastPaintedHtml = '';
+  }
 
   // Double-click the HTML Viewer node → LOAD the last report (no run; running is
   // the header "▶ Run workflow" button's job). Shows a prompt if nothing has run yet.
@@ -1258,10 +1299,16 @@
     if (reportRunning) return; // a run is in flight — its overlay already shows progress
     const cached = lastReportByApp.get(currentId);
     if (cached && cached.html) {
-      $reportSub.innerHTML = `Last report${cached.label ? ' · ' + escapeHtml(cached.label) : ''} — rendered from the run's output, never composed by the UI.`;
-      paintReport(cached.html);
+      const sfx = cached.label ? ' · ' + cached.label : '';
+      if (cached.interactive) {
+        $reportTitle.textContent = `3D Viewer · ${app.displayName}`;
+        $reportSub.textContent = `Last 3D view${sfx} — drag to orbit, scroll to zoom, click an element to inspect.`;
+      } else {
+        $reportSub.textContent = `Last report${sfx} — rendered from the run's output, never composed by the UI.`;
+      }
+      paintReport(cached.html, cached.interactive);
     } else {
-      $reportFrame.srcdoc = '';
+      clearReportFrames();
       $reportShare.hidden = true; // nothing to share — hide, don't disable
       $reportOverlay.hidden = false;
       $reportOverlay.innerHTML = `<div>No report yet. Click <strong>▶ Run workflow</strong> (top right) to run it against the live model, then double-click to view it any time.</div>`;
@@ -1286,7 +1333,7 @@
     const inputBadge = Object.entries(inputs).map(([k, v]) => `${k}=${v}`).join(' · ');
     $reportTitle.textContent = `HTML Viewer · ${app.displayName}`;
     $reportSub.innerHTML = `Live run of <code>${escapeHtml(nodeId)}</code>${inputBadge ? ' · ' + escapeHtml(inputBadge) : ''} — rendered from the node's output, never composed by the UI.`;
-    $reportFrame.srcdoc = ''; // clear any previously rendered report while this run is in flight
+    clearReportFrames(); // clear any previous report (static or 3D) before this run paints a fresh one
     $reportShare.hidden = true; // the frame is blank — only a painted report is shareable
     $reportOverlay.hidden = false;
     $reportOverlay.innerHTML = opts.debug
@@ -1307,14 +1354,19 @@
       // body, not real data) — prompt reconnect instead of rendering the noise.
       if (res.credentialIssue) { surfaceCredentialIssue(res.credentialIssue); return; }
       const html = res.report && res.report.html;
+      const interactive = !!(res.report && res.report.interactive);
       if (!html) {
         $reportOverlay.innerHTML = `<div>Run completed but <code>${escapeHtml(nodeId)}</code> returned no <code>html</code>. Check the Execution tab.</div>`;
         return;
       }
-      paintReport(html);
-      lastReportByApp.set(currentId, { nodeId, label: inputBadge, html });
+      if (interactive) {
+        $reportTitle.textContent = `3D Viewer · ${app.displayName}`;
+        $reportSub.innerHTML = `Live 3D view from <code>${escapeHtml(nodeId)}</code>${inputBadge ? ' · ' + escapeHtml(inputBadge) : ''} — drag to orbit, scroll to zoom, click an element to inspect.`;
+      }
+      paintReport(html, interactive);
+      lastReportByApp.set(currentId, { nodeId, label: inputBadge, html, interactive });
       $reportModal.dataset.html = '1';
-      appendNarration(`Rendered the report from <strong>${escapeHtml(nodeId)}</strong>${inputBadge ? ' (' + escapeHtml(inputBadge) + ')' : ''} — live run against the model.`);
+      appendNarration(`Rendered the ${interactive ? '3D view' : 'report'} from <strong>${escapeHtml(nodeId)}</strong>${inputBadge ? ' (' + escapeHtml(inputBadge) + ')' : ''} — live run against the model.`);
     } catch (e) {
       const msg = e && e.message ? e.message : String(e);
       if (cancelRequested) {
@@ -1362,7 +1414,7 @@
   const CRED_BODY_IDLE = 'Sign in again and then run the workflow — it takes about 30 seconds.';
 
   function showCredentialReconnect(cred) {
-    $reportFrame.srcdoc = '';
+    clearReportFrames();
     $reportShare.hidden = true;
     $reportOverlay.hidden = false;
     $reportOverlay.replaceChildren();
@@ -1674,10 +1726,22 @@
   // The Stop button is rebuilt into the overlay each run — delegate so one
   // listener survives every innerHTML swap.
   $reportOverlay.addEventListener('click', (e) => { if (e.target.closest('.overlay-stop')) stopRun(); });
+  // The interactive 3D doc (viewer-3d) posts a load handshake from its opaque-origin frame:
+  // `viewer-ready` clears the loading overlay; `viewer-error` (CDN/script/timeout) shows a
+  // retry. Guard: only when the 3D frame is the active surface and the message is from it.
+  window.addEventListener('message', (e) => {
+    if ($reportFrame3d.hidden || e.source !== $reportFrame3d.contentWindow) return;
+    const t = e.data && e.data.type;
+    if (t === 'viewer-ready') { $reportOverlay.hidden = true; $reportOverlay.replaceChildren(); }
+    else if (t === 'viewer-error') {
+      $reportOverlay.hidden = false; $reportOverlay.replaceChildren();
+      $reportOverlay.append(mkEl('div', null, '3D view failed to load — check your connection, then click ▶ Run workflow to try again.'));
+    }
+  });
   // The header ■ Stop run — the always-reachable twin of the overlay Stop (#39).
   if ($stopRunBtn) $stopRunBtn.onclick = () => stopRun();
   $reportOpen.onclick = () => {
-    const html = $reportFrame.srcdoc;
+    const html = lastPaintedHtml || $reportFrame.srcdoc;
     if (!html) return;
     // Open via a blob: URL — an opaque origin, so the report can't script the
     // app origin (mirrors the iframe's sandbox intent).
@@ -4033,7 +4097,7 @@
     $reportModal.dataset.nodeId = reportNodeId() || '';
     const cached = lastReportByApp.get(id);
     if (cached && cached.html) paintReport(cached.html);
-    else { $reportFrame.srcdoc = ''; $reportShare.hidden = true; }
+    else { clearReportFrames(); $reportShare.hidden = true; }
     $reportOverlay.hidden = false;
     $reportOverlay.replaceChildren();
     $reportOverlay.append(mkEl('div', 'spinner'), mkEl('div', null, 'Starting live session…'));
@@ -4118,7 +4182,7 @@
       $reportShare.hidden = false; // the cached report is the primary content
       $reportSub.innerHTML = `<span class="live-pip" aria-hidden="true"></span>Live · waiting for the next change — change your selection in Tekla to refresh the report.`;
     } else {
-      $reportFrame.srcdoc = '';
+      clearReportFrames();
       $reportShare.hidden = true;
       $reportOverlay.hidden = false;
       $reportOverlay.replaceChildren();
@@ -4146,7 +4210,7 @@
         ? `Run complete · last report above — click <strong>▶ Run workflow</strong> to run again.`
         : `Live session stopped · last report above — click <strong>▶ Run workflow</strong> to start again.`;
     } else {
-      $reportFrame.srcdoc = '';
+      clearReportFrames();
       $reportShare.hidden = true;
       $reportOverlay.hidden = false;
       $reportOverlay.replaceChildren();

package/dist/web/index.html

@@ -319,6 +319,13 @@
              Scripts stay BLOCKED (no allow-scripts), so even though the report is now
              same-origin it has no JS to touch the app page — static reports only. -->
         <iframe id="report-frame" sandbox="allow-same-origin allow-popups allow-popups-to-escape-sandbox" title="Report"></iframe>
+        <!-- Interactive output (the viewer-3d agent) needs scripts, so it cannot use the
+             scriptless static frame above. Loaded via a `data:text/html` URL → an opaque
+             origin (cannot reach the app page, cookies, or same-origin APIs). Minimal
+             sandbox: `allow-scripts` ONLY — the 3D doc has no links/popups of its own
+             (↗ Open is a parent-side action), and NO allow-same-origin. Shown only for
+             interactive reports; the static frame is used otherwise. -->
+        <iframe id="report-frame-3d" sandbox="allow-scripts" title="3D view" hidden></iframe>
         <div class="report-overlay" id="report-overlay" hidden></div>
       </div>
     </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floless/app",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "type": "module",
   "description": "Thin localhost host for floless.app — serves web/ and shells the aware CLI. No engine, no LLM.",
   "bin": {