@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/ui-storage.md

@@ -0,0 +1,165 @@
+# `@pyric/ui/storage`
+
+Headless components + hooks for browsing AND administering Firebase Storage —
+list/navigate/select (the read path), upload, inspect, metadata editing, and
+bulk delete (the write path), plus rules-aware affordances (the gate
+pre-evaluates rules so denied actions warn BEFORE the click). Same one-handle
+contract as the Firestore half: every hook takes the sandbox
+`FirebaseStorage` handle from `pyric/storage`.
+
+```ts
+import {
+  // read path
+  useStorageList,
+  usePathState,
+  ObjectBrowser,
+  PathBreadcrumb,
+  // write path
+  useObjectUpload,
+  useStorageObject,
+  useMetadataEditor,
+  useStorageSelection,
+  useStorageDelete,
+  // rules-aware affordances
+  useStorageRulesGate,
+  UploadDropzone,
+  ObjectInspector,
+  DeleteSelectionWithConfirm,
+  defaultStoragePreviews,
+} from '@pyric/ui/storage';
+// hooks-only entry: '@pyric/ui/storage/hooks'
+```
+
+## The wiring (one screen)
+
+```tsx
+function StorageAdmin({ storage }) {
+  const nav = usePathState();
+  const list = useStorageList(storage, nav.path);
+  const selection = useStorageSelection();
+  const upload = useObjectUpload(storage, { path: nav.path, list });
+  const gate = useStorageRulesGate(storage);
+  const pathVerdict = gate.verdictFor(nav.path);
+  const [inspecting, setInspecting] = useState<string | null>(null);
+
+  return (
+    <ToastProvider>
+      <ConfirmProvider>
+        <PathBreadcrumb path={nav.path} onNavigate={nav.setPath} />
+        <UploadDropzone
+          disabled={!pathVerdict.upload}
+          disabledReason={pathVerdict.reasons.write.join('; ')}
+          onFiles={(files) =>
+            upload.upload(files.map((f) => ({ path: f.relativePath, data: f.file })))
+          }
+        >
+          <ObjectBrowser
+            entries={list.entries}
+            status={list.status}
+            error={list.error}
+            gate={gate}
+            onNavigate={(p) => { selection.clear(); nav.enter(p); }}
+            onSelect={(ref) => setInspecting(ref.fullPath)}
+          />
+        </UploadDropzone>
+        <DeleteSelectionWithConfirm
+          storage={storage}
+          entries={selection.selected}
+          list={list}
+          gate={gate}
+          onDeleted={() => { selection.clear(); list.refresh(); }}
+        />
+        <ObjectInspector storage={storage} path={inspecting} />
+      </ConfirmProvider>
+    </ToastProvider>
+  );
+}
+```
+
+## Components
+
+- [ObjectBrowser](../ui-storage-objectbrowser/) — the folder/object row list;
+  virtualized above 100 rows.
+- [PathBreadcrumb](../ui-storage-pathbreadcrumb/) — clickable ancestor trail.
+- [UploadDropzone](../ui-storage-uploaddropzone/) — slot-based file + folder drop
+  target.
+- [ObjectInspector](../ui-storage-objectinspector/) — metadata + content-type-driven
+  previews (image/text/json built in, consumer-extensible).
+- [DeleteSelectionWithConfirm](../ui-storage-deleteselectionwithconfirm/) — bulk +
+  recursive delete behind the confirm dialog, toasts on outcome.
+
+## Concepts
+
+- [Rules-aware affordances](../ui-storage-rules-aware-affordances/) — how the gate's
+  verdicts flow into `data-pyric-denied` rows and disabled-with-reason
+  states.
+
+## Hooks
+
+Hook docs live in the source JSDoc — every hook has an options/return
+interface commented per field ([`useStorageRulesGate`](../ui-storage-usestoragerulesgate/)
+also has a full page). Summary:
+
+- **`useStorageList(storage, path)`** — `listAll` + the prefix→folder
+  synthesis: `{ status, items, prefixes, entries, error, refresh,
+  insertItem, removeItem }`. `insertItem`/`removeItem` are the optimistic
+  seam the upload/delete hooks plug into (a trailing slash declares a
+  folder). A rules-denied list surfaces the typed error
+  (`error.code === 'storage/unauthorized'`).
+- **`usePathState({ path?, onPathChange?, defaultPath? })`** — navigation
+  state, controlled or uncontrolled. `{ path, segments, setPath, enter, up,
+  navigateToIndex }`.
+- **`useObjectUpload(storage, { path, list, onProgress, onComplete,
+  onError })`** — multi-file upload with a **task-shaped API**
+  (`UploadTask` carries byte counters; `pyric/storage` has no resumable
+  uploads yet, so tasks complete in one tick — the type won't change when
+  resumable lands). Optimistic insert + rollback through the `list` seam.
+  Also `createFolder(name)` — writes the zero-byte `<path>/` placeholder
+  (the GCS convention) into the sandbox mirror.
+- **`useStorageObject(storage, path)`** — one object's metadata + lazy
+  bytes: `{ status, metadata, error, refresh, blobStatus, blob, blobUrl,
+  blobError, loadBlob }`. `blobUrl` is a `URL.createObjectURL` handle,
+  revoked automatically on path change and unmount.
+- **`useMetadataEditor(storage, path, { initial })`** — the
+  `useDocumentEditor` reducer pattern over `updateMetadata`: contentType,
+  cacheControl, customMetadata k/v rows (stable ids, empty/duplicate-key
+  validation), `isDirty`/`isValid`/`reset`/`toPatch`, plus
+  `save`/`isSaving`/`saveError`. Note: clearing a text field keeps the old
+  value — the storage surface doesn't model null-clears yet.
+- **`useStorageSelection()`** — multi-select keyed by `fullPath`;
+  `list.entries` rows pass straight in.
+- **`useStorageDelete(storage, { impl?, list? })`** — bulk + recursive
+  delete. Folders walk via the injectable `StorageRecursiveDeleteImpl`
+  (default: `createListAllDeleteImpl()` — `listAll`-driven, sweeps
+  create-folder placeholders so emptied folders don't ghost).
+- **`useStorageRulesGate(storage, { paths?, rules?, identity?,
+  writeResource? })`** — pre-flight rules verdicts (`{ read, write,
+  delete, upload, reasons }`; delete/upload derive from write) via the
+  pure evaluator. Sandbox handles need zero config (rules + identity come
+  off the handle). Fails open. Full page:
+  [useStorageRulesGate](../ui-storage-usestoragerulesgate/).
+
+## Constraints worth knowing (from the storage COMPAT)
+
+- **`listAll` only, no pagination** — a very large sandbox prefix arrives
+  as one flat result. `<ObjectBrowser>` virtualizes, but
+  the fetch itself is unpaginated. The recursive delete walks the same way.
+- **Read-via-get, not realtime** — lists and inspectors update on `refresh`,
+  path change, or the optimistic seam.
+- **`getDownloadURL` is page-local** — it returns a blob URL backed by
+  the sandbox object; revoke it with `URL.revokeObjectURL` when done.
+- **No resumable uploads** — `useObjectUpload` is task-shaped for
+  forward-compat; `onProgress` fires start + completion today.
+- **Create-folder uses a structural reference** — the `<path>/` placeholder
+  name cannot be expressed through the JS-SDK-shaped `ref()` because it
+  normalizes trailing slashes.
+
+## See also
+
+- design rationale — the
+  milestone roadmap (the playground consumer, M8, is next; M7's traffic
+  panel is STOP-documented in
+  the design rationale).
+- [`<VirtualList>`](../ui-primitives-virtuallist/),
+  [`<ConfirmDialog>`](../ui-primitives-confirmdialog/),
+  [`<Toast>`](../ui-primitives-toast/) — the primitives this half composes.

package/dist/serve/docs-ui/docs/ui-traffic/index.html

@@ -0,0 +1,88 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>@pyric/ui/traffic · 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>Traffic</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">@pyric/ui/traffic</span> </li> </ol> </nav>  <article class="prose">  <h1 id="pyricuitraffic"><code>@pyric/ui/traffic</code></h1>
+<p>Headless components + hooks for observing rule-eval traffic — a Chrome
+DevTools Network-panel-style <strong>log</strong> and a per-rule <strong>heatmap</strong>, plus stats
+and grouping. Decoupled from <code>pyric/sandbox</code>: the data hook takes a <code>source</code>
+function, so the same components work against the sandbox or a production
+log feed.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  useTrafficMonitor</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  useTrafficFilter</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  useRuleHeatmap</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  useTrafficStats</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  useTrafficGroups</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  TrafficLog</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  TrafficRow</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  TrafficGroupRow</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  TrafficDetail</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  RuleHeatmap</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  TrafficStats</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#C678DD">  type</span><span style="color:#E06C75"> TrafficEvent</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#C678DD">  type</span><span style="color:#E06C75"> TrafficSource</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">} </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/ui/traffic'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<h2 id="the-decoupling-contract">The decoupling contract</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">type</span><span style="color:#E5C07B"> TrafficSource</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> (</span><span style="color:#61AFEF">cb</span><span style="color:#ABB2BF">: (</span><span style="color:#E06C75;font-style:italic">event</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">TrafficEvent</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> void</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> () </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> void</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p><code>pyric/sandbox</code>’s <code>Sandbox.onRequest</code> matches this signature exactly —
+<code>useTrafficMonitor({ source: sandbox.onRequest })</code> wires with zero adapter
+code. <code>TrafficEvent</code> is structurally identical to the sandbox’s <code>RequestEvent</code>
+but the library owns its own copy so it never imports <code>pyric/sandbox</code>.</p>
+<h2 id="components">Components</h2>
+<ul>
+<li><a href="../ui-traffic-trafficlog/">TrafficLog</a> — the event stream; virtualized flat list,
+or singles + collapsible groups in grouped mode.</li>
+<li><a href="../ui-traffic-trafficdetail/">TrafficDetail</a> — drill-in panel for one event.</li>
+<li><a href="../ui-traffic-ruleheatmap/">RuleHeatmap</a> — per-rule fire / deny rollup.</li>
+<li><a href="../ui-traffic-trafficstats/">TrafficStats</a> — totals + breakdowns.</li>
+</ul>
+<h2 id="hooks">Hooks</h2>
+<p>Hook docs live in the source JSDoc — every hook has an options interface and a
+return-shape interface commented per field. Summary:</p>
+<ul>
+<li><strong><code>useTrafficMonitor({ source, bufferSize?, paused?, transform? })</code></strong> — the
+core. A capped ring buffer (default 5000) with <code>pause</code> / <code>resume</code> / <code>clear</code>
+and derived <code>counts</code>. <code>transform</code> runs per event before buffering, for
+consumer-side payload shrinking.</li>
+<li><strong><code>useTrafficFilter({ events })</code></strong> — filters along origin / result / path.
+Defaults to <strong>user-origin, allow+deny visible, listener hidden</strong> — the probe
+found listener traffic is 94–99.6% of events.</li>
+<li><strong><code>useRuleHeatmap({ events })</code></strong> — rolls events up by
+<code>matchedRule.ruleIndex</code>: per-rule total / allow / deny counts + deny ratio.</li>
+<li><strong><code>useTrafficStats({ events, topPaths? })</code></strong> — totals, deny rate, and count
+breakdowns by method / origin / path.</li>
+<li><strong><code>useTrafficGroups({ events })</code></strong> — folds the buffer into singles +
+collapsible groups: <code>groupId</code> batches/transactions, and consecutive
+listener-run aggregation.</li>
+</ul>
+<h2 id="minimal-wiring">Minimal wiring</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"> TrafficPanel</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"> monitor</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> useTrafficMonitor</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">onRequest</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">filtered</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">filter</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">setOrigin</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">setResult</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">setPathQuery</span><span style="color:#ABB2BF"> } </span><span style="color:#56B6C2">=</span></span>
+<span class="line"><span style="color:#61AFEF">    useTrafficFilter</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">events</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">monitor</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">events</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">selectedId</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">setSelectedId</span><span style="color:#ABB2BF">] </span><span style="color:#56B6C2">=</span><span style="color:#61AFEF"> useState</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF"> | </span><span style="color:#E5C07B">null</span><span style="color:#ABB2BF">>(</span><span style="color:#D19A66">null</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">  const</span><span style="color:#E5C07B"> selected</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> monitor</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">events</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">find</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:#E5C07B"> e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">id</span><span style="color:#56B6C2"> ===</span><span style="color:#E06C75"> selectedId</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">  return</span><span style="color:#E06C75"> selected</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">TrafficDetail</span><span style="color:#D19A66;font-style:italic"> event</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E06C75">selected</span><span style="color:#C678DD">}</span><span style="color:#D19A66;font-style:italic"> onBack</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#ABB2BF">() </span><span style="color:#C678DD">=></span><span style="color:#61AFEF"> setSelectedId</span><span style="color:#ABB2BF">(</span><span style="color:#D19A66">null</span><span style="color:#ABB2BF">)</span><span style="color:#C678DD">}</span><span style="color:#ABB2BF"> /></span></span>
+<span class="line"><span style="color:#ABB2BF">  ) </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">TrafficLog</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">      events</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#ABB2BF">[...</span><span style="color:#E06C75">filtered</span><span style="color:#ABB2BF">].</span><span style="color:#61AFEF">reverse</span><span style="color:#ABB2BF">()</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">      selectedId</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E06C75">selectedId</span><span style="color:#56B6C2"> ??</span><span style="color:#D19A66"> undefined</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">      onSelect</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"> setSelectedId</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">id</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">  );</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<h2 id="notes">Notes</h2>
+<ul>
+<li><strong>Latency is de-featured.</strong> <code>evalMs</code> stays on <code>TrafficEvent</code> and shows in
+<code>TrafficDetail</code>, but it is not a log column — this is a local simulator.</li>
+<li><strong>Classification is the consumer’s.</strong> <code>expected</code> / <code>ambiguous</code> /
+<code>unexpected</code> verdicts are app-source analysis, not sandbox data. Components
+expose a <code>renderClassification</code> render-prop slot for it.</li>
+</ul>
+<h2 id="see-also">See also</h2>
+<ul>
+<li>design rationale — the milestone roadmap.</li>
+<li>design rationale — the sandbox
+<code>onRequest</code> API and the empirical probe findings this builds on.</li>
+<li>Live showcase — the “Traffic
+Monitor” route.</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="#the-decoupling-contract">The decoupling contract</a> </li><li data-depth="2"> <a href="#components">Components</a> </li><li data-depth="2"> <a href="#hooks">Hooks</a> </li><li data-depth="2"> <a href="#minimal-wiring">Minimal wiring</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-traffic-ruleheatmap/index.html

@@ -0,0 +1,79 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>&lt;RuleHeatmap&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>Traffic</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">&lt;RuleHeatmap&gt;</span> </li> </ol> </nav>  <article class="prose">  <h1 id="ruleheatmap"><code>&#x3C;RuleHeatmap></code></h1>
+<p>Per-rule fire / deny rollup — one row per rule, busiest first. Pairs with
+<code>useRuleHeatmap</code>, which does the aggregation.</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">RuleHeatmap</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">useRuleHeatmap</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/ui/traffic'</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">const</span><span style="color:#ABB2BF"> { </span><span style="color:#E5C07B">entries</span><span style="color:#ABB2BF"> } </span><span style="color:#56B6C2">=</span><span style="color:#61AFEF"> useRuleHeatmap</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">events</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">monitor</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">events</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">RuleHeatmap</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:#E06C75">entries</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">  selectedRuleIndex</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#E06C75">selectedRule</span><span style="color:#56B6C2"> ??</span><span style="color:#D19A66"> undefined</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#D19A66;font-style:italic">  onSelectRule</span><span style="color:#56B6C2">=</span><span style="color:#C678DD">{</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">i</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#61AFEF"> setSelectedRule</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">cur</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75">cur</span><span style="color:#56B6C2"> ===</span><span style="color:#E06C75"> i</span><span style="color:#C678DD"> ?</span><span style="color:#D19A66"> null</span><span style="color:#C678DD"> :</span><span style="color:#E06C75"> i</span><span style="color:#ABB2BF">))</span><span style="color:#C678DD">}</span></span>
+<span class="line"><span style="color:#ABB2BF">/></span></span></code></pre>
+<p>Wire <code>onSelectRule</code> to your log filter for the cross-view “click a rule, see
+its traffic” interaction — the showcase narrows the event list to
+<code>matchedRule.ruleIndex === selectedRule</code> before the origin/result filter runs.</p>
+<h2 id="props">Props</h2>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Prop</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>entries</code></td><td><code>RuleHeatmapEntry[]</code></td><td>yes</td><td>From <code>useRuleHeatmap</code>.</td></tr><tr><td><code>selectedRuleIndex</code></td><td><code>number</code></td><td>no</td><td>Marks one row with <code>data-pyric-selected</code>.</td></tr><tr><td><code>onSelectRule</code></td><td><code>(ruleIndex) => void</code></td><td>no</td><td>Fired on row click.</td></tr><tr><td><code>emptyState</code></td><td><code>ReactNode</code></td><td>no</td><td>Rendered when there are no entries.</td></tr><tr><td><code>className</code></td><td><code>string</code></td><td>no</td><td>Forwarded to the root.</td></tr></tbody></table></div>
+<h2 id="two-styling-channels-for-heat">Two styling channels for “heat”</h2>
+<p>Each row exposes the deny intensity two ways — use whichever fits:</p>
+<ul>
+<li><strong><code>data-pyric-rule-heat</code></strong> — a discrete bucket (<code>none</code> / <code>low</code> / <code>medium</code> /
+<code>high</code>) for threshold-based coloring.</li>
+<li><strong><code>--pyric-deny-ratio</code></strong> — the raw 0–1 ratio as a CSS custom property, for a
+proportional bar or gradient (<code>[data-pyric-rule-bar]</code> is provided as the
+target element).</li>
+</ul>
+<h2 id="styling-hooks">Styling hooks</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="plaintext"><code><span class="line"><span>[data-pyric-ui="rule-heatmap"]</span></span>
+<span class="line"><span>[data-pyric-rule-row]                  /* + data-pyric-rule-index / -heat, data-pyric-selected */</span></span>
+<span class="line"><span>[data-pyric-rule-label]                /* "#N" */</span></span>
+<span class="line"><span>[data-pyric-rule-operations]</span></span>
+<span class="line"><span>[data-pyric-rule-total] / -allows / -denies</span></span>
+<span class="line"><span>[data-pyric-rule-bar]                  /* read --pyric-deny-ratio off the row */</span></span></code></pre>
+<h2 id="notes">Notes</h2>
+<ul>
+<li>Events with no <code>matchedRule</code> aren’t attributed to any row — <code>useRuleHeatmap</code>
+reports them as <code>unmatchedCount</code>.</li>
+</ul>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#example">Example</a> </li><li data-depth="2"> <a href="#props">Props</a> </li><li data-depth="2"> <a href="#two-styling-channels-for-heat">Two styling channels for “heat”</a> </li><li data-depth="2"> <a href="#styling-hooks">Styling hooks</a> </li><li data-depth="2"> <a href="#notes">Notes</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/ui-traffic-ruleheatmap.md

@@ -0,0 +1,60 @@
+# `<RuleHeatmap>`
+
+Per-rule fire / deny rollup — one row per rule, busiest first. Pairs with
+`useRuleHeatmap`, which does the aggregation.
+
+```ts
+import { RuleHeatmap, useRuleHeatmap } from '@pyric/ui/traffic';
+```
+
+## Example
+
+```tsx
+const { entries } = useRuleHeatmap({ events: monitor.events });
+
+<RuleHeatmap
+  entries={entries}
+  selectedRuleIndex={selectedRule ?? undefined}
+  onSelectRule={(i) => setSelectedRule((cur) => (cur === i ? null : i))}
+/>
+```
+
+Wire `onSelectRule` to your log filter for the cross-view "click a rule, see
+its traffic" interaction — the showcase narrows the event list to
+`matchedRule.ruleIndex === selectedRule` before the origin/result filter runs.
+
+## Props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `entries` | `RuleHeatmapEntry[]` | yes | From `useRuleHeatmap`. |
+| `selectedRuleIndex` | `number` | no | Marks one row with `data-pyric-selected`. |
+| `onSelectRule` | `(ruleIndex) => void` | no | Fired on row click. |
+| `emptyState` | `ReactNode` | no | Rendered when there are no entries. |
+| `className` | `string` | no | Forwarded to the root. |
+
+## Two styling channels for "heat"
+
+Each row exposes the deny intensity two ways — use whichever fits:
+
+- **`data-pyric-rule-heat`** — a discrete bucket (`none` / `low` / `medium` /
+  `high`) for threshold-based coloring.
+- **`--pyric-deny-ratio`** — the raw 0–1 ratio as a CSS custom property, for a
+  proportional bar or gradient (`[data-pyric-rule-bar]` is provided as the
+  target element).
+
+## Styling hooks
+
+```
+[data-pyric-ui="rule-heatmap"]
+[data-pyric-rule-row]                  /* + data-pyric-rule-index / -heat, data-pyric-selected */
+[data-pyric-rule-label]                /* "#N" */
+[data-pyric-rule-operations]
+[data-pyric-rule-total] / -allows / -denies
+[data-pyric-rule-bar]                  /* read --pyric-deny-ratio off the row */
+```
+
+## Notes
+
+- Events with no `matchedRule` aren't attributed to any row — `useRuleHeatmap`
+  reports them as `unmatchedCount`.