@pyric/cli 0.1.0-alpha.11 → 0.1.0-alpha.12

package/src/serve/entries/database.ts

@@ -0,0 +1,129 @@
+/**
+ * The bundle the import map serves for `firebase/database`.
+ *
+ * The SharedWorker client already carries the RTDB data-plane used by Studio
+ * and the Playground. This entry gives served apps the same common modular SDK
+ * surface while the in-page fallback delegates to `pyric/database`.
+ */
+import * as ip from 'pyric/database';
+import { getDatabase as pyricGetDatabase } from 'pyric/database';
+import {
+  rtdbChild,
+  rtdbConnectDatabaseEmulator,
+  rtdbGet,
+  rtdbGetDatabase,
+  rtdbOff,
+  rtdbOnValue,
+  rtdbPush,
+  rtdbRef,
+  rtdbRemove,
+  rtdbServerTimestamp,
+  rtdbSet,
+  rtdbUpdate,
+} from '../worker/client.js';
+import { useWorker } from './worker-runtime.js';
+import { getApp, type FirebaseApp } from 'pyric/app';
+import { workerClientForApp } from './app-client.js';
+
+const workerDatabaseByApp = new WeakMap<FirebaseApp, ReturnType<typeof pyricGetDatabase>>();
+
+export const getDatabase = ((app?: FirebaseApp) => {
+  const resolved = app ?? getApp();
+  if (!useWorker) return pyricGetDatabase(resolved);
+  const existing = workerDatabaseByApp.get(resolved);
+  if (existing) return existing;
+  const client = workerClientForApp(resolved);
+  const handle = Object.assign(rtdbGetDatabase(client), { app: resolved }) as unknown as ReturnType<typeof pyricGetDatabase>;
+  workerDatabaseByApp.set(resolved, handle);
+  return handle;
+}) as typeof pyricGetDatabase;
+
+export const ref = (useWorker ? rtdbRef : ip.ref) as typeof ip.ref;
+export const child = (useWorker ? rtdbChild : ip.child) as typeof ip.child;
+export const get = (useWorker ? rtdbGet : ip.get) as typeof ip.get;
+export const set = (useWorker ? rtdbSet : ip.set) as typeof ip.set;
+export const update = (useWorker ? rtdbUpdate : ip.update) as typeof ip.update;
+export const remove = (useWorker ? rtdbRemove : ip.remove) as typeof ip.remove;
+export const push = (useWorker ? rtdbPush : ip.push) as typeof ip.push;
+export const onValue = (useWorker ? rtdbOnValue : ip.onValue) as typeof ip.onValue;
+export const off = (useWorker ? rtdbOff : ip.off) as typeof ip.off;
+export const serverTimestamp = (
+  useWorker ? rtdbServerTimestamp : ip.serverTimestamp
+) as typeof ip.serverTimestamp;
+export const connectDatabaseEmulator = (
+  useWorker ? rtdbConnectDatabaseEmulator : ip.connectDatabaseEmulator
+) as typeof ip.connectDatabaseEmulator;
+
+// ── Low-hanging-fruit exports (issue #149) ────────────────────────────────
+// Served mode is always sandbox-backed (never a prod handle), and these are
+// honest no-ops in the sandbox model regardless of the worker/in-page split,
+// so they are unconditional no-ops here — no worker RPC needed. This also
+// gives served apps import-time parity for the `firebase/database` surface.
+export const goOffline = ((_db?: unknown) => {}) as typeof ip.goOffline;
+export const goOnline = ((_db?: unknown) => {}) as typeof ip.goOnline;
+export const forceLongPolling = (() => {}) as typeof ip.forceLongPolling;
+export const forceWebSockets = (() => {}) as typeof ip.forceWebSockets;
+export const enableLogging = ((_logger?: unknown, _persistent?: unknown) => {}) as typeof ip.enableLogging;
+
+/**
+ * `refFromURL(db, url)` — parse the path out of the URL and delegate to the
+ * picked `ref` (worker or in-page), so the resolved ref behaves exactly like
+ * `ref(db, path)`. The URL host/namespace is not honored (served sandbox is
+ * single-database) — matching the in-page `pyric/database` behavior.
+ */
+export const refFromURL = ((db: unknown, url: string) => {
+  let path: string;
+  try {
+    path = new URL(url).pathname;
+  } catch {
+    throw new Error(
+      `firebase/database refFromURL received a value that is not an absolute URL: ${url}`,
+    );
+  }
+  return (ref as (db: unknown, path?: string) => unknown)(db, path);
+}) as typeof ip.refFromURL;
+
+function unsupportedWorkerApi(name: string): never {
+  throw new Error(
+    `firebase/database ${name}() is not supported over the pyric SharedWorker yet. ` +
+      'Use the in-page fallback for this operation.',
+  );
+}
+
+export const runTransaction = (
+  useWorker ? (() => unsupportedWorkerApi('runTransaction')) : ip.runTransaction
+) as typeof ip.runTransaction;
+
+export const query = (
+  useWorker ? (() => unsupportedWorkerApi('query')) : ip.query
+) as typeof ip.query;
+export const orderByChild = (
+  useWorker ? (() => unsupportedWorkerApi('orderByChild')) : ip.orderByChild
+) as typeof ip.orderByChild;
+export const orderByKey = (
+  useWorker ? (() => unsupportedWorkerApi('orderByKey')) : ip.orderByKey
+) as typeof ip.orderByKey;
+export const orderByValue = (
+  useWorker ? (() => unsupportedWorkerApi('orderByValue')) : ip.orderByValue
+) as typeof ip.orderByValue;
+export const startAt = (
+  useWorker ? (() => unsupportedWorkerApi('startAt')) : ip.startAt
+) as typeof ip.startAt;
+export const startAfter = (
+  useWorker ? (() => unsupportedWorkerApi('startAfter')) : ip.startAfter
+) as typeof ip.startAfter;
+export const endAt = (
+  useWorker ? (() => unsupportedWorkerApi('endAt')) : ip.endAt
+) as typeof ip.endAt;
+export const endBefore = (
+  useWorker ? (() => unsupportedWorkerApi('endBefore')) : ip.endBefore
+) as typeof ip.endBefore;
+export const equalTo = (
+  useWorker ? (() => unsupportedWorkerApi('equalTo')) : ip.equalTo
+) as typeof ip.equalTo;
+export const limitToFirst = (
+  useWorker ? (() => unsupportedWorkerApi('limitToFirst')) : ip.limitToFirst
+) as typeof ip.limitToFirst;
+export const limitToLast = (
+  useWorker ? (() => unsupportedWorkerApi('limitToLast')) : ip.limitToLast
+) as typeof ip.limitToLast;

package/src/serve/entries/firestore.ts

@@ -0,0 +1,232 @@
+/**
+ * The bundle the import map serves for `firebase/firestore`.
+ *
+ * DUAL-PATH (Phase 3c): when a SharedWorker is available, the data ops route
+ * to the ONE worker-hosted sandbox (multi-tab sync + IDB/`--persist`
+ * durability); otherwise they run against the in-page sandbox — the unchanged
+ * fallback. The branch is picked ONCE at module load (`useWorker`).
+ *
+ * The COMPLETE modular surface is exported on BOTH paths: a missing named
+ * export fails the page at import time (the firebase/app failure class), so the
+ * worker path fills the functions the thin worker-client lacks (`or`/`and`,
+ * `Timestamp`, the client-cache config no-ops) right here.
+ *
+ * Browser-bundled by `../bundler.ts`; never imported by node-side code.
+ */
+import * as ip from 'pyric/firestore';
+import { getFirestore as pyricGetFirestore } from 'pyric/firestore';
+import * as wcRaw from '../worker/client.js';
+import { useWorker } from './worker-runtime.js';
+import { getApp, type FirebaseApp } from 'pyric/app';
+import { workerClientForApp } from './app-client.js';
+
+// The worker client mirrors pyric/firestore's DATA surface (same names + arg
+// shapes); cast so the picked bindings type-check against the canonical module.
+// Members the worker client genuinely lacks (or/and/Timestamp/cache config) are
+// handled explicitly below — NOT taken from this cast.
+const wc = wcRaw as unknown as typeof ip;
+
+/** The data-path implementation chosen at load. */
+const D = useWorker ? wc : ip;
+
+// ── Data ops — route to the worker-hosted or in-page sandbox ──────────────
+export const onSnapshot = D.onSnapshot;
+export const collection = D.collection;
+export const collectionGroup = D.collectionGroup;
+export const doc = D.doc;
+export const getDoc = D.getDoc;
+export const getDocs = D.getDocs;
+export const setDoc = D.setDoc;
+export const addDoc = D.addDoc;
+export const updateDoc = D.updateDoc;
+export const deleteDoc = D.deleteDoc;
+export const query = D.query;
+export const where = D.where;
+export const orderBy = D.orderBy;
+export const limit = D.limit;
+export const limitToLast = D.limitToLast;
+export const startAt = D.startAt;
+export const startAfter = D.startAfter;
+export const endAt = D.endAt;
+export const endBefore = D.endBefore;
+export const runTransaction = D.runTransaction;
+export const writeBatch = D.writeBatch;
+export const serverTimestamp = D.serverTimestamp;
+export const increment = D.increment;
+export const arrayUnion = D.arrayUnion;
+export const arrayRemove = D.arrayRemove;
+export const deleteField = D.deleteField;
+
+// ── Value class — path-independent (builds data; the worker serializes it via
+//    the shared codec) ──────────────────────────────────────────────────────
+export const Timestamp = ip.Timestamp;
+
+// ── Composite filters — path-independent (issue #144). The worker query
+//    protocol carries the composite filter tree end-to-end: the client `or`/
+//    `and` factories emit nested `FilterConstraintDescriptor`s, `query()`
+//    embeds them in the query descriptor, and the host rebuilds them through
+//    the REAL `pyric/firestore` `and`/`or` factories (see
+//    `worker/host.ts` resolveConstraint + `worker/protocol.ts`
+//    FilterConstraintDescriptor). So on BOTH paths `or`/`and` come from the
+//    chosen data impl `D` — the worker client on the worker path, in-page
+//    otherwise. Nested `and`/`or`/`where` composites and composition with
+//    orderBy/limit all cross intact; malformed composites (empty / non-filter
+//    operand) still raise the same modular-SDK TypeError. ────────────────────
+export const or = D.or;
+export const and = D.and;
+
+// ── getFirestore — the canonical bare call returns the page's shared backend:
+//    the worker ClientDb on the worker path, the in-page sandbox otherwise. ──
+const workerFirestoreByApp = new WeakMap<FirebaseApp, ReturnType<typeof pyricGetFirestore>>();
+
+export const getFirestore = ((app?: FirebaseApp) => {
+  const resolved = app ?? getApp();
+  if (!useWorker) return pyricGetFirestore(resolved);
+  const existing = workerFirestoreByApp.get(resolved);
+  if (existing) return existing;
+  const client = workerClientForApp(resolved);
+  const handle = Object.assign(client, { app: resolved }) as unknown as ReturnType<typeof pyricGetFirestore>;
+  workerFirestoreByApp.set(resolved, handle);
+  return handle;
+}) as typeof pyricGetFirestore;
+
+// ── section 3c tier 2: ACCEPTED, sandbox-managed (no-op + one-time notice). ──────
+// Apps configure client caching unconditionally; a missing named export
+// fails the page at IMPORT time (the firebase/app failure class). None of
+// these are emulated — the sandbox (in-page OR worker) IS the source of
+// truth, so the client cache layer these configure has no role. Durable data
+// is the worker's IDB (default) + `pyric dev --persist`. Path-independent.
+
+let cacheNoticeShown = false;
+function acceptedNoOp(name: string): void {
+  if (cacheNoticeShown) return;
+  cacheNoticeShown = true;
+  console.info(
+    `[pyric dev] ${name}(): client cache/persistence settings are accepted but unused — ` +
+      'the pyric sandbox is the source of truth. Durable state is the worker store / `pyric dev --persist`.',
+  );
+}
+
+/** firebase's sentinel value, re-exported for settings parity. */
+export const CACHE_SIZE_UNLIMITED = -1;
+
+export function initializeFirestore(
+  app?: Parameters<typeof pyricGetFirestore>[0],
+  settings?: unknown,
+): ReturnType<typeof getFirestore> {
+  if (settings && Object.keys(settings as object).length > 0) acceptedNoOp('initializeFirestore');
+  return getFirestore(app as never);
+}
+
+export function persistentLocalCache(_settings?: unknown): { kind: string } {
+  acceptedNoOp('persistentLocalCache');
+  return { kind: 'persistent' };
+}
+
+export function memoryLocalCache(_settings?: unknown): { kind: string } {
+  return { kind: 'memory' };
+}
+
+export function persistentSingleTabManager(_settings?: unknown): { kind: string } {
+  return { kind: 'persistentSingleTab' };
+}
+
+export function persistentMultipleTabManager(): { kind: string } {
+  return { kind: 'persistentMultipleTab' };
+}
+
+export async function enableIndexedDbPersistence(_db?: unknown): Promise<void> {
+  acceptedNoOp('enableIndexedDbPersistence');
+}
+
+/** No-op success, same rationale as `enableIndexedDbPersistence` — the
+ *  SharedWorker path already IS the one store every tab reads/writes, so
+ *  there's no separate multi-tab mode to opt into over the worker; the
+ *  in-page fallback has no multi-tab story to begin with. */
+export async function enableMultiTabIndexedDbPersistence(_db?: unknown): Promise<void> {
+  acceptedNoOp('enableMultiTabIndexedDbPersistence');
+}
+
+export async function clearIndexedDbPersistence(_db?: unknown): Promise<void> {
+  acceptedNoOp('clearIndexedDbPersistence');
+}
+
+/** Resolves immediately — sandbox writes apply synchronously in-page; over the
+ *  worker the RPC ack already settled (judgment zone 4, recorded). */
+export async function waitForPendingWrites(_db?: unknown): Promise<void> {}
+
+// ── network toggles — no-op (accepted, unused). No network exists in the
+//    sandbox (in-page OR worker): every op is a local call, never a request
+//    that could be offline. Writes issued after `disableNetwork()` still
+//    commit immediately — no offline queue is simulated, because the sandbox
+//    cannot honestly deliver "queued until reconnected" with no connection to
+//    lose in the first place. ───────────────────────────────────────────────
+export async function disableNetwork(_db?: unknown): Promise<void> {
+  acceptedNoOp('disableNetwork');
+}
+
+export async function enableNetwork(_db?: unknown): Promise<void> {
+  acceptedNoOp('enableNetwork');
+}
+
+/**
+ * In-page fallback: forwards to `pyric/firestore`'s `terminate`, which
+ * genuinely tears the sandbox down via `Sandbox.dispose()`.
+ *
+ * Worker path: accepted no-op. The SharedWorker-hosted sandbox is
+ * shared across every tab on the page's origin — disposing it here
+ * would tear down listener registries out from under other open tabs,
+ * which the real `terminate()` contract (single-instance teardown)
+ * never implies. Documented divergence: over the worker, `terminate`
+ * settles without tearing anything down.
+ */
+export async function terminate(db?: unknown): Promise<void> {
+  if (useWorker) {
+    console.info(
+      '[pyric dev] terminate(): the SharedWorker-hosted sandbox is shared across every tab; ' +
+        'it is not torn down by a single tab calling terminate().',
+    );
+    return;
+  }
+  return ip.terminate(db as Parameters<typeof ip.terminate>[0]);
+}
+
+// ── tier-1 cache-init + get-from-* + log-level + snapshot-sync (issue #144,
+//    tier-1 pass). Aliases and honest no-op config tokens — see
+//    `packages/pyric/src/firestore/index.ts`'s tier-1 section for the full
+//    rationale. `memoryEagerGarbageCollector`/`memoryLruGarbageCollector` and
+//    `setLogLevel` are path-independent (no data routing), so they delegate
+//    straight to `pyric/firestore`. `getDocFromServer`/`getDocFromCache` and
+//    their plural forms MUST route through `D` (the worker-vs-in-page pick)
+//    like `getDoc`/`getDocs` above, not straight to `ip`, so they read from
+//    whichever backend this page actually uses. ─────────────────────────────
+
+export const memoryEagerGarbageCollector = ip.memoryEagerGarbageCollector;
+export const memoryLruGarbageCollector = ip.memoryLruGarbageCollector;
+export const setLogLevel = ip.setLogLevel;
+
+export const getDocFromServer = D.getDoc;
+export const getDocsFromServer = D.getDocs;
+export const getDocFromCache = D.getDoc;
+export const getDocsFromCache = D.getDocs;
+
+/**
+ * Local no-op reimplementation rather than delegating to `ip.onSnapshotsInSync`:
+ * on the worker path `db` is a `ClientDb`, not a `pyric/firestore` `Firestore`
+ * handle, so it doesn't carry the `TARGET_SYMBOL` brand `ip.onSnapshotsInSync`
+ * dispatches on. Fires the callback once the current microtask queue settles —
+ * same honest approximation as the in-page implementation — on both paths.
+ */
+export function onSnapshotsInSync(
+  _db: unknown,
+  observerOrCallback: (() => void) | { next?: () => void },
+): () => void {
+  const cb = typeof observerOrCallback === 'function' ? observerOrCallback : observerOrCallback.next;
+  let cancelled = false;
+  queueMicrotask(() => {
+    if (!cancelled && cb) cb();
+  });
+  return () => {
+    cancelled = true;
+  };
+}

package/src/serve/entries/init.ts

@@ -0,0 +1,46 @@
+/**
+ * `/__pyric/sdk/init.js` — the script tag `pyric dev` injects into every
+ * served HTML page. Pulls the shared runtime and mounts the sign-in helper.
+ * In worker mode the helper reads the worker user directory and owns UI state
+ * only; in fallback mode it adapts the page sandbox's Auth store.
+ */
+import { getAuth, sandbox as authSandbox } from 'pyric/auth';
+import {
+  getAuth as getWorkerAuth,
+  listUsers,
+} from '../worker/client.js';
+import { sandbox } from './runtime.js';
+import { useWorker, workerDb } from './worker-runtime.js';
+import { ServeAuthHelper } from './auth-helper-core.js';
+import { installServeAuthResolver } from './auth-helper-runtime.js';
+import { mountAuthHelperDialog } from './auth-helper-dom.js';
+
+const localAuth = useWorker ? null : getAuth(sandbox);
+const workerAuth = useWorker && workerDb ? getWorkerAuth(workerDb) : null;
+const helper = new ServeAuthHelper(
+  workerAuth
+    ? {
+        list: async () => (await listUsers(workerAuth)).map((user) => ({
+          uid: user.uid,
+          email: user.email,
+          displayName: user.displayName,
+          customClaims: user.customClaims,
+        })),
+      }
+    : {
+        list: () => authSandbox.listIdentities(localAuth!),
+        add: (identity) => authSandbox.seedUsers(localAuth!, [{
+          uid: identity.uid,
+          email: identity.email ?? '',
+          password: '__pyric_popup_no_password__',
+          displayName: identity.displayName ?? undefined,
+          customClaims: identity.customClaims,
+        }]),
+      },
+);
+const resolver = helper.resolver();
+installServeAuthResolver(resolver);
+if (localAuth) authSandbox.setAuthFlowResolver(localAuth, resolver);
+mountAuthHelperDialog(helper);
+
+export {};

package/src/serve/entries/keepalive.ts

@@ -0,0 +1,46 @@
+/**
+ * `keepalive` size gate for the persist flush (pre-mortem #1).
+ *
+ * The persistence controller's `beforeunload` flush fires while the page is
+ * unloading; a plain `fetch` is aborted on unload, so the final delta is
+ * lost (the original "crash-only loss window" claim was wrong). `fetch(...,
+ * {keepalive: true})` survives unload — but the browser caps the TOTAL body
+ * size of in-flight keepalive requests at ~64KB. Above that the request is
+ * rejected, so we only set keepalive when the body comfortably fits, and
+ * warn once when it doesn't (that page's final unsaved change can be lost on
+ * tab close; reload-triggered flushes are unaffected because they complete
+ * before navigation).
+ */
+
+/** Below this, keepalive is safe; above, skip it (and warn once). 60KB
+ *  leaves headroom under the ~64KB spec cap for headers/other requests. */
+export const KEEPALIVE_MAX_BYTES = 60_000;
+
+let warnedLargeState = false;
+
+export function keepaliveSafe(
+  body: string,
+  warn: (msg: string) => void = (m) => console.warn(m),
+): boolean {
+  const bytes = byteLength(body);
+  if (bytes <= KEEPALIVE_MAX_BYTES) return true;
+  if (!warnedLargeState) {
+    warnedLargeState = true;
+    warn(
+      `[pyric dev] persisted state is ${Math.round(bytes / 1024)}KB — too large for an ` +
+        'unload-time flush; the final unsaved change may be lost if you CLOSE the tab before ' +
+        'the next auto-flush. Reloads and normal saves are unaffected.',
+    );
+  }
+  return false;
+}
+
+/** Reset module state — tests only. */
+export function __resetKeepaliveWarning(): void {
+  warnedLargeState = false;
+}
+
+function byteLength(s: string): number {
+  // TextEncoder is in every browser + bun; avoids assuming Buffer.
+  return typeof TextEncoder !== 'undefined' ? new TextEncoder().encode(s).length : s.length;
+}

package/src/serve/entries/messaging-sw.ts

@@ -0,0 +1,75 @@
+/** The canonical `firebase/messaging/sw` served mirror. */
+import * as inPage from 'pyric/messaging/sw';
+import type {
+  MessagePayload,
+  Messaging,
+  NextFn,
+  Observer,
+  Unsubscribe,
+} from 'pyric/messaging/sw';
+import { getApp, type FirebaseApp } from 'pyric/app';
+import { registerSandboxDelivery } from 'pyric/messaging/internal';
+import {
+  messagingDeliver,
+  messagingGetMessaging,
+  messagingSubscribe,
+  type ClientMessaging,
+} from '../worker/client/messaging.js';
+import { workerClientForApp } from './app-client.js';
+import { useWorker } from './worker-runtime.js';
+
+export type {
+  FcmOptions,
+  GetTokenOptions,
+  MessagePayload,
+  Messaging,
+  NextFn,
+  NotificationPayload,
+  Observer,
+  Unsubscribe,
+} from 'pyric/messaging/sw';
+
+type WorkerMessaging = Messaging & ClientMessaging;
+const workerMessagingByApp = new WeakMap<FirebaseApp, WorkerMessaging>();
+const bigQueryExport = new WeakMap<Messaging, boolean>();
+
+export function getMessaging(app?: FirebaseApp): Messaging {
+  const resolved = app ?? getApp();
+  if (!useWorker) return inPage.getMessaging(resolved);
+  const existing = workerMessagingByApp.get(resolved);
+  if (existing) return existing;
+  const handle = Object.assign(
+    messagingGetMessaging(workerClientForApp(resolved)),
+    { app: resolved },
+  ) as WorkerMessaging;
+  workerMessagingByApp.set(resolved, handle);
+  // Symmetric with the client entry: let `pyric/messaging/sw`'s `sandbox.deliver`
+  // drive this worker-backed handle over the transport (same broker, same op).
+  registerSandboxDelivery(handle, (spec) => messagingDeliver(handle, spec));
+  return handle;
+}
+
+export function onBackgroundMessage(
+  messaging: Messaging,
+  nextOrObserver: NextFn<MessagePayload> | Observer<MessagePayload>,
+): Unsubscribe {
+  return useWorker
+    ? messagingSubscribe(messaging as WorkerMessaging, 'messaging.background', nextOrObserver)
+    : inPage.onBackgroundMessage(messaging, nextOrObserver);
+}
+
+export function experimentalSetDeliveryMetricsExportedToBigQueryEnabled(
+  messaging: Messaging,
+  enable: boolean,
+): void {
+  if (!useWorker) {
+    inPage.experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging, enable);
+    return;
+  }
+  if ((messaging as Partial<ClientMessaging>).__kind !== 'client-messaging') {
+    throw new Error('firebase/messaging/sw: unrecognized Messaging instance');
+  }
+  bigQueryExport.set(messaging, enable);
+}
+
+export const isSupported = inPage.isSupported;

package/src/serve/entries/messaging.ts

@@ -0,0 +1,96 @@
+/** The canonical `firebase/messaging` served mirror. */
+import * as inPage from 'pyric/messaging';
+import type {
+  GetTokenOptions,
+  MessagePayload,
+  Messaging,
+  NextFn,
+  Observer,
+  Unsubscribe,
+} from 'pyric/messaging';
+import { getApp, type FirebaseApp } from 'pyric/app';
+import { registerAppCleanup } from 'pyric/app/internal';
+import { registerSandboxDelivery } from 'pyric/messaging/internal';
+import {
+  messagingDeleteToken,
+  messagingDeliver,
+  messagingGetMessaging,
+  messagingGetToken,
+  messagingSetVisibility,
+  messagingSubscribe,
+  type ClientMessaging,
+} from '../worker/client/messaging.js';
+import { workerClientForApp } from './app-client.js';
+import { useWorker } from './worker-runtime.js';
+
+export type {
+  FcmOptions,
+  GetTokenOptions,
+  MessagePayload,
+  Messaging,
+  NextFn,
+  NotificationPayload,
+  Observer,
+  Unsubscribe,
+} from 'pyric/messaging';
+
+type WorkerMessaging = Messaging & ClientMessaging;
+const workerMessagingByApp = new WeakMap<FirebaseApp, WorkerMessaging>();
+const visibilityWired = new WeakSet<FirebaseApp>();
+
+function wireVisibility(app: FirebaseApp, messaging: WorkerMessaging): void {
+  if (visibilityWired.has(app) || typeof document === 'undefined') return;
+  visibilityWired.add(app);
+  const sync = (): void => {
+    const state = document.visibilityState === 'visible' ? 'visible' : 'hidden';
+    void messagingSetVisibility(messaging, state).catch(() => {});
+  };
+  document.addEventListener('visibilitychange', sync);
+  registerAppCleanup(app, () => {
+    visibilityWired.delete(app);
+    document.removeEventListener('visibilitychange', sync);
+  });
+  sync();
+}
+
+export function getMessaging(app?: FirebaseApp): Messaging {
+  const resolved = app ?? getApp();
+  if (!useWorker) return inPage.getMessaging(resolved);
+  const existing = workerMessagingByApp.get(resolved);
+  if (existing) return existing;
+  const handle = Object.assign(
+    messagingGetMessaging(workerClientForApp(resolved)),
+    { app: resolved },
+  ) as WorkerMessaging;
+  workerMessagingByApp.set(resolved, handle);
+  wireVisibility(resolved, handle);
+  // The worker-backed handle isn't in pyric's in-page instance registry, so
+  // teach `pyric/messaging`'s `sandbox.deliver` to drive it over the transport
+  // (visibility+routing resolved host-side). Keeps `firebase/messaging` itself
+  // free of any `sandbox` surface — production parity is untouched.
+  registerSandboxDelivery(handle, (spec) => messagingDeliver(handle, spec));
+  return handle;
+}
+
+export function getToken(messaging: Messaging, options?: GetTokenOptions): Promise<string> {
+  return useWorker
+    ? messagingGetToken(messaging as WorkerMessaging, options)
+    : inPage.getToken(messaging, options);
+}
+
+export function deleteToken(messaging: Messaging): Promise<boolean> {
+  return useWorker
+    ? messagingDeleteToken(messaging as WorkerMessaging)
+    : inPage.deleteToken(messaging);
+}
+
+export function onMessage(
+  messaging: Messaging,
+  nextOrObserver: NextFn<MessagePayload> | Observer<MessagePayload>,
+): Unsubscribe {
+  return useWorker
+    ? messagingSubscribe(messaging as WorkerMessaging, 'messaging.foreground', nextOrObserver)
+    : inPage.onMessage(messaging, nextOrObserver);
+}
+
+export const isSupported = inPage.isSupported;