@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/flow/run/RunRewindDialog.tsx

@@ -0,0 +1,197 @@
+// RunRewindDialog: the dialog around rewindPlan.ts. It asks for the last
+// step to keep and an optional reason, previews what is reused and what runs
+// again, and sends the fork request. The rules live in rewindPlan.ts.
+
+import type { ReactNode } from 'react'
+import { History, RotateCw, type LucideIcon } from 'lucide-react'
+import { Button, InlineNotice, NativeSelect, TextField } from '../../index'
+import { SectionedModal } from '../internal/SectionedModal'
+import { defineLabels, fill, useFlowLocale, useLabels } from '../internal/labels'
+import { useRewindPlan, type RewindNode } from './rewindPlan'
+import { ShortId } from './ShortId'
+
+export { splitAtCut, canCutAt, type RewindNode } from './rewindPlan'
+
+export interface RunRewindDialogLabels {
+  title: string
+  subtitle: string
+  picker: string
+  reason: string
+  reasonPlaceholder: string
+  keptHeading: string
+  rerunHeading: string
+  none: string
+  noEligible: string
+  counts: string
+  run: string
+  cancel: string
+  confirm: string
+  confirming: string
+}
+
+export const runRewindDialogLabels = defineLabels<RunRewindDialogLabels>('run-rewind-dialog', {
+  en: {
+    title: 'Rewind and run again',
+    subtitle: 'Choose the last step to keep. Every step after it runs again with the current flow.',
+    picker: 'Keep results up to',
+    reason: 'Reason (optional)',
+    reasonPlaceholder: 'What is being corrected',
+    keptHeading: '{count, plural, one {Kept from this run: # step} other {Kept from this run: # steps}}',
+    rerunHeading: '{count, plural, one {Will run again: # step} other {Will run again: # steps}}',
+    none: 'none',
+    noEligible: 'No step of this run completed, so there is nothing to keep. Start a new run instead.',
+    counts: '{kept} kept, {rerun} will run again',
+    run: 'Run',
+    cancel: 'Cancel',
+    confirm: 'Rewind',
+    confirming: 'Rewinding',
+  },
+  'pt-BR': {
+    title: 'Voltar e executar de novo',
+    subtitle: 'Escolha o último passo a manter. Todos os passos seguintes rodam de novo com o fluxo atual.',
+    picker: 'Manter resultados até',
+    reason: 'Motivo (opcional)',
+    reasonPlaceholder: 'O que está sendo corrigido',
+    keptHeading: '{count, plural, one {Mantido desta execução: # passo} other {Mantidos desta execução: # passos}}',
+    rerunHeading: '{count, plural, one {Roda de novo: # passo} other {Rodam de novo: # passos}}',
+    none: 'nenhum',
+    noEligible: 'Nenhum passo desta execução foi concluído, então não há o que manter. Inicie uma nova execução.',
+    counts: '{kept} mantidos, {rerun} rodam de novo',
+    run: 'Execução',
+    cancel: 'Cancelar',
+    confirm: 'Voltar',
+    confirming: 'Voltando',
+  },
+  es: {
+    title: 'Retroceder y ejecutar de nuevo',
+    subtitle: 'Elija el último paso que se conserva. Todos los pasos siguientes se ejecutan de nuevo con el flujo actual.',
+    picker: 'Conservar resultados hasta',
+    reason: 'Motivo (opcional)',
+    reasonPlaceholder: 'Qué se está corrigiendo',
+    keptHeading: '{count, plural, one {Conservado de esta ejecución: # paso} other {Conservados de esta ejecución: # pasos}}',
+    rerunHeading: '{count, plural, one {Se ejecuta de nuevo: # paso} other {Se ejecutan de nuevo: # pasos}}',
+    none: 'ninguno',
+    noEligible: 'Ningún paso de esta ejecución terminó, así que no hay nada que conservar. Inicie una nueva ejecución.',
+    counts: '{kept} conservados, {rerun} se ejecutan de nuevo',
+    run: 'Ejecución',
+    cancel: 'Cancelar',
+    confirm: 'Retroceder',
+    confirming: 'Retrocediendo',
+  },
+})
+export const defaultRunRewindDialogLabels: RunRewindDialogLabels = runRewindDialogLabels.bundles.en
+
+export interface RunRewindDialogProps {
+  open: boolean
+  onClose: () => void
+  runId: string
+  nodes: readonly RewindNode[]
+  initialNodeId?: string
+  onRewind: (input: { resetToNode: string; reason?: string }) => Promise<void>
+  labels?: Partial<RunRewindDialogLabels>
+}
+
+/** The two preview columns, described once and drawn the same way. */
+const PREVIEW_COLUMNS: ReadonlyArray<{ id: string; icon: LucideIcon; heading: 'keptHeading' | 'rerunHeading'; pick: 'kept' | 'rerun' }> = [
+  { id: 'ty-rewind-kept', icon: History, heading: 'keptHeading', pick: 'kept' },
+  { id: 'ty-rewind-rerun', icon: RotateCw, heading: 'rerunHeading', pick: 'rerun' },
+]
+
+function stepLines(steps: readonly RewindNode[], labelledBy: string, emptyWord: string): ReactNode {
+  if (!steps.length) return <p className="ty-run-hint">{emptyWord}</p>
+  return (
+    <ul aria-labelledby={labelledBy} className="ty-run-rewind__items">
+      {steps.map(({ nodeId, nodeKind }) => (
+        <li key={nodeId}>
+          <code className="ty-run-mono">{nodeId}</code> <span className="ty-run-row__kind">{nodeKind}</span>
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+export function RunRewindDialog(props: RunRewindDialogProps) {
+  const text = useLabels(runRewindDialogLabels, props.labels)
+  const { locale } = useFlowLocale()
+  const { eligible, draft, act, split, moveCut } = useRewindPlan(props.open, props.nodes, props.initialNodeId)
+  const sending = draft.phase.name === 'sending'
+  const nothingToKeep = eligible.length === 0
+
+  const submit = async () => {
+    const cut = draft.cut
+    if (!cut) return
+    const reason = draft.reason.trim()
+    act({ kind: 'send' })
+    try {
+      await props.onRewind(reason ? { resetToNode: cut, reason } : { resetToNode: cut })
+      act({ kind: 'sent' })
+      props.onClose()
+    } catch (problem) {
+      act({ kind: 'fail', message: problem instanceof Error ? problem.message : String(problem) })
+    }
+  }
+
+  const preview = PREVIEW_COLUMNS.map((col) => {
+    const steps = split[col.pick]
+    const Icon = col.icon
+    return (
+      <section key={col.id} className="ty-run-rewind__list" aria-labelledby={col.id}>
+        <h3 id={col.id} className="ty-run-section__title">
+          <Icon aria-hidden="true" focusable="false" className="ty-run-rewind__icon" />
+          {fill(text[col.heading], { count: steps.length }, locale)}
+        </h3>
+        {stepLines(steps, col.id, text.none)}
+      </section>
+    )
+  })
+
+  const form = (
+    <div className="ty-run-form">
+      {draft.phase.name === 'failed' ? (
+        <InlineNotice tone="danger" urgency="assertive">
+          {draft.phase.message}
+        </InlineNotice>
+      ) : null}
+      <NativeSelect label={text.picker} options={eligible.map((s) => ({ value: s.nodeId, label: `${s.nodeId}, ${s.nodeKind}` }))} value={draft.cut ?? ''} onChange={moveCut} />
+      <TextField label={text.reason} placeholder={text.reasonPlaceholder} value={draft.reason} onChange={(t) => act({ kind: 'reason', text: t })} />
+      <div className="ty-run-rewind__preview">{preview}</div>
+      <p className="ty-visually-hidden" role="status" aria-live="polite">
+        {draft.echo ? fill(text.counts, draft.echo, locale) : ''}
+      </p>
+    </div>
+  )
+
+  const footer = (
+    <div className="ty-run-dialog-footer">
+      <span className="ty-run-dialog-footer__ids">
+        <ShortId id={props.runId} label={text.run} />
+      </span>
+      <Button variant="quiet" onPress={props.onClose} disabled={sending}>
+        {text.cancel}
+      </Button>
+      {nothingToKeep ? null : (
+        <Button variant="primary" onPress={() => void submit()} disabled={!draft.cut} busy={sending} busyLabel={text.confirming}>
+          {text.confirm}
+        </Button>
+      )}
+    </div>
+  )
+
+  return (
+    <SectionedModal
+      isOpen={props.open}
+      onOpenChange={(stays) => {
+        if (!stays && !sending) props.onClose()
+      }}
+      title={text.title}
+      subtitle={text.subtitle}
+      tone="warning"
+      width="wide"
+      busy={sending}
+      className="ty-run-rewind"
+      footer={footer}
+    >
+      {nothingToKeep ? <InlineNotice tone="warning">{text.noEligible}</InlineNotice> : form}
+    </SectionedModal>
+  )
+}

package/src/flow/run/RunStatusMark.tsx

@@ -0,0 +1,79 @@
+// Status of a run or of a node inside a run: always an icon and a word
+// (design direction §2.3, §2.11); the tone only reinforces them.
+
+import { CircleCheck, CircleDashed, CircleHelp, CircleSlash, CircleX, Clock, History, LoaderCircle } from 'lucide-react'
+import type { ComponentType, SVGProps } from 'react'
+import { defineLabels, useLabels } from '../internal/labels'
+import { normaliseStatus } from './lineage'
+import type { RunWord } from './types'
+
+export type RunWordLabels = Record<RunWord, string>
+
+export const runWordLabels = defineLabels<RunWordLabels>('run-status', {
+  en: { idle: 'idle', pending: 'pending', running: 'running', completed: 'completed', failed: 'failed', skipped: 'skipped', restored: 'restored', unknown: 'unknown' },
+  'pt-BR': { idle: 'parada', pending: 'pendente', running: 'em execução', completed: 'concluída', failed: 'falhou', skipped: 'pulada', restored: 'reaproveitada', unknown: 'desconhecido' },
+  es: { idle: 'inactiva', pending: 'pendiente', running: 'en ejecución', completed: 'completada', failed: 'falló', skipped: 'omitida', restored: 'restaurada', unknown: 'desconocido' },
+})
+
+export const defaultRunWordLabels: RunWordLabels = runWordLabels.bundles.en
+
+const WORD_OF: Record<string, RunWord> = {
+  idle: 'idle',
+  pending: 'pending',
+  queued: 'pending',
+  waiting: 'pending',
+  running: 'running',
+  in_progress: 'running',
+  started: 'running',
+  streaming: 'running',
+  completed: 'completed',
+  complete: 'completed',
+  succeeded: 'completed',
+  success: 'completed',
+  done: 'completed',
+  failed: 'failed',
+  error: 'failed',
+  errored: 'failed',
+  cancelled: 'failed',
+  canceled: 'failed',
+  skipped: 'skipped',
+  restored: 'restored',
+  served_from_history: 'restored',
+}
+
+/** Engine spellings (COMPLETED, succeeded, success …) → one word of the view vocabulary. */
+export function runWordOf(status: string | undefined | null): RunWord {
+  if (!status) return 'idle'
+  return WORD_OF[normaliseStatus(status)] ?? 'unknown'
+}
+
+const ICONS: Record<RunWord, ComponentType<SVGProps<SVGSVGElement>>> = {
+  idle: CircleDashed,
+  pending: Clock,
+  running: LoaderCircle,
+  completed: CircleCheck,
+  failed: CircleX,
+  skipped: CircleSlash,
+  restored: History,
+  unknown: CircleHelp,
+}
+
+export interface RunStatusMarkProps {
+  status: string | RunWord
+  labels?: Partial<RunWordLabels>
+  /** Hide the word visually (it stays in the accessible text). */
+  quiet?: boolean
+  className?: string
+}
+
+export function RunStatusMark({ status, labels, quiet = false, className }: RunStatusMarkProps) {
+  const l = useLabels(runWordLabels, labels)
+  const word = runWordOf(status)
+  const Icon = ICONS[word]
+  return (
+    <span className={['ty-run-status', className].filter(Boolean).join(' ')} data-status={word}>
+      <Icon className="ty-run-status__icon" aria-hidden="true" focusable="false" />
+      <span className={quiet ? 'ty-visually-hidden' : 'ty-run-status__word'}>{l[word]}</span>
+    </span>
+  )
+}

package/src/flow/run/RunTimePanel.test.tsx

@@ -0,0 +1,55 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { renderWithProvider } from '../../../test/render'
+import { RunTimePanel, type RunTimeNode } from './RunTimePanel'
+
+const nodes: RunTimeNode[] = [
+  { id: 'extract', name: 'Extração', kind: 'source', state: 'succeeded', durationMs: 8000 },
+  { id: 'transform', name: 'Transformação', kind: 'transform', state: 'succeeded', durationMs: 2000 },
+  { id: 'load', name: 'Carga', kind: 'sink', state: 'waiting', durationMs: null, waitingSince: new Date(Date.now() - 5 * 60000).toISOString() },
+  { id: 'notify', name: 'Notificação', kind: 'agent', state: 'skipped', durationMs: null },
+]
+
+describe('RunTimePanel', () => {
+  it('renders the claim, one row per node and proportional bars', async () => {
+    const { container } = renderWithProvider(
+      <RunTimePanel
+        nodes={nodes}
+        claim="Extração responde por 80% do tempo desta execução."
+        events={[{ at: new Date().toISOString(), text: 'Run started' }]}
+      />,
+    )
+    expect(screen.getByText('Extração responde por 80% do tempo desta execução.')).toBeInTheDocument()
+    expect(screen.getByText('Extração')).toBeInTheDocument()
+    expect(screen.getByText('Transformação')).toBeInTheDocument()
+    // Waiting row: word, hatched bar, no fill share.
+    const waitingRow = container.querySelector('.ty-run-time__row[data-state="waiting"]')!
+    expect(waitingRow).toHaveAttribute('data-waiting', '')
+    expect(waitingRow.querySelector('.ty-run-time__fill')).toHaveAttribute('data-hatched', '')
+    expect(waitingRow.querySelector<HTMLElement>('.ty-run-time__fill')!.style.inlineSize).toBe('0%')
+    // Reported rows split the total: 8000/10000 -> 80%, 2000/10000 -> 20% (floored at 2%).
+    const fills = [...container.querySelectorAll<HTMLElement>('.ty-run-time__row[data-state="succeeded"] .ty-run-time__fill')]
+    expect(fills.map((f) => f.style.inlineSize)).toEqual(['80%', '20%'])
+    expect(fills.every((f) => !f.hasAttribute('data-hatched'))).toBe(true)
+    // The bar is labelled for assistive tech; the visible duration text is present too.
+    expect(screen.getByLabelText(/, 80% of the run time/)).toBeInTheDocument()
+    expect(screen.getByText('Event log')).toBeInTheDocument()
+    expect(screen.getByText('Run started')).toBeInTheDocument()
+    await expectNoAxeViolations(container)
+  })
+
+  it('renders without claim and without events, and marks unreported durations', async () => {
+    const { container } = renderWithProvider(<RunTimePanel nodes={[{ id: 'x', name: 'X', state: 'failed', durationMs: null }]} />)
+    expect(container.querySelector('.ty-run-time__claim')).toBeNull()
+    expect(container.querySelector('.ty-run-time__events')).toBeNull()
+    expect(screen.getByText('not reported')).toBeInTheDocument()
+    await expectNoAxeViolations(container)
+  })
+
+  it('bare render (no provider) still resolves English labels', () => {
+    render(<RunTimePanel nodes={[{ id: 'a', name: 'A', state: 'running', durationMs: 500 }]} />)
+    expect(screen.getByText('Where the time went')).toBeInTheDocument()
+    expect(screen.getByText('running')).toBeInTheDocument()
+  })
+})

package/src/flow/run/RunTimePanel.tsx

@@ -0,0 +1,143 @@
+// RunTimePanel: "para onde foi o tempo" — where the time of a run went. An
+// optional data-derived claim line, then one row per node: state glyph and
+// word, node name, duration and a proportional bar of the total run time.
+// Rows that are still waiting draw a hatched bar instead of a fill, so an
+// unfinished run reads differently from a fast one. Status is always an icon
+// plus a word (design direction §2.3); the bar reinforces, never carries.
+
+import { useId, type CSSProperties } from 'react'
+import { defineLabels, fill, useFlowLocale, useLabels } from '../internal/labels'
+import { formatDuration, formatRelative } from '../internal/format'
+import type { RunWord } from '../run/types'
+import { RunStatusMark } from './RunStatusMark'
+
+export type RunTimeNodeState = 'running' | 'waiting' | 'succeeded' | 'failed' | 'skipped'
+
+export interface RunTimeNode {
+  id: string
+  name: string
+  /** Node kind (kept for hosts that tint or link per kind; not rendered). */
+  kind?: string
+  state: RunTimeNodeState
+  /** Wall time the node took; null when not reported (a still-waiting row). */
+  durationMs: number | null
+  /** ISO timestamp since when the node has been waiting (waiting rows). */
+  waitingSince?: string | null
+}
+
+export interface RunTimeEvent {
+  /** ISO timestamp of the event. */
+  at: string
+  text: string
+}
+
+export interface RunTimePanelLabels {
+  /** Accessible name of the panel landmark. */
+  title: string
+  /** Word for a still-waiting row (replaces the pending word of the status mark). */
+  waiting: string
+  notReported: string
+  /** Heading of the optional event log. */
+  events: string
+  /** Accessible text of a proportional bar: "{node}: {duration}, {percent}% of the run time". */
+  bar: string
+}
+
+export const runTimePanelLabels = defineLabels<RunTimePanelLabels>('run-time-panel', {
+  en: {
+    title: 'Where the time went',
+    waiting: 'waiting',
+    notReported: 'not reported',
+    events: 'Event log',
+    bar: '{node}: {duration}, {percent}% of the run time',
+  },
+  'pt-BR': {
+    title: 'Para onde foi o tempo',
+    waiting: 'aguardando',
+    notReported: 'não informado',
+    events: 'Registro de eventos',
+    bar: '{node}: {duration}, {percent}% do tempo de execução',
+  },
+  es: {
+    title: 'Adónde fue el tiempo',
+    waiting: 'en espera',
+    notReported: 'no informado',
+    events: 'Registro de eventos',
+    bar: '{node}: {duration}, {percent}% del tiempo de ejecución',
+  },
+})
+
+const WORD_OF: Record<RunTimeNodeState, RunWord> = {
+  running: 'running',
+  waiting: 'pending',
+  succeeded: 'completed',
+  failed: 'failed',
+  skipped: 'skipped',
+}
+
+export interface RunTimePanelProps {
+  nodes: RunTimeNode[]
+  /** The data-derived assertion sentence ("Extrção levou 80% do tempo"). */
+  claim?: string
+  /** Optional event log of the run, newest last. */
+  events?: RunTimeEvent[]
+  labels?: Partial<RunTimePanelLabels>
+  className?: string
+}
+
+export function RunTimePanel({ nodes, claim, events, labels, className }: RunTimePanelProps) {
+  const l = useLabels(runTimePanelLabels, labels)
+  const { locale } = useFlowLocale()
+  const titleId = useId()
+  const total = nodes.reduce((sum, node) => sum + (node.durationMs ?? 0), 0)
+  return (
+    <section className={['ty-run-time', className].filter(Boolean).join(' ')} aria-labelledby={claim ? undefined : titleId}>
+      <h3 className="ty-run-time__title" id={titleId}>
+        {l.title}
+      </h3>
+      {claim ? (
+        <p className="ty-run-time__claim">
+          {claim}
+        </p>
+      ) : null}
+      <ul className="ty-run-time__rows">
+        {nodes.map((node) => {
+          const waiting = node.state === 'waiting'
+          const duration = node.durationMs !== null && node.durationMs !== undefined ? formatDuration(node.durationMs, locale) : null
+          const durationText = waiting ? (node.waitingSince ? formatRelative(node.waitingSince, locale) : l.waiting) : (duration ?? l.notReported)
+          const percent = total > 0 && node.durationMs != null ? Math.max(2, Math.round((node.durationMs / total) * 100)) : 0
+          const barStyle = { inlineSize: `${percent}%` } as CSSProperties
+          return (
+            <li key={node.id} className="ty-run-time__row" data-state={node.state} data-waiting={waiting ? '' : undefined}>
+              <RunStatusMark status={WORD_OF[node.state]} labels={{ pending: l.waiting }} className="ty-run-time__state" />
+              <span className="ty-run-time__name">{node.name}</span>
+              <span className="ty-run-time__duration">{durationText}</span>
+              <span
+                className="ty-run-time__bar"
+                role="img"
+                aria-label={fill(l.bar, { node: node.name, duration: duration ?? durationText, percent }, locale)}
+              >
+                <span className="ty-run-time__fill" data-hatched={waiting ? '' : undefined} style={barStyle} />
+              </span>
+            </li>
+          )
+        })}
+      </ul>
+      {events?.length ? (
+        <div className="ty-run-time__events">
+          <h4 className="ty-run-time__events-title">{l.events}</h4>
+          <ol className="ty-run-time__event-list">
+            {events.map((event, i) => (
+              <li key={i} className="ty-run-time__event">
+                <time className="ty-run-time__event-time" dateTime={event.at}>
+                  {formatRelative(event.at, locale)}
+                </time>
+                <span className="ty-run-time__event-text">{event.text}</span>
+              </li>
+            ))}
+          </ol>
+        </div>
+      ) : null}
+    </section>
+  )
+}

package/src/flow/run/RunViews.tsx

@@ -0,0 +1,170 @@
+// RunViewModes: RunPreviewPanel (compact, floating) and RunDrawer (full,
+// docked) as two modes of one feature. The selected run, the selected node and
+// the drawer tab live here, so switching mode keeps them.
+
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { useMediaQuery } from '../../index'
+import { defineLabels, useLabels } from '../internal/labels'
+import { useControllable } from '../internal/useControllable'
+import { useFlowEditorState } from '../state/editorState'
+import { RunDrawer, type RunDrawerLabels, type RunDrawerTab } from './RunDrawer'
+import { RunPreviewPanel, type RunPreviewPanelLabels } from './RunPreviewPanel'
+import type { RunWordLabels } from './RunStatusMark'
+import { useTransition } from './runData'
+import type { LoadRuns } from './types'
+
+export type RunViewMode = 'panel' | 'drawer'
+
+export interface RunViewState {
+  mode: RunViewMode
+  open: boolean
+}
+
+export interface PreferredRunModeStore {
+  get(): RunViewMode | null
+  set(mode: RunViewMode): void
+}
+
+export interface RunViewsLabels {
+  nowPanel: string
+  nowDrawer: string
+}
+
+export const runViewsLabels = defineLabels<RunViewsLabels>('run-views', {
+  en: { nowPanel: 'Showing the compact run view', nowDrawer: 'Showing the full run details' },
+  'pt-BR': { nowPanel: 'Mostrando a visão compacta da execução', nowDrawer: 'Mostrando os detalhes completos da execução' },
+  es: { nowPanel: 'Mostrando la vista compacta de la ejecución', nowDrawer: 'Mostrando los detalles completos de la ejecución' },
+})
+export const defaultRunViewsLabels: RunViewsLabels = runViewsLabels.bundles.en
+
+export interface RunViewsProps {
+  flowId: string
+  loadRuns: LoadRuns
+  runView?: RunViewState
+  defaultRunView?: RunViewState
+  onRunViewChange?: (next: RunViewState) => void
+  /** Open the current mode when a run starts. */
+  openOnRun?: boolean
+  preferredModeStore?: PreferredRunModeStore
+  labels?: Partial<RunViewsLabels> & { panel?: Partial<RunPreviewPanelLabels>; drawer?: Partial<RunDrawerLabels> }
+  statusLabels?: Partial<RunWordLabels>
+  /** Element focus returns to when a view closes (the run details button). */
+  opener?: HTMLElement | null
+  /** Engine status of the current run; derived from node results when absent. */
+  runStatus?: string
+}
+
+const CLOSED: RunViewState = { mode: 'drawer', open: false }
+
+export function RunViews(props: RunViewsProps) {
+  const { flowId, loadRuns, openOnRun = false, preferredModeStore, labels, statusLabels, opener } = props
+  const l = useLabels(runViewsLabels, labels)
+  const wide = useMediaQuery('(min-width: 1024px)', true)
+  const [view, setView] = useControllable<RunViewState>(props.runView, props.defaultRunView ?? CLOSED, props.onRunViewChange)
+  const isRunning = useFlowEditorState((s) => s.isRunning)
+  const results = useFlowEditorState((s) => s.nodeResults)
+  const [runId, setRunId] = useState<string | null>(null)
+  const [nodeId, setNodeId] = useState<string | null>(null)
+  const [tab, setTab] = useState<RunDrawerTab>('live')
+  const [announcement, setAnnouncement] = useState('')
+  const root = useRef<HTMLDivElement>(null)
+  const focusSwitch = useRef(false)
+  const preferenceApplied = useRef(false)
+
+  // First opening follows the person's remembered mode.
+  useTransition(view.open, false, true, () => {
+    if (preferenceApplied.current || !preferredModeStore) return
+    preferenceApplied.current = true
+    const remembered = preferredModeStore.get()
+    if (remembered && remembered !== view.mode) setView({ mode: remembered, open: true })
+  })
+
+  useTransition(isRunning, false, true, () => {
+    if (openOnRun && !view.open) setView({ ...view, open: true })
+  })
+
+  // A failure always opens the drawer on the failing node (design direction §3.10).
+  const failing = Object.entries(results).find(([, r]) => r.status === 'error')?.[0] ?? null
+  const seenFailure = useRef<string | null>(null)
+  useEffect(() => {
+    if (!failing || failing === seenFailure.current) {
+      if (!failing) seenFailure.current = null
+      return
+    }
+    seenFailure.current = failing
+    setRunId(null)
+    setTab('live')
+    setNodeId(failing)
+    setView({ mode: 'drawer', open: true })
+    // setView identity changes per render; the failing id is the trigger.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [failing])
+
+  const switchTo = useCallback(
+    (mode: RunViewMode) => {
+      focusSwitch.current = true
+      if (mode === 'drawer') setTab(runId ? 'history' : 'live')
+      preferredModeStore?.set(mode)
+      setAnnouncement(mode === 'panel' ? l.nowPanel : l.nowDrawer)
+      setView({ mode, open: true })
+    },
+    [preferredModeStore, l, setView, runId],
+  )
+
+  useLayoutEffect(() => {
+    if (!focusSwitch.current) return
+    focusSwitch.current = false
+    root.current?.querySelector<HTMLElement>('.ty-run-switch')?.focus()
+  })
+
+  const close = () => setView({ ...view, open: false })
+  const mode: RunViewMode = wide ? view.mode : 'drawer'
+  const runStatus = props.runStatus ?? (isRunning ? 'running' : failing ? 'failed' : Object.keys(results).length ? 'completed' : 'idle')
+
+  return (
+    <div ref={root} className="ty-run-views" data-mode={view.open ? mode : 'closed'}>
+      <p className="ty-visually-hidden" role="status" aria-live="polite">
+        {announcement}
+      </p>
+      {view.open && mode === 'panel' ? (
+        <RunPreviewPanel
+          open
+          onClose={close}
+          flowId={flowId}
+          loadRuns={loadRuns}
+          labels={labels?.panel}
+          statusLabels={statusLabels}
+          selectedRunId={runId}
+          onSelectedRunChange={setRunId}
+          selectedNodeId={nodeId}
+          onSelectedNodeChange={setNodeId}
+          onExpand={() => switchTo('drawer')}
+          returnFocusTo={opener ?? null}
+        />
+      ) : null}
+      {view.open && mode === 'drawer' ? (
+        <RunDrawer
+          open
+          onClose={close}
+          flowId={flowId}
+          isRunning={isRunning}
+          runStatus={runStatus}
+          loadRuns={loadRuns}
+          labels={labels?.drawer}
+          statusLabels={statusLabels}
+          tab={tab}
+          onTabChange={setTab}
+          selectedRunId={runId}
+          onSelectedRunChange={(id) => {
+            setRunId(id)
+            if (id) setTab('history')
+          }}
+          selectedNodeId={nodeId}
+          onSelectedNodeChange={setNodeId}
+          {...(wide ? { onCompact: () => switchTo('panel') } : {})}
+          returnFocusTo={opener ?? null}
+        />
+      ) : null}
+    </div>
+  )
+}

package/src/flow/run/ShortId.tsx

@@ -0,0 +1,15 @@
+// A long identifier shown as a short prefix, with the full value kept in the
+// accessible text and the title (never cut for assistive technology).
+
+export function ShortId({ id, label, visible = 8 }: { id: string; label?: string; visible?: number }) {
+  const short = id.length > visible ? id.slice(0, visible) : id
+  return (
+    <span className="ty-run-shortid" title={id}>
+      {label ? <span className="ty-run-shortid__label">{label} </span> : null}
+      <code className="ty-run-mono" aria-hidden="true">
+        {short}
+      </code>
+      <span className="ty-visually-hidden">{id}</span>
+    </span>
+  )
+}