@hakam-aldeen-kh/blix 0.7.0 → 0.9.0

package/README.md

@@ -7,7 +7,8 @@ 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).
+[Production elimination](#production-elimination). To keep it on a staging
+server, see [Enabling Blix in a production build](#enabling-blix-in-a-production-build-staging).
 
 Release notes are in [CHANGELOG.md](https://github.com/Hakam-aldeen-Kh/blix/blob/main/CHANGELOG.md).
 
@@ -397,7 +398,9 @@ never creating one of its own — and the panel updates.
 It is a **silent no-op** — never a throw, never a console warning — in every
 one of these:
 
-- outside development (`process.env.NODE_ENV !== "development"`);
+- outside development (`process.env.NODE_ENV !== "development"`), unless the
+  build opted in with `NEXT_PUBLIC_BLIX=true` (see
+  [staging](#enabling-blix-in-a-production-build-staging));
 - **outside the browser** — the gate is also `typeof window !== "undefined"`,
   so every call made while rendering on the server does nothing, by design (see
   [Production elimination](#production-elimination));
@@ -721,7 +724,11 @@ import { store } from "@/src/store";
 // module graph, which fails the production build. Importing them here keeps
 // that evaluation on the client side of the boundary.
 export default function BlixMount() {
-  if (process.env.NODE_ENV !== "development") return null;
+  if (
+    process.env.NODE_ENV !== "development" &&
+    process.env.NEXT_PUBLIC_BLIX !== "true"
+  )
+    return null;
   return <Blix store={store} apiClient={apiClient} dbName="my-app" />;
 }
 ```
@@ -786,16 +793,25 @@ The panel is one header, one rail and two panes.
 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.
+returns you to the request you were reading. Each row ends with its own number
+key, because a shortcut is best taught where it is used. Below the sources it
+carries the session totals; collapsed, it keeps the sources and their counts
+and drops the totals, since four numbers without their labels are four
+unattributed numbers.
 
 **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.
+is being filtered out, and where the panel lives. While a filter is on, the
+field carries its own count — `8 of 56` — and a clear button, so you never
+have to read the status bar to know one is applied. `.*` widens the search to
+request and response bodies.
+
+**The red bin beside Export clears the source you are reading**, and only
+that one: emptying Redux leaves Network alone. Pinned entries survive it, and
+it is disabled when the source has nothing left to clear. To empty every
+source at once, use **Clear log** in the overflow menu, or `⇧C`.
+
+The panel opens **floating** the first time. Dock it to the bottom or the
+right from the header; the choice is saved per project.
 
 **`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
@@ -804,6 +820,13 @@ 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.
 
+**The columns are yours.** Right-click the column head — or open **Columns** in
+the overflow menu — and switch off any of Pin, Method, Size, Status, Time,
+Linked and Timing. The choice persists. ROUTE has no switch: it is the column
+that says *which* entry a row is, and a list of rows you cannot identify is not
+a list. A narrow pane drops columns on its own, worst-affordable first, so the
+route keeps the width it needs.
+
 **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
@@ -895,14 +918,18 @@ 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 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
-for dense monospace.
-
-There is no API for adding your own; a theme is ~20 colours in
-`src/ui/themes/themes.ts` if you are working from source.
+paints, down to the JSON syntax highlighting and the timing bars, comes from
+the active theme. The two tones that carry text are held to 4.5:1 against every
+ground they land on, which is why a few of the ported palettes differ by a
+shade from the originals in the slots used for dense monospace. One tone is
+deliberately below it and may never hold text: it is for separators, payload
+punctuation and disabled glyphs.
+
+There is no API for adding your own; a theme is 33 colour slots in
+`src/ui/themes/bx.ts` if you are working from source. Every theme fills the
+same set — a theme that cannot is reported in the console during development,
+along with any whose text tones fall under 4.5:1 on a ground they actually
+land on.
 
 ### `dbName` — when you need it
 
@@ -1002,8 +1029,55 @@ payloads for the lifetime of the server. Keeping the server-side singleton
 permanently empty is the point.
 
 Practically: a `captureEncrypted` call that runs during SSR does nothing, and
-`<Blix />` returns `null` there — it checks `typeof window` alongside
-`NODE_ENV` before touching the panel import.
+`<Blix />` renders nothing there. It also renders nothing during hydration, so
+its first client render matches the server's HTML; the panel mounts on the
+render right after. (Before 0.9.0 it branched on `typeof window` instead,
+which Next.js reported as a hydration mismatch on every load.)
+
+### Enabling Blix in a production build (staging)
+
+A staging or test server usually runs a production build, where the panel is
+gone by design. Setting `NODE_ENV=development` for that build does not bring
+it back on Next.js 16: `next build` runs on Turbopack and inlines `NODE_ENV`
+as `"production"` whatever the environment says.
+
+Opt in explicitly instead, in that server's env file:
+
+```bash
+NEXT_PUBLIC_BLIX=true
+```
+
+The panel and the capture layer both check it next to `NODE_ENV`, as the same
+kind of literal comparison, so Next.js inlines it at build time.
+
+> **Set `NEXT_PUBLIC_BLIX=false` in your production env file.** Next.js only
+> inlines variables that are defined. Left unset, the comparison stays in the
+> bundle as a runtime check: the panel still never loads — the variable is
+> undefined in the browser — but its chunk is emitted into your production
+> build. `false` lets the bundler fold the check and drop the chunk.
+
+**Never set `NEXT_PUBLIC_BLIX=true` for a build that real users get.** It
+ships the monitor to them, and with it everything it captures — see
+[Security](#security).
+
+**Your own guards need the variable too.** A mount component that returns
+`null` outside development (as in [Mounting the panel](#mounting-the-panel)),
+or a call-site guard around `attachHttpMonitor` (below), keeps Blix off on
+staging regardless of the variable. Add it to each:
+
+```ts
+if (
+  (process.env.NODE_ENV === "development" ||
+    process.env.NEXT_PUBLIC_BLIX === "true") &&
+  typeof window !== "undefined"
+) {
+  attachHttpMonitor(apiClient);
+}
+```
+
+The variable is read under its `NEXT_PUBLIC_` name, which is a Next.js
+convention. The opt-in has been verified with Next.js 16 (Turbopack) only;
+other bundlers do not inline that name by default.
 
 ### Guard your call sites
 
@@ -1073,10 +1147,12 @@ option to keep a third party's traffic out of the log.
 By default all of that is **in memory only**. Nothing is written to disk, and
 a reload starts clean.
 
-All of it is dev-only regardless. Capture is gated on
+All of it is dev-only unless you opt a build in. Capture is gated on
 `process.env.NODE_ENV === "development" && typeof window !== "undefined"`, and
 the database is opened only when the panel mounts — see
-[Production elimination](#production-elimination).
+[Production elimination](#production-elimination). A build made with
+`NEXT_PUBLIC_BLIX=true` captures exactly as development does, so everything in
+this section applies to whoever uses that build.
 
 ### What reaches disk, and when