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-storage-uploaddropzone/index.html ADDED Viewed

@@ -0,0 +1,93 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>&lt;UploadDropzone&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>Storage</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">&lt;UploadDropzone&gt;</span> </li> </ol> </nav>  <article class="prose">  <h1 id="uploaddropzone"><code>&#x3C;UploadDropzone></code></h1>
+<p>Headless drop target for file <strong>and folder</strong> uploads. Slot-based — the children render the chrome; the component owns the drag wiring, flattens the drop (folders traverse recursively via <code>webkitGetAsEntry</code>), and emits <code>DroppedFile { file, relativePath }[]</code> ready for <code>useObjectUpload</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">UploadDropzone</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/ui/storage'</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">useObjectUpload</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">useStorageList</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">usePathState</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/ui/storage/hooks'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">function</span><span style="color:#61AFEF"> Uploader</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75;font-style:italic">storage</span><span style="color:#ABB2BF"> }) {</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> nav</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> usePathState</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> list</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> useStorageList</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">storage</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">nav</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">path</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">upload</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">tasks</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">isUploading</span><span style="color:#ABB2BF"> } </span><span style="color:#56B6C2">=</span><span style="color:#61AFEF"> useObjectUpload</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">storage</span><span style="color:#ABB2BF">, {</span></span>
+<span class="line"><span style="color:#E06C75">    path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">nav</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">path</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    list</span><span style="color:#ABB2BF">, </span><span style="color:#7F848E;font-style:italic">// optimistic insert + rollback</span></span>
+<span class="line"><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 style="color:#E5C07B">UploadDropzone</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">      onFiles</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">files</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span></span>
+<span class="line"><span style="color:#61AFEF">        upload</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">files</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">map</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">f</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> ({ </span><span style="color:#E06C75">path</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">f</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">relativePath</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">data</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">f</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">file</span><span style="color:#ABB2BF"> })))</span></span>
+<span class="line"><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:#E06C75">p</span><span style="color:#ABB2BF">></span><span style="color:#C678DD">{</span><span style="color:#E06C75">isUploading</span><span style="color:#C678DD"> ?</span><span style="color:#98C379"> `Uploading </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">tasks</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">length</span><span style="color:#C678DD">}</span><span style="color:#98C379">…`</span><span style="color:#C678DD"> :</span><span style="color:#98C379"> 'Drop files or folders here'</span><span style="color:#C678DD">}</span><span style="color:#ABB2BF">&#x3C;/</span><span style="color:#E06C75">p</span><span style="color:#ABB2BF">></span></span>
+<span class="line"><span style="color:#C678DD">      {</span><span style="color:#7F848E;font-style:italic">/* click-to-browse lives in the slot: */</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#ABB2BF">      &#x3C;</span><span style="color:#E06C75">input</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">        type</span><span style="color:#56B6C2">=</span><span style="color:#98C379">"file"</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">        multiple</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:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">e</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#61AFEF"> upload</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">Array</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">from</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">e</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">target</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">files</span><span style="color:#56B6C2"> ??</span><span style="color:#ABB2BF"> []))</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">UploadDropzone</span><span style="color:#ABB2BF">></span></span>
+<span class="line"><span style="color:#ABB2BF">  );</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<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>onFiles</code></td><td><code>(files: DroppedFile[]) => void</code></td><td>Fired once per drop with the flattened list. <code>relativePath</code> keeps dropped-folder structure (<code>photos/cat.png</code>). Not fired for empty drops.</td></tr><tr><td><code>children</code></td><td><code>ReactNode</code></td><td>The chrome slot (copy, browse input, task list, …).</td></tr><tr><td><code>disabled</code></td><td><code>boolean</code></td><td>Ignore drops + suppress the dragging state.</td></tr><tr><td><code>disabledReason</code></td><td><code>string</code></td><td>Why — stamped on <code>data-disabled-reason</code> (only while <code>disabled</code>, alongside <code>aria-disabled</code>). Canonical source is the rules gate: <code>disabled={!gate.verdictFor(path).upload}</code> + <code>disabledReason={verdict.reasons.write.join('; ')}</code> — see <a href="../ui-storage-rules-aware-affordances/">rules-aware affordances</a>.</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="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="upload-dropzone"]                 /* root */</span></span>
+<span class="line"><span>[data-pyric-ui="upload-dropzone"][data-dragging]  /* a drag is hovering */</span></span>
+<span class="line"><span>[data-pyric-ui="upload-dropzone"][data-disabled]</span></span>
+<span class="line"><span>[data-pyric-ui="upload-dropzone"][data-disabled-reason]  /* why (rules gate) */</span></span></code></pre>
+<h2 id="notes">Notes</h2>
+<ul>
+<li><strong>Folder drops</strong> traverse the <code>webkitGetAsEntry</code> tree (batched
+<code>readEntries</code>, so >100-child folders work). Browsers only expose folder
+structure through this channel — items without it fall back to
+<code>getAsFile</code>, and a bare <code>DataTransfer</code> falls back to <code>files</code>.</li>
+<li><strong>Empty folders yield nothing.</strong> A dropped empty directory produces no
+files; wire <code>useObjectUpload.createFolder</code> to your own “new folder”
+affordance instead (it writes the zero-byte <code>&#x3C;path>/</code> placeholder, hidden
+from <code>items</code>).</li>
+<li><strong><code>data-dragging</code> doesn’t flicker</strong> when the drag crosses child elements —
+an enter/leave depth counter handles the pairing.</li>
+<li><strong>No built-in browse input</strong> — render your own in the slot (see the
+example) and pass the <code>FileList</code> straight to <code>upload()</code>.</li>
+</ul>
+<h2 id="see-also">See also</h2>
+<ul>
+<li><code>useObjectUpload</code> — the task-shaped upload hook this feeds.</li>
+<li><a href="../ui-storage-objectbrowser/"><code>&#x3C;ObjectBrowser></code></a> — typically rendered inside the
+dropzone so the whole table is a drop target.</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="#styling-hooks">Styling hooks</a> </li><li data-depth="2"> <a href="#notes">Notes</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/ui-storage-uploaddropzone.md ADDED Viewed

@@ -0,0 +1,78 @@
+# `<UploadDropzone>`
+Headless drop target for file **and folder** uploads. Slot-based — the children render the chrome; the component owns the drag wiring, flattens the drop (folders traverse recursively via `webkitGetAsEntry`), and emits `DroppedFile { file, relativePath }[]` ready for `useObjectUpload`.
+```ts
+import { UploadDropzone } from '@pyric/ui/storage';
+```
+## Example
+```tsx
+import { useObjectUpload, useStorageList, usePathState } from '@pyric/ui/storage/hooks';
+function Uploader({ storage }) {
+  const nav = usePathState();
+  const list = useStorageList(storage, nav.path);
+  const { upload, tasks, isUploading } = useObjectUpload(storage, {
+    path: nav.path,
+    list, // optimistic insert + rollback
+  });
+  return (
+    <UploadDropzone
+      onFiles={(files) =>
+        upload(files.map((f) => ({ path: f.relativePath, data: f.file })))
+      }
+    >
+      <p>{isUploading ? `Uploading ${tasks.length}…` : 'Drop files or folders here'}</p>
+      {/* click-to-browse lives in the slot: */}
+      <input
+        type="file"
+        multiple
+        onChange={(e) => upload(Array.from(e.target.files ?? []))}
+      />
+    </UploadDropzone>
+  );
+}
+```
+## Props
+| Prop | Type | Description |
+|---|---|---|
+| `onFiles` | `(files: DroppedFile[]) => void` | Fired once per drop with the flattened list. `relativePath` keeps dropped-folder structure (`photos/cat.png`). Not fired for empty drops. |
+| `children` | `ReactNode` | The chrome slot (copy, browse input, task list, …). |
+| `disabled` | `boolean` | Ignore drops + suppress the dragging state. |
+| `disabledReason` | `string` | Why — stamped on `data-disabled-reason` (only while `disabled`, alongside `aria-disabled`). Canonical source is the rules gate: `disabled={!gate.verdictFor(path).upload}` + `disabledReason={verdict.reasons.write.join('; ')}` — see [rules-aware affordances](../ui-storage-rules-aware-affordances/). |
+| `className` | `string` | Forwarded to the root. |
+## Styling hooks
+```
+[data-pyric-ui="upload-dropzone"]                 /* root */
+[data-pyric-ui="upload-dropzone"][data-dragging]  /* a drag is hovering */
+[data-pyric-ui="upload-dropzone"][data-disabled]
+[data-pyric-ui="upload-dropzone"][data-disabled-reason]  /* why (rules gate) */
+```
+## Notes
+- **Folder drops** traverse the `webkitGetAsEntry` tree (batched
+  `readEntries`, so >100-child folders work). Browsers only expose folder
+  structure through this channel — items without it fall back to
+  `getAsFile`, and a bare `DataTransfer` falls back to `files`.
+- **Empty folders yield nothing.** A dropped empty directory produces no
+  files; wire `useObjectUpload.createFolder` to your own "new folder"
+  affordance instead (it writes the zero-byte `<path>/` placeholder, hidden
+  from `items`).
+- **`data-dragging` doesn't flicker** when the drag crosses child elements —
+  an enter/leave depth counter handles the pairing.
+- **No built-in browse input** — render your own in the slot (see the
+  example) and pass the `FileList` straight to `upload()`.
+## See also
+- `useObjectUpload` — the task-shaped upload hook this feeds.
+- [`<ObjectBrowser>`](../ui-storage-objectbrowser/) — typically rendered inside the
+  dropzone so the whole table is a drop target.

package/dist/serve/docs-ui/docs/ui-storage-usestoragerulesgate/index.html ADDED Viewed

@@ -0,0 +1,144 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>useStorageRulesGate · 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>Storage</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">useStorageRulesGate</span> </li> </ol> </nav>  <article class="prose">  <h1 id="usestoragerulesgate"><code>useStorageRulesGate</code></h1>
+<p>Pre-flight rules evaluation — evaluate the current identity against storage paths <strong>before the click</strong>, so the UI can mark denied affordances (<code>data-pyric-denied</code> rows, disabled-with-reason buttons) instead of letting the user discover a denial through a thrown <code>storage/unauthorized</code>. Built on the pure evaluator exports from <code>pyric/storage</code> (<code>parseStorageRules</code> + <code>evaluateStorageRules</code>) — the same evaluator the sandbox enforces with.</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">useStorageRulesGate</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/ui/storage/hooks'</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">function</span><span style="color:#61AFEF"> GatedAdmin</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75;font-style:italic">storage</span><span style="color:#ABB2BF"> }) {</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> nav</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> usePathState</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> list</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> useStorageList</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">storage</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">nav</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">path</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> selection</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> useStorageSelection</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> gate</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> useStorageRulesGate</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">storage</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> pathVerdict</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> gate</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">verdictFor</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">nav</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">path</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">UploadDropzone</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">        disabled</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#56B6C2">!</span><span style="color:#E5C07B">pathVerdict</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">upload</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">        disabledReason</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E5C07B">pathVerdict</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">reasons</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">write</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">join</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'; '</span><span style="color:#ABB2BF">)</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">        onFiles</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#7F848E;font-style:italic">/* … */</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">ObjectBrowser</span><span style="color:#D19A66;font-style:italic"> entries</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E5C07B">list</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">entries</span><span style="color:#C678DD">}</span><span style="color:#D19A66;font-style:italic"> gate</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E06C75">gate</span><span style="color:#C678DD">}</span><span style="color:#7F848E;font-style:italic"> /* … */</span><span style="color:#ABB2BF"> /></span></span>
+<span class="line"><span style="color:#ABB2BF">      &#x3C;/</span><span style="color:#E5C07B">UploadDropzone</span><span style="color:#ABB2BF">></span></span>
+<span class="line"><span style="color:#ABB2BF">      &#x3C;</span><span style="color:#E5C07B">DeleteSelectionWithConfirm</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">        storage</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E06C75">storage</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">        entries</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E5C07B">selection</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">selected</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">        gate</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E06C75">gate</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>
+<span class="line"><span style="color:#ABB2BF">  );</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<h2 id="signature">Signature</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#61AFEF">useStorageRulesGate</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">storage</span><span style="color:#ABB2BF">, {</span></span>
+<span class="line"><span style="color:#ABB2BF">  paths?, rules?, identity?, writeResource?,</span></span>
+<span class="line"><span style="color:#ABB2BF">}): {</span></span>
+<span class="line"><span style="color:#E06C75">  status</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">advisory</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">identity</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">verdicts</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">verdictFor</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">error</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<h3 id="options">Options</h3>
+<div class="table-scroll">
+<table><thead><tr><th>Option</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>paths</code></td><td><code>string | readonly string[]</code></td><td>Paths pre-evaluated into <code>verdicts</code> (keyed by normalized path). Ad-hoc paths go through <code>verdictFor</code> — same evaluation.</td></tr><tr><td><code>rules</code></td><td><code>string | StorageRules</code></td><td>Explicit rules source — raw text (parsed here; malformed → <code>status: 'error'</code>) or pre-parsed. Overrides the sandbox’s deployed ruleset.</td></tr><tr><td><code>identity</code></td><td><code>StorageAuth | null</code></td><td>Identity override. <code>null</code> = anonymous; <strong>omit</strong> to use the handle’s own identity (the sandbox context’s <code>auth</code>).</td></tr><tr><td><code>writeResource</code></td><td><code>{ size: number; contentType?: string }</code></td><td>Bound as <code>request.resource</code> for the WRITE evaluation — pass it when gating a specific upload so size/contentType-conditioned rules evaluate truthfully. Omitted = delete semantics (no inbound payload).</td></tr></tbody></table></div>
+<h3 id="result">Result</h3>
+<div class="table-scroll">
+<table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>status</code></td><td><code>'idle' | 'loading' | 'ready' | 'error'</code></td><td><code>'idle'</code> only when <code>storage</code> is null. Sandbox rules resolve async (one await).</td></tr><tr><td><code>source</code></td><td><code>'option' | 'sandbox' | 'none'</code></td><td>Where the active ruleset came from. <code>'none'</code> = nothing reachable — everything allows (open-by-default, matching <code>pyric/storage</code> enforcement).</td></tr><tr><td><code>advisory</code></td><td><code>boolean</code></td><td>Always <code>false</code>; <code>pyric/storage</code> handles are sandbox mirrors.</td></tr><tr><td><code>identity</code></td><td><code>StorageAuth | null</code></td><td>The identity verdicts evaluate under.</td></tr><tr><td><code>verdicts</code></td><td><code>Record&#x3C;string, StorageGateVerdict></code></td><td>Pre-evaluated verdicts for <code>paths</code>.</td></tr><tr><td><code>verdictFor</code></td><td><code>(path: string) => StorageGateVerdict</code></td><td>Evaluate any path — pure + synchronous once ready.</td></tr><tr><td><code>error</code></td><td><code>Error | undefined</code></td><td>Rules-resolution failure (e.g. malformed <code>rules</code> text).</td></tr></tbody></table></div>
+<p><code>StorageGateVerdict</code> is <code>{ read, write, delete, upload, reasons }</code> —
+<code>delete</code> and <code>upload</code> are <strong>derived aliases of <code>write</code></strong> (the rules subset
+has exactly two verbs; Firebase Storage’s <code>write</code> governs
+create/overwrite/delete). <code>reasons.read</code> / <code>reasons.write</code> carry the
+evaluator’s trace for denied verbs (<code>"match /users/{uid}/… : condition false"</code>), ready for tooltips.</p>
+<h2 id="where-rules-and-identity-come-from">Where rules and identity come from</h2>
+<ul>
+<li><strong>Sandbox handle</strong> — both are on the handle: the ruleset
+<code>getStorageSandbox(ctx, { rules })</code> parsed at config time, and the
+context’s <code>auth</code>. Pass nothing; verdicts are <strong>truthful</strong> (same
+evaluator, same bindings as enforcement).</li>
+</ul>
+<p>Production applications select <code>firebase/storage</code> through package
+resolution, so this Pyric-only hook is not present in production bundles.</p>
+<h2 id="evaluation-contract">Evaluation contract</h2>
+<ul>
+<li><code>resource</code> (the existing object) binds <code>null</code> — the gate doesn’t fetch
+per-path metadata, mirroring how the sandbox enforces <code>listAll</code>. Rules
+over <code>resource.*</code> evaluate as if the object doesn’t exist.</li>
+<li>The gate <strong>fails open</strong>: idle/loading/error and rules-less states return
+the allow-all verdict. Affordances only ever add warnings; enforcement
+stays real.</li>
+</ul>
+<h2 id="see-also">See also</h2>
+<ul>
+<li><a href="../ui-storage-rules-aware-affordances/">Rules-aware affordances</a> — the concept
+note: which component consumes which verdict.</li>
+<li>the design rationale — the
+request/denial <em>stream</em> (traffic panel) spec, blocked on a
+<code>pyric/storage</code> event channel.</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="#signature">Signature</a> </li><li data-depth="3"> <a href="#options">Options</a> </li><li data-depth="3"> <a href="#result">Result</a> </li><li data-depth="2"> <a href="#where-rules-and-identity-come-from">Where rules and identity come from</a> </li><li data-depth="2"> <a href="#evaluation-contract">Evaluation contract</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/ui-storage-usestoragerulesgate.md ADDED Viewed

@@ -0,0 +1,101 @@
+# `useStorageRulesGate`
+Pre-flight rules evaluation — evaluate the current identity against storage paths **before the click**, so the UI can mark denied affordances (`data-pyric-denied` rows, disabled-with-reason buttons) instead of letting the user discover a denial through a thrown `storage/unauthorized`. Built on the pure evaluator exports from `pyric/storage` (`parseStorageRules` + `evaluateStorageRules`) — the same evaluator the sandbox enforces with.
+```ts
+import { useStorageRulesGate } from '@pyric/ui/storage/hooks';
+```
+## Example
+```tsx
+function GatedAdmin({ storage }) {
+  const nav = usePathState();
+  const list = useStorageList(storage, nav.path);
+  const selection = useStorageSelection();
+  const gate = useStorageRulesGate(storage);
+  const pathVerdict = gate.verdictFor(nav.path);
+  return (
+    <>
+      <UploadDropzone
+        disabled={!pathVerdict.upload}
+        disabledReason={pathVerdict.reasons.write.join('; ')}
+        onFiles={/* … */}
+      >
+        <ObjectBrowser entries={list.entries} gate={gate} /* … */ />
+      </UploadDropzone>
+      <DeleteSelectionWithConfirm
+        storage={storage}
+        entries={selection.selected}
+        gate={gate}
+      />
+    </>
+  );
+}
+```
+## Signature
+```ts
+useStorageRulesGate(storage, {
+  paths?, rules?, identity?, writeResource?,
+}): {
+  status, source, advisory, identity, verdicts, verdictFor, error,
+}
+```
+### Options
+| Option | Type | Description |
+|---|---|---|
+| `paths` | `string \| readonly string[]` | Paths pre-evaluated into `verdicts` (keyed by normalized path). Ad-hoc paths go through `verdictFor` — same evaluation. |
+| `rules` | `string \| StorageRules` | Explicit rules source — raw text (parsed here; malformed → `status: 'error'`) or pre-parsed. Overrides the sandbox's deployed ruleset. |
+| `identity` | `StorageAuth \| null` | Identity override. `null` = anonymous; **omit** to use the handle's own identity (the sandbox context's `auth`). |
+| `writeResource` | `{ size: number; contentType?: string }` | Bound as `request.resource` for the WRITE evaluation — pass it when gating a specific upload so size/contentType-conditioned rules evaluate truthfully. Omitted = delete semantics (no inbound payload). |
+### Result
+| Field | Type | Description |
+|---|---|---|
+| `status` | `'idle' \| 'loading' \| 'ready' \| 'error'` | `'idle'` only when `storage` is null. Sandbox rules resolve async (one await). |
+| `source` | `'option' \| 'sandbox' \| 'none'` | Where the active ruleset came from. `'none'` = nothing reachable — everything allows (open-by-default, matching `pyric/storage` enforcement). |
+| `advisory` | `boolean` | Always `false`; `pyric/storage` handles are sandbox mirrors. |
+| `identity` | `StorageAuth \| null` | The identity verdicts evaluate under. |
+| `verdicts` | `Record<string, StorageGateVerdict>` | Pre-evaluated verdicts for `paths`. |
+| `verdictFor` | `(path: string) => StorageGateVerdict` | Evaluate any path — pure + synchronous once ready. |
+| `error` | `Error \| undefined` | Rules-resolution failure (e.g. malformed `rules` text). |
+`StorageGateVerdict` is `{ read, write, delete, upload, reasons }` —
+`delete` and `upload` are **derived aliases of `write`** (the rules subset
+has exactly two verbs; Firebase Storage's `write` governs
+create/overwrite/delete). `reasons.read` / `reasons.write` carry the
+evaluator's trace for denied verbs (`"match /users/{uid}/… : condition
+false"`), ready for tooltips.
+## Where rules and identity come from
+- **Sandbox handle** — both are on the handle: the ruleset
+  `getStorageSandbox(ctx, { rules })` parsed at config time, and the
+  context's `auth`. Pass nothing; verdicts are **truthful** (same
+  evaluator, same bindings as enforcement).
+Production applications select `firebase/storage` through package
+resolution, so this Pyric-only hook is not present in production bundles.
+## Evaluation contract
+- `resource` (the existing object) binds `null` — the gate doesn't fetch
+  per-path metadata, mirroring how the sandbox enforces `listAll`. Rules
+  over `resource.*` evaluate as if the object doesn't exist.
+- The gate **fails open**: idle/loading/error and rules-less states return
+  the allow-all verdict. Affordances only ever add warnings; enforcement
+  stays real.
+## See also
+- [Rules-aware affordances](../ui-storage-rules-aware-affordances/) — the concept
+  note: which component consumes which verdict.
+- the design rationale — the
+  request/denial *stream* (traffic panel) spec, blocked on a
+  `pyric/storage` event channel.