feat(studio): render compiled TSX artifacts in a sandboxed pane

Implements Increment 1 of docs/specs/2026-08-20-harness-studio-artifact-view.md:
Studio can now show what a run produced instead of sending the reviewer out to
open files by hand. `--artifacts <dir>` indexes a directory behind opaque ids,
compiles `.tsx` and `.jsx` artifacts on request through esbuild-wasm
`transformSync`, and mounts them in an iframe sandboxed without
`allow-same-origin`, so artifact code runs on an opaque origin and cannot reach
the Studio shell. The opaque origin splits subresource loading: the host bundle
ships as a classic script while the compiled module needs CORS, including on the
failure response, or the compiler diagnostic is lost behind a generic fetch
error. Non-module kinds state that no renderer exists yet rather than rendering a
guess, and nothing compiles until the reader selects a row.

`esbuild-wasm` moves from devDependency to dependency because compilation now
happens at request time and the published files list is dist/ only.

Both artifact routes guard their own directory reads: the server dispatches with
`void route(...)`, so a directory removed after startup would otherwise reject
out of the handler and end the process. The served module's sourceMappingURL now
names a sibling route that answers with a real map.

Validated with 111 Studio tests, 13 Playwright tests with no console or page
errors and screenshots at wide, compact, and narrow widths, and 1412 root tests.

Co-authored-by: QoderAI (Qwen 3.8 Max) <qoder_ai@qoder.com>

Author: phodal

docs/specs/2026-08-20-harness-studio-artifact-view.md

@@ -47,6 +47,7 @@
     "@shikijs/engine-javascript": "^4.4.3",
     "@shikijs/langs": "^4.4.3",
     "@tanstack/react-virtual": "^3.14.9",
+    "esbuild-wasm": "0.28.1",
     "react": "19.2.8",
     "react-dom": "19.2.8"
   },
@@ -55,7 +56,6 @@
     "@types/node": "26.2.0",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.4",
-    "esbuild-wasm": "0.28.1",
     "typescript": "7.0.2",
     "vitest": "4.1.10"
   },

package-lock.json

@@ -25,8 +25,26 @@ await build({
   define: { "process.env.NODE_ENV": '"production"' },
   logLevel: "warning",
 });
+// The artifact host is a separate IIFE bundle, not a chunk of the shell: it runs
+// inside the sandboxed artifact iframe, which has an opaque origin and can load
+// a classic script without CORS but not a module script.
+await build({
+  entryPoints: { "artifact-host": join(packageRoot, "src", "app", "artifact-host.ts") },
+  outdir: join(appDir, "assets"),
+  entryNames: "[name]",
+  bundle: true,
+  format: "iife",
+  globalName: "harnessArtifactHost",
+  platform: "browser",
+  target: "es2022",
+  minify: true,
+  sourcemap: true,
+  define: { "process.env.NODE_ENV": '"production"' },
+  logLevel: "warning",
+});
 await Promise.all([
   copyFile(join(packageRoot, "src", "app", "index.html"), join(appDir, "index.html")),
+  copyFile(join(packageRoot, "src", "app", "artifact-host.html"), join(appDir, "artifact-host.html")),
   ...["tokens.css", "shell.css", "workbench.css"].map((file) =>
     copyFile(join(packageRoot, "src", "app", "styles", file), join(appDir, "assets", file)),
   ),

packages/harness-studio/package.json

@@ -5,6 +5,7 @@ import { Binoculars } from "@phosphor-icons/react/Binoculars";
 import { BugBeetle } from "@phosphor-icons/react/BugBeetle";
 import { Flask } from "@phosphor-icons/react/Flask";
 import { GitBranch } from "@phosphor-icons/react/GitBranch";
+import { Package } from "@phosphor-icons/react/Package";
 import { SidebarSimple } from "@phosphor-icons/react/SidebarSimple";
 import { SquaresFour } from "@phosphor-icons/react/SquaresFour";
 import { CompareView } from "./CompareView.js";
@@ -26,13 +27,15 @@ import {
 const NAV_ICONS: Record<StudioArea, Icon> = {
   overview: SquaresFour,
   inspector: Binoculars,
+  artifacts: Package,
   debugger: BugBeetle,
   compare: Flask,
 };
 
 const AREA_COPY: Record<StudioArea, { eyebrow: string; title: string }> = {
   overview: { eyebrow: "Control", title: "Harness Control Center" },
   inspector: { eyebrow: "Observe", title: "Inspector" },
+  artifacts: { eyebrow: "Observe", title: "Artifacts" },
   debugger: { eyebrow: "Run", title: "Debugger" },
   compare: { eyebrow: "Validate", title: "Compare" },
 };
@@ -48,6 +51,7 @@ interface StudioSourceOption {
 
 const EMPTY_CONFIG: StudioConfig = {
   aguiEnabled: false,
+  artifactsEnabled: false,
   evidenceEnabled: false,
   experimentEnabled: false,
   historyEnabled: false,
@@ -191,6 +195,7 @@ export function App(): React.JSX.Element {
       <div className={`studio-surface studio-surface-${area}`}>
         {area === "overview" && <Overview config={config} onOpen={openArea} />}
         {area === "inspector" && <InspectorWorkspace key={`inspector-${dataRevision}-${config.inspectorEnabled}`} config={config} />}
+        {area === "artifacts" && <ArtifactsWorkspace key={`artifacts-${dataRevision}-${config.artifactsEnabled}`} config={config} />}
         {area === "debugger" && <DebuggerWorkspace config={config} />}
         {area === "compare" && <CompareWorkspace key={`compare-${dataRevision}-${config.experimentEnabled}-${config.evidenceEnabled}`} config={config} surface={compareSurface} navigation={compareNavigation} />}
       </div>
@@ -315,6 +320,96 @@ function InspectorWorkspace(props: { config: StudioConfig }): React.JSX.Element
   return <EmptyWorkspace eyebrow="Observed delivery" title="Connect an Inspector report" detail="Inspector requires retained, privacy-filtered evidence. It never substitutes the recorded Session Debugger fixture for a real workspace." command="--inspector ./harness-inspector.html" />;
 }
 
+interface ArtifactDescriptor {
+  id: string;
+  kind: string;
+  label: string;
+  size: number;
+}
+
+/**
+ * Artifacts pane: a row list of run outputs plus a sandboxed preview.
+ *
+ * The preview frame withholds `allow-same-origin`, so artifact code runs on an
+ * opaque origin and cannot reach the Studio shell.
+ */
+function ArtifactsWorkspace(props: { config: StudioConfig }): React.JSX.Element {
+  const [artifacts, setArtifacts] = useState<ArtifactDescriptor[] | undefined>(undefined);
+  const [failure, setFailure] = useState<string | undefined>(undefined);
+  const [selected, setSelected] = useState<string | undefined>(undefined);
+
+  useEffect(() => {
+    if (!props.config.artifactsEnabled) return;
+    let cancelled = false;
+    void (async () => {
+      try {
+        const response = await fetch("api/artifacts");
+        if (!response.ok) throw new Error(`Artifact catalog failed (${response.status}).`);
+        const payload = await response.json() as { artifacts?: ArtifactDescriptor[] };
+        if (cancelled) return;
+        // Deliberately no auto-selection: compiling an artifact the reader has
+        // not asked for spends server work and can open the pane on an error.
+        setArtifacts(Array.isArray(payload.artifacts) ? payload.artifacts : []);
+      } catch (error) {
+        if (!cancelled) setFailure(error instanceof Error ? error.message : String(error));
+      }
+    })();
+    return () => { cancelled = true; };
+  }, [props.config.artifactsEnabled]);
+
+  if (!props.config.artifactsEnabled) {
+    return <EmptyWorkspace eyebrow="Run outputs" title="Load an artifact directory" detail="Artifacts renders what a run produced. It reads a directory read-only and never writes back to it." command="--artifacts ./artifacts" />;
+  }
+  if (failure !== undefined) {
+    return <EmptyWorkspace eyebrow="Run outputs" title="Cannot read the artifact catalog" detail={failure} command="--artifacts ./artifacts" />;
+  }
+  if (artifacts === undefined) {
+    return <p className="artifact-status" role="status">Loading artifacts…</p>;
+  }
+  if (artifacts.length === 0) {
+    return <EmptyWorkspace eyebrow="Run outputs" title="No artifacts in this directory" detail="The configured directory holds no files Studio can render yet. Artifact rows appear once a run writes into it." command="--artifacts ./artifacts" />;
+  }
+
+  const active = artifacts.find((entry) => entry.id === selected);
+  return <section className="artifact-workspace" aria-label="Artifacts workspace">
+    <div className="artifact-list-pane">
+      <header><div><small>Retained</small><h2>Artifacts</h2></div><span>{artifacts.length}</span></header>
+      <ul className="artifact-rows">
+        {artifacts.map((entry) => <li key={entry.id}>
+          <button
+            type="button"
+            className={entry.id === selected ? "selected" : undefined}
+            aria-current={entry.id === selected}
+            onClick={() => setSelected(entry.id)}
+          >
+            <span className="artifact-row-copy"><strong>{entry.label}</strong><small>{entry.kind} · {formatBytes(entry.size)}</small></span>
+          </button>
+        </li>)}
+      </ul>
+    </div>
+    <div className="artifact-preview-pane">
+      {active === undefined
+        ? <p className="artifact-status" role="status">Select an artifact to preview it.</p>
+        : active.kind === "module"
+          ? <iframe
+            key={active.id}
+            className="artifact-frame"
+            title={`Artifact preview: ${active.label}`}
+            src={`artifact-host.html?module=api/artifacts/${active.id}/module.js`}
+            sandbox="allow-scripts"
+            referrerPolicy="no-referrer"
+          />
+          : <p className="artifact-status" role="status">No renderer for <code>{active.kind}</code> yet. Only compiled modules render in this increment.</p>}
+    </div>
+  </section>;
+}
+
+function formatBytes(size: number): string {
+  if (size < 1024) return `${size} B`;
+  if (size < 1024 * 1024) return `${Math.round(size / 1024)} KB`;
+  return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+}
+
 function DebuggerWorkspace(props: { config: StudioConfig }): React.JSX.Element {
   if (!props.config.aguiEnabled) {
     return <EmptyWorkspace eyebrow="Live runs" title="Load a harness for live runs" detail="The Debugger drives a live harness run over the embedded AG-UI endpoint and saves finished runs for replay." command="--harness ./my-agent.harness" />;

packages/harness-studio/scripts/build-app.mjs

@@ -0,0 +1,50 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Harness Studio Artifact</title>
+    <link rel="stylesheet" href="./assets/tokens.css" />
+    <style>
+      html,
+      body {
+        margin: 0;
+        min-height: 100%;
+        background: var(--color-surface, #ffffff);
+        color: var(--color-text, #263244);
+        font: 13px/1.5 var(--font-ui, system-ui, sans-serif);
+      }
+      #artifact-root {
+        box-sizing: border-box;
+        min-height: 100vh;
+        padding: 12px;
+      }
+      .artifact-failure {
+        display: flex;
+        flex-direction: column;
+        gap: 8px;
+        padding: 12px;
+        border: 1px solid var(--color-danger, #a63d45);
+        border-radius: var(--radius-md, 4px);
+        background: var(--color-danger-surface, #fdebed);
+        color: var(--color-text, #263244);
+      }
+      .artifact-failure pre {
+        margin: 0;
+        overflow-x: auto;
+        font: 12px/1.5 var(--font-code, ui-monospace, monospace);
+        white-space: pre-wrap;
+        word-break: break-word;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="artifact-root"></div>
+    <!-- Classic script: the sandbox gives this document an opaque origin, where a
+         module script would require CORS but a classic script does not. -->
+    <script src="./assets/artifact-host.js"></script>
+    <script>
+      harnessArtifactHost.mount(new URLSearchParams(location.search).get("module"));
+    </script>
+  </body>
+</html>

packages/harness-studio/src/app/App.tsx

@@ -0,0 +1,127 @@
+import { Component, createElement, type ErrorInfo, type ReactNode } from "react";
+import * as React from "react";
+import { createRoot } from "react-dom/client";
+
+/**
+ * Artifact host runtime.
+ *
+ * This bundle runs inside the sandboxed artifact iframe, never in the Studio
+ * shell. It is built as an IIFE and loaded with a classic `<script>` tag: the
+ * iframe carries `sandbox="allow-scripts"` without `allow-same-origin`, so it
+ * has an opaque origin, and classic scripts load from an opaque origin without
+ * CORS while module scripts would not.
+ *
+ * The compiled artifact module is lowered to `React.createElement` and relies on
+ * the `React` global installed here, so one React instance is shared with the
+ * host and the artifact needs no import map.
+ */
+
+interface BoundaryProps {
+  children: ReactNode;
+}
+
+interface BoundaryState {
+  message: string | undefined;
+}
+
+class ArtifactErrorBoundary extends Component<BoundaryProps, BoundaryState> {
+  override state: BoundaryState = { message: undefined };
+
+  static getDerivedStateFromError(error: unknown): BoundaryState {
+    return { message: error instanceof Error ? error.message : String(error) };
+  }
+
+  override componentDidCatch(error: unknown, info: ErrorInfo): void {
+    // Keep the failure observable for browser verification without letting a
+    // throwing artifact take the frame down silently.
+    console.error("[artifact] render failed", error, info.componentStack);
+  }
+
+  override render(): ReactNode {
+    const { message } = this.state;
+    if (message === undefined) return this.props.children;
+    return failureElement("This artifact failed while rendering.", message);
+  }
+}
+
+function failureElement(headline: string, detail: string): ReactNode {
+  return createElement(
+    "div",
+    { className: "artifact-failure", role: "alert" },
+    createElement("strong", null, headline),
+    createElement("pre", null, detail),
+  );
+}
+
+/**
+ * Only same-origin artifact module paths are accepted. Without this the host
+ * would import whatever URL a query string names.
+ */
+export function resolveModuleUrl(raw: string | null): string {
+  const candidate = (raw ?? "").trim();
+  if (candidate === "") throw new Error("No artifact module was requested.");
+  if (!/^\/?api\/artifacts\/[A-Za-z0-9_-]+\/module\.js$/u.test(candidate)) {
+    throw new Error(`Refusing to load an artifact module from '${candidate}'.`);
+  }
+  return new URL(candidate, document.baseURI).href;
+}
+
+export async function mount(rawModule: string | null): Promise<void> {
+  const root = document.getElementById("artifact-root");
+  if (!(root instanceof HTMLElement)) {
+    console.error("[artifact] host root element is missing");
+    return;
+  }
+
+  // The compiled artifact calls `React.createElement`, so the namespace has to
+  // land on the global before the module is imported.
+  (globalThis as unknown as { React: unknown }).React = React;
+
+  let url: string;
+  try {
+    url = resolveModuleUrl(rawModule);
+  } catch (error) {
+    createRoot(root).render(failureElement("This artifact could not be loaded.", messageOf(error)));
+    return;
+  }
+
+  try {
+    const loaded = (await import(url)) as { default?: unknown };
+    const Artifact = loaded.default;
+    if (typeof Artifact !== "function") {
+      throw new Error("Artifact modules must default-export a React component.");
+    }
+    createRoot(root).render(
+      createElement(ArtifactErrorBoundary, null, createElement(Artifact as React.ComponentType)),
+    );
+  } catch (error) {
+    // A failed module import reports only a generic fetch failure, so ask the
+    // server directly for the diagnostic it already produced.
+    const detail = (await serverDiagnostic(url)) ?? messageOf(error);
+    createRoot(root).render(failureElement("This artifact could not be compiled or loaded.", detail));
+  }
+}
+
+/**
+ * Recover the server's error body for a module the browser refused to import.
+ * Returns undefined when the request succeeded or carried no readable reason.
+ */
+async function serverDiagnostic(url: string): Promise<string | undefined> {
+  try {
+    const response = await fetch(url);
+    if (response.ok) return undefined;
+    const body = await response.text();
+    try {
+      const parsed = JSON.parse(body) as { error?: unknown };
+      return typeof parsed.error === "string" && parsed.error !== "" ? parsed.error : undefined;
+    } catch {
+      return body.trim() === "" ? undefined : body.trim();
+    }
+  } catch {
+    return undefined;
+  }
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error && error.message ? error.message : String(error);
+}