apache · Dante-dan · Sep 12, 2026 · Sep 12, 2026
diff --git a/apps/desktop/src/main/__tests__/artifact-html-preview-fallback.test.ts b/apps/desktop/src/main/__tests__/artifact-html-preview-fallback.test.ts
@@ -0,0 +1,120 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import assert from 'node:assert/strict';
+import { afterEach, test } from 'node:test';
+import { parseHTML } from 'linkedom';
+import { act, createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { AstryxLocaleProvider, LocaleProvider } from '@maka/ui';
+import type { ArtifactDescriptor } from '@maka/core/artifacts';
+import {
+  ArtifactPreview,
+  createFakeWorkbarServices,
+  WorkbarServicesProvider,
+} from '../../renderer/features/workbar/testing.js';
+
+const originalGlobals = {
+  document: globalThis.document,
+  window: globalThis.window,
+  HTMLElement: globalThis.HTMLElement,
+  HTMLIFrameElement: globalThis.HTMLIFrameElement,
+  Event: globalThis.Event,
+  Node: globalThis.Node,
+  IS_REACT_ACT_ENVIRONMENT: (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean })
+    .IS_REACT_ACT_ENVIRONMENT,
+};
+
+let mountedRoot: Root | undefined;
+
+afterEach(() => {
+  if (mountedRoot) {
+    act(() => mountedRoot?.unmount());
+    mountedRoot = undefined;
+  }
+  Object.assign(globalThis, originalGlobals);
+});
+
+test('HTML read failure offers the existing safe open-path action', async () => {
+  const { document, window } = parseHTML('<html><body><div id="root"></div></body></html>');
+  Object.assign(globalThis, {
+    document,
+    window,
+    HTMLElement: window.HTMLElement,
+    HTMLIFrameElement: window.HTMLIFrameElement ?? class HTMLIFrameElement {},
+    Event: window.Event,
+    Node: window.Node,
+    IS_REACT_ACT_ENVIRONMENT: true,
+  });
+  const container = document.querySelector('#root');
+  assert.ok(container);
+
+  const record: ArtifactDescriptor = {
+    id: 'artifact-html',
+    sessionId: 'session-html',
+    turnId: 'turn-html',
+    name: 'report.html',
+    kind: 'html',
+    mimeType: 'text/html',
+    sizeBytes: 42,
+    createdAt: 1,
+    source: 'tool_result',
+  };
+  const calls: Array<[string, string]> = [];
+  const defaults = createFakeWorkbarServices();
+  const services = {
+    ...defaults,
+    artifacts: {
+      ...defaults.artifacts,
+      readText: async () => ({ ok: false as const, reason: 'read_failed' as const }),
+      openPath: async (sessionId: string, artifactId: string) => {
+        calls.push([sessionId, artifactId]);
+        return { ok: true as const, opened: 'report.html' };
+      },
+    },
+  };
+  const root = createRoot(container);
+  mountedRoot = root;
+
+  await act(async () => {
+    root.render(createElement(LocaleProvider, {
+      locale: 'en',
+      children: createElement(AstryxLocaleProvider, {
+        children: createElement(WorkbarServicesProvider, {
+          services,
+          children: createElement(ArtifactPreview, {
+            record,
+            onShowInFolder: () => void services.artifacts.openPath(record.sessionId, record.id),
+          }),
+        }),
+      }),
+    }));
+    await Promise.resolve();
+  });
+
+  const button = Array.from(container.querySelectorAll('button')).find(
+    (candidate) => candidate.textContent === 'Show in Finder',
+  );
+  assert.ok(button, 'HTML read failure should render a Finder fallback button');
+  await act(async () => {
+    button.dispatchEvent(new window.Event('click', { bubbles: true }));
+    await Promise.resolve();
+  });
+  assert.deepEqual(calls, [['session-html', 'artifact-html']]);
+});
diff --git a/apps/desktop/src/main/__tests__/workbar-services-adapter.test.ts b/apps/desktop/src/main/__tests__/workbar-services-adapter.test.ts
@@ -240,6 +240,10 @@ describe('createDesktopWorkbarServices', () => {
       's',
       'a',
     ]);
+    assert.deepEqual(calls.find((call) => call.name === 'app.openArtifactPath')?.args, [
+      's',
+      'a',
+    ]);
     assert.deepEqual(calls.find((call) => call.name === 'inspector.trace')?.args, [
       's',
       'cursor-1',

diff --git a/apps/desktop/src/renderer/features/workbar/testing.ts b/apps/desktop/src/renderer/features/workbar/testing.ts
@@ -30,6 +30,7 @@ export * from './model/workbar-tabs.js';
 export * from './model/workbar-layout.js';
 export * from './model/workbar-tool-definitions.js';
 export * from './tools/artifacts/artifact-list-keyboard.js';
+export { ArtifactPreview } from './tools/artifacts/artifact-preview.js';
 export * from './tools/artifacts/artifact-visibility.js';
 export * from './tools/inspector/session-inspector-panel-model.js';
 export {

diff --git a/...desktop/src/renderer/features/workbar/tools/artifacts/artifact-preview-registry-shell.tsx b/...desktop/src/renderer/features/workbar/tools/artifacts/artifact-preview-registry-shell.tsx
@@ -31,7 +31,7 @@ import {
   formatPreviewSize,
   resolvePreviewKind,
 } from '@maka/ui/artifact-preview-registry';
-import { getArtifactCopy, type ArtifactCopy } from '../../../../locales/artifact-copy';
+import { getArtifactCopy, type ArtifactCopy } from '../../../../locales/artifact-copy.js';
 import { useWorkbarServices } from '../../services-context.js';
 
 /**

diff --git a/apps/desktop/src/renderer/features/workbar/tools/artifacts/artifact-preview.tsx b/apps/desktop/src/renderer/features/workbar/tools/artifacts/artifact-preview.tsx
@@ -66,8 +66,8 @@ import {
 import { Banner } from '@astryxdesign/core/Banner';
 import { CodeBlock } from '@astryxdesign/core/CodeBlock';
 import { Spinner } from '@astryxdesign/core/Spinner';
-import { RegistryArtifactPreview } from './artifact-preview-registry-shell';
-import { getArtifactCopy, type ArtifactCopy } from '../../../../locales/artifact-copy';
+import { RegistryArtifactPreview } from './artifact-preview-registry-shell.js';
+import { getArtifactCopy, type ArtifactCopy } from '../../../../locales/artifact-copy.js';
 import { useWorkbarServices } from '../../services-context.js';
 
 export function ArtifactPreview(props: { record: ArtifactDescriptor; onShowInFolder?: () => void }) {
@@ -79,7 +79,7 @@ export function ArtifactPreview(props: { record: ArtifactDescriptor; onShowInFol
     case 'diff':
       return <DiffPreview record={record} copy={copy} />;
     case 'html':
-      return <HtmlPreview record={record} copy={copy} />;
+      return <HtmlPreview record={record} copy={copy} onShowInFolder={onShowInFolder} />;
     case 'image':
       // PR-UI-RENDER-3a: route image previews through the typed
       // registry shell so the resolution path (mime match / ext
@@ -176,10 +176,23 @@ function DiffPreview(props: { record: ArtifactDescriptor; copy: ArtifactCopy })
   );
 }
 
-function HtmlPreview(props: { record: ArtifactDescriptor; copy: ArtifactCopy }) {
+function HtmlPreview(props: {
+  record: ArtifactDescriptor;
+  copy: ArtifactCopy;
+  onShowInFolder?: () => void;
+}) {
   const result = useTextRead(props.record.sessionId, props.record.id);
   if (result.state === 'loading') return <PreviewLoading label={props.copy.preview.loadingHtml} />;
-  if (!result.value.ok) return <TextFailureCard record={props.record} reason={result.value.reason} copy={props.copy} />;
+  if (!result.value.ok) {
+    return (
+      <TextFailureCard
+        record={props.record}
+        reason={result.value.reason}
+        copy={props.copy}
+        onShowInFolder={props.onShowInFolder}
+      />
+    );
+  }
   const bounded = boundPreviewText(result.value.text);
   if (bounded.isDisplayTruncated) {
     return (
@@ -335,9 +348,28 @@ function PreviewLoading(props: { label: string }) {
   );
 }
 
-function TextFailureCard(props: { record: ArtifactDescriptor; reason: TextFailureReason; copy: ArtifactCopy }) {
+function TextFailureCard(props: {
+  record: ArtifactDescriptor;
+  reason: TextFailureReason;
+  copy: ArtifactCopy;
+  onShowInFolder?: () => void;
+}) {
   const { status, title, description } = failureCopyText(props.record, props.reason, props.copy);
-  return <Banner status={status} role="status" title={title} description={description} />;
+  return (
+    <Banner
+      status={status}
+      role="status"
+      title={title}
+      description={description}
+      endContent={props.onShowInFolder ? (
+        <Button
+          variant="secondary"
+          onClick={props.onShowInFolder}
+          label={props.copy.pane.openInFinder}
+        />
+      ) : undefined}
+    />
+  );
 }
 
 function BinaryFailureCard(props: { record: ArtifactDescriptor; reason: BinaryFailureReason; copy: ArtifactCopy }) {
-Original file line number
+Diff line change
@@ Expand Up / @@ -240,6 +240,10 @@ describe('createDesktopWorkbarServices', () => { @@
           's',
           'a',
         ]);
+        assert.deepEqual(calls.find((call) => call.name === 'app.openArtifactPath')?.args, [
+          's',
+          'a',
+        ]);
         assert.deepEqual(calls.find((call) => call.name === 'inspector.trace')?.args, [
           's',
           'cursor-1',
@@ Expand Down @@