npm - @pyric/cli - Versions diffs - 0.1.0-alpha.9 - Mend

@pyric/cli 0.1.0-alpha.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1169) hide show

package/dist/serve/docs-ui/docs/pyric-admin-firestore-reference-api.md ADDED Viewed

@@ -0,0 +1,30 @@
+<!-- Generated from published package declarations via TypeDoc. Do not edit by hand; run bun run docs:api:generate. -->
+## Functions
+<a id="getfirestore"></a>
+### getFirestore()
+```ts
+function getFirestore(target?: any): SandboxFirestore;
+```
+Return the admin Firestore handle.
+  - `getFirestore(ctx)` — the original context form (rules-applied for the
+    ctx's captured identity). Unchanged; idempotent per `SandboxContext`.
+  - `getFirestore(app)` — resolves a PyricAdminApp's sandbox.
+  - `getFirestore()` — resolves the default app; throws `app/no-app` when
+    nothing is initialized.
+#### Parameters
+| Parameter | Type |
+| :------ | :------ |
+| `target?` | `any` |
+#### Returns
+`SandboxFirestore`

package/dist/serve/docs-ui/docs/pyric-admin-firestore-reference-onsnapshot/index.html ADDED Viewed

@@ -0,0 +1,68 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>onSnapshot overloads · Pyric Studio</title><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_.CQYSemvw.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>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><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/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/" aria-current="true"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </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-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><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/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/" aria-current="true"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </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/pyric-admin-firestore/">pyric-admin / firestore</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Reference</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">onSnapshot overloads</span> </li> </ol> </nav>  <article class="prose">  <h1 id="onsnapshot-overloads"><code>onSnapshot</code> overloads</h1>
+<p>The Web-SDK-shaped streaming surface. Four overload groups mirror <code>firebase/firestore</code>’s <code>onSnapshot</code> exactly, so existing call sites copied from production code typecheck unchanged.</p>
+<h2 id="why-web-shaped-not-admin-shaped">Why Web-shaped, not Admin-shaped</h2>
+<p>The Firebase Admin SDK’s <code>onSnapshot</code> lives on the reference (<code>db.doc('x').onSnapshot(...)</code>), takes positional <code>(onNext, onError)</code>, and produces admin-shaped snapshot types. The Web SDK’s <code>onSnapshot</code> is a standalone function (<code>onSnapshot(ref, observer)</code>), takes either positional or observer-shaped arguments, and produces a different snapshot type with <code>metadata</code>.</p>
+<p><code>pyric-admin</code> exposes the Web-SDK form for two reasons:</p>
+<ul>
+<li>React, Vue, and Svelte UI code copied from production looks identical.</li>
+<li>The Web-SDK observer form (<code>{ next, error, complete }</code>) is convenient for tests.</li>
+</ul>
+<p>The reference-method form (<code>ref.onSnapshot(...)</code>) is also available because the underlying Firestore reference still carries that method.</p>
+<h2 id="document-overloads">Document overloads</h2>
+<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:#7F848E;font-style:italic">// (observer)</span></span>
+<span class="line"><span style="color:#61AFEF">onSnapshot</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">ref</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">DocumentReference</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">observer</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">SnapshotObserver</span><span style="color:#56B6C2">&#x3C;</span><span style="color:#E06C75">DocumentSnapshot</span><span style="color:#56B6C2">></span><span style="color:#ABB2BF">): </span><span style="color:#E06C75">Unsubscribe</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">onSnapshot</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">ref</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">DocumentReference</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">options</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">SnapshotListenOptions</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">observer</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">SnapshotObserver</span><span style="color:#56B6C2">&#x3C;</span><span style="color:#E06C75">DocumentSnapshot</span><span style="color:#56B6C2">></span><span style="color:#ABB2BF">): </span><span style="color:#E06C75">Unsubscribe</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// (onNext, onError?)</span></span>
+<span class="line"><span style="color:#61AFEF">onSnapshot</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">ref</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">DocumentReference</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">onNext</span><span style="color:#ABB2BF">: (</span><span style="color:#E06C75;font-style:italic">snap</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">DocumentSnapshot</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#C678DD"> void</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">onError</span><span style="color:#C678DD">?:</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75;font-style:italic">error</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#C678DD"> void</span><span style="color:#ABB2BF">): </span><span style="color:#E06C75">Unsubscribe</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">onSnapshot</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">ref</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">DocumentReference</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">options</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">SnapshotListenOptions</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">onNext</span><span style="color:#ABB2BF">: (</span><span style="color:#E06C75;font-style:italic">snap</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">DocumentSnapshot</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#C678DD"> void</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">onError</span><span style="color:#C678DD">?:</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75;font-style:italic">error</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#C678DD"> void</span><span style="color:#ABB2BF">): </span><span style="color:#E06C75">Unsubscribe</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<h2 id="query-overloads">Query overloads</h2>
+<p>Same four shapes against <code>Query</code>:</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:#61AFEF">onSnapshot</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">query</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">Query</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">observer</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">SnapshotObserver</span><span style="color:#56B6C2">&#x3C;</span><span style="color:#E06C75">QuerySnapshot</span><span style="color:#56B6C2">></span><span style="color:#ABB2BF">): </span><span style="color:#E06C75">Unsubscribe</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">onSnapshot</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">query</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">Query</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">options</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">SnapshotListenOptions</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">observer</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">SnapshotObserver</span><span style="color:#56B6C2">&#x3C;</span><span style="color:#E06C75">QuerySnapshot</span><span style="color:#56B6C2">></span><span style="color:#ABB2BF">): </span><span style="color:#E06C75">Unsubscribe</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">onSnapshot</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">query</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">Query</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">onNext</span><span style="color:#ABB2BF">: (</span><span style="color:#E06C75;font-style:italic">snap</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">QuerySnapshot</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#C678DD"> void</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">onError</span><span style="color:#C678DD">?:</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75;font-style:italic">error</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#C678DD"> void</span><span style="color:#ABB2BF">): </span><span style="color:#E06C75">Unsubscribe</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#61AFEF">onSnapshot</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">query</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">Query</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">options</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">SnapshotListenOptions</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">onNext</span><span style="color:#ABB2BF">: (</span><span style="color:#E06C75;font-style:italic">snap</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">QuerySnapshot</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#C678DD"> void</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">onError</span><span style="color:#C678DD">?:</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75;font-style:italic">error</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#C678DD"> void</span><span style="color:#ABB2BF">): </span><span style="color:#E06C75">Unsubscribe</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<h2 id="snapshotlistenoptions"><code>SnapshotListenOptions</code></h2>
+<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">interface</span><span style="color:#E5C07B"> SnapshotListenOptions</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  includeMetadataChanges</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">boolean</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Accepted for shape parity. <code>includeMetadataChanges</code> has no observable effect in the sandbox (there’s no offline cache and no pending-writes window), so <code>metadata.fromCache</code> and <code>metadata.hasPendingWrites</code> are always <code>false</code>.</p>
+<h2 id="what-unsubscribe-does">What <code>Unsubscribe</code> does</h2>
+<p>Calling the returned function deregisters the listener and stops further callback invocations. Idempotent: calling it twice is a no-op.</p>
+<p>Always unsubscribe before discarding a listener, especially in React <code>useEffect</code> cleanup. Without it, a new render registers a fresh listener and the old one stays alive (until the sandbox is reset or disposed).</p>
+<h2 id="what-fires-the-error-callback">What fires the <code>error</code> callback</h2>
+<p>The observer’s <code>error</code> (or the positional <code>onError</code>) fires when a snapshot listener is silently terminated by a rule denial, either at initial read or during re-evaluation after a write. Once-per-stream: after <code>error</code> fires, no further callbacks happen on that listener.</p>
+<p>The sandbox also exposes <code>sandbox.onSnapshotError(cb)</code> (from <code>pyric/sandbox</code>) which fires for every stream-error across every listener. Use that when you want host-level error handling without each listener registering its own callback.</p>
+<h2 id="what-does-not-fire-the-callbacks">What does <em>not</em> fire the callbacks</h2>
+<ul>
+<li>Network failures: there is no network.</li>
+<li><code>unavailable</code> / <code>aborted</code> errors: no transport, no concurrent transactions.</li>
+<li><code>complete</code>: the listener stream has no terminal state.</li>
+</ul>
+<h2 id="routing">Routing</h2>
+<p>The handler routes by reference type:</p>
+<div class="table-scroll">
+<table><thead><tr><th>Argument</th><th>Target</th></tr></thead><tbody><tr><td><code>DocumentReference</code></td><td><code>{ kind: 'doc', path }</code></td></tr><tr><td><code>CollectionReference</code></td><td><code>{ kind: 'query', collection: path }</code></td></tr><tr><td>Chained query (<code>.where</code>, <code>.orderBy</code>, <code>.limit</code>)</td><td><code>{ kind: 'query', collection: rootCollection }</code></td></tr></tbody></table></div>
+<p>Chained queries currently route as whole-collection listeners: the simulator fires for any change in the collection, and the callback receives every document. Filter/order honoring at the listener layer is in a later slice.</p>
+<h2 id="auth-capture-at-register-time">Auth capture at register time</h2>
+<p>The context’s <code>auth</code> is captured when <code>onSnapshot</code> is called. Subsequent rule evaluations use that auth identity, even if the registering context is later replaced. To listen as a different identity, register a new listener through a different context’s handle.</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="#why-web-shaped-not-admin-shaped">Why Web-shaped, not Admin-shaped</a> </li><li data-depth="2"> <a href="#document-overloads">Document overloads</a> </li><li data-depth="2"> <a href="#query-overloads">Query overloads</a> </li><li data-depth="2"> <a href="#snapshotlistenoptions">SnapshotListenOptions</a> </li><li data-depth="2"> <a href="#what-unsubscribe-does">What Unsubscribe does</a> </li><li data-depth="2"> <a href="#what-fires-the-error-callback">What fires the error callback</a> </li><li data-depth="2"> <a href="#what-does-not-fire-the-callbacks">What does not fire the callbacks</a> </li><li data-depth="2"> <a href="#routing">Routing</a> </li><li data-depth="2"> <a href="#auth-capture-at-register-time">Auth capture at register time</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>

package/dist/serve/docs-ui/docs/pyric-admin-firestore-reference-onsnapshot.md ADDED Viewed

@@ -0,0 +1,81 @@
+# `onSnapshot` overloads
+The Web-SDK-shaped streaming surface. Four overload groups mirror `firebase/firestore`'s `onSnapshot` exactly, so existing call sites copied from production code typecheck unchanged.
+## Why Web-shaped, not Admin-shaped
+The Firebase Admin SDK's `onSnapshot` lives on the reference (`db.doc('x').onSnapshot(...)`), takes positional `(onNext, onError)`, and produces admin-shaped snapshot types. The Web SDK's `onSnapshot` is a standalone function (`onSnapshot(ref, observer)`), takes either positional or observer-shaped arguments, and produces a different snapshot type with `metadata`.
+`pyric-admin` exposes the Web-SDK form for two reasons:
+- React, Vue, and Svelte UI code copied from production looks identical.
+- The Web-SDK observer form (`{ next, error, complete }`) is convenient for tests.
+The reference-method form (`ref.onSnapshot(...)`) is also available because the underlying Firestore reference still carries that method.
+## Document overloads
+```ts
+// (observer)
+onSnapshot(ref: DocumentReference, observer: SnapshotObserver<DocumentSnapshot>): Unsubscribe;
+onSnapshot(ref: DocumentReference, options: SnapshotListenOptions, observer: SnapshotObserver<DocumentSnapshot>): Unsubscribe;
+// (onNext, onError?)
+onSnapshot(ref: DocumentReference, onNext: (snap: DocumentSnapshot) => void, onError?: (error: unknown) => void): Unsubscribe;
+onSnapshot(ref: DocumentReference, options: SnapshotListenOptions, onNext: (snap: DocumentSnapshot) => void, onError?: (error: unknown) => void): Unsubscribe;
+```
+## Query overloads
+Same four shapes against `Query`:
+```ts
+onSnapshot(query: Query, observer: SnapshotObserver<QuerySnapshot>): Unsubscribe;
+onSnapshot(query: Query, options: SnapshotListenOptions, observer: SnapshotObserver<QuerySnapshot>): Unsubscribe;
+onSnapshot(query: Query, onNext: (snap: QuerySnapshot) => void, onError?: (error: unknown) => void): Unsubscribe;
+onSnapshot(query: Query, options: SnapshotListenOptions, onNext: (snap: QuerySnapshot) => void, onError?: (error: unknown) => void): Unsubscribe;
+```
+## `SnapshotListenOptions`
+```ts
+interface SnapshotListenOptions {
+  includeMetadataChanges?: boolean;
+}
+```
+Accepted for shape parity. `includeMetadataChanges` has no observable effect in the sandbox (there's no offline cache and no pending-writes window), so `metadata.fromCache` and `metadata.hasPendingWrites` are always `false`.
+## What `Unsubscribe` does
+Calling the returned function deregisters the listener and stops further callback invocations. Idempotent: calling it twice is a no-op.
+Always unsubscribe before discarding a listener, especially in React `useEffect` cleanup. Without it, a new render registers a fresh listener and the old one stays alive (until the sandbox is reset or disposed).
+## What fires the `error` callback
+The observer's `error` (or the positional `onError`) fires when a snapshot listener is silently terminated by a rule denial, either at initial read or during re-evaluation after a write. Once-per-stream: after `error` fires, no further callbacks happen on that listener.
+The sandbox also exposes `sandbox.onSnapshotError(cb)` (from `pyric/sandbox`) which fires for every stream-error across every listener. Use that when you want host-level error handling without each listener registering its own callback.
+## What does *not* fire the callbacks
+- Network failures: there is no network.
+- `unavailable` / `aborted` errors: no transport, no concurrent transactions.
+- `complete`: the listener stream has no terminal state.
+## Routing
+The handler routes by reference type:
+| Argument | Target |
+|---|---|
+| `DocumentReference` | `{ kind: 'doc', path }` |
+| `CollectionReference` | `{ kind: 'query', collection: path }` |
+| Chained query (`.where`, `.orderBy`, `.limit`) | `{ kind: 'query', collection: rootCollection }` |
+Chained queries currently route as whole-collection listeners: the simulator fires for any change in the collection, and the callback receives every document. Filter/order honoring at the listener layer is in a later slice.
+## Auth capture at register time
+The context's `auth` is captured when `onSnapshot` is called. Subsequent rule evaluations use that auth identity, even if the registering context is later replaced. To listen as a different identity, register a new listener through a different context's handle.

package/dist/serve/docs-ui/docs/pyric-admin-firestore-reference-re-exported-types/index.html ADDED Viewed

@@ -0,0 +1,76 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Re-exported types · Pyric Studio</title><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_.CQYSemvw.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>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><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/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/" aria-current="true"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </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-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><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/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/" aria-current="true"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </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/pyric-admin-firestore/">pyric-admin / firestore</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Reference</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Re-exported types</span> </li> </ol> </nav>  <article class="prose">  <h1 id="re-exported-types">Re-exported types</h1>
+<p><code>pyric-admin/firestore</code> re-exports a large surface of types from the sandbox
+admin-firestore implementation and <code>pyric/sandbox</code> so most consumers can import
+the Firestore admin surface from one place. This page lists what comes from
+where and why.</p>
+<h2 id="from-pyricsandbox">From <code>pyric/sandbox</code></h2>
+<p>Foundation types you’ll always need alongside the data plane:</p>
+<ul>
+<li><code>AuthState</code>: the <code>{ uid, token? }</code> shape <code>withAuth</code> accepts.</li>
+<li><code>Sandbox</code>: the root handle from <code>initializeSandbox()</code>.</li>
+<li><code>SandboxContext</code>: the <code>(sandbox, auth)</code> pair <code>getFirestore</code> accepts.</li>
+<li><code>SandboxError</code>: the typed error family. Catch with <code>instanceof</code>.</li>
+</ul>
+<p>Anyone needing more reaches into <code>pyric/sandbox</code> directly.</p>
+<h2 id="production-shaped-types">Production-shaped types</h2>
+<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">export</span><span style="color:#C678DD"> type</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  AggregateField</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">AggregateQuerySnapshot</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">AggregateSpec</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">Filter</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  CollectionReference</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">DocumentData</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">DocumentReference</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  DocumentSnapshot</span><span style="color:#C678DD"> as</span><span style="color:#E06C75"> AdminDocumentSnapshot</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  FieldValueSentinel</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">Firestore</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  LintResult</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">LintWarning</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">OrderDirection</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  Query</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  QueryDocumentSnapshot</span><span style="color:#C678DD"> as</span><span style="color:#E06C75"> AdminQueryDocumentSnapshot</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  QuerySnapshot</span><span style="color:#C678DD"> as</span><span style="color:#E06C75"> AdminQuerySnapshot</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  RulesMetrics</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">SetOptions</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">Transaction</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">WhereFilterOp</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">WriteBatch</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">} </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox/admin-firestore'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>These mirror <code>firebase-admin/firestore</code>. The shapes match production exactly; the implementations are sandbox-aware.</p>
+<h3 id="why-the-admin-prefixes">Why the <code>Admin*</code> prefixes</h3>
+<p>The three snapshot types appear with <code>Admin*</code> prefixes:</p>
+<ul>
+<li><code>AdminDocumentSnapshot</code></li>
+<li><code>AdminQuerySnapshot</code></li>
+<li><code>AdminQueryDocumentSnapshot</code></li>
+</ul>
+<p>This is because the Web SDK has differently-shaped snapshot types with the same canonical names, and <code>onSnapshot</code> callbacks consume the Web shape. Aliasing the admin variants with the <code>Admin*</code> prefix keeps the canonical names available for the Web shape (see next section), so call sites copied from a <code>firebase/firestore</code> codebase typecheck without renaming.</p>
+<h2 id="web-sdk-shaped-snapshot-types">Web-SDK-shaped snapshot types</h2>
+<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">export</span><span style="color:#C678DD"> type</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  LiveDocumentSnapshot</span><span style="color:#C678DD"> as</span><span style="color:#E06C75"> DocumentSnapshot</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  LiveQueryDocumentSnapshot</span><span style="color:#C678DD"> as</span><span style="color:#E06C75"> QueryDocumentSnapshot</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  LiveQuerySnapshot</span><span style="color:#C678DD"> as</span><span style="color:#E06C75"> QuerySnapshot</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  DocumentChange</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  DocumentChangeType</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  DocChangesOptions</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  SnapshotMetadata</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">} </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox/admin-firestore'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>Spelled with the conventional Web SDK names. Use these when typing <code>onSnapshot</code> callbacks:</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">onSnapshot</span><span style="color:#ABB2BF">, </span><span style="color:#C678DD">type</span><span style="color:#E06C75"> DocumentSnapshot</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric-admin/firestore'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#61AFEF">onSnapshot</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">db</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'games/g1'</span><span style="color:#ABB2BF">), (</span><span style="color:#E06C75;font-style:italic">snap</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">DocumentSnapshot</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">snap</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">exists</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">snap</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">data</span><span style="color:#ABB2BF">(), </span><span style="color:#E5C07B">snap</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">metadata</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">fromCache</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span></code></pre>
+<h2 id="values">Values</h2>
+<p>Two runtime values re-exported from the simulator:</p>
+<ul>
+<li><code>FieldValue</code>: the sentinel factory. <code>FieldValue.serverTimestamp()</code>, <code>FieldValue.increment(1)</code>, <code>FieldValue.arrayUnion(...)</code>, <code>FieldValue.arrayRemove(...)</code>, <code>FieldValue.delete()</code>.</li>
+<li><code>Timestamp</code>: the timestamp wrapper class. <code>Timestamp.now()</code>, <code>Timestamp.fromDate(d)</code>, <code>Timestamp.fromMillis(ms)</code>.</li>
+</ul>
+<p>Both behave the same way as in <code>firebase-admin/firestore</code>. The implementations route through the sandbox’s value-resolver so writes encoded with sentinels merge correctly into the post-state.</p>
+<h2 id="why-all-this-lives-at-the-top-of-pyric-admin">Why all this lives at the top of <code>pyric-admin</code></h2>
+<p>A user writing a test wants:</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>
+<span class="line"><span style="color:#E06C75">  getFirestore</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  initializeSandbox</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  SandboxError</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  FieldValue</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  Timestamp</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#C678DD">  type</span><span style="color:#E06C75"> DocumentSnapshot</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">} </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric-admin'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>Mostly one import. Reaching for <code>pyric/sandbox</code> separately to get
+<code>SandboxError</code>, or for <code>pyric/sandbox/admin-firestore</code> separately for
+<code>FieldValue</code>, would create friction for the common case. The aliases and
+re-exports here exist to remove that friction.</p>
+<p>When the consumer genuinely needs something not in this surface (the raw
+<code>LocalEnvironment</code>, credentials for Rules Test API, the rules linter), the import path tells
+them where to look: <code>pyric/sandbox/internal</code>, <code>@pyric/cli/credentials/node</code>, or
+<code>pyric/rules</code>.</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="#from-pyricsandbox">From pyric/sandbox</a> </li><li data-depth="2"> <a href="#production-shaped-types">Production-shaped types</a> </li><li data-depth="3"> <a href="#why-the-admin-prefixes">Why the Admin* prefixes</a> </li><li data-depth="2"> <a href="#web-sdk-shaped-snapshot-types">Web-SDK-shaped snapshot types</a> </li><li data-depth="2"> <a href="#values">Values</a> </li><li data-depth="2"> <a href="#why-all-this-lives-at-the-top-of-pyric-admin">Why all this lives at the top of pyric-admin</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>

package/dist/serve/docs-ui/docs/pyric-admin-firestore-reference-re-exported-types.md ADDED Viewed

@@ -0,0 +1,103 @@
+# Re-exported types
+`pyric-admin/firestore` re-exports a large surface of types from the sandbox
+admin-firestore implementation and `pyric/sandbox` so most consumers can import
+the Firestore admin surface from one place. This page lists what comes from
+where and why.
+## From `pyric/sandbox`
+Foundation types you'll always need alongside the data plane:
+- `AuthState`: the `{ uid, token? }` shape `withAuth` accepts.
+- `Sandbox`: the root handle from `initializeSandbox()`.
+- `SandboxContext`: the `(sandbox, auth)` pair `getFirestore` accepts.
+- `SandboxError`: the typed error family. Catch with `instanceof`.
+Anyone needing more reaches into `pyric/sandbox` directly.
+## Production-shaped types
+```ts
+export type {
+  AggregateField, AggregateQuerySnapshot, AggregateSpec, Filter,
+  CollectionReference, DocumentData, DocumentReference,
+  DocumentSnapshot as AdminDocumentSnapshot,
+  FieldValueSentinel, Firestore,
+  LintResult, LintWarning, OrderDirection,
+  Query,
+  QueryDocumentSnapshot as AdminQueryDocumentSnapshot,
+  QuerySnapshot as AdminQuerySnapshot,
+  RulesMetrics, SetOptions, Transaction, WhereFilterOp, WriteBatch,
+} from 'pyric/sandbox/admin-firestore';
+```
+These mirror `firebase-admin/firestore`. The shapes match production exactly; the implementations are sandbox-aware.
+### Why the `Admin*` prefixes
+The three snapshot types appear with `Admin*` prefixes:
+- `AdminDocumentSnapshot`
+- `AdminQuerySnapshot`
+- `AdminQueryDocumentSnapshot`
+This is because the Web SDK has differently-shaped snapshot types with the same canonical names, and `onSnapshot` callbacks consume the Web shape. Aliasing the admin variants with the `Admin*` prefix keeps the canonical names available for the Web shape (see next section), so call sites copied from a `firebase/firestore` codebase typecheck without renaming.
+## Web-SDK-shaped snapshot types
+```ts
+export type {
+  LiveDocumentSnapshot as DocumentSnapshot,
+  LiveQueryDocumentSnapshot as QueryDocumentSnapshot,
+  LiveQuerySnapshot as QuerySnapshot,
+  DocumentChange,
+  DocumentChangeType,
+  DocChangesOptions,
+  SnapshotMetadata,
+} from 'pyric/sandbox/admin-firestore';
+```
+Spelled with the conventional Web SDK names. Use these when typing `onSnapshot` callbacks:
+```ts
+import { onSnapshot, type DocumentSnapshot } from 'pyric-admin/firestore';
+onSnapshot(db.doc('games/g1'), (snap: DocumentSnapshot) => {
+  console.log(snap.exists, snap.data(), snap.metadata.fromCache);
+});
+```
+## Values
+Two runtime values re-exported from the simulator:
+- `FieldValue`: the sentinel factory. `FieldValue.serverTimestamp()`, `FieldValue.increment(1)`, `FieldValue.arrayUnion(...)`, `FieldValue.arrayRemove(...)`, `FieldValue.delete()`.
+- `Timestamp`: the timestamp wrapper class. `Timestamp.now()`, `Timestamp.fromDate(d)`, `Timestamp.fromMillis(ms)`.
+Both behave the same way as in `firebase-admin/firestore`. The implementations route through the sandbox's value-resolver so writes encoded with sentinels merge correctly into the post-state.
+## Why all this lives at the top of `pyric-admin`
+A user writing a test wants:
+```ts
+import {
+  getFirestore,
+  initializeSandbox,
+  SandboxError,
+  FieldValue,
+  Timestamp,
+  type DocumentSnapshot,
+} from 'pyric-admin';
+```
+Mostly one import. Reaching for `pyric/sandbox` separately to get
+`SandboxError`, or for `pyric/sandbox/admin-firestore` separately for
+`FieldValue`, would create friction for the common case. The aliases and
+re-exports here exist to remove that friction.
+When the consumer genuinely needs something not in this surface (the raw
+`LocalEnvironment`, credentials for Rules Test API, the rules linter), the import path tells
+them where to look: `pyric/sandbox/internal`, `@pyric/cli/credentials/node`, or
+`pyric/rules`.