@pyric/cli 0.1.0-alpha.14 → 0.1.0-alpha.15

package/src/serve/bundler.ts

@@ -67,41 +67,15 @@ export function defaultSdkEntries(): Record<string, string> {
   };
 }
 
-/**
- * Resolve the built Studio app dir (the plugin's `ui` option + the CLI's
- * `--ui`). Reached by file path so @pyric/cli never imports `@pyric/studio`:
- * the packaged location (`dist/serve/studio-ui`, copied at build) or, in the
- * monorepo, the sibling studio build. Null when neither exists. The standalone
- * binary embeds these same bytes instead (see `standalone-assets.ts`).
- */
-export function resolveStudioUiDir(): string | null {
-  const candidates = [
-    new URL('./studio-ui/', import.meta.url),
-    new URL('../../../studio/dist/app/', import.meta.url),
-  ];
-  for (const candidate of candidates) {
-    const dir = fileURLToPath(candidate);
-    if (existsSync(dir)) return dir;
-  }
-  return null;
-}
-
-/**
- * Resolve the built docs site dir (site-docs). `pyric dev --ui` embeds it so
- * the Studio Docs tab has local docs without the hosted site. Built with base
- * `/__pyric/ui/` (see scripts/build.sh) so every page/asset/twin URL resolves
- * under the CLI mount: pages at `/__pyric/ui/docs/<slug>/`, assets at
- * `/__pyric/ui/_astro/*`, the search index at `/__pyric/ui/docs/index.json`,
- * and the shell chrome's tab links back at `/__pyric/ui/<tab>`. The dir holds
- * the site-docs `dist/` verbatim: `docs/`, `_astro/`, `index.html`, `llms.txt`.
- */
-export function resolveDocsUiDir(): string | null {
-  const candidates = [
-    new URL('./docs-ui/', import.meta.url),
-  ];
+/** Resolve the unified Astro documentation + Studio tree embedded by the build. */
+export function resolveSiteUiDir(
+  candidates: readonly string[] = [
+    fileURLToPath(new URL('./site-ui/', import.meta.url)),
+    fileURLToPath(new URL('../../../site-docs/dist/', import.meta.url)),
+  ],
+): string | null {
   for (const candidate of candidates) {
-    const dir = fileURLToPath(candidate);
-    if (existsSync(dir)) return dir;
+    if (existsSync(candidate)) return candidate;
   }
   return null;
 }

package/src/serve/entries/app-client.ts

@@ -3,7 +3,7 @@ import type { FirebaseApp } from 'pyric/app';
 import { registerAppCleanup } from 'pyric/app/internal';
 import type { ClientDb } from '../worker/client.js';
 import type { InboundMessage } from '../worker/protocol.js';
-import { disconnectClient } from '../worker/client/disconnect.js';
+import { ownClientUntilPagehide } from '../worker/client/pagehide.js';
 import { openWorkerDb } from './worker-runtime.js';
 
 const clients = new WeakMap<FirebaseApp, ClientDb>();
@@ -11,12 +11,13 @@ const clients = new WeakMap<FirebaseApp, ClientDb>();
 export function workerClientForApp(app: FirebaseApp): ClientDb {
   const existing = clients.get(app);
   if (existing) return existing;
-  let client: ClientDb | undefined;
+  const client = openWorkerDb(app.name);
+  const lifecycle = ownClientUntilPagehide(client);
   registerAppCleanup(app, async () => {
     clients.delete(app);
-    if (client) await disconnectClient(client);
+    lifecycle.dispose();
+    await lifecycle.disconnect();
   });
-  client = openWorkerDb(app.name);
   client.port.postMessage({
     t: 'appConfig',
     options: app.options as Record<string, unknown>,

package/src/serve/entries/auth-helper-core.ts

@@ -5,8 +5,9 @@
  * directory and returns a Firebase-shaped credential; it never constructs an
  * Auth handle or mutates a Sandbox. In SharedWorker mode the directory reads
  * the worker's user pool and the picked credential is committed by
- * `auth.acceptIdentity`. The in-page fallback supplies a small adapter over its
- * local auth user store.
+ * `auth.acceptIdentity`. The in-page fallback supplies a mint that calls
+ * `sandbox.createSignInCredential` so the resolved User carries real
+ * provider metadata.
  */
 import type {
   AuthFlowRequest,
@@ -31,10 +32,22 @@ export interface HelperIdentity {
 
 export interface HelperIdentityDirectory {
   list(): HelperIdentity[] | Promise<HelperIdentity[]>;
-  /** Optional on the worker path: `auth.acceptIdentity` performs the write. */
+  /** Optional on the worker path: `auth.acceptIdentity` performs the write.
+   *  Unused when a custom {@link HelperCredentialMint} owns creation. */
   add?(identity: HelperIdentity): void | Promise<void>;
 }
 
+/**
+ * Mint a Firebase-shaped credential for a picker pick/add. The default mint
+ * builds a bare helper User (worker path → discarded by `acceptIdentity`).
+ * The in-page fallback injects `sandbox.createSignInCredential`.
+ */
+export type HelperCredentialMint = (
+  request:
+    | { kind: 'pick'; identity: HelperIdentity; providerId: string }
+    | { kind: 'add'; spec: NewIdentitySpec; providerId: string },
+) => UserCredential | Promise<UserCredential>;
+
 export interface HelperSnapshot {
   /** The in-flight request, or null when no popup/redirect is pending. */
   request: AuthFlowRequest | null;
@@ -52,8 +65,13 @@ export class ServeAuthHelper {
   private readonly listeners = new Set<() => void>();
   private cached: HelperSnapshot | null = null;
   private identities: HelperIdentity[] = [];
+  private readonly mint: HelperCredentialMint;
 
-  constructor(private readonly directory: HelperIdentityDirectory) {
+  constructor(
+    private readonly directory: HelperIdentityDirectory,
+    mint?: HelperCredentialMint,
+  ) {
+    this.mint = mint ?? ((request) => this.defaultMint(request));
     this.refreshIdentities();
   }
 
@@ -118,22 +136,17 @@ export class ServeAuthHelper {
       pending.reject(authError('auth/internal-error', `unknown identity ${uid}`));
       return;
     }
-    pending.resolve(this.credential(identity, pending.req.providerId));
+    void Promise.resolve(
+      this.mint({ kind: 'pick', identity, providerId: pending.req.providerId }),
+    ).then(pending.resolve, pending.reject);
   }
 
   add(spec: NewIdentitySpec): void {
     const pending = this.take();
     if (!pending) return;
-    const identity: HelperIdentity = {
-      uid: `${pending.req.providerId}:${spec.email}`,
-      email: spec.email,
-      displayName: spec.displayName ?? null,
-      customClaims: spec.customClaims ?? {},
-    };
-    void Promise.resolve(this.directory.add?.(identity)).then(
-      () => pending.resolve(this.credential(identity, pending.req.providerId)),
-      pending.reject,
-    );
+    void Promise.resolve(
+      this.mint({ kind: 'add', spec, providerId: pending.req.providerId }),
+    ).then(pending.resolve, pending.reject);
   }
 
   cancel(): void {
@@ -154,25 +167,65 @@ export class ServeAuthHelper {
     return pending;
   }
 
-  private credential(identity: HelperIdentity, providerId: string): UserCredential {
-    const user: User = {
-      uid: identity.uid,
-      email: identity.email,
-      displayName: identity.displayName,
-      isAnonymous: false,
-      getIdToken: async () => `pyric-serve-${identity.uid}`,
-      getIdTokenResult: async () => ({
-        token: `pyric-serve-${identity.uid}`,
-        claims: { sub: identity.uid, ...identity.customClaims },
-        expirationTime: new Date(Date.now() + 3600_000).toISOString(),
-        issuedAtTime: new Date().toISOString(),
-        authTime: new Date().toISOString(),
-      }),
+  private async defaultMint(
+    request:
+      | { kind: 'pick'; identity: HelperIdentity; providerId: string }
+      | { kind: 'add'; spec: NewIdentitySpec; providerId: string },
+  ): Promise<UserCredential> {
+    if (request.kind === 'pick') {
+      return bareCredential(request.identity, request.providerId);
+    }
+    const identity: HelperIdentity = {
+      uid: `${request.providerId}:${request.spec.email}`,
+      email: request.spec.email,
+      displayName: request.spec.displayName ?? null,
+      customClaims: request.spec.customClaims ?? {},
     };
-    return { user, providerId, operationType: 'signIn' };
+    await Promise.resolve(this.directory.add?.(identity));
+    return bareCredential(identity, request.providerId);
   }
 }
 
+/** Bare helper User — worker path discards this in favor of `acceptIdentity`. */
+function bareCredential(identity: HelperIdentity, providerId: string): UserCredential {
+  const issuedAtTime = new Date().toISOString();
+  const expirationTime = new Date(Date.now() + 3600_000).toISOString();
+  const user: User = {
+    uid: identity.uid,
+    email: identity.email,
+    displayName: identity.displayName,
+    isAnonymous: false,
+    emailVerified: false,
+    photoURL: null,
+    phoneNumber: null,
+    providerId: 'firebase',
+    providerData: [
+      {
+        uid: identity.uid,
+        displayName: identity.displayName,
+        email: identity.email,
+        phoneNumber: null,
+        photoURL: null,
+        providerId,
+      },
+    ],
+    getIdToken: async () => `pyric-serve-${identity.uid}`,
+    getIdTokenResult: async () => ({
+      token: `pyric-serve-${identity.uid}`,
+      claims: {
+        sub: identity.uid,
+        ...identity.customClaims,
+        firebase: { sign_in_provider: providerId },
+      },
+      signInProvider: providerId,
+      expirationTime,
+      issuedAtTime,
+      authTime: issuedAtTime,
+    }),
+  };
+  return { user, providerId, operationType: 'signIn' };
+}
+
 function authError(code: string, message: string): Error & { code: string } {
   const error = new Error(message) as Error & { code: string };
   error.name = 'FirebaseError';

package/src/serve/entries/database.ts

@@ -7,46 +7,137 @@
  */
 import * as ip from 'pyric/database';
 import { getDatabase as pyricGetDatabase } from 'pyric/database';
+import { queryIdentifier } from 'pyric/database/internal';
+import { rtdbChild, rtdbGetDatabase, rtdbRef } from '../worker/client/rtdb-references.js';
+import { rtdbGet } from '../worker/client/rtdb-reads.js';
 import {
-  rtdbChild,
-  rtdbConnectDatabaseEmulator,
-  rtdbGet,
-  rtdbGetDatabase,
-  rtdbOff,
-  rtdbOnValue,
   rtdbPush,
-  rtdbRef,
   rtdbRemove,
-  rtdbServerTimestamp,
   rtdbSet,
+  rtdbSetPriority,
+  rtdbSetWithPriority,
   rtdbUpdate,
-} from '../worker/client.js';
+} from '../worker/client/rtdb-writes.js';
+import {
+  rtdbOff,
+  rtdbOnChildAdded,
+  rtdbOnChildChanged,
+  rtdbOnChildMoved,
+  rtdbOnChildRemoved,
+  rtdbOnValue,
+} from '../worker/client/rtdb-listeners.js';
+import { rtdbRunTransaction } from '../worker/client/rtdb-transactions.js';
+import {
+  RtdbOnDisconnect,
+  rtdbGoOffline,
+  rtdbGoOnline,
+  rtdbOnDisconnect,
+} from '../worker/client/rtdb-connection-lifecycle.js';
+import {
+  rtdbConnectDatabaseEmulator,
+  rtdbServerTimestamp,
+} from '../worker/client/rtdb-controls.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>>();
 
+type WorkerSnapshot = Awaited<ReturnType<typeof rtdbGet>>;
+
+function wrapWorkerSnapshot(snapshot: WorkerSnapshot): ip.DataSnapshot {
+  return new ip.DataSnapshot({
+    key: snapshot.key,
+    size: snapshot.size,
+    priority: snapshot.priority,
+    ref: snapshot.ref as unknown as ip.DatabaseReference,
+    exists: () => snapshot.exists(),
+    val: () => snapshot.val() as ip.JsonValue,
+    child: (path) => wrapWorkerSnapshot(snapshot.child(path)),
+    hasChild: (path) => snapshot.hasChild(path),
+    hasChildren: () => snapshot.hasChildren(),
+    exportVal: () => snapshot.exportVal() as ip.JsonValue,
+    toJSON: () => snapshot.toJSON() as ip.JsonValue,
+    forEach: (callback) => snapshot.forEach((childSnapshot) =>
+      callback(wrapWorkerSnapshot(childSnapshot))),
+  });
+}
+
 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>;
+  const handle = Object.assign(
+    new ip.Database(undefined, resolved),
+    rtdbGetDatabase(client),
+    { app: resolved },
+  ) 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 get = (
+  useWorker
+    ? (async (target: Parameters<typeof ip.get>[0]) =>
+        wrapWorkerSnapshot(await rtdbGet(target as never)))
+    : 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 onValue = (
+  useWorker
+    ? ((
+        target: Parameters<typeof ip.onValue>[0],
+        callback: Parameters<typeof ip.onValue>[1],
+        cancelOrOptions?: Parameters<typeof ip.onValue>[2],
+        options?: Parameters<typeof ip.onValue>[3],
+      ) => rtdbOnValue(
+        target as never,
+        (snapshot) => callback(wrapWorkerSnapshot(snapshot)),
+        cancelOrOptions as never,
+        options,
+        callback,
+      ))
+    : ip.onValue
+) as typeof ip.onValue;
+export const onChildAdded = (
+  useWorker
+    ? ((target: Parameters<typeof ip.onChildAdded>[0], callback: Parameters<typeof ip.onChildAdded>[1], cancelOrOptions?: Parameters<typeof ip.onChildAdded>[2], options?: Parameters<typeof ip.onChildAdded>[3]) =>
+        rtdbOnChildAdded(target as never, (snapshot, previous) => callback(wrapWorkerSnapshot(snapshot), previous), cancelOrOptions as never, options, callback))
+    : ip.onChildAdded
+) as typeof ip.onChildAdded;
+export const onChildChanged = (
+  useWorker
+    ? ((target: Parameters<typeof ip.onChildChanged>[0], callback: Parameters<typeof ip.onChildChanged>[1], cancelOrOptions?: Parameters<typeof ip.onChildChanged>[2], options?: Parameters<typeof ip.onChildChanged>[3]) =>
+        rtdbOnChildChanged(target as never, (snapshot, previous) => callback(wrapWorkerSnapshot(snapshot), previous), cancelOrOptions as never, options, callback))
+    : ip.onChildChanged
+) as typeof ip.onChildChanged;
+export const onChildRemoved = (
+  useWorker
+    ? ((target: Parameters<typeof ip.onChildRemoved>[0], callback: Parameters<typeof ip.onChildRemoved>[1], cancelOrOptions?: Parameters<typeof ip.onChildRemoved>[2], options?: Parameters<typeof ip.onChildRemoved>[3]) =>
+        rtdbOnChildRemoved(target as never, (snapshot, previous) => callback(wrapWorkerSnapshot(snapshot), previous), cancelOrOptions as never, options, callback))
+    : ip.onChildRemoved
+) as typeof ip.onChildRemoved;
+export const onChildMoved = (
+  useWorker
+    ? ((target: Parameters<typeof ip.onChildMoved>[0], callback: Parameters<typeof ip.onChildMoved>[1], cancelOrOptions?: Parameters<typeof ip.onChildMoved>[2], options?: Parameters<typeof ip.onChildMoved>[3]) =>
+        rtdbOnChildMoved(target as never, (snapshot, previous) => callback(wrapWorkerSnapshot(snapshot), previous), cancelOrOptions as never, options, callback))
+    : ip.onChildMoved
+) as typeof ip.onChildMoved;
+export const onDisconnect = (
+  useWorker ? rtdbOnDisconnect : ip.onDisconnect
+) as typeof ip.onDisconnect;
+export const OnDisconnect = (
+  useWorker ? RtdbOnDisconnect : ip.OnDisconnect
+) as typeof ip.OnDisconnect;
 export const off = (useWorker ? rtdbOff : ip.off) as typeof ip.off;
+export const increment = ip.increment;
 export const serverTimestamp = (
   useWorker ? rtdbServerTimestamp : ip.serverTimestamp
 ) as typeof ip.serverTimestamp;
@@ -55,12 +146,12 @@ export const 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;
+// Served mode is always sandbox-backed (never a prod handle). The connection
+// controls still cross the worker boundary because goOffline drains that
+// port's one-shot onDisconnect queue; transport-selection controls remain
+// honest no-ops in either runtime.
+export const goOffline = (useWorker ? rtdbGoOffline : ip.goOffline) as typeof ip.goOffline;
+export const goOnline = (useWorker ? rtdbGoOnline : ip.goOnline) 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;
@@ -83,47 +174,79 @@ export const refFromURL = ((db: unknown, url: string) => {
   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
+  useWorker
+    ? (async (
+        target: Parameters<typeof ip.runTransaction>[0],
+        update: Parameters<typeof ip.runTransaction>[1],
+        options?: Parameters<typeof ip.runTransaction>[2],
+      ) => {
+        const result = await rtdbRunTransaction(
+          target as never,
+          update as (current: unknown) => unknown,
+          options,
+        );
+        return new ip.TransactionResult(result.committed, wrapWorkerSnapshot(result.snapshot));
+      })
+    : ip.runTransaction
 ) as typeof ip.runTransaction;
 
 export const query = (
-  useWorker ? (() => unsupportedWorkerApi('query')) : ip.query
+  useWorker
+    ? ((target: Parameters<typeof ip.query>[0], ...constraints: Parameters<typeof ip.query>[1][]) => {
+        const built = ip.query(target, ...constraints);
+        return {
+          ...built,
+          isEqual(other: ip.Query | null) {
+            return other !== null
+              && 'port' in built.ref
+              && 'port' in other.ref
+              && built.ref.port === other.ref.port
+              && built.ref._path === other.ref._path
+              && queryIdentifier(built._spec) === queryIdentifier(other._spec);
+          },
+        };
+      })
+    : 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;
+export const orderByChild = ip.orderByChild;
+export const orderByKey = ip.orderByKey;
+export const orderByPriority = ip.orderByPriority;
+export const orderByValue = ip.orderByValue;
+export const startAt = ip.startAt;
+export const startAfter = ip.startAfter;
+export const endAt = ip.endAt;
+export const endBefore = ip.endBefore;
+export const equalTo = ip.equalTo;
+export const limitToFirst = ip.limitToFirst;
+export const limitToLast = ip.limitToLast;
+
+export const setPriority = (
+  useWorker ? rtdbSetPriority : ip.setPriority
+) as typeof ip.setPriority;
+export const setWithPriority = (
+  useWorker ? rtdbSetWithPriority : ip.setWithPriority
+) as typeof ip.setWithPriority;
+
+// Runtime constructors and type-only declarations expected by common
+// `firebase/database` imports. Served worker results are wrapped above so the
+// public handles, snapshots, constraints, and transaction results keep these
+// observable constructor identities.
+export const Database = ip.Database;
+export const DataSnapshot = ip.DataSnapshot;
+export const QueryConstraint = ip.QueryConstraint;
+export const TransactionResult = ip.TransactionResult;
+export type Database = ip.Database;
+export type DataSnapshot = ip.DataSnapshot;
+export type QueryConstraint = ip.QueryConstraint;
+export type TransactionResult = ip.TransactionResult;
+export type OnDisconnect = ip.OnDisconnect;
+export type DatabaseReference = ip.DatabaseReference;
+export type EmulatorMockTokenOptions = ip.EmulatorMockTokenOptions;
+export type EventType = ip.EventType;
+export type ListenOptions = ip.ListenOptions;
+export type Query = ip.Query;
+export type QueryConstraintType = ip.QueryConstraintType;
+export type ThenableReference = ip.ThenableReference;
+export type TransactionOptions = ip.TransactionOptions;
+export type Unsubscribe = ip.Unsubscribe;

package/src/serve/entries/init.ts

@@ -2,7 +2,8 @@
  * `/__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.
+ * only; in fallback mode it mints credentials via `createSignInCredential`
+ * so OAuth users carry real provider metadata.
  */
 import { getAuth, sandbox as authSandbox } from 'pyric/auth';
 import {
@@ -19,27 +20,36 @@ import { getPyricRuntimeStatus } from '../runtime/status.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,
-        })),
-      }
-    : {
+const helper = workerAuth
+  ? new ServeAuthHelper({
+      list: async () => (await listUsers(workerAuth)).map((user) => ({
+        uid: user.uid,
+        email: user.email,
+        displayName: user.displayName,
+        customClaims: user.customClaims,
+      })),
+    })
+  : new ServeAuthHelper(
+      {
         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,
-        }]),
       },
-);
+      (request) => {
+        if (request.kind === 'pick') {
+          return authSandbox.createSignInCredential(localAuth!, {
+            providerId: request.providerId,
+            uid: request.identity.uid,
+          });
+        }
+        return authSandbox.createSignInCredential(localAuth!, {
+          providerId: request.providerId,
+          spec: {
+            email: request.spec.email,
+            displayName: request.spec.displayName,
+            customClaims: request.spec.customClaims,
+          },
+        });
+      },
+    );
 const resolver = helper.resolver();
 installServeAuthResolver(resolver);
 if (localAuth) authSandbox.setAuthFlowResolver(localAuth, resolver);

package/src/serve/html-injection.ts

@@ -0,0 +1,65 @@
+import { SANDBOX_BUILD_MARKER } from './sandbox-marker.js';
+
+/** The import-map targets. Spec → served URL. */
+export function sdkImportMap(): Record<string, string> {
+  return {
+    'firebase/ai': '/__pyric/sdk/ai.js',
+    'firebase/app': '/__pyric/sdk/app.js',
+    'firebase/auth': '/__pyric/sdk/auth.js',
+    'firebase/database': '/__pyric/sdk/database.js',
+    'firebase/firestore': '/__pyric/sdk/firestore.js',
+    'firebase/messaging': '/__pyric/sdk/messaging.js',
+    'firebase/messaging/sw': '/__pyric/sdk/messaging-sw.js',
+    'firebase/storage': '/__pyric/sdk/storage.js',
+  };
+}
+
+/** Inject the sandbox import map and boot tags before application modules. */
+export function injectServeTags(
+  html: string,
+  importMap: Record<string, string> = sdkImportMap(),
+  workerVersion?: string,
+  forceInPage = false,
+): string {
+  const marker = 'data-pyric-serve';
+  if (html.includes(marker)) return html;
+  // A sandbox build already bundles its runtime. Adding the import map and
+  // init module would boot a second backend; only the staleness stamp belongs.
+  if (html.includes(SANDBOX_BUILD_MARKER)) {
+    if (!workerVersion || html.includes('pyric-worker-v')) return html;
+    const meta = `<meta name="pyric-worker-v" content="${workerVersion}" ${marker}>`;
+    const headTag = html.match(/<head[^>]*>/i);
+    if (headTag && headTag.index !== undefined) {
+      const at = headTag.index + headTag[0].length;
+      return html.slice(0, at) + meta + html.slice(at);
+    }
+    return meta + html;
+  }
+
+  // SharedWorkers survive page reloads, so the page compares this served hash
+  // with the worker's baked hash and can offer an explicit worker update.
+  const versionMeta = workerVersion
+    ? `<meta name="pyric-worker-v" content="${workerVersion}" ${marker}>`
+    : '';
+  // Bridge mode must select the in-page backend before any application module
+  // runs, otherwise the agent and application would use different sandboxes.
+  const forceTag = forceInPage
+    ? `<script ${marker}>globalThis.__PYRIC_FORCE_INPAGE__=true;</script>`
+    : '';
+  const tags =
+    versionMeta +
+    forceTag +
+    `<script type="importmap" ${marker}>${JSON.stringify({ imports: importMap })}</script>` +
+    `<script type="module" src="/__pyric/sdk/init.js" ${marker}></script>`;
+  const head = html.match(/<head[^>]*>/i);
+  if (head && head.index !== undefined) {
+    const at = head.index + head[0].length;
+    return html.slice(0, at) + tags + html.slice(at);
+  }
+  const htmlTag = html.match(/<html[^>]*>/i);
+  if (htmlTag && htmlTag.index !== undefined) {
+    const at = htmlTag.index + htmlTag[0].length;
+    return html.slice(0, at) + tags + html.slice(at);
+  }
+  return tags + html;
+}