@freighttech/ui 0.13.18

package/src/backend/injection/eventBridge.ts

@@ -0,0 +1,158 @@
+"use client"
+import { useEffect, useRef } from 'react'
+import type { AppEventPayload } from '@open-mercato/shared/modules/widgets/injection'
+import { APP_EVENT_DOM_NAME } from './useAppEvent'
+
+const SSE_ENDPOINT = '/api/events/stream'
+const HEARTBEAT_TIMEOUT = 45_000 // Expect heartbeat every 30s, allow 45s grace
+const RECONNECT_BASE_MS = 1_000
+const RECONNECT_MAX_MS = 30_000
+const DEDUP_WINDOW_MS = 500
+const BRIDGE_RECONNECTED_EVENT_ID = 'om:bridge:reconnected'
+
+/**
+ * React hook that establishes a singleton SSE connection to the event bridge.
+ *
+ * Mount once in the app shell/layout. Receives server-side events with
+ * `clientBroadcast: true` and dispatches them as `om:event` CustomEvents
+ * on the window object for consumption by `useAppEvent`.
+ *
+ * Features:
+ * - Auto-reconnect with exponential backoff
+ * - Deduplication within 500ms window
+ * - Heartbeat-based liveness detection
+ * - Singleton connection per browser tab
+ */
+export function useEventBridge(): void {
+  const sourceRef = useRef<EventSource | null>(null)
+  const reconnectAttempts = useRef(0)
+  const reconnectTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const heartbeatTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const recentEvents = useRef<Map<string, number>>(new Map())
+  const hasEverConnected = useRef(false)
+  const reconnectPending = useRef(false)
+
+  useEffect(() => {
+    let mounted = true
+
+    function isDuplicate(eventPayload: AppEventPayload): boolean {
+      const key = `${eventPayload.id}:${JSON.stringify(eventPayload.payload ?? {})}`
+      const lastSeen = recentEvents.current.get(key)
+      if (lastSeen && Date.now() - lastSeen < DEDUP_WINDOW_MS) return true
+      recentEvents.current.set(key, Date.now())
+      // Prune old entries
+      if (recentEvents.current.size > 100) {
+        const now = Date.now()
+        for (const [k, v] of recentEvents.current) {
+          if (now - v > DEDUP_WINDOW_MS * 2) recentEvents.current.delete(k)
+        }
+      }
+      return false
+    }
+
+    function resetHeartbeatTimer() {
+      if (heartbeatTimer.current) clearTimeout(heartbeatTimer.current)
+      heartbeatTimer.current = setTimeout(() => {
+        console.warn('[EventBridge] Heartbeat timeout — reconnecting')
+        disconnect()
+        scheduleReconnect()
+      }, HEARTBEAT_TIMEOUT)
+    }
+
+    function connect() {
+      if (!mounted) return
+      if (sourceRef.current) return
+
+      try {
+        const source = new EventSource(SSE_ENDPOINT, { withCredentials: true })
+        sourceRef.current = source
+
+        source.onopen = () => {
+          const shouldEmitReconnect = hasEverConnected.current && reconnectPending.current
+          hasEverConnected.current = true
+          reconnectPending.current = false
+          reconnectAttempts.current = 0
+          resetHeartbeatTimer()
+          if (shouldEmitReconnect) {
+            window.dispatchEvent(
+              new CustomEvent(APP_EVENT_DOM_NAME, {
+                detail: {
+                  id: BRIDGE_RECONNECTED_EVENT_ID,
+                  payload: {},
+                  timestamp: Date.now(),
+                  organizationId: '',
+                } satisfies AppEventPayload,
+              }),
+            )
+          }
+        }
+
+        source.onmessage = (event) => {
+          resetHeartbeatTimer()
+          if (!event.data || event.data === ':heartbeat') return
+
+          try {
+            const parsed = JSON.parse(event.data) as AppEventPayload
+            if (!parsed.id || typeof parsed.id !== 'string') return
+
+            if (isDuplicate(parsed)) return
+
+            window.dispatchEvent(
+              new CustomEvent(APP_EVENT_DOM_NAME, { detail: parsed }),
+            )
+          } catch {
+            // Ignore malformed events
+          }
+        }
+
+        source.onerror = () => {
+          if (hasEverConnected.current) {
+            reconnectPending.current = true
+          }
+          disconnect()
+          if (mounted) scheduleReconnect()
+        }
+      } catch {
+        if (hasEverConnected.current) {
+          reconnectPending.current = true
+        }
+        if (mounted) scheduleReconnect()
+      }
+    }
+
+    function disconnect() {
+      if (sourceRef.current) {
+        sourceRef.current.close()
+        sourceRef.current = null
+      }
+      if (heartbeatTimer.current) {
+        clearTimeout(heartbeatTimer.current)
+        heartbeatTimer.current = null
+      }
+    }
+
+    function scheduleReconnect() {
+      if (reconnectTimer.current) return
+      const delay = Math.min(
+        RECONNECT_BASE_MS * Math.pow(2, reconnectAttempts.current),
+        RECONNECT_MAX_MS,
+      )
+      reconnectAttempts.current++
+      reconnectTimer.current = setTimeout(() => {
+        reconnectTimer.current = null
+        connect()
+      }, delay)
+    }
+
+    connect()
+
+    return () => {
+      mounted = false
+      disconnect()
+      if (reconnectTimer.current) {
+        clearTimeout(reconnectTimer.current)
+        reconnectTimer.current = null
+      }
+    }
+  }, [])
+}

package/src/backend/injection/helpers.ts

@@ -0,0 +1,35 @@
+import type { InjectionSpotId } from '@open-mercato/shared/modules/widgets/injection'
+
+/**
+ * Generate a standard injection spot ID for CRUD forms
+ * @param formName The name/identifier of the form (e.g., 'catalog.product', 'catalog.variant')
+ * @returns A standardized injection spot ID
+ */
+export function generateCrudFormInjectionSpotId(formName: string): InjectionSpotId {
+  return `crud-form:${formName}`
+}
+
+/**
+ * Generate injection spot IDs for common CRUD form locations
+ */
+export const CrudFormInjectionSpots = {
+  /**
+   * Generate injection spot ID for before the form fields
+   */
+  beforeFields: (formName: string): InjectionSpotId => `${generateCrudFormInjectionSpotId(formName)}:before-fields`,
+  
+  /**
+   * Generate injection spot ID for after the form fields
+   */
+  afterFields: (formName: string): InjectionSpotId => `${generateCrudFormInjectionSpotId(formName)}:after-fields`,
+  
+  /**
+   * Generate injection spot ID for the header area
+   */
+  header: (formName: string): InjectionSpotId => `${generateCrudFormInjectionSpotId(formName)}:header`,
+  
+  /**
+   * Generate injection spot ID for the footer/actions area
+   */
+  footer: (formName: string): InjectionSpotId => `${generateCrudFormInjectionSpotId(formName)}:footer`,
+}

package/src/backend/injection/mergeMenuItems.ts

@@ -0,0 +1,80 @@
+import type { InjectionMenuItem } from '@open-mercato/shared/modules/widgets/injection'
+import { insertByInjectionPlacement } from '@open-mercato/shared/modules/widgets/injection-position'
+
+export type MergedMenuItem = {
+  id: string
+  label?: string
+  labelKey?: string
+  icon?: string
+  href?: string
+  onClick?: () => void
+  separator?: boolean
+  badge?: string | number
+  groupId?: string
+  groupLabel?: string
+  groupLabelKey?: string
+  groupOrder?: number
+  children?: Omit<InjectionMenuItem, 'children'>[]
+  source: 'built-in' | 'injected'
+}
+
+type BuiltInMenuItem = {
+  id: string
+  [key: string]: unknown
+}
+
+function toMergedInjectedItem(item: InjectionMenuItem): MergedMenuItem {
+  return {
+    id: item.id,
+    label: item.label,
+    labelKey: item.labelKey,
+    icon: item.icon,
+    href: item.href,
+    onClick: item.onClick,
+    separator: item.separator,
+    badge: item.badge,
+    groupId: item.groupId,
+    groupLabel: item.groupLabel,
+    groupLabelKey: item.groupLabelKey,
+    groupOrder: item.groupOrder,
+    children: item.children,
+    source: 'injected',
+  }
+}
+
+export function mergeMenuItems(
+  builtIn: BuiltInMenuItem[],
+  injected: InjectionMenuItem[],
+): MergedMenuItem[] {
+  let merged: MergedMenuItem[] = builtIn.map((item) => ({
+    ...(item as Record<string, unknown>),
+    id: item.id,
+    source: 'built-in',
+  })) as MergedMenuItem[]
+
+  const existingIds = new Set(builtIn.map((i) => i.id))
+  const existingHrefs = new Set(builtIn.map((i) => (i as Record<string, unknown>).href as string | undefined).filter(Boolean))
+
+  for (const item of injected) {
+    if (existingIds.has(item.id)) continue
+    if (item.href && existingHrefs.has(item.href)) continue
+
+    const nextItem = toMergedInjectedItem(item)
+    existingIds.add(item.id)
+    if (item.href) existingHrefs.add(item.href)
+
+    if (!item.placement && item.groupId) {
+      const existingGroupIndexes = merged
+        .map((entry, index) => ({ entry, index }))
+        .filter(({ entry }) => entry.groupId === item.groupId)
+      if (existingGroupIndexes.length > 0) {
+        const insertAfter = existingGroupIndexes[existingGroupIndexes.length - 1]?.index ?? -1
+        merged.splice(insertAfter + 1, 0, nextItem)
+        continue
+      }
+    }
+    merged = insertByInjectionPlacement(merged, nextItem, item.placement, (entry) => entry.id)
+  }
+
+  return merged
+}

package/src/backend/injection/mutationEvents.ts

@@ -0,0 +1,22 @@
+"use client"
+
+import { BACKEND_RECORD_CURRENT_INJECTION_SPOT_ID } from './spotIds'
+
+export const LEGACY_GLOBAL_MUTATION_INJECTION_SPOT_ID = 'backend-mutation:global'
+export const GLOBAL_MUTATION_INJECTION_SPOT_ID = BACKEND_RECORD_CURRENT_INJECTION_SPOT_ID
+export const BACKEND_MUTATION_ERROR_EVENT = 'om:backend-mutation-error'
+
+export type BackendMutationErrorEventDetail = {
+  contextId?: string
+  formId?: string
+  error?: unknown
+}
+
+export function dispatchBackendMutationError(detail: BackendMutationErrorEventDetail) {
+  if (typeof window === 'undefined') return
+  window.dispatchEvent(
+    new CustomEvent(BACKEND_MUTATION_ERROR_EVENT, {
+      detail,
+    }),
+  )
+}

package/src/backend/injection/resolveInjectedIcon.tsx

@@ -0,0 +1,30 @@
+import * as React from 'react'
+import * as LucideIcons from 'lucide-react'
+
+type LucideIconComponent = React.ComponentType<{ className?: string }>
+
+function toPascalCaseIconName(name: string): string {
+  if (!name.includes('-') && !name.includes('_') && !name.includes(' ')) return name
+  return name
+    .split(/[-_\s]+/)
+    .filter((part) => part.length > 0)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+}
+
+export function resolveInjectedIcon(icon?: string, className = 'size-4'): React.ReactNode | null {
+  if (!icon) return null
+  const normalized = icon.trim()
+  if (!normalized) return null
+
+  const candidates = [normalized, toPascalCaseIconName(normalized)]
+  const registry = LucideIcons as unknown as Record<string, LucideIconComponent | undefined>
+
+  for (const candidate of candidates) {
+    const IconComponent = registry[candidate]
+    if (!IconComponent) continue
+    return <IconComponent className={className} />
+  }
+
+  return null
+}

package/src/backend/injection/spotIds.ts

@@ -0,0 +1,64 @@
+import type { InjectionSpotId } from '@open-mercato/shared/modules/widgets/injection'
+
+export const BACKEND_RECORD_CURRENT_INJECTION_SPOT_ID: InjectionSpotId = 'backend:record:current'
+export const BACKEND_LAYOUT_TOP_INJECTION_SPOT_ID: InjectionSpotId = 'backend:layout:top'
+export const BACKEND_LAYOUT_FOOTER_INJECTION_SPOT_ID: InjectionSpotId = 'backend:layout:footer'
+export const BACKEND_SIDEBAR_TOP_INJECTION_SPOT_ID: InjectionSpotId = 'backend:sidebar:top'
+export const BACKEND_SIDEBAR_FOOTER_INJECTION_SPOT_ID: InjectionSpotId = 'backend:sidebar:footer'
+
+// Standardized backend chrome spot ids
+export const BACKEND_TOPBAR_PROFILE_MENU_INJECTION_SPOT_ID: InjectionSpotId = 'backend:topbar:profile-menu'
+export const BACKEND_TOPBAR_ACTIONS_INJECTION_SPOT_ID: InjectionSpotId = 'backend:topbar:actions'
+export const BACKEND_SIDEBAR_NAV_INJECTION_SPOT_ID: InjectionSpotId = 'backend:sidebar:nav'
+export const BACKEND_SIDEBAR_NAV_FOOTER_INJECTION_SPOT_ID: InjectionSpotId = 'backend:sidebar:nav:footer'
+
+// Standardized global status spot ids
+export const GLOBAL_SIDEBAR_STATUS_BADGES_INJECTION_SPOT_ID: InjectionSpotId = 'global:sidebar:status-badges'
+export const GLOBAL_HEADER_STATUS_INDICATORS_INJECTION_SPOT_ID: InjectionSpotId = 'global:header:status-indicators'
+
+// Standardized pattern helpers
+export const CrudFormInjectionSpots = {
+  base: (entityId: string): InjectionSpotId => `crud-form:${entityId}`,
+  beforeFields: (entityId: string): InjectionSpotId => `crud-form:${entityId}:before-fields`,
+  afterFields: (entityId: string): InjectionSpotId => `crud-form:${entityId}:after-fields`,
+  header: (entityId: string): InjectionSpotId => `crud-form:${entityId}:header`,
+  footer: (entityId: string): InjectionSpotId => `crud-form:${entityId}:footer`,
+  sidebar: (entityId: string): InjectionSpotId => `crud-form:${entityId}:sidebar`,
+  group: (entityId: string, groupId: string): InjectionSpotId => `crud-form:${entityId}:group:${groupId}`,
+  fieldBefore: (entityId: string, fieldId: string): InjectionSpotId => `crud-form:${entityId}:field:${fieldId}:before`,
+  fieldAfter: (entityId: string, fieldId: string): InjectionSpotId => `crud-form:${entityId}:field:${fieldId}:after`,
+} as const
+
+export const DataTableInjectionSpots = {
+  header: (tableId: string): InjectionSpotId => `data-table:${tableId}:header`,
+  footer: (tableId: string): InjectionSpotId => `data-table:${tableId}:footer`,
+  toolbar: (tableId: string): InjectionSpotId => `data-table:${tableId}:toolbar`,
+  emptyState: (tableId: string): InjectionSpotId => `data-table:${tableId}:empty-state`,
+  columns: (tableId: string): InjectionSpotId => `data-table:${tableId}:columns`,
+  rowActions: (tableId: string): InjectionSpotId => `data-table:${tableId}:row-actions`,
+  bulkActions: (tableId: string): InjectionSpotId => `data-table:${tableId}:bulk-actions`,
+  filters: (tableId: string): InjectionSpotId => `data-table:${tableId}:filters`,
+} as const
+
+// Portal chrome spot IDs (FROZEN once shipped)
+export const PORTAL_SIDEBAR_MAIN_INJECTION_SPOT_ID: InjectionSpotId = 'menu:portal:sidebar:main'
+export const PORTAL_SIDEBAR_ACCOUNT_INJECTION_SPOT_ID: InjectionSpotId = 'menu:portal:sidebar:account'
+export const PORTAL_HEADER_ACTIONS_INJECTION_SPOT_ID: InjectionSpotId = 'menu:portal:header:actions'
+export const PORTAL_USER_DROPDOWN_INJECTION_SPOT_ID: InjectionSpotId = 'menu:portal:user-dropdown'
+
+// Portal page injection spots (FROZEN once shipped)
+export const PortalInjectionSpots = {
+  dashboardSections: 'portal:dashboard:sections' as InjectionSpotId,
+  dashboardProfile: 'portal:dashboard:profile' as InjectionSpotId,
+  dashboardSidebar: 'portal:dashboard:sidebar' as InjectionSpotId,
+  pageBefore: (pageId: string): InjectionSpotId => `portal:${pageId}:before` as InjectionSpotId,
+  pageAfter: (pageId: string): InjectionSpotId => `portal:${pageId}:after` as InjectionSpotId,
+} as const
+
+export const DetailInjectionSpots = {
+  header: (entityId: string): InjectionSpotId => `detail:${entityId}:header`,
+  tabs: (entityId: string): InjectionSpotId => `detail:${entityId}:tabs`,
+  sidebar: (entityId: string): InjectionSpotId => `detail:${entityId}:sidebar`,
+  footer: (entityId: string): InjectionSpotId => `detail:${entityId}:footer`,
+  statusBadges: (entityId: string): InjectionSpotId => `detail:${entityId}:status-badges`,
+} as const

package/src/backend/injection/useAppEvent.ts

@@ -0,0 +1,76 @@
+"use client"
+import { useEffect, useRef } from 'react'
+import type { AppEventPayload } from '@open-mercato/shared/modules/widgets/injection'
+
+/**
+ * DOM Event Bridge event name.
+ * Server-side events with `clientBroadcast: true` are dispatched as
+ * CustomEvents with this name on the window object.
+ */
+export const APP_EVENT_DOM_NAME = 'om:event'
+
+/**
+ * Match an event ID against a wildcard pattern.
+ *
+ * Supports:
+ * - Exact match: `'example.todo.created'`
+ * - Wildcard suffix: `'example.todo.*'` matches `'example.todo.created'`, `'example.todo.updated'`
+ * - Global wildcard: `'*'` matches everything
+ *
+ * @example
+ * matchesPattern('example.todo.*', 'example.todo.created') // true
+ * matchesPattern('example.todo.*', 'example.item.created') // false
+ * matchesPattern('*', 'anything.here') // true
+ */
+export function matchesPattern(pattern: string, eventId: string): boolean {
+  if (pattern === '*') return true
+  if (!pattern.includes('*')) return pattern === eventId
+  const escapedPattern = pattern
+    .replace(/[|\\{}()[\]^$+?.]/g, '\\$&')
+    .replace(/\*/g, '.*')
+  const regex = new RegExp(
+    '^' + escapedPattern + '$',
+  )
+  return regex.test(eventId)
+}
+
+/**
+ * React hook that listens for app events delivered via the DOM Event Bridge.
+ *
+ * Events are dispatched as `om:event` CustomEvents on `window` by the event bridge
+ * (see `eventBridge.ts`). This hook filters events by pattern and calls the handler.
+ *
+ * @param eventPattern - Pattern to match event IDs against (e.g., 'example.todo.*')
+ * @param handler - Callback invoked when a matching event arrives
+ * @param deps - Optional dependency array for the handler (defaults to [])
+ *
+ * @example
+ * useAppEvent('example.todo.*', (event) => {
+ *   console.log('Todo event:', event.id, event.payload)
+ *   setRefreshKey(k => k + 1)
+ * })
+ */
+export function useAppEvent(
+  eventPattern: string,
+  handler: (payload: AppEventPayload) => void,
+  deps: unknown[] = [],
+): void {
+  const handlerRef = useRef(handler)
+  handlerRef.current = handler
+
+  useEffect(() => {
+    const listener = (e: Event) => {
+      const detail = (e as CustomEvent<AppEventPayload>).detail
+      if (!detail || typeof detail.id !== 'string') return
+      if (matchesPattern(eventPattern, detail.id)) {
+        handlerRef.current(detail)
+      }
+    }
+
+    window.addEventListener(APP_EVENT_DOM_NAME, listener)
+    return () => {
+      window.removeEventListener(APP_EVENT_DOM_NAME, listener)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [eventPattern, ...deps])
+}

package/src/backend/injection/useGuardedMutation.ts

@@ -0,0 +1,101 @@
+"use client"
+
+import * as React from 'react'
+import { useInjectionSpotEvents } from './InjectionSpot'
+import { GLOBAL_MUTATION_INJECTION_SPOT_ID, dispatchBackendMutationError } from './mutationEvents'
+import { withScopedApiRequestHeaders } from '../utils/apiCall'
+
+type GuardedMutationContext = Record<string, unknown>
+
+type GuardedMutationRunInput<TResult, TContext extends GuardedMutationContext> = {
+  operation: () => Promise<TResult>
+  context: TContext
+  mutationPayload?: Record<string, unknown>
+}
+
+type UseGuardedMutationOptions = {
+  contextId: string
+  blockedMessage?: string
+  spotId?: string
+}
+
+type StoredMutation<TContext extends GuardedMutationContext> = {
+  operation: () => Promise<unknown>
+  context: TContext
+  mutationPayload: Record<string, unknown>
+}
+
+export function useGuardedMutation<TContext extends GuardedMutationContext>({
+  contextId,
+  blockedMessage = 'Save blocked by validation',
+  spotId = GLOBAL_MUTATION_INJECTION_SPOT_ID,
+}: UseGuardedMutationOptions) {
+  const { triggerEvent } = useInjectionSpotEvents<TContext, Record<string, unknown>>(spotId)
+  const lastMutationRef = React.useRef<StoredMutation<TContext> | null>(null)
+
+  const emitMutationSaveError = React.useCallback((error: unknown) => {
+    dispatchBackendMutationError({
+      contextId,
+      formId: contextId,
+      error,
+    })
+  }, [contextId])
+
+  const runMutation = React.useCallback(async <TResult,>({
+    operation,
+    context,
+    mutationPayload,
+  }: GuardedMutationRunInput<TResult, TContext>): Promise<TResult> => {
+    const payload = mutationPayload ?? {}
+    lastMutationRef.current = {
+      operation: operation as () => Promise<unknown>,
+      context,
+      mutationPayload: payload,
+    }
+
+    const beforeSave = await triggerEvent('onBeforeSave', payload, context)
+    if (!beforeSave.ok) {
+      emitMutationSaveError(beforeSave.details ?? beforeSave)
+      throw new Error(beforeSave.message || blockedMessage)
+    }
+
+    try {
+      const result =
+        beforeSave.requestHeaders && Object.keys(beforeSave.requestHeaders).length > 0
+          ? await withScopedApiRequestHeaders(beforeSave.requestHeaders, operation)
+          : await operation()
+
+      try {
+        await triggerEvent('onAfterSave', payload, context)
+      } catch (error) {
+        console.error('[useGuardedMutation] Error in onAfterSave injection event:', error)
+      }
+
+      return result
+    } catch (error) {
+      emitMutationSaveError(error)
+      throw error
+    }
+  }, [blockedMessage, emitMutationSaveError, triggerEvent])
+
+  const retryLastMutation = React.useCallback(async (): Promise<boolean> => {
+    const lastMutation = lastMutationRef.current
+    if (!lastMutation) return false
+
+    try {
+      await runMutation({
+        operation: lastMutation.operation,
+        context: lastMutation.context,
+        mutationPayload: lastMutation.mutationPayload,
+      })
+      return true
+    } catch {
+      return false
+    }
+  }, [runMutation])
+
+  return {
+    runMutation,
+    retryLastMutation,
+  }
+}

package/src/backend/injection/useInjectedMenuItems.ts

@@ -0,0 +1,67 @@
+'use client'
+
+import * as React from 'react'
+import type { InjectionMenuItem } from '@open-mercato/shared/modules/widgets/injection'
+import { hasAllFeatures } from '@open-mercato/shared/security/features'
+import { useInjectionDataWidgets } from './useInjectionDataWidgets'
+import { useBackendChrome } from '../BackendChromeProvider'
+
+export type MenuSurfaceId =
+  | 'menu:sidebar:main'
+  | 'menu:sidebar:settings'
+  | 'menu:sidebar:profile'
+  | 'menu:topbar:profile-dropdown'
+  | 'menu:topbar:actions'
+  | `menu:sidebar:settings:${string}`
+  | `menu:sidebar:main:${string}`
+  | `menu:${string}`
+
+export function useInjectedMenuItems(surfaceId: MenuSurfaceId): {
+  items: InjectionMenuItem[]
+  isLoading: boolean
+} {
+  const { widgets, isLoading } = useInjectionDataWidgets(surfaceId)
+  const { payload, isReady } = useBackendChrome()
+  const grantedFeatureList = React.useMemo(
+    () => payload?.grantedFeatures ?? [],
+    [payload?.grantedFeatures],
+  )
+  const userRoles = React.useMemo(
+    () => new Set(payload?.roles ?? []),
+    [payload?.roles],
+  )
+
+  const rawItems = React.useMemo(() => {
+    const entries: InjectionMenuItem[] = []
+    for (const widget of widgets) {
+      if (!('menuItems' in widget)) continue
+      const metadataFeatures = widget.metadata.features ?? []
+      for (const menuItem of widget.menuItems) {
+        const features = [...metadataFeatures, ...(menuItem.features ?? [])]
+        const normalizedLabelKey =
+          menuItem.labelKey ??
+          (typeof menuItem.label === 'string' && menuItem.label.includes('.') ? menuItem.label : undefined)
+        entries.push({
+          ...menuItem,
+          labelKey: normalizedLabelKey,
+          features,
+        })
+      }
+    }
+    return entries
+  }, [widgets])
+
+  const items = React.useMemo(
+    () =>
+      rawItems.filter((item) => {
+        const features = item.features ?? []
+        const roles = item.roles ?? []
+        const featuresOk = features.length === 0 || hasAllFeatures(grantedFeatureList, features)
+        const rolesOk = roles.length === 0 || roles.some((role) => userRoles.has(role))
+        return featuresOk && rolesOk
+      }),
+    [rawItems, grantedFeatureList, userRoles],
+  )
+
+  return { items, isLoading: isLoading || !isReady }
+}

package/src/backend/injection/useInjectionDataWidgets.ts

@@ -0,0 +1,41 @@
+'use client'
+
+import * as React from 'react'
+import type { InjectionSpotId } from '@open-mercato/shared/modules/widgets/injection'
+import { loadInjectionDataWidgetsForSpot, type LoadedInjectionDataWidget } from '@open-mercato/shared/modules/widgets/injection-loader'
+
+export function useInjectionDataWidgets(spotId: InjectionSpotId): {
+  widgets: LoadedInjectionDataWidget[]
+  isLoading: boolean
+  error: string | null
+} {
+  const [widgets, setWidgets] = React.useState<LoadedInjectionDataWidget[]>([])
+  const [isLoading, setIsLoading] = React.useState(true)
+  const [error, setError] = React.useState<string | null>(null)
+
+  React.useEffect(() => {
+    let mounted = true
+    const load = async () => {
+      try {
+        setIsLoading(true)
+        setError(null)
+        const loaded = await loadInjectionDataWidgetsForSpot(spotId)
+        if (!mounted) return
+        setWidgets(loaded)
+      } catch (loadError) {
+        if (!mounted) return
+        console.error(`[useInjectionDataWidgets] Failed to load widgets for spot ${spotId}:`, loadError)
+        setError(loadError instanceof Error ? loadError.message : String(loadError))
+        setWidgets([])
+      } finally {
+        if (mounted) setIsLoading(false)
+      }
+    }
+    void load()
+    return () => {
+      mounted = false
+    }
+  }, [spotId])
+
+  return { widgets, isLoading, error }
+}