@svgrid/enterprise 2.2.1 → 2.3.0

package/src/alerts/alert-formats.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest'
+import { rulesToConditionalFormats, toConditionalFormats } from './alert-formats'
+import type { AlertEvent, AlertRule } from './alert-types'
+
+type Row = { id: string; price: number }
+const getRowId = (r: Row) => r.id
+
+const event = (over: Partial<AlertEvent> = {}): AlertEvent => ({
+  ruleId: 'r1',
+  ruleName: 'High',
+  severity: 'warning',
+  scope: 'row',
+  triggerType: 'dataChange',
+  rowId: 'a',
+  message: 'hi',
+  actions: [{ kind: 'highlight', style: { background: '#fee2e2', color: '#991b1b' } }],
+  firedAt: 0,
+  ...over,
+})
+
+describe('toConditionalFormats', () => {
+  it('turns a highlight action into a row-matching RuleFormat', () => {
+    const formats = toConditionalFormats([event()], getRowId)
+    expect(formats).toHaveLength(1)
+    const f = formats[0]!
+    expect(f.type).toBe('rule')
+    if (f.type === 'rule') {
+      expect(f.background).toBe('#fee2e2')
+      expect(f.color).toBe('#991b1b')
+      expect(f.when({ value: 120, row: { id: 'a', price: 120 } })).toBe(true)
+      expect(f.when({ value: 80, row: { id: 'b', price: 80 } })).toBe(false)
+    }
+  })
+
+  it('scopes to the event column when no explicit columns', () => {
+    const formats = toConditionalFormats([event({ columnId: 'price' })], getRowId)
+    const f = formats[0]!
+    if (f.type === 'rule') expect(f.columns).toEqual(['price'])
+  })
+
+  it('honours explicit action columns', () => {
+    const formats = toConditionalFormats(
+      [event({ actions: [{ kind: 'badge', columns: ['price', 'id'], style: { background: '#fff' } }] })],
+      getRowId,
+    )
+    const f = formats[0]!
+    if (f.type === 'rule') expect(f.columns).toEqual(['price', 'id'])
+  })
+
+  it('ignores toast/log/flash-only events (no styling)', () => {
+    expect(toConditionalFormats([event({ actions: [{ kind: 'toast' }, { kind: 'log' }] })], getRowId)).toHaveLength(0)
+  })
+
+  it('skips events without a row id', () => {
+    expect(toConditionalFormats([event({ rowId: undefined })], getRowId)).toHaveLength(0)
+  })
+})
+
+describe('rulesToConditionalFormats', () => {
+  const rule = (over: Partial<AlertRule> = {}): AlertRule => ({
+    id: 'r1',
+    name: 'High',
+    enabled: true,
+    severity: 'warning',
+    scope: 'row',
+    predicate: { kind: 'cmp', column: 'price', op: 'greaterThan', value: 100 },
+    trigger: { type: 'dataChange' },
+    actions: [{ kind: 'highlight', style: { background: '#fee2e2' } }],
+    createdAt: 0,
+    ...over,
+  })
+
+  it('emits one live predicate-driven format per styling rule', () => {
+    const formats = rulesToConditionalFormats<Row>([rule()])
+    expect(formats).toHaveLength(1)
+    const f = formats[0]!
+    if (f.type === 'rule') {
+      expect(f.when({ value: 0, row: { id: 'a', price: 120 } })).toBe(true)
+      expect(f.when({ value: 0, row: { id: 'b', price: 80 } })).toBe(false)
+    }
+  })
+
+  it('ignores disabled rules and non-styling rules', () => {
+    expect(rulesToConditionalFormats<Row>([rule({ enabled: false })])).toHaveLength(0)
+    expect(rulesToConditionalFormats<Row>([rule({ actions: [{ kind: 'toast' }] })])).toHaveLength(0)
+  })
+})

package/src/alerts/alert-formats.ts

@@ -0,0 +1,77 @@
+/**
+ * Bridge fired alert events to the grid's conditional-formatting engine. A
+ * `badge` / `highlight` action becomes a `RuleFormat` whose `when` matches the
+ * row that fired, so `resolveCellFormat` paints it - the same painter the grid
+ * already uses for color scales and data bars. No new rendering path.
+ */
+import type { ConditionalFormat } from '@svgrid/grid/format'
+import { evaluatePredicate } from '../expressions/evaluate'
+import type { AlertEvent, AlertRule } from './alert-types'
+
+/** Which action kinds paint onto cells. */
+const STYLING_KINDS = new Set(['badge', 'highlight'])
+
+export type StylingContext<TData> = {
+  getValue?: (row: TData, columnId: string) => unknown
+  locale?: string | ReadonlyArray<string>
+}
+
+/**
+ * Persistent styling: one self-contained `RuleFormat` per enabled rule that has
+ * a `badge`/`highlight` action. The format's `when` runs the rule predicate
+ * directly, so the styling stays live as data changes (rows light up while they
+ * match and clear when they stop) without any row-id bookkeeping. One format
+ * per rule keeps the array tiny regardless of row count.
+ */
+export function rulesToConditionalFormats<TData = Record<string, unknown>>(
+  rules: ReadonlyArray<AlertRule>,
+  ctx: StylingContext<TData> = {},
+): ConditionalFormat<TData>[] {
+  const formats: ConditionalFormat<TData>[] = []
+  for (const rule of rules) {
+    if (!rule.enabled) continue
+    for (const action of rule.actions) {
+      if (!STYLING_KINDS.has(action.kind)) continue
+      const columns = action.columns ?? rule.columns
+      const style = action.style ?? {}
+      formats.push({
+        type: 'rule',
+        ...(columns ? { columns } : {}),
+        when: ({ row }: { value: unknown; row: TData }) =>
+          evaluatePredicate(rule.predicate, { row, getValue: ctx.getValue, locale: ctx.locale }),
+        ...(style.background ? { background: style.background } : {}),
+        ...(style.color ? { color: style.color } : {}),
+      })
+    }
+  }
+  return formats
+}
+
+/**
+ * Turn active alert events into conditional formats. Events whose actions only
+ * toast/log/flash contribute nothing here. Matching is by row id, so the format
+ * follows the row through sort/filter rather than a fixed index.
+ */
+export function toConditionalFormats<TData = Record<string, unknown>>(
+  events: ReadonlyArray<AlertEvent>,
+  getRowId: (row: TData) => string,
+): ConditionalFormat<TData>[] {
+  const formats: ConditionalFormat<TData>[] = []
+  for (const event of events) {
+    if (event.rowId == null) continue
+    const rowId = event.rowId
+    for (const action of event.actions) {
+      if (!STYLING_KINDS.has(action.kind)) continue
+      const columns = action.columns ?? (event.columnId ? [event.columnId] : undefined)
+      const style = action.style ?? {}
+      formats.push({
+        type: 'rule',
+        ...(columns ? { columns } : {}),
+        when: ({ row }: { value: unknown; row: TData }) => getRowId(row) === rowId,
+        ...(style.background ? { background: style.background } : {}),
+        ...(style.color ? { color: style.color } : {}),
+      })
+    }
+  }
+  return formats
+}

package/src/alerts/alert-observer.test.ts

@@ -0,0 +1,189 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createAlertEngine } from './alert-engine'
+import { createAlertObserver } from './alert-observer'
+import { createAlertScheduler } from './alert-scheduler'
+import type { AlertEvent, AlertRule } from './alert-types'
+
+type Row = { id: string; price: number; region: string; status: string }
+
+const seedRows = (over: Partial<Row>[] = []): Row[] =>
+  [
+    { id: 'a', price: 120, region: 'EU', status: 'open' },
+    { id: 'b', price: 80, region: 'US', status: 'open' },
+  ].map((r, i) => ({ ...r, ...(over[i] ?? {}) }))
+
+const getRowId = (r: Row) => r.id
+
+const dataChangeRule: AlertRule = {
+  id: 'r1',
+  name: 'High price',
+  enabled: true,
+  severity: 'warning',
+  scope: 'row',
+  predicate: { kind: 'cmp', column: 'price', op: 'greaterThan', value: 100 },
+  trigger: { type: 'dataChange' },
+  actions: [{ kind: 'toast', message: '{region} at {value}' }],
+  createdAt: 0,
+}
+
+const relativeRule: AlertRule = {
+  id: 'r2',
+  name: 'Jumped',
+  enabled: true,
+  severity: 'info',
+  scope: 'row',
+  predicate: { kind: 'const', value: true },
+  trigger: { type: 'relativeChange', expr: { kind: 'percentChange', column: 'price', op: '>', value: 5, abs: true } },
+  actions: [{ kind: 'toast', message: 'moved' }],
+  createdAt: 0,
+}
+
+function harness(rules: AlertRule[]) {
+  const engine = createAlertEngine<Row>({ rules, getRowId, now: () => 1000 })
+  const events: AlertEvent[] = []
+  const observer = createAlertObserver<Row>({
+    engine,
+    getRowId,
+    schedule: 'sync', // deterministic: runs inline
+    onEvents: (batch) => events.push(...batch),
+  })
+  return { engine, observer, events }
+}
+
+describe('engine.needsPrev / needsFullSet', () => {
+  it('needsPrev is true only when a relativeChange rule is enabled', () => {
+    expect(createAlertEngine<Row>({ rules: [dataChangeRule], getRowId }).needsPrev()).toBe(false)
+    expect(createAlertEngine<Row>({ rules: [relativeRule], getRowId }).needsPrev()).toBe(true)
+    expect(
+      createAlertEngine<Row>({ rules: [{ ...relativeRule, enabled: false }], getRowId }).needsPrev(),
+    ).toBe(false)
+  })
+
+  it('needsFullSet is true only when an aggregate-scope rule is enabled', () => {
+    expect(createAlertEngine<Row>({ rules: [dataChangeRule], getRowId }).needsFullSet()).toBe(false)
+    const agg: AlertRule = { ...dataChangeRule, id: 'agg', scope: 'aggregate' }
+    expect(createAlertEngine<Row>({ rules: [agg], getRowId }).needsFullSet()).toBe(true)
+  })
+})
+
+describe('createAlertObserver push mode', () => {
+  it('seed is silent - pre-existing matches do not fire', () => {
+    const { observer, events } = harness([dataChangeRule])
+    observer.seed(seedRows()) // 'a' already > 100
+    expect(events).toHaveLength(0)
+  })
+
+  it('pushChanged fires only for the rows it is given, once on crossing', () => {
+    const { observer, events } = harness([dataChangeRule])
+    observer.seed(seedRows([{ price: 90 }])) // 'a' starts below threshold
+    // 'b' unchanged and below threshold; push 'a' now crossing.
+    observer.pushChanged([{ id: 'a', price: 130, region: 'EU', status: 'open' }])
+    expect(events).toHaveLength(1)
+    expect(events[0]!.rowId).toBe('a')
+    // Pushing it again while it stays above must not re-fire (edge memory).
+    observer.pushChanged([{ id: 'a', price: 131, region: 'EU', status: 'open' }])
+    expect(events).toHaveLength(1)
+  })
+
+  it('does not evaluate rows that were never pushed', () => {
+    const { observer, events } = harness([dataChangeRule])
+    observer.seed(seedRows([{ price: 90 }, { price: 95 }])) // both below
+    // Only 'b' is pushed, crossing the line; 'a' is untouched.
+    observer.pushChanged([{ id: 'b', price: 150, region: 'US', status: 'open' }])
+    expect(events).toHaveLength(1)
+    expect(events[0]!.rowId).toBe('b')
+  })
+
+  it('relativeChange push sees prev via the maintained snapshot', () => {
+    const { observer, events } = harness([relativeRule])
+    const start = seedRows()
+    observer.seed(start)
+    // 'a' 120 -> 140 is +16% -> fires.
+    observer.pushChanged([{ id: 'a', price: 140, region: 'EU', status: 'open' }])
+    expect(events).toHaveLength(1)
+    expect(events[0]!.columnId).toBe('price')
+  })
+})
+
+describe('createAlertObserver scales O(changed), not O(total)', () => {
+  it('a push over a 100k seed touches only the changed rows', () => {
+    // Seed 100k rows, then push a handful. The evaluation must not re-scan the
+    // whole set - we assert by counting getRowId calls after the seed.
+    let calls = 0
+    const countingId = (r: Row) => {
+      calls++
+      return r.id
+    }
+    const engine = createAlertEngine<Row>({ rules: [dataChangeRule], getRowId: countingId, now: () => 1000 })
+    const events: AlertEvent[] = []
+    const observer = createAlertObserver<Row>({
+      engine,
+      getRowId: countingId,
+      schedule: 'sync',
+      onEvents: (b) => events.push(...b),
+    })
+
+    const big: Row[] = Array.from({ length: 100_000 }, (_, i) => ({
+      id: `r${i}`,
+      price: 10, // all below the >100 threshold
+      region: 'EU',
+      status: 'open',
+    }))
+    observer.seed(big)
+    calls = 0 // ignore the one-time seed cost; measure only the push
+
+    observer.pushChanged([{ id: 'r5', price: 130, region: 'EU', status: 'open' }])
+    expect(events).toHaveLength(1)
+    expect(events[0]!.rowId).toBe('r5')
+    // O(changed): a single changed row costs a bounded handful of id lookups,
+    // nowhere near the 100k total.
+    expect(calls).toBeLessThan(50)
+  })
+})
+
+describe('createAlertObserver scan (watch) mode', () => {
+  it('index-diffs the array and evaluates only changed rows', () => {
+    const { observer, events } = harness([dataChangeRule])
+    let data: Row[] = seedRows([{ price: 90 }]) // 'a' below
+    observer.scan(() => data) // first scan seeds silently
+    expect(events).toHaveLength(0)
+    // Immutable replace of 'a' only (Svelte-5 style).
+    data = [{ ...data[0]!, price: 130 }, data[1]!]
+    observer.scan(() => data)
+    expect(events).toHaveLength(1)
+    expect(events[0]!.rowId).toBe('a')
+  })
+})
+
+describe('createScheduler', () => {
+  it('sync mode runs immediately', () => {
+    const s = createAlertScheduler('sync')
+    const fn = vi.fn()
+    s.schedule(fn)
+    expect(fn).toHaveBeenCalledTimes(1)
+    expect(s.pending).toBe(false)
+  })
+
+  it('coalesces multiple schedules and flush runs the latest once', () => {
+    const s = createAlertScheduler('raf') // no rAF in node -> setTimeout fallback, but flush is sync
+    const a = vi.fn()
+    const b = vi.fn()
+    s.schedule(a)
+    s.schedule(b)
+    expect(s.pending).toBe(true)
+    s.flush()
+    // Latest wins - only the most recent callback runs, exactly once.
+    expect(a).not.toHaveBeenCalled()
+    expect(b).toHaveBeenCalledTimes(1)
+    expect(s.pending).toBe(false)
+  })
+
+  it('cancel drops the pending callback', () => {
+    const s = createAlertScheduler('raf')
+    const fn = vi.fn()
+    s.schedule(fn)
+    s.cancel()
+    s.flush()
+    expect(fn).not.toHaveBeenCalled()
+  })
+})

package/src/alerts/alert-observer.ts

@@ -0,0 +1,208 @@
+/**
+ * alert-observer - the observation layer that turns data movement into engine
+ * passes WITHOUT ever blocking the grid's render frame, and in O(changed) rather
+ * than O(all rows).
+ *
+ * Two ways to feed it, both funnelling through the same coalescing scheduler so
+ * at most one evaluation runs per frame, post-paint:
+ *
+ *  - PUSH  (`pushChanged`) - the consumer already knows which rows changed (a
+ *    streaming feed, a transaction, the flagship demo's own tick loop). We
+ *    evaluate ONLY those rows. Cost is O(rows that changed) at any dataset size.
+ *
+ *  - SCAN  (`scan`) - the zero-effort fallback for a plain `data = ...` where no
+ *    change signal exists. We index-diff the new array against the previous one
+ *    (Svelte 5 replaces changed rows immutably, so unchanged rows keep their
+ *    reference) and evaluate only the mismatches. Still O(all rows) to FIND the
+ *    changes, but deferred to after paint so it never lengthens the grid's frame.
+ *
+ * Cloning of previous row values is gated on `engine.needsPrev()`: for a rule set
+ * that is purely `dataChange`/aggregate (the common case), we keep NO prev
+ * snapshots at all - the biggest GC saver on large live feeds. Full-set passes
+ * (aggregate scope, or a row-count change) run on the same deferred path.
+ *
+ * Pure TypeScript - no Svelte, no DOM. The `<SvGridAlerts>` overlay wires an
+ * instance to a scheduler and an `onEvents` sink; `attachAlertEngine` wraps it
+ * for non-Svelte hosts.
+ */
+import type { AlertEngine } from './alert-engine'
+import type { AlertEvent, AlertRule } from './alert-types'
+import { createAlertScheduler, type AlertScheduler, type AlertSchedulerMode } from './alert-scheduler'
+
+export type AlertObserverOptions<TData> = {
+  engine: AlertEngine<TData>
+  getRowId: (row: TData) => string
+  /** Fired events to route to side effects (toast/log/formats). Batched per run. */
+  onEvents: (events: AlertEvent[]) => void
+  /** Scheduling strategy (default `raf`), or a custom scheduler for tests. */
+  schedule?: AlertSchedulerMode | AlertScheduler
+}
+
+export type AlertObserver<TData> = {
+  /** Silent full seed - arms edges from the current set so pre-existing matches
+   *  do not fire. Call on mount and after a rule change (in push mode). */
+  seed(rows: ReadonlyArray<TData>): void
+  /** Queue changed rows for a deferred, O(changed) evaluation (push mode). */
+  pushChanged(rows: ReadonlyArray<TData>): void
+  /** Schedule a deferred index-diff scan of the latest full row set (watch mode). */
+  scan(getRows: () => ReadonlyArray<TData>): void
+  /** Swap the rule set; edge memory is reset and a fresh seed is required. */
+  setRules(rules: AlertRule[]): void
+  /** Run any pending evaluation immediately (e.g. before a snapshot/test). */
+  flush(): void
+  /** Stop: cancel pending work and release retained snapshots. */
+  detach(): void
+}
+
+const clone = <TData>(r: TData): TData =>
+  r && typeof r === 'object' ? ({ ...(r as Record<string, unknown>) } as TData) : r
+
+export function createAlertObserver<TData = Record<string, unknown>>(
+  opts: AlertObserverOptions<TData>,
+): AlertObserver<TData> {
+  const { engine, getRowId, onEvents } = opts
+  const scheduler: AlertScheduler =
+    opts.schedule && typeof opts.schedule === 'object'
+      ? opts.schedule
+      : createAlertScheduler(opts.schedule ?? 'raf')
+
+  // Carry-over between runs. Only populated when a rule actually needs it.
+  let seeded = false
+  let prevRows: ReadonlyArray<TData> = [] // last array seen by scan (reference diff)
+  let prevSnapById = new Map<string, TData>() // cloned prev VALUES (only if needsPrev)
+  let fullById: Map<string, TData> | null = null // full current set (only if needsFullSet)
+
+  // Pending work, accumulated between scheduler runs.
+  const pushQueue = new Map<string, TData>()
+  let scanSource: (() => ReadonlyArray<TData>) | null = null
+
+  function snapshotAll(rows: ReadonlyArray<TData>) {
+    prevSnapById = new Map()
+    for (const row of rows) prevSnapById.set(getRowId(row), clone(row))
+  }
+
+  function rebuildFullIndex(rows: ReadonlyArray<TData>) {
+    fullById = new Map()
+    for (const row of rows) fullById.set(getRowId(row), row)
+  }
+
+  function seedNow(rows: ReadonlyArray<TData>) {
+    engine.reset()
+    engine.evaluate(rows) // arm dataChange/aggregate edges; discard the events
+    seeded = true
+    prevRows = rows
+    if (engine.needsPrev()) snapshotAll(rows)
+    else prevSnapById = new Map()
+    if (engine.needsFullSet()) rebuildFullIndex(rows)
+    else fullById = null
+  }
+
+  function emit(events: AlertEvent[]) {
+    if (events.length) onEvents(events)
+  }
+
+  /** PUSH run: evaluate exactly the queued rows (or the full set for aggregates). */
+  function runPush() {
+    const next = [...pushQueue.values()]
+    pushQueue.clear()
+    if (next.length === 0) return
+    const needsPrev = engine.needsPrev()
+
+    if (engine.needsFullSet()) {
+      // Aggregates need every row; evaluate over the maintained full index.
+      const rows = fullById ? [...fullById.values()] : next
+      const prev = needsPrev ? [...prevSnapById.values()] : []
+      const events = engine.evaluateTransition(prev, rows)
+      if (needsPrev) snapshotAll(rows)
+      emit(events)
+      return
+    }
+
+    const prev = needsPrev ? next.map((r) => prevSnapById.get(getRowId(r)) ?? r) : []
+    if (needsPrev) for (const r of next) prevSnapById.set(getRowId(r), clone(r))
+    emit(engine.evaluateTransition(prev, next))
+  }
+
+  /** SCAN run: index-diff the latest full array and evaluate the mismatches. */
+  function runScan(rows: ReadonlyArray<TData>) {
+    if (!seeded) {
+      seedNow(rows)
+      return
+    }
+    const needsPrev = engine.needsPrev()
+    const needsFull = engine.needsFullSet() || rows.length !== prevRows.length
+
+    if (needsFull) {
+      const prev = needsPrev ? [...prevSnapById.values()] : []
+      const events = engine.evaluateTransition(prev, rows)
+      prevRows = rows
+      if (needsPrev) snapshotAll(rows)
+      if (engine.needsFullSet()) rebuildFullIndex(rows)
+      emit(events)
+      return
+    }
+
+    // Fast path: index-aligned reference diff (unchanged rows keep their ref).
+    const changedNext: TData[] = []
+    const changedPrev: TData[] = []
+    for (let i = 0; i < rows.length; i++) {
+      if (rows[i] !== prevRows[i]) {
+        const row = rows[i] as TData
+        changedNext.push(row)
+        if (needsPrev) changedPrev.push(prevSnapById.get(getRowId(row)) ?? row)
+      }
+    }
+    prevRows = rows
+    if (changedNext.length === 0) return
+    if (needsPrev) for (const r of changedNext) prevSnapById.set(getRowId(r), clone(r))
+    emit(engine.evaluateTransition(changedPrev, changedNext))
+  }
+
+  function run() {
+    // A consumer drives one mode at a time; be defensive and honour whichever
+    // has pending work (scan takes precedence as it carries the full set).
+    if (scanSource) {
+      const src = scanSource
+      scanSource = null
+      runScan(src())
+    }
+    if (pushQueue.size) runPush()
+  }
+
+  return {
+    seed(rows) {
+      // Seeding is a one-off; do it synchronously so edges are armed before the
+      // first data event, then let subsequent evaluations defer.
+      seedNow(rows)
+    },
+    pushChanged(rows) {
+      if (fullById) for (const r of rows) fullById.set(getRowId(r), r)
+      for (const r of rows) pushQueue.set(getRowId(r), r)
+      if (!seeded) seeded = true // push implies the consumer is driving; edges arm lazily
+      scheduler.schedule(run)
+    },
+    scan(getRows) {
+      scanSource = getRows
+      scheduler.schedule(run)
+    },
+    setRules(rules) {
+      engine.setRules(rules)
+      engine.reset()
+      // Force a fresh silent seed before anything fires under the new rules.
+      seeded = false
+      prevSnapById = new Map()
+      fullById = null
+      pushQueue.clear()
+    },
+    flush() {
+      scheduler.flush()
+    },
+    detach() {
+      scheduler.cancel()
+      prevSnapById = new Map()
+      fullById = null
+      pushQueue.clear()
+      scanSource = null
+    },
+  }
+}

package/src/alerts/alert-scheduler.ts

@@ -0,0 +1,96 @@
+/**
+ * alert-scheduler - decouples WHEN alert evaluation runs from the reactive flush
+ * that mutates the grid's data. The whole performance premise of the rewrite is
+ * that alert work must never lengthen the frame that paints the grid: on a data
+ * change we schedule one evaluation for AFTER paint (`requestAnimationFrame`) and
+ * coalesce a burst of updates into a single run.
+ *
+ * Modes:
+ *  - `raf`  (default) - run once on the next animation frame, post-paint.
+ *  - `idle` - run when the browser is idle (`requestIdleCallback`), best for
+ *             non-urgent watch scans; falls back to `raf` where unavailable.
+ *  - `sync` - run immediately (deterministic tests, or hosts with no rAF).
+ *
+ * The scheduler is intentionally tiny and dependency-free: it holds at most one
+ * pending callback (the latest wins), so repeated `schedule()` calls within a
+ * frame collapse to a single run. The observer accumulates the changed-row queue
+ * itself, so "latest wins" loses no work.
+ */
+export type AlertSchedulerMode = 'raf' | 'idle' | 'sync'
+
+export type AlertScheduler = {
+  /** Queue `fn` to run once on the next tick (coalesced). */
+  schedule(fn: () => void): void
+  /** Run any pending callback now, synchronously. No-op if nothing is pending. */
+  flush(): void
+  /** Drop any pending callback without running it. */
+  cancel(): void
+  /** Whether a callback is currently queued. */
+  readonly pending: boolean
+}
+
+type RafHost = {
+  requestAnimationFrame?: (cb: () => void) => number
+  cancelAnimationFrame?: (handle: number) => void
+  requestIdleCallback?: (cb: () => void) => number
+  cancelIdleCallback?: (handle: number) => void
+}
+
+const host: RafHost = typeof globalThis !== 'undefined' ? (globalThis as RafHost) : {}
+
+function raf(cb: () => void): () => void {
+  if (typeof host.requestAnimationFrame === 'function') {
+    const id = host.requestAnimationFrame(cb)
+    return () => host.cancelAnimationFrame?.(id)
+  }
+  const id = setTimeout(cb, 16)
+  return () => clearTimeout(id)
+}
+
+function idle(cb: () => void): () => void {
+  if (typeof host.requestIdleCallback === 'function') {
+    const id = host.requestIdleCallback(cb)
+    return () => host.cancelIdleCallback?.(id)
+  }
+  return raf(cb)
+}
+
+export function createAlertScheduler(mode: AlertSchedulerMode = 'raf'): AlertScheduler {
+  let pendingFn: (() => void) | null = null
+  let cancelHandle: (() => void) | null = null
+
+  const request = mode === 'idle' ? idle : raf
+
+  const run = () => {
+    cancelHandle = null
+    const fn = pendingFn
+    pendingFn = null
+    fn?.()
+  }
+
+  return {
+    schedule(fn) {
+      if (mode === 'sync') {
+        fn()
+        return
+      }
+      // Latest wins - the observer keeps the accumulated queue, so replacing the
+      // callback never drops queued rows; it just avoids double-running a frame.
+      pendingFn = fn
+      if (!cancelHandle) cancelHandle = request(run)
+    },
+    flush() {
+      if (!pendingFn) return
+      cancelHandle?.()
+      run()
+    },
+    cancel() {
+      cancelHandle?.()
+      cancelHandle = null
+      pendingFn = null
+    },
+    get pending() {
+      return pendingFn != null
+    },
+  }
+}