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-cli-how-to-serve-persistence-and-multi-tab/index.html ADDED Viewed

@@ -0,0 +1,228 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Persistence and multi-tab with pyric dev · 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/" aria-current="true"> @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/"> 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/" aria-current="true"> @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/"> 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-cli/">@pyric/cli</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>How-to</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Persistence &amp; multi-tab</span> </li> </ol> </nav>  <article class="prose">  <h1 id="persistence-and-multi-tab-with-pyric-dev">Persistence and multi-tab with <code>pyric dev</code></h1>
+<p>When you run <code>pyric dev</code>, your app’s <code>firebase/*</code> imports are served from an
+<strong>in-browser pyric sandbox</strong> instead of real Firebase. This guide covers how
+that sandbox keeps (or doesn’t keep) data, the flags that control it, and what
+to do if the SharedWorker that backs it acts up.</p>
+<h2 id="how-the-sandbox-is-hosted-and-why-it-matters">How the sandbox is hosted (and why it matters)</h2>
+<p><code>pyric dev</code> runs the sandbox one of two ways, chosen automatically:</p>
+<ul>
+<li><strong>SharedWorker (the default: Chrome/Edge, Firefox, Safari 16.4+).</strong> One
+sandbox lives in a SharedWorker shared by <strong>every tab</strong> of the origin. All
+tabs read and write the same backend, so writes sync <strong>live across tabs</strong>,
+and the worker keeps its data in <strong>IndexedDB</strong>, so your data <strong>survives a
+refresh, a tab close, and a <code>pyric dev</code> restart by default</strong>.</li>
+<li><strong>In-page fallback (older browsers without SharedWorker).</strong> Each tab runs its
+own sandbox in the page. Data is <strong>ephemeral</strong> (lost on refresh) unless you
+pass <code>--persist</code>; cross-tab realtime uses BroadcastChannel.</li>
+</ul>
+<p>You can see which path you’re on in the console:
+<code>[pyric dev] firebase/* on this page is served by the pyric sandbox in a SharedWorker …</code>.</p>
+<h2 id="keep-data-across-reloads-the-default">Keep data across reloads: the default</h2>
+<p>On the SharedWorker path you don’t need any flag. The worker persists to the
+browser’s IndexedDB automatically: refresh the page, close the tab and reopen,
+or restart <code>pyric dev</code>, and your Firestore docs, auth users, and signed-in
+session come back.</p>
+<p>The SharedWorker makes <strong>durability the default</strong> so a refresh does not lose
+your work.</p>
+<h2 id="what-survives-what-the-coverage-matrix">What survives what: the coverage matrix</h2>
+<p>Durability is per service in this release. “Worker death” means the last tab
+of the origin closed (or the browser tore the SharedWorker down between a
+refresh of your only tab). With two tabs open (Studio plus your app), the
+worker stays alive, and everything in this table trivially survives a refresh.</p>
+<div class="table-scroll">
+<table><thead><tr><th></th><th>refresh<br>(worker alive)</th><th>worker death /<br>browser restart</th><th><code>--persist</code><br>(state.json)</th><th><code>pyric snapshot</code></th></tr></thead><tbody><tr><td>Firestore documents</td><td>✓</td><td>✓ IndexedDB</td><td>✓</td><td>✓</td></tr><tr><td>Auth users + session</td><td>✓</td><td>✓ IndexedDB</td><td>✓</td><td>✓</td></tr><tr><td>Storage objects</td><td>✓</td><td>✓ IndexedDB (its own store)</td><td>✗</td><td>✗</td></tr><tr><td>RTDB data</td><td>✓</td><td>✓ IndexedDB</td><td>✓</td><td>✓ (rides the state blob)</td></tr><tr><td>Traffic / event history</td><td>✓</td><td>✓ re-hydrated from the session capture (served mode; the last ~400ms can lag)</td><td>✗</td><td>✗</td></tr><tr><td>Sandbox branches</td><td>✓</td><td>✓ IndexedDB</td><td>✗ deliberately local</td><td>✗</td></tr></tbody></table></div>
+<p>Notes, honestly stated:</p>
+<ul>
+<li><strong>Storage persists in this browser but does not ride <code>--persist</code></strong>: objects
+live in their own IndexedDB store, so they survive restarts on your machine
+but are not part of the committable state file or <code>pyric snapshot</code>.</li>
+<li><strong>Branches never reach <code>state.json</code> on purpose</strong>: they are local working
+state, like a stash, not part of the fixture you’d commit.</li>
+<li>IndexedDB is <strong>per browser profile, per origin (host:port)</strong>: a different
+port, profile, or incognito window is a fresh sandbox.</li>
+</ul>
+<h2 id="persist-to-a-committable-file---persist">Persist to a committable file: <code>--persist</code></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"> --persist</span></span></code></pre>
+<p><code>--persist</code> adds a durable, <strong>git-trackable</strong> state file at
+<code>.pyric/state/state.json</code>. The sandbox restores from it on start and mirrors
+writes back to it. Reach for it when you want sandbox state that:</p>
+<ul>
+<li>survives clearing your browser’s storage,</li>
+<li>can be committed and shared with teammates,</li>
+<li>can be promoted to real Firestore later (<code>pyric snapshot</code>).</li>
+</ul>
+<p>On the SharedWorker path your data already persists in the browser without this
+flag: <code>--persist</code> is specifically about the <strong>on-disk, shareable</strong> copy.</p>
+<h2 id="run-ephemerally-no-data-kept">Run ephemerally: no data kept</h2>
+<p>There is <strong>no <code>--ephemeral</code> flag</strong>; durable-by-default is intentional. To run
+without keeping anything between sessions:</p>
+<ul>
+<li><strong>Use a private / incognito window.</strong> Its IndexedDB is discarded when the
+window closes, so every session starts clean. (Simplest option.)</li>
+<li>Or <strong>clear site data</strong> between runs (see below).</li>
+</ul>
+<p>On a browser without SharedWorker, the in-page fallback is already ephemeral
+unless you pass <code>--persist</code>.</p>
+<h2 id="start-fresh--clear-persistence">Start fresh / clear persistence</h2>
+<p>Two stores can hold data. Clear the one(s) you need:</p>
+<div class="table-scroll">
+<table><thead><tr><th>Store</th><th>Where it lives</th><th>Clear it with</th></tr></thead><tbody><tr><td><strong>IndexedDB</strong> (the SharedWorker’s default durable store)</td><td>the browser, per origin</td><td>DevTools → <strong>Application → Storage → Clear site data</strong>, then reload, or use a private window instead</td></tr><tr><td><strong><code>.pyric/state/state.json</code></strong> (the <code>--persist</code> file)</td><td>your project directory</td><td><code>pyric dev --persist --fresh</code> (discards it and re-seeds)</td></tr></tbody></table></div>
+<p><code>--fresh</code> <strong>requires <code>--persist</code></strong>: it discards <code>.pyric/state/state.json</code>, and
+without <code>--persist</code> there is no such file, so <code>pyric dev</code> now errors instead of
+silently doing nothing.</p>
+<p><code>--fresh</code> clears only the on-disk file. It does <strong>not</strong> touch the browser’s
+IndexedDB. ⚠ <strong>This makes <code>--fresh</code> a half-reset</strong>: prime-once only fills an
+EMPTY IndexedDB, so a browser tab that already has sandbox data KEEPS it, and
+that tab’s next flush writes it straight back into the file <code>--fresh</code> just
+cleared. The “fresh” file quietly refills with the old data. For a fully clean
+slate on the SharedWorker path, you must <strong>also clear site data</strong> (or use a
+private window) whenever you pass <code>--fresh</code>. (A real reset handshake that makes
+<code>--fresh</code> clear the browser store too is future work.)</p>
+<h2 id="seed-data-on-boot---seed">Seed data on boot: <code>--seed</code></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"> --seed</span><span style="color:#98C379"> seed.json</span></span></code></pre>
+<p>Loads a fixture document set admin-style before your app runs. Accepts either a
+<code>"collection/doc" → fields</code> map or a <code>pyric snapshot</code> state file.</p>
+<p><strong>A seed applies only into an empty home.</strong> If the sandbox already holds
+restored data, whether a <code>--persist</code> state file or data IndexedDB restored
+from an earlier session (which happens even without <code>--persist</code>, since
+IndexedDB is the SharedWorker’s default durable store), the fixture is
+skipped, not applied on top of it, and a console line explains why. This is
+what stops <code>--seed</code> from silently reverting your edits on every reload:
+without it, default (ephemeral) mode had no state file to gate on, so the
+fixture re-applied on every boot no matter what you’d changed in the browser.
+Use <code>--persist --fresh</code> (plus clearing browser storage, see above) to
+discard existing state and re-seed from scratch.</p>
+<h2 id="sharedworker-troubleshooting">SharedWorker troubleshooting</h2>
+<p>A SharedWorker is shared by all tabs of an origin and <strong>stays alive as long as
+any tab is open</strong>. That leads to a few dev-time gotchas:</p>
+<p><strong>“I rebuilt pyric, but my change isn’t taking effect.”</strong>
+A SharedWorker can’t hot-update: it runs whatever code started it until
+<strong>every</strong> tab of the origin closes. After rebuilding pyric, <strong>close all tabs</strong>
+of the origin and open one fresh. The page logs a clear warning when it detects
+a stale worker (<code>the SharedWorker is running OLDER code … CLOSE ALL TABS</code>). You
+can also force-kill it at <code>chrome://inspect/#workers</code> → find
+<code>pyric-shared-worker</code> → <strong>Terminate</strong>.
+<em>This only affects people developing pyric itself. Editing <strong>your app’s</strong> code
+reloads normally, because the worker holds pyric’s code, not yours.</em></p>
+<p><strong>“My tabs aren’t syncing with each other.”</strong>
+Live multi-tab sync needs all tabs to share one worker. They will, as long as
+they’re the <strong>same origin</strong> (same <code>http://localhost:PORT</code>) and loaded from the
+<strong>same pyric build</strong>. If you opened tabs across a rebuild, close them all and
+reopen so they share the current worker.</p>
+<p><strong>Sign-in.</strong> Email/password, anonymous, and provider popup/redirect
+(<code>signInWithPopup</code>/<code>signInWithRedirect</code>) all work over the worker: the picker
+runs in the page and the identity is handed to the worker, and the session is
+shared across tabs. <code>or()</code>/<code>and()</code> composite queries work over the worker too:
+the composite filter tree (including nested <code>and</code>/<code>or</code>/<code>where</code> and composition
+with <code>orderBy</code>/<code>limit</code>) crosses the worker protocol and evaluates against the
+one shared sandbox, matching the in-page result. <code>signInWithCredential</code> isn’t
+supported over the worker yet (it raises a clear error); it works on the
+in-page fallback.</p>
+<h2 id="the-flags-this-guide-uses">The flags this guide uses</h2>
+<div class="table-scroll">
+<table><thead><tr><th>Flag</th><th>Effect</th></tr></thead><tbody><tr><td><code>--persist</code></td><td>durable, git-trackable state at <code>.pyric/state/state.json</code> (worker mirrors to it; the in-page fallback uses it as its durable store)</td></tr><tr><td><code>--fresh</code></td><td>requires <code>--persist</code> (errors otherwise); discards the <code>.pyric/state</code> file and re-seeds, but does <strong>not</strong> clear browser IndexedDB, so a browser with existing data writes it right back (also clear site data / use a private window for a full reset)</td></tr><tr><td><code>--seed &#x3C;file></code></td><td>load fixture docs on boot (a <code>"collection/doc" → fields</code> map, or a <code>pyric snapshot</code> file); applies only into an empty sandbox, skipped (with a console note) if restored/lived data is already present</td></tr><tr><td><code>--no-capture</code></td><td>disable the default-on session capture (<code>.pyric/last-session.json</code>, replayed by <code>pyric verify</code>)</td></tr></tbody></table></div>
+<p>The complete <code>pyric dev</code> flag set (<code>--port</code>, <code>--host</code>, <code>--bridge</code>,
+<code>--no-watch</code>, <code>--no-open</code>, <code>--no-cache</code>, <code>--allowed-host</code>, <code>--json</code>, …) lives in
+the <a href="../pyric-cli-reference-cli/#pyric-dev">CLI reference</a>.</p>
+<h2 id="see-also">See also</h2>
+<ul>
+<li><a href="../pyric-sandbox-explanation-local-backend-vs-firestore-offline/">Why an in-browser backend is <em>not</em> Firestore offline persistence</a>:
+why multi-tab + persistence here avoid the distributed-systems complexity.</li>
+<li><a href="../start-building/">Getting started</a>: scaffold → serve → agent.</li>
+</ul>  </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="#how-the-sandbox-is-hosted-and-why-it-matters">How the sandbox is hosted (and why it matters)</a> </li><li data-depth="2"> <a href="#keep-data-across-reloads-the-default">Keep data across reloads: the default</a> </li><li data-depth="2"> <a href="#what-survives-what-the-coverage-matrix">What survives what: the coverage matrix</a> </li><li data-depth="2"> <a href="#persist-to-a-committable-file---persist">Persist to a committable file: --persist</a> </li><li data-depth="2"> <a href="#run-ephemerally-no-data-kept">Run ephemerally: no data kept</a> </li><li data-depth="2"> <a href="#start-fresh--clear-persistence">Start fresh / clear persistence</a> </li><li data-depth="2"> <a href="#seed-data-on-boot---seed">Seed data on boot: --seed</a> </li><li data-depth="2"> <a href="#sharedworker-troubleshooting">SharedWorker troubleshooting</a> </li><li data-depth="2"> <a href="#the-flags-this-guide-uses">The flags this guide uses</a> </li><li data-depth="2"> <a href="#see-also">See also</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-cli-how-to-serve-persistence-and-multi-tab.md ADDED Viewed

@@ -0,0 +1,179 @@
+# Persistence and multi-tab with `pyric dev`
+When you run `pyric dev`, your app's `firebase/*` imports are served from an
+**in-browser pyric sandbox** instead of real Firebase. This guide covers how
+that sandbox keeps (or doesn't keep) data, the flags that control it, and what
+to do if the SharedWorker that backs it acts up.
+## How the sandbox is hosted (and why it matters)
+`pyric dev` runs the sandbox one of two ways, chosen automatically:
+- **SharedWorker (the default: Chrome/Edge, Firefox, Safari 16.4+).** One
+  sandbox lives in a SharedWorker shared by **every tab** of the origin. All
+  tabs read and write the same backend, so writes sync **live across tabs**,
+  and the worker keeps its data in **IndexedDB**, so your data **survives a
+  refresh, a tab close, and a `pyric dev` restart by default**.
+- **In-page fallback (older browsers without SharedWorker).** Each tab runs its
+  own sandbox in the page. Data is **ephemeral** (lost on refresh) unless you
+  pass `--persist`; cross-tab realtime uses BroadcastChannel.
+You can see which path you're on in the console:
+`[pyric dev] firebase/* on this page is served by the pyric sandbox in a SharedWorker …`.
+## Keep data across reloads: the default
+On the SharedWorker path you don't need any flag. The worker persists to the
+browser's IndexedDB automatically: refresh the page, close the tab and reopen,
+or restart `pyric dev`, and your Firestore docs, auth users, and signed-in
+session come back.
+The SharedWorker makes **durability the default** so a refresh does not lose
+your work.
+## What survives what: the coverage matrix
+Durability is per service in this release. "Worker death" means the last tab
+of the origin closed (or the browser tore the SharedWorker down between a
+refresh of your only tab). With two tabs open (Studio plus your app), the
+worker stays alive, and everything in this table trivially survives a refresh.
+| | refresh<br>(worker alive) | worker death /<br>browser restart | `--persist`<br>(state.json) | `pyric snapshot` |
+| --- | --- | --- | --- | --- |
+| Firestore documents | ✓ | ✓ IndexedDB | ✓ | ✓ |
+| Auth users + session | ✓ | ✓ IndexedDB | ✓ | ✓ |
+| Storage objects | ✓ | ✓ IndexedDB (its own store) | ✗ | ✗ |
+| RTDB data | ✓ | ✓ IndexedDB | ✓ | ✓ (rides the state blob) |
+| Traffic / event history | ✓ | ✓ re-hydrated from the session capture (served mode; the last ~400ms can lag) | ✗ | ✗ |
+| Sandbox branches | ✓ | ✓ IndexedDB | ✗ deliberately local | ✗ |
+Notes, honestly stated:
+- **Storage persists in this browser but does not ride `--persist`**: objects
+  live in their own IndexedDB store, so they survive restarts on your machine
+  but are not part of the committable state file or `pyric snapshot`.
+- **Branches never reach `state.json` on purpose**: they are local working
+  state, like a stash, not part of the fixture you'd commit.
+- IndexedDB is **per browser profile, per origin (host:port)**: a different
+  port, profile, or incognito window is a fresh sandbox.
+## Persist to a committable file: `--persist`
+```bash
+pyric dev --persist
+```
+`--persist` adds a durable, **git-trackable** state file at
+`.pyric/state/state.json`. The sandbox restores from it on start and mirrors
+writes back to it. Reach for it when you want sandbox state that:
+- survives clearing your browser's storage,
+- can be committed and shared with teammates,
+- can be promoted to real Firestore later (`pyric snapshot`).
+On the SharedWorker path your data already persists in the browser without this
+flag: `--persist` is specifically about the **on-disk, shareable** copy.
+## Run ephemerally: no data kept
+There is **no `--ephemeral` flag**; durable-by-default is intentional. To run
+without keeping anything between sessions:
+- **Use a private / incognito window.** Its IndexedDB is discarded when the
+  window closes, so every session starts clean. (Simplest option.)
+- Or **clear site data** between runs (see below).
+On a browser without SharedWorker, the in-page fallback is already ephemeral
+unless you pass `--persist`.
+## Start fresh / clear persistence
+Two stores can hold data. Clear the one(s) you need:
+| Store | Where it lives | Clear it with |
+|---|---|---|
+| **IndexedDB** (the SharedWorker's default durable store) | the browser, per origin | DevTools → **Application → Storage → Clear site data**, then reload, or use a private window instead |
+| **`.pyric/state/state.json`** (the `--persist` file) | your project directory | `pyric dev --persist --fresh` (discards it and re-seeds) |
+`--fresh` **requires `--persist`**: it discards `.pyric/state/state.json`, and
+without `--persist` there is no such file, so `pyric dev` now errors instead of
+silently doing nothing.
+`--fresh` clears only the on-disk file. It does **not** touch the browser's
+IndexedDB. ⚠ **This makes `--fresh` a half-reset**: prime-once only fills an
+EMPTY IndexedDB, so a browser tab that already has sandbox data KEEPS it, and
+that tab's next flush writes it straight back into the file `--fresh` just
+cleared. The "fresh" file quietly refills with the old data. For a fully clean
+slate on the SharedWorker path, you must **also clear site data** (or use a
+private window) whenever you pass `--fresh`. (A real reset handshake that makes
+`--fresh` clear the browser store too is future work.)
+## Seed data on boot: `--seed`
+```bash
+pyric dev --seed seed.json
+```
+Loads a fixture document set admin-style before your app runs. Accepts either a
+`"collection/doc" → fields` map or a `pyric snapshot` state file.
+**A seed applies only into an empty home.** If the sandbox already holds
+restored data, whether a `--persist` state file or data IndexedDB restored
+from an earlier session (which happens even without `--persist`, since
+IndexedDB is the SharedWorker's default durable store), the fixture is
+skipped, not applied on top of it, and a console line explains why. This is
+what stops `--seed` from silently reverting your edits on every reload:
+without it, default (ephemeral) mode had no state file to gate on, so the
+fixture re-applied on every boot no matter what you'd changed in the browser.
+Use `--persist --fresh` (plus clearing browser storage, see above) to
+discard existing state and re-seed from scratch.
+## SharedWorker troubleshooting
+A SharedWorker is shared by all tabs of an origin and **stays alive as long as
+any tab is open**. That leads to a few dev-time gotchas:
+**"I rebuilt pyric, but my change isn't taking effect."**
+A SharedWorker can't hot-update: it runs whatever code started it until
+**every** tab of the origin closes. After rebuilding pyric, **close all tabs**
+of the origin and open one fresh. The page logs a clear warning when it detects
+a stale worker (`the SharedWorker is running OLDER code … CLOSE ALL TABS`). You
+can also force-kill it at `chrome://inspect/#workers` → find
+`pyric-shared-worker` → **Terminate**.
+*This only affects people developing pyric itself. Editing **your app's** code
+reloads normally, because the worker holds pyric's code, not yours.*
+**"My tabs aren't syncing with each other."**
+Live multi-tab sync needs all tabs to share one worker. They will, as long as
+they're the **same origin** (same `http://localhost:PORT`) and loaded from the
+**same pyric build**. If you opened tabs across a rebuild, close them all and
+reopen so they share the current worker.
+**Sign-in.** Email/password, anonymous, and provider popup/redirect
+(`signInWithPopup`/`signInWithRedirect`) all work over the worker: the picker
+runs in the page and the identity is handed to the worker, and the session is
+shared across tabs. `or()`/`and()` composite queries work over the worker too:
+the composite filter tree (including nested `and`/`or`/`where` and composition
+with `orderBy`/`limit`) crosses the worker protocol and evaluates against the
+one shared sandbox, matching the in-page result. `signInWithCredential` isn't
+supported over the worker yet (it raises a clear error); it works on the
+in-page fallback.
+## The flags this guide uses
+| Flag | Effect |
+|---|---|
+| `--persist` | durable, git-trackable state at `.pyric/state/state.json` (worker mirrors to it; the in-page fallback uses it as its durable store) |
+| `--fresh` | requires `--persist` (errors otherwise); discards the `.pyric/state` file and re-seeds, but does **not** clear browser IndexedDB, so a browser with existing data writes it right back (also clear site data / use a private window for a full reset) |
+| `--seed <file>` | load fixture docs on boot (a `"collection/doc" → fields` map, or a `pyric snapshot` file); applies only into an empty sandbox, skipped (with a console note) if restored/lived data is already present |
+| `--no-capture` | disable the default-on session capture (`.pyric/last-session.json`, replayed by `pyric verify`) |
+The complete `pyric dev` flag set (`--port`, `--host`, `--bridge`,
+`--no-watch`, `--no-open`, `--no-cache`, `--allowed-host`, `--json`, …) lives in
+the [CLI reference](../pyric-cli-reference-cli/#pyric-dev).
+## See also
+- [Why an in-browser backend is *not* Firestore offline persistence](../pyric-sandbox-explanation-local-backend-vs-firestore-offline/):
+  why multi-tab + persistence here avoid the distributed-systems complexity.
+- [Getting started](../start-building/): scaffold → serve → agent.