@gntik-ai/blocks 0.0.0-stage → 0.5.0

package/src/builders/FlowBuilder/fixtures.ts

@@ -0,0 +1,80 @@
+import type { FlowCanvasProps, FlowNode, FlowNodeKind } from '@gntik-ai/flow';
+
+/** React Flow edge, as FlowCanvas takes it. */
+export type FlowEdge = NonNullable<FlowCanvasProps['edges']>[number];
+
+export interface PaletteItem {
+  kind: FlowNodeKind;
+  /** Default title of a node created from this item. */
+  title: string;
+  description: string;
+}
+
+export interface ConsoleEntry {
+  id: string;
+  /** Display time, e.g. "10:42:07". */
+  time: string;
+  level: 'info' | 'success' | 'warn' | 'error';
+  message: string;
+}
+
+const CARD = { width: 208, height: 90 } as const;
+const SLIM = { width: 208, height: 56 } as const;
+
+/** Neutral starter flow: webhook → validate → route → notify / store. */
+export const builderNodes: FlowNode[] = [
+  {
+    id: 'webhook',
+    type: 'trigger',
+    position: { x: 0, y: 112 },
+    ...SLIM,
+    data: { title: 'Webhook', subtitle: 'POST /v1/orders' },
+  },
+  {
+    id: 'validate',
+    type: 'step',
+    position: { x: 256, y: 96 },
+    ...CARD,
+    data: { title: 'Validate payload', subtitle: 'schema check', meta: 'v1.4', tone: 'done' },
+  },
+  {
+    id: 'route',
+    type: 'router',
+    position: { x: 512, y: 112 },
+    ...SLIM,
+    data: { title: 'Route by region', subtitle: '2 branches' },
+  },
+  {
+    id: 'notify',
+    type: 'output',
+    position: { x: 768, y: 16 },
+    ...CARD,
+    data: { title: 'Notify team', subtitle: 'email digest' },
+  },
+  {
+    id: 'store',
+    type: 'output',
+    position: { x: 768, y: 192 },
+    ...CARD,
+    data: { title: 'Store record', subtitle: 'orders table' },
+  },
+];
+
+export const builderEdges: FlowEdge[] = [
+  { id: 'e-webhook-validate', source: 'webhook', target: 'validate', animated: true },
+  { id: 'e-validate-route', source: 'validate', target: 'route' },
+  { id: 'e-route-notify', source: 'route', target: 'notify', label: 'eu' },
+  { id: 'e-route-store', source: 'route', target: 'store', label: 'other' },
+];
+
+export const builderPalette: PaletteItem[] = [
+  { kind: 'trigger', title: 'Trigger', description: 'Starts the flow on an event' },
+  { kind: 'step', title: 'Step', description: 'Processes or transforms data' },
+  { kind: 'router', title: 'Router', description: 'Branches on a condition' },
+  { kind: 'output', title: 'Output', description: 'Sends the final result' },
+];
+
+export const builderConsole: ConsoleEntry[] = [
+  { id: 'c1', time: '10:41:58', level: 'info', message: 'Flow loaded · 5 nodes, 4 edges' },
+  { id: 'c2', time: '10:42:01', level: 'success', message: 'Validation passed' },
+];

package/src/builders/FlowBuilder/parts.tsx

@@ -0,0 +1,196 @@
+import { useId } from 'react';
+import { MousePointerClick, Plus, Trash2 } from '@gntik-ai/icons';
+import {
+  FLOW_TONES,
+  KIND_CHIP,
+  KindGlyph,
+  type FlowNode,
+  type FlowNodeData,
+  type FlowTone,
+  type FlowNodeKind,
+} from '@gntik-ai/flow';
+import { Button, Field, FieldLabel, Input, SimpleSelect, cn } from '@gntik-ai/ui';
+import type { ConsoleEntry, PaletteItem } from './fixtures';
+
+/** Heading level of a panel title (one below the builder's title). */
+export type PanelHeading = 'h3' | 'h4' | 'h5';
+
+const panelTitle =
+  'px-3 pt-3 pb-2 font-mono text-[10.5px] font-medium tracking-[0.12em] text-muted-foreground uppercase';
+
+export interface NodePaletteProps {
+  items: PaletteItem[];
+  onAdd: (item: PaletteItem) => void;
+  /** Heading level of the panel title (default h3). */
+  titleAs?: PanelHeading;
+}
+
+/** Left rail: node kinds to add to the canvas. */
+export function NodePalette({ items, onAdd, titleAs: TitleTag = 'h3' }: NodePaletteProps) {
+  const titleId = useId();
+  return (
+    <div className="flex h-full min-h-0 flex-col bg-card">
+      <TitleTag id={titleId} className={panelTitle}>
+        Nodes
+      </TitleTag>
+      <ul aria-labelledby={titleId} className="flex-1 overflow-y-auto px-2 pb-2">
+        {items.map((item) => (
+          <li key={item.kind + item.title}>
+            <button
+              type="button"
+              onClick={() => onAdd(item)}
+              aria-label={`Add ${item.title}`}
+              title={item.description}
+              className="group flex w-full items-center gap-2.5 rounded-md px-2 py-2 text-start hover:bg-secondary/70 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring"
+            >
+              <span className={cn('grid size-7 shrink-0 place-items-center rounded-md', KIND_CHIP[item.kind])}>
+                <KindGlyph kind={item.kind} size={14} />
+              </span>
+              <span className="min-w-0 flex-1">
+                <span className="block text-[12.5px] font-medium text-foreground">{item.title}</span>
+                <span className="block truncate text-[11px] text-muted-foreground">{item.description}</span>
+              </span>
+              <Plus size={14} aria-hidden className="shrink-0 text-muted-foreground group-hover:text-foreground" />
+            </button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+function inspectorKind(type: string | undefined): FlowNodeKind {
+  return type === 'trigger' || type === 'router' || type === 'output' ? type : 'step';
+}
+
+const TONE_ITEMS = [
+  { value: 'none', label: 'No status' },
+  ...(Object.keys(FLOW_TONES) as FlowTone[]).map((t) => ({ value: t, label: FLOW_TONES[t].label })),
+];
+
+export interface NodeInspectorProps<Kind extends string = FlowNodeKind> {
+  node: FlowNode<Kind> | undefined;
+  onChange: (id: string, patch: Partial<FlowNodeData>) => void;
+  onDelete: (id: string) => void;
+  /** Heading level of the panel title (default h3). */
+  titleAs?: PanelHeading;
+}
+
+/** Right rail: the selected node's editable fields. */
+export function NodeInspector<Kind extends string = FlowNodeKind>({
+  node,
+  onChange,
+  onDelete,
+  titleAs: TitleTag = 'h3',
+}: NodeInspectorProps<Kind>) {
+  const titleId = useId();
+  return (
+    <div className="flex h-full min-h-0 flex-col bg-card">
+      <TitleTag id={titleId} className={panelTitle}>
+        Inspector
+      </TitleTag>
+      {node ? (
+        <form
+          aria-labelledby={titleId}
+          onSubmit={(e) => e.preventDefault()}
+          className="flex flex-1 flex-col gap-3 overflow-y-auto px-3 pb-3"
+        >
+          <p className="flex items-center gap-2 text-[12px] text-muted-foreground">
+            <span className={cn('grid size-5 place-items-center rounded', KIND_CHIP[inspectorKind(node.type)])}>
+              <KindGlyph kind={inspectorKind(node.type)} size={11} />
+            </span>
+            <span className="capitalize">{node.type}</span>
+            <span className="font-mono text-[11px]">· {node.id}</span>
+          </p>
+          <Field>
+            <FieldLabel>Title</FieldLabel>
+            <Input size="sm" value={node.data.title} onValueChange={(v) => onChange(node.id, { title: String(v) })} />
+          </Field>
+          <Field>
+            <FieldLabel>Subtitle</FieldLabel>
+            <Input
+              size="sm"
+              value={node.data.subtitle ?? ''}
+              onValueChange={(v) => onChange(node.id, { subtitle: String(v) || undefined })}
+            />
+          </Field>
+          <Field>
+            <FieldLabel>Meta</FieldLabel>
+            <Input
+              size="sm"
+              value={node.data.meta ?? ''}
+              onValueChange={(v) => onChange(node.id, { meta: String(v) || undefined })}
+            />
+          </Field>
+          <SimpleSelect
+            label="Status"
+            size="sm"
+            items={TONE_ITEMS}
+            value={node.data.tone ?? 'none'}
+            onValueChange={(v) => onChange(node.id, { tone: v && v !== 'none' ? (v as FlowTone) : undefined })}
+          />
+          <Button
+            variant="ghost"
+            size="sm"
+            icon={Trash2}
+            onClick={() => onDelete(node.id)}
+            className="mt-auto self-start"
+          >
+            Delete node
+          </Button>
+        </form>
+      ) : (
+        <div className="flex flex-1 flex-col items-center justify-center gap-2 px-4 pb-6 text-center">
+          <MousePointerClick size={18} aria-hidden className="text-muted-foreground" />
+          <p className="text-[12.5px] text-muted-foreground">Select a node to edit its fields.</p>
+        </div>
+      )}
+    </div>
+  );
+}
+
+const CONSOLE_LEVEL: Record<ConsoleEntry['level'], string> = {
+  info: 'text-muted-foreground',
+  success: 'text-success-text',
+  warn: 'text-warning-text',
+  error: 'text-destructive-text',
+};
+
+export interface RunConsoleProps {
+  entries: ConsoleEntry[];
+  onClear: () => void;
+  /** Heading level of the panel title (default h3). */
+  titleAs?: PanelHeading;
+}
+
+/** Bottom panel: run output (role="log"). */
+export function RunConsole({ entries, onClear, titleAs: TitleTag = 'h3' }: RunConsoleProps) {
+  return (
+    <div className="flex h-full min-h-0 flex-col bg-card">
+      <div className="flex items-center justify-between border-b border-border pe-2">
+        <TitleTag className={cn(panelTitle, 'pb-2')}>Run console</TitleTag>
+        <Button variant="ghost" size="sm" onClick={onClear} disabled={entries.length === 0} className="h-7">
+          Clear
+        </Button>
+      </div>
+      <div
+        role="log"
+        aria-label="Run console"
+        tabIndex={0}
+        className="flex-1 overflow-y-auto px-3 py-2 font-mono text-[11.5px] focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring"
+      >
+        {entries.length === 0 ? (
+          <p className="font-sans text-[12.5px] text-muted-foreground">No output yet. Run the flow to see its steps.</p>
+        ) : (
+          entries.map((e) => (
+            <p key={e.id} className="flex gap-3 py-0.5">
+              <span className="shrink-0 text-muted-foreground tabular-nums">{e.time}</span>
+              <span className={cn('w-14 shrink-0 uppercase', CONSOLE_LEVEL[e.level])}>{e.level}</span>
+              <span className="min-w-0 text-foreground">{e.message}</span>
+            </p>
+          ))
+        )}
+      </div>
+    </div>
+  );
+}

package/src/builders/FlowBuilder/problems.tsx

@@ -0,0 +1,40 @@
+import { TriangleAlert } from '@gntik-ai/icons';
+import type { FlowValidationIssue } from './extensions';
+import type { PanelHeading } from './parts';
+
+export function FlowProblems({
+  issues,
+  onSelect,
+  titleAs: Title = 'h3',
+}: {
+  issues: readonly FlowValidationIssue[];
+  onSelect: (id: string) => void;
+  titleAs?: PanelHeading;
+}) {
+  if (!issues.length) return null;
+  return (
+    <div className="max-h-40 shrink-0 overflow-auto border-b border-border px-3 py-2">
+      <Title className="text-[12px] font-semibold text-foreground">Problems</Title>
+      <ul aria-label="Flow problems" className="text-[12px] text-foreground">
+        {issues.map((issue, i) => (
+          <li key={`${issue.code}-${issue.nodeId ?? ''}-${i}`} className="flex items-center gap-2">
+            <TriangleAlert size={14} aria-hidden className="shrink-0 text-destructive-text" />
+            {issue.nodeId ? (
+              <button
+                type="button"
+                onClick={() => onSelect(issue.nodeId!)}
+                className="text-start underline focus-visible:outline-2 focus-visible:outline-focus-ring"
+              >
+                {issue.code}: {issue.message} · {issue.nodeId}
+              </button>
+            ) : (
+              <span>
+                {issue.code}: {issue.message} (Flow)
+              </span>
+            )}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

package/src/builders/LogViewer/LogViewer.test.tsx

@@ -0,0 +1,97 @@
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { LogViewer } from './LogViewer';
+import { makeLogLines } from './fixtures';
+
+const renderedLines = () => document.querySelectorAll('[data-slot="log-line"]');
+
+describe('LogViewer', () => {
+  it('follows the bottom, stops after scrolling up more than a row and resumes on demand', async () => {
+    const user = userEvent.setup();
+    const { rerender } = render(<LogViewer lines={makeLogLines(100)} height={240} rowHeight={24} />);
+    const log = screen.getByRole('log');
+    expect(log.scrollTop).toBe(2160);
+    rerender(<LogViewer lines={makeLogLines(101)} height={240} rowHeight={24} />);
+    expect(log.scrollTop).toBe(2184);
+    log.scrollTop = 2135;
+    fireEvent.scroll(log);
+    expect(screen.getByRole('switch', { name: 'Follow' })).not.toBeChecked();
+    rerender(<LogViewer lines={makeLogLines(102)} height={240} rowHeight={24} />);
+    expect(log.scrollTop).toBe(2135);
+    expect(log).toHaveAttribute('aria-live', 'off');
+    await user.click(screen.getByRole('switch', { name: 'Follow' }));
+    expect(log.scrollTop).toBe(2208);
+    expect(log).toHaveAttribute('aria-live', 'polite');
+  });
+
+  it('can suppress event announcements while preserving the default live behavior', () => {
+    const { rerender } = render(<LogViewer lines={makeLogLines(2)} />);
+    expect(screen.getByRole('log')).toHaveAttribute('aria-live', 'polite');
+    expect(screen.queryByRole('button', { name: /^Inspect event/ })).toBeNull();
+    rerender(<LogViewer lines={makeLogLines(3)} announceLines={false} />);
+    expect(screen.getByRole('log')).toHaveAttribute('aria-live', 'off');
+    expect(screen.getByRole('switch', { name: 'Follow' })).toBeChecked();
+  });
+
+  it('offers keyboard and mouse selection independently of copying', async () => {
+    const user = userEvent.setup();
+    const lines = makeLogLines(2).map((line, index) => ({ ...line, timestamp: `12:00:0${index}.000` }));
+    const onSelectLine = vi.fn();
+    const onCopyLine = vi.fn();
+    render(
+      <LogViewer lines={lines} onSelectLine={onSelectLine} selectedLineId={lines[0]!.id} onCopyLine={onCopyLine} />,
+    );
+    const first = screen.getByRole('button', { name: 'Inspect event 12:00:00.000' });
+    expect(first).toHaveAttribute('aria-pressed', 'true');
+    const second = screen.getByRole('button', { name: 'Inspect event 12:00:01.000' });
+    expect(second).toHaveAttribute('aria-pressed', 'false');
+    await user.click(second);
+    expect(onSelectLine).toHaveBeenLastCalledWith(lines[1]);
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'Copy line 12:00:01.000' })).toHaveFocus();
+    await user.tab({ shift: true });
+    expect(second).toHaveFocus();
+    await user.keyboard('{Enter}');
+    await user.keyboard(' ');
+    expect(onSelectLine).toHaveBeenCalledTimes(3);
+    await user.click(screen.getByRole('button', { name: 'Copy line 12:00:00.000' }));
+    expect(onCopyLine).toHaveBeenCalledWith(lines[0]);
+    expect(onSelectLine).toHaveBeenCalledTimes(3);
+    await expectNoAxeViolations();
+  });
+
+  it('renders only a window of rows, pinned to the tail while following', async () => {
+    render(<LogViewer />);
+    const log = screen.getByRole('log', { name: 'Logs' });
+    expect(log).toBeInTheDocument();
+    expect(renderedLines().length).toBeLessThan(40);
+    expect(within(log).getByText('12:02:57.230')).toBeInTheDocument(); // last line (index 479)
+    await expectNoAxeViolations();
+  });
+
+  it('scrolling moves the window and turns follow off', () => {
+    render(<LogViewer lines={makeLogLines(1000)} defaultFollow={false} height={240} rowHeight={24} overscan={2} />);
+    const log = screen.getByRole('log');
+    expect(screen.getByRole('switch', { name: 'Follow' })).not.toBeChecked();
+    expect(within(log).getByText('12:00:00.000')).toBeInTheDocument();
+    log.scrollTop = 24 * 500;
+    fireEvent.scroll(log);
+    expect(within(log).queryByText('12:00:00.000')).not.toBeInTheDocument();
+    expect(renderedLines()).toHaveLength(14);
+  });
+
+  it('filters by level, highlights search matches and copies a line', async () => {
+    const user = userEvent.setup();
+    const onCopyLine = vi.fn();
+    render(<LogViewer lines={makeLogLines(20)} onCopyLine={onCopyLine} />);
+    await user.click(screen.getByRole('button', { name: /^debug/ }));
+    expect(screen.getByText('16 of 20')).toBeInTheDocument();
+    await user.type(screen.getByRole('searchbox', { name: 'Search logs' }), 'failed');
+    expect(screen.getByText('2 of 20')).toBeInTheDocument();
+    expect(document.querySelectorAll('mark')).toHaveLength(2);
+    await user.click(screen.getAllByRole('button', { name: /^Copy line/ })[0]!);
+    expect(onCopyLine).toHaveBeenCalledWith(expect.objectContaining({ level: 'error' }));
+    expect(screen.getByRole('button', { name: 'Copied' })).toBeInTheDocument();
+  });
+});

package/src/builders/LogViewer/LogViewer.tsx

@@ -0,0 +1,253 @@
+import { useEffect, useId, useMemo, useRef, useState, type ReactNode, type UIEvent } from 'react';
+import { Check, Copy, Eye, Search } from '@gntik-ai/icons';
+import { IconButton, Input, Switch, Toggle, ToggleGroup, cn } from '@gntik-ai/ui';
+import { logLines as defaultLines, type LogLevel, type LogLine } from './fixtures';
+
+export type { LogLevel, LogLine } from './fixtures';
+
+export const LOG_LEVELS: LogLevel[] = ['debug', 'info', 'warn', 'error'];
+
+const LEVEL_STYLE: Record<LogLevel, { label: string; className: string }> = {
+  debug: { label: 'DEBUG', className: 'bg-muted-foreground/16 text-foreground' },
+  info: { label: 'INFO', className: 'bg-info/15 text-foreground' },
+  warn: { label: 'WARN', className: 'bg-warning/16 text-warning-chip-text' },
+  error: { label: 'ERROR', className: 'bg-destructive/15 text-destructive-chip-text' },
+};
+
+export interface LogViewerProps {
+  /** Log lines, oldest first. */
+  lines?: LogLine[];
+  /** Accessible name of the log region and visible title. */
+  title?: string;
+  /** Height of the scrolling viewport in px. */
+  height?: number;
+  /** Fixed row height in px (the windowing math relies on it). */
+  rowHeight?: number;
+  /** Rows rendered above and below the visible window. */
+  overscan?: number;
+  /** Levels shown initially. */
+  defaultLevels?: LogLevel[];
+  /** Start pinned to the newest line. */
+  defaultFollow?: boolean;
+  /** Called after a line is copied. */
+  onCopyLine?: (line: LogLine) => void;
+  /** Enables an inspect button and mouse selection on each visible row. */
+  onSelectLine?: (line: LogLine) => void;
+  /** Selected inspect button, exposed through aria-pressed. */
+  selectedLineId?: string;
+  /** Announce appended lines while following (default true). False keeps aria-live off. */
+  announceLines?: boolean;
+  /** Heading level of the title, to fit the page outline (default h3). */
+  titleAs?: 'h2' | 'h3' | 'h4';
+  className?: string;
+}
+
+/** Wraps case-insensitive matches of `query` in <mark>. */
+function highlight(text: string, query: string): ReactNode {
+  if (!query) return text;
+  const lower = text.toLowerCase();
+  const q = query.toLowerCase();
+  const parts: ReactNode[] = [];
+  let from = 0;
+  let at = lower.indexOf(q, from);
+  while (at !== -1) {
+    if (at > from) parts.push(text.slice(from, at));
+    parts.push(
+      <mark key={at} className="rounded-sm bg-warning/30 text-foreground">
+        {text.slice(at, at + q.length)}
+      </mark>,
+    );
+    from = at + q.length;
+    at = lower.indexOf(q, from);
+  }
+  if (from < text.length) parts.push(text.slice(from));
+  return parts;
+}
+
+function lineText(line: LogLine) {
+  return `${line.timestamp} ${LEVEL_STYLE[line.level].label} ${line.source ? `[${line.source}] ` : ''}${line.message}`;
+}
+
+/**
+ * Log stream viewer. Only the visible rows are rendered (fixed row height + scroll offset),
+ * so it stays fast with thousands of lines. Level filter, search with highlighted matches,
+ * follow-tail and per-line copy.
+ */
+export function LogViewer({
+  lines = defaultLines,
+  title = 'Logs',
+  height = 360,
+  rowHeight = 24,
+  overscan = 8,
+  defaultLevels = LOG_LEVELS,
+  defaultFollow = true,
+  onCopyLine,
+  onSelectLine,
+  selectedLineId,
+  announceLines = true,
+  titleAs: TitleTag = 'h3',
+  className,
+}: LogViewerProps) {
+  const titleId = useId();
+  const viewport = useRef<HTMLDivElement>(null);
+  const copyTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const [levels, setLevels] = useState<string[]>(defaultLevels);
+  const [query, setQuery] = useState('');
+  const [follow, setFollow] = useState(defaultFollow);
+  const [scrollTop, setScrollTop] = useState(0);
+  const [copied, setCopied] = useState<string | null>(null);
+
+  const counts = useMemo(() => {
+    const c: Record<LogLevel, number> = { debug: 0, info: 0, warn: 0, error: 0 };
+    for (const l of lines) c[l.level] += 1;
+    return c;
+  }, [lines]);
+
+  const visible = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    return lines.filter(
+      (l) =>
+        levels.includes(l.level) &&
+        (!q || l.message.toLowerCase().includes(q) || (l.source ?? '').toLowerCase().includes(q)),
+    );
+  }, [lines, levels, query]);
+
+  const total = visible.length * rowHeight;
+  const maxScroll = Math.max(0, total - height);
+  // While following, the window is pinned to the end (the DOM scroll catches up in the effect).
+  const offset = follow ? maxScroll : Math.min(scrollTop, maxScroll);
+  const start = Math.max(0, Math.floor(offset / rowHeight) - overscan);
+  const end = Math.min(visible.length, Math.ceil((offset + height) / rowHeight) + overscan);
+  const rows = visible.slice(start, end);
+
+  useEffect(() => {
+    if (follow && viewport.current) viewport.current.scrollTop = maxScroll;
+  }, [follow, maxScroll]);
+
+  useEffect(() => () => clearTimeout(copyTimer.current), []);
+
+  const onScroll = (event: UIEvent<HTMLDivElement>) => {
+    const top = event.currentTarget.scrollTop;
+    setScrollTop(top);
+    if (follow && top < maxScroll - rowHeight) setFollow(false);
+  };
+
+  const copy = (line: LogLine) => {
+    void navigator.clipboard?.writeText(lineText(line)).catch(() => undefined);
+    onCopyLine?.(line);
+    setCopied(line.id);
+    clearTimeout(copyTimer.current);
+    copyTimer.current = setTimeout(() => setCopied(null), 1500);
+  };
+
+  return (
+    <section
+      aria-labelledby={titleId}
+      className={cn('flex flex-col overflow-hidden rounded-lg border border-border bg-card shadow-sm', className)}
+    >
+      <div className="flex flex-col gap-3 border-b border-border bg-secondary/35 px-3 py-2.5 lg:flex-row lg:items-center">
+        <div className="flex items-center gap-2">
+          <TitleTag id={titleId} className="text-[13px] font-semibold text-foreground">
+            {title}
+          </TitleTag>
+          <span className="font-mono text-[11px] text-muted-foreground">
+            {visible.length} of {lines.length}
+          </span>
+        </div>
+        <div className="flex flex-wrap items-center gap-2 lg:ms-auto">
+          <ToggleGroup aria-label="Log levels" size="sm" multiple value={levels} onValueChange={(v) => setLevels(v)}>
+            {LOG_LEVELS.map((lv) => (
+              <Toggle key={lv} value={lv}>
+                {lv}
+                <span className="font-mono text-[10.5px] opacity-70">{counts[lv]}</span>
+              </Toggle>
+            ))}
+          </ToggleGroup>
+          <Input
+            size="sm"
+            type="search"
+            aria-label="Search logs"
+            placeholder="Search…"
+            leadingIcon={Search}
+            value={query}
+            onValueChange={(v) => setQuery(String(v))}
+            className="w-full sm:w-48"
+          />
+          <Switch size="sm" label="Follow" checked={follow} onCheckedChange={setFollow} />
+        </div>
+      </div>
+      <div
+        ref={viewport}
+        role="log"
+        aria-label={title}
+        aria-live={announceLines && follow ? 'polite' : 'off'}
+        tabIndex={0}
+        onScroll={onScroll}
+        className="relative overflow-auto bg-background font-mono text-[12px] focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring"
+        style={{ height }}
+      >
+        {visible.length === 0 ? (
+          <p className="px-4 py-6 text-center font-sans text-[13px] text-muted-foreground">
+            No lines match the current filters.
+          </p>
+        ) : (
+          <div className="relative w-full" style={{ height: total }}>
+            {rows.map((line, i) => {
+              const lv = LEVEL_STYLE[line.level];
+              return (
+                <div
+                  key={line.id}
+                  data-slot="log-line"
+                  onClick={onSelectLine ? () => onSelectLine(line) : undefined}
+                  className="group absolute inset-x-0 flex items-center gap-2.5 px-3 hover:bg-secondary/50"
+                  style={{ top: (start + i) * rowHeight, height: rowHeight }}
+                >
+                  <span className="shrink-0 text-muted-foreground tabular-nums">{line.timestamp}</span>
+                  <span
+                    className={cn(
+                      'inline-flex h-4 w-12 shrink-0 items-center justify-center rounded text-[10px] font-semibold',
+                      lv.className,
+                    )}
+                  >
+                    {lv.label}
+                  </span>
+                  {line.source && (
+                    <span className="hidden shrink-0 text-muted-foreground sm:inline">
+                      [{highlight(line.source, query.trim())}]
+                    </span>
+                  )}
+                  <span className="min-w-0 flex-1 truncate text-foreground">
+                    {highlight(line.message, query.trim())}
+                  </span>
+                  {onSelectLine && (
+                    <IconButton
+                      size="sm"
+                      icon={Eye}
+                      label={`Inspect event ${line.timestamp}`}
+                      aria-pressed={line.id === selectedLineId}
+                      onClick={(event) => {
+                        event.stopPropagation();
+                        onSelectLine(line);
+                      }}
+                      className="size-6 shrink-0"
+                    />
+                  )}
+                  <IconButton
+                    size="sm"
+                    icon={copied === line.id ? Check : Copy}
+                    label={copied === line.id ? 'Copied' : `Copy line ${line.timestamp}`}
+                    onClick={(event) => {
+                      if (onSelectLine) event.stopPropagation();
+                      copy(line);
+                    }}
+                    className="size-6 shrink-0 opacity-0 group-hover:opacity-100 focus-visible:opacity-100"
+                  />
+                </div>
+              );
+            })}
+          </div>
+        )}
+      </div>
+    </section>
+  );
+}

package/src/builders/LogViewer/block.meta.ts

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Log viewer',
+  family: 'builders',
+  status: 'beta',
+  description:
+    'Windowed log stream (role="log"): level filter, search with highlighted matches, follow-tail and per-line copy. Renders only the visible rows.',
+  uses: ['ToggleGroup', 'Toggle', 'Input', 'Switch', 'IconButton'],
+};