@shipfox/client-logs 0.2.0

package/src/components/log-view.test.tsx

@@ -0,0 +1,266 @@
+import type {LogRecord} from '@shipfox/api-logs-dto';
+import {fireEvent, render, screen, waitFor} from '@testing-library/react';
+import {LogView, LogViewSkeleton} from './log-view.js';
+
+const ts = new Date('2026-06-23T10:00:00.000Z').getTime();
+const THINKING_BUTTON_NAME = /thinking/i;
+
+const output = (data: string): LogRecord => ({
+  v: 1,
+  ts,
+  type: 'output',
+  stream: 'stdout',
+  data,
+});
+type AgentSessionRow = Extract<LogRecord, {type: 'agent_session'}>['row'];
+
+const agentSession = (row: AgentSessionRow, offsetMs = 0): LogRecord => ({
+  v: 1,
+  ts: ts + offsetMs,
+  type: 'agent_session',
+  row,
+});
+
+describe('LogView', () => {
+  let scrollIntoViewDescriptor: PropertyDescriptor | undefined;
+  let scrollIntoViewWasStubbed = false;
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+    if (scrollIntoViewWasStubbed) {
+      if (scrollIntoViewDescriptor != null) {
+        Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', scrollIntoViewDescriptor);
+      } else {
+        Reflect.deleteProperty(HTMLElement.prototype, 'scrollIntoView');
+      }
+    }
+    scrollIntoViewDescriptor = undefined;
+    scrollIntoViewWasStubbed = false;
+  });
+
+  test('renders the complete empty state for an empty closed stream', () => {
+    render(<LogView records={[]} />);
+
+    expect(screen.getByText('Step produced no output')).toBeDefined();
+    expect(
+      screen.getByText('This log stream closed without session entries or process output.'),
+    ).toBeDefined();
+    expect(screen.getByRole('log')).toBeDefined();
+  });
+
+  test('renders the pending empty state for an empty open stream', () => {
+    render(<LogView records={[]} emptyState="pending" />);
+
+    expect(screen.getByText('No output yet')).toBeDefined();
+    expect(screen.getByText('New lines will appear here as the step writes them.')).toBeDefined();
+    expect(screen.queryByText('Step produced no output')).toBeNull();
+  });
+
+  test('renders no-output copy before the end marker for an end-marker-only stream', () => {
+    render(<LogView records={[{v: 1, ts, type: 'end', total_bytes: 0}]} />);
+
+    expect(screen.getByText('Step produced no output')).toBeDefined();
+    expect(screen.getByText('End of log')).toBeDefined();
+    expect(screen.getByText('0 lines · 0 B · 0ms')).toBeDefined();
+  });
+
+  test.each([
+    {record: {v: 1, ts, type: 'runner_lost'} as const, label: 'Runner disconnected'},
+    {record: {v: 1, ts, type: 'gap', dropped_bytes: 2048} as const, label: 'Output missing'},
+    {record: {v: 1, ts, type: 'capped'} as const, label: 'Log size limit reached'},
+  ])('does not show no-output copy for a $record.type marker-only stream', ({record, label}) => {
+    render(<LogView records={[record]} />);
+
+    expect(screen.getByText(label)).toBeDefined();
+    expect(screen.queryByText('Step produced no output')).toBeNull();
+    expect(screen.queryByText('No output yet')).toBeNull();
+  });
+
+  test('does not render empty copy when output exists', () => {
+    render(<LogView records={[output('hello\n')]} />);
+
+    expect(screen.getByText('hello')).toBeDefined();
+    expect(screen.queryByText('Step produced no output')).toBeNull();
+    expect(screen.queryByText('No output yet')).toBeNull();
+  });
+
+  test('renders assistant session text and collapsed thinking', () => {
+    render(
+      <LogView
+        records={[
+          agentSession({
+            kind: 'message',
+            timestamp: ts,
+            role: 'assistant',
+            label: 'assistant',
+            meta: [],
+            text: 'I will inspect the failure.',
+            terminalFailure: false,
+          }),
+          agentSession({
+            kind: 'thinking',
+            timestamp: ts,
+            text: 'The stack trace points at validation.',
+          }),
+        ]}
+      />,
+    );
+
+    expect(screen.getByText('I will inspect the failure.')).toBeDefined();
+    expect(screen.getByRole('button', {name: THINKING_BUTTON_NAME})).toBeDefined();
+    expect(screen.queryByText('The stack trace points at validation.')).toBeNull();
+
+    fireEvent.click(screen.getByRole('button', {name: THINKING_BUTTON_NAME}));
+
+    expect(screen.getByText('The stack trace points at validation.')).toBeDefined();
+  });
+
+  test('renders tool calls with awaiting state until a result appears later in the stream', () => {
+    render(
+      <LogView
+        records={[
+          agentSession({
+            kind: 'tool-call',
+            timestamp: ts,
+            id: 'call-1',
+            name: 'edit_file',
+            input: '{}',
+          }),
+          output('stdout between call and result\n'),
+          agentSession({
+            kind: 'tool-result',
+            timestamp: ts + 1,
+            toolCallId: 'call-1',
+            toolName: 'edit_file',
+            output: 'patched',
+            isError: false,
+          }),
+        ]}
+      />,
+    );
+
+    expect(screen.getByText('tool edit_file')).toBeDefined();
+    expect(screen.getByText('stdout between call and result')).toBeDefined();
+    expect(screen.getByText('result edit_file')).toBeDefined();
+    expect(screen.queryByText('awaiting result')).toBeNull();
+  });
+
+  test('shows the awaiting-result state for a tool call with no matching result', () => {
+    render(
+      <LogView
+        records={[
+          agentSession({
+            kind: 'tool-call',
+            timestamp: ts,
+            id: 'call-1',
+            name: 'edit_file',
+            input: '{}',
+          }),
+        ]}
+      />,
+    );
+
+    expect(screen.getByText('tool edit_file')).toBeDefined();
+    expect(screen.getByText('awaiting result')).toBeDefined();
+  });
+
+  test('renders unknown session entries without crashing', () => {
+    render(
+      <LogView
+        records={[
+          agentSession({
+            kind: 'raw',
+            timestamp: ts,
+            label: 'Unknown session entry: future_entry',
+            raw: '{"type":"future_entry","payload":{"value":true}}',
+          }),
+        ]}
+      />,
+    );
+
+    expect(screen.getByText('Unknown session entry: future_entry')).toBeDefined();
+  });
+
+  test('truncates large payloads with a show-more control', () => {
+    render(
+      <LogView
+        records={[
+          agentSession({
+            kind: 'message',
+            timestamp: ts,
+            role: 'assistant',
+            label: 'assistant',
+            meta: [],
+            text: 'x'.repeat(1500),
+            terminalFailure: false,
+          }),
+        ]}
+      />,
+    );
+
+    const toggle = screen.getByRole('button', {name: 'show more'});
+    expect(toggle.getAttribute('aria-expanded')).toBe('false');
+
+    fireEvent.click(toggle);
+
+    expect(screen.getByRole('button', {name: 'show less'}).getAttribute('aria-expanded')).toBe(
+      'true',
+    );
+  });
+
+  test('anchors terminal failures when requested', async () => {
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+      callback(0);
+      return 1;
+    });
+    vi.stubGlobal('cancelAnimationFrame', vi.fn());
+    scrollIntoViewDescriptor = Object.getOwnPropertyDescriptor(
+      HTMLElement.prototype,
+      'scrollIntoView',
+    );
+    scrollIntoViewWasStubbed = true;
+    if (scrollIntoViewDescriptor == null) {
+      Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', {
+        configurable: true,
+        value: () => undefined,
+      });
+    }
+    const scrollIntoView = vi
+      .spyOn(HTMLElement.prototype, 'scrollIntoView')
+      .mockImplementation(() => undefined);
+
+    render(
+      <LogView
+        anchorToFailure
+        records={[
+          output('setup\n'),
+          agentSession({
+            kind: 'message',
+            timestamp: ts,
+            role: 'assistant',
+            label: 'assistant',
+            meta: [],
+            text: 'I cannot continue.',
+            terminalFailure: true,
+          }),
+        ]}
+      />,
+    );
+
+    await waitFor(() => expect(scrollIntoView).toHaveBeenCalledWith({block: 'center'}));
+  });
+});
+
+describe('LogViewSkeleton', () => {
+  test('keeps visual log chrome without exposing fake log content', () => {
+    const {container} = render(<LogViewSkeleton rows={3} />);
+
+    expect(screen.queryByRole('log')).toBeNull();
+    expect(container.querySelector('[data-slot="log-rows"]')?.getAttribute('aria-hidden')).toBe(
+      'true',
+    );
+    expect(container.querySelectorAll('[data-slot="log-row"]')).toHaveLength(3);
+    expect(container.querySelectorAll('[data-slot="skeleton"]')).toHaveLength(3);
+  });
+});

package/src/components/log-view.tsx

@@ -0,0 +1,281 @@
+'use client';
+
+import type {LogRecord} from '@shipfox/api-logs-dto';
+import {Icon} from '@shipfox/react-ui/icon';
+import {LogContent, LogRow, LogRows, type LogTimestampMode} from '@shipfox/react-ui/log';
+import {Skeleton} from '@shipfox/react-ui/skeleton';
+import {type ReactNode, type UIEventHandler, useEffect, useMemo, useRef} from 'react';
+import {
+  assertNever,
+  buildLogTree,
+  type LogNode,
+  type LogTree,
+  type MarkerLogRecord,
+} from '#core/log-tree.js';
+import {AgentSessionRows} from './agent-session-rows.js';
+import {LogGroup} from './log-group.js';
+import {OutputLogRow} from './output-log-row.js';
+import {CappedMarker, EndMarker, GapMarker, RunnerLostMarker} from './system-markers.js';
+
+export interface LogViewProps {
+  records: readonly LogRecord[];
+  timestamps?: LogTimestampMode;
+  wrap?: boolean;
+  showLineNumbers?: boolean;
+  emptyState?: 'complete' | 'pending';
+  defaultGroupsOpen?: boolean;
+  anchorToFailure?: boolean;
+  className?: string | undefined;
+  onScroll?: UIEventHandler<HTMLDivElement> | undefined;
+}
+
+export interface LogViewSkeletonProps
+  extends Pick<LogViewProps, 'timestamps' | 'wrap' | 'showLineNumbers' | 'className'> {
+  rows?: number;
+}
+
+export function LogView({
+  records,
+  timestamps = 'off',
+  wrap = false,
+  showLineNumbers = true,
+  emptyState = 'complete',
+  defaultGroupsOpen = false,
+  anchorToFailure = false,
+  className,
+  onScroll,
+}: LogViewProps) {
+  const rowsRef = useRef<HTMLDivElement>(null);
+  const tree = useMemo(() => buildLogTree(records), [records]);
+  const resolvedToolCallIds = useMemo(() => collectResolvedToolCallIds(tree.nodes), [tree.nodes]);
+  const noOutputState = getNoOutputState(tree, emptyState);
+  const anchorRecordCount = records.length;
+
+  useEffect(() => {
+    if (!anchorToFailure) return;
+    if (anchorRecordCount === 0) return;
+
+    const frame = scheduleAnimationFrame(() => {
+      const rows = rowsRef.current;
+      if (!rows) return;
+
+      const failure = rows.querySelector<HTMLElement>('[data-log-terminal-failure="true"]');
+      if (failure) {
+        failure.scrollIntoView({block: 'center'});
+        return;
+      }
+
+      rows.scrollTop = rows.scrollHeight;
+    });
+
+    return () => cancelScheduledFrame(frame);
+  }, [anchorToFailure, anchorRecordCount]);
+
+  return (
+    <LogRows
+      ref={rowsRef}
+      timestamps={timestamps}
+      wrap={wrap}
+      showLineNumbers={showLineNumbers}
+      className={className}
+      onScroll={onScroll}
+      {...(tree.originTs != null ? {timestampOrigin: new Date(tree.originTs)} : {})}
+    >
+      {noOutputState ? <NoOutputRow state={noOutputState} /> : null}
+      {renderNodes(tree.nodes, 0, tree, defaultGroupsOpen, resolvedToolCallIds)}
+    </LogRows>
+  );
+}
+
+export function LogViewSkeleton({
+  rows = 5,
+  timestamps = 'off',
+  wrap = false,
+  showLineNumbers = true,
+  className,
+}: LogViewSkeletonProps) {
+  const widths = ['w-[62%]', 'w-[44%]', 'w-[74%]', 'w-[36%]', 'w-[55%]'];
+  const skeletonRows = getSkeletonRows(rows);
+
+  return (
+    <LogRows
+      timestamps={timestamps}
+      wrap={wrap}
+      showLineNumbers={showLineNumbers}
+      className={className}
+      role="presentation"
+      aria-live="off"
+      aria-hidden="true"
+    >
+      {skeletonRows.map((row) => (
+        <LogRow key={row.id} lineNumber={row.lineNumber}>
+          <Skeleton
+            className={`my-4 h-12 ${widths[(row.lineNumber - 1) % widths.length] ?? 'w-[48%]'}`}
+          />
+        </LogRow>
+      ))}
+    </LogRows>
+  );
+}
+
+function getSkeletonRows(rows: number): {id: string; lineNumber: number}[] {
+  return Array.from({length: rows}, (_, index) => {
+    const lineNumber = index + 1;
+    return {id: `log-view-skeleton-row-${lineNumber}`, lineNumber};
+  });
+}
+
+function getNoOutputState(
+  tree: LogTree,
+  emptyState: NonNullable<LogViewProps['emptyState']>,
+): LogViewProps['emptyState'] | null {
+  if (tree.nodes.length === 0) return emptyState;
+
+  if (tree.lineCount !== 0) return null;
+  if (tree.nodes.length !== 1) return null;
+
+  const [node] = tree.nodes;
+  if (node?.kind === 'marker' && node.record.type === 'end') return 'complete';
+
+  return null;
+}
+
+function NoOutputRow({state}: {state: NonNullable<LogViewProps['emptyState']>}) {
+  const copy =
+    state === 'pending'
+      ? {
+          title: 'No output yet',
+          detail: 'New lines will appear here as the step writes them.',
+        }
+      : {
+          title: 'Step produced no output',
+          detail: 'This log stream closed without session entries or process output.',
+        };
+
+  return (
+    <LogRow lineNumber={null}>
+      <LogContent className="text-foreground-neutral-muted">
+        <span className="inline-flex min-w-0 items-center gap-8">
+          <Icon name="info" className="size-14 flex-none" aria-hidden="true" />
+          <span className="min-w-0">
+            <span className="font-medium">{copy.title}</span>
+            {' · '}
+            <span className="text-foreground-neutral-subtle">{copy.detail}</span>
+          </span>
+        </span>
+      </LogContent>
+    </LogRow>
+  );
+}
+
+function renderNodes(
+  nodes: readonly LogNode[],
+  depth: number,
+  tree: LogTree,
+  defaultGroupsOpen: boolean,
+  resolvedToolCallIds: ReadonlySet<string>,
+): ReactNode[] {
+  // `node.seq` is the stable, unique render key (see `LogNodeBase`): a concatenated
+  // multi-step/retry stream can repeat a `group_id` or a marker's `(type, ts)` at one
+  // level, which a key derived from those fields would collide on.
+  return nodes.map((node): ReactNode => {
+    switch (node.kind) {
+      case 'output':
+        return (
+          <OutputLogRow
+            key={node.seq}
+            record={node.record}
+            lineNumber={node.lineNumber}
+            indent={depth}
+          />
+        );
+      case 'group':
+        return (
+          <LogGroup
+            key={node.seq}
+            node={node}
+            depth={depth}
+            terminated={tree.terminated}
+            defaultOpen={defaultGroupsOpen}
+          >
+            {renderNodes(node.children, depth + 1, tree, defaultGroupsOpen, resolvedToolCallIds)}
+          </LogGroup>
+        );
+      case 'marker':
+        return <MarkerRow key={node.seq} record={node.record} tree={tree} />;
+      case 'session':
+        return (
+          <AgentSessionRows
+            key={node.seq}
+            rows={[node.record.row]}
+            resolvedToolCallIds={resolvedToolCallIds}
+            indent={depth}
+          />
+        );
+      default:
+        return assertNever(node);
+    }
+  });
+}
+
+function collectResolvedToolCallIds(nodes: readonly LogNode[]): ReadonlySet<string> {
+  const ids = new Set<string>();
+  collectResolvedToolCallIdsInto(nodes, ids);
+  return ids;
+}
+
+function collectResolvedToolCallIdsInto(nodes: readonly LogNode[], ids: Set<string>): void {
+  for (const node of nodes) {
+    switch (node.kind) {
+      case 'session':
+        if (node.record.row.kind === 'tool-result' && node.record.row.toolCallId != null) {
+          ids.add(node.record.row.toolCallId);
+        }
+        break;
+      case 'group':
+        collectResolvedToolCallIdsInto(node.children, ids);
+        break;
+      case 'output':
+      case 'marker':
+        break;
+      default:
+        assertNever(node);
+    }
+  }
+}
+
+function scheduleAnimationFrame(callback: FrameRequestCallback): number {
+  if (typeof globalThis.requestAnimationFrame === 'function') {
+    return globalThis.requestAnimationFrame(callback);
+  }
+  return window.setTimeout(() => callback(Date.now()), 0);
+}
+
+function cancelScheduledFrame(frame: number) {
+  if (typeof globalThis.cancelAnimationFrame === 'function') {
+    globalThis.cancelAnimationFrame(frame);
+    return;
+  }
+  window.clearTimeout(frame);
+}
+
+function MarkerRow({record, tree}: {record: MarkerLogRecord; tree: LogTree}): ReactNode {
+  switch (record.type) {
+    case 'end':
+      return (
+        <EndMarker
+          record={record}
+          lineCount={tree.lineCount}
+          durationMs={tree.originTs != null ? record.ts - tree.originTs : null}
+        />
+      );
+    case 'gap':
+      return <GapMarker record={record} />;
+    case 'capped':
+      return <CappedMarker record={record} />;
+    case 'runner_lost':
+      return <RunnerLostMarker record={record} />;
+    default:
+      return assertNever(record);
+  }
+}

package/src/components/output-log-row.stories.tsx

@@ -0,0 +1,76 @@
+import {LogRows} from '@shipfox/react-ui/log';
+import type {Meta, StoryObj} from '@storybook/react';
+import type {OutputLogRecord} from '#core/log-tree.js';
+import {OutputLogRow} from './output-log-row.js';
+
+const ESC = String.fromCharCode(27);
+const origin = new Date('2026-06-23T10:00:00.000Z').getTime();
+
+const record = (
+  data: string,
+  stream: 'stdout' | 'stderr' = 'stdout',
+  offsetSeconds = 0,
+): OutputLogRecord => ({
+  v: 1,
+  ts: origin + offsetSeconds * 1000,
+  type: 'output',
+  stream,
+  data,
+});
+
+const meta = {
+  title: 'Logs/OutputLogRow',
+  component: OutputLogRow,
+  parameters: {layout: 'padded'},
+  tags: ['autodocs'],
+} satisfies Meta<typeof OutputLogRow>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  render: () => (
+    <div className="max-w-3xl">
+      <LogRows>
+        <OutputLogRow
+          record={record('transforming (1284) src/index.tsx\n', 'stdout', 0)}
+          lineNumber={1}
+        />
+        <OutputLogRow
+          record={record(
+            `${ESC}[32m✓${ESC}[0m built ${ESC}[34m1284${ESC}[0m modules\n`,
+            'stdout',
+            1,
+          )}
+          lineNumber={2}
+        />
+        <OutputLogRow
+          record={record('warn: deprecated glob@7, upgrade to glob@10\n', 'stderr', 2)}
+          lineNumber={3}
+        />
+        <OutputLogRow
+          record={record('FAIL client.test.ts > retries on 503\n', 'stderr', 3)}
+          lineNumber={4}
+        />
+        <OutputLogRow record={record('done in 412ms\n', 'stdout', 4)} lineNumber={5} />
+      </LogRows>
+    </div>
+  ),
+};
+
+export const LongLine: Story = {
+  render: () => (
+    <div className="max-w-md">
+      <LogRows>
+        <OutputLogRow
+          record={record(
+            'ERROR TypeError: Cannot read properties of undefined (reading "id") at withRetry (src/api/retry.ts:42:18) at async runStep (src/runner/step.ts:118:7)\n',
+            'stderr',
+            0,
+          )}
+          lineNumber={120}
+        />
+      </LogRows>
+    </div>
+  ),
+};

package/src/components/output-log-row.tsx

@@ -0,0 +1,35 @@
+import {LogContent, LogRow} from '@shipfox/react-ui/log';
+import {cn} from '@shipfox/react-ui/utils';
+import {type OutputLogRecord, stripTrailingNewline} from '#core/log-tree.js';
+
+export interface OutputLogRowProps {
+  record: OutputLogRecord;
+  lineNumber?: number | null;
+  indent?: number;
+  selected?: boolean;
+}
+
+export function OutputLogRow({
+  record,
+  lineNumber = null,
+  indent = 0,
+  selected = false,
+}: OutputLogRowProps) {
+  const isStderr = record.stream === 'stderr';
+  // Stderr uses a neutral channel rule; it is a stream, not a severity, so it never reads as an error.
+
+  return (
+    <LogRow
+      lineNumber={lineNumber}
+      timestamp={new Date(record.ts)}
+      indent={indent}
+      selected={selected}
+      data-stream={record.stream}
+      className={cn(isStderr && 'shadow-[inset_2px_0_0_var(--color-border-neutral-strong)]')}
+    >
+      <LogContent variant="code" ansi className={cn(isStderr && 'text-foreground-neutral-subtle')}>
+        {stripTrailingNewline(record.data)}
+      </LogContent>
+    </LogRow>
+  );
+}

package/src/components/system-markers.stories.tsx

@@ -0,0 +1,46 @@
+import {LogRows} from '@shipfox/react-ui/log';
+import type {Meta, StoryObj} from '@storybook/react';
+import {CappedMarker, EndMarker, GapMarker, RunnerLostMarker} from './system-markers.js';
+
+const ts = new Date('2026-06-23T10:00:00.000Z').getTime();
+
+const meta = {
+  title: 'Logs/SystemMarkers',
+  component: EndMarker,
+  parameters: {layout: 'padded'},
+  tags: ['autodocs'],
+} satisfies Meta<typeof EndMarker>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  render: () => (
+    <div className="max-w-3xl">
+      <LogRows>
+        <EndMarker
+          record={{v: 1, ts, type: 'end', total_bytes: 15_360}}
+          lineCount={412}
+          durationMs={2100}
+        />
+      </LogRows>
+    </div>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="max-w-3xl">
+      <LogRows>
+        <GapMarker record={{v: 1, ts, type: 'gap', dropped_bytes: 2048}} />
+        <CappedMarker record={{v: 1, ts, type: 'capped'}} />
+        <RunnerLostMarker record={{v: 1, ts, type: 'runner_lost'}} />
+        <EndMarker
+          record={{v: 1, ts, type: 'end', total_bytes: 15_360}}
+          lineCount={412}
+          durationMs={2100}
+        />
+      </LogRows>
+    </div>
+  ),
+};