@freighttech/ui 0.13.18

package/src/backend/dynamic-table/registry/ContentRegistryContext.tsx

@@ -0,0 +1,244 @@
+'use client'
+
+// One registry over the two things a pane can hold.
+//
+// It WRAPS `TableRegistryContext` rather than replacing it: tables keep their
+// existing provider, their existing `hasFeature` injection and
+// `filterAccessibleTables`, and every page that renders a table by id is
+// untouched. This layer adds widgets beside them and resolves both through ONE
+// lookup with ONE set of degradation states, so a host renders a slot without
+// caring which kind it holds.
+//
+// ── The four states, and why widgets can reach all four ──────────────────────
+// Tables get `denied` from the host's grant check. Widgets cannot: the server
+// catalogue (`/api/dashboards/layout`) returns only the ALLOWED set, so a widget
+// the user may not have is simply absent — indistinguishable from one deleted in
+// a release. The client-side widget entry registry closes that gap: it is
+// unfiltered and lists every widget compiled into the build, so
+//
+//     in catalogue                        -> ok
+//     not in catalogue, code exists       -> denied
+//     not in catalogue, no code           -> unknown
+//     catalogue still in flight           -> loading
+//
+// which is the same vocabulary tables already use, arrived at honestly rather
+// than by collapsing two different failures into one message.
+//
+// Spec: .ai/specs/2026-08-17-split-view-workspace-composition.md (Phase 2)
+
+import * as React from 'react'
+import type { PaneContentRef } from '../split-view/types'
+import type { TableDefinition } from './types'
+import { useAccessibleTables, useTableById } from './TableRegistryContext'
+import {
+  EMPTY_WIDGET_CATALOG,
+  useWidgetCatalog,
+  widgetLoaderKeyExists,
+  type WidgetCatalog,
+  type WidgetCatalogEntry,
+} from './widgetCatalog'
+
+/** Same four states the table registry already uses. Do not add a fifth. */
+export type ContentStatus = 'ok' | 'unknown' | 'denied' | 'loading'
+
+export type TableContentItem = {
+  kind: 'table'
+  id: string
+  title: string
+  icon?: string
+  group?: string
+  definition: TableDefinition
+}
+
+export type WidgetContentItem = {
+  kind: 'widget'
+  id: string
+  title: string
+  icon?: string
+  group?: string
+  /** What `loadDashboardWidgetModule` takes. Present on widgets only. */
+  loaderKey: string
+  description?: string | null
+  defaultSettings?: unknown
+  supportsRefresh?: boolean
+}
+
+/** One entry a picker can list and a pane can mount, of either kind. */
+export type PaneContentItem = TableContentItem | WidgetContentItem
+
+export type ContentRegistryValue = WidgetCatalog & {
+  /**
+   * True only when a provider is actually mounted.
+   *
+   * Distinct from `ready`, which means "the catalogue answered". Without this a
+   * host that forgot the provider would sit at `loading` forever, which reads as
+   * "still working" — the one failure mode worse than an error.
+   */
+  mounted: boolean
+  /** Injected so tests need no widget bootstrap. Defaults to the real registry. */
+  loaderKeyExists: (loaderKey: string) => boolean
+}
+
+const DEFAULT_VALUE: ContentRegistryValue = {
+  ...EMPTY_WIDGET_CATALOG,
+  mounted: false,
+  // Default-deny, exactly as `TableRegistryContext` defaults `hasFeature` to
+  // false: a host that forgot the provider offers nothing rather than
+  // everything.
+  loaderKeyExists: () => false,
+}
+
+const ContentRegistryContext = React.createContext<ContentRegistryValue>(DEFAULT_VALUE)
+
+/**
+ * Supplies an already-resolved catalogue. Use this when a host owns the fetch
+ * (or a test owns the fixtures); use `ContentRegistryBootstrap` otherwise.
+ */
+export function ContentRegistryProvider({
+  value,
+  children,
+}: {
+  value: Omit<ContentRegistryValue, 'mounted' | 'loaderKeyExists'> &
+    Partial<Pick<ContentRegistryValue, 'loaderKeyExists'>>
+  children: React.ReactNode
+}) {
+  const resolved = React.useMemo<ContentRegistryValue>(
+    () => ({
+      widgets: value.widgets,
+      context: value.context,
+      ready: value.ready,
+      mounted: true,
+      loaderKeyExists: value.loaderKeyExists ?? widgetLoaderKeyExists,
+    }),
+    [value],
+  )
+  return <ContentRegistryContext.Provider value={resolved}>{children}</ContentRegistryContext.Provider>
+}
+
+/**
+ * Fetches the widget catalogue and provides it. Mount once, inside whatever
+ * already provides the table registry and a react-query client.
+ */
+export function ContentRegistryBootstrap({ children }: { children: React.ReactNode }) {
+  const catalog = useWidgetCatalog()
+  return <ContentRegistryProvider value={catalog}>{children}</ContentRegistryProvider>
+}
+
+export function useContentRegistry(): ContentRegistryValue {
+  return React.useContext(ContentRegistryContext)
+}
+
+/** The widget render context (`userId` / `tenantId` / `organizationId`), or null. */
+export function useWidgetRenderContext() {
+  return useContentRegistry().context
+}
+
+function widgetItem(entry: WidgetCatalogEntry): WidgetContentItem {
+  return {
+    kind: 'widget',
+    id: entry.id,
+    title: entry.title,
+    icon: entry.icon ?? undefined,
+    group: entry.moduleId,
+    loaderKey: entry.loaderKey,
+    description: entry.description,
+    defaultSettings: entry.defaultSettings,
+    supportsRefresh: entry.supportsRefresh,
+  }
+}
+
+function tableItem(definition: TableDefinition): TableContentItem {
+  return {
+    kind: 'table',
+    id: definition.metadata.id,
+    title: definition.metadata.title,
+    icon: definition.metadata.icon,
+    group: definition.metadata.group,
+    definition,
+  }
+}
+
+/**
+ * Everything the current user may put in a slot — tables AND widgets.
+ *
+ * Tables come through `filterAccessibleTables` (the host's grant check, applied
+ * client-side, UX not security); widgets arrive pre-filtered by the server. Two
+ * ACL paths, because the two halves genuinely have two authorities — but one
+ * result shape, so a picker never branches.
+ */
+export function useAccessibleContent(): PaneContentItem[] {
+  const tables = useAccessibleTables()
+  const { widgets } = useContentRegistry()
+  return React.useMemo(
+    () => [...tables.map(tableItem), ...widgets.map(widgetItem)],
+    [tables, widgets],
+  )
+}
+
+function useWidgetById(ref: Extract<PaneContentRef, { kind: 'widget' }>): {
+  item: PaneContentItem | null
+  status: ContentStatus
+} {
+  const { widgets, ready, mounted, loaderKeyExists } = useContentRegistry()
+  return React.useMemo(() => {
+    if (!mounted) {
+      // Only complain about a slot that actually names a widget — the sentinel
+      // ref below keeps hook order stable on table-only pages, and those hosts
+      // are under no obligation to mount this provider.
+      if (ref.widgetId && process.env.NODE_ENV !== 'production') {
+        try {
+          console.warn(
+            '[ContentRegistry] A widget slot was resolved with no ContentRegistryProvider mounted. ' +
+              'Wrap the host in <ContentRegistryBootstrap> — otherwise every widget pane reads as removed.',
+          )
+        } catch {}
+      }
+      return { item: null, status: 'unknown' as const }
+    }
+    const entry = widgets.find((w) => w.id === ref.widgetId)
+    if (entry) return { item: widgetItem(entry), status: 'ok' as const }
+    if (!ready) return { item: null, status: 'loading' as const }
+    // Absent from the allowed set. Its code still being in the build is what
+    // makes this a permission verdict rather than a missing feature.
+    if (loaderKeyExists(ref.loaderKey)) return { item: null, status: 'denied' as const }
+    return { item: null, status: 'unknown' as const }
+  }, [widgets, ready, mounted, loaderKeyExists, ref, ref.widgetId, ref.loaderKey])
+}
+
+function useTableContentById(ref: Extract<PaneContentRef, { kind: 'table' }>): {
+  item: PaneContentItem | null
+  status: ContentStatus
+} {
+  const { definition, status } = useTableById(ref.tableId)
+  return React.useMemo(
+    () => ({ item: definition ? tableItem(definition) : null, status }),
+    [definition, status],
+  )
+}
+
+/**
+ * Resolve one slot's content, of either kind.
+ *
+ * Both branches run their hooks unconditionally — `PaneContentRef.kind` is
+ * stable for the life of a slot (changing content replaces the node, minting a
+ * new pane id), so this cannot reorder hooks between renders, and keeping both
+ * live avoids forcing every caller to branch before it knows what it has.
+ */
+export function useContentById(ref: PaneContentRef | null | undefined): {
+  item: PaneContentItem | null
+  status: ContentStatus
+} {
+  const tableRef = React.useMemo<Extract<PaneContentRef, { kind: 'table' }>>(
+    () => (ref?.kind === 'table' ? ref : { kind: 'table', tableId: '' }),
+    [ref],
+  )
+  const widgetRef = React.useMemo<Extract<PaneContentRef, { kind: 'widget' }>>(
+    () => (ref?.kind === 'widget' ? ref : { kind: 'widget', widgetId: '', loaderKey: '' }),
+    [ref],
+  )
+  const table = useTableContentById(tableRef)
+  const widget = useWidgetById(widgetRef)
+
+  if (!ref) return { item: null, status: 'unknown' }
+  return ref.kind === 'table' ? table : widget
+}

package/src/backend/dynamic-table/registry/TableRegistryContext.tsx

@@ -0,0 +1,84 @@
+'use client'
+
+// The seam between the registry (which knows nothing about auth) and a host
+// (which does).
+//
+// Pages live in `packages/*` and the collected registry lives in `apps/web`, so
+// a page cannot import it directly without inverting the dependency. A context
+// mounted once in the backend layout carries both halves — the tables the host
+// collected, and the host's own feature check — to any page that wants to
+// render a table by id.
+//
+// Spec: .ai/specs/2026-08-04-module-table-registry.md
+
+import * as React from 'react'
+import type { TableDefinition } from './types'
+import { filterAccessibleTables, findTableDefinition } from './filterAccessibleTables'
+
+export type TableRegistryValue = {
+  /** Every table this host collected, before ACL. */
+  tables: TableDefinition[]
+  /**
+   * Host-supplied grant check. Opaque to the registry — the backend resolves it
+   * through `POST /api/auth/feature-check` (organization-scoped, server-side);
+   * another surface would resolve it against its own authority.
+   */
+  hasFeature: (feature: string) => boolean
+  /** False while grants are still loading, so a picker can avoid flashing an
+   *  empty list and then filling it. */
+  ready: boolean
+}
+
+const EMPTY: TableDefinition[] = []
+
+const TableRegistryContext = React.createContext<TableRegistryValue>({
+  tables: EMPTY,
+  // Default-deny. A host that forgot to mount the provider shows nothing rather
+  // than everything — the failure is visible, not permissive.
+  hasFeature: () => false,
+  ready: false,
+})
+
+export function TableRegistryProvider({
+  value,
+  children,
+}: {
+  value: TableRegistryValue
+  children: React.ReactNode
+}) {
+  return (
+    <TableRegistryContext.Provider value={value}>{children}</TableRegistryContext.Provider>
+  )
+}
+
+export function useTableRegistry(): TableRegistryValue {
+  return React.useContext(TableRegistryContext)
+}
+
+/** The tables the current user may see, memoised against the grant function. */
+export function useAccessibleTables(): TableDefinition[] {
+  const { tables, hasFeature } = useTableRegistry()
+  return React.useMemo(() => filterAccessibleTables(tables, hasFeature), [tables, hasFeature])
+}
+
+/**
+ * Resolve one table by id, with the two degradations a host needs.
+ * `unknown` — not in the registry (e.g. a saved layout naming a removed table).
+ * `denied`  — present but the user lacks its features.
+ */
+export function useTableById(id: string | null | undefined): {
+  definition: TableDefinition | null
+  status: 'ok' | 'unknown' | 'denied' | 'loading'
+} {
+  const { tables, hasFeature, ready } = useTableRegistry()
+  return React.useMemo(() => {
+    if (!id) return { definition: null, status: 'unknown' as const }
+    const definition = findTableDefinition(tables, id)
+    if (!definition) return { definition: null, status: 'unknown' as const }
+    if (!ready) return { definition, status: 'loading' as const }
+    const allowed = definition.metadata.features.every((f) => hasFeature(f))
+    return allowed
+      ? { definition, status: 'ok' as const }
+      : { definition, status: 'denied' as const }
+  }, [id, tables, hasFeature, ready])
+}

package/src/backend/dynamic-table/registry/filterAccessibleTables.ts

@@ -0,0 +1,36 @@
+import type { TableDefinition } from './types'
+
+/**
+ * Narrow a registry to the tables a user may see.
+ *
+ * **Pure on purpose.** It calls no endpoint and knows nothing about who is
+ * logged in — `metadata.features` are opaque strings and the HOST injects the
+ * check. That is what keeps the registry usable by more than one surface: the
+ * backend resolves grants through `POST /api/auth/feature-check` (which is
+ * organization-scoped, server-side), and any other host wires `hasFeature` to
+ * its own authority.
+ *
+ * **This filter is UX, not security.** The boundary is unchanged and unmoved:
+ * every table's own list route still declares and enforces its feature
+ * requirements. Hiding an inaccessible table from a picker is courtesy — it
+ * stops a host offering something that would render an empty error — and a
+ * table reached some other way (a stale saved layout) is still refused by the
+ * route, not by this function.
+ */
+export function filterAccessibleTables(
+  tables: TableDefinition[],
+  hasFeature: (feature: string) => boolean,
+): TableDefinition[] {
+  return tables.filter((table) =>
+    table.metadata.features.every((feature) => hasFeature(feature)),
+  )
+}
+
+/** Look one up by `metadata.id`. Returns null rather than throwing — a host
+ *  restoring a saved layout must degrade that slot, not fail the whole view. */
+export function findTableDefinition(
+  tables: TableDefinition[],
+  id: string,
+): TableDefinition | null {
+  return tables.find((t) => t.metadata.id === id) ?? null
+}

package/src/backend/dynamic-table/registry/index.ts

@@ -0,0 +1,38 @@
+export type {
+  TableDefinition,
+  TableDefinitionMetadata,
+  TableHostContext,
+  TableLoader,
+} from './types'
+export { lazyTable } from './lazyTable'
+export { filterAccessibleTables, findTableDefinition } from './filterAccessibleTables'
+export {
+  TableRegistryProvider,
+  useTableRegistry,
+  useAccessibleTables,
+  useTableById,
+} from './TableRegistryContext'
+export type { TableRegistryValue } from './TableRegistryContext'
+export {
+  ContentRegistryProvider,
+  ContentRegistryBootstrap,
+  useContentRegistry,
+  useAccessibleContent,
+  useContentById,
+  useWidgetRenderContext,
+} from './ContentRegistryContext'
+export type {
+  ContentRegistryValue,
+  ContentStatus,
+  PaneContentItem,
+  TableContentItem,
+  WidgetContentItem,
+} from './ContentRegistryContext'
+export {
+  useWidgetCatalog,
+  widgetLoaderKeyExists,
+  parseWidgetCatalog,
+  parseWidgetRenderContext,
+  EMPTY_WIDGET_CATALOG,
+} from './widgetCatalog'
+export type { WidgetCatalog, WidgetCatalogEntry } from './widgetCatalog'

package/src/backend/dynamic-table/registry/lazyTable.tsx

@@ -0,0 +1,80 @@
+'use client'
+
+// Mirrors `lazyDashboardWidget` (@open-mercato/shared/modules/dashboard/widgets.ts:64):
+// a cached, single-flight loader so a table's code is only fetched when a host
+// actually renders it, and only once no matter how many hosts mount at the
+// same moment.
+
+import * as React from 'react'
+import TableSkeleton from '../components/TableSkeleton'
+import type { TableHostContext, TableLoader } from './types'
+
+export function lazyTable(
+  loader: TableLoader,
+): React.ComponentType<TableHostContext> {
+  let cached: React.ComponentType<TableHostContext> | null = null
+  let pending: Promise<void> | null = null
+  let failed: unknown = null
+
+  const load = () => {
+    if (cached) return Promise.resolve()
+    if (!pending) {
+      pending = loader()
+        .then((mod) => {
+          cached =
+            (mod as { default?: React.ComponentType<TableHostContext> }).default ??
+            (mod as React.ComponentType<TableHostContext>)
+        })
+        .catch((err) => {
+          // Clear `pending` so a later mount retries rather than awaiting a
+          // promise that will never resolve — a failed chunk fetch is usually
+          // transient (deploy mid-session, flaky network).
+          pending = null
+          failed = err
+          throw err
+        })
+    }
+    return pending
+  }
+
+  const LazyTable: React.ComponentType<TableHostContext> = (props) => {
+    const [, setTick] = React.useState(0)
+
+    React.useEffect(() => {
+      let cancelled = false
+      void load()
+        .then(() => {
+          if (!cancelled) setTick((v) => v + 1)
+        })
+        .catch((err) => {
+          if (cancelled) return
+          try {
+            console.error('Failed to load table component', err)
+          } catch {}
+          // Re-render so the failure is SHOWN. A lazy loader that swallows its
+          // error leaves a permanent skeleton, which reads as "still loading"
+          // forever — the one outcome worse than an error message.
+          setTick((v) => v + 1)
+        })
+      return () => {
+        cancelled = true
+      }
+    }, [])
+
+    if (cached) {
+      const Loaded = cached
+      return <Loaded {...props} />
+    }
+    if (failed) {
+      return (
+        <div className="p-4 text-body-regular-sm" role="alert" data-table-load-error="">
+          This table could not be loaded.
+        </div>
+      )
+    }
+    return <TableSkeleton rows={10} columns={5} />
+  }
+
+  LazyTable.displayName = 'LazyTable'
+  return LazyTable
+}

package/src/backend/dynamic-table/registry/types.ts

@@ -0,0 +1,181 @@
+// Module table registry — the contract by which a module declares a table it
+// owns, so the table has an identity beyond "the body of one page.tsx".
+//
+// Deliberately mirrors `DashboardWidgetModule`
+// (@open-mercato/shared/modules/dashboard/widgets): same shape of
+// `{ metadata, Component }`, same lazy-loader helper, same `features` field for
+// ACL. Modules already know that pattern; this is not a second dialect.
+//
+// Spec: .ai/specs/2026-08-04-module-table-registry.md
+
+import type * as React from 'react'
+import type { FilterRow } from '../types/index'
+import type { SharedFilterMapping } from '../split-view/sharedCriteria'
+
+/**
+ * What a host passes a table when the table is NOT the whole page.
+ *
+ * Three props, each earned by a verified problem rather than anticipated need.
+ * A table rendered with none of them behaves exactly as it does today.
+ */
+export type TableHostContext = {
+  /**
+   * Prefix for this instance's per-table client storage keys (last-used
+   * perspective, column widths).
+   *
+   * Absent or '' → today's keys, byte-for-byte. Without this, two instances of
+   * the SAME table overwrite each other, because those keys are derived from
+   * `tableId` alone.
+   */
+  storageScope?: string
+  /**
+   * True when the table is not the whole page. One rule, two consequences:
+   * **an embedded table does not touch page-level state**.
+   *
+   *  1. Row clicks select instead of navigating — otherwise a click inside a
+   *     host tears the host down.
+   *  2. No reading or writing of the URL query string. Four tables today seed
+   *     filters from it (`?status=`, `?fileId=`) and one writes back to it, so
+   *     two embedded instances would contend over the same query keys.
+   */
+  embedded?: boolean
+  /**
+   * Filters the host wants applied on mount. This is what replaces the URL
+   * seeding an embedded table must not do.
+   */
+  initialFilters?: FilterRow[]
+  /**
+   * Filters a WORKSPACE is driving this pane with, already translated into this
+   * table's own field names by `mapCriteriaForTable`.
+   *
+   * Distinct from `initialFilters`, which is read ONCE on mount. These are
+   * LIVE: the user retypes in the workspace bar and every pane re-narrows. They
+   * are also kept apart from the table's own filter state all the way down, so
+   * turning the workspace off restores exactly what the user had set locally.
+   */
+  sharedFilters?: FilterRow[]
+  /**
+   * The workspace search box's value while it is driving this pane.
+   *
+   * Presence is the switch: `undefined` means no workspace search and the
+   * pane's own box applies; `''` means the bar is on with an empty needle, and
+   * the pane's own (now hidden) search must stop filtering — otherwise the grid
+   * stays narrowed by a control the user can no longer see.
+   */
+  sharedSearch?: string
+  /**
+   * Controls the HOST wants rendered inside the table's own toolbar row.
+   *
+   * Exists so a host adds no vertical chrome of its own. An earlier build put
+   * the split/layout controls in a strip ABOVE the grid, which pushed every
+   * adopted page's first row ~33px down — a straight density loss on pages
+   * whose entire purpose is rows per screen. The toolbar already has a wide
+   * empty gap between the search box and the action buttons; that is where
+   * host controls belong.
+   *
+   * The table merges this into `uiConfig.searchBarEnd` alongside anything it
+   * already puts there.
+   */
+  /**
+   * True only when this table is ONE OF SEVERAL on screen.
+   *
+   * Distinct from `embedded`, which merely says "a host owns my bounds" and is
+   * true even for a single pane. Page-level chrome — a mode selector that
+   * decides what the whole page is about — is still correct for one pane and
+   * wrong for several, where it repeats and implies a selection nobody made.
+   */
+  multiview?: boolean
+  /**
+   * True when this table IS the page's subject, so opening a row is what the
+   * page is for.
+   *
+   * ═══ WHY THIS IS NOT JUST `!embedded` ═══
+   *
+   * `embedded` above claims to mean "not the whole page", and `multiview`'s
+   * note says it "merely says a host owns my bounds and is true even for a
+   * single pane". Both are true of it, and that is the problem: it carries two
+   * meanings that come apart at exactly one place — the PRIMARY pane of a
+   * split-view host, which is the page's own table rendered inside a host that
+   * owns its bounds.
+   *
+   * `multiview` was already carved out of `embedded` for the same reason. This
+   * is the second carve-out, and it was not free: every list page in the app
+   * moved to `SplitViewHost`, which passes `embedded` to every pane, so the
+   * Files list lost its row links and its row-click handler at once and a
+   * forwarder had **no way to open a file from the list of files** (HEDGE-110
+   * step 1). The table's navigation code was all still there; nothing called
+   * it.
+   *
+   * Hosts that own bounds AND own the page (the primary pane) set this. A
+   * drawer or a secondary pane does not — there, a navigation really would
+   * tear the host down, which is what `embedded` was protecting against.
+   */
+  ownsPageNavigation?: boolean
+  /**
+   * Rows the HOST wants inside the table's overflow menu.
+   *
+   * Deliberately NOT a toolbar slot: a host rendering its own button beside the
+   * table's overflow leaves two near-identical menus in one strip. One menu,
+   * host items appended.
+   */
+  overflowExtras?: React.ReactNode
+  /**
+   * Chrome rows the host wants suppressed, so a pane can trade toolbar for
+   * rows. The table maps these onto `DynamicTable`'s existing
+   * `hideSearch` / `hidePerspectiveTabs` / `hidePagination`.
+   */
+  hideToolbar?: boolean
+  hideSearch?: boolean
+  hideViews?: boolean
+  hidePagination?: boolean
+}
+
+export type TableDefinitionMetadata = {
+  /** '<module>.<entity>', singular entity — 'offers.offer', 'products.product'. */
+  id: string
+  title: string
+  titleKey: string
+  /** ACL features. Opaque strings — the registry never resolves them. */
+  features: string[]
+  /**
+   * The table's EXISTING perspectives key, a **separate and immutable**
+   * namespace from `id`. Today's values are flat slugs that predate this
+   * registry ('products', 'facilities', 'products_carriers', 'fms-files') and
+   * have live user data behind them at `/api/perspectives/{tableId}` — so they
+   * must never be renamed to match `id`. Declared here so a table's two
+   * identities are visible in one place.
+   */
+  perspectiveTableId: string
+  /** Entity id from the generated ids (e.g. 'products:product'). */
+  entityId: string
+  /** Canonical full-page route — powers "open full page" from any host. */
+  href: string
+  /** lucide-react icon name. A string, matching the dashboard-widget convention. */
+  icon?: string
+  /** Grouping for pickers; reuse the owning route's pageGroup. */
+  group?: string
+  groupKey?: string
+  /**
+   * Which of THIS table's fields answers a shared workspace criterion.
+   * Absent = not participating.
+   *
+   * Declared per table because panes hold different entities: "customer" is
+   * `contractorId` here and `customerId` there. Without an explicit
+   * declaration the workspace bar would have to guess, and a pane that guesses
+   * wrong shows unfiltered rows to someone who believes they are filtered —
+   * the one failure this whole mechanism exists to prevent. A criterion with
+   * no entry here is REPORTED back to the pane as unmapped, so the pane says
+   * "not filtered by customer" instead of staying quiet.
+   */
+  sharedFilters?: SharedFilterMapping
+}
+
+export type TableDefinition = {
+  metadata: TableDefinitionMetadata
+  Table: React.ComponentType<TableHostContext>
+}
+
+export type TableLoader = () => Promise<
+  | { default: React.ComponentType<TableHostContext> }
+  | React.ComponentType<TableHostContext>
+>