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/ui-firestore-querybuilder/index.html ADDED Viewed

@@ -0,0 +1,104 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>&lt;QueryBuilder&gt; · 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/"> 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/" aria-current="true"> @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/"> 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/" aria-current="true"> @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/ui/">@pyric/ui</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Firestore</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">&lt;QueryBuilder&gt;</span> </li> </ol> </nav>  <article class="prose">  <h1 id="querybuilder"><code>&#x3C;QueryBuilder></code></h1>
+<p>Single-level where/orderBy/limit query builder. Composes state into a real Firestore <code>Query</code> via the hook’s <code>buildQuery(base)</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:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">QueryBuilder</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/ui/firestore'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<h2 id="example">Example</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="tsx"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">useState</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'react'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">collection</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/firestore'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">QueryBuilder</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">useDocumentList</span><span style="color:#ABB2BF">, </span><span style="color:#C678DD">type</span><span style="color:#E06C75"> UseQueryBuilderResult</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/ui/firestore'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">function</span><span style="color:#61AFEF"> FilteredDocs</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75;font-style:italic">firestore</span><span style="color:#ABB2BF"> }) {</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#ABB2BF"> [</span><span style="color:#E5C07B">builder</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">setBuilder</span><span style="color:#ABB2BF">] </span><span style="color:#56B6C2">=</span><span style="color:#61AFEF"> useState</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">UseQueryBuilderResult</span><span style="color:#ABB2BF"> | </span><span style="color:#E5C07B">null</span><span style="color:#ABB2BF">>(</span><span style="color:#D19A66">null</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> base</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> collection</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">firestore</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'users'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> query</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> builder</span><span style="color:#ABB2BF">?.</span><span style="color:#61AFEF">buildQuery</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">base</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#ABB2BF"> { </span><span style="color:#E5C07B">documents</span><span style="color:#ABB2BF"> } </span><span style="color:#56B6C2">=</span><span style="color:#61AFEF"> useDocumentList</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">collection</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">base</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">query</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">  return</span><span style="color:#ABB2BF"> (</span></span>
+<span class="line"><span style="color:#ABB2BF">    &#x3C;></span></span>
+<span class="line"><span style="color:#ABB2BF">      &#x3C;</span><span style="color:#E5C07B">QueryBuilder</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">        initial</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#ABB2BF">{</span></span>
+<span class="line"><span style="color:#E06C75">          conditions</span><span style="color:#ABB2BF">: [{ </span><span style="color:#E06C75">id</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'c1'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">field</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'active'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">op</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'=='</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">value</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF"> }],</span></span>
+<span class="line"><span style="color:#E06C75">          orderBy</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">field</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'score'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">direction</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'desc'</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#E06C75">          limit</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">20</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">        }</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">        onChange</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E06C75">setBuilder</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#ABB2BF">      /></span></span>
+<span class="line"><span style="color:#ABB2BF">      &#x3C;</span><span style="color:#E5C07B">DocumentList</span><span style="color:#D19A66;font-style:italic"> documents</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E06C75">documents</span><span style="color:#C678DD">}</span><span style="color:#ABB2BF"> /></span></span>
+<span class="line"><span style="color:#ABB2BF">    &#x3C;/></span></span>
+<span class="line"><span style="color:#ABB2BF">  );</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<h2 id="props">Props</h2>
+<div class="table-scroll">
+<table><thead><tr><th>Prop</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>initial</code></td><td><code>Partial&#x3C;QueryBuilderState></code></td><td>Pre-populate conditions, orderBy, limit.</td></tr><tr><td><code>onChange</code></td><td><code>(builder: UseQueryBuilderResult) => void</code></td><td>Fires on every state change. Capture this to call <code>buildQuery</code>.</td></tr><tr><td><code>className</code></td><td><code>string</code></td><td>Forwarded to the root.</td></tr></tbody></table></div>
+<h2 id="value-parsing">Value parsing</h2>
+<p>The value input is JSON-parsed on every change. So:</p>
+<ul>
+<li><code>42</code> → number</li>
+<li><code>"text"</code> → string</li>
+<li><code>true</code> / <code>false</code> / <code>null</code> → those primitives</li>
+<li><code>[1, 2, 3]</code> → array (for <code>in</code> / <code>not-in</code> / <code>array-contains-any</code> ops)</li>
+<li>Anything that doesn’t parse as JSON → falls through as a raw string</li>
+</ul>
+<p>For non-JSON Firestore values (Timestamp, GeoPoint, Reference, Bytes), the bundled component isn’t enough — use <code>useQueryBuilder</code> directly with your own value editor.</p>
+<h2 id="direct-hook-access">Direct hook access</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="tsx"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  useQueryBuilder</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  QUERY_OPS</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  MULTI_VALUE_OPS</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/ui/firestore/hooks'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> builder</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> useQueryBuilder</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">initial</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">conditions</span><span style="color:#ABB2BF">: [...] } });</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// {</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">//   conditions, orderBy, limit,</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">//   addCondition, updateCondition, removeCondition,</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">//   setOrderBy, setLimit, reset, buildQuery,</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// }</span></span></code></pre>
+<h2 id="whats-not-in-v1">What’s not in v1</h2>
+<ul>
+<li><strong>Compound <code>and()</code> / <code>or()</code> groups.</strong> Single-level only — every condition is implicitly AND-joined. Compound groups deferred.</li>
+<li><strong>Cursor-based pagination (<code>startAfter</code>).</strong> Use <code>useDocumentList</code> with the composed query — pagination is its job.</li>
+</ul>
+<h2 id="styling-hooks">Styling hooks</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="plaintext"><code><span class="line"><span>[data-pyric-ui="query-builder"]</span></span>
+<span class="line"><span>[data-pyric-query-conditions]</span></span>
+<span class="line"><span>[data-pyric-query-condition]</span></span>
+<span class="line"><span>[data-pyric-query-field]</span></span>
+<span class="line"><span>[data-pyric-query-op]</span></span>
+<span class="line"><span>[data-pyric-query-value]</span></span>
+<span class="line"><span>[data-pyric-query-remove]</span></span>
+<span class="line"><span>[data-pyric-query-add-condition]</span></span>
+<span class="line"><span>[data-pyric-query-modifiers]</span></span>
+<span class="line"><span>[data-pyric-query-orderby]</span></span>
+<span class="line"><span>[data-pyric-query-orderby-field]</span></span>
+<span class="line"><span>[data-pyric-query-orderby-direction]</span></span>
+<span class="line"><span>[data-pyric-query-limit]</span></span>
+<span class="line"><span>[data-pyric-query-limit-input]</span></span></code></pre>
+<h2 id="notes">Notes</h2>
+<ul>
+<li><strong>Empty-field conditions are dropped</strong> silently in <code>buildQuery</code>. The UI lets users add a row and fill it in over multiple keystrokes; passing a <code>where('', '==', '')</code> to Firestore would throw.</li>
+<li><strong><code>limit: 0</code></strong> is treated as “no limit” (same as <code>undefined</code>). Firestore rejects <code>limit(0)</code> outright.</li>
+<li><strong>The hook is stable.</strong> Calling <code>addCondition</code> / <code>updateCondition</code> etc. returns identity-stable callbacks; including the hook return value as an effect dep is safe.</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="#example">Example</a> </li><li data-depth="2"> <a href="#props">Props</a> </li><li data-depth="2"> <a href="#value-parsing">Value parsing</a> </li><li data-depth="2"> <a href="#direct-hook-access">Direct hook access</a> </li><li data-depth="2"> <a href="#whats-not-in-v1">What’s not in v1</a> </li><li data-depth="2"> <a href="#styling-hooks">Styling hooks</a> </li><li data-depth="2"> <a href="#notes">Notes</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/ui-firestore-querybuilder.md ADDED Viewed

@@ -0,0 +1,103 @@
+# `<QueryBuilder>`
+Single-level where/orderBy/limit query builder. Composes state into a real Firestore `Query` via the hook's `buildQuery(base)`.
+```ts
+import { QueryBuilder } from '@pyric/ui/firestore';
+```
+## Example
+```tsx
+import { useState } from 'react';
+import { collection } from 'pyric/firestore';
+import { QueryBuilder, useDocumentList, type UseQueryBuilderResult } from '@pyric/ui/firestore';
+function FilteredDocs({ firestore }) {
+  const [builder, setBuilder] = useState<UseQueryBuilderResult | null>(null);
+  const base = collection(firestore, 'users');
+  const query = builder?.buildQuery(base);
+  const { documents } = useDocumentList({ collection: base, query });
+  return (
+    <>
+      <QueryBuilder
+        initial={{
+          conditions: [{ id: 'c1', field: 'active', op: '==', value: true }],
+          orderBy: { field: 'score', direction: 'desc' },
+          limit: 20,
+        }}
+        onChange={setBuilder}
+      />
+      <DocumentList documents={documents} />
+    </>
+  );
+}
+```
+## Props
+| Prop | Type | Description |
+|---|---|---|
+| `initial` | `Partial<QueryBuilderState>` | Pre-populate conditions, orderBy, limit. |
+| `onChange` | `(builder: UseQueryBuilderResult) => void` | Fires on every state change. Capture this to call `buildQuery`. |
+| `className` | `string` | Forwarded to the root. |
+## Value parsing
+The value input is JSON-parsed on every change. So:
+- `42` → number
+- `"text"` → string
+- `true` / `false` / `null` → those primitives
+- `[1, 2, 3]` → array (for `in` / `not-in` / `array-contains-any` ops)
+- Anything that doesn't parse as JSON → falls through as a raw string
+For non-JSON Firestore values (Timestamp, GeoPoint, Reference, Bytes), the bundled component isn't enough — use `useQueryBuilder` directly with your own value editor.
+## Direct hook access
+```tsx
+import {
+  useQueryBuilder,
+  QUERY_OPS,
+  MULTI_VALUE_OPS,
+} from '@pyric/ui/firestore/hooks';
+const builder = useQueryBuilder({ initial: { conditions: [...] } });
+// {
+//   conditions, orderBy, limit,
+//   addCondition, updateCondition, removeCondition,
+//   setOrderBy, setLimit, reset, buildQuery,
+// }
+```
+## What's not in v1
+- **Compound `and()` / `or()` groups.** Single-level only — every condition is implicitly AND-joined. Compound groups deferred.
+- **Cursor-based pagination (`startAfter`).** Use `useDocumentList` with the composed query — pagination is its job.
+## Styling hooks
+```
+[data-pyric-ui="query-builder"]
+[data-pyric-query-conditions]
+[data-pyric-query-condition]
+[data-pyric-query-field]
+[data-pyric-query-op]
+[data-pyric-query-value]
+[data-pyric-query-remove]
+[data-pyric-query-add-condition]
+[data-pyric-query-modifiers]
+[data-pyric-query-orderby]
+[data-pyric-query-orderby-field]
+[data-pyric-query-orderby-direction]
+[data-pyric-query-limit]
+[data-pyric-query-limit-input]
+```
+## Notes
+- **Empty-field conditions are dropped** silently in `buildQuery`. The UI lets users add a row and fill it in over multiple keystrokes; passing a `where('', '==', '')` to Firestore would throw.
+- **`limit: 0`** is treated as "no limit" (same as `undefined`). Firestore rejects `limit(0)` outright.
+- **The hook is stable.** Calling `addCondition` / `updateCondition` etc. returns identity-stable callbacks; including the hook return value as an effect dep is safe.

package/dist/serve/docs-ui/docs/ui-firestore-referencepicker/index.html ADDED Viewed

@@ -0,0 +1,113 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>&lt;ReferencePicker&gt; · 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/"> 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/" aria-current="true"> @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/"> 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/" aria-current="true"> @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/ui/">@pyric/ui</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Firestore</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">&lt;ReferencePicker&gt;</span> </li> </ol> </nav>  <article class="prose">  <h1 id="referencepicker"><code>&#x3C;ReferencePicker></code></h1>
+<p>Pick a <code>DocumentReference</code> by typing a path OR by browsing the tree. Improvement over firebase-tools-ui’s plain text input.</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">ReferencePicker</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/ui/firestore'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<h2 id="example">Example</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="tsx"><code><span class="line"><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">ReferencePicker</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">  firestore</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E06C75">fs</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">  listCollections</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E06C75">mySchemaAwareLister</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">  initialPath</span><span style="color:#56B6C2">=</span><span style="color:#98C379">"users/alice"</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">  onPick</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">ref</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">    // Commit the picked ref into wherever you need it — typically</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">    // a useDocumentEditor field.</span></span>
+<span class="line"><span style="color:#E5C07B">    editor</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">setValue</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">nodeId</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">ref</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">  }</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#ABB2BF">/></span></span></code></pre>
+<h2 id="props">Props</h2>
+<div class="table-scroll">
+<table><thead><tr><th>Prop</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>firestore</code></td><td><code>Firestore</code></td><td>yes</td><td>Backend handle. Used to parse the path input via <code>doc(firestore, path)</code>.</td></tr><tr><td><code>listCollections</code></td><td><code>(firestore, parent: DocumentReference | null) => Promise&#x3C;CollectionReference[]></code></td><td>yes</td><td>Injected lister. See <code>CollectionList.md</code> for the three plausible implementations.</td></tr><tr><td><code>initialPath</code></td><td><code>string</code></td><td>no</td><td>Pre-populates the text input.</td></tr><tr><td><code>onPick</code></td><td><code>(ref: DocumentReference) => void</code></td><td>no</td><td>Fired when the user commits via the button OR clicks a doc in the browse panel.</td></tr><tr><td><code>pathLabel</code></td><td><code>string</code></td><td>no</td><td>Label on the path input. Default <code>'Document path'</code>.</td></tr><tr><td><code>className</code></td><td><code>string</code></td><td>no</td><td>Forwarded to the root.</td></tr></tbody></table></div>
+<h2 id="two-ways-to-commit">Two ways to commit</h2>
+<ol>
+<li><strong>Type + Commit.</strong> The path input parses on every keystroke; the Commit button is enabled only when the path resolves to a valid <code>DocumentReference</code>. Click Commit → <code>onPick(ref)</code> fires.</li>
+<li><strong>Browse + Click.</strong> Toggle the Browse panel; drill into collections via the row buttons, then click a document. <code>onPick(ref)</code> fires immediately.</li>
+</ol>
+<p>Either way, the text input updates to reflect the committed path so the two paths stay in sync.</p>
+<h2 id="browse-panel-mechanics">Browse panel mechanics</h2>
+<ul>
+<li><strong>Root level</strong> — shows collections from <code>listCollections(firestore, null)</code>.</li>
+<li><strong>Collection level</strong> — fetches the first page (<code>pageSize</code> default 20) via <code>getDocs(query(coll, limit(20)))</code>. Each row has a Pick button (commit) and a Drill button (descend into that doc’s subcollections).</li>
+<li><strong>Document level</strong> — shows that doc’s subcollections via <code>listCollections(firestore, ref)</code>.</li>
+<li><strong>Back</strong> — pops the navigation history. Disabled at root.</li>
+</ul>
+<h2 id="direct-hook-access">Direct hook access</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="tsx"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">useReferencePicker</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/ui/firestore/hooks'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> picker</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> useReferencePicker</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">firestore</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">listCollections</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// {</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">//   pathInput, reference, error,</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">//   browseLocation, canDrillBack, collections, documents, isLoading,</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">//   setPathInput, pick, drillIntoCollection, drillIntoDocument,</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">//   drillBack, clear,</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// }</span></span></code></pre>
+<p>Use the hook directly for custom layouts (popover trigger inside another component, etc).</p>
+<h2 id="styling-hooks">Styling hooks</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="plaintext"><code><span class="line"><span>[data-pyric-ui="reference-picker"]</span></span>
+<span class="line"><span>[data-pyric-reference-path-label]</span></span>
+<span class="line"><span>[data-pyric-reference-path-input]</span></span>
+<span class="line"><span>[data-pyric-reference-path-input][aria-invalid="true"]</span></span>
+<span class="line"><span>[data-pyric-reference-actions]</span></span>
+<span class="line"><span>[data-pyric-reference-browse-toggle]</span></span>
+<span class="line"><span>[data-pyric-reference-commit]</span></span>
+<span class="line"><span>[data-pyric-reference-commit][disabled]</span></span>
+<span class="line"><span>[data-pyric-ui="reference-browse-panel"]</span></span>
+<span class="line"><span>[data-pyric-ui="reference-browse-panel"][data-pyric-loading]</span></span>
+<span class="line"><span>[data-pyric-browse-header]</span></span>
+<span class="line"><span>[data-pyric-browse-back]</span></span>
+<span class="line"><span>[data-pyric-browse-location]</span></span>
+<span class="line"><span>[data-pyric-browse-collections]</span></span>
+<span class="line"><span>[data-pyric-browse-documents]</span></span>
+<span class="line"><span>[data-pyric-browse-entry][data-pyric-entry-kind="collection|document"]</span></span>
+<span class="line"><span>[data-pyric-browse-select]</span></span>
+<span class="line"><span>[data-pyric-browse-pick]</span></span>
+<span class="line"><span>[data-pyric-browse-drill]</span></span></code></pre>
+<h2 id="notes">Notes</h2>
+<ul>
+<li><strong>Path validation</strong> uses <code>doc(firestore, path)</code> wrapped in try/catch. Empty paths are valid (no commit available). Paths with an odd number of segments fail with <code>"Must point to a document (even segment count)"</code>.</li>
+<li><strong><code>listCollections</code> is ref-stabilized internally.</strong> You can pass an inline arrow function on every render — the hook stores the latest closure in a ref so the fetch effect’s deps don’t churn.</li>
+<li><strong>Pre-release.</strong> No popover / modal chrome; the component renders inline. Wrap in your own popover for a tighter UX. A bundled <code>&#x3C;ReferencePopover></code> may land in a later milestone.</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="#example">Example</a> </li><li data-depth="2"> <a href="#props">Props</a> </li><li data-depth="2"> <a href="#two-ways-to-commit">Two ways to commit</a> </li><li data-depth="2"> <a href="#browse-panel-mechanics">Browse panel mechanics</a> </li><li data-depth="2"> <a href="#direct-hook-access">Direct hook access</a> </li><li data-depth="2"> <a href="#styling-hooks">Styling hooks</a> </li><li data-depth="2"> <a href="#notes">Notes</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/ui-firestore-referencepicker.md ADDED Viewed

@@ -0,0 +1,93 @@
+# `<ReferencePicker>`
+Pick a `DocumentReference` by typing a path OR by browsing the tree. Improvement over firebase-tools-ui's plain text input.
+```ts
+import { ReferencePicker } from '@pyric/ui/firestore';
+```
+## Example
+```tsx
+<ReferencePicker
+  firestore={fs}
+  listCollections={mySchemaAwareLister}
+  initialPath="users/alice"
+  onPick={(ref) => {
+    // Commit the picked ref into wherever you need it — typically
+    // a useDocumentEditor field.
+    editor.setValue(nodeId, ref);
+  }}
+/>
+```
+## Props
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `firestore` | `Firestore` | yes | Backend handle. Used to parse the path input via `doc(firestore, path)`. |
+| `listCollections` | `(firestore, parent: DocumentReference \| null) => Promise<CollectionReference[]>` | yes | Injected lister. See `CollectionList.md` for the three plausible implementations. |
+| `initialPath` | `string` | no | Pre-populates the text input. |
+| `onPick` | `(ref: DocumentReference) => void` | no | Fired when the user commits via the button OR clicks a doc in the browse panel. |
+| `pathLabel` | `string` | no | Label on the path input. Default `'Document path'`. |
+| `className` | `string` | no | Forwarded to the root. |
+## Two ways to commit
+1. **Type + Commit.** The path input parses on every keystroke; the Commit button is enabled only when the path resolves to a valid `DocumentReference`. Click Commit → `onPick(ref)` fires.
+2. **Browse + Click.** Toggle the Browse panel; drill into collections via the row buttons, then click a document. `onPick(ref)` fires immediately.
+Either way, the text input updates to reflect the committed path so the two paths stay in sync.
+## Browse panel mechanics
+- **Root level** — shows collections from `listCollections(firestore, null)`.
+- **Collection level** — fetches the first page (`pageSize` default 20) via `getDocs(query(coll, limit(20)))`. Each row has a Pick button (commit) and a Drill button (descend into that doc's subcollections).
+- **Document level** — shows that doc's subcollections via `listCollections(firestore, ref)`.
+- **Back** — pops the navigation history. Disabled at root.
+## Direct hook access
+```tsx
+import { useReferencePicker } from '@pyric/ui/firestore/hooks';
+const picker = useReferencePicker({ firestore, listCollections });
+// {
+//   pathInput, reference, error,
+//   browseLocation, canDrillBack, collections, documents, isLoading,
+//   setPathInput, pick, drillIntoCollection, drillIntoDocument,
+//   drillBack, clear,
+// }
+```
+Use the hook directly for custom layouts (popover trigger inside another component, etc).
+## Styling hooks
+```
+[data-pyric-ui="reference-picker"]
+[data-pyric-reference-path-label]
+[data-pyric-reference-path-input]
+[data-pyric-reference-path-input][aria-invalid="true"]
+[data-pyric-reference-actions]
+[data-pyric-reference-browse-toggle]
+[data-pyric-reference-commit]
+[data-pyric-reference-commit][disabled]
+[data-pyric-ui="reference-browse-panel"]
+[data-pyric-ui="reference-browse-panel"][data-pyric-loading]
+[data-pyric-browse-header]
+[data-pyric-browse-back]
+[data-pyric-browse-location]
+[data-pyric-browse-collections]
+[data-pyric-browse-documents]
+[data-pyric-browse-entry][data-pyric-entry-kind="collection|document"]
+[data-pyric-browse-select]
+[data-pyric-browse-pick]
+[data-pyric-browse-drill]
+```
+## Notes
+- **Path validation** uses `doc(firestore, path)` wrapped in try/catch. Empty paths are valid (no commit available). Paths with an odd number of segments fail with `"Must point to a document (even segment count)"`.
+- **`listCollections` is ref-stabilized internally.** You can pass an inline arrow function on every render — the hook stores the latest closure in a ref so the fetch effect's deps don't churn.
+- **Pre-release.** No popover / modal chrome; the component renders inline. Wrap in your own popover for a tighter UX. A bundled `<ReferencePopover>` may land in a later milestone.