@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/flow/decision/DecisionNode.tsx

@@ -0,0 +1,182 @@
+// DecisionNode (backlog B-002): a model reads an input state and chooses one
+// of the declared options. Before a run the card shows what is read, how many
+// options exist and who decides (provider · model · version); after a run it
+// shows the chosen value and each option's probability as text, with a bar
+// that only repeats the number.
+
+import { useId } from 'react'
+import { Target, TriangleAlert } from 'lucide-react'
+import { defineLabels, fill, useFlowLocale, useLabels } from '../internal/labels'
+import type { FlowNode, LayoutDirection } from '../model/types'
+import { useNodeResult } from '../state/editorState'
+import { ConnectionPorts } from '../nodes/ConnectionPorts'
+import { GraphNodeCard, type CardDensity } from '../nodes/GraphNodeCard'
+import { useKindPresentation } from '../nodes/nodeChrome'
+import { NodeRunIndicator, useRunWords } from '../nodes/NodeRunIndicator'
+import { rankedOptions, type DecisionConfig, type DecisionResult } from './types'
+
+export interface DecisionNodeLabels {
+  kind: string
+  title: string
+  input: string
+  options: string
+  decidedBy: string
+  version: string
+  chosen: string
+  probabilities: string
+  probability: string
+  needsReview: string
+  notConfigured: string
+  remove: string
+}
+
+export const decisionNodeLabels = defineLabels<DecisionNodeLabels>('decisionNode', {
+  en: {
+    kind: 'decision',
+    title: 'Decision',
+    input: 'reads {ref}',
+    options: '{count, plural, =0 {no options} one {# option} other {# options}}',
+    decidedBy: 'decided by',
+    version: 'version {version}',
+    chosen: 'chosen: {value}',
+    probabilities: 'Probability of each option',
+    probability: '{label}: {percent}',
+    needsReview: 'Needs review: no option is clear enough',
+    notConfigured: 'Choose the input and at least two options.',
+    remove: 'Remove {title}',
+  },
+  'pt-BR': {
+    kind: 'decisão',
+    title: 'Decisão',
+    input: 'lê {ref}',
+    options: '{count, plural, =0 {nenhuma opção} one {# opção} other {# opções}}',
+    decidedBy: 'decidido por',
+    version: 'versão {version}',
+    chosen: 'escolha: {value}',
+    probabilities: 'Probabilidade de cada opção',
+    probability: '{label}: {percent}',
+    needsReview: 'Precisa de revisão: nenhuma opção é clara o bastante',
+    notConfigured: 'Escolha a entrada e pelo menos duas opções.',
+    remove: 'Remover {title}',
+  },
+  es: {
+    kind: 'decisión',
+    title: 'Decisión',
+    input: 'lee {ref}',
+    options: '{count, plural, =0 {ninguna opción} one {# opción} other {# opciones}}',
+    decidedBy: 'decidido por',
+    version: 'versión {version}',
+    chosen: 'elegido: {value}',
+    probabilities: 'Probabilidad de cada opción',
+    probability: '{label}: {percent}',
+    needsReview: 'Requiere revisión: ninguna opción es lo bastante clara',
+    notConfigured: 'Elige la entrada y al menos dos opciones.',
+    remove: 'Quitar {title}',
+  },
+})
+export const defaultDecisionNodeLabels = decisionNodeLabels.bundles.en
+
+/** A run result that has the decision shape. */
+export function isDecisionResult(x: unknown): x is DecisionResult {
+  return !!x && typeof x === 'object' && typeof (x as DecisionResult).value === 'string' && typeof (x as DecisionResult).probabilities === 'object'
+}
+
+export interface DecisionNodeProps {
+  id: string
+  config: DecisionConfig | null
+  /** Outcome to show; defaults to the node's run result when it has the decision shape. */
+  result?: DecisionResult
+  label?: string
+  density?: CardDensity
+  onConfigure?: (id: string) => void
+  onRemove?: (id: string) => void
+  selected?: boolean
+  locked?: boolean
+  preview?: boolean
+  direction?: LayoutDirection
+  labels?: Partial<DecisionNodeLabels>
+}
+
+export function DecisionNode(props: DecisionNodeProps) {
+  const { id, config, label, density = 'detailed', onConfigure, onRemove, selected = false, locked = false, preview = false, direction = 'right' } = props
+  const l = useLabels(decisionNodeLabels, props.labels)
+  const { locale } = useFlowLocale()
+  const listId = useId()
+  const node: FlowNode = { id, kind: 'decision', position: { x: 0, y: 0 }, data: {} }
+  const k = useKindPresentation(node, direction)
+  const run = useRunWords(id)
+  const live = useNodeResult(id)
+  const result = props.result ?? (isDecisionResult(live?.data) ? live.data : undefined)
+  const title = label ?? l.title
+  const configured = !!config && !!config.input.ref && config.options.length >= 2
+  const canEdit = !preview && !locked
+  const pct = (p: number) => new Intl.NumberFormat(locale, { style: 'percent', maximumFractionDigits: 0 }).format(p)
+  const optionLabel = (value: string) => config?.options.find((o) => o.value === value)?.label ?? value
+  const who = result ? [result.provider, result.model].filter(Boolean).join(' · ') : [config?.provider, config?.model].filter(Boolean).join(' · ')
+  const version = result?.modelVersion ?? config?.modelVersion
+  const words = [
+    result ? fill(l.chosen, { value: optionLabel(result.value) }, locale) : null,
+    result?.needsReview ? l.needsReview : null,
+    run.words,
+  ].filter((w): w is string => !!w)
+
+  const meta = configured ? (
+    <div className="ty-decision-node__meta">
+      <span className="ty-decision-node__input">{fill(l.input, { ref: config!.input.ref }, locale)}</span>
+      <span>{fill(l.options, { count: config!.options.length }, locale)}</span>
+      {who || version ? (
+        <span className="ty-decision-node__model">
+          <span className="ty-visually-hidden">{l.decidedBy} </span>
+          {who ? <code>{who}</code> : null}
+          {version ? <code>{fill(l.version, { version }, locale)}</code> : null}
+        </span>
+      ) : null}
+      {result ? (
+        <div className="ty-decision-node__result">
+          <p className="ty-decision-node__chosen">{fill(l.chosen, { value: optionLabel(result.value) }, locale)}</p>
+          {result.needsReview ? (
+            <p className="ty-decision-node__review">
+              <TriangleAlert aria-hidden="true" focusable="false" />
+              {l.needsReview}
+            </p>
+          ) : null}
+          <ul className="ty-decision-node__probabilities" aria-label={l.probabilities} id={listId}>
+            {rankedOptions(result, config!.options).map((o) => (
+              <li key={o.value} className="ty-decision-node__option" data-chosen={o.value === result.value ? 'true' : undefined}>
+                <span className="ty-decision-node__option-text">{fill(l.probability, { label: o.label, percent: o.probability === null ? '?' : pct(o.probability) }, locale)}</span>
+                <span className="ty-decision-node__bar" aria-hidden="true">
+                  <span className="ty-decision-node__bar-fill" style={{ inlineSize: `${Math.round((o.probability ?? 0) * 100)}%` }} />
+                </span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      ) : null}
+    </div>
+  ) : undefined
+
+  return (
+    <GraphNodeCard
+      kind="decision"
+      kindLabel={l.kind}
+      title={title}
+      icon={<Target />}
+      tone={k.tone}
+      width="wide"
+      density={density}
+      selected={selected}
+      locked={locked}
+      runState={run.runState}
+      problem={configured ? false : l.notConfigured}
+      stateWords={words}
+      {...(onConfigure && (canEdit || preview) ? { onActivate: () => onConfigure(id) } : {})}
+      {...(onRemove && canEdit ? { onDelete: () => onRemove(id) } : {})}
+      labels={{ remove: l.remove }}
+      meta={meta}
+      className="ty-flow-node ty-decision-node"
+    >
+      <ConnectionPorts nodeId={id} nodeLabel={title} inputs={k.inputs} outputs={k.outputs} tone={k.tone} preview={preview} />
+      <NodeRunIndicator nodeId={id} kind="decision" nodeLabel={title} />
+    </GraphNodeCard>
+  )
+}

package/src/flow/decision/decision.css

@@ -0,0 +1 @@
+/* decision group stylesheet barrel: DecisionNode rules live in nodes/flow-nodes.css. */

package/src/flow/decision/index.ts

@@ -0,0 +1,3 @@
+// @datatechsolutions/tympan/flow: decision group barrel (backlog B-002).
+export * from './types'
+export * from './DecisionNode'

package/src/flow/decision/types.ts

@@ -0,0 +1,60 @@
+// Generic decision step (backlog B-002): a model reads an input state and
+// chooses one value from a declared set of options. The run records the
+// chosen value, the probability of each option, and which provider and model
+// version decided, so an analysis can be audited and replayed.
+
+/** One allowed outcome of the decision. */
+export interface DecisionOption {
+  /** Stable value written to the output (for example "above_limit"). */
+  value: string
+  /** Human label (from the host's i18n). */
+  label: string
+  description?: string
+}
+
+/** Where the input state comes from: an upstream reference, plus an optional shape. */
+export interface DecisionInputState {
+  /** Reference to an upstream value (for example "assertion.value"). */
+  ref: string
+  /** Optional JSON-Schema-like description of the expected input. */
+  schema?: Record<string, unknown>
+}
+
+export interface DecisionConfig {
+  kind: 'decision'
+  input: DecisionInputState
+  options: DecisionOption[]
+  /** Instruction given to the model (may reference upstream values). */
+  instruction?: string
+  provider?: string
+  model?: string
+  /** Pinned model version; recorded with every result. */
+  modelVersion?: string
+  /** Name of the output variable (default "decision"). */
+  outputVariable?: string
+  /** Minimum probability for the result to count as decided; below it the step asks for review. */
+  threshold?: number
+}
+
+/** What one run of the decision produced. */
+export interface DecisionResult {
+  value: string
+  /** Probability per option value (0..1); they need not sum to exactly 1. */
+  probabilities: Record<string, number>
+  provider: string
+  model: string
+  modelVersion: string
+  /** True when the top probability is under the configured threshold. */
+  needsReview?: boolean
+}
+
+export function defaultDecisionConfig(): DecisionConfig {
+  return { kind: 'decision', input: { ref: '' }, options: [], outputVariable: 'decision' }
+}
+
+/** Options sorted by probability, highest first; unknown options last. */
+export function rankedOptions(result: DecisionResult, options: readonly DecisionOption[]): Array<DecisionOption & { probability: number | null }> {
+  return options
+    .map((o) => ({ ...o, probability: result.probabilities[o.value] ?? null }))
+    .sort((a, b) => (b.probability ?? -1) - (a.probability ?? -1))
+}

package/src/flow/dialogs/DefinitionDialogs.test.tsx

@@ -0,0 +1,177 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { TympanProvider } from '../../index'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import type { FlowGraph } from '../model/types'
+import { DefinitionExportDialog, definitionFileName, flowDefinitionText } from './DefinitionExportDialog'
+import { checkFlowDefinition, DefinitionImportDialog } from './DefinitionImportDialog'
+
+const graph: FlowGraph = {
+  nodes: [
+    { id: 'a', kind: 'start', position: { x: 0, y: 0 }, data: { label: 'Start' } },
+    { id: 'b', kind: 'code', position: { x: 200, y: 0 }, data: { label: 'Count' } },
+    { id: 'c', kind: 'end', position: { x: 400, y: 0 }, data: { label: 'End' } },
+  ],
+  connectors: [
+    { id: 'ab', source: 'a', target: 'b', condition: { operation: 'eq', left: { ref: 'x' }, right: { value: 1 } } },
+    { id: 'bc', source: 'b', target: 'c' },
+  ],
+  viewport: { x: 0, y: 0, zoom: 1 },
+}
+const flow = { name: 'Pricing', version: 2 }
+const at = () => new Date('2026-09-20T12:00:00Z')
+
+afterEach(() => vi.restoreAllMocks())
+
+describe('DefinitionExportDialog', () => {
+  it('shows node and connector counts', async () => {
+    const { baseElement } = render(<DefinitionExportDialog open onClose={() => {}} flow={flow} graph={graph} now={at} />)
+    const meta = screen.getByText('Steps').closest('div')!
+    expect(meta).toHaveTextContent('3')
+    expect(screen.getByText('Connections').closest('div')).toHaveTextContent('2')
+    await expectNoAxeViolations(baseElement)
+  })
+
+  it('truncates a long preview to the limit plus an ellipsis line', () => {
+    render(<DefinitionExportDialog open onClose={() => {}} flow={flow} graph={graph} now={at} previewLineLimit={5} />)
+    const preview = screen.getByRole('region', { name: 'Definition preview' })
+    const lines = preview.textContent!.split('\n')
+    expect(lines).toHaveLength(6)
+    expect(lines[5]).toMatch(/^… \d+ more lines$/)
+    expect(preview).toHaveAttribute('dir', 'ltr')
+  })
+
+  it('copies the full definition and announces "Copied"', async () => {
+    const writeText = vi.fn(() => Promise.resolve())
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } })
+    render(<DefinitionExportDialog open onClose={() => {}} flow={flow} graph={graph} now={at} previewLineLimit={3} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Copy' }))
+    expect(writeText).toHaveBeenCalledWith(flowDefinitionText(flow, graph, at()))
+    expect(screen.getByRole('status')).toHaveTextContent('Copied')
+  })
+
+  it('reports a copy failure instead of claiming success', async () => {
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText: () => Promise.reject(new Error('denied')) } })
+    render(<DefinitionExportDialog open onClose={() => {}} flow={flow} graph={graph} now={at} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Copy' }))
+    expect(screen.getByText(/Could not copy/)).toBeInTheDocument()
+  })
+
+  it('downloads a file named from the flow name and version', async () => {
+    const created: HTMLAnchorElement[] = []
+    const orig = document.createElement.bind(document)
+    vi.spyOn(document, 'createElement').mockImplementation((tag: string, o?: ElementCreationOptions) => {
+      const el = orig(tag, o)
+      if (tag === 'a') {
+        created.push(el as HTMLAnchorElement)
+        vi.spyOn(el as HTMLAnchorElement, 'click').mockImplementation(() => {})
+      }
+      return el
+    })
+    URL.createObjectURL = vi.fn(() => 'blob:x')
+    URL.revokeObjectURL = vi.fn()
+    render(<DefinitionExportDialog open onClose={() => {}} flow={{ name: 'Pricing', version: 2 }} graph={graph} now={at} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Download' }))
+    expect(created.at(-1)!.download).toBe('Pricing-v2.json')
+  })
+
+  it('keeps letters of any script in file names and strips forbidden characters', () => {
+    expect(definitionFileName({ name: 'تحليل: المراحل/2026', version: 1 })).toBe('تحليل-المراحل2026-v1.json')
+    expect(definitionFileName({ name: 'Análise de preços', version: 3 })).toBe('Análise-de-preços-v3.json')
+  })
+
+  it('keeps branch conditions in the exported definition', () => {
+    const parsed = JSON.parse(flowDefinitionText(flow, graph, at()))
+    expect(parsed.graph.connectors[0].condition).toEqual(graph.connectors[0]!.condition)
+    expect(parsed.exportedAt).toBe('2026-09-20T12:00:00.000Z')
+  })
+
+  it('formats counts with the provider locale and uses es strings', () => {
+    render(
+      <TympanProvider locale="es">
+        <DefinitionExportDialog open onClose={() => {}} flow={flow} graph={graph} now={at} />
+      </TympanProvider>,
+    )
+    expect(screen.getByRole('button', { name: 'Descargar' })).toBeInTheDocument()
+  })
+})
+
+function file(text: string, name = 'flow.json') {
+  return new File([text], name, { type: 'application/json' })
+}
+
+describe('DefinitionImportDialog', () => {
+  it('accepts a valid file, shows the counts and enables Import', async () => {
+    render(<DefinitionImportDialog open onClose={() => {}} onImport={() => {}} />)
+    expect(screen.getByRole('button', { name: 'Import' })).toBeDisabled()
+    const input = document.querySelector<HTMLInputElement>('input[type="file"]')!
+    await userEvent.upload(input, file(JSON.stringify({ graph })))
+    expect(await screen.findByText('3 steps and 2 connections ready to import.')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Import' })).toBeEnabled()
+  })
+
+  it('lists "invalid format" for an unparseable file and keeps Import disabled', async () => {
+    render(<DefinitionImportDialog open onClose={() => {}} onImport={() => {}} />)
+    await userEvent.upload(document.querySelector<HTMLInputElement>('input[type="file"]')!, file('{nope'))
+    expect(await screen.findByText(/Invalid format/)).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Import' })).toBeDisabled()
+  })
+
+  it('names the item index and the missing field', () => {
+    const bad = structuredClone(graph) as unknown as { nodes: Array<Record<string, unknown>> }
+    delete bad.nodes[2]!.position
+    const r = checkFlowDefinition(JSON.stringify(bad))
+    expect(r.ok).toBe(false)
+    expect(!r.ok && r.errors).toEqual(['Step 2: missing position.'])
+  })
+
+  it('reaches the file picker by keyboard and it is a real button', async () => {
+    const { baseElement } = render(<DefinitionImportDialog open onClose={() => {}} onImport={() => {}} />)
+    const picker = screen.getByRole('button', { name: 'Choose file' })
+    picker.focus()
+    expect(picker).toHaveFocus()
+    expect(screen.getByText('Drop a definition file here').closest('[role="button"]')).toBeNull()
+    await expectNoAxeViolations(baseElement)
+  })
+
+  it('imports the connector with its condition', async () => {
+    const onImport = vi.fn()
+    render(<DefinitionImportDialog open onClose={() => {}} onImport={onImport} />)
+    await userEvent.upload(document.querySelector<HTMLInputElement>('input[type="file"]')!, file(JSON.stringify(graph)))
+    await screen.findByText(/ready to import/)
+    await userEvent.click(screen.getByRole('button', { name: 'Import' }))
+    expect(onImport.mock.calls[0]![0].connectors[0].condition).toEqual(graph.connectors[0]!.condition)
+  })
+
+  it('returns to the drop zone with focus on the picker after "Choose another"', async () => {
+    render(<DefinitionImportDialog open onClose={() => {}} onImport={() => {}} />)
+    await userEvent.upload(document.querySelector<HTMLInputElement>('input[type="file"]')!, file('{}'))
+    await userEvent.click(await screen.findByRole('button', { name: 'Choose another file' }))
+    await new Promise((r) => requestAnimationFrame(() => r(null)))
+    expect(screen.getByRole('button', { name: 'Choose file' })).toHaveFocus()
+  })
+
+  it('normalises missing data, ports and viewport numbers', () => {
+    const r = checkFlowDefinition(JSON.stringify({ nodes: [{ id: 'a', kind: 'k', position: {} }], connectors: [{ id: 'c', source: 'a', target: 'a' }], viewport: {} }))
+    expect(r.ok && r.graph).toMatchObject({ nodes: [{ data: { label: '' }, position: { x: 0, y: 0 } }], connectors: [{ sourcePort: 'out', targetPort: 'in' }], viewport: { x: 0, y: 0, zoom: 1 } })
+  })
+
+  it('marks drag-over with a thicker border, not colour alone, and stops the transition under reduced motion', () => {
+    const css = cssOf('flow/dialogs/dialogs.css')
+    expect(css).toMatch(/\.ty-definition-import__zone\[data-drop-target\]\s*\{[^}]*border: 3px solid/)
+    expect(mediaBlock(css, /\(forced-colors: active\)/)).toMatch(/4px solid Highlight/)
+    expect(mediaBlock(css, /\(prefers-reduced-motion: reduce\)/)).toMatch(/transition: none/)
+  })
+
+  it('lists validation messages in pt-BR', async () => {
+    render(
+      <TympanProvider locale="pt-BR">
+        <DefinitionImportDialog open onClose={() => {}} onImport={() => {}} />
+      </TympanProvider>,
+    )
+    await userEvent.upload(document.querySelector<HTMLInputElement>('input[type="file"]')!, file('[]'))
+    expect(await screen.findByText('A definição precisa ser um objeto.')).toBeInTheDocument()
+  })
+})

package/src/flow/dialogs/DefinitionExportDialog.tsx

@@ -0,0 +1,234 @@
+// DefinitionExportDialog: shows a flow's portable definition (metadata plus
+// graph), copies the whole text or downloads it as a file.
+
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { Button, InlineNotice } from '../../index'
+import { SectionedModal } from '../internal/SectionedModal'
+import { defineLabels, fill, useFlowLocale, useLabels } from '../internal/labels'
+import type { FlowConnector, FlowNode, Viewport } from '../model/types'
+
+export interface ExportableGraph {
+  nodes: FlowNode[]
+  connectors: FlowConnector[]
+  viewport: Viewport
+}
+
+export interface FlowDefinitionMeta {
+  name: string
+  description?: string
+  version: number
+}
+
+export interface DefinitionExportDialogLabels {
+  title: string
+  description: string
+  name: string
+  version: string
+  nodes: string
+  connectors: string
+  preview: string
+  more: string
+  copy: string
+  copied: string
+  copyFailed: string
+  download: string
+}
+
+export const definitionExportDialogLabels = defineLabels<DefinitionExportDialogLabels>('DefinitionExportDialog', {
+  en: {
+    title: 'Export definition',
+    description: 'A portable copy of this flow that another project can import.',
+    name: 'Name',
+    version: 'Version',
+    nodes: 'Steps',
+    connectors: 'Connections',
+    preview: 'Definition preview',
+    more: '… {count, plural, one {# more line} other {# more lines}}',
+    copy: 'Copy',
+    copied: 'Copied',
+    copyFailed: 'Could not copy. Select the text in the preview and copy it by hand.',
+    download: 'Download',
+  },
+  'pt-BR': {
+    title: 'Exportar definição',
+    description: 'Uma cópia portátil deste fluxo, que outro projeto pode importar.',
+    name: 'Nome',
+    version: 'Versão',
+    nodes: 'Passos',
+    connectors: 'Conexões',
+    preview: 'Prévia da definição',
+    more: '… {count, plural, one {mais # linha} other {mais # linhas}}',
+    copy: 'Copiar',
+    copied: 'Copiado',
+    copyFailed: 'Não foi possível copiar. Selecione o texto da prévia e copie manualmente.',
+    download: 'Baixar',
+  },
+  es: {
+    title: 'Exportar definición',
+    description: 'Una copia portátil de este flujo que otro proyecto puede importar.',
+    name: 'Nombre',
+    version: 'Versión',
+    nodes: 'Pasos',
+    connectors: 'Conexiones',
+    preview: 'Vista previa de la definición',
+    more: '… {count, plural, one {# línea más} other {# líneas más}}',
+    copy: 'Copiar',
+    copied: 'Copiado',
+    copyFailed: 'No se pudo copiar. Selecciona el texto de la vista previa y cópialo a mano.',
+    download: 'Descargar',
+  },
+})
+export const defaultDefinitionExportDialogLabels = definitionExportDialogLabels.bundles.en
+
+/** The portable definition: metadata, export time and the graph, with stable indentation. */
+export function flowDefinitionText(flow: FlowDefinitionMeta, graph: ExportableGraph, exportedAt: Date = new Date()): string {
+  const definition = {
+    name: flow.name,
+    description: flow.description ?? '',
+    version: flow.version,
+    exportedAt: exportedAt.toISOString(),
+    graph: { nodes: graph.nodes, connectors: graph.connectors, viewport: graph.viewport },
+  }
+  return JSON.stringify(definition, null, 2)
+}
+
+/** File name from the flow name and version, without characters file systems refuse. */
+export function definitionFileName(flow: FlowDefinitionMeta): string {
+  // Letters of any script stay; only characters file systems refuse are removed.
+  const base = flow.name
+    .normalize('NFC')
+    .replace(/[<>:"/\\|?*\u0000-\u001f]+/g, '')
+    .trim()
+    .replace(/\s+/g, '-')
+    .replace(/^\.+/, '')
+  return `${base || 'flow'}-v${flow.version}.json`
+}
+
+async function copyText(text: string): Promise<boolean> {
+  try {
+    if (navigator.clipboard?.writeText) {
+      await navigator.clipboard.writeText(text)
+      return true
+    }
+  } catch {
+    // fall through to the selection copy
+  }
+  try {
+    const area = document.createElement('textarea')
+    area.value = text
+    area.setAttribute('readonly', '')
+    area.className = 'ty-visually-hidden'
+    document.body.append(area)
+    area.select()
+    const ok = typeof document.execCommand === 'function' && document.execCommand('copy')
+    area.remove()
+    return !!ok
+  } catch {
+    return false
+  }
+}
+
+export interface DefinitionExportDialogProps {
+  open: boolean
+  onClose: () => void
+  flow: FlowDefinitionMeta
+  graph: ExportableGraph
+  previewLineLimit?: number
+  /** Clock for the export time (tests). */
+  now?: () => Date
+  labels?: Partial<DefinitionExportDialogLabels>
+}
+
+const COPIED_MS = 2000
+
+export function DefinitionExportDialog({ open, onClose, flow, graph, previewLineLimit = 40, now, labels }: DefinitionExportDialogProps) {
+  const l = useLabels(definitionExportDialogLabels, labels)
+  const { locale, direction } = useFlowLocale()
+  const n = (v: number) => new Intl.NumberFormat(locale).format(v)
+  const [copyState, setCopyState] = useState<'idle' | 'copied' | 'failed'>('idle')
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const text = useMemo(() => (open ? flowDefinitionText(flow, graph, now?.() ?? new Date()) : ''), [open, flow, graph, now])
+  const lines = text.split('\n')
+  const shown = lines.slice(0, previewLineLimit)
+  const hidden = lines.length - shown.length
+
+  useEffect(() => () => {
+    if (timer.current) clearTimeout(timer.current)
+  }, [])
+  useEffect(() => {
+    if (!open) setCopyState('idle')
+  }, [open])
+
+  const copy = async () => {
+    const ok = await copyText(text)
+    setCopyState(ok ? 'copied' : 'failed')
+    if (timer.current) clearTimeout(timer.current)
+    if (ok) timer.current = setTimeout(() => setCopyState('idle'), COPIED_MS)
+  }
+  const download = () => {
+    const blob = new Blob([text], { type: 'application/json' })
+    const url = URL.createObjectURL(blob)
+    const a = document.createElement('a')
+    a.href = url
+    a.download = definitionFileName(flow)
+    a.className = 'ty-visually-hidden'
+    document.body.append(a)
+    a.click()
+    a.remove()
+    setTimeout(() => URL.revokeObjectURL(url), 0)
+  }
+
+  return (
+    <SectionedModal
+      isOpen={open}
+      onOpenChange={(o) => {
+        if (!o) onClose()
+      }}
+      title={l.title}
+      subtitle={l.description}
+      width="wide"
+      className="ty-definition-export"
+      footer={
+        <>
+          <Button variant="secondary" onPress={() => void copy()}>
+            {copyState === 'copied' ? l.copied : l.copy}
+          </Button>
+          <Button variant="primary" onPress={download}>
+            {l.download}
+          </Button>
+        </>
+      }
+    >
+      <dl className="ty-definition-export__meta" dir={direction}>
+        <div>
+          <dt>{l.name}</dt>
+          <dd>{flow.name}</dd>
+        </div>
+        <div>
+          <dt>{l.version}</dt>
+          <dd className="ty-definition-export__mono">{n(flow.version)}</dd>
+        </div>
+        <div>
+          <dt>{l.nodes}</dt>
+          <dd className="ty-definition-export__mono">{n(graph.nodes.length)}</dd>
+        </div>
+        <div>
+          <dt>{l.connectors}</dt>
+          <dd className="ty-definition-export__mono">{n(graph.connectors.length)}</dd>
+        </div>
+      </dl>
+      <pre className="ty-definition-export__preview" dir="ltr" tabIndex={0} role="region" aria-label={l.preview}>
+        {shown.join('\n')}
+        {hidden > 0 ? `\n${fill(l.more, { count: hidden }, locale)}` : ''}
+      </pre>
+      {copyState === 'failed' ? (
+        <InlineNotice tone="danger" urgency="assertive">
+          {l.copyFailed}
+        </InlineNotice>
+      ) : null}
+      <p className="ty-visually-hidden" role="status" aria-live="polite">
+        {copyState === 'copied' ? l.copied : ''}
+      </p>
+    </SectionedModal>
+  )
+}