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-auth-authsigninhelper/index.html ADDED Viewed

@@ -0,0 +1,194 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>&lt;AuthSignInHelper&gt; + useAuthFlowHelper · 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>Auth</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">AuthSignInHelper</span> </li> </ol> </nav>  <article class="prose">  <h1 id="authsigninhelper--useauthflowhelper"><code>&#x3C;AuthSignInHelper></code> + <code>useAuthFlowHelper</code></h1>
+<p>Emulator-style sign-in helper for sandbox auth: when an app calls
+<code>signInWithPopup</code> / <code>signInWithRedirect</code> against a sandbox <code>Auth</code> handle, the
+flow parks on a helper request; this pair renders an account picker +
+add-account form and settles the app’s promise.</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">AuthSignInHelper</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">useAuthFlowHelper</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/ui/auth'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// hook-only entry:</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">useAuthFlowHelper</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/ui/auth/hooks'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>Sandbox-only: the underlying controller drives <code>pyric/auth</code>’s
+<code>sandbox.setAuthFlowResolver</code> seam, which throws <code>failed-precondition</code> on a
+prod-backed handle.</p>
+<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">getAuth</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/auth'</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">AuthSignInHelper</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">useAuthFlowHelper</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/ui/auth'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">function</span><span style="color:#61AFEF"> SignInHelper</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75;font-style:italic">sandbox</span><span style="color:#ABB2BF"> }) {</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> auth</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getAuth</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">sandbox</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">state</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">pick</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">add</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">cancel</span><span style="color:#ABB2BF"> } </span><span style="color:#56B6C2">=</span><span style="color:#61AFEF"> useAuthFlowHelper</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">auth</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  if</span><span style="color:#ABB2BF"> (</span><span style="color:#56B6C2">!</span><span style="color:#E5C07B">state</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">request</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">return</span><span style="color:#D19A66"> null</span><span style="color:#ABB2BF">; </span><span style="color:#7F848E;font-style:italic">// nothing in flight</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">MyModal</span><span style="color:#D19A66;font-style:italic"> open</span><span style="color:#D19A66;font-style:italic"> onClose</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E06C75">cancel</span><span style="color:#C678DD">}</span><span style="color:#ABB2BF">></span></span>
+<span class="line"><span style="color:#ABB2BF">      &#x3C;</span><span style="color:#E5C07B">AuthSignInHelper</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">        state</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E06C75">state</span><span style="color:#C678DD">}</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:#E06C75">pick</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">        onAdd</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E06C75">add</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">        onCancel</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E06C75">cancel</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">        description</span><span style="color:#56B6C2">=</span><span style="color:#98C379">"Pick a test account or add one."</span></span>
+<span class="line"><span style="color:#ABB2BF">      /></span></span>
+<span class="line"><span style="color:#ABB2BF">    &#x3C;/</span><span style="color:#E5C07B">MyModal</span><span style="color:#ABB2BF">></span></span>
+<span class="line"><span style="color:#ABB2BF">  );</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>The component is positioning-agnostic — wrap it in your own modal/panel.
+<code>onCancel</code> rejects the app’s promise with the faithful
+<code>auth/popup-closed-by-user</code>.</p>
+<h2 id="useauthflowhelperauth"><code>useAuthFlowHelper(auth)</code></h2>
+<p>Installs the resolver for the lifetime of the calling component (paired
+effect; StrictMode-safe; re-targets when the <code>auth</code> handle identity changes).</p>
+<div class="table-scroll">
+<table><thead><tr><th>Returns</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>state</code></td><td><code>HelperState</code></td><td><code>{ request, identities }</code> — the in-flight <code>AuthFlowRequest</code> (or <code>null</code>) + pickable sandbox identities.</td></tr><tr><td><code>pick</code></td><td><code>(uid: string) => void</code></td><td>Settle with an existing identity.</td></tr><tr><td><code>add</code></td><td><code>(spec: NewIdentitySpec) => void</code></td><td>Seed + sign in a new identity (<code>{email, displayName?, customClaims?}</code>).</td></tr><tr><td><code>cancel</code></td><td><code>() => void</code></td><td>Dismiss; rejects with <code>auth/popup-closed-by-user</code>.</td></tr></tbody></table></div>
+<p>Non-React hosts can use the exported <code>AuthFlowController</code> class directly
+(<code>install</code>/<code>uninstall</code>, <code>subscribe</code>/<code>snapshot</code>, <code>pick</code>/<code>add</code>/<code>cancel</code>).</p>
+<h2 id="authsigninhelper-props"><code>&#x3C;AuthSignInHelper></code> props</h2>
+<div class="table-scroll">
+<table><thead><tr><th>Prop</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>state</code></td><td><code>HelperState</code></td><td>From the hook. Renders <code>null</code> while <code>state.request</code> is null.</td></tr><tr><td><code>onPick</code></td><td><code>(uid: string) => void</code></td><td>Wire to the hook’s <code>pick</code>.</td></tr><tr><td><code>onAdd</code></td><td><code>(spec: NewIdentitySpec) => void</code></td><td>Wire to the hook’s <code>add</code>. Called with the validated form payload.</td></tr><tr><td><code>onCancel</code></td><td><code>() => void</code></td><td>Wire to the hook’s <code>cancel</code>.</td></tr><tr><td><code>renderAccount</code></td><td><code>(identity: SandboxIdentity) => ReactNode</code></td><td>Optional account-row content override (the row button + data attrs stay component-owned).</td></tr><tr><td><code>title</code></td><td><code>ReactNode</code></td><td>Heading override. Default <code>Sign in with &#x3C;provider label></code>.</td></tr><tr><td><code>description</code></td><td><code>ReactNode</code></td><td>Optional helper text under the title.</td></tr><tr><td><code>initialValues</code></td><td><code>{email?, displayName?, claims?}</code></td><td>Prefill for the add form (raw JSON text for <code>claims</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="claims-validation">Claims validation</h2>
+<p>The add form validates the claims textarea with the same checks and messages
+as the Firebase emulator UI: must be a JSON <strong>object</strong>, ≤ 1000 characters,
+and no reserved JWT keys (<code>sub</code>, <code>iss</code>, <code>exp</code>, …). Exposed for reuse:</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">validateSerializedClaims</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">FORBIDDEN_CUSTOM_CLAIMS</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/ui/auth'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<h2 id="provider-labels">Provider labels</h2>
+<p><code>providerLabel(providerId)</code> maps the emulator’s provider-id set to text
+(<code>'google.com'</code> → <code>Google</code>, falls back to the raw id). Hook icons or styling
+off <code>data-pyric-provider-id</code> instead — the library ships no assets.</p>
+<h2 id="styling-hooks">Styling hooks</h2>
+<div class="table-scroll">
+<table><thead><tr><th>Selector</th><th>Element</th></tr></thead><tbody><tr><td><code>[data-pyric-ui="auth-signin-helper"]</code></td><td>Root <code>&#x3C;section></code>; carries <code>data-pyric-provider-id</code> + <code>data-pyric-auth-type</code>.</td></tr><tr><td><code>[data-pyric-helper-title]</code> / <code>[data-pyric-helper-description]</code></td><td>Header text.</td></tr><tr><td><code>[data-pyric-account-list]</code> / <code>[data-pyric-account-entry]</code></td><td>Picker list / rows (<code>data-pyric-account-uid</code>, <code>data-pyric-provider-id</code>).</td></tr><tr><td><code>button[data-pyric-account-pick]</code></td><td>Row button. Default children: <code>[data-pyric-account-name]</code> + <code>[data-pyric-account-email]</code>.</td></tr><tr><td><code>form[data-pyric-add-account-form]</code></td><td>Add-account form.</td></tr><tr><td><code>[data-pyric-field="email" | "display-name" | "claims"]</code></td><td>Inputs. The claims textarea gains <code>data-pyric-claims-invalid</code> + <code>aria-invalid</code> on error.</td></tr><tr><td><code>[data-pyric-claims-error]</code></td><td><code>role="alert"</code> validation message.</td></tr><tr><td><code>button[data-pyric-cancel]</code> / <code>button[data-pyric-submit]</code></td><td>Actions. Submit is disabled while the email is empty.</td></tr></tbody></table></div>
+<h2 id="gotchas">Gotchas</h2>
+<ul>
+<li><strong>One flow at a time</strong> — a new <code>signInWithPopup</code> while one is parked
+cancels the stale request (rejects <code>auth/popup-closed-by-user</code>).</li>
+<li><strong>Tokens are host-synthesized</strong> (<code>sandbox-helper-&#x3C;uid></code>) until the sandbox
+backend grows <code>createSignInCredential</code> (tracked follow-up); claims still
+flow into rules evaluation via the seeded identity.</li>
+<li>A live consumer: the playground’s
+<code>PreviewAuthHelper</code>
+<ul>
+<li>its <code>global.css</code> skin.</li>
+</ul>
+</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="#useauthflowhelperauth">useAuthFlowHelper(auth)</a> </li><li data-depth="2"> <a href="#authsigninhelper-props">&lt;AuthSignInHelper&gt; props</a> </li><li data-depth="2"> <a href="#claims-validation">Claims validation</a> </li><li data-depth="2"> <a href="#provider-labels">Provider labels</a> </li><li data-depth="2"> <a href="#styling-hooks">Styling hooks</a> </li><li data-depth="2"> <a href="#gotchas">Gotchas</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-auth-authsigninhelper.md ADDED Viewed

@@ -0,0 +1,114 @@
+# `<AuthSignInHelper>` + `useAuthFlowHelper`
+Emulator-style sign-in helper for sandbox auth: when an app calls
+`signInWithPopup` / `signInWithRedirect` against a sandbox `Auth` handle, the
+flow parks on a helper request; this pair renders an account picker +
+add-account form and settles the app's promise.
+```ts
+import { AuthSignInHelper, useAuthFlowHelper } from '@pyric/ui/auth';
+// hook-only entry:
+import { useAuthFlowHelper } from '@pyric/ui/auth/hooks';
+```
+Sandbox-only: the underlying controller drives `pyric/auth`'s
+`sandbox.setAuthFlowResolver` seam, which throws `failed-precondition` on a
+prod-backed handle.
+## Example
+```tsx
+import { getAuth } from 'pyric/auth';
+import { AuthSignInHelper, useAuthFlowHelper } from '@pyric/ui/auth';
+function SignInHelper({ sandbox }) {
+  const auth = getAuth(sandbox);
+  const { state, pick, add, cancel } = useAuthFlowHelper(auth);
+  if (!state.request) return null; // nothing in flight
+  return (
+    <MyModal open onClose={cancel}>
+      <AuthSignInHelper
+        state={state}
+        onPick={pick}
+        onAdd={add}
+        onCancel={cancel}
+        description="Pick a test account or add one."
+      />
+    </MyModal>
+  );
+}
+```
+The component is positioning-agnostic — wrap it in your own modal/panel.
+`onCancel` rejects the app's promise with the faithful
+`auth/popup-closed-by-user`.
+## `useAuthFlowHelper(auth)`
+Installs the resolver for the lifetime of the calling component (paired
+effect; StrictMode-safe; re-targets when the `auth` handle identity changes).
+| Returns | Type | Description |
+|---|---|---|
+| `state` | `HelperState` | `{ request, identities }` — the in-flight `AuthFlowRequest` (or `null`) + pickable sandbox identities. |
+| `pick` | `(uid: string) => void` | Settle with an existing identity. |
+| `add` | `(spec: NewIdentitySpec) => void` | Seed + sign in a new identity (`{email, displayName?, customClaims?}`). |
+| `cancel` | `() => void` | Dismiss; rejects with `auth/popup-closed-by-user`. |
+Non-React hosts can use the exported `AuthFlowController` class directly
+(`install`/`uninstall`, `subscribe`/`snapshot`, `pick`/`add`/`cancel`).
+## `<AuthSignInHelper>` props
+| Prop | Type | Description |
+|---|---|---|
+| `state` | `HelperState` | From the hook. Renders `null` while `state.request` is null. |
+| `onPick` | `(uid: string) => void` | Wire to the hook's `pick`. |
+| `onAdd` | `(spec: NewIdentitySpec) => void` | Wire to the hook's `add`. Called with the validated form payload. |
+| `onCancel` | `() => void` | Wire to the hook's `cancel`. |
+| `renderAccount` | `(identity: SandboxIdentity) => ReactNode` | Optional account-row content override (the row button + data attrs stay component-owned). |
+| `title` | `ReactNode` | Heading override. Default `Sign in with <provider label>`. |
+| `description` | `ReactNode` | Optional helper text under the title. |
+| `initialValues` | `{email?, displayName?, claims?}` | Prefill for the add form (raw JSON text for `claims`). |
+| `className` | `string` | Forwarded to the root. |
+## Claims validation
+The add form validates the claims textarea with the same checks and messages
+as the Firebase emulator UI: must be a JSON **object**, ≤ 1000 characters,
+and no reserved JWT keys (`sub`, `iss`, `exp`, …). Exposed for reuse:
+```ts
+import { validateSerializedClaims, FORBIDDEN_CUSTOM_CLAIMS } from '@pyric/ui/auth';
+```
+## Provider labels
+`providerLabel(providerId)` maps the emulator's provider-id set to text
+(`'google.com'` → `Google`, falls back to the raw id). Hook icons or styling
+off `data-pyric-provider-id` instead — the library ships no assets.
+## Styling hooks
+| Selector | Element |
+|---|---|
+| `[data-pyric-ui="auth-signin-helper"]` | Root `<section>`; carries `data-pyric-provider-id` + `data-pyric-auth-type`. |
+| `[data-pyric-helper-title]` / `[data-pyric-helper-description]` | Header text. |
+| `[data-pyric-account-list]` / `[data-pyric-account-entry]` | Picker list / rows (`data-pyric-account-uid`, `data-pyric-provider-id`). |
+| `button[data-pyric-account-pick]` | Row button. Default children: `[data-pyric-account-name]` + `[data-pyric-account-email]`. |
+| `form[data-pyric-add-account-form]` | Add-account form. |
+| `[data-pyric-field="email" \| "display-name" \| "claims"]` | Inputs. The claims textarea gains `data-pyric-claims-invalid` + `aria-invalid` on error. |
+| `[data-pyric-claims-error]` | `role="alert"` validation message. |
+| `button[data-pyric-cancel]` / `button[data-pyric-submit]` | Actions. Submit is disabled while the email is empty. |
+## Gotchas
+- **One flow at a time** — a new `signInWithPopup` while one is parked
+  cancels the stale request (rejects `auth/popup-closed-by-user`).
+- **Tokens are host-synthesized** (`sandbox-helper-<uid>`) until the sandbox
+  backend grows `createSignInCredential` (tracked follow-up); claims still
+  flow into rules evaluation via the seeded identity.
+- A live consumer: the playground's
+  `PreviewAuthHelper`
+  + its `global.css` skin.