@vertesia/ui 1.2.0 → 1.4.0-dev.20260615.042549Z

package/src/features/agent/chat/index.ts

@@ -1,36 +1,67 @@
 export {
-    AgentChart, isRechartsSpec, isVegaLiteSpec, type AgentChartSpec,
+    AgentChart,
+    type AgentChartSpec,
+    isRechartsSpec,
+    isVegaLiteSpec,
     type RechartsChartSpec,
-    type VegaLiteChartSpec
-} from "./AgentChart";
-export * from "./AnimatedThinkingDots";
-export * from "./JumpingDots";
-export { ModernAgentConversation } from "./ModernAgentConversation";
-export { VegaLiteChart } from "./VegaLiteChart";
-export * from "./WaitingMessages";
-// MessageInput types for external use
-export type { SelectedDocument, UploadedFile } from "./ModernAgentOutput/MessageInput";
+    type VegaLiteChartSpec,
+} from './AgentChart';
+export {
+    AgentChatFixtureReplay,
+    type AgentChatFixtureReplayProps,
+    type AgentChatReplayFixture,
+    type AgentChatReplayStreamingFrame,
+    type AgentChatReplayStreamingMessage,
+} from './AgentChatFixtureReplay';
+export { AgentChatPlaybackControls, type AgentChatPlaybackControlsProps } from './AgentChatPlaybackControls';
+export * from './AnimatedThinkingDots';
 // AskUser widget for displaying agent prompts/questions
 export {
+    type AskUserOption,
     AskUserWidget,
-    ConfirmationWidget, type AskUserOption, type AskUserWidgetProps, type ConfirmationWidgetProps
-} from "./AskUserWidget";
+    type AskUserWidgetProps,
+    ConfirmationWidget,
+    type ConfirmationWidgetProps,
+} from './AskUserWidget';
+export * from './JumpingDots';
+export { ModernAgentConversation, type ModernAgentConversationProps } from './ModernAgentConversation';
+// AgentConversationViewMode type for external use
+export type {
+    AgentConversationViewMode,
+    AgentInitialRequestTemplate,
+    AgentInitialRequestTemplateContext,
+} from './ModernAgentOutput/AllMessagesMixed';
+// BatchProgressPanel types for external use
+export type { BatchProgressPanelClassNames } from './ModernAgentOutput/BatchProgressPanel';
+export type { HeaderProps } from './ModernAgentOutput/Header';
+// Header widget and types for external use
+export { default as Header } from './ModernAgentOutput/Header';
+// MessageInput types for external use
+export type { SelectedDocument, UploadedFile } from './ModernAgentOutput/MessageInput';
+export type { MessageItemClassNames, MessageItemProps, MessageStyleConfig } from './ModernAgentOutput/MessageItem';
 // MessageItem widget and types for external use
-export { default as MessageItem, MESSAGE_STYLES } from "./ModernAgentOutput/MessageItem";
-export type { MessageItemProps, MessageItemClassNames, MessageStyleConfig } from "./ModernAgentOutput/MessageItem";
+export { default as MessageItem, MESSAGE_STYLES } from './ModernAgentOutput/MessageItem';
+export type { MessagesContainerProps } from './ModernAgentOutput/MessagesContainer';
 // MessagesContainer widget and types for external use
-export { default as MessagesContainer } from "./ModernAgentOutput/MessagesContainer";
-export type { MessagesContainerProps } from "./ModernAgentOutput/MessagesContainer";
-// Header widget and types for external use
-export { default as Header } from "./ModernAgentOutput/Header";
-export type { HeaderProps } from "./ModernAgentOutput/Header";
+export { default as MessagesContainer } from './ModernAgentOutput/MessagesContainer';
+export type { StreamingMessageClassNames, StreamingMessageProps } from './ModernAgentOutput/StreamingMessage';
 // StreamingMessage widget and types for external use
-export { default as StreamingMessage } from "./ModernAgentOutput/StreamingMessage";
-export type { StreamingMessageProps, StreamingMessageClassNames } from "./ModernAgentOutput/StreamingMessage";
+export { default as StreamingMessage } from './ModernAgentOutput/StreamingMessage';
 // ToolCallGroup types for external use
-export type { ToolCallGroupClassNames } from "./ModernAgentOutput/ToolCallGroup";
-// BatchProgressPanel types for external use
-export type { BatchProgressPanelClassNames } from "./ModernAgentOutput/BatchProgressPanel";
-export * from "./SkillWidgetProvider";
-// AgentConversationViewMode type for external use
-export type { AgentConversationViewMode } from "./ModernAgentOutput/AllMessagesMixed";
+export type { ToolCallGroupClassNames } from './ModernAgentOutput/ToolCallGroup';
+export {
+    type AgentChatPlaybackCursor,
+    type AgentChatPlaybackState,
+    clampPlaybackCursor,
+    createPlaybackState,
+    getNextUserTurnIndex,
+    getPlaybackCursorIndex,
+    getPreviousUserTurnIndex,
+    isAgentChatPlaybackAvailable,
+    isAgentChatPlaybackEnabled,
+    isLocalhostAgentChatPlaybackAvailable,
+    isLocalhostAgentChatPlaybackEnabled,
+} from './playback';
+export * from './SkillWidgetProvider';
+export { VegaLiteChart } from './VegaLiteChart';
+export * from './WaitingMessages';

package/src/features/agent/chat/playback.test.ts

@@ -0,0 +1,70 @@
+import { type AgentMessage, AgentMessageType } from '@vertesia/common';
+import { describe, expect, it } from 'vitest';
+import {
+    clampPlaybackCursor,
+    createPlaybackState,
+    getNextUserTurnIndex,
+    getPlaybackCursorIndex,
+    getPreviousUserTurnIndex,
+    isAgentChatPlaybackEnabled,
+} from './playback';
+
+function message(type: AgentMessageType, text: string): AgentMessage {
+    return {
+        timestamp: Date.now(),
+        workflow_run_id: 'run-1',
+        type,
+        message: text,
+        workstream_id: 'main',
+    };
+}
+
+describe('agent chat playback helpers', () => {
+    const messages = [
+        message(AgentMessageType.QUESTION, 'first question'),
+        message(AgentMessageType.ANSWER, 'first answer'),
+        message(AgentMessageType.QUESTION, 'second question'),
+        message(AgentMessageType.ANSWER, 'second answer'),
+    ];
+
+    it('clamps cursors and maps live to the latest message index', () => {
+        expect(clampPlaybackCursor(-10, messages.length)).toBe(0);
+        expect(clampPlaybackCursor(99, messages.length)).toBe(3);
+        expect(clampPlaybackCursor('live', messages.length)).toBe('live');
+        expect(clampPlaybackCursor(0, 0)).toBe('live');
+        expect(getPlaybackCursorIndex('live', messages.length)).toBe(3);
+        expect(getPlaybackCursorIndex('live', 0)).toBe(-1);
+    });
+
+    it('finds previous and next user turns from message and live cursors', () => {
+        expect(getPreviousUserTurnIndex(messages, 'live')).toBe(2);
+        expect(getPreviousUserTurnIndex(messages, 2)).toBe(0);
+        expect(getPreviousUserTurnIndex(messages, 0)).toBeNull();
+        expect(getNextUserTurnIndex(messages, 0)).toBe(2);
+        expect(getNextUserTurnIndex(messages, 2)).toBe('live');
+        expect(getNextUserTurnIndex(messages, 'live')).toBeNull();
+    });
+
+    it('builds a render-only message slice when playback is enabled', () => {
+        const scrubbed = createPlaybackState(messages, 1, true);
+        expect(scrubbed.isLive).toBe(false);
+        expect(scrubbed.renderedMessageCount).toBe(2);
+        expect(scrubbed.displayedMessages.map((item) => item.message)).toEqual(['first question', 'first answer']);
+
+        const live = createPlaybackState(messages, 1, false);
+        expect(live.cursor).toBe('live');
+        expect(live.isLive).toBe(true);
+        expect(live.displayedMessages).toBe(messages);
+    });
+
+    it('enables playback from regular and hash-route query params', () => {
+        window.history.pushState(null, '', '/store/agents/run-1?agentChatPlayback=1#conversation');
+        expect(isAgentChatPlaybackEnabled()).toBe(true);
+
+        window.history.pushState(null, '', '/store/agents/run-1?p=project#conversation?agentChatPlayback=1');
+        expect(isAgentChatPlaybackEnabled()).toBe(true);
+
+        window.history.pushState(null, '', '/store/agents/run-1?p=project#conversation');
+        expect(isAgentChatPlaybackEnabled()).toBe(false);
+    });
+});

package/src/features/agent/chat/playback.ts

@@ -0,0 +1,93 @@
+import { type AgentMessage, AgentMessageType } from '@vertesia/common';
+
+export type AgentChatPlaybackCursor = 'live' | number;
+
+export interface AgentChatPlaybackState {
+    cursor: AgentChatPlaybackCursor;
+    cursorIndex: number;
+    isLive: boolean;
+    renderedMessageCount: number;
+    displayedMessages: AgentMessage[];
+}
+
+export function clampPlaybackCursor(cursor: AgentChatPlaybackCursor, messageCount: number): AgentChatPlaybackCursor {
+    if (cursor === 'live') return cursor;
+    if (messageCount === 0) return 'live';
+    return Math.min(Math.max(cursor, 0), messageCount - 1);
+}
+
+export function getPlaybackCursorIndex(cursor: AgentChatPlaybackCursor, messageCount: number): number {
+    if (messageCount === 0) return -1;
+    if (cursor === 'live') return messageCount - 1;
+    return Math.min(Math.max(cursor, 0), messageCount - 1);
+}
+
+export function getPreviousUserTurnIndex(messages: AgentMessage[], cursor: AgentChatPlaybackCursor): number | null {
+    if (messages.length === 0) return null;
+    const currentIndex = cursor === 'live' ? messages.length : getPlaybackCursorIndex(cursor, messages.length);
+
+    for (let index = Math.min(currentIndex - 1, messages.length - 1); index >= 0; index--) {
+        if (messages[index].type === AgentMessageType.QUESTION) return index;
+    }
+
+    return null;
+}
+
+export function getNextUserTurnIndex(
+    messages: AgentMessage[],
+    cursor: AgentChatPlaybackCursor,
+): number | 'live' | null {
+    if (messages.length === 0 || cursor === 'live') return null;
+    const currentIndex = getPlaybackCursorIndex(cursor, messages.length);
+
+    for (let index = currentIndex + 1; index < messages.length; index++) {
+        if (messages[index].type === AgentMessageType.QUESTION) return index;
+    }
+
+    return 'live';
+}
+
+export function createPlaybackState(
+    messages: AgentMessage[],
+    cursor: AgentChatPlaybackCursor,
+    enabled: boolean,
+): AgentChatPlaybackState {
+    const clampedCursor = enabled ? clampPlaybackCursor(cursor, messages.length) : 'live';
+    const cursorIndex = getPlaybackCursorIndex(clampedCursor, messages.length);
+    const isLive = !enabled || clampedCursor === 'live';
+    const displayedMessages = isLive ? messages : messages.slice(0, cursorIndex + 1);
+
+    return {
+        cursor: clampedCursor,
+        cursorIndex,
+        isLive,
+        renderedMessageCount: displayedMessages.length,
+        displayedMessages,
+    };
+}
+
+function getHashSearchParams(hash: string): URLSearchParams {
+    const queryStart = hash.indexOf('?');
+    if (queryStart === -1) return new URLSearchParams();
+    return new URLSearchParams(hash.slice(queryStart + 1));
+}
+
+export function isAgentChatPlaybackAvailable(): boolean {
+    if (typeof window === 'undefined') return false;
+    return true;
+}
+
+export function isAgentChatPlaybackEnabled(): boolean {
+    if (!isAgentChatPlaybackAvailable()) return false;
+
+    const params = new URLSearchParams(window.location.search);
+    const hashParams = getHashSearchParams(window.location.hash);
+    const value = params.get('agentChatPlayback') ?? hashParams.get('agentChatPlayback');
+    return value === '1' || value === 'true';
+}
+
+/** @deprecated Playback is no longer localhost-only. Use isAgentChatPlaybackAvailable instead. */
+export const isLocalhostAgentChatPlaybackAvailable = isAgentChatPlaybackAvailable;
+
+/** @deprecated Playback is no longer localhost-only. Use isAgentChatPlaybackEnabled instead. */
+export const isLocalhostAgentChatPlaybackEnabled = isAgentChatPlaybackEnabled;

package/src/features/agent/chat/useArtifactUrlCache.tsx

@@ -1,12 +1,9 @@
-import React, { createContext, useContext, useCallback, useRef } from "react";
+import React, { createContext, useCallback, useContext, useRef } from 'react';
 
 interface ArtifactUrlCacheContextValue {
     getUrl: (key: string) => string | undefined;
     setUrl: (key: string, url: string) => void;
-    getOrFetch: (
-        key: string,
-        fetcher: () => Promise<string>
-    ) => Promise<string>;
+    getOrFetch: (key: string, fetcher: () => Promise<string>) => Promise<string>;
 }
 
 const ArtifactUrlCacheContext = createContext<ArtifactUrlCacheContextValue | null>(null);
@@ -27,10 +24,7 @@ export function ArtifactUrlCacheProvider({ children }: { children: React.ReactNo
         cacheRef.current.set(key, url);
     }, []);
 
-    const getOrFetch = useCallback(async (
-        key: string,
-        fetcher: () => Promise<string>
-    ): Promise<string> => {
+    const getOrFetch = useCallback(async (key: string, fetcher: () => Promise<string>): Promise<string> => {
         // Return cached URL if available
         const cached = cacheRef.current.get(key);
         if (cached) {
@@ -44,29 +38,24 @@ export function ArtifactUrlCacheProvider({ children }: { children: React.ReactNo
         }
 
         // Start new fetch and cache the promise
-        const promise = fetcher().then((url) => {
-            cacheRef.current.set(key, url);
-            pendingRef.current.delete(key);
-            return url;
-        }).catch((err) => {
-            pendingRef.current.delete(key);
-            throw err;
-        });
+        const promise = fetcher()
+            .then((url) => {
+                cacheRef.current.set(key, url);
+                pendingRef.current.delete(key);
+                return url;
+            })
+            .catch((err) => {
+                pendingRef.current.delete(key);
+                throw err;
+            });
 
         pendingRef.current.set(key, promise);
         return promise;
     }, []);
 
-    const value = React.useMemo(
-        () => ({ getUrl, setUrl, getOrFetch }),
-        [getUrl, setUrl, getOrFetch]
-    );
+    const value = React.useMemo(() => ({ getUrl, setUrl, getOrFetch }), [getUrl, setUrl, getOrFetch]);
 
-    return (
-        <ArtifactUrlCacheContext.Provider value={value}>
-            {children}
-        </ArtifactUrlCacheContext.Provider>
-    );
+    return <ArtifactUrlCacheContext.Provider value={value}>{children}</ArtifactUrlCacheContext.Provider>;
 }
 
 /**
@@ -77,10 +66,19 @@ export function useArtifactUrlCache(): ArtifactUrlCacheContextValue | null {
     return useContext(ArtifactUrlCacheContext);
 }
 
+/**
+ * Whether an artifact: path points directly into the project bucket
+ * (agents/ run prefixes, documents/ repository copies made by create_document)
+ * rather than being a run-local shorthand like out/chart.png.
+ */
+export function isProjectFilePath(path: string): boolean {
+    return path.startsWith('agents/') || path.startsWith('documents/');
+}
+
 /**
  * Generate a cache key for an artifact URL.
  */
-export function getArtifactCacheKey(runId: string, path: string, disposition: string = "inline"): string {
+export function getArtifactCacheKey(runId: string, path: string, disposition: string = 'inline'): string {
     return `artifact:${runId}:${path}:${disposition}`;
 }
 

package/src/features/agent/chat/workstreams.ts

@@ -0,0 +1,182 @@
+import { type AgentMessage, AgentMessageType } from '@vertesia/common';
+
+export interface WorkstreamInfo {
+    workstream_id: string;
+    launch_id: string;
+    interaction?: string;
+    elapsed_ms: number;
+    deadline_ms: number;
+    remaining_ms: number;
+    status: 'running' | 'canceling' | 'completed' | 'canceled' | 'failed' | 'timeout';
+    phase?: string;
+    child_workflow_id?: string;
+    child_workflow_run_id?: string;
+}
+
+export interface WorkstreamLaunchDetails {
+    workstreamId: string;
+    launchId?: string;
+    kind?: string;
+    interaction?: string;
+    childWorkflowId?: string;
+    childWorkflowRunId?: string;
+}
+
+export function formatWorkstreamName(workstreamId: string) {
+    const normalized = workstreamId
+        .replace(/^workstream[:_-]?/i, '')
+        .replace(/^sys:/i, '')
+        .replace(/[-_:]?[0-9a-f]{8}-[0-9a-f-]{12,}$/i, '')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .replace(/[:_-]+/g, ' ')
+        .trim();
+
+    if (!normalized) return workstreamId;
+
+    return normalized
+        .split(/\s+/)
+        .map((part) => {
+            const lower = part.toLowerCase();
+            if (lower === 'qa') return 'QA';
+            if (lower === 'ui') return 'UI';
+            if (lower === 'api') return 'API';
+            if (lower === 'url') return 'URL';
+            return lower.charAt(0).toUpperCase() + lower.slice(1);
+        })
+        .join(' ');
+}
+
+function isGeneratedWorkstreamId(workstreamId: string) {
+    return /[0-9a-f]{8}-[0-9a-f-]{12,}/i.test(workstreamId);
+}
+
+export function getWorkstreamDisplayName(workstreamId: string, interaction?: string) {
+    const formattedInteraction = interaction ? formatWorkstreamName(interaction) : '';
+    const formattedWorkstream = formatWorkstreamName(workstreamId);
+
+    if (!formattedInteraction) return formattedWorkstream;
+    if (isGeneratedWorkstreamId(workstreamId)) return formattedInteraction;
+
+    const normalizedInteraction = formattedInteraction.toLowerCase().replace(/\s+/g, '');
+    const normalizedWorkstream = formattedWorkstream.toLowerCase().replace(/\s+/g, '');
+    if (normalizedWorkstream.startsWith(normalizedInteraction)) return formattedInteraction;
+
+    return formattedWorkstream;
+}
+
+function getMessageText(message: AgentMessage): string {
+    if (!message.message) return '';
+    if (typeof message.message === 'object') return JSON.stringify(message.message, null, 2);
+    return String(message.message).trim();
+}
+
+function isNonMainWorkstreamId(workstreamId: unknown): workstreamId is string {
+    if (typeof workstreamId !== 'string') return false;
+    const normalized = workstreamId.trim().toLowerCase();
+    return Boolean(normalized && normalized !== 'main' && normalized !== 'all');
+}
+
+function isJsonLikeText(text: string): boolean {
+    const trimmed = text.trim();
+    if (!trimmed || !/^[{[]/.test(trimmed)) return false;
+
+    try {
+        JSON.parse(trimmed);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export function isWorkstreamInternalResultText(text: string, workstreamId?: unknown): boolean {
+    return isNonMainWorkstreamId(workstreamId) && isJsonLikeText(text);
+}
+
+export function isWorkstreamInternalResultMessage(message: AgentMessage): boolean {
+    if (!isWorkstreamInternalResultText(getMessageText(message), message.workstream_id)) return false;
+    if (message.type !== AgentMessageType.ANSWER && message.type !== AgentMessageType.COMPLETE) return false;
+
+    const eventClass = message.details?.event_class;
+    return eventClass === 'user_content' || message.details?.streamed === true;
+}
+
+export function getWorkstreamStatusClass(status: WorkstreamInfo['status']) {
+    switch (status) {
+        case 'running':
+            return 'bg-info';
+        case 'canceling':
+            return 'bg-attention';
+        case 'completed':
+            return 'bg-success';
+        case 'canceled':
+        case 'failed':
+        case 'timeout':
+            return 'bg-destructive';
+    }
+}
+
+export function getWorkstreamLifecycleStatus(message: AgentMessage): WorkstreamInfo['status'] | undefined {
+    const details = message.details as
+        | {
+              status?: unknown;
+              workstream_event?: unknown;
+          }
+        | undefined;
+
+    const status = details?.status;
+    if (
+        status === 'running' ||
+        status === 'canceling' ||
+        status === 'completed' ||
+        status === 'canceled' ||
+        status === 'failed' ||
+        status === 'timeout'
+    ) {
+        return status;
+    }
+
+    if (details?.workstream_event === 'completed') return 'completed';
+    return undefined;
+}
+
+export function isWorkstreamTerminalMessage(message: AgentMessage): boolean {
+    const status = getWorkstreamLifecycleStatus(message);
+    if (status === 'completed' || status === 'canceled' || status === 'failed' || status === 'timeout') return true;
+    return false;
+}
+
+export function getWorkstreamLaunchDetails(message: AgentMessage): WorkstreamLaunchDetails | null {
+    const details = message.details as
+        | {
+              workstream_event?: unknown;
+              workstream_id?: unknown;
+              launch_id?: unknown;
+              kind?: unknown;
+              interaction?: unknown;
+              child_workflow_id?: unknown;
+              child_workflow_run_id?: unknown;
+          }
+        | undefined;
+
+    if (details?.workstream_event !== 'launched') return null;
+
+    const workstreamId =
+        typeof details.workstream_id === 'string'
+            ? details.workstream_id
+            : typeof message.workstream_id === 'string'
+              ? message.workstream_id
+              : '';
+
+    if (!workstreamId || workstreamId === 'main' || workstreamId === 'all') return null;
+
+    return {
+        workstreamId,
+        launchId: typeof details.launch_id === 'string' ? details.launch_id : undefined,
+        kind: typeof details.kind === 'string' ? details.kind : undefined,
+        interaction: typeof details.interaction === 'string' ? details.interaction : undefined,
+        childWorkflowId: typeof details.child_workflow_id === 'string' ? details.child_workflow_id : undefined,
+        childWorkflowRunId:
+            typeof details.child_workflow_run_id === 'string' ? details.child_workflow_run_id : undefined,
+    };
+}

package/src/features/agent/index.ts

@@ -1,2 +1,2 @@
-export * from "./chat";
-export * from "./PayloadBuilder";
+export * from './chat';
+export * from './PayloadBuilder';

package/src/features/document-viewer/UniversalDocumentViewer.test.tsx

@@ -0,0 +1,123 @@
+import { screen, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { renderWithProviders } from '../../__tests__/test-utils.js';
+
+const { getArtifactDownloadUrl, getDownloadUrl } = vi.hoisted(() => ({
+    getArtifactDownloadUrl: vi.fn(),
+    getDownloadUrl: vi.fn(),
+}));
+
+vi.mock('../pdf-viewer/SimplePdfViewer.js', () => ({
+    SimplePdfViewer: () => <div data-testid="pdf-viewer" />,
+}));
+
+vi.mock('@vertesia/ui/session', () => ({
+    useUserSession: () => ({
+        client: {
+            files: {
+                getArtifactDownloadUrl,
+                getDownloadUrl,
+            },
+        },
+    }),
+}));
+
+import { UniversalDocumentViewer } from './UniversalDocumentViewer';
+
+describe('UniversalDocumentViewer TSX sandbox preview', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        getArtifactDownloadUrl.mockImplementation(
+            async (_runId: string, path: string, _disposition: 'inline' | 'attachment') => ({
+                url: `https://signed.example/${encodeURIComponent(path)}`,
+            }),
+        );
+        getDownloadUrl.mockImplementation(
+            async (path: string, _fileName?: string, _disposition?: 'inline' | 'attachment') => ({
+                url: `https://signed.example/${encodeURIComponent(path)}`,
+            }),
+        );
+        vi.stubGlobal(
+            'fetch',
+            vi.fn(async (url: string) => {
+                const decodedUrl = decodeURIComponent(url);
+                const body = decodedUrl.endsWith('.render.json')
+                    ? JSON.stringify({
+                          ok: true,
+                          source_artifact: 'files/mockups/Dashboard.tsx',
+                          screenshot_artifact: 'files/mockups/Dashboard.png',
+                          rendered_at: '2026-06-03T12:00:00.000Z',
+                          viewport: { width: 1440, height: 900 },
+                          dependencies_reused: true,
+                          status: 200,
+                          timings_ms: { total_before_cleanup: 11481 },
+                      })
+                    : 'export default function Dashboard() { return <main>Dashboard</main>; }';
+                return {
+                    ok: true,
+                    statusText: 'OK',
+                    text: async () => body,
+                };
+            }),
+        );
+    });
+
+    it('renders a sibling sandbox PNG preview for TSX artifacts without executing source in Studio', async () => {
+        renderWithProviders(
+            <UniversalDocumentViewer
+                source={{
+                    fileName: 'Dashboard.tsx',
+                    contentType: 'text/typescript',
+                    artifact: {
+                        runId: 'agent-run-1',
+                        path: 'files/mockups/Dashboard.tsx',
+                    },
+                }}
+            />,
+        );
+
+        await screen.findByText('PNG preview');
+        const image = screen.getByAltText('Dashboard.tsx sandbox render') as HTMLImageElement;
+        expect(image.getAttribute('src')).toBe('https://signed.example/files%2Fmockups%2FDashboard.png');
+        expect(screen.getByText('deps reused')).toBeTruthy();
+        expect(screen.getByText('Total 11 s')).toBeTruthy();
+        expect(screen.getByText(/export default function Dashboard/)).toBeTruthy();
+
+        await waitFor(() => {
+            expect(getArtifactDownloadUrl).toHaveBeenCalledWith(
+                'agent-run-1',
+                'files/mockups/Dashboard.render.json',
+                'inline',
+            );
+        });
+        expect(getArtifactDownloadUrl).toHaveBeenCalledWith('agent-run-1', 'files/mockups/Dashboard.png', 'inline');
+    });
+
+    it('resolves copied render metadata relative to app design storage paths', async () => {
+        renderWithProviders(
+            <UniversalDocumentViewer
+                source={{
+                    fileName: 'Dashboard.tsx',
+                    contentType: 'text/typescript',
+                    sourcePath: 'apps/store-health/designs/design-1/artifacts/files/mockups/Dashboard.tsx',
+                }}
+            />,
+        );
+
+        await screen.findByText('PNG preview');
+        const image = screen.getByAltText('Dashboard.tsx sandbox render') as HTMLImageElement;
+        expect(image.getAttribute('src')).toBe(
+            'https://signed.example/apps%2Fstore-health%2Fdesigns%2Fdesign-1%2Fartifacts%2Ffiles%2Fmockups%2FDashboard.png',
+        );
+        expect(getDownloadUrl).toHaveBeenCalledWith(
+            'apps/store-health/designs/design-1/artifacts/files/mockups/Dashboard.render.json',
+            'Dashboard.render.json',
+            'inline',
+        );
+        expect(getDownloadUrl).toHaveBeenCalledWith(
+            'apps/store-health/designs/design-1/artifacts/files/mockups/Dashboard.png',
+            'Dashboard.png',
+            'inline',
+        );
+    });
+});