@open-mercato/ui 0.6.7 → 0.6.8-develop.6874.1.982d6097d8

package/src/backend/utils/__tests__/fetchAllPages.test.ts

@@ -0,0 +1,103 @@
+/** @jest-environment node */
+
+const apiCall = jest.fn()
+
+jest.mock('../apiCall', () => ({
+  apiCall: (...args: unknown[]) => apiCall(...args),
+}))
+
+import { fetchAllOffsetPages, MAX_OFFSET_PAGES } from '../fetchAllPages'
+
+const okPage = (payload: Record<string, unknown>) => ({ ok: true, result: payload })
+
+const requestedUrls = () => apiCall.mock.calls.map(([url]) => url as string)
+
+describe('fetchAllOffsetPages', () => {
+  beforeEach(() => {
+    apiCall.mockReset()
+  })
+
+  it('issues a single untouched request when the route does not report hasMore', async () => {
+    apiCall.mockResolvedValueOnce(okPage({ items: [{ value: 'a' }, { value: 'b' }] }))
+
+    const result = await fetchAllOffsetPages('/api/options')
+
+    expect(requestedUrls()).toEqual(['/api/options'])
+    expect(result.ok).toBe(true)
+    expect(result.pageCount).toBe(1)
+    expect(result.items).toEqual([{ value: 'a' }, { value: 'b' }])
+  })
+
+  it('walks hasMore, advancing the offset by the rows already collected', async () => {
+    apiCall
+      .mockResolvedValueOnce(okPage({ items: [{ value: 'a' }, { value: 'b' }], hasMore: true }))
+      .mockResolvedValueOnce(okPage({ items: [{ value: 'c' }], hasMore: false }))
+
+    const result = await fetchAllOffsetPages('/api/options')
+
+    expect(requestedUrls()).toEqual(['/api/options', '/api/options?offset=2'])
+    expect(result.items).toHaveLength(3)
+    expect(result.pageCount).toBe(2)
+  })
+
+  it('preserves the caller query string when it appends the offset', async () => {
+    apiCall
+      .mockResolvedValueOnce(okPage({ items: [{ value: 'a' }], hasMore: true }))
+      .mockResolvedValueOnce(okPage({ items: [{ value: 'b' }], hasMore: false }))
+
+    await fetchAllOffsetPages('/api/options?query=ab&q=ab')
+
+    expect(requestedUrls()[1]).toBe('/api/options?query=ab&q=ab&offset=1')
+  })
+
+  it('continues from an offset the caller already put on the url', async () => {
+    apiCall
+      .mockResolvedValueOnce(okPage({ items: [{ value: 'a' }], hasMore: true }))
+      .mockResolvedValueOnce(okPage({ items: [{ value: 'b' }], hasMore: false }))
+
+    await fetchAllOffsetPages('/api/options?offset=10')
+
+    expect(requestedUrls()).toEqual(['/api/options?offset=10', '/api/options?offset=11'])
+  })
+
+  it('exposes the first payload so callers can read page-invariant metadata', async () => {
+    apiCall
+      .mockResolvedValueOnce(okPage({ items: [{ value: 'a' }], hasMore: true, sortMode: 'value_desc' }))
+      .mockResolvedValueOnce(okPage({ items: [{ value: 'b' }], hasMore: false, sortMode: 'value_desc' }))
+
+    const result = await fetchAllOffsetPages('/api/options')
+
+    expect(result.firstPayload.sortMode).toBe('value_desc')
+  })
+
+  it('stops on an empty page so a route reporting hasMore forever cannot spin', async () => {
+    apiCall
+      .mockResolvedValueOnce(okPage({ items: [{ value: 'a' }], hasMore: true }))
+      .mockResolvedValueOnce(okPage({ items: [], hasMore: true }))
+
+    const result = await fetchAllOffsetPages('/api/options')
+
+    expect(apiCall).toHaveBeenCalledTimes(2)
+    expect(result.items).toHaveLength(1)
+  })
+
+  it('caps the walk at the page ceiling', async () => {
+    apiCall.mockResolvedValue(okPage({ items: [{ value: 'a' }], hasMore: true }))
+
+    const result = await fetchAllOffsetPages('/api/options')
+
+    expect(apiCall).toHaveBeenCalledTimes(MAX_OFFSET_PAGES)
+    expect(result.pageCount).toBe(MAX_OFFSET_PAGES)
+  })
+
+  it('reports a failed page instead of returning a silently truncated list', async () => {
+    apiCall
+      .mockResolvedValueOnce(okPage({ items: [{ value: 'a' }], hasMore: true }))
+      .mockResolvedValueOnce({ ok: false, result: { error: 'Forbidden' } })
+
+    const result = await fetchAllOffsetPages('/api/options')
+
+    expect(result.ok).toBe(false)
+    expect(result.errorPayload).toEqual({ error: 'Forbidden' })
+  })
+})

package/src/backend/utils/apiCall.ts

@@ -19,6 +19,27 @@ export type ApiCallResult<TReturn> = {
 
 const scopedRequestHeaders = createScopedHeaderStack()
 
+function isAbortError(error: unknown): boolean {
+  return typeof error === 'object'
+    && error !== null
+    && (error as { name?: unknown }).name === 'AbortError'
+}
+
+function createAbortError(): Error {
+  if (typeof DOMException === 'function') {
+    return new DOMException('[internal] The operation was aborted.', 'AbortError')
+  }
+  const error = new Error('[internal] The operation was aborted.')
+  error.name = 'AbortError'
+  return error
+}
+
+function resolveAbortSignal(input: RequestInfo | URL, init?: RequestInit): AbortSignal | null {
+  if (init?.signal) return init.signal
+  if (typeof Request !== 'undefined' && input instanceof Request) return input.signal ?? null
+  return null
+}
+
 function mergeHeaders(base: HeadersInit | undefined, extra: Record<string, string>): HeadersInit {
   if (!base) return extra
   if (typeof Headers !== 'undefined' && base instanceof Headers) {
@@ -63,9 +84,16 @@ export async function apiCall<TReturn = Record<string, unknown>>(
       : response
     if (parser) result = await parser(source)
     else result = await readJsonSafe<TReturn>(source, fallback)
-  } catch {
+  } catch (err) {
+    if (isAbortError(err)) throw err
     result = fallback
   }
+  // `readJsonSafe` swallows the abort that cancels an in-flight body read, so a
+  // request aborted after its response headers arrived would otherwise look like
+  // a successful call that returned an empty payload.
+  if (result == null && resolveAbortSignal(input, init)?.aborted) {
+    throw createAbortError()
+  }
   return {
     ok: response.ok,
     status: response.status,

package/src/backend/utils/customFieldDefs.ts

@@ -39,6 +39,7 @@ export type CustomFieldDefDto = {
   dictionaryId?: string
   dictionaryInlineCreate?: boolean
   defaultValue?: string | number | boolean | null
+  relatedEntityId?: string
 }
 
 export type CustomFieldsetGroupDto = {

package/src/backend/utils/customFieldForms.ts

@@ -9,7 +9,7 @@ import {
   fetchCustomFieldDefinitionsPayload,
 } from './customFieldDefs'
 import { FieldRegistry, loadGeneratedFieldRegistrations } from '../fields/registry'
-import { apiCall } from './apiCall'
+import { fetchAllOffsetPages } from './fetchAllPages'
 import { normalizeCustomFieldOptions } from '@open-mercato/shared/modules/entities/options'
 import { CURRENCY_OPTIONS_URL } from '@open-mercato/shared/modules/entities/kinds'
 
@@ -42,18 +42,22 @@ function buildOptionsUrl(base: string, query?: string): string {
   }
 }
 
-type OptionsResponse = { items?: unknown[] }
-
 async function loadRemoteOptions(url: string): Promise<Array<{ value: string; label: string }>> {
   try {
-    const call = await apiCall<OptionsResponse>(url, undefined, { fallback: { items: [] } })
-    if (!call.ok) return []
-    const payload = call.result ?? { items: [] }
-    const items = Array.isArray(payload?.items) ? payload.items : []
-    return items.map((it: any) => ({
-      value: String(it?.value ?? it),
-      label: String(it?.label ?? it?.value ?? it),
-    }))
+    // Options routes bound how many rows one response carries (dictionary
+    // entries at 500), so walk every page instead of reading a single
+    // response — a stored value past the first page must stay selectable and
+    // resolvable to its label. Routes without `hasMore` still resolve in one
+    // request.
+    const pages = await fetchAllOffsetPages(url)
+    if (!pages.ok) return []
+    return pages.items.map((item) => {
+      const record = item && typeof item === 'object' ? (item as Record<string, unknown>) : null
+      return {
+        value: String(record?.value ?? item),
+        label: String(record?.label ?? record?.value ?? item),
+      }
+    })
   } catch {
     return []
   }

package/src/backend/utils/fetchAllPages.ts

@@ -0,0 +1,93 @@
+"use client"
+
+import { apiCall } from './apiCall'
+
+// Offset-paged list routes cap how many rows one response may carry, so a
+// caller that needs the whole collection has to walk the pages. Bound the walk
+// so a route reporting hasMore forever cannot hang the caller; at the 500-row
+// dictionary ceiling this still covers 25k rows.
+export const MAX_OFFSET_PAGES = 50
+
+export type OffsetPagedPayload = Record<string, unknown>
+
+export type OffsetPagedResult = {
+  ok: boolean
+  items: unknown[]
+  pageCount: number
+  firstPayload: OffsetPagedPayload
+  errorPayload: OffsetPagedPayload | null
+}
+
+const ABSOLUTE_URL_PATTERN = /^([a-z][a-z\d+\-.]*:)?\/\//i
+
+type ParsedUrl = { url: URL; absolute: boolean }
+
+function parseUrl(value: string): ParsedUrl | null {
+  try {
+    const absolute = ABSOLUTE_URL_PATTERN.test(value)
+    const origin = typeof window !== 'undefined' ? window.location.origin : 'http://localhost'
+    return { url: absolute ? new URL(value) : new URL(value, origin), absolute }
+  } catch {
+    return null
+  }
+}
+
+function formatUrl(parsed: ParsedUrl): string {
+  return parsed.absolute ? parsed.url.toString() : `${parsed.url.pathname}${parsed.url.search}`
+}
+
+function readOffset(value: string): number {
+  const parsed = parseUrl(value)
+  if (!parsed) return 0
+  const offset = Number.parseInt(parsed.url.searchParams.get('offset') ?? '', 10)
+  return Number.isFinite(offset) && offset > 0 ? offset : 0
+}
+
+function withOffset(value: string, offset: number): string {
+  const parsed = parseUrl(value)
+  if (!parsed) {
+    const separator = value.includes('?') ? '&' : '?'
+    return `${value}${separator}offset=${offset}`
+  }
+  parsed.url.searchParams.set('offset', String(offset))
+  return formatUrl(parsed)
+}
+
+/**
+ * Walk every page of an offset-paged list route and return the assembled items.
+ *
+ * A route that does not report `hasMore` resolves after a single request, so
+ * this is a drop-in replacement for a one-shot `apiCall` against any list
+ * endpoint. Ordering is preserved as the route returned it, page after page —
+ * callers that need a global order across page boundaries must re-sort.
+ */
+export async function fetchAllOffsetPages(
+  url: string,
+  options: { maxPages?: number } = {},
+): Promise<OffsetPagedResult> {
+  const maxPages = options.maxPages ?? MAX_OFFSET_PAGES
+  const baseOffset = readOffset(url)
+  const items: unknown[] = []
+  let firstPayload: OffsetPagedPayload = {}
+  let pageCount = 0
+
+  while (pageCount < maxPages) {
+    // The first request goes out untouched so a route that caches only its
+    // default page still serves that page from cache.
+    const pageUrl = pageCount === 0 ? url : withOffset(url, baseOffset + items.length)
+    const call = await apiCall<OffsetPagedPayload>(pageUrl, undefined, { fallback: {} })
+    const payload = call.result ?? {}
+    if (!call.ok) {
+      return { ok: false, items, pageCount, firstPayload, errorPayload: payload }
+    }
+    pageCount += 1
+    if (pageCount === 1) firstPayload = payload
+    const pageItems = Array.isArray(payload.items) ? payload.items : []
+    items.push(...pageItems)
+    // An empty page also stops the walk: without it a route that keeps
+    // reporting hasMore while returning nothing would spin to the page cap.
+    if (payload.hasMore !== true || pageItems.length === 0) break
+  }
+
+  return { ok: true, items, pageCount, firstPayload, errorPayload: null }
+}

package/src/backend/utils/nav.ts

@@ -100,6 +100,26 @@ export type SettingsSectionItem = {
   children?: SettingsSectionItem[]
 }
 
+/**
+ * Slug of a rendered group label, used as the pre-#4843 settings section id.
+ *
+ * `sectionOrder` used to be keyed by these slugs, which made ordering depend on the active locale.
+ * Kept only as a lookup fallback so third-party callers passing a legacy map keep their weights.
+ *
+ * @deprecated Key `sectionOrder` by the untranslated group id (`AdminNavItem.groupId`) instead.
+ */
+function legacySettingsSectionSlug(groupLabel: string): string {
+  return groupLabel.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '')
+}
+
+/**
+ * Groups the settings-context nav entries into ordered sections.
+ *
+ * `sectionOrder` is keyed by the untranslated group id (`AdminNavItem.groupId`, i.e. the page's
+ * `pageGroupKey` when it declares one) — the same convention the main sidebar's `defaultGroupOrder`
+ * follows. Keying off the rendered label instead made every non-English deployment miss its weights
+ * and fall back to the catch-all bucket (#4843).
+ */
 export function buildSettingsSections(
   entries: AdminNavItem[],
   sectionOrder: Record<string, number>
@@ -123,8 +143,8 @@ export function buildSettingsSections(
   }
 
   for (const item of settingsItems) {
-    const sectionId = item.group.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '')
-    const order = sectionOrder[sectionId] ?? 999
+    const sectionId = item.groupId
+    const order = sectionOrder[sectionId] ?? sectionOrder[legacySettingsSectionSlug(item.group)] ?? 999
 
     if (!sectionMap.has(sectionId)) {
       sectionMap.set(sectionId, {

package/src/backend/version-history/VersionHistoryPanel.tsx

@@ -192,7 +192,7 @@ export function VersionHistoryPanel({
             ) : (
               <div className="space-y-3">
                 {shouldAutoCheck && !permissions.isLoading && !permissions.canViewTenant && permissions.currentUserId ? (
-                  <Alert variant="info">
+                  <Alert status="information">
                     <AlertDescription>
                       {t('audit_logs.hint.view_self_only', 'Showing only your own changes. Contact an administrator for broader access.')}
                     </AlertDescription>

package/src/frontend/LanguageSwitcher.tsx

@@ -24,6 +24,7 @@ export function LanguageSwitcher() {
     pl: t('common.languages.polish', 'Polski'),
     es: t('common.languages.spanish', 'Español'),
     de: t('common.languages.german', 'Deutsch'),
+    ko: t('common.languages.korean', '한국어'),
   }
 
   async function setLocale(locale: Locale) {

package/src/portal/PortalContext.tsx

@@ -91,7 +91,7 @@ export function PortalProvider({ orgSlug, children, initialAuth, initialTenant }
         },
         roles: [],
         resolvedFeatures: initialAuth.resolvedFeatures,
-        isPortalAdmin: initialAuth.resolvedFeatures.some((f) => f === 'portal.*'),
+        isPortalAdmin: initialAuth.isPortalAdmin === true,
         loading: false,
         error: null,
       }

package/src/portal/hooks/__tests__/usePortalEventBridge.test.tsx

@@ -0,0 +1,66 @@
+/** @jest-environment jsdom */
+import { act, renderHook } from '@testing-library/react'
+import { usePortalEventBridge } from '../usePortalEventBridge'
+import {
+  clearPortalBridgeHealth,
+  PORTAL_BRIDGE_STATUS_DOM_NAME,
+  readPortalBridgeHealth,
+  type PortalBridgeStatusDetail,
+} from '../portalBridgeStatus'
+
+class EventSourceMock {
+  static instances: EventSourceMock[] = []
+
+  onopen: ((event: Event) => void) | null = null
+  onmessage: ((event: MessageEvent) => void) | null = null
+  onerror: ((event: Event) => void) | null = null
+  close = jest.fn()
+
+  constructor() {
+    EventSourceMock.instances.push(this)
+  }
+}
+
+describe('usePortalEventBridge health lifecycle', () => {
+  const originalEventSource = globalThis.window?.EventSource
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    EventSourceMock.instances = []
+    clearPortalBridgeHealth()
+    ;(window as unknown as { EventSource?: typeof EventSource }).EventSource = EventSourceMock as unknown as typeof EventSource
+  })
+
+  afterEach(() => {
+    clearPortalBridgeHealth()
+    if (typeof originalEventSource === 'undefined') {
+      delete (window as unknown as { EventSource?: typeof EventSource }).EventSource
+    } else {
+      ;(window as unknown as { EventSource?: typeof EventSource }).EventSource = originalEventSource
+    }
+  })
+
+  it('publishes healthy on open and unhealthy when the bridge unmounts', () => {
+    const statuses: boolean[] = []
+    const handleStatus = (event: Event) => {
+      statuses.push((event as CustomEvent<PortalBridgeStatusDetail>).detail.healthy)
+    }
+    window.addEventListener(PORTAL_BRIDGE_STATUS_DOM_NAME, handleStatus)
+
+    const { unmount } = renderHook(() => usePortalEventBridge())
+    const source = EventSourceMock.instances[0]
+    expect(source).toBeDefined()
+
+    act(() => {
+      source.onopen?.(new Event('open'))
+    })
+    expect(readPortalBridgeHealth()).toBe(true)
+
+    unmount()
+
+    expect(source.close).toHaveBeenCalledTimes(1)
+    expect(readPortalBridgeHealth()).toBe(false)
+    expect(statuses).toEqual([true, false])
+    window.removeEventListener(PORTAL_BRIDGE_STATUS_DOM_NAME, handleStatus)
+  })
+})

package/src/portal/hooks/__tests__/usePortalNotifications.test.tsx

@@ -0,0 +1,155 @@
+/** @jest-environment jsdom */
+import * as React from 'react'
+import { renderHook, act, waitFor } from '@testing-library/react'
+import { usePortalNotifications } from '../usePortalNotifications'
+import {
+  clearPortalBridgeHealth,
+  publishPortalBridgeHealth,
+} from '../portalBridgeStatus'
+
+const apiCallMock = jest.fn()
+
+jest.mock('../../../backend/utils/apiCall', () => ({
+  apiCall: (...args: unknown[]) => apiCallMock(...args),
+}))
+
+describe('usePortalNotifications strategy', () => {
+  const originalEventSource = globalThis.window?.EventSource
+  let setIntervalSpy: jest.SpyInstance
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    apiCallMock.mockResolvedValue({
+      ok: true,
+      result: { ok: true, items: [], unreadCount: 0 },
+    })
+    setIntervalSpy = jest.spyOn(global, 'setInterval')
+    clearPortalBridgeHealth()
+  })
+
+  afterEach(() => {
+    setIntervalSpy.mockRestore()
+    if (typeof originalEventSource === 'undefined') {
+      delete (window as unknown as { EventSource?: typeof EventSource }).EventSource
+    } else {
+      ;(window as unknown as { EventSource?: typeof EventSource }).EventSource = originalEventSource
+    }
+  })
+
+  it('keeps polling until an available EventSource bridge reports healthy', async () => {
+    ;(window as unknown as { EventSource?: typeof EventSource }).EventSource = function EventSourceMock() {
+      return {} as EventSource
+    } as unknown as typeof EventSource
+
+    const { result } = renderHook(() => usePortalNotifications())
+    await waitFor(() => expect(result.current.isLoading).toBe(false))
+
+    expect(apiCallMock).toHaveBeenCalled()
+    expect(setIntervalSpy).toHaveBeenCalledWith(expect.any(Function), 8000)
+  })
+
+  it('uses SSE strategy without polling when the bridge is explicitly healthy', async () => {
+    ;(window as unknown as { EventSource?: typeof EventSource }).EventSource = function EventSourceMock() {
+      return {} as EventSource
+    } as unknown as typeof EventSource
+    publishPortalBridgeHealth(true)
+
+    const { result } = renderHook(() => usePortalNotifications())
+    await waitFor(() => expect(result.current.isLoading).toBe(false))
+
+    expect(apiCallMock).toHaveBeenCalled()
+    expect(setIntervalSpy).not.toHaveBeenCalledWith(expect.any(Function), 8000)
+  })
+
+  it('falls back to polling strategy when EventSource is unavailable', async () => {
+    delete (window as unknown as { EventSource?: typeof EventSource }).EventSource
+
+    const { result } = renderHook(() => usePortalNotifications())
+    await waitFor(() => expect(result.current.isLoading).toBe(false))
+
+    expect(apiCallMock).toHaveBeenCalled()
+    expect(setIntervalSpy).toHaveBeenCalledWith(expect.any(Function), 8000)
+  })
+
+  it('activates polling when SSE is explicitly marked unhealthy', async () => {
+    ;(window as unknown as { EventSource?: typeof EventSource }).EventSource = function EventSourceMock() {
+      return {} as EventSource
+    } as unknown as typeof EventSource
+
+    publishPortalBridgeHealth(false)
+
+    const { result } = renderHook(() => usePortalNotifications())
+    await waitFor(() => expect(result.current.isLoading).toBe(false))
+
+    expect(setIntervalSpy).toHaveBeenCalledWith(expect.any(Function), 8000)
+  })
+
+  it('switches to polling fallback dynamically when status becomes unhealthy', async () => {
+    ;(window as unknown as { EventSource?: typeof EventSource }).EventSource = function EventSourceMock() {
+      return {} as EventSource
+    } as unknown as typeof EventSource
+    publishPortalBridgeHealth(true)
+
+    const { result } = renderHook(() => usePortalNotifications())
+    await waitFor(() => expect(result.current.isLoading).toBe(false))
+    expect(apiCallMock).toHaveBeenCalledTimes(2)
+
+    expect(setIntervalSpy).not.toHaveBeenCalledWith(expect.any(Function), 8000)
+
+    act(() => {
+      publishPortalBridgeHealth(false)
+    })
+
+    expect(setIntervalSpy).toHaveBeenCalledWith(expect.any(Function), 8000)
+    await waitFor(() => expect(apiCallMock).toHaveBeenCalledTimes(4))
+  })
+
+  it('performs one reconciliation for an unhealthy-to-reconnected sequence', async () => {
+    ;(window as unknown as { EventSource?: typeof EventSource }).EventSource = function EventSourceMock() {
+      return {} as EventSource
+    } as unknown as typeof EventSource
+    publishPortalBridgeHealth(true)
+
+    const { result } = renderHook(() => usePortalNotifications())
+    await waitFor(() => expect(result.current.isLoading).toBe(false))
+    expect(apiCallMock).toHaveBeenCalledTimes(2)
+
+    act(() => {
+      publishPortalBridgeHealth(false)
+    })
+    await waitFor(() => expect(apiCallMock).toHaveBeenCalledTimes(4))
+
+    act(() => {
+      publishPortalBridgeHealth(true)
+      window.dispatchEvent(
+        new CustomEvent('om:portal-event', {
+          detail: {
+            id: 'om:portal-bridge:reconnected',
+            payload: {},
+          },
+        })
+      )
+    })
+
+    await waitFor(() => expect(apiCallMock).toHaveBeenCalledTimes(6))
+  })
+
+  it('reconciles notifications when the portal window regains focus', async () => {
+    ;(window as unknown as { EventSource?: typeof EventSource }).EventSource = function EventSourceMock() {
+      return {} as EventSource
+    } as unknown as typeof EventSource
+
+    const { result } = renderHook(() => usePortalNotifications())
+    await waitFor(() => expect(result.current.isLoading).toBe(false))
+    expect(apiCallMock).toHaveBeenCalledTimes(2)
+
+    await act(async () => {
+      window.dispatchEvent(new Event('focus'))
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, 0)
+      })
+    })
+
+    await waitFor(() => expect(apiCallMock).toHaveBeenCalledTimes(4))
+  })
+})

package/src/portal/hooks/portalBridgeStatus.ts

@@ -0,0 +1,29 @@
+export const PORTAL_BRIDGE_STATUS_DOM_NAME = 'om:portal-bridge:status'
+
+export type PortalBridgeStatusDetail = {
+  healthy: boolean
+}
+
+type PortalBridgeWindow = Window & {
+  __portalBridgeHealthy?: boolean
+}
+
+export function readPortalBridgeHealth(): boolean | undefined {
+  if (typeof window === 'undefined') return undefined
+  return (window as PortalBridgeWindow).__portalBridgeHealthy
+}
+
+export function publishPortalBridgeHealth(healthy: boolean): void {
+  if (typeof window === 'undefined') return
+  ;(window as PortalBridgeWindow).__portalBridgeHealthy = healthy
+  window.dispatchEvent(
+    new CustomEvent<PortalBridgeStatusDetail>(PORTAL_BRIDGE_STATUS_DOM_NAME, {
+      detail: { healthy },
+    }),
+  )
+}
+
+export function clearPortalBridgeHealth(): void {
+  if (typeof window === 'undefined') return
+  delete (window as PortalBridgeWindow).__portalBridgeHealthy
+}

package/src/portal/hooks/usePortalEventBridge.ts

@@ -3,6 +3,7 @@ import { useEffect, useRef } from 'react'
 import type { AppEventPayload } from '@open-mercato/shared/modules/widgets/injection'
 import { PORTAL_EVENT_DOM_NAME } from './usePortalAppEvent'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import { publishPortalBridgeHealth } from './portalBridgeStatus'
 
 const logger = createLogger('ui').child({ component: 'PortalEventBridge' })
 
@@ -62,6 +63,7 @@ export function usePortalEventBridge(): void {
       if (heartbeatTimer.current) clearTimeout(heartbeatTimer.current)
       heartbeatTimer.current = setTimeout(() => {
         logger.warn('Heartbeat timeout — reconnecting')
+        publishPortalBridgeHealth(false)
         disconnect()
         scheduleReconnect()
       }, HEARTBEAT_TIMEOUT)
@@ -80,6 +82,7 @@ export function usePortalEventBridge(): void {
           hasEverConnected.current = true
           reconnectPending.current = false
           reconnectAttempts.current = 0
+          publishPortalBridgeHealth(true)
           resetHeartbeatTimer()
           if (shouldEmitReconnect) {
             window.dispatchEvent(
@@ -116,6 +119,7 @@ export function usePortalEventBridge(): void {
           if (hasEverConnected.current) {
             reconnectPending.current = true
           }
+          publishPortalBridgeHealth(false)
           disconnect()
           if (mounted) scheduleReconnect()
         }
@@ -123,6 +127,7 @@ export function usePortalEventBridge(): void {
         if (hasEverConnected.current) {
           reconnectPending.current = true
         }
+        publishPortalBridgeHealth(false)
         if (mounted) scheduleReconnect()
       }
     }
@@ -155,6 +160,7 @@ export function usePortalEventBridge(): void {
 
     return () => {
       mounted = false
+      publishPortalBridgeHealth(false)
       disconnect()
       if (reconnectTimer.current) {
         clearTimeout(reconnectTimer.current)