create-pyric 0.1.0-alpha.22 → 0.1.0-alpha.25

package/src/package-manager.ts

@@ -0,0 +1,38 @@
+/**
+ * The package manager that ran `create pyric`, so the printed next steps
+ * name the commands the user already uses.
+ */
+
+export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';
+
+const PACKAGE_MANAGERS: readonly PackageManager[] = ['npm', 'pnpm', 'yarn', 'bun'];
+
+/** A step a template writes for one package manager, such as `bun run dev`. */
+const PACKAGE_MANAGER_STEP = /^(npm|bun) /;
+
+/** The alternative a template names after a step, such as `# or: bun install`. */
+const ALTERNATIVE_COMMENT = /\s+# or: .*$/;
+
+/**
+ * Reads the `npm_config_user_agent` value every package manager sets for
+ * `create` and `exec`, such as `pnpm/9.0.0 npm/? node/v22.15.0 linux x64`.
+ * Without one, the user ran the binary directly, and the docs use npm.
+ */
+export function detectPackageManager(userAgent: string | undefined): PackageManager {
+  const name = userAgent?.split('/')[0];
+  const known = PACKAGE_MANAGERS.find((pm) => pm === name);
+  return known ?? 'npm';
+}
+
+/**
+ * Rewrites each `npm <command>` or `bun <command>` step to the same command
+ * for `pm`, and drops the `# or: ...` alternative, since the step now names
+ * the package manager in use.
+ */
+export function nextStepsFor(steps: readonly string[], pm: PackageManager): string[] {
+  return steps.map((step) => {
+    const isPackageManagerStep = PACKAGE_MANAGER_STEP.test(step);
+    if (!isPackageManagerStep) return step;
+    return step.replace(PACKAGE_MANAGER_STEP, `${pm} `).replace(ALTERNATIVE_COMMENT, '');
+  });
+}

package/src/scaffold.ts

@@ -19,16 +19,16 @@ import type { FlagValue } from './parse-args.js';
 export type { ScaffoldTemplate, TemplateName };
 export { TEMPLATES, TEMPLATE_NAMES, isTemplateName } from './templates.js';
 
-/** Where the scaffold's `pyric` / `@pyric/cli` deps come from. */
+/** Where the scaffold's `pyric` / `@pyric/cli` / `@pyric/ui` deps come from. */
 export type DepsMode = 'vendor' | 'npm';
 
-/** Return a copy of `t` with `pyric` / `@pyric/cli` deps rewritten for `mode`. */
+/** Return a copy of `t` with `pyric` / `@pyric/cli` / `@pyric/ui` deps rewritten for `mode`. */
 export function applyDepsMode(
   t: ScaffoldTemplate,
   mode: DepsMode,
   opts: { vendorSpecs?: Record<string, string>; version?: string | null },
 ): ScaffoldTemplate {
-  const WORKSPACE_PKGS = ['pyric', '@pyric/cli'];
+  const WORKSPACE_PKGS = ['pyric', '@pyric/cli', '@pyric/ui'];
   const rewrite = (section: Record<string, string>): Record<string, string> => {
     const next = { ...section };
     for (const pkg of WORKSPACE_PKGS) {
@@ -202,7 +202,7 @@ export interface ScaffoldRequest {
   depsMode?: DepsMode;
   /** Already-rewritten template; defaults to TEMPLATES[template] (+ npm pin). */
   effectiveTemplate?: ScaffoldTemplate;
-  /** Version pin for npm-mode `@pyric/cli` / `pyric` ranges. */
+  /** Version pin for npm-mode `@pyric/cli` / `pyric` / `@pyric/ui` ranges. */
   pinVersion?: string | null;
   /** Label used in human report lines (`create-pyric` or `pyric init`). */
   commandLabel?: string;
@@ -281,7 +281,7 @@ export async function runScaffold(
     merged: [],
     skipped: [],
     conflicts: [],
-    nextSteps: template.nextSteps,
+    nextSteps: effective.nextSteps,
   };
 
   const pkgPath = join(dir, 'package.json');

package/src/template-nextjs.ts

@@ -1,6 +1,7 @@
 /**
  * Scaffold template definition for Next.js (`npm create pyric -- --template nextjs`).
  */
+import { FIREBASE_ADMIN_PIN, FIREBASE_PIN } from './firebase-pins.js';
 import type { ScaffoldTemplate } from './templates.js';
 
 const NEXTJS_CONFIG_MJS = `import { fileURLToPath } from 'node:url';
@@ -491,8 +492,8 @@ export const NEXTJS_TEMPLATE: ScaffoldTemplate = {
     start: 'next start',
   },
   dependencies: {
-    firebase: '^12.12.0',
-    'firebase-admin': '^13.0.0',
+    firebase: FIREBASE_PIN,
+    'firebase-admin': FIREBASE_ADMIN_PIN,
     next: '^15.0.0',
     react: '^19.0.0',
     'react-dom': '^19.0.0',

package/src/templates.ts

@@ -19,6 +19,7 @@
 import { lstatSync, readFileSync, readdirSync } from 'node:fs';
 import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { FIREBASE_PIN } from './firebase-pins.js';
 import { NEXTJS_TEMPLATE } from './template-nextjs.js';
 
 export const TEMPLATE_NAMES = ['web', 'node', 'static', 'chat', 'nextjs'] as const;
@@ -182,8 +183,9 @@ const WEB_INDEX_HTML = (name: string): string => `<!doctype html>
 `;
 
 const WEB_APP_JS = `// Canonical firebase/* imports. Under \`pyric sandbox\` they are served by the
-// in-page pyric sandbox (the config below is ignored); under any standard
-// bundler/pipeline the same imports resolve to the real \`firebase\` package.
+// in-page pyric sandbox (no request reaches the project the config names);
+// under any standard bundler/pipeline the same imports resolve to the real
+// \`firebase\` package.
 // Graduation changes where you run this code, never the code itself.
 import { initializeApp } from 'firebase/app';
 import {
@@ -347,7 +349,8 @@ const FIRESTORE_INDEXES = `{
 // ─── node template (init v1 scaffold, carried over) ───────────────────
 
 const NODE_APP_TS = `// Canonical Firebase imports stay unchanged between sandbox and production.
-// \`bun run dev\` activates @pyric/cli/register; \`bun start\` loads Firebase.
+// \`bun run dev\` runs this file against the Node-hosted Pyric sandbox
+// (\`pyric sandbox --hosted\`); \`bun start\` loads Firebase.
 import { initializeApp } from 'firebase/app';
 import { getFirestore, collection, getDocs } from 'firebase/firestore';
 import { seed } from './seed.ts';
@@ -371,15 +374,17 @@ snap.forEach((doc) => console.log(\`  \${doc.id}:\`, doc.data()));
 // Production: fill .env, deploy firestore.rules, then \`bun start\`.
 `;
 
-const NODE_SEED_TS = `import { collection, addDoc, type Firestore } from 'firebase/firestore';
+const NODE_SEED_TS = `import { doc, setDoc, type Firestore } from 'firebase/firestore';
 
+// Fixed ids: the hosted sandbox keeps its data between runs, so each
+// \`bun run dev\` rewrites the same two posts instead of adding two more.
 export async function seed(db: Firestore): Promise<void> {
-  await addDoc(collection(db, 'posts'), {
+  await setDoc(doc(db, 'posts', 'hello'), {
     title: 'Hello, Pyric',
     author: 'sandbox',
     createdAt: new Date(),
   });
-  await addDoc(collection(db, 'posts'), {
+  await setDoc(doc(db, 'posts', 'local-first'), {
     title: 'Local-first by default',
     author: 'sandbox',
     createdAt: new Date(),
@@ -432,7 +437,7 @@ real Firebase in production. No application-code switch is required.
 
 \`\`\`bash
 bun install
-bun run dev        # Pyric sandbox through the Node package swap
+bun run dev        # Pyric sandbox hosted in Node (pyric sandbox --hosted)
 bun start          # production: real Firebase
 \`\`\`
 
@@ -490,13 +495,17 @@ const VITE_INDEX_HTML = (name: string): string => `<!doctype html>
       form { display: flex; gap: 0.5rem; margin: 1rem 0; }
       input { flex: 1; padding: 0.4rem 0.6rem; }
       ul { padding-left: 1.2rem; }
-      .status { color: #666; }
+      .status { color: #666; display: flex; align-items: center; gap: 0.5rem; }
+      .avatar { width: 32px; height: 32px; border-radius: 50%; }
     </style>
   </head>
   <body>
     <main>
       <h1>${name}</h1>
-      <p class="status" id="auth-status">Signed out</p>
+      <p class="status">
+        <img class="avatar" id="avatar" alt="" hidden />
+        <span id="auth-status">Signed out</span>
+      </p>
       <button id="sign-in">Sign in with Google</button>
       <button id="sign-out" hidden>Sign out</button>
       <!-- Visible even while signed out ON PURPOSE — submitting attempts the
@@ -512,10 +521,11 @@ const VITE_INDEX_HTML = (name: string): string => `<!doctype html>
 </html>
 `;
 
-const VITE_MAIN_TS = `// Canonical firebase/* imports — UNCHANGED between dev and prod.
+const VITE_MAIN_TS = `// Canonical firebase/* imports, the same in dev and prod.
 // In \`vite dev\` the \`@pyric/cli/vite\` plugin swaps these to an in-process
-// sandbox (the config below is accepted but ignored). \`vite build\` ships the
-// real \`firebase\` package and uses the SAME config. Graduation is a build, not
+// sandbox: no request reaches the project the config below names, and the
+// sandbox reads its projectId the way Firebase does. \`vite build\` ships the
+// real \`firebase\` package with the same config. Graduation is a build, not
 // a code edit.
 import { initializeApp } from 'firebase/app';
 import {
@@ -553,7 +563,7 @@ if (hasProjectId) {
 
 const app = initializeApp({
   // Filled from .env (see .env.example) at \`vite build\` time for production.
-  // Ignored in \`vite dev\` — the pyric sandbox stands in for Firebase.
+  // In \`vite dev\` the pyric sandbox stands in for Firebase and reads projectId.
   apiKey,
   authDomain,
   projectId,
@@ -564,6 +574,7 @@ const db = getFirestore(app);
 const $ = <T extends HTMLElement>(id: string): T => document.getElementById(id) as T;
 const els = {
   status: $('auth-status'),
+  avatar: $<HTMLImageElement>('avatar'),
   signIn: $<HTMLButtonElement>('sign-in'),
   signOut: $<HTMLButtonElement>('sign-out'),
   form: $<HTMLFormElement>('add-post'),
@@ -579,7 +590,7 @@ let unsubscribePosts: (() => void) | undefined = undefined;
 onAuthStateChanged(auth, (user) => {
   const hasActiveSubscription = unsubscribePosts !== undefined;
   if (hasActiveSubscription) {
-    unsubscribePosts();
+    unsubscribePosts?.();
     unsubscribePosts = undefined;
   }
 
@@ -595,6 +606,16 @@ onAuthStateChanged(auth, (user) => {
       displayLabel = user.displayName as string;
     }
     els.status.textContent = 'Signed in as ' + displayLabel;
+    // Provider sign-ins always carry a photoURL, in the sandbox as in
+    // production; email/password and anonymous users have none.
+    const hasPhoto = user.photoURL !== null;
+    if (hasPhoto) {
+      els.avatar.src = user.photoURL as string;
+      els.avatar.hidden = false;
+    } else {
+      els.avatar.src = '';
+      els.avatar.hidden = true;
+    }
     els.signIn.hidden = true;
     els.signOut.hidden = false;
 
@@ -616,6 +637,8 @@ onAuthStateChanged(auth, (user) => {
     });
   } else {
     els.status.textContent = 'Signed out';
+    els.avatar.hidden = true;
+    els.avatar.src = '';
     els.signIn.hidden = false;
     els.signOut.hidden = true;
     els.posts.replaceChildren();
@@ -671,8 +694,34 @@ import { pyric } from '@pyric/cli/vite';
 // self-contained sandbox preview you can serve under \`pyric sandbox\`, build with a
 // non-production mode: \`vite build --mode development\` (see the \`build:sandbox\`
 // script). That output is marked and can never be deployed.
+
+// A custom avatar generator lives in its own file so this config stays
+// small. The pyric example app ships vite.avatars.ts with a worked example
+// that calls an image API; write your own function of the same shape to
+// use the \`avatars.source\` option below.
+// import { nanoBananaAvatar } from './vite.avatars';
+
 export default defineConfig({
-  plugins: [pyric()],
+  plugins: [
+    pyric({
+      // Profile photos for provider sign-ins. The default needs no
+      // configuration: every federated sign-in gets a deterministic
+      // generated avatar. Comment exactly one option back in to try the
+      // alternatives.
+
+      // Firebase-null behaviour — photoURL stays null and the avatar
+      // route unmounts:
+      // avatars: false,
+
+      // A pre-created avatar set: a directory holding a manifest.json and
+      // image files; each user is deterministically assigned one:
+      // avatars: './avatars',
+
+      // Generate each user's photo once, on demand, with the function
+      // named in the commented import above:
+      // avatars: { source: nanoBananaAvatar },
+    }),
+  ],
 });
 `;
 
@@ -777,7 +826,7 @@ export const TEMPLATES: Record<TemplateName, ScaffoldTemplate> = {
     },
     // The real firebase package ships day one so the production `vite build`
     // resolves the same canonical imports against it — no code edit at graduation.
-    dependencies: { firebase: '^12.12.0' },
+    dependencies: { firebase: FIREBASE_PIN },
     devDependencies: { '@pyric/cli': '*', vite: '^6.0.0', typescript: '^5.7.0' },
     dirs: ['src'],
     files: (name) => [
@@ -802,10 +851,10 @@ export const TEMPLATES: Record<TemplateName, ScaffoldTemplate> = {
   node: {
     scripts: {
       start: 'node --env-file-if-exists=.env --experimental-strip-types src/app.ts',
-      dev: 'pyric sandbox --no-open -- node --env-file-if-exists=.env --experimental-strip-types src/app.ts',
+      dev: 'pyric sandbox --hosted --no-open -- node --env-file-if-exists=.env --experimental-strip-types src/app.ts',
      bridge: 'pyric bridge',
     },
-    dependencies: { firebase: '^12.12.0' },
+    dependencies: { firebase: FIREBASE_PIN },
     devDependencies: { '@pyric/cli': '*', '@types/node': '^22.0.0', typescript: '^5.7.0' },
     dirs: ['src'],
     files: (name) => [
@@ -828,7 +877,7 @@ export const TEMPLATES: Record<TemplateName, ScaffoldTemplate> = {
       dev: 'pyric sandbox --seed seed.json',
      'dev:agent': 'pyric sandbox --bridge --seed seed.json',
     },
-    dependencies: { firebase: '^12.12.0' },
+    dependencies: { firebase: FIREBASE_PIN },
     devDependencies: { '@pyric/cli': '*' },
     dirs: ['public'],
     files: (name) => [

package/templates/chat/.env.development

@@ -0,0 +1,6 @@
+# Loaded by Vite for `--mode development`, which includes the served sandbox
+# build (`npm run build:sandbox`). Vite otherwise treats every `vite build` as
+# NODE_ENV=production, which turns off pyric's listener attribution and the
+# React component capture behind it. Development is also what the plain
+# `vite dev` path runs as, so the two sandbox paths behave the same.
+NODE_ENV=development

package/templates/chat/database.rules.json

@@ -1,16 +1,16 @@
 {
   "rules": {
     "presence": {
-      ".read": "auth !== null",
+      ".read": "auth != null",
       "$uid": {
-        ".write": "auth !== null && auth.uid === $uid",
+        ".write": "auth != null && auth.uid == $uid",
         ".validate": "newData.hasChildren(['state', 'at']) && newData.child('state').isString()"
       }
     },
     "notify": {
       "$uid": {
-        ".read": "auth !== null && auth.uid === $uid",
-        ".write": "auth !== null && auth.uid === $uid",
+        ".read": "auth != null && auth.uid == $uid",
+        ".write": "auth != null && auth.uid == $uid",
         "$pushId": {
           ".validate": "newData.hasChildren(['title', 'body']) && newData.child('title').isString() && newData.child('body').isString()"
         }

package/templates/chat/functions/package.json

@@ -9,7 +9,7 @@
     "node": "20"
   },
   "dependencies": {
-    "firebase-admin": "^13.10.0",
+    "firebase-admin": "~13.10.0",
     "firebase-functions": "^6.0.0"
   }
 }

package/templates/chat/package.json

@@ -9,6 +9,7 @@
     "build:sandbox": "vite build --mode development",
     "test": "node --experimental-strip-types --test test/*.test.*",
     "test:notifications": "npm run build && node --experimental-strip-types scripts/check-notification-build.ts",
+    "test:listener-owner": "node --experimental-strip-types scripts/check-listener-owner-build.ts",
     "preview": "vite preview",
     "typecheck": "tsc --noEmit",
     "rules:resolve": "pyric firestore rules resolve firestore.modules.rules --out firestore.rules"
@@ -25,7 +26,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "esbuild-wasm": "^0.25.0",
-    "firebase": "^12.12.0",
+    "firebase": "~12.13.0",
     "lucide-react": "^1.25.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
@@ -37,6 +38,7 @@
   },
   "devDependencies": {
     "@pyric/cli": "*",
+    "@pyric/ui": "*",
     "@tailwindcss/vite": "^4.3.3",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
@@ -46,7 +48,7 @@
     "typescript": "^5.7.0",
     "vite": "^6.0.0",
     "pyric": "*",
-    "firebase-admin": "^13.10.0",
+    "firebase-admin": "~13.10.0",
     "firebase-functions": "^6.0.0"
   }
 }

package/templates/chat/scaffold.json

@@ -1,5 +1,6 @@
 {
   "include": [
+    ".env.development",
     ".env.example",
     "README.md",
     "components.json",

package/templates/chat/scripts/check-listener-owner-build.ts

@@ -0,0 +1,73 @@
+/**
+ * Proves that listener attribution costs the production build nothing.
+ *
+ * The app calls `useListenerOwner` from `@pyric/ui/listener-owner` to name
+ * the React component that owns each Firestore listener. That hook gates its
+ * capture on `process.env.NODE_ENV`, and `@pyric/cli/vite` swaps `firebase/*`
+ * to pyric only outside production mode. Both claims are checked here by
+ * building the app twice and reading the emitted JavaScript.
+ *
+ * Two markers are read:
+ *
+ * - `pyric`, which appears throughout the sandbox implementation. A
+ *   production bundle must not contain it anywhere.
+ * - the string `/node_modules/`, the frame filter the hook uses when it reads
+ *   a render-phase call stack. It is present only when the capture survived
+ *   the build, so it stands in for the capture itself.
+ *
+ * A production build must carry neither. A development-mode build, the one
+ * `npm run build:sandbox` produces for serving under `pyric sandbox`, must
+ * carry both, which is what makes the production result evidence of the gate
+ * rather than of a marker that never existed.
+ */
+import { execFileSync } from 'node:child_process';
+import { readdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PYRIC_MARKER = 'pyric';
+const CAPTURE_MARKER = '/node_modules/';
+
+const scriptDirectory = dirname(fileURLToPath(import.meta.url));
+const templateDirectory = join(scriptDirectory, '..');
+
+/** Build the app in `mode` into its own directory and return the emitted
+ *  application JavaScript, the service worker excluded. */
+async function buildAndRead(mode: string, outDirectory: string): Promise<string> {
+  execFileSync(
+    'npx',
+    ['vite', 'build', '--mode', mode, '--emptyOutDir', '--outDir', outDirectory],
+    { cwd: templateDirectory, stdio: 'inherit' },
+  );
+  const assetsDirectory = join(templateDirectory, outDirectory, 'assets');
+  const names = (await readdir(assetsDirectory)).filter(
+    (name) => name.endsWith('.js') && !name.startsWith('firebase-messaging-sw-'),
+  );
+  if (names.length === 0) {
+    throw new Error(`The ${mode} build emitted no application JavaScript.`);
+  }
+  const sources = await Promise.all(
+    names.map((name) => readFile(join(assetsDirectory, name), 'utf8')),
+  );
+  return sources.join('\n');
+}
+
+const production = await buildAndRead('production', 'dist/listener-owner-check/production');
+
+if (production.includes(PYRIC_MARKER)) {
+  throw new Error('The production bundle contains pyric.');
+}
+if (production.includes(CAPTURE_MARKER)) {
+  throw new Error('The production bundle contains the listener-owner stack capture.');
+}
+
+const development = await buildAndRead('development', 'dist/listener-owner-check/development');
+
+if (!development.includes(PYRIC_MARKER)) {
+  throw new Error('The development-mode bundle does not contain pyric, so the production result proves nothing.');
+}
+if (!development.includes(CAPTURE_MARKER)) {
+  throw new Error('The development-mode bundle does not contain the listener-owner stack capture, so the production result proves nothing.');
+}
+
+console.log('Listener owner build checks passed: pyric and the stack capture are in the development build and absent from the production build.');

package/templates/chat/src/services/conversation-service.ts

@@ -16,6 +16,7 @@ import {
   type Query,
   type QueryDocumentSnapshot,
   type QuerySnapshot,
+  type SnapshotListenOptions,
 } from 'firebase/firestore';
 import { auth, db } from '../firebase/app';
 import {
@@ -28,7 +29,7 @@ import {
   type PageOptions,
   ServiceError,
 } from '../firebase/types';
-import { clampPageSize, mapFirestoreError, requireUid } from './firestore-helpers';
+import { clampPageSize, listenOptions, mapFirestoreError, requireUid, type ListenerOptions } from './firestore-helpers';
 
 const allowedModels = new Set(['gemini-3.5-flash', 'gemini-3.1-flash-lite', 'gemini-2.5-flash', 'gemini-2.0-flash', 'gemini-1.5-flash', 'gemini-flash-lite-latest']);
 const cleanTitle = (title: string): string => title.trim().slice(0, 120) || 'New conversation';
@@ -59,10 +60,10 @@ export class ConversationService {
     }
   }
 
-  observeList(callback: (conversations: Conversation[]) => void, options: PageOptions = {}): () => void {
+  observeList(callback: (conversations: Conversation[]) => void, options: PageOptions & ListenerOptions = {}): () => void {
     const uid = requireUid(auth.currentUser?.uid);
     const pageSize = clampPageSize(options.pageSize);
-    return onSnapshot(conversationQuery(uid, pageSize), (snapshot) => callback(snapshot.docs.map(toConversation)));
+    return onSnapshot(conversationQuery(uid, pageSize), listenOptions<SnapshotListenOptions>(options), (snapshot) => callback(snapshot.docs.map(toConversation)));
   }
 
   async create(input: CreateConversationInput = {}): Promise<Conversation['id']> {
@@ -146,9 +147,9 @@ export class ConversationService {
     }
   }
 
-  observe(id: Conversation['id'], callback: (value: Conversation) => void): () => void {
+  observe(id: Conversation['id'], callback: (value: Conversation) => void, options?: ListenerOptions): () => void {
     requireUid(auth.currentUser?.uid);
-    return onSnapshot(doc(db, 'conversations', id), (snapshot) => {
+    return onSnapshot(doc(db, 'conversations', id), listenOptions<SnapshotListenOptions>(options), (snapshot) => {
       if (snapshot.exists()) callback({ id, ...(snapshot.data() as ConversationDocument) });
     });
   }

package/templates/chat/src/services/firestore-helpers.ts

@@ -1,3 +1,4 @@
+import type { ListenerOwner } from '@pyric/ui/listener-owner';
 import {
   doc,
   type DocumentData,
@@ -37,3 +38,20 @@ export const typedDoc = <T extends DocumentData>(firestore: Firestore, path: str
 
 export const clampPageSize = (value: number | undefined, fallback = 50): number =>
   Math.min(Math.max(Math.trunc(value ?? fallback), 1), 100);
+
+/**
+ * Who owns a listener: either a region name the caller gives it, or the
+ * React component `useListenerOwner` identified. Under the local sandbox the
+ * SDK records this as the listener's owner, which is how the runtime chip and
+ * Studio group listeners by the UI they feed. The production SDK reads only
+ * its own keys from the listen options and ignores the owner.
+ *
+ * `ListenerOwner` is a type-only import. `@pyric/ui` is a development
+ * dependency and none of it reaches the production build.
+ */
+export type ListenerOptions = { owner?: string | ListenerOwner };
+
+/** The listen options object to hand the SDK, typed as whatever the SDK expects so the extra key passes. */
+export function listenOptions<T extends object>(options: ListenerOptions | undefined): T {
+  return (options?.owner === undefined ? {} : { owner: options.owner }) as T;
+}

package/templates/chat/src/services/message-service.ts

@@ -11,11 +11,12 @@ import {
   serverTimestamp,
   startAfter,
   where,
+  type SnapshotListenOptions,
 } from 'firebase/firestore';
 import { push, ref, serverTimestamp as rtdbServerTimestamp } from 'firebase/database';
 import { auth, db, rtdb } from '../firebase/app';
 import { asMessageId, type AppendAssistantMessageInput, type AppendUserMessageInput, type Message, type MessageDocument, type Page, type PageOptions, ServiceError } from '../firebase/types';
-import { clampPageSize, mapFirestoreError, requireUid } from './firestore-helpers';
+import { clampPageSize, mapFirestoreError, requireUid, listenOptions, type ListenerOptions } from './firestore-helpers';
 
 const toMessage = (snapshot: { id: string; data: () => unknown }): Message => ({
   id: asMessageId(snapshot.id),
@@ -144,9 +145,9 @@ export class MessageService {
     }
   }
 
-  observeRecent(conversationId: string, callback: (messages: Message[]) => void): () => void {
+  observeRecent(conversationId: string, callback: (messages: Message[]) => void, options?: ListenerOptions): () => void {
     const uid = requireUid(auth.currentUser?.uid);
     const messageQuery = query(messageCollection(conversationId), where('ownerUid', '==', uid), orderBy('createdAt', 'desc'), limit(50));
-    return onSnapshot(messageQuery, (snapshot) => callback(snapshot.docs.map(toMessage).reverse()));
+    return onSnapshot(messageQuery, listenOptions<SnapshotListenOptions>(options), (snapshot) => callback(snapshot.docs.map(toMessage).reverse()));
   }
 }

package/templates/chat/src/services/presence-service.ts

@@ -1,7 +1,7 @@
-import { onDisconnect, onValue, ref, serverTimestamp, set } from 'firebase/database';
+import { onDisconnect, onValue, ref, serverTimestamp, set, type ListenOptions } from 'firebase/database';
 import { auth, rtdb } from '../firebase/app';
 import { asUserId, type AuthUser, type PresenceEntry, type PresenceRecord, ServiceError } from '../firebase/types';
-import { requireUid } from './firestore-helpers';
+import { listenOptions, requireUid, type ListenerOptions } from './firestore-helpers';
 
 const mapRtdbError = (error: unknown): ServiceError => {
   const code = typeof error === 'object' && error && 'code' in error ? String(error.code) : '';
@@ -50,7 +50,7 @@ export class PresenceService {
   }
 
   /** Observe every presence node; the callback receives the online members. */
-  observe(callback: (online: PresenceEntry[]) => void): () => void {
+  observe(callback: (online: PresenceEntry[]) => void, options?: ListenerOptions): () => void {
     requireUid(auth.currentUser?.uid);
     return onValue(ref(rtdb, 'presence'), (snapshot) => {
       const entries: PresenceEntry[] = [];
@@ -59,6 +59,6 @@ export class PresenceService {
         if (entry && entry.state === 'online') entries.push(entry);
       });
       callback(entries);
-    });
+    }, listenOptions<ListenOptions>(options));
   }
 }

package/templates/chat/src/ui/chat/chat-format.ts

@@ -0,0 +1,8 @@
+import type { UiUser } from './chat-types';
+
+/** The initials shown in an avatar for a user, or for "You" when there is none. */
+export const initials = (user: UiUser | null): string =>
+  (user?.displayName ?? user?.email ?? 'You').split(' ').map((part) => part[0]).join('').slice(0, 2).toUpperCase();
+
+/** A short local time for a conversation or message timestamp. */
+export const formatTime = (date?: Date): string => date ? new Intl.DateTimeFormat(undefined, { hour: 'numeric', minute: '2-digit' }).format(date) : '';