@pyric/cli 0.1.0-alpha.16 → 0.1.0-alpha.17

package/src/register/mapping.ts

@@ -23,11 +23,57 @@ const MAPPINGS: ReadonlyArray<readonly [from: string, to: string]> = [
  * Map a Firebase specifier to its pyric mirror, or return `null` when the
  * specifier is not a Firebase package (leave it for the default resolver).
  */
-export function mapFirebaseSpecifier(specifier: string): string | null {
-  if (specifier === 'firebase/app') return 'pyric/app/register';
+export function mapFirebaseSpecifier(
+  specifier: string,
+  importer?: string,
+  options?: { aiMode?: 'sandbox' | 'production' },
+): string | null {
+  const isShadowBridgeImporter = importer !== undefined &&
+    (importer.includes('app-bridge') || importer.includes('app-ai-passthrough'));
+  const isFirebaseAppSpecifier = specifier === 'firebase/app';
+  const isBypassedBridgeImport = isShadowBridgeImporter && isFirebaseAppSpecifier;
+  if (isBypassedBridgeImport) {
+    return null;
+  }
+
+  let mode: 'sandbox' | 'production' = 'sandbox';
+  const explicitMode = options?.aiMode;
+  const hasExplicitMode = explicitMode !== undefined;
+  if (hasExplicitMode) {
+    mode = explicitMode;
+  } else {
+    const isEnvProductionMode = process.env.PYRIC_AI_MODE === 'production';
+    const isEnvPassthroughFlag = process.env.PYRIC_AI_PASSTHROUGH === '1';
+    const isProductionEnv = isEnvProductionMode || isEnvPassthroughFlag;
+    if (isProductionEnv) {
+      mode = 'production';
+    }
+  }
+
+  const isProductionMode = mode === 'production';
+  const isFirebaseAiSpecifier = specifier === 'firebase/ai';
+  const isProductionAiPassthrough = isProductionMode && isFirebaseAiSpecifier;
+  if (isProductionAiPassthrough) {
+    return null;
+  }
+
+  if (isFirebaseAppSpecifier) {
+    if (isProductionMode) {
+      return '@pyric/cli/register/app-bridge';
+    }
+    return 'pyric/app/register';
+  }
+
   for (const [from, to] of MAPPINGS) {
-    if (specifier === from) return to;
-    if (specifier.startsWith(`${from}/`)) return to + specifier.slice(from.length);
+    const isExactMatch = specifier === from;
+    if (isExactMatch) {
+      return to;
+    }
+    const isSubpathMatch = specifier.startsWith(`${from}/`);
+    if (isSubpathMatch) {
+      const subpath = specifier.slice(from.length);
+      return to + subpath;
+    }
   }
   return null;
 }

package/src/rtdb/rules-json.ts

@@ -27,3 +27,113 @@ export function isRtdbRulesDocument(value: unknown): value is RtdbRulesDocument
 function isRtdbRulesObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+
+/**
+ * Strip JavaScript-style line comments (`//...`) and block comments (`/*...*\/`)
+ * from JSON source text without altering string literals. Firebase Realtime
+ * Database security rules files (`database.rules.json`) permit comment blocks,
+ * requiring pre-processing before evaluation with standard JSON parsers.
+ */
+export function stripJsonComments(text: string): string {
+  let result = '';
+  let inString = false;
+  let inSingleLineComment = false;
+  let inMultiLineComment = false;
+  let i = 0;
+
+  while (i < text.length) {
+    const char = text[i];
+    const nextChar = i + 1 < text.length ? text[i + 1] : '';
+
+    if (inSingleLineComment) {
+      const isNewline = char === '\n' || char === '\r';
+      if (isNewline) {
+        inSingleLineComment = false;
+        result += char;
+      }
+      i++;
+      continue;
+    }
+
+    if (inMultiLineComment) {
+      const isEndOfBlock = char === '*' && nextChar === '/';
+      if (isEndOfBlock) {
+        inMultiLineComment = false;
+        i += 2;
+      } else {
+        const isNewline = char === '\n' || char === '\r';
+        if (isNewline) {
+          result += char; // Preserve line numbering for accurate diagnostics
+        }
+        i++;
+      }
+      continue;
+    }
+
+    if (inString) {
+      const isEscape = char === '\\';
+      if (isEscape) {
+        result += char;
+        if (nextChar !== '') {
+          result += nextChar;
+          i++;
+        }
+        i++;
+        continue;
+      }
+      const isQuote = char === '"';
+      if (isQuote) {
+        inString = false;
+      }
+      result += char;
+      i++;
+      continue;
+    }
+
+    const isQuote = char === '"';
+    if (isQuote) {
+      inString = true;
+      result += char;
+      i++;
+      continue;
+    }
+
+    const isLineCommentStart = char === '/' && nextChar === '/';
+    if (isLineCommentStart) {
+      inSingleLineComment = true;
+      i += 2;
+      continue;
+    }
+
+    const isBlockCommentStart = char === '/' && nextChar === '*';
+    if (isBlockCommentStart) {
+      inMultiLineComment = true;
+      i += 2;
+      continue;
+    }
+
+    result += char;
+    i++;
+  }
+
+  return result;
+}
+
+/**
+ * Parse a JSON string that may contain line or block comments into a validated
+ * Realtime Database rules document structure.
+ */
+export function parseRtdbRulesText(
+  text: string,
+  onInvalid: (error: Error) => Error,
+): RtdbRulesJson {
+  const clean = stripJsonComments(text);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(clean);
+  } catch (e) {
+    const detail = e instanceof Error ? e.message : String(e);
+    throw onInvalid(new Error(`Failed to parse rules JSON: ${detail}`));
+  }
+  return parseRtdbRulesJson(parsed, () => onInvalid(new Error('Document must contain a top-level "rules" object.')));
+}

package/src/serve/bundler.ts

@@ -57,6 +57,7 @@ export function defaultSdkEntries(): Record<string, string> {
   return {
     ai: pick('ai'),
     app: pick('app'),
+    'app-ai-passthrough': pick('app-ai-passthrough'),
     auth: pick('auth'),
     firestore: pick('firestore'),
     database: pick('database'),
@@ -309,6 +310,7 @@ export async function bundleSdk(opts: BundleOptions): Promise<BundleResult> {
       sourcemap: 'linked',
       minify: opts.minify ?? true,
       logLevel: 'silent',
+      external: ['firebase/*'],
       // Provenance: any stack frame or "view source" into these bundles must
       // self-identify as the sandbox shim, not the real Firebase SDK.
       chunkNames: 'pyric-sandbox-[hash]',

package/src/serve/discovery.ts

@@ -17,16 +17,36 @@
  * first while the browser is on the other — split-brain.
  */
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 
 /** Ports probed when the pointer is absent — serve's default scan window PLUS
- *  the vite-plugin default (5174), which the plain 3473+ window would miss (so a
- *  vite-only project was never found by scan). The standalone `pyric bridge`
- *  serves `/health` (not `/__pyric/health`) and writes no pointer, so it is
- *  registered directly via `claude mcp add`, not discovered here. */
-export const SCAN_PORTS = [3473, 3474, 3475, 3476, 3477, 5174];
+ *  the standard Vite dev ports (5173-5177), which the plain 3473+ window would miss
+ *  (so a vite-only or monorepo split-directory project is reliably found by scan).
+ *  The standalone `pyric bridge` serves `/health` (not `/__pyric/health`) and
+ *  writes no pointer, so it is registered directly via `claude mcp add`, not discovered here. */
+export const SCAN_PORTS = [3473, 3474, 3475, 3476, 3477, 5173, 5174, 5175, 5176, 5177];
 export const POINTER = join('.pyric', 'serve.json');
 
+function candidatePointerPaths(startDir: string): string[] {
+  const paths: string[] = [];
+  const seen = new Set<string>();
+  const subdirs = ['', 'web', 'frontend', 'client', 'app', 'ui', 'www'];
+  let current = resolve(startDir);
+  while (true) {
+    for (const sub of subdirs) {
+      const p = sub ? join(current, sub, POINTER) : join(current, POINTER);
+      if (!seen.has(p)) {
+        seen.add(p);
+        paths.push(p);
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return paths;
+}
+
 export interface HealthLite {
   mode?: string;
   instanceId?: string;
@@ -141,46 +161,47 @@ export async function discoverServe(
   // real localhost ports, which a test environment can't guarantee are free.
   scanPorts: number[] = SCAN_PORTS,
 ): Promise<Discovered | null> {
-  const pointerPath = join(cwd, POINTER);
-  if (existsSync(pointerPath)) {
-    try {
-      const p = JSON.parse(readFileSync(pointerPath, 'utf8')) as {
-        url?: string;
-        mcpUrl?: string;
-        port?: number;
-        instanceId?: string;
-      };
-      const port = p.port ?? portOf(p.mcpUrl) ?? portOf(p.url);
-      if (port) {
-        const expectedId = typeof p.instanceId === 'string' && p.instanceId ? p.instanceId : null;
-        const hit = await healthyBase(port, expectedId);
-        if (hit) {
-          return {
-            mcpUrl: `${hit.base}/__pyric/mcp`,
-            url: canonicalServeUrl(port, p.url),
-            base: hit.base,
-            instanceId: hit.instanceId,
-            source: `pointer ${POINTER}`,
-          };
-        }
-        // The pointer named a specific identity we could NOT find on its port:
-        // a different sandbox may be squatting it (cross-family collision) or
-        // the server stopped. Do NOT scan into a possibly-wrong server — that
-        // split-brain is exactly what this identity check prevents. Fail legibly.
-        if (expectedId) {
-          log(
-            `pointer ${POINTER} names a server (instanceId ${expectedId.slice(0, 8)}…) ` +
-              `that isn't answering on port ${port} — another sandbox may be squatting the ` +
-              `port on the other loopback family, or the server stopped. Not falling back to ` +
-              `a blind port scan (it could hit the wrong sandbox). Restart your dev server, ` +
-              `and open the exact URL it prints (http://localhost:<port> by default) — every ` +
-              `page must share that ONE origin, or the browser splits into separate sandboxes.`,
-          );
-          return null;
+  for (const pointerPath of candidatePointerPaths(cwd)) {
+    if (existsSync(pointerPath)) {
+      try {
+        const p = JSON.parse(readFileSync(pointerPath, 'utf8')) as {
+          url?: string;
+          mcpUrl?: string;
+          port?: number;
+          instanceId?: string;
+        };
+        const port = p.port ?? portOf(p.mcpUrl) ?? portOf(p.url);
+        if (port) {
+          const expectedId = typeof p.instanceId === 'string' && p.instanceId ? p.instanceId : null;
+          const hit = await healthyBase(port, expectedId);
+          if (hit) {
+            return {
+              mcpUrl: `${hit.base}/__pyric/mcp`,
+              url: canonicalServeUrl(port, p.url),
+              base: hit.base,
+              instanceId: hit.instanceId,
+              source: `pointer ${pointerPath}`,
+            };
+          }
+          // The pointer named a specific identity we could NOT find on its port:
+          // a different sandbox may be squatting it (cross-family collision) or
+          // the server stopped. Do NOT scan into a possibly-wrong server — that
+          // split-brain is exactly what this identity check prevents. Fail legibly.
+          if (expectedId) {
+            log(
+              `pointer ${pointerPath} names a server (instanceId ${expectedId.slice(0, 8)}…) ` +
+                `that isn't answering on port ${port} — another sandbox may be squatting the ` +
+                `port on the other loopback family, or the server stopped. Not falling back to ` +
+                `a blind port scan (it could hit the wrong sandbox). Restart your dev server, ` +
+                `and open the exact URL it prints (http://localhost:<port> by default) — every ` +
+                `page must share that ONE origin, or the browser splits into separate sandboxes.`,
+            );
+            return null;
+          }
         }
+      } catch {
+        /* stale/corrupt pointer — fall through to next candidate */
       }
-    } catch {
-      /* stale/corrupt pointer — fall through to scan */
     }
   }
   for (const port of scanPorts) {

package/src/serve/entries/app-ai-passthrough.ts

@@ -0,0 +1,83 @@
+/** Served `firebase/app`: Pyric client registry with shadow container bridge for production AI pass-through. */
+import { bindAppRegistrySandbox } from 'pyric/app/internal';
+import { sandbox } from './app-backend.js';
+import * as pyricApp from 'pyric/app';
+import * as realApp from 'firebase/app';
+
+bindAppRegistrySandbox(sandbox);
+
+function decorateApp(
+  app: pyricApp.FirebaseApp,
+  options?: pyricApp.FirebaseOptions,
+  rawSettings?: string | pyricApp.FirebaseAppSettings,
+): pyricApp.FirebaseApp {
+  try {
+    let shadow: { container?: unknown };
+    try {
+      shadow = realApp.getApp(app.name) as { container?: unknown };
+    } catch {
+      const initOptions = (options ?? app.options) as realApp.FirebaseOptions;
+      const initSettings = rawSettings ?? app.name;
+      const isStringSettings = typeof initSettings === 'string';
+      if (isStringSettings) {
+        shadow = realApp.initializeApp(initOptions, initSettings) as { container?: unknown };
+      } else {
+        const objectSettings = initSettings as realApp.FirebaseAppSettings;
+        shadow = realApp.initializeApp(initOptions, objectSettings) as { container?: unknown };
+      }
+    }
+    const hasShadowContainer = shadow.container !== undefined && shadow.container !== null;
+    if (hasShadowContainer) {
+      Object.defineProperty(app, 'container', { value: shadow.container, configurable: true });
+    }
+  } catch {
+    // Observational/best-effort: do not break Pyric initialization if shadow initialization fails.
+  }
+  return app;
+}
+
+export function initializeApp(
+  options?: pyricApp.FirebaseOptions,
+  rawSettings?: string | pyricApp.FirebaseAppSettings,
+): pyricApp.FirebaseApp {
+  const app = pyricApp.initializeApp(options, rawSettings);
+  return decorateApp(app, options, rawSettings);
+}
+
+export function getApp(name?: string): pyricApp.FirebaseApp {
+  return decorateApp(pyricApp.getApp(name));
+}
+
+export function getApps(): pyricApp.FirebaseApp[] {
+  return pyricApp.getApps().map((app) => decorateApp(app));
+}
+
+export async function deleteApp(app: pyricApp.FirebaseApp): Promise<void> {
+  try {
+    const shadow = realApp.getApp(app.name);
+    const hasShadow = shadow !== undefined && shadow !== null;
+    if (hasShadow) {
+      await realApp.deleteApp(shadow);
+    }
+  } catch {
+    // Ignore if shadow app was not initialized or already deleted.
+  }
+  return pyricApp.deleteApp(app);
+}
+
+export {
+  FirebaseError,
+  SDK_VERSION,
+  onLog,
+  registerVersion,
+  setLogLevel,
+} from 'pyric/app';
+export type {
+  FirebaseApp,
+  FirebaseAppSettings,
+  FirebaseOptions,
+  LogCallback,
+  LogEntry,
+  LogLevel,
+  LogOptions,
+} from 'pyric/app';

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

@@ -224,6 +224,12 @@ function mintProviderUid(): string {
 function bareCredential(identity: HelperIdentity, providerId: string): UserCredential {
   const issuedAtTime = new Date().toISOString();
   const expirationTime = new Date(Date.now() + 3600_000).toISOString();
+  const claims: Record<string, unknown> = {
+    sub: identity.uid,
+    ...identity.customClaims,
+    firebase: { sign_in_provider: providerId },
+  };
+  const token = `sandbox-id-token-${identity.uid}-0:${JSON.stringify(claims)}`;
   const user: User = {
     uid: identity.uid,
     email: identity.email,
@@ -243,14 +249,10 @@ function bareCredential(identity: HelperIdentity, providerId: string): UserCrede
         providerId,
       },
     ],
-    getIdToken: async () => `pyric-serve-${identity.uid}`,
+    getIdToken: async () => token,
     getIdTokenResult: async () => ({
-      token: `pyric-serve-${identity.uid}`,
-      claims: {
-        sub: identity.uid,
-        ...identity.customClaims,
-        firebase: { sign_in_provider: providerId },
-      },
+      token,
+      claims,
       signInProvider: providerId,
       expirationTime,
       issuedAtTime,

package/src/serve/entries/auth.ts

@@ -13,6 +13,7 @@
  * in or seeds a user. Email/password + anonymous also go straight to the
  * worker. The COMPLETE surface is exported on both paths (import-time parity).
  */
+import './init.js';
 import * as ipAuth from 'pyric/auth';
 import { getAuth as pyricGetAuth, setPersistence as pyricSetPersistence } from 'pyric/auth';
 import * as wcRaw from '../worker/client.js';

package/src/serve/entries/bridge-url.ts

@@ -22,9 +22,16 @@ export function toPageOriginWsUrl(
   loc: { href: string; protocol: string; host: string },
 ): string {
   try {
-    const path = new URL(raw, loc.href).pathname;
+    const rawUrl = new URL(raw, loc.href);
+    const locUrl = new URL(loc.href);
     const scheme = loc.protocol === 'https:' ? 'wss:' : 'ws:';
-    return `${scheme}//${loc.host}${path}`;
+
+    const hasExplicitLocPort = locUrl.port.length > 0;
+    const hasExplicitRawPort = rawUrl.port.length > 0;
+    const shouldPreserveRawPort = hasExplicitLocPort && hasExplicitRawPort;
+    const hostTarget = shouldPreserveRawPort ? `${locUrl.hostname}:${rawUrl.port}` : locUrl.host;
+
+    return `${scheme}//${hostTarget}${rawUrl.pathname}`;
   } catch {
     return raw;
   }

package/src/serve/entries/database.ts

@@ -5,6 +5,7 @@
  * and the Playground. This entry gives served apps the same common modular SDK
  * surface while the in-page fallback delegates to `pyric/database`.
  */
+import './init.js';
 import * as ip from 'pyric/database';
 import { getDatabase as pyricGetDatabase } from 'pyric/database';
 import { queryIdentifier } from 'pyric/database/internal';

package/src/serve/entries/firestore.ts

@@ -13,6 +13,7 @@
  *
  * Browser-bundled by `../bundler.ts`; never imported by node-side code.
  */
+import './init.js';
 import * as ip from 'pyric/firestore';
 import { getFirestore as pyricGetFirestore } from 'pyric/firestore';
 import * as wcRaw from '../worker/client.js';

package/src/serve/entries/init.ts

@@ -53,7 +53,10 @@ const helper = workerAuth
 const resolver = helper.resolver();
 installServeAuthResolver(resolver);
 if (localAuth) authSandbox.setAuthFlowResolver(localAuth, resolver);
-mountAuthHelperDialog(helper);
-installPyricRuntimeChip({ runtime: getPyricRuntimeStatus(), document });
+
+if (typeof document !== 'undefined' && typeof window !== 'undefined') {
+  mountAuthHelperDialog(helper);
+  installPyricRuntimeChip({ runtime: getPyricRuntimeStatus(), document });
+}
 
 export {};

package/src/serve/entries/runtime.ts

@@ -553,4 +553,29 @@ if (!useWorker && typeof EventSource !== 'undefined') {
       console.error('[pyric dev] rules hot-reload failed:', err instanceof Error ? err.message : String(err));
     }
   });
+  events.addEventListener('rtdb-rules-update', (e) => {
+    try {
+      const { rules, rulesHash } = JSON.parse((e as MessageEvent).data as string) as {
+        rules: { rules: Record<string, unknown> };
+        rulesHash: string;
+      };
+      rtdbSandbox.setRules(getDatabase(sandbox), rules);
+      diagnostics.databaseRulesDeployed = true;
+      let newHash: string | null = null;
+      const isHashDefined = rulesHash !== undefined;
+      if (isHashDefined) {
+        newHash = rulesHash;
+      }
+      diagnostics.databaseRulesHash = newHash;
+      console.info(`[pyric dev] database.rules.json hot-reloaded (hash ${rulesHash})`);
+    } catch (err) {
+      runtimeStatus.reportError(err, 'runtime');
+      const isErrorInstance = err instanceof Error;
+      let errorMessage = String(err);
+      if (isErrorInstance) {
+        errorMessage = (err as Error).message;
+      }
+      console.error('[pyric dev] database rules hot-reload failed:', errorMessage);
+    }
+  });
 }

package/src/serve/entries/storage.ts

@@ -6,6 +6,7 @@
  * still lack a worker protocol fail loudly. In in-page fallback mode, the entry
  * delegates to `pyric/storage` against the page sandbox.
  */
+import './init.js';
 import * as ip from 'pyric/storage';
 import {
   getStorage as pyricGetStorage,
@@ -20,6 +21,8 @@ import {
   listAll as workerListAll,
   ref as workerRef,
   uploadBytes as workerUploadBytes,
+  uploadString as workerUploadString,
+  uploadBytesResumable as workerUploadBytesResumable,
   deleteObject as workerDeleteObject,
 } from '../worker/client.js';
 import { useWorker } from './worker-runtime.js';
@@ -85,8 +88,16 @@ function workerOrInPage<T extends (...args: any[]) => unknown>(name: string, fn:
 // ruleset; only their active Auth sessions differ. Payloads are capped at
 // 8 MiB per op.
 export const uploadBytes = (useWorker ? workerUploadBytes : ip.uploadBytes) as typeof ip.uploadBytes;
+
+let selectedUploadBytesResumable = ip.uploadBytesResumable;
+const isWorkerMode = useWorker === true;
+if (isWorkerMode) {
+  selectedUploadBytesResumable = workerUploadBytesResumable as unknown as typeof ip.uploadBytesResumable;
+}
+export const uploadBytesResumable = selectedUploadBytesResumable;
+
 export const getBytes = (useWorker ? workerGetBytes : ip.getBytes) as typeof ip.getBytes;
 export const deleteObject = (useWorker ? workerDeleteObject : ip.deleteObject) as typeof ip.deleteObject;
 
-export const uploadString = workerOrInPage('uploadString', ip.uploadString);
+export const uploadString = (useWorker ? workerUploadString : ip.uploadString) as typeof ip.uploadString;
 export const updateMetadata = workerOrInPage('updateMetadata', ip.updateMetadata);

package/src/serve/html-injection.ts

@@ -1,7 +1,32 @@
 import { SANDBOX_BUILD_MARKER } from './sandbox-marker.js';
 
 /** The import-map targets. Spec → served URL. */
-export function sdkImportMap(): Record<string, string> {
+export function sdkImportMap(options?: { aiMode?: 'sandbox' | 'production' }): Record<string, string> {
+  const explicitMode = options?.aiMode;
+  let mode: 'sandbox' | 'production' = 'sandbox';
+  const hasExplicitMode = explicitMode !== undefined;
+  if (hasExplicitMode) {
+    mode = explicitMode;
+  } else {
+    const isEnvProductionMode = process.env.PYRIC_AI_MODE === 'production';
+    const isEnvPassthroughFlag = process.env.PYRIC_AI_PASSTHROUGH === '1';
+    const isProductionEnv = isEnvProductionMode || isEnvPassthroughFlag;
+    if (isProductionEnv) {
+      mode = 'production';
+    }
+  }
+  const isProductionMode = mode === 'production';
+  if (isProductionMode) {
+    return {
+      'firebase/app': '/__pyric/sdk/app-ai-passthrough.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',
+    };
+  }
   return {
     'firebase/ai': '/__pyric/sdk/ai.js',
     'firebase/app': '/__pyric/sdk/app.js',

package/src/serve/rules.ts

@@ -16,7 +16,7 @@ import { isAbsolute, join } from 'node:path';
 import { lintFirestoreRules, resolveModulesBrowser } from 'pyric/rules/internal';
 import { parseStorageRules } from 'pyric/storage';
 import type { FirebaseJson } from '../cli/firebase-json.js';
-import { parseRtdbRulesJson } from '../rtdb/rules-json.js';
+import { parseRtdbRulesJson, stripJsonComments } from '../rtdb/rules-json.js';
 
 export interface LoadedRules {
   /** Plain-v2 source ready for the sandbox, or null when the project has no
@@ -186,7 +186,7 @@ export async function loadProjectDatabaseRules(
 
   let parsed: unknown;
   try {
-    parsed = JSON.parse(raw);
+    parsed = JSON.parse(stripJsonComments(raw));
   } catch (e) {
     throw new Error(`pyric dev: ${path} failed to parse as RTDB rules JSON: ${e instanceof Error ? e.message : String(e)}`);
   }

package/src/serve/runtime/chip-config.ts

@@ -17,14 +17,27 @@ interface RuntimeChipDocument {
   querySelector(selector: string): { getAttribute(name: string): string | null } | null;
 }
 
-/** Read only plugin-authored values; absent/unknown metadata keeps the UI off. */
+function hasBundlerRuntimeChipConfig(): boolean {
+  return typeof process !== 'undefined' && typeof process.env !== 'undefined' && typeof process.env.PYRIC_RUNTIME_CHIP === 'string';
+}
+
+/** Read plugin-authored values from DOM metadata or bundler environment variables, defaulting to collapsed UI when omitted. */
 export function readPyricRuntimeChipConfig(
   documentLike: RuntimeChipDocument,
 ): PyricRuntimeChipConfig | null {
   const meta = documentLike.querySelector(`meta[name="${PYRIC_RUNTIME_CHIP_META}"]`);
-  const value = meta?.getAttribute('content');
-  const studioEnabled = meta?.getAttribute('data-studio') !== 'off';
-  if (value === 'collapsed') return { initiallyOpen: false, studioEnabled };
-  if (value === 'expanded') return { initiallyOpen: true, studioEnabled };
-  return null;
+  const hasMetaTag = meta !== null;
+  let value = hasMetaTag ? meta.getAttribute('content') : null;
+
+  const shouldFallbackToEnv = !hasMetaTag && hasBundlerRuntimeChipConfig();
+  if (shouldFallbackToEnv) {
+    value = process.env.PYRIC_RUNTIME_CHIP as string;
+  }
+  if (value === 'off') {
+    return null;
+  }
+
+  const studioEnabled = !hasMetaTag || meta.getAttribute('data-studio') !== 'off';
+  const initiallyOpen = value === 'expanded';
+  return { initiallyOpen, studioEnabled };
 }