@hakam-aldeen-kh/blix 0.4.1 → 0.5.0

package/README.md

@@ -3,12 +3,13 @@
 
 An in-app dev-tools panel for React apps. Captures HTTP requests, Redux
 actions, TanStack Query cache events and realtime traffic, and renders them in
-a dockable panel with a waterfall, diffing, replay and HAR/cURL export.
+a dockable panel with cross-source links, diffing, replay and HAR/cURL
+export.
 
 The entire panel is eliminated from production builds — see
 [Production elimination](#production-elimination).
 
-Release notes are in [CHANGELOG.md](CHANGELOG.md).
+Release notes are in [CHANGELOG.md](https://github.com/Hakam-aldeen-Kh/blix/blob/main/CHANGELOG.md).
 
 ---
 
@@ -173,8 +174,8 @@ instance.interceptors.response.use(undefined, (error) =>
 
 The consequence is silent and total: **every non-2xx request stays `pending`
 in the panel for the rest of the session.** No error, no warning, no Failed
-filter. (The 30-second pending cap only bounds the width of the waterfall bar;
-it does not resolve the entry.)
+filter. (The 30-second pending cap only bounds how far the row's duration bar
+grows; it does not resolve the entry.)
 
 Two ways out, and you currently have to choose one:
 
@@ -385,7 +386,7 @@ both. There is no wrong choice here and no silent failure.
 
 What *does* matter is which one your app calls through. Only the proxy's traps
 record a stack, so every request made against the unwrapped instance is still
-captured but arrives with an empty Initiator column. Export the wrapped one and
+captured but arrives with no initiator. Export the wrapped one and
 keep the original private:
 
 ```ts
@@ -401,7 +402,7 @@ The traps cover the callable form (`apiClient(config)`) plus `request`, `get`,
 the `*Form` helpers — pass through unwrapped: still captured, just with no
 initiator stack.
 
-> **Known limitation.** The Initiator column is produced by filtering your own
+> **Known limitation.** The initiator stack is produced by filtering your own
 > HTTP wrapper's frames out of the captured stack, and that filter currently
 > matches a fixed set of module paths rather than deriving them from where
 > `withInitiatorCapture` was called. If your axios module does not sit at one
@@ -601,6 +602,39 @@ structural typing means you just pass your store and client.)
 Passing neither still gives you a fully working capture log; you only lose the
 two features that need a live handle on the app.
 
+### Finding your way around
+
+The panel is one header, one rail and two panes.
+
+**The rail on the left is the four sources** — Network, Realtime, Redux,
+Query. They are not filters over one table: each has its own columns and its
+own notion of a row, so switching source switches the whole view. `1`–`4` jump
+between them, and each keeps its own selection, so stepping to Redux and back
+returns you to the request you were reading. Below the sources it carries the
+session totals, and it collapses to icons — click the chevron, or let a narrow
+dock do it for you.
+
+**The header is the session**, not the entry: whether capture is running, what
+is being filtered out, and where the panel lives. Filter tokens you have
+already applied become chips *inside* the filter field, each removable on its
+own, so `method:post status:5xx` is two things you can undo separately rather
+than one string to re-edit. `.*` widens the search to request and response
+bodies.
+
+**`Ctrl/⌘ K` opens the command palette**, and for several things it is the only
+way in — sort order, row density, dock position, the copy formats, the filter
+syntax. The header spends its width on what you read constantly; everything you
+reach for occasionally lives one keystroke away instead of costing a button
+each. Every row shows its key binding where it has one, so the palette teaches
+its own shortcuts. `?` still opens the full cheatsheet.
+
+**Linked events tie the sources together.** When Blix can see that a query
+caused a request, that a request came from a query, or that one entry is a
+replay of another, the row grows a coloured tick and the foot of the detail
+pane grows a chip you can click to step straight to the other side. The
+relation is observed, never inferred: no tick means *not known*, not
+*unrelated*.
+
 ### Viewing payloads
 
 Every payload pane has a format switch. The choice is remembered, so you pick
@@ -634,7 +668,7 @@ literal rather than a pre-serialized string.
 
 ### Exporting the log
 
-The ◐ toolbar's neighbour, the download button, offers six formats and a scope
+The **Export** button in the header offers six formats and a scope
 toggle — **Shown** (what the current section and filters leave visible) or
 **All**. It defaults to Shown, with both counts on the control, so an export
 says what it will contain before you pick a format.
@@ -653,7 +687,8 @@ placeholder rather than a working token — use **Replay** for a real re-run.
 
 ### Themes
 
-Twelve themes, under the ◐ button in the toolbar:
+Twelve themes, under the theme button in the header — it names the one
+currently applied:
 
 | | Theme | |
 | --- | --- | --- |
@@ -682,7 +717,7 @@ panel's other preferences and survives a reload.
 The panel never inherits your app's styling — it portals outside every stacking
 context and ships its own palettes, so nothing you do to your own theme can
 distort it. Themes are complete rather than partial: every colour the panel
-paints, down to the JSON syntax highlighting and the waterfall bars, comes from
+paints, down to the JSON syntax highlighting and the duration bars, comes from
 the active theme. Each palette is checked against WCAG contrast targets — 4.5:1
 for anything read as text, 3:1 for badges and quiet chrome — which is why a few
 of the ported palettes differ by a shade from the originals in the slots used
@@ -825,13 +860,16 @@ the database is opened only when the panel mounts — see
 while it is off nothing Blix captures reaches IndexedDB — the store is
 actively cleared on every panel mount.
 
-Three ways to toggle it:
+Four ways to toggle it:
 
 | Where | Note |
 | --- | --- |
-| Toolbar button | Hidden in the compact layout |
-| **⋯ More actions** overflow menu | Always available |
-| `Shift+L` | Always available |
+| Header button | Keeps its icon at every width; loses its label when the panel is narrow |
+| **⋯ More actions** overflow menu | — |
+| Command palette (`Ctrl/⌘ K`) | Listed as **Preserve log across reloads** / **Stop preserving the log** |
+| `Shift+L` | — |
+
+All four require the panel to be mounted.
 
 **Turning it on is retroactive.** The toggle does not mean "from now on".
 Switching it on writes every entry already sitting in the live buffer — the
@@ -872,7 +910,9 @@ that is not one of the four above, it is captured verbatim.
 
 Masking is partial rather than total: for a value longer than 12 characters
 the first 8 and last 4 survive, so you can still tell which token you sent.
-Shorter values are replaced outright.
+Shorter values are replaced outright. The Headers tab tags every masked row
+`MASKED` rather than leaving you to infer it from an ellipsis, and the stored
+value keeps a `(masked)` suffix so every export path carries the fact too.
 
 **Nothing inside a body is redacted.** Request bodies, response bodies, error
 payloads, the encrypted request/response values, Redux payloads and diffs, and
@@ -887,7 +927,7 @@ for your payloads and no way to tell a secret from any other string.
 | Bound | Value |
 | --- | --- |
 | Records | 200 |
-| Total size | 24 MB |
+| Total size | 24 MB — HTTP entries only |
 | Per payload field | 512 KB |
 | Eviction | oldest first, once either bound is exceeded |
 | Time-based expiry | none |
@@ -897,26 +937,27 @@ records or 24 MB of newer traffic push it out, or when you clear it yourself.
 On a low-traffic app with preserve-log left on, a captured token stays in the
 browser profile indefinitely.
 
-> **Realtime frames are an exception to the size bound.** They are stored
-> without truncation and are under-counted against the byte budget — a record
-> is charged a flat allowance regardless of how many frames it carries, and a
-> connection can hold hundreds. A long-lived realtime session can therefore
-> occupy considerably more on disk than the 24 MB figure implies, and eviction
-> will not reclaim it. The record and size caps hold for HTTP entries.
-> Tracked in [#N](https://github.com/Hakam-aldeen-Kh/blix/issues/N).
+Three ways to purge:
+
+| Where | Note |
+| --- | --- |
+| The persisted-size label in the status bar — the one reading `12 saved · 3.4 MB` | The label *is* the control, and it is the only one that asks twice: click once to arm it, at which point it changes to `Purge saved log?`, and click again. It disarms itself after three seconds. Rendered only while preserve-log is on |
+| **⋯ More actions** → **Purge saved log** | Deletes on a single press, with no confirmation |
+| Command palette (`Ctrl/⌘ K`) → **Purge the saved log** | Deletes on a single press, with no confirmation |
 
-To purge, use the persisted-size label in the status bar — the one reading
-`12 saved · 3.4 MB`. It is the control: click once to arm it, at which point
-it changes to `Purge saved log?`, and click again to delete the database.
+The menu and palette entries are disabled when nothing is on disk, but unlike
+the status-bar label they do not depend on preserve-log being on — so a log
+written earlier in the session can still be deleted after you have switched
+the toggle off.
 
 Switching preserve-log **off** also clears the stored entries, so turning it
-off is itself a way to drop everything Blix has written. What survives is the
-database and your panel preferences, not the captured bodies.
+off is itself a way to drop everything Blix has written.
 
-**The purge control is only rendered while preserve-log is on**, so once you
-have switched it off there is nothing left in the UI to press — and there is
-no programmatic API for it either. Use Purge when you want the database gone
-outright; switch off when clearing the entries is enough.
+Every path clears the captured entries; Purge additionally deletes the
+IndexedDB database itself. **Your panel preferences survive either way** —
+they are mirrored to `localStorage`, and a fresh database is re-seeded from
+that mirror on the next boot. There is no UI or API for clearing them, and no
+programmatic API for purging either.
 
 ### Threat model
 
@@ -931,7 +972,7 @@ Export and copy move captured data out of the browser entirely:
 | --- | --- |
 | HAR export | Decrypted request and response bodies |
 | JSON / NDJSON export | Everything captured — frames, Redux diffs, timings |
-| **Copy as cURL** / **Copy as fetch** | Headers and bodies, with `Authorization` masked — so the output is not a working request |
+| **Copy as cURL** / **Copy as fetch** | Headers and bodies, with the four redacted headers masked — so the output is not a working request |
 
 HAR is the one to watch. It is a plain JSON file carrying your decrypted
 bodies, and it is the artifact most likely to end up attached to a ticket.
@@ -941,8 +982,9 @@ bodies, and it is the artifact most likely to end up attached to a ticket.
 - **Leave preserve-log off unless you actively need it.** It is off by
   default. In-memory capture already gives you the entire panel; the toggle
   buys you nothing but survival across a reload.
-- **Purge after any session that captured an auth flow** — and purge *before*
-  you switch preserve-log back off, or the control disappears on you.
+- **Clear the log after any session that captured an auth flow** —
+  switching preserve-log off is enough; Purge additionally deletes the
+  database, though neither removes your panel preferences.
 - **Use the Redux `ignore` option** for action types that carry credentials or
   personal data, so they are never captured in the first place. See
   [Redux](#redux--createreduxmonitormiddlewareoptions).
@@ -973,4 +1015,4 @@ The `/capture` entry exports `attachHttpMonitor`, `captureEncrypted`,
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+MIT — see [LICENSE](https://github.com/Hakam-aldeen-Kh/blix/blob/main/LICENSE).