React hooks

The React surface is small and deliberately effect-free where it matters.

import {
  useBridge,
  useProvideBridge,
  useBridgeState,
  useBridgeReady,
  BridgeScopeProvider,
} from '@malopezr7/bridgekit';

`useBridge(Contract, opts?)`

Returns a stable typed proxy. Safe to destructure; the reference is stable across renders.

const app = useBridge(AppHost);
const result = await app.saveFile({ url, name });   // Promise<'success' | ...>
const notes = app.notifications();                           // { subscribe } + AsyncIterable

Scope it explicitly when you need to:

const scoped = useBridge(AppHost, { scope: { kind: 'feature', feature: 'YourApp.Feature' } });

`useBridgeState(Contract, key)`

Subscribes to a state member and returns { value, status }, backed by useSyncExternalStore. value is total — initial values guarantee it’s never undefined.

const { value: net, status } = useBridgeState(AppHost, 'connectivity');
// status: 'initial' | 'provided' | 'stale' | 'unprovided'
return <Banner offline={!net.online} stale={status === 'unprovided'} />;

`useBridgeReady(Contract)`

A reactive readiness gate — one hook, not a dance. Readiness is not monotonic; it drops on runtime teardown and returns on reconnect.

const ready = useBridgeReady(AppHost);
if (!ready) return <Skeleton />;

`useProvideBridge(Contract, impl)`

Provide a contract from JS (the reverse direction). Auto-unregisters on unmount and is StrictMode-safe — a double mount supersedes harmlessly.

useProvideBridge(InboxFeature, {
  getUnreadCount: () => store.unread,
});

Imperative use outside React

There is no standalone bridge() / provideBridge() function. Outside React (services, entry points, module-load side effects), reach for the singleton and call the same two methods the hooks call internally:

import { getDefaultBridgeKit } from '@malopezr7/bridgekit';

const bk = getDefaultBridgeKit();

const app = bk.bridge(AppHost);
await app.isLoggedIn();

const binding = bk.provide(InboxFeature, impl);
binding.close('final');

bk.provide(Contract, impl, opts?) returns a Binding — close(reason?) de-registers it ('final' fails pending calls, 'replacing' holds them for a grace window) and setState(key, value) pushes provider-owned state. Both methods take the same { scope } option object as the hooks.

`BridgeScopeProvider`

Sets the ambient feature + instance scope for a subtree. The instance tag is the React root view tag — the single source of truth for instance scoping.

<BridgeScopeProvider feature="YourApp.Feature" instance={rootTag}>
  {children}
</BridgeScopeProvider>