@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/flow/internal/labels.ts

@@ -0,0 +1,101 @@
+// Labels (every user-visible string) and locale.
+//
+// Each component declares its strings once with `defineLabels(key, { en,
+// 'pt-BR', es })`. At render, `useLabels(definition, props.labels)` resolves:
+//   1. the component's `labels` prop (partial),
+//   2. the host catalogue given to <FlowMessagesProvider messages={{ [key]: … }}>,
+//   3. the built-in bundle for the provider locale (exact tag, then language),
+//   4. English.
+// Templates use an ICU MessageFormat subset (see messageFormat.ts); `fill`
+// formats them with the provider locale. Locale and direction come from React
+// Aria's I18nProvider, which @datatechsolutions/tympan's TympanProvider sets.
+
+import { createContext, createElement, useContext, useMemo, type ReactNode } from 'react'
+import { useLocale } from 'react-aria-components'
+import { formatMessage, type MessageValues } from './messageFormat'
+
+export interface LabelDefinition<L extends object> {
+  readonly key: string
+  readonly bundles: Readonly<Record<string, Partial<L>>> & { readonly en: L }
+}
+
+const registry = new Map<string, LabelDefinition<object>>()
+
+/** Declares a component's strings: English is complete; other locales may be partial. */
+export function defineLabels<L extends object>(key: string, bundles: { en: L } & Record<string, Partial<L>>): LabelDefinition<L> {
+  const definition: LabelDefinition<L> = Object.freeze({ key, bundles: Object.freeze({ ...bundles }) as LabelDefinition<L>['bundles'] })
+  if (!registry.has(key)) registry.set(key, definition as LabelDefinition<object>)
+  return definition
+}
+
+/**
+ * Every label definition the library ships, in definition order (one per component key). For hosts that export the
+ * built-in strings into their own translation system; values are strings or message functions, as declared.
+ */
+export function builtInLabels(): readonly LabelDefinition<object>[] {
+  return [...registry.values()]
+}
+
+/** Locales the library ships strings for. Hosts add any other through FlowMessagesProvider. */
+export const BUILT_IN_LOCALES = ['en', 'pt-BR', 'es'] as const
+
+type HostCatalogue = Record<string, Record<string, unknown>>
+
+const MessagesContext = createContext<HostCatalogue | null>(null)
+
+/** Host i18n adapter: `messages[componentKey]` overrides that component's labels. */
+export function FlowMessagesProvider({ messages, children }: { messages: HostCatalogue; children: ReactNode }) {
+  return createElement(MessagesContext.Provider, { value: messages }, children)
+}
+
+function isDefinition<L extends object>(x: L | LabelDefinition<L>): x is LabelDefinition<L> {
+  return typeof x === 'object' && x !== null && 'bundles' in x && 'key' in x
+}
+
+function stripUndefined<L extends object>(o: Partial<L> | undefined): Partial<L> {
+  const out: Partial<L> = {}
+  if (!o) return out
+  for (const [k, v] of Object.entries(o)) if (v !== undefined) (out as Record<string, unknown>)[k] = v
+  return out
+}
+
+/** Picks the bundle for a BCP 47 tag: exact, then same language, else nothing. */
+export function bundleFor<L extends object>(def: LabelDefinition<L>, locale: string): Partial<L> {
+  const exact = def.bundles[locale]
+  if (exact) return exact
+  const lang = locale.split('-')[0]!.toLowerCase()
+  const byLanguage = Object.entries(def.bundles).find(([tag]) => tag.split('-')[0]!.toLowerCase() === lang)
+  return byLanguage ? byLanguage[1] : {}
+}
+
+/** Resolves labels (see the header). Accepts a definition or a plain English object. */
+export function useLabels<L extends object>(defaults: L | LabelDefinition<L>, overrides: Partial<L> | undefined): L {
+  const { locale } = useLocale()
+  const host = useContext(MessagesContext)
+  return useMemo(() => {
+    if (!isDefinition(defaults)) return { ...defaults, ...stripUndefined(overrides) }
+    return {
+      ...defaults.bundles.en,
+      ...stripUndefined(bundleFor(defaults, locale)),
+      ...stripUndefined(host?.[defaults.key] as Partial<L> | undefined),
+      ...stripUndefined(overrides),
+    }
+  }, [defaults, overrides, locale, host])
+}
+
+/** Formats a label template (ICU subset). Pass the locale for plurals and numbers. */
+export function fill(template: string, values: MessageValues, locale?: string): string {
+  return formatMessage(template, values, locale)
+}
+
+export interface FlowLocale {
+  locale: string
+  direction: 'ltr' | 'rtl'
+  rtl: boolean
+}
+
+/** Provider locale and reading direction (React Aria I18nProvider, else the browser). */
+export function useFlowLocale(): FlowLocale {
+  const { locale, direction } = useLocale()
+  return useMemo(() => ({ locale, direction, rtl: direction === 'rtl' }), [locale, direction])
+}

package/src/flow/internal/messageFormat.ts

@@ -0,0 +1,102 @@
+// A small ICU MessageFormat subset for label templates, so hosts can pass the
+// same strings they keep in ICU catalogues:
+//   {name}                                  argument
+//   {count, number}                         Intl.NumberFormat
+//   {count, plural, =0 {none} one {# item} other {# items}}
+//   {kind, select, agent {agent} other {step}}
+// `#` inside a plural branch is the formatted number. Apostrophe quoting is not
+// supported (not needed by the library's own strings).
+
+export type MessageValues = Record<string, string | number | boolean | null | undefined>
+
+interface Cursor {
+  s: string
+  i: number
+}
+
+function readUntilBalanced(c: Cursor): string {
+  // c.i is just after an opening brace; returns the content up to its match.
+  let depth = 1
+  const start = c.i
+  while (c.i < c.s.length) {
+    const ch = c.s[c.i]
+    if (ch === '{') depth++
+    else if (ch === '}') {
+      depth--
+      if (depth === 0) {
+        const body = c.s.slice(start, c.i)
+        c.i++
+        return body
+      }
+    }
+    c.i++
+  }
+  return c.s.slice(start)
+}
+
+function parseBranches(text: string): Map<string, string> {
+  const branches = new Map<string, string>()
+  const c: Cursor = { s: text, i: 0 }
+  while (c.i < text.length) {
+    while (c.i < text.length && /\s/.test(text[c.i]!)) c.i++
+    let key = ''
+    while (c.i < text.length && text[c.i] !== '{' && !/\s/.test(text[c.i]!)) key += text[c.i++]
+    while (c.i < text.length && /\s/.test(text[c.i]!)) c.i++
+    if (text[c.i] !== '{') break
+    c.i++
+    branches.set(key, readUntilBalanced(c))
+  }
+  return branches
+}
+
+function render(template: string, values: MessageValues, locale: string | undefined, hash: string | null): string {
+  let out = ''
+  const c: Cursor = { s: template, i: 0 }
+  while (c.i < template.length) {
+    const ch = template[c.i]!
+    if (ch === '#' && hash !== null) {
+      out += hash
+      c.i++
+      continue
+    }
+    if (ch !== '{') {
+      out += ch
+      c.i++
+      continue
+    }
+    c.i++
+    const body = readUntilBalanced(c)
+    const firstComma = body.indexOf(',')
+    const name = (firstComma < 0 ? body : body.slice(0, firstComma)).trim()
+    const value = values[name]
+    if (firstComma < 0) {
+      out += value === undefined || value === null ? `{${name}}` : String(value)
+      continue
+    }
+    const rest = body.slice(firstComma + 1)
+    const secondComma = rest.indexOf(',')
+    const type = (secondComma < 0 ? rest : rest.slice(0, secondComma)).trim()
+    const arg = secondComma < 0 ? '' : rest.slice(secondComma + 1)
+    if (type === 'number') {
+      out += typeof value === 'number' ? new Intl.NumberFormat(locale).format(value) : String(value ?? '')
+    } else if (type === 'plural') {
+      const n = typeof value === 'number' ? value : Number(value)
+      const branches = parseBranches(arg)
+      const exact = branches.get(`=${n}`)
+      const category = new Intl.PluralRules(locale).select(n)
+      const chosen = exact ?? branches.get(category) ?? branches.get('other') ?? ''
+      out += render(chosen, values, locale, new Intl.NumberFormat(locale).format(n))
+    } else if (type === 'select') {
+      const branches = parseBranches(arg)
+      out += render(branches.get(String(value)) ?? branches.get('other') ?? '', values, locale, hash)
+    } else {
+      out += String(value ?? '')
+    }
+  }
+  return out
+}
+
+/** Formats an ICU-subset template with values in `locale`. */
+export function formatMessage(template: string, values: MessageValues = {}, locale?: string): string {
+  return render(template, values, locale, null)
+}

package/src/flow/internal/useControllable.ts

@@ -0,0 +1,17 @@
+import { useCallback, useRef, useState } from 'react'
+
+/** Controlled when `value` is defined, uncontrolled otherwise; `onChange` fires in both. */
+export function useControllable<T>(value: T | undefined, initial: T | (() => T), onChange?: (next: T) => void): [T, (next: T) => void] {
+  const [own, setOwn] = useState<T>(initial)
+  const controlled = value !== undefined
+  const latest = useRef(onChange)
+  latest.current = onChange
+  const set = useCallback(
+    (next: T) => {
+      if (!controlled) setOwn(next)
+      latest.current?.(next)
+    },
+    [controlled],
+  )
+  return [controlled ? (value as T) : own, set]
+}

package/src/flow/layout/autoLayout.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest'
+import { autoLayout, type LayoutNode } from './autoLayout'
+
+const node = (id: string, kind = 'code', extra: Partial<LayoutNode> = {}): LayoutNode => ({ id, kind, position: { x: 0, y: 0 }, ...extra })
+const chain = [node('A'), node('B'), node('C')]
+const links = [
+  { source: 'A', target: 'B' },
+  { source: 'B', target: 'C' },
+]
+
+describe('AutoLayout', () => {
+  it('left-right: x(A) < x(B) < x(C)', () => {
+    const out = autoLayout(chain, links, 'left-right')
+    const x = Object.fromEntries(out.map((n) => [n.id, n.position.x]))
+    expect(x.A).toBeLessThan(x.B!)
+    expect(x.B).toBeLessThan(x.C!)
+  })
+
+  it('top-down: y(A) < y(B) < y(C)', () => {
+    const out = autoLayout(chain, links, 'top-down')
+    const y = Object.fromEntries(out.map((n) => [n.id, n.position.y]))
+    expect(y.A).toBeLessThan(y.B!)
+    expect(y.B).toBeLessThan(y.C!)
+  })
+
+  it('keeps notes and grouped children where they are', () => {
+    const note = node('N', 'note', { position: { x: 7, y: 9 } })
+    const child = node('K', 'code', { position: { x: 3, y: 4 }, parentId: 'G' })
+    const out = autoLayout([...chain, note, child], links, 'top-down')
+    expect(out.find((n) => n.id === 'N')!.position).toEqual({ x: 7, y: 9 })
+    expect(out.find((n) => n.id === 'K')!.position).toEqual({ x: 3, y: 4 })
+  })
+
+  it('ignores connectors to a note when ranking', () => {
+    const note = node('N', 'note', { position: { x: 7, y: 9 } })
+    const withNote = autoLayout([...chain, note], [...links, { source: 'C', target: 'N' }], 'top-down')
+    const without = autoLayout(chain, links, 'top-down')
+    expect(withNote.slice(0, 3).map((n) => n.position)).toEqual(without.map((n) => n.position))
+  })
+
+  it('is deterministic and does not mutate its input', () => {
+    const input = structuredClone(chain)
+    const a = autoLayout(input, links, 'left-right')
+    const b = autoLayout(input, links, 'left-right')
+    expect(a).toEqual(b)
+    expect(input).toEqual(chain)
+    expect(a.map((n) => n.id)).toEqual(['A', 'B', 'C'])
+  })
+
+  it('centres nodes of different sizes on their rank line', () => {
+    const sized = [node('A', 'code', { measured: { width: 100, height: 40 } }), node('B', 'code', { measured: { width: 300, height: 120 } })]
+    const out = autoLayout(sized, [{ source: 'A', target: 'B' }], 'top-down')
+    const centreX = (i: number) => out[i]!.position.x + sized[i]!.measured!.width / 2
+    expect(centreX(0)).toBeCloseTo(centreX(1), 5)
+  })
+})

package/src/flow/layout/autoLayout.ts

@@ -0,0 +1,93 @@
+// Ranked placement of a directed graph so connectors read one way. The
+// crossing reduction and coordinates come from @dagrejs/dagre (MIT); this
+// module only chooses who takes part, feeds sizes in and reads corners out.
+// Pure: the input list is never changed.
+
+import { placeChain } from './chainLayout'
+import { Graph, layout } from '@dagrejs/dagre'
+import { sizeOf } from '../geometry/rect'
+import type { Point, RankDirection, Size } from '../model/types'
+
+export interface LayoutNode {
+  id: string
+  kind: string
+  position: Point
+  size?: Size
+  measured?: Size
+  parentId?: string
+}
+
+export interface LayoutEdge {
+  source: string
+  target: string
+}
+
+export interface AutoLayoutOptions {
+  /** Gap between ranks (design direction §2.1: --ty-space-8 = 64). */
+  rankGap?: number
+  /** Gap between nodes of one rank (--ty-space-6 = 32). */
+  siblingGap?: number
+  /** Margin around the whole layout (--ty-space-5 = 24). */
+  margin?: number
+  /** Kinds whose nodes are never moved (annotations). Default: note. */
+  fixedKinds?: readonly string[]
+  /** Size to assume when a node has neither measured nor declared size. */
+  fallbackSize?: Size
+  /**
+   * `start` (top-down only) keeps a chain on one line and puts branches after
+   * it toward the inline end, which `rtl` flips (see chainLayout.ts);
+   * `centre` (default) centres parents over their children.
+   */
+  alignment?: 'centre' | 'start'
+  rtl?: boolean
+}
+
+const RANKDIR: Record<RankDirection, 'TB' | 'LR' | 'RL'> = { 'top-down': 'TB', 'left-right': 'LR', 'right-left': 'RL' }
+
+/** Top-left corner for every node that takes part, keyed by id. */
+function placeRanked(members: readonly LayoutNode[], links: readonly LayoutEdge[], direction: RankDirection, o: AutoLayoutOptions): Map<string, Point> {
+  const g = new Graph()
+  const edgeGap = o.margin ?? 24
+  g.setGraph({
+    rankdir: RANKDIR[direction],
+    ranksep: o.rankGap ?? 64,
+    nodesep: o.siblingGap ?? 32,
+    marginx: edgeGap,
+    marginy: edgeGap,
+  })
+  g.setDefaultEdgeLabel(() => ({}))
+  const sizes = new Map(members.map((m) => [m.id, sizeOf(m, o.fallbackSize)]))
+  sizes.forEach((s, id) => g.setNode(id, { width: s.width, height: s.height }))
+  for (const { source, target } of links) if (source !== target && sizes.has(source) && sizes.has(target)) g.setEdge(source, target)
+  layout(g)
+  const corners = new Map<string, Point>()
+  sizes.forEach((s, id) => {
+    const centre = g.node(id) as { x: number; y: number } | undefined
+    if (centre) corners.set(id, { x: centre.x - s.width / 2, y: centre.y - s.height / 2 })
+  })
+  return corners
+}
+
+/** Arranges nodes in ranks. Grouped children and fixed kinds (notes) keep their positions. */
+export function autoLayout<N extends LayoutNode>(nodes: readonly N[], connectors: readonly LayoutEdge[], direction: RankDirection, options: AutoLayoutOptions = {}): N[] {
+  const staysPut = new Set(options.fixedKinds ?? ['note'])
+  const members = nodes.filter((n) => n.parentId === undefined && !staysPut.has(n.kind))
+  const corners = !members.length
+    ? new Map<string, Point>()
+    : options.alignment === 'start' && direction === 'top-down'
+      ? placeChain(new Map(members.map((m) => [m.id, sizeOf(m, options.fallbackSize)])), connectors, { rankGap: options.rankGap ?? 64, siblingGap: options.siblingGap ?? 32, margin: options.margin ?? 24, rtl: !!options.rtl })
+      : placeRanked(members, connectors, direction, options)
+  return nodes.map((n) => {
+    const corner = corners.get(n.id)
+    return corner ? { ...n, position: corner } : n
+  })
+}
+
+/**
+ * Maps the editor's direction names onto AutoLayout's. A horizontal flow reads
+ * in the text direction: right-to-left in RTL locales unless `keepLtr`.
+ */
+export function rankDirectionOf(direction: 'down' | 'right', rtl = false, keepLtr = false): RankDirection {
+  if (direction === 'down') return 'top-down'
+  return rtl && !keepLtr ? 'right-left' : 'left-right'
+}

package/src/flow/layout/chainLayout.ts

@@ -0,0 +1,66 @@
+// Chain placement for flows that read downwards: each step sits in its first
+// parent's column, a parent's later children step toward the inline end, and
+// a step that would overlap one already placed in its row moves along until
+// it fits. The main chain therefore stays on one straight line. Pure.
+
+import type { Point, Size } from '../model/types'
+
+export interface ChainOptions {
+  rankGap: number
+  siblingGap: number
+  margin: number
+  rtl?: boolean
+}
+
+/** Top-left corners by id for `sizes` (insertion order breaks ties). */
+export function placeChain(sizes: ReadonlyMap<string, Size>, links: ReadonlyArray<{ source: string; target: string }>, o: ChainOptions): Map<string, Point> {
+  const ids = [...sizes.keys()]
+  const kids = new Map<string, string[]>(ids.map((id) => [id, []]))
+  const parents = new Map<string, string[]>(ids.map((id) => [id, []]))
+  for (const { source, target } of links) {
+    if (source === target || !sizes.has(source) || !sizes.has(target)) continue
+    kids.get(source)!.push(target)
+    parents.get(target)!.push(source)
+  }
+  // Row = longest path from a start (cycles are cut by the visit guard).
+  const row = new Map<string, number>()
+  const depth = (id: string, seen: Set<string>): number => {
+    if (row.has(id)) return row.get(id)!
+    if (seen.has(id)) return 0
+    seen.add(id)
+    const d = Math.max(-1, ...parents.get(id)!.map((p) => depth(p, seen))) + 1
+    row.set(id, d)
+    return d
+  }
+  ids.forEach((id) => depth(id, new Set()))
+  const rows = Math.max(0, ...row.values()) + 1
+  const rowHeight = Math.max(0, ...[...sizes.values()].map((s) => s.height)) + o.rankGap
+  const used: Array<Array<[number, number]>> = Array.from({ length: rows }, () => [])
+  const x = new Map<string, number>()
+  const fits = (r: number, from: number, w: number) => used[r]!.every(([a, b]) => from + w + o.siblingGap <= a || from >= b + o.siblingGap)
+  let rootEnd = 0
+  for (let r = 0; r < rows; r++) {
+    for (const id of ids.filter((i) => row.get(i) === r)) {
+      const w = sizes.get(id)!.width
+      const first = parents.get(id)!.find((p) => x.has(p))
+      let want: number
+      if (first === undefined) {
+        want = rootEnd
+      } else {
+        const order = kids.get(first)!.indexOf(id)
+        want = x.get(first)! + order * (w + o.siblingGap)
+      }
+      while (!fits(r, want, w)) want += 8
+      x.set(id, want)
+      used[r]!.push([want, want + w])
+      if (first === undefined) rootEnd = want + w + o.siblingGap
+    }
+  }
+  const right = Math.max(0, ...ids.map((id) => x.get(id)! + sizes.get(id)!.width))
+  const out = new Map<string, Point>()
+  for (const id of ids) {
+    const left = o.rtl ? right - x.get(id)! - sizes.get(id)!.width : x.get(id)!
+    out.set(id, { x: left + o.margin, y: row.get(id)! * rowHeight + o.margin })
+  }
+  return out
+}

package/src/flow/model/graph.ts

@@ -0,0 +1,123 @@
+// Pure graph queries over node ids and directed pairs. Nothing here knows about
+// React, the DOM or a particular node kind.
+
+export interface DirectedPair {
+  source: string
+  target: string
+}
+
+interface Adjacency {
+  out: Map<string, string[]>
+  into: Map<string, string[]>
+}
+
+function adjacency(ids: Iterable<string>, pairs: readonly DirectedPair[]): Adjacency {
+  const out = new Map<string, string[]>()
+  const into = new Map<string, string[]>()
+  for (const id of ids) {
+    out.set(id, [])
+    into.set(id, [])
+  }
+  for (const { source, target } of pairs) {
+    if (!out.has(source) || !into.has(target)) continue
+    out.get(source)!.push(target)
+    into.get(target)!.push(source)
+  }
+  return { out, into }
+}
+
+/**
+ * Kahn ordering that keeps the given id order as the tie-break, so the result
+ * is stable. Ids left over by a cycle are appended in their original order.
+ */
+export function topologicalOrder(ids: readonly string[], pairs: readonly DirectedPair[]): string[] {
+  const { out, into } = adjacency(ids, pairs)
+  const remaining = new Map(ids.map((id) => [id, into.get(id)!.length]))
+  const rankOf = new Map(ids.map((id, i) => [id, i]))
+  const ready = ids.filter((id) => remaining.get(id) === 0)
+  const ordered: string[] = []
+  const placed = new Set<string>()
+  while (ready.length) {
+    ready.sort((a, b) => rankOf.get(a)! - rankOf.get(b)!)
+    const id = ready.shift()!
+    ordered.push(id)
+    placed.add(id)
+    for (const next of out.get(id)!) {
+      const left = remaining.get(next)! - 1
+      remaining.set(next, left)
+      if (left === 0) ready.push(next)
+    }
+  }
+  for (const id of ids) if (!placed.has(id)) ordered.push(id)
+  return ordered
+}
+
+/** Longest-path layer of each id (sources are layer 0); cycles fall back to 0. */
+export function layerIndex(ids: readonly string[], pairs: readonly DirectedPair[]): Map<string, number> {
+  const order = topologicalOrder(ids, pairs)
+  const { into } = adjacency(ids, pairs)
+  const layer = new Map<string, number>()
+  for (const id of order) {
+    let best = 0
+    for (const parent of into.get(id)!) {
+      const l = layer.get(parent)
+      if (l !== undefined) best = Math.max(best, l + 1)
+    }
+    layer.set(id, best)
+  }
+  return layer
+}
+
+export type HopDirection = 'backward' | 'forward' | 'both'
+
+/**
+ * Ids reachable from `focus` within `hops` steps. `backward` follows pairs
+ * against their direction (towards what the focus was derived from),
+ * `forward` along them. Returns a map id → distance (focus is 0).
+ */
+export function withinHops(focus: string, pairs: readonly DirectedPair[], hops: number, direction: HopDirection): Map<string, number> {
+  const forward = new Map<string, string[]>()
+  const backward = new Map<string, string[]>()
+  for (const { source, target } of pairs) {
+    if (!forward.has(source)) forward.set(source, [])
+    if (!backward.has(target)) backward.set(target, [])
+    forward.get(source)!.push(target)
+    backward.get(target)!.push(source)
+  }
+  const found = new Map<string, number>([[focus, 0]])
+  const walk = (links: Map<string, string[]>) => {
+    let frontier = [focus]
+    for (let step = 1; step <= hops && frontier.length; step++) {
+      const next: string[] = []
+      for (const id of frontier) {
+        for (const n of links.get(id) ?? []) {
+          if (found.has(n) && found.get(n)! <= step) continue
+          found.set(n, step)
+          next.push(n)
+        }
+      }
+      frontier = next
+    }
+  }
+  if (direction !== 'forward') walk(backward)
+  if (direction !== 'backward') walk(forward)
+  return found
+}
+
+/** Every id that can reach `id` (its ancestors), nearest first. */
+export function ancestorsOf(id: string, pairs: readonly DirectedPair[]): string[] {
+  const within = withinHops(id, pairs, Number.POSITIVE_INFINITY, 'backward')
+  within.delete(id)
+  return [...within.entries()].sort((a, b) => a[1] - b[1]).map(([k]) => k)
+}
+
+/** Direct predecessors and successors of `id`. */
+export function neighboursOf(id: string, pairs: readonly DirectedPair[]): { incoming: string[]; outgoing: string[] } {
+  const incoming: string[] = []
+  const outgoing: string[] = []
+  for (const p of pairs) {
+    if (p.target === id) incoming.push(p.source)
+    if (p.source === id) outgoing.push(p.target)
+  }
+  return { incoming, outgoing }
+}

package/src/flow/model/types.ts

@@ -0,0 +1,83 @@
+// Graph vocabulary shared by every canvas in this package. Positions and sizes
+// are in canvas units (1 unit = 1 CSS px at zoom 1). The screen position of a
+// canvas point p is `p * zoom + (viewport.x, viewport.y)`.
+
+export interface Point {
+  x: number
+  y: number
+}
+
+export interface Size {
+  width: number
+  height: number
+}
+
+export interface Rect extends Point, Size {}
+
+/** Pan offset (screen px) and zoom factor of a canvas. */
+export interface Viewport {
+  x: number
+  y: number
+  zoom: number
+}
+
+/** Side of a node box. `start`/`end` are the inline sides (left/right in LTR). */
+export type Side = 'start' | 'end' | 'top' | 'bottom'
+
+/** Direction used by the editor state and the command bar. */
+export type LayoutDirection = 'down' | 'right'
+
+/** Direction used by AutoLayout ('right-left' is the RTL reading of 'left-right'). */
+export type RankDirection = 'top-down' | 'left-right' | 'right-left'
+
+/** A step on a canvas. `data` belongs to the node kind. */
+export interface FlowNode<D extends Record<string, unknown> = Record<string, unknown>> {
+  id: string
+  kind: string
+  position: Point
+  data: D
+  /** Size the node declares (card width variant, note size, group frame). */
+  size?: Size
+  /** Size measured in the browser, when available. */
+  measured?: Size
+  /** Enclosing group frame; the position is then relative to that frame. */
+  parentId?: string
+  selected?: boolean
+  hidden?: boolean
+}
+
+/** A directed connection between two nodes (the fork called these edges). */
+export interface FlowConnector {
+  id: string
+  source: string
+  target: string
+  sourcePort?: string
+  targetPort?: string
+  /** Explicit branch label; otherwise derived from well-known output ports. */
+  label?: string
+  /** Branch condition carried with the connector (opaque to the canvas). */
+  condition?: unknown
+  selected?: boolean
+  hidden?: boolean
+}
+
+export interface FlowGraph {
+  nodes: FlowNode[]
+  connectors: FlowConnector[]
+  viewport: Viewport
+}
+
+/** Per-node state of the live or inspected run held by the editor state. */
+export type NodeResultStatus = 'pending' | 'running' | 'success' | 'error'
+
+export interface NodeRunResult {
+  status: NodeResultStatus
+  data?: unknown
+  error?: string
+  durationMs?: number
+}
+
+/** Status vocabulary of read-only previews and run inspection. */
+export type RunStatus = 'running' | 'completed' | 'failed' | 'skipped' | 'restored' | 'served-from-history' | 'unknown'
+
+export const ORIGIN_VIEWPORT: Viewport = Object.freeze({ x: 0, y: 0, zoom: 1 })