@fayz-ai/core 0.9.0 → 0.10.0

package/src/data/refresh.ts

@@ -1,115 +0,0 @@
-import * as React from 'react'
-import { eventBus } from '../events'
-import { globalCache } from '../lib/cache'
-import { getActiveTenantId } from '../tenant'
-
-// ---------------------------------------------------------------------------
-// Data refresh bus — "something wrote; whoever is showing it should reload".
-//
-// A write that happens OUTSIDE the list showing it (the assistant creating an
-// appointment, a webhook, another tab) used to leave the screen stale until the
-// user reloaded by hand. Providers already invalidate their own read cache on
-// create/update/remove, but a mounted list holds its rows in a store — nothing
-// told it to fetch again.
-//
-// This is the missing half: one broadcast, every surface that renders the
-// affected data listens. Deliberately coarse — a table name, not a row diff.
-// Refetching a page of rows is cheap; a stale screen after "criei o
-// agendamento" is not.
-// ---------------------------------------------------------------------------
-
-export const DATA_CHANGED_EVENT = 'data:changed'
-
-export interface DataChangedPayload {
-  /** Physical table the write touched, when the writer knows it. */
-  table?: string
-  /** Registered entity key (deriveEntityKey), when the writer knows it. */
-  entityKey?: string
-  /** Archetype the record belongs to (`person:client`), when known. */
-  archetype?: string
-  op?: 'create' | 'update' | 'delete' | 'unknown'
-  /** Affected record id, when known. */
-  id?: string
-  /** What caused the write — lets a surface ignore its own UI writes. */
-  source?: 'agent' | 'ui' | 'remote'
-}
-
-/** What a subscriber renders. Any field left out matches everything. */
-export interface DataChangedMatch {
-  table?: string
-  entityKey?: string
-  archetype?: string
-}
-
-/**
- * A write with NO table/entityKey is a write we could not attribute (a plugin
- * tool, an RPC). Subscribers still refresh for it: a redundant refetch costs a
- * request, a missed one costs the user's trust in what the screen shows.
- */
-export function matchesDataChange(match: DataChangedMatch, payload: DataChangedPayload): boolean {
-  const attributed = payload.table ?? payload.entityKey ?? payload.archetype
-  if (!attributed) return true
-  if (match.table && payload.table && match.table === payload.table) return true
-  if (match.entityKey && payload.entityKey && match.entityKey === payload.entityKey) return true
-  if (match.archetype && payload.archetype && match.archetype === payload.archetype) return true
-  // A subscriber that declared nothing listens to everything.
-  return !match.table && !match.entityKey && !match.archetype
-}
-
-// One agent turn can write twice (create + link). Coalesce so the lists behind
-// it fetch once, after the turn settles, instead of once per call.
-let pending: DataChangedPayload[] = []
-let flushTimer: ReturnType<typeof setTimeout> | null = null
-
-function flush(): void {
-  const batch = pending
-  pending = []
-  flushTimer = null
-  for (const payload of batch) eventBus.emit(DATA_CHANGED_EVENT, payload)
-}
-
-/**
- * Announce a write. Invalidates the provider read cache for the affected table
- * (an unattributed write clears it wholesale — a stale hit would defeat the
- * refetch it just triggered) and broadcasts to mounted surfaces.
- */
-export function emitDataChanged(payload: DataChangedPayload = {}): void {
-  if (payload.table) {
-    const tenant = getActiveTenantId() ?? '_'
-    // The base table and its read-model view are the SAME data under two cache
-    // namespaces (appointments / v_appointments). Invalidating only the one the
-    // writer names leaves the other serving a snapshot that predates the write
-    // — which is how the assistant kept reporting an empty agenda after a
-    // booking was created on the agenda screen.
-    const sibling = payload.table.startsWith('v_')
-      ? payload.table.slice(2)
-      : `v_${payload.table}`
-    globalCache.invalidate(`${tenant}:${payload.table}`)
-    globalCache.invalidate(`${tenant}:${sibling}`)
-  } else {
-    globalCache.clear()
-  }
-  pending.push({ op: 'unknown', source: 'agent', ...payload })
-  if (flushTimer) return
-  flushTimer = setTimeout(flush, 120)
-}
-
-/** Subscribe for the lifetime of the component. The latest handler always runs. */
-export function useDataChanged(
-  match: DataChangedMatch,
-  handler: (payload: DataChangedPayload) => void,
-  deps: React.DependencyList = [],
-): void {
-  const handlerRef = React.useRef(handler)
-  handlerRef.current = handler
-  const { table, entityKey, archetype } = match
-
-  React.useEffect(
-    () =>
-      eventBus.on<DataChangedPayload>(DATA_CHANGED_EVENT, (payload) => {
-        if (matchesDataChange({ table, entityKey, archetype }, payload)) handlerRef.current(payload)
-      }),
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [table, entityKey, archetype, ...deps],
-  )
-}

package/src/data/resolve.ts

@@ -1,126 +0,0 @@
-import type { EntityDef } from '../types/crud'
-import type { BackendRef } from '../manifest'
-import type { DataProvider } from './types'
-import { getSupabaseClientOptional } from './supabase'
-import { createSupabaseProvider } from './supabase'
-import { createArchetypeProvider } from './archetype'
-import { createMockProvider } from './mock'
-import { createFayzApiProvider, type FayzApiProviderConfig } from './platform-api'
-import { withCache } from './cached'
-import { getActiveTenantId } from '../tenant'
-
-/**
- * Resolve the best data provider for an EntityDef.
- * Supabase → Archetype → Mock (in order of preference).
- *
- * Reusable by createCrudPage, PluginRegistryManager, or any component
- * that needs a DataProvider from an EntityDef.
- */
-export interface ResolveDataProviderOptions {
-  backend?: BackendRef
-  fayzApi?: Omit<FayzApiProviderConfig, 'entityKey' | 'table'>
-  /**
-   * Read through the shared TTL cache (default true).
-   *
-   * Callers that must observe writes made by ANOTHER surface pass false: the
-   * cache is only invalidated by writes that go through it, so a record created
-   * on the agenda screen stays invisible to the assistant for the rest of the
-   * TTL — which is how "o que tem na agenda hoje?" answered "nada" over a
-   * booking made seconds earlier.
-   */
-  cache?: boolean
-  customProviders?: Record<string, <T extends { id: string }>(entityDef: EntityDef<T>, mockData?: T[]) => DataProvider<T>>
-}
-
-export function resolveDataProvider<T extends { id: string }>(
-  entityDef: EntityDef<T>,
-  mockData?: T[],
-  options: ResolveDataProviderOptions = {},
-): DataProvider<T> {
-  const backend = options.backend
-
-  if (backend?.provider === 'mock') {
-    return createMockProvider(entityDef, mockData)
-  }
-
-  if (backend?.provider === 'fayz-api') {
-    const table = entityDef.data?.table ?? entityDef.name
-    return createFayzApiProvider<T>(table, {
-      ...options.fayzApi,
-      baseUrl: options.fayzApi?.baseUrl ?? backend.url,
-      projectId: options.fayzApi?.projectId ?? backend.projectRef,
-      entityKey: entityDef.name ?? table,
-      table,
-      schema: options.fayzApi?.schema ?? entityDef.data?.schema,
-      idColumn: options.fayzApi?.idColumn ?? entityDef.data?.columnMap?.id,
-      searchColumns: options.fayzApi?.searchColumns ?? entityDef.data?.searchColumns ?? entityDef.fields
-        .filter((field) => field.searchable)
-        .map((field) => field.key),
-      tenantIdColumn: entityDef.data?.tenantScoped === false
-        ? false
-        : options.fayzApi?.tenantIdColumn ?? entityDef.data?.tenantIdColumn,
-      tenantId: options.fayzApi?.tenantId ?? (() => getActiveTenantId()),
-    })
-  }
-
-  if (backend?.provider === 'custom') {
-    const adapterId = backend.adapterId
-    const factory = adapterId ? options.customProviders?.[adapterId] : undefined
-    if (!adapterId || !factory) {
-      throw new Error(`[@fayz-ai/core] Custom data provider "${adapterId ?? 'unknown'}" is not registered.`)
-    }
-    return factory<T>(entityDef, mockData)
-  }
-
-  const client = getSupabaseClientOptional()
-
-  if (client && entityDef.data?.table) {
-    const tenantId = () => getActiveTenantId()
-    // Archetype entities share a physical table (e.g. people) across kinds
-    // (student/teacher/staff…). The cache key must carry the kind or the first
-    // kind's resultset is served to every sibling entity (teachers page
-    // listing students).
-    const cacheOptions = {
-      table: entityDef.data.archetypeKind
-        ? `${entityDef.data.table}#${entityDef.data.archetypeKind}`
-        : entityDef.data.table,
-      tenantId,
-      ttl: entityDef.data.cacheTTL,
-    }
-    const cached = <P extends DataProvider<T>>(p: P): DataProvider<T> =>
-      options.cache === false ? p : withCache(p, cacheOptions)
-
-    if (entityDef.data.archetype && entityDef.data.archetypeKind && !entityDef.data.schema) {
-      return cached(createArchetypeProvider<T>({
-        archetype: entityDef.data.archetype,
-        archetypeKind: entityDef.data.archetypeKind,
-        projectTable: entityDef.data.table,
-        tenantId,
-        searchColumns: entityDef.data.searchColumns ?? entityDef.fields
-          .filter((field) => field.searchable)
-          .map((field) => field.key),
-      }))
-    }
-
-    return cached(createSupabaseProvider<T>(entityDef.data.table, {
-      schema: entityDef.data.schema,
-      tenantId: entityDef.data.tenantScoped === false ? undefined : tenantId,
-      tenantIdColumn: entityDef.data.tenantIdColumn,
-      searchColumns: entityDef.data.searchColumns ?? entityDef.fields
-        .filter((field) => field.searchable)
-        .map((field) => field.key),
-      selectColumns: entityDef.data.selectColumns,
-      columnMap: entityDef.data.columnMap,
-      filters: entityDef.data.filters,
-      defaults: entityDef.data.defaults,
-    }))
-  }
-
-  if (entityDef.data?.table) {
-    console.warn(
-      `[fayz/core] resolveDataProvider: falling back to mock for "${entityDef.name}" (table: ${entityDef.data.table}). ` +
-      `Supabase client ${client ? 'available' : 'NOT initialized'}.`,
-    )
-  }
-  return createMockProvider(entityDef, mockData)
-}

package/src/data/supabase.ts

@@ -1,230 +0,0 @@
-import type { DataProvider, CrudQuery, CrudResult } from './types'
-import { applyRangeToQuery, isFilterObject, parseRangeFilter } from './filters'
-
-export interface SupabaseProviderConfig {
-  schema?: string
-  tenantId?: string | (() => string | undefined)
-  tenantIdColumn?: string
-  searchColumns?: string[]
-  selectColumns?: string
-  columnMap?: Record<string, string>
-  filters?: Record<string, string>
-  defaults?: Record<string, unknown>
-  supabaseClient?: unknown
-}
-
-function camelToSnake(str: string): string {
-  return str.replace(/[A-Z]/g, (c) => '_' + c.toLowerCase())
-}
-
-function snakeToCamel(str: string): string {
-  return str.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase())
-}
-
-function mapRow<T>(row: Record<string, unknown>, columnMap?: Record<string, string>): T {
-  const result: Record<string, unknown> = {}
-  for (const [key, value] of Object.entries(row)) {
-    const camelKey = columnMap?.[key] ?? snakeToCamel(key)
-    result[camelKey] = value
-  }
-  return result as T
-}
-
-function mapEntity(entity: Record<string, unknown>, columnMap?: Record<string, string>): Record<string, unknown> {
-  const reverseMap: Record<string, string> = {}
-  if (columnMap) {
-    for (const [snake, camel] of Object.entries(columnMap)) {
-      reverseMap[camel] = snake
-    }
-  }
-  const result: Record<string, unknown> = {}
-  for (const [key, value] of Object.entries(entity)) {
-    if (key === 'id' || key === 'createdAt' || key === 'updatedAt' || key === 'tenantId') continue
-    const snakeKey = reverseMap[key] ?? camelToSnake(key)
-    result[snakeKey] = value
-  }
-  return result
-}
-
-// Global Supabase client registry — set once via createFayzApp
-let _globalSupabaseClient: unknown | null = null
-
-export function setGlobalSupabaseClient(client: unknown): void {
-  _globalSupabaseClient = client
-}
-
-export function getSupabaseClientOptional(): unknown | null {
-  return _globalSupabaseClient
-}
-
-export function createSupabaseProvider<T extends { id: string }>(
-  table: string,
-  config?: SupabaseProviderConfig,
-): DataProvider<T> {
-  const schema = config?.schema ?? 'public'
-  const tenantIdCol = config?.tenantIdColumn ?? 'tenant_id'
-  const searchCols = config?.searchColumns ?? []
-  const selectCols = config?.selectColumns ?? '*'
-  const columnMap = config?.columnMap
-
-  function resolveTenantId(): string | undefined {
-    if (!config?.tenantId) return undefined
-    return typeof config.tenantId === 'function' ? config.tenantId() : config.tenantId
-  }
-
-  function getClient() {
-    const supabase = (config?.supabaseClient ?? _globalSupabaseClient) as {
-      schema: (s: string) => unknown
-      from: (t: string) => unknown
-    } | null
-    if (!supabase) throw new Error(`[@fayz-ai/core] Supabase client not available. Call createFayzApp with a provider first.`)
-    return schema === 'public' ? (supabase as { from: (t: string) => unknown }) : (supabase.schema(schema) as { from: (t: string) => unknown })
-  }
-
-  return {
-    async list(query: CrudQuery): Promise<CrudResult<T>> {
-      // 'none' skips PostgREST's count aggregate entirely — see CrudQuery.countMode.
-      const wantCount = query.countMode !== 'none'
-      let q = (getClient().from(table) as { select: (...args: unknown[]) => unknown })
-        .select(selectCols, wantCount ? { count: 'exact' } : undefined) as Record<string, unknown>
-
-      const tenantId = resolveTenantId()
-      if (tenantId) q = (q as { eq: (col: string, val: string) => unknown }).eq(tenantIdCol, tenantId) as Record<string, unknown>
-
-      if (config?.filters) {
-        for (const [col, val] of Object.entries(config.filters)) {
-          q = (q as { eq: (c: string, v: string) => unknown }).eq(col, val) as Record<string, unknown>
-        }
-      }
-
-      // Faceted / dynamic filters from the query, mapped to columns. Equality
-      // by default; a range object ({from,to} / {gte,lt} / {$gte,$lt}) becomes
-      // real SQL bounds instead of an equality compare against "[object Object]".
-      if (query.filters) {
-        for (const [key, val] of Object.entries(query.filters)) {
-          if (val == null || val === '') continue
-          const col = columnMap?.[key] ?? camelToSnake(key)
-          const range = parseRangeFilter(val)
-          if (range) {
-            q = applyRangeToQuery(q, col, range)
-            continue
-          }
-          if (isFilterObject(val)) {
-            throw new Error(
-              `[@fayz-ai/core] Filter "${key}" is an object with no recognised bound. ` +
-                'Use {from,to} / {gte,lte,gt,lt} for ranges, or a plain value for equality.',
-            )
-          }
-          q = (q as { eq: (c: string, v: unknown) => unknown }).eq(col, val) as Record<string, unknown>
-        }
-      }
-
-      if (query.search && searchCols.length > 0) {
-        const term = `%${query.search}%`
-        const orClause = searchCols.map((col) => `${camelToSnake(col)}.ilike.${term}`).join(',')
-        q = (q as { or: (c: string) => unknown }).or(orClause) as Record<string, unknown>
-      }
-
-      if (query.sortBy) {
-        q = (q as { order: (col: string, opts: unknown) => unknown })
-          .order(camelToSnake(query.sortBy), { ascending: query.sortDir !== 'desc' }) as Record<string, unknown>
-      } else {
-        q = (q as { order: (col: string, opts: unknown) => unknown })
-          .order('created_at', { ascending: false }) as Record<string, unknown>
-      }
-
-      const page = query.page ?? 1
-      const pageSize = query.pageSize ?? 50
-      const from = (page - 1) * pageSize
-      q = (q as { range: (f: number, t: number) => unknown }).range(from, from + pageSize - 1) as Record<string, unknown>
-
-      const { data, error, count } = await q as { data: Record<string, unknown>[] | null; error: unknown; count: number | null }
-      if (error) throw error
-
-      return {
-        data: (data ?? []).map((row) => mapRow<T>(row, columnMap)),
-        total: count ?? 0,
-      }
-    },
-
-    async create(data) {
-      const row = mapEntity(data as Record<string, unknown>, columnMap)
-      const tenantId = resolveTenantId()
-      if (tenantId) row[tenantIdCol] = tenantId
-      if (config?.defaults) {
-        for (const [col, val] of Object.entries(config.defaults)) {
-          if (row[col] === undefined) row[col] = val
-        }
-      }
-
-      const { data: created, error } = (await (getClient().from(table) as {
-        insert: (r: unknown) => { select: () => { single: () => Promise<{ data: unknown; error: unknown }> } }
-      }).insert(row).select().single()) as { data: Record<string, unknown> | null; error: unknown }
-
-      if (error) throw error
-      return mapRow<T>(created!, columnMap)
-    },
-
-    async createMany(rows, options) {
-      const tenantId = resolveTenantId()
-      const size = Math.max(1, options?.chunkSize ?? 200)
-      const prepared = rows.map((r) => {
-        const row = mapEntity(r as Record<string, unknown>, columnMap)
-        if (tenantId) row[tenantIdCol] = tenantId
-        if (config?.defaults) {
-          for (const [col, val] of Object.entries(config.defaults)) {
-            if (row[col] === undefined) row[col] = val
-          }
-        }
-        return row
-      })
-
-      let created = 0
-      const failed: Array<{ index: number; message: string }> = []
-      for (let start = 0; start < prepared.length; start += size) {
-        const chunk = prepared.slice(start, start + size)
-        const { error } = (await (getClient().from(table) as {
-          insert: (r: unknown) => Promise<{ error: unknown }>
-        }).insert(chunk)) as { error: unknown }
-        if (!error) {
-          created += chunk.length
-        } else {
-          // One bad row rejects its whole chunk. Retrying it row by row keeps
-          // the other 199 — an import that loses 200 records over one malformed
-          // phone number is worse than no import.
-          const message = error instanceof Error ? error.message : String(error)
-          for (let i = 0; i < chunk.length; i++) {
-            const { error: rowError } = (await (getClient().from(table) as {
-              insert: (r: unknown) => Promise<{ error: unknown }>
-            }).insert(chunk[i])) as { error: unknown }
-            if (rowError) {
-              failed.push({
-                index: start + i,
-                message: rowError instanceof Error ? rowError.message : String(rowError ?? message),
-              })
-            } else created += 1
-          }
-        }
-        options?.onProgress?.(Math.min(start + chunk.length, prepared.length), prepared.length)
-      }
-      return { created, failed }
-    },
-
-    async update(id, data) {
-      const row = mapEntity(data as Record<string, unknown>, columnMap)
-      const { data: updated, error } = (await (getClient().from(table) as {
-        update: (r: unknown) => { eq: (c: string, v: string) => { select: () => { single: () => Promise<{ data: unknown; error: unknown }> } } }
-      }).update(row).eq('id', id).select().single()) as { data: Record<string, unknown> | null; error: unknown }
-
-      if (error) throw error
-      return mapRow<T>(updated!, columnMap)
-    },
-
-    async remove(id) {
-      const { error } = (await (getClient().from(table) as {
-        delete: () => { eq: (c: string, v: string) => Promise<{ error: unknown }> }
-      }).delete().eq('id', id)) as { error: unknown }
-      if (error) throw error
-    },
-  }
-}

package/src/data/types.ts

@@ -1,50 +0,0 @@
-export interface CrudQuery {
-  search?: string
-  sortBy?: string
-  sortDir?: 'asc' | 'desc'
-  page?: number
-  pageSize?: number
-  filters?: Record<string, unknown>
-  /**
-   * Default 'exact' — a CRUD pager needs the total. It is a second aggregate
-   * over the filtered set, and on the live pool cost ~1070ms against ~270ms for
-   * the rows themselves. Callers that only want rows pass 'none' (total: 0).
-   */
-  countMode?: 'exact' | 'none'
-}
-
-export interface CrudResult<T> {
-  data: T[]
-  total: number
-}
-
-/** Outcome of a bulk write: what landed, and what did not and why. */
-export interface BulkWriteResult {
-  created: number
-  failed: Array<{ index: number; message: string }>
-}
-
-export interface BulkWriteOptions {
-  /** Rows per round-trip. Larger is fewer trips; too large trips statement timeouts. */
-  chunkSize?: number
-  onProgress?: (done: number, total: number) => void
-}
-
-export interface DataProvider<T extends { id: string } = { id: string }> {
-  list(query: CrudQuery): Promise<CrudResult<T>>
-  create(data: Omit<T, 'id' | 'createdAt' | 'updatedAt' | 'tenantId'>): Promise<T>
-  /**
-   * Write many rows in as few round-trips as the backend allows.
-   *
-   * Optional: `bulkCreate` falls back to looping `create` for providers that do
-   * not implement it, so a caller never has to branch. Importing a 900-row
-   * client list one INSERT at a time is 900 round-trips — the difference
-   * between a progress bar and a hung tab.
-   */
-  createMany?(
-    rows: Array<Omit<T, 'id' | 'createdAt' | 'updatedAt' | 'tenantId'>>,
-    options?: BulkWriteOptions,
-  ): Promise<BulkWriteResult>
-  update(id: string, data: Partial<T>): Promise<T>
-  remove(id: string): Promise<void>
-}

package/src/entity/index.ts

@@ -1,2 +0,0 @@
-export { registerEntity, getEntityByKey, getAllEntities, clearEntityRegistry, deriveEntityKey } from './registry'
-export type { RegisteredEntity } from './registry'

package/src/entity/registry.ts

@@ -1,49 +0,0 @@
-import type { EntityDef } from '../types/crud'
-import type { EntityArchetype } from '../types/entities'
-
-export interface RegisteredEntity {
-  entityKey: string
-  label: string
-  labelPlural: string
-  icon?: string
-  fields: EntityDef['fields']
-  source: 'app' | 'plugin'
-  /**
-   * The definition itself, so consumers that need to *read* the entity — the AI
-   * tool executor resolving a data provider — are not limited to the display
-   * metadata. Optional: registrations made before this existed omit it.
-   */
-  entityDef?: EntityDef
-  mockData?: Array<{ id: string }>
-  archetype?: EntityArchetype
-  pluginId?: string
-  pluginName?: string
-  pluginIcon?: string
-}
-
-const entityRegistry = new Map<string, RegisteredEntity>()
-
-export function registerEntity(entry: RegisteredEntity): void {
-  entityRegistry.set(entry.entityKey, entry)
-}
-
-export function getEntityByKey(key: string): RegisteredEntity | undefined {
-  return entityRegistry.get(key)
-}
-
-export function getAllEntities(): RegisteredEntity[] {
-  return Array.from(entityRegistry.values())
-}
-
-export function clearEntityRegistry(): void {
-  entityRegistry.clear()
-}
-
-export function deriveEntityKey(entityDef: EntityDef): string {
-  const name = entityDef.name.toLowerCase().replace(/\s+/g, '-')
-  if (entityDef.data?.archetype && entityDef.data?.archetypeKind) {
-    return `${entityDef.data.archetype}:${entityDef.data.archetypeKind}`
-  }
-  if (entityDef.data?.archetype) return entityDef.data.archetype
-  return name
-}

package/src/events/index.tsx

@@ -1,82 +0,0 @@
-import * as React from 'react'
-
-// ---------------------------------------------------------------------------
-// Event bus — the substrate for cross-plugin behavior. Replaces the bespoke
-// `window.dispatchEvent('agenda:open-booking')` hack and the imperative
-// financial bridge: plugins emit named events, others subscribe, and the
-// AppManifest can declare event→action bindings as data. Plugins describe the
-// events they emit via PluginManifest.events (see types/plugins) so the
-// platform can introspect and wire automations.
-// ---------------------------------------------------------------------------
-
-export type EventHandler<T = unknown> = (payload: T) => void
-
-export interface EventBus {
-  emit<T = unknown>(event: string, payload?: T): void
-  on<T = unknown>(event: string, handler: EventHandler<T>): () => void
-  once<T = unknown>(event: string, handler: EventHandler<T>): () => void
-  off<T = unknown>(event: string, handler: EventHandler<T>): void
-  clear(event?: string): void
-}
-
-export function createEventBus(): EventBus {
-  const handlers = new Map<string, Set<EventHandler>>()
-  const bus: EventBus = {
-    emit(event, payload) {
-      const set = handlers.get(event)
-      if (!set) return
-      // Snapshot so handlers can subscribe/unsubscribe during dispatch.
-      for (const handler of Array.from(set)) {
-        try {
-          handler(payload)
-        } catch (err) {
-          // A misbehaving subscriber must not break the emitter or its peers.
-          console.error(`[fayz] event handler for "${event}" threw:`, err)
-        }
-      }
-    },
-    on(event, handler) {
-      let set = handlers.get(event)
-      if (!set) {
-        set = new Set()
-        handlers.set(event, set)
-      }
-      set.add(handler as EventHandler)
-      return () => bus.off(event, handler)
-    },
-    once(event, handler) {
-      const wrapped: EventHandler = (payload) => {
-        bus.off(event, wrapped)
-        ;(handler as EventHandler)(payload)
-      }
-      return bus.on(event, wrapped)
-    },
-    off(event, handler) {
-      handlers.get(event)?.delete(handler as EventHandler)
-    },
-    clear(event) {
-      if (event) handlers.delete(event)
-      else handlers.clear()
-    },
-  }
-  return bus
-}
-
-/** The app-wide default bus. One per app runtime (repo-per-app). */
-export const eventBus: EventBus = createEventBus()
-
-/** Subscribe to an event for the lifetime of the component. The latest handler
- *  is always invoked, so closures over fresh props/state work without resubscribing. */
-export function useOnEvent<T = unknown>(
-  event: string,
-  handler: EventHandler<T>,
-  deps: React.DependencyList = [],
-): void {
-  const ref = React.useRef(handler)
-  ref.current = handler
-  React.useEffect(
-    () => eventBus.on<T>(event, (payload) => ref.current(payload)),
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [event, ...deps],
-  )
-}