@pyric/cli 0.1.0-alpha.10

package/dist/serve/docs-ui/docs/messaging-compat.md

@@ -0,0 +1,285 @@
+<!-- Generated from the conformance model (registry rows + surface contracts). Do not edit by hand; run bun run compat:generate. -->
+
+# `pyric` messaging compatibility matrix
+
+<div class="compat-stat">
+<p class="compat-stat-figure">
+<span class="compat-stat-pct">100%</span>
+<span class="compat-stat-label">of the public API supported</span>
+</p>
+<div class="compat-meters">
+<span class="compat-meter-track"><span class="compat-meter-fill" style="width: 100%"></span></span>
+</div>
+<p class="compat-stat-denom">13 of 13 public API</p>
+</div>
+
+
+## Status legend
+
+<div class="compat-key">
+<span class="compat-key-item"><span class="compat-dot" data-status="ok"></span><strong>Conforming</strong> — sandbox matches prod, locked by a passing probe</span>
+</div>
+
+## `firebase/messaging` (client)
+
+<div class="compat-list">
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">getMessaging(app?): Messaging</code><span class="compat-sub"><span class="compat-behavior">Returns the FCM <code>Messaging</code> instance associated with the given (or default) <code>FirebaseApp</code>. Bound to the client component registered under the name <code>messaging</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings/JSDoc (firebase 12.13.0, <code>@firebase/messaging</code> 0.12.26); in-process mirror suite plus canonical-import SharedWorker replay <code>messaging-app-boundary.pw.ts</code>.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">getToken(messaging, options?): Promise&lt;string&gt;</code><span class="compat-sub"><span class="compat-behavior">Subscribes the instance to push and resolves with an FCM registration token; requests notification permission if not already granted and rejects if denied. Production tokens are colon-separated, URL-safe, ~142 chars, with the suffix after the colon beginning <code>APA91b</code>, and are stable across repeated <code>getToken</code> calls on the same service-worker registration (no per-call rotation).</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">oracle: <code>messaging-web-token-shape.json</code> (minted, length 142, colon-separated, suffix starts <code>APA91b</code>, URL-safe) + <code>messaging-web-token-stability.json</code> (second <code>getToken</code> on the same registration returns the same token). Replayed by the conformance suite.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">deleteToken(messaging): Promise&lt;boolean&gt;</code><span class="compat-sub"><span class="compat-behavior">Deletes the registration token and unsubscribes the instance from its push subscription; resolves truthy. After deletion no message reaches the client on either route, and a server send to the now-dead token eventually surfaces the UNREGISTERED / 404-class error on the send plane (propagation is asynchronous — the first send after delete may still be accepted while delivery has already stopped).</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">oracle: <code>messaging-web-deletetoken-unregistered.json</code> (deleteToken resolved truthy; no delivery to client; send plane eventually UNREGISTERED). Replayed by the conformance suite.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">onMessage(messaging, nextOrObserver): Unsubscribe</code><span class="compat-sub"><span class="compat-behavior">Dispatched with the push payload when a message arrives while a window client is visible; the returned function stops listening. Routing keys on page VISIBILITY, not focus: a <code>visibilityState: "visible"</code> page receives <code>onMessage</code> even when unfocused, and when no window client is visible the message routes to the service-worker <code>onBackgroundMessage</code> instead.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">oracle: <code>messaging-web-onmessage-foreground.json</code> (focused page → onMessage) + <code>messaging-web-visibility-routing.json</code> (visible → onMessage, no visible client → onBackgroundMessage). Replayed by the conformance suite.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">isSupported(): Promise&lt;boolean&gt;</code><span class="compat-sub"><span class="compat-behavior">Resolves whether every API required by FCM exists in the current browser window context (bound to <code>isWindowSupported</code>).</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings/JSDoc (<code>@firebase/messaging</code> 0.12.26); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface Messaging { app }</code><span class="compat-sub"><span class="compat-behavior">Public interface of the FCM client SDK; exposes the bound <code>FirebaseApp</code> as <code>app</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (<code>@firebase/messaging</code> 0.12.26 <code>public-types</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface GetTokenOptions { vapidKey?; serviceWorkerRegistration? }</code><span class="compat-sub"><span class="compat-behavior">Options for <code>getToken</code>: an optional <code>vapidKey</code> (Web Push certificate public key) and an optional <code>serviceWorkerRegistration</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (<code>@firebase/messaging</code> 0.12.26 <code>public-types</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface MessagePayload { notification?; data?; fcmOptions?; from; collapseKey; messageId }</code><span class="compat-sub"><span class="compat-behavior">Received message envelope delivered to <code>onMessage</code> / <code>onBackgroundMessage</code>. Production deliveries carry top-level keys <code>data</code>, <code>from</code>, <code>messageId</code>, and <code>notification</code>; <code>from</code> equals the project messaging sender id and <code>messageId</code> is present. (<code>from</code>, <code>collapseKey</code>, <code>messageId</code> are typed as required.)</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">oracle: <code>messaging-web-onmessage-foreground.json</code> + <code>messaging-web-onbackgroundmessage.json</code> (top-level keys data/from/messageId/notification; from = sender id; messageId present). Replayed by the conformance suite.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface NotificationPayload { title?; body?; image?; icon? }</code><span class="compat-sub"><span class="compat-behavior">Display-notification block inside a <code>MessagePayload</code>. Production foreground deliveries carry a <code>notification</code> object whose keys include <code>title</code> and <code>body</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">oracle: <code>messaging-web-onmessage-foreground.json</code> (notificationKeys body, title). Replayed by the conformance suite.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface FcmOptions { link?; analyticsLabel? }</code><span class="compat-sub"><span class="compat-behavior">WebpushFcmOptions-style options carried on a client <code>MessagePayload</code> (<code>link</code>, <code>analyticsLabel</code>).</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (<code>@firebase/messaging</code> 0.12.26 <code>public-types</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">NextFn, Observer, Unsubscribe (re-exported from @firebase/util)</code><span class="compat-sub"><span class="compat-behavior">The callback, observer, and teardown types consumed by <code>onMessage</code> / <code>onBackgroundMessage</code> are re-exported from <code>@firebase/util</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (<code>@firebase/messaging</code> 0.12.26 re-exports); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">const enum ErrorCode (client)</code><span class="compat-sub"><span class="compat-behavior">Client failures surface as thrown <code>FirebaseError</code>s carrying one of the 18 documented <code>ErrorCode</code> values (<code>missing-app-config-values</code>, <code>only-available-in-window</code>, <code>only-available-in-sw</code>, <code>permission-default</code>, <code>permission-blocked</code>, <code>unsupported-browser</code>, <code>indexed-db-unsupported</code>, <code>failed-service-worker-registration</code>, <code>token-subscribe-failed</code>, <code>token-subscribe-no-token</code>, <code>token-unsubscribe-failed</code>, <code>token-update-failed</code>, <code>token-update-no-token</code>, <code>invalid-bg-handler</code>, <code>use-sw-after-get-token</code>, <code>invalid-sw-registration</code>, <code>use-vapid-key-after-get-token</code>, <code>invalid-vapid-key</code>). The enum itself is <code>@internal</code>, not a public export.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (<code>@firebase/messaging</code> 0.12.26 <code>src/util/errors</code>); no client-error observation among the committed set.</div></div>
+</details>
+</div>
+
+## `firebase/messaging/sw` (service worker)
+
+<div class="compat-list">
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">getMessaging(app?): Messaging (sw)</code><span class="compat-sub"><span class="compat-behavior">Returns the FCM instance within a service-worker context (bound to <code>getMessagingInSw</code>); registers under the component name <code>messaging-sw</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (<code>@firebase/messaging</code> 0.12.26 <code>sw/index-public</code>) plus real module-ServiceWorker served-entry replay <code>messaging-app-boundary.pw.ts</code>.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">onBackgroundMessage(messaging, nextOrObserver): Unsubscribe</code><span class="compat-sub"><span class="compat-behavior">Called when a message arrives while the app has no visible window client. Production routes background deliveries here rather than to <code>onMessage</code>; the delivered payload carries <code>data</code> / <code>from</code> / <code>messageId</code> and, for notification messages, a <code>notification</code> block. A DATA-ONLY message still fires <code>onBackgroundMessage</code> with no <code>notification</code> key, and a registered handler suppresses the SDK auto-display.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">oracle: <code>messaging-web-onbackgroundmessage.json</code> (no visible client → onBackgroundMessage) + <code>messaging-web-visibility-routing.json</code> + <code>messaging-web-data-only-background.json</code> (data-only fires, no notification key). Replayed by the conformance suite and by a real module Service Worker connected to the canonical SharedWorker broker in <code>messaging-app-boundary.pw.ts</code>.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging, enable): void</code><span class="compat-sub"><span class="compat-behavior">Enables or disables delivery-metrics export to BigQuery at runtime; default off.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (<code>@firebase/messaging</code> 0.12.26 <code>sw/index-public</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">isSupported(): Promise&lt;boolean&gt; (sw)</code><span class="compat-sub"><span class="compat-behavior">Resolves whether every API required by FCM exists within the service-worker context (bound to <code>isSwSupported</code>).</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (<code>@firebase/messaging</code> 0.12.26 <code>sw/index-public</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">firebase/messaging/sw module boundary + shared type parity</code><span class="compat-sub"><span class="compat-behavior">The sw entry exports <code>onBackgroundMessage</code>, <code>getMessaging</code>, <code>experimentalSetDeliveryMetricsExportedToBigQueryEnabled</code>, and <code>isSupported</code>, but NOT <code>getToken</code> / <code>deleteToken</code> / <code>onMessage</code>; the client entry exports the latter but NOT <code>onBackgroundMessage</code> / the metrics toggle. The two modules register under different component names (<code>messaging</code> vs <code>messaging-sw</code>) and re-export identical <code>Messaging</code> / <code>GetTokenOptions</code> / <code>MessagePayload</code> / <code>NotificationPayload</code> / <code>FcmOptions</code> type declarations.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (<code>@firebase/messaging</code> 0.12.26 <code>index.d.ts</code> / <code>index.sw.d.ts</code>) plus Window and real module-ServiceWorker boundary replay <code>messaging-app-boundary.pw.ts</code>.</div></div>
+</details>
+</div>
+
+## `firebase-admin/messaging` — entry + `Messaging` class
+
+<div class="compat-list">
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">getMessaging(app?): Messaging</code><span class="compat-sub"><span class="compat-behavior">Returns the <code>Messaging</code> service for the default or given admin <code>App</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings/JSDoc (firebase-admin 13.10.0 <code>lib/messaging/index</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">messaging(app?): messaging.Messaging</code><span class="compat-sub"><span class="compat-behavior">Namespaced / legacy accessor equivalent of <code>getMessaging</code>, exposed by the compat entry alongside the <code>namespace messaging</code> type aliases.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-namespace</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">Messaging.get app(): App</code><span class="compat-sub"><span class="compat-behavior">The admin <code>App</code> this <code>Messaging</code> instance is bound to.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">Messaging.send(message, dryRun?): Promise&lt;string&gt;</code><span class="compat-sub"><span class="compat-behavior">Sends one message via FCM v1 and resolves with the resource name <code>projects/&lt;projectId&gt;/messages/&lt;numeric id&gt;</code>. <code>dryRun=true</code> returns the SAME shape (fake id), so callers cannot distinguish validation from acceptance by shape. Topic, condition, token, notification-only, data-only, and webpush-config sends are all accepted. Malformed sends fail server-side validation with HTTP 4xx <code>google.rpc</code> error envelopes carrying both a <code>google.rpc.BadRequest</code> (fieldViolations) and a <code>google.firebase.fcm.v1.FcmError</code> (errorCode); detail ordering is not contractual. The documented data-payload cap is 4096 bytes.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">oracle: 10 send-plane observations — accept paths <code>messaging-send-topic-accepted</code>, <code>messaging-send-condition-accepted</code>, <code>messaging-send-notification-only-vs-data-only-accepted</code>, <code>messaging-send-webpush-config-accepted</code>; error envelopes <code>messaging-send-no-target-error-envelope</code>, <code>messaging-send-invalid-token-error-envelope</code>, <code>messaging-send-invalid-condition-error-envelope</code>, <code>messaging-send-invalid-topic-name-error-envelope</code>, <code>messaging-send-oversized-payload-error-envelope</code>, <code>messaging-send-webpush-invalid-ttl-error-envelope</code>. Replayed by the conformance suite.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">Messaging.sendEach(messages, dryRun?): Promise&lt;BatchResponse&gt;</code><span class="compat-sub"><span class="compat-behavior">Sends an array of up to 500 messages, one RPC per message; resolves a <code>BatchResponse</code> whose <code>responses</code> are ordered to match the input. Total failure is signalled by a throw or an all-failure <code>BatchResponse</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings/JSDoc (firebase-admin 13.10.0 <code>messaging</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">Messaging.sendEachForMulticast(message, dryRun?): Promise&lt;BatchResponse&gt;</code><span class="compat-sub"><span class="compat-behavior">Fans a <code>MulticastMessage</code> (up to 500 tokens) out through <code>sendEach</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings/JSDoc (firebase-admin 13.10.0 <code>messaging</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">Messaging.subscribeToTopic(tokenOrTokens, topic): Promise&lt;MessagingTopicManagementResponse&gt;</code><span class="compat-sub"><span class="compat-behavior">Subscribes one or many registration tokens to a topic; resolves a <code>MessagingTopicManagementResponse</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings/JSDoc (firebase-admin 13.10.0 <code>messaging</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">Messaging.unsubscribeFromTopic(tokenOrTokens, topic): Promise&lt;MessagingTopicManagementResponse&gt;</code><span class="compat-sub"><span class="compat-behavior">Unsubscribes one or many registration tokens from a topic; resolves a <code>MessagingTopicManagementResponse</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings/JSDoc (firebase-admin 13.10.0 <code>messaging</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">Messaging.enableLegacyHttpTransport(): void</code><span class="compat-sub"><span class="compat-behavior">Forces HTTP/1.1 transport for <code>sendEach</code> / <code>sendEachForMulticast</code>; deprecated.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings/JSDoc (firebase-admin 13.10.0 <code>messaging</code>, <code>@deprecated</code>); no observation yet.</div></div>
+</details>
+</div>
+
+## `Message` union + targets
+
+<div class="compat-list">
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">type Message = TokenMessage | TopicMessage | ConditionMessage</code><span class="compat-sub"><span class="compat-behavior">A send payload carrying exactly one of token, topic, or condition.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface BaseMessage { data?; notification?; android?; webpush?; apns?; fcmOptions? }</code><span class="compat-sub"><span class="compat-behavior">Common message fields shared by every target variant. Production accepts a message carrying ONLY a <code>notification</code> block and, separately, ONLY a <code>data</code> block — neither is individually required.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">oracle: <code>messaging-send-notification-only-vs-data-only-accepted.json</code> (both accepted). Replayed by the conformance suite.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface TokenMessage extends BaseMessage { token: string }</code><span class="compat-sub"><span class="compat-behavior">A device-token target. A syntactically invalid token is rejected with HTTP 400 INVALID_ARGUMENT whose fieldViolations name <code>message.token</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">oracle: <code>messaging-send-invalid-token-error-envelope.json</code> (fieldViolations names message.token). Replayed by the conformance suite.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface TopicMessage extends BaseMessage { topic: string }</code><span class="compat-sub"><span class="compat-behavior">A topic target. A well-formed topic send is accepted and returns the standard resource name (no subscribers required); a topic name containing characters outside the documented <code>[a-zA-Z0-9-_.~%]</code> set is rejected with an INVALID_ARGUMENT error envelope.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">oracle: <code>messaging-send-topic-accepted.json</code> (accepted) + <code>messaging-send-invalid-topic-name-error-envelope.json</code> (bad name rejected). Replayed by the conformance suite.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface ConditionMessage extends BaseMessage { condition: string }</code><span class="compat-sub"><span class="compat-behavior">A condition target. A well-formed condition of the form <code>"'a' in topics &amp;&amp; 'b' in topics"</code> is accepted with the standard resource-name shape (no subscribers required); a malformed condition (dangling operator) is rejected with an error envelope.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">oracle: <code>messaging-send-condition-accepted.json</code> (accepted) + <code>messaging-send-invalid-condition-error-envelope.json</code> (malformed rejected). Replayed by the conformance suite.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface MulticastMessage extends BaseMessage { tokens: string[] }</code><span class="compat-sub"><span class="compat-behavior">A multicast target of up to 500 tokens, fanned out by <code>sendEachForMulticast</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+</div>
+
+## Payload / config option shapes
+
+<div class="compat-list">
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface Notification { title?; body?; imageUrl? }</code><span class="compat-sub"><span class="compat-behavior">Top-level, platform-independent notification block. Production accepts a notification-only message (no data block).</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">oracle: <code>messaging-send-notification-only-vs-data-only-accepted.json</code>. Replayed by the conformance suite.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface FcmOptions { analyticsLabel? }</code><span class="compat-sub"><span class="compat-behavior">Platform-independent FCM options (<code>analyticsLabel</code>).</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface WebpushConfig { headers?; data?; notification?; fcmOptions? }</code><span class="compat-sub"><span class="compat-behavior">Webpush overrides. Production accepts a webpush config carrying <code>headers.TTL</code> and <code>fcmOptions.link</code>; a non-numeric <code>headers.TTL</code> is rejected with an error envelope.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">oracle: <code>messaging-send-webpush-config-accepted.json</code> (accepted) + <code>messaging-send-webpush-invalid-ttl-error-envelope.json</code> (bad TTL rejected). Replayed by the conformance suite.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface WebpushFcmOptions { link? }</code><span class="compat-sub"><span class="compat-behavior">Webpush FCM options (<code>link</code>, HTTPS required). Production accepts <code>fcmOptions.link</code> on a webpush send.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">oracle: <code>messaging-send-webpush-config-accepted.json</code> (link accepted). Replayed by the conformance suite.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface WebpushNotification { title?; actions?; badge?; body?; dir?; icon?; image?; renotify?; requireInteraction?; silent?; tag?; vibrate?; [key] }</code><span class="compat-sub"><span class="compat-behavior">Web Notification API-shaped options, including an open-ended index signature.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface ApnsConfig { liveActivityToken?; headers?; payload?; fcmOptions? }</code><span class="compat-sub"><span class="compat-behavior">APNs overrides.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface ApnsPayload { aps; [customData] }</code><span class="compat-sub"><span class="compat-behavior">APNs payload wrapper carrying the required <code>aps</code> dictionary plus arbitrary custom keys.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface Aps { alert?; badge?; sound?; contentAvailable?; mutableContent?; category?; threadId?; [customData] }</code><span class="compat-sub"><span class="compat-behavior">APNs <code>aps</code> dictionary; <code>alert</code> is a string or an <code>ApsAlert</code>, <code>sound</code> a string or a <code>CriticalSound</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface ApsAlert { title?; subtitle?; body?; locKey?; locArgs?; ...; launchImage? }</code><span class="compat-sub"><span class="compat-behavior">APNs alert object with title/subtitle/body and localization keys.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface CriticalSound { critical?; name; volume? }</code><span class="compat-sub"><span class="compat-behavior">APNs critical sound — <code>name</code> required; <code>volume</code> in the range 0.0–1.0.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface ApnsFcmOptions { analyticsLabel?; imageUrl? }</code><span class="compat-sub"><span class="compat-behavior">APNs FCM options (<code>analyticsLabel</code>, <code>imageUrl</code>).</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface AndroidConfig { collapseKey?; priority?; ttl?; restrictedPackageName?; data?; notification?; fcmOptions?; ... }</code><span class="compat-sub"><span class="compat-behavior">Android overrides; <code>ttl</code> is in milliseconds and <code>priority</code> is <code>high</code> | <code>normal</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface AndroidNotification { title?; body?; icon?; color?; sound?; tag?; imageUrl?; channelId?; priority?; visibility?; lightSettings?; ... }</code><span class="compat-sub"><span class="compat-behavior">Android notification options, including localization keys, LED light settings, and delivery-proxy controls.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface LightSettings { color; lightOnDurationMillis; lightOffDurationMillis }</code><span class="compat-sub"><span class="compat-behavior">Android LED light settings — all three fields required.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface AndroidFcmOptions { analyticsLabel? }</code><span class="compat-sub"><span class="compat-behavior">Android FCM options (<code>analyticsLabel</code>).</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+</div>
+
+## Legacy payload shapes
+
+<div class="compat-list">
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface DataMessagePayload { [key]: string }</code><span class="compat-sub"><span class="compat-behavior">Legacy data payload — up to 4KB; the keys <code>from</code> and <code>google.*</code> are reserved.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface NotificationMessagePayload { tag?; body?; icon?; badge?; color?; sound?; title?; ...; [key] }</code><span class="compat-sub"><span class="compat-behavior">Legacy notification payload with localization keys, a <code>clickAction</code>, and arbitrary string keys.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface MessagingPayload { data?; notification? }</code><span class="compat-sub"><span class="compat-behavior">Legacy combined payload — one or both of <code>data</code> / <code>notification</code> required.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface MessagingOptions { dryRun?; priority?; timeToLive?; collapseKey?; mutableContent?; contentAvailable?; restrictedPackageName?; [key] }</code><span class="compat-sub"><span class="compat-behavior">Legacy send options; documented defaults are dryRun false, ttl 2419200s (4 weeks), priority high for notifications / normal for data.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+</div>
+
+## Response shapes
+
+<div class="compat-list">
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface MessagingTopicManagementResponse { failureCount; successCount; errors }</code><span class="compat-sub"><span class="compat-behavior">Topic subscribe / unsubscribe result carrying per-index errors as <code>FirebaseArrayIndexError[]</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface BatchResponse { responses; successCount; failureCount }</code><span class="compat-sub"><span class="compat-behavior">Batch send result; <code>responses</code> is a <code>SendResponse[]</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">interface SendResponse { success; messageId?; error? }</code><span class="compat-sub"><span class="compat-behavior">Per-message batch entry — on success <code>messageId</code> is set, on failure <code>error</code> is set.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>messaging-api</code>); no observation yet.</div></div>
+</details>
+</div>
+
+## Errors
+
+<div class="compat-list">
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">class FirebaseMessagingError extends PrefixedFirebaseError</code><span class="compat-sub"><span class="compat-behavior">The exported admin messaging error type.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">Upstream typings (firebase-admin 13.10.0 <code>lib/messaging/index</code>); no observation yet.</div></div>
+</details>
+<details class="compat-row" data-status="ok">
+<summary class="compat-line"><span class="compat-dot" data-status="ok" role="img" aria-label="Conforming" title="Conforming"></span><span class="compat-main"><code class="compat-api">class MessagingClientErrorCode</code><span class="compat-sub"><span class="compat-behavior">Exported static <code>{ code, message }</code> members (<code>INVALID_ARGUMENT</code>, <code>INVALID_RECIPIENT</code>, <code>INVALID_PAYLOAD</code>, … <code>UNKNOWN_ERROR</code>). The wire-level <code>INVALID_ARGUMENT</code> FcmError returned by malformed sends maps to <code>MessagingClientErrorCode.INVALID_ARGUMENT</code>.</span></span></span></summary>
+<div class="compat-evidence"><div class="compat-probe">oracle: <code>messaging-send-no-target-error-envelope.json</code> + <code>messaging-send-invalid-token-error-envelope.json</code> (both carry the INVALID_ARGUMENT FcmError). Replayed by the conformance suite.</div></div>
+</details>
+</div>

package/dist/serve/docs-ui/docs/observe/see-whats-happening/index.html

@@ -0,0 +1,73 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Watch every read, write, and denial live · Pyric Studio</title><meta name="description" content="See every operation your backend performs, with its rules verdict, without writing a log line."><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.DPUwShm2.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Get started</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/get-started/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/get-started/how-the-swap-works/"> How the swap works </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Build</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/build/authentication/"> Authentication </a> </li><li> <a href="/__pyric/ui/docs/build/cloud-firestore/"> Cloud Firestore </a> </li><li> <a href="/__pyric/ui/docs/build/realtime-database/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/build/cloud-storage/"> Cloud Storage </a> </li><li> <a href="/__pyric/ui/docs/build/cloud-messaging/"> Cloud Messaging </a> </li><li> <a href="/__pyric/ui/docs/build/ai-logic/"> AI Logic </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Secure &amp; debug</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/secure/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/secure/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/secure/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/secure/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/secure/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/secure/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/secure/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/secure/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" open> <summary>Observe &amp; shape</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/observe/see-whats-happening/" aria-current="page"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/observe/shape-your-data/"> Seed, snapshot, replay </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship &amp; test</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/ship/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Work with an agent</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/agent/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/agent/work-with-an-agent/"> Use the MCP tools </a> </li><li> <a href="/__pyric/ui/docs/agent/watch-and-review/"> Watch in Pyric Studio </a> </li> </ul> </div> </div> </details><a class="docs-nav-toplink" href="/__pyric/ui/docs/trust/versioning-and-compatibility/"> Trust </a><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/conformance-scores/"> Public API coverage </a> </li><li> <a href="/__pyric/ui/docs/trust/how-we-know-it-matches-firebase/"> How we know it matches Firebase </a> </li><li> <a href="/__pyric/ui/docs/app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/functions-rtdb-compat/"> Functions · RTDB </a> </li><li> <a href="/__pyric/ui/docs/rules-compat/"> Rules </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group"> <summary>Reference</summary> <div class="docs-nav-group-body docs-nav-group-body--reference"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading">pyric</h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-app-reference-api/"> pyric/app </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-reference-api/"> pyric/firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-reference-api/"> pyric/auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-reference-api/"> pyric/ai </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-scripting-reference-api/"> pyric/ai/scripting </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-reference-api/"> pyric/database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-reference-api/"> pyric/storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-reference-api/"> pyric/messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-sw-reference-api/"> pyric/messaging/sw </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-api/"> pyric/rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-values-reference-api/"> pyric/firestore-values </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-reference-api/"> pyric/sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-firestore-reference-api/"> pyric/sandbox/firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-database-reference-api/"> pyric/sandbox/database </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading">pyric-admin</h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-admin-app-reference-api/"> pyric-admin/app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-reference-api/"> pyric-admin/firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth-reference-api/"> pyric-admin/auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database-reference-api/"> pyric-admin/database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage-reference-api/"> pyric-admin/storage </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading">create-pyric</h2> <ul> <li> <a href="/__pyric/ui/docs/create-pyric-reference-api/"> create-pyric </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading">@pyric/cli</h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-credentials-node-reference-api/"> @pyric/cli/credentials/node </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-verify-reference-api/"> @pyric/cli/verify </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-conformance-reference-api/"> @pyric/cli/conformance </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-conformance-browser-reference-api/"> @pyric/cli/conformance/browser </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-assurance-reference-api/"> @pyric/cli/assurance </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-assurance-browser-reference-api/"> @pyric/cli/assurance/browser </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-bridge-reference-api/"> @pyric/cli/bridge </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-bridge-client-reference-api/"> @pyric/cli/bridge/client </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-discover-reference-api/"> @pyric/cli/discover </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-vite-reference-api/"> @pyric/cli/vite </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-serve-worker-reference-api/"> @pyric/cli/serve/worker </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-remote-reference-api/"> @pyric/cli/remote </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-register-reference-api/"> @pyric/cli/register </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading">@pyric/ui</h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-ui-auth-reference-api/"> @pyric/ui/auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-auth-hooks-reference-api/"> @pyric/ui/auth/hooks </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-primitives-reference-api/"> @pyric/ui/primitives </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-firestore-reference-api/"> @pyric/ui/firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-firestore-hooks-reference-api/"> @pyric/ui/firestore/hooks </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-rtdb-reference-api/"> @pyric/ui/rtdb </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-storage-reference-api/"> @pyric/ui/storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-storage-hooks-reference-api/"> @pyric/ui/storage/hooks </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-traffic-reference-api/"> @pyric/ui/traffic </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-traffic-hooks-reference-api/"> @pyric/ui/traffic/hooks </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-events-reference-api/"> @pyric/ui/events </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-events-hooks-reference-api/"> @pyric/ui/events/hooks </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-agents-reference-api/"> @pyric/ui/agents </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-rules-reference-api/"> @pyric/ui/rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-rules-hooks-reference-api/"> @pyric/ui/rules/hooks </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-get-started"> <summary>Get started</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/get-started/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/get-started/how-the-swap-works/"> How the swap works </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-build"> <summary>Build</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/build/authentication/"> Authentication </a> </li><li> <a href="/__pyric/ui/docs/build/cloud-firestore/"> Cloud Firestore </a> </li><li> <a href="/__pyric/ui/docs/build/realtime-database/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/build/cloud-storage/"> Cloud Storage </a> </li><li> <a href="/__pyric/ui/docs/build/cloud-messaging/"> Cloud Messaging </a> </li><li> <a href="/__pyric/ui/docs/build/ai-logic/"> AI Logic </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-secure-debug"> <summary>Secure &amp; debug</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/secure/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/secure/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/secure/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/secure/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/secure/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/secure/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/secure/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/secure/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-observe-shape" open> <summary>Observe &amp; shape</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/observe/see-whats-happening/" aria-current="page"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/observe/shape-your-data/"> Seed, snapshot, replay </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-test"> <summary>Ship &amp; test</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/ship/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-work-with-an-agent"> <summary>Work with an agent</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/agent/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/agent/work-with-an-agent/"> Use the MCP tools </a> </li><li> <a href="/__pyric/ui/docs/agent/watch-and-review/"> Watch in Pyric Studio </a> </li> </ul> </div> </div> </details><a class="docs-nav-toplink" href="/__pyric/ui/docs/trust/versioning-and-compatibility/" id="nav-group-trust"> Trust </a><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/conformance-scores/"> Public API coverage </a> </li><li> <a href="/__pyric/ui/docs/trust/how-we-know-it-matches-firebase/"> How we know it matches Firebase </a> </li><li> <a href="/__pyric/ui/docs/app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/functions-rtdb-compat/"> Functions · RTDB </a> </li><li> <a href="/__pyric/ui/docs/rules-compat/"> Rules </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference"> <summary>Reference</summary> <div class="docs-nav-group-body docs-nav-group-body--reference"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading">pyric</h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-app-reference-api/"> pyric/app </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-reference-api/"> pyric/firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-reference-api/"> pyric/auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-reference-api/"> pyric/ai </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-scripting-reference-api/"> pyric/ai/scripting </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-reference-api/"> pyric/database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-reference-api/"> pyric/storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-reference-api/"> pyric/messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-sw-reference-api/"> pyric/messaging/sw </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-reference-api/"> pyric/rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-values-reference-api/"> pyric/firestore-values </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-reference-api/"> pyric/sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-firestore-reference-api/"> pyric/sandbox/firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox-database-reference-api/"> pyric/sandbox/database </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading">pyric-admin</h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-admin-app-reference-api/"> pyric-admin/app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore-reference-api/"> pyric-admin/firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth-reference-api/"> pyric-admin/auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database-reference-api/"> pyric-admin/database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage-reference-api/"> pyric-admin/storage </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading">create-pyric</h2> <ul> <li> <a href="/__pyric/ui/docs/create-pyric-reference-api/"> create-pyric </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading">@pyric/cli</h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-credentials-node-reference-api/"> @pyric/cli/credentials/node </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-verify-reference-api/"> @pyric/cli/verify </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-conformance-reference-api/"> @pyric/cli/conformance </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-conformance-browser-reference-api/"> @pyric/cli/conformance/browser </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-assurance-reference-api/"> @pyric/cli/assurance </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-assurance-browser-reference-api/"> @pyric/cli/assurance/browser </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-bridge-reference-api/"> @pyric/cli/bridge </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-bridge-client-reference-api/"> @pyric/cli/bridge/client </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-discover-reference-api/"> @pyric/cli/discover </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-vite-reference-api/"> @pyric/cli/vite </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-serve-worker-reference-api/"> @pyric/cli/serve/worker </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-remote-reference-api/"> @pyric/cli/remote </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-register-reference-api/"> @pyric/cli/register </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading">@pyric/ui</h2> <ul> <li> <a href="/__pyric/ui/docs/pyric-ui-auth-reference-api/"> @pyric/ui/auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-auth-hooks-reference-api/"> @pyric/ui/auth/hooks </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-primitives-reference-api/"> @pyric/ui/primitives </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-firestore-reference-api/"> @pyric/ui/firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-firestore-hooks-reference-api/"> @pyric/ui/firestore/hooks </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-rtdb-reference-api/"> @pyric/ui/rtdb </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-storage-reference-api/"> @pyric/ui/storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-storage-hooks-reference-api/"> @pyric/ui/storage/hooks </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-traffic-reference-api/"> @pyric/ui/traffic </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-traffic-hooks-reference-api/"> @pyric/ui/traffic/hooks </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-events-reference-api/"> @pyric/ui/events </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-events-hooks-reference-api/"> @pyric/ui/events/hooks </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-agents-reference-api/"> @pyric/ui/agents </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-rules-reference-api/"> @pyric/ui/rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-ui-rules-hooks-reference-api/"> @pyric/ui/rules/hooks </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/observe/see-whats-happening/">Observe &amp; shape</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Traffic &amp; rule verdicts</span> </li> </ol> </nav>  <article class="prose">  <h1 id="watch-every-read-write-and-denial-live">Watch every read, write, and denial live</h1>
+<p>Every operation your app performs produces a typed event: the request with its rules verdict, the committed write, the snapshot a listener delivered. You don’t instrument anything. The stream is already there, and you can watch it two ways: in Studio, or with one subscription in code.</p>
+<h2 id="open-the-traffic-view">Open the Traffic view</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> dev</span><span style="color:#D19A66"> --ui</span></span></code></pre>
+<p>Studio mounts at <code>/__pyric/ui/</code> on your dev server. The Traffic tab shows the stream live: each request, who made it, the allow or deny verdict, and how long the rules evaluation took. Sign in, write a document, break a rule on purpose. Each one appears as it happens, in the same backend your open tabs are using.</p>
+<h2 id="subscribe-to-the-event-stream">Subscribe to the event stream</h2>
+<p>One subscription covers everything observable:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">initializeSandbox</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> sandbox</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> initializeSandbox</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> unsubscribe</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">onEvent</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">event</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E5C07B">  console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">kind</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span></code></pre>
+<p>The kinds at a glance:</p>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th><code>event.kind</code></th><th>What it tells you</th></tr></thead><tbody><tr><td><code>request</code></td><td>An operation the rules engine evaluated, with <code>result: 'allow' | 'deny'</code>, the identity, and <code>evalMs</code></td></tr><tr><td><code>write</code></td><td>A committed write, with the document’s prior and next state</td></tr><tr><td><code>snapshot_delivery</code></td><td>A listener delivered results to your callback, with added, modified, and removed counts</td></tr><tr><td><code>snapshot_suppressed</code></td><td>A listener woke up but had nothing new to deliver</td></tr><tr><td><code>listener_attach</code> / <code>listener_detach</code> / <code>listener_errored</code></td><td>Listener lifecycle, including denials that silently terminate a stream</td></tr><tr><td><code>session_boundary</code></td><td>A <code>reset()</code> or <code>dispose()</code> happened, so you can segment a persisted stream</td></tr></tbody></table></div>
+<p>Denials are a one-line filter over the same stream:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">onEvent</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">event</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  if</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">kind</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'request'</span><span style="color:#56B6C2"> &#x26;&#x26;</span><span style="color:#E5C07B"> event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">result</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'deny'</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#E5C07B">    console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`</span><span style="color:#C678DD">${</span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">method</span><span style="color:#C678DD">}</span><span style="color:#C678DD"> ${</span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">path</span><span style="color:#C678DD">}</span><span style="color:#98C379"> denied for </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">auth</span><span style="color:#ABB2BF">?.</span><span style="color:#E06C75">uid</span><span style="color:#56B6C2"> ??</span><span style="color:#98C379"> 'anonymous'</span><span style="color:#C678DD">}</span><span style="color:#98C379">`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">  }</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span></code></pre>
+<p>The subscription survives <code>sandbox.reset()</code>. A <code>session_boundary</code> event fires before each rollover, so a subscriber attached once keeps working across every test.</p>
+<h2 id="when-a-denial-needs-explaining">When a denial needs explaining</h2>
+<p>A <code>deny</code> event is not a bare <code>permission-denied</code> string. It carries the method and path, the identity the rules saw, the reasons, and the request data that was evaluated. That is enough to answer “which rule said no, and what did it see” without adding a single log line. <a href="../../secure/read-a-denial/">Read a denial and understand it</a> walks through one.</p>
+<h2 id="build-a-traffic-monitor">Build a traffic monitor</h2>
+<p>Studio’s Traffic view is a consumer of <code>onEvent</code>, and you can build your own in about seventy lines. Subscribe, format each kind, and you get a terminal log like this:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="plaintext"><code><span class="line"><span>[#3] request    allow set    notes/n1  by alice  1.4ms</span></span>
+<span class="line"><span>[#4] write      set    notes/n1  by alice  (was: null)</span></span>
+<span class="line"><span>[#5] snapshot_delivery query notes (+1 ~0 -0) size=1 by alice  triggered by set notes/n1</span></span>
+<span class="line"><span>[#7] request    deny   get    notes/n1  by bob    0.2ms  Rule #0 (read,write) deny</span></span></code></pre>
+<p>Two things to know before you ship one:</p>
+<ul>
+<li>Listener re-evaluations dominate the raw stream. Default your view to user-origin requests, deliveries, lifecycle, and denials, and put <code>origin: 'listener'</code> traffic behind a toggle.</li>
+<li>Your callback runs synchronously with the operation that produced it, so push heavy work off the hot path with <code>queueMicrotask</code> or a worker.</li>
+</ul>
+<h2 id="inspect-the-backend-through-an-agent">Inspect the backend through an agent</h2>
+<p>An agent doesn’t scroll a panel. It calls <code>sandbox_inspect</code> and gets the current rules, a lint summary, a document census, and the recent requests and denials in one response. That one call replaced a debugging session that once took fifty-one tool calls. See <a href="../../agent/set-up-your-agent/">Set up your agent</a>.</p>
+<h2 id="where-to-go-next">Where to go next</h2>
+<p>Chase a specific denial in <a href="../../secure/read-a-denial/">Read a denial and understand it</a>, or start treating the state you’re watching as source in <a href="../shape-your-data/">Shape your data</a>.</p>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#open-the-traffic-view">Open the Traffic view</a> </li><li data-depth="2"> <a href="#subscribe-to-the-event-stream">Subscribe to the event stream</a> </li><li data-depth="2"> <a href="#when-a-denial-needs-explaining">When a denial needs explaining</a> </li><li data-depth="2"> <a href="#build-a-traffic-monitor">Build a traffic monitor</a> </li><li data-depth="2"> <a href="#inspect-the-backend-through-an-agent">Inspect the backend through an agent</a> </li><li data-depth="2"> <a href="#where-to-go-next">Where to go next</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>