npm - @hakam-aldeen-kh/blix - Versions diffs - 0.3.3 → 0.4.1 - Mend

@hakam-aldeen-kh/blix 0.3.3 → 0.4.1

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 (3) hide show

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,129 @@
+# Changelog
+All notable changes to this project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.4.1] - 2026-08-24
+### Changed
+- Documentation only — no code change.
+- Added a Security section documenting what Blix captures, what reaches
+  IndexedDB and when, the four redacted header names, retention limits and
+  how to purge.
+- Documented `preserve-log`: its default, the three toggles, and that
+  switching it on writes the session already in the buffer.
+- Corrected the `dbName` section, which claimed the log persists across a
+  reload by default. It does not — persistence is opt-in.
+- Noted that the package is ESM-only.
+- Added `SECURITY.md`.
+## [0.4.0] - 2026-08-24
+Identical in code to 0.3.3. It exists only to correct the version number: 0.3.3
+was a feature release with a type-level break and should never have been a patch
+bump. 0.3.3 is deprecated on npm in favour of this release. Everything below is
+new relative to 0.3.2, not to 0.3.3.
+### Added
+- Twelve panel themes, behind a new toolbar button. Dark: Midnight (default),
+  Carbon, Nord, Tokyo Night, One Dark, Mocha, Dracula, Gruvbox. Light: Daylight,
+  GitHub, Latte, Solar. Hovering or arrow-keying an entry applies it to the panel
+  behind the menu; moving away restores the previous one. The default preference
+  is `auto`, which follows the host app's light/dark class on `<html>`. The
+  choice is persisted with the panel's other preferences.
+- A format switch on every payload pane — Tree, Table, JSON, YAML, Text. It
+  applies to request and response bodies, realtime frames, the encrypted
+  envelope, Redux actions and both Redux state views. Copy returns whichever
+  format is on screen (Table copies CSV, YAML copies YAML). The choice is
+  persisted.
+- Folding in the JSON view, with a **Collapse all** action; Alt-click in the Tree
+  expands or collapses an entire subtree.
+- Keyboard navigation in the payload tree (arrow keys to move, expand, collapse
+  and step in/out; Enter to toggle) and in menus (arrows, Home/End, Enter, and
+  Esc to close and return focus to the button that opened it). The `?` cheatsheet
+  documents both, plus the theme picker and the formats.
+- An export menu with six formats — HAR, JSON, NDJSON, Markdown table (to the
+  clipboard), CSV and a cURL script — and a **Shown** / **All** scope toggle that
+  shows both counts. Export previously always took the unfiltered buffer,
+  whatever the list was showing; Shown is now the default. CSV is written with a
+  UTF-8 BOM so Excel reads non-ASCII correctly.
+- A store slice picker on the Redux **State** tab. It opens on the slice the
+  selected action wrote to when the action touched exactly one, marks every slice
+  the action changed, and keeps `root` selectable.
+- **Copy as fetch** in the row context menu, alongside Copy as cURL.
+- Horizontal scrolling for the tab row and the slice picker when they overflow,
+  with edge fades, wheel support and arrow buttons.
+- Accessible names and pressed/expanded state on the toolbar controls, and
+  tab/tablist roles on the tab and slice strips.
+### Changed
+- The **Preview** and **Response** tabs are merged into a single **Response**
+  tab. Both previously rendered the same field — one as a tree, one as raw JSON —
+  so the rendering is now chosen with the format switch instead of by picking a
+  tab.
+- `MonitorPrefs`, exported from `@hakam-aldeen-kh/blix/capture`, gained two
+  required fields: `theme: string` and `dataFormat: string`. This is a
+  compile-time break for anyone constructing a `MonitorPrefs` object literal.
+  `BlixProps` and every function signature in `/capture` are unchanged.
+- HAR download filename: `network-<timestamp>.har` → `blix-<timestamp>.har`.
+  Every other export uses the same `blix-<timestamp>.<ext>` form.
+- A press anywhere outside an open menu now dismisses it, including inside the
+  panel; previously only a press outside the panel root did, so a menu left open
+  over the panel could only be closed with Esc or its own button. The press is
+  not swallowed — it still selects the row or activates the button underneath.
+- The status bar and the detail pane's empty states name what a row is in the
+  active section — requests, connections, actions or queries — instead of calling
+  every row a "request".
+- Every colour the panel paints now comes from the active theme's tokens: status
+  colours, method and section accents, waterfall bars, timing segments and JSON
+  syntax highlighting. The previous split, with a light palette in CSS and a
+  duplicate dark one in JS, is gone.
+- WebSocket, Redux and Query rows take their section's accent colour rather than
+  the shared fallback that HTTP verbs fell through to.
+- The docked badge reads "Blix" rather than "Dev", and the toolbar shows a BLIX
+  wordmark beside the status dot.
+### Fixed
+- Generated downloads revoke their object URL on the next task instead of
+  immediately after the click, which could race the browser's read of the blob
+  and save an empty file in Safari.
+## [0.3.3] - 2026-08-24 — DEPRECATED
+Released in error as a patch bump: it was a feature release that also added two
+required fields to the publicly exported `MonitorPrefs` type. Superseded by
+0.4.0, which is identical in code. Deprecated on npm — use 0.4.0. Its contents
+are listed under 0.4.0.
+## [0.3.2] - 2026-08-19
+### Added
+- `./package.json` as an export subpath, a top-level `types` field, `engines`
+  declaring Node >= 18, and package metadata (repository, homepage, bugs,
+  keywords).
+### Changed
+- `peerDependencies` narrowed from `*` to `axios ^1.0.0`,
+  `@reduxjs/toolkit ^2.0.0` and `@tanstack/react-query ^5.0.0`. Narrowing a peer
+  range is breaking by convention and this shipped as a patch — though 0.3.2 was
+  the first version on the public npm registry, so no npm consumer could have
+  been affected.
+- License: `UNLICENSED` → MIT.
+- Published to the public npm registry instead of GitHub Packages.
+### Fixed
+- `tapQueryClient`'s disposer now clears the client's internal tapped mark. A
+  dispose-then-reinstall cycle — exactly what React Strict Mode does to an effect
+  returning this disposer — hit the idempotency guard and became a permanent
+  no-op, leaving the Query tab silently empty for the rest of the session.
+Versions before 0.3.2 were published to GitHub Packages and are not available on the public npm registry.

package/README.md CHANGED Viewed

@@ -1,4 +1,5 @@
 # @hakam-aldeen-kh/blix
+[![npm](https://img.shields.io/npm/v/@hakam-aldeen-kh/blix)](https://www.npmjs.com/package/@hakam-aldeen-kh/blix)
 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
@@ -7,6 +8,8 @@ a dockable panel with a waterfall, 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).
 ---
 ## Install
@@ -29,6 +32,13 @@ while resolving that import. devDependencies have to be present at build time.
 Dropping them from the final runtime image is fine: nothing from Blix reaches
 the production output anyway.
+The package ships **ESM only**. Both entry points declare `"types"` and
+`"import"` in `exports`, with no `"require"` and no `"default"` fallback, so
+`require("@hakam-aldeen-kh/blix")` and CJS-only tooling — an older Jest config
+is the usual one — fail with `ERR_PACKAGE_PATH_NOT_EXPORTED`. That is by
+design, not a packaging bug: a dev tool that is eliminated from production has
+no reason to carry a second build output.
 ### Peer dependencies
 `react` and `react-dom` (v19) are required. `axios`, `@reduxjs/toolkit` and
@@ -348,12 +358,14 @@ as a bounded hex preview plus byte length). They go through the same
 serialization and truncation rules as the plaintext bodies, both in the panel
 and in IndexedDB, so a multi-megabyte ciphertext cannot blow out the log.
-> **Redaction.** Blix masks sensitive *headers* (`authorization`, `cookie`, …).
-> It does **not**, and cannot, redact anything inside the values you pass here
-> — they are bodies, and Blix has no way to tell ciphertext from plaintext. If
-> you pass an already-decrypted body as `response`, whatever secrets it
-> contains are shown in the panel verbatim and written to IndexedDB when
-> preserve-log is on. Pass the wire form, not the decrypted one.
+> **Redaction.** Blix masks sensitive *headers* — and the list is closed at
+> exactly four, matched exactly: `authorization`, `cookie`, `set-cookie`,
+> `x-api-key`. It does **not**, and cannot, redact anything inside the values
+> you pass here — they are bodies, and Blix has no way to tell ciphertext from
+> plaintext. If you pass an already-decrypted body as `response`, whatever
+> secrets it contains are shown in the panel verbatim and written to IndexedDB
+> when preserve-log is on. Pass the wire form, not the decrypted one. See
+> [Security](#security) for the full picture.
 #### `withInitiatorCapture(instance)`
@@ -681,11 +693,15 @@ There is no API for adding your own; a theme is ~20 colours in
 ### `dbName` — when you need it
-The panel persists its log to IndexedDB so it survives a reload. IndexedDB is
-scoped **per origin**, not per app — so two apps served from the same origin
-(different ports in dev are different origins, but path-based routing,
-multi-zone Next.js setups and anything behind one reverse proxy are not) both
-open `nm-devtools` and interleave their logs into one database.
+The panel can persist its log to IndexedDB so it survives a reload, but only
+when you opt in: **preserve-log is off by default**, and while it is off
+nothing is written to disk. See [Security](#security) for what the toggle does
+and what lands there.
+IndexedDB is scoped **per origin**, not per app — so two apps served from the
+same origin (different ports in dev are different origins, but path-based
+routing, multi-zone Next.js setups and anything behind one reverse proxy are
+not) both open `nm-devtools` and interleave their logs into one database.
 Give each app its own name to keep them separate:
@@ -785,6 +801,156 @@ example above, which is written in the guarded form.
 ---
+## Security
+Blix is a debugger, and it captures what a debugger has to capture: **full
+request and response bodies, request and response headers, Redux action
+payloads and state diffs, and realtime frames**. It captures them in
+plaintext — the request body *before* your encryption interceptor runs, the
+response body *after* your decryption interceptor. That is the whole point of
+it, and it means the log holds whatever your traffic holds, credentials
+included.
+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
+`process.env.NODE_ENV === "development" && typeof window !== "undefined"`, and
+the database is opened only when the panel mounts — see
+[Production elimination](#production-elimination).
+### What reaches disk, and when
+**Preserve-log** is the sole gate on disk writes. It is off by default, and
+while it is off nothing Blix captures reaches IndexedDB — the store is
+actively cleared on every panel mount.
+Three ways to toggle it:
+| Where | Note |
+| --- | --- |
+| Toolbar button | Hidden in the compact layout |
+| **⋯ More actions** overflow menu | Always available |
+| `Shift+L` | Always available |
+**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
+session you have *already* captured — to disk immediately, along with
+everything that follows. If you have just reproduced a login flow and then
+reach for the toggle, you have written that login flow to disk. Read that
+again before you assume otherwise; it is the one behaviour here that
+reasonably surprises people.
+With preserve-log on, this is what is kept:
+| Captured | Persisted |
+| --- | --- |
+| HTTP entries — bodies, headers, timings | yes |
+| Realtime frames | yes |
+| The encrypted envelope, if you call `captureEncrypted` | yes |
+| Panel preferences and budget totals | yes — preferences are also mirrored to `localStorage` |
+| Redux actions, payloads and diffs | only if you pin the row |
+| Query cache rows | only if you pin the row |
+### What is redacted
+Exactly four header names, and nothing else:
+| Header | Match |
+| --- | --- |
+| `authorization` | exact, case-insensitive |
+| `cookie` | exact, case-insensitive |
+| `set-cookie` | exact, case-insensitive |
+| `x-api-key` | exact, case-insensitive |
+The match is **exact on the full header name** — not a prefix, not a
+substring, not a pattern. Near-miss names are *not* covered and are written in
+the clear: `x-auth-token` and `api-key` are the two that most often catch
+people out, and `proxy-authorization`, `x-csrf-token` and
+`x-amz-security-token` are equally uncovered. If your auth travels in a header
+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.
+**Nothing inside a body is redacted.** Request bodies, response bodies, error
+payloads, the encrypted request/response values, Redux payloads and diffs, and
+realtime frames all pass through a size-only walker — it truncates large
+values and never once inspects a key name. A `password`, `ssn` or
+`refreshToken` field is captured, and with preserve-log on written to disk,
+exactly as it appears. Blix has no mechanism to do otherwise: it has no schema
+for your payloads and no way to tell a secret from any other string.
+### Retention and clearing
+| Bound | Value |
+| --- | --- |
+| Records | 200 |
+| Total size | 24 MB |
+| Per payload field | 512 KB |
+| Eviction | oldest first, once either bound is exceeded |
+| Time-based expiry | none |
+There is **no TTL of any kind**. A record leaves the database when 200 newer
+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).
+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.
+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.
+**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.
+### Threat model
+IndexedDB is scoped **per origin, not per app**, and it is not encrypted at
+rest. Any script running on that origin can read Blix's database — including
+browser extension content scripts with access to the origin. Whatever you
+capture is readable by whatever you have installed.
+Export and copy move captured data out of the browser entirely:
+| Path | Carries |
+| --- | --- |
+| 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 |
+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.
+### If you handle sensitive data
+- **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.
+- **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).
+- **Treat an exported HAR as a credential-bearing file.** Do not attach one to
+  a public issue, and do not commit one.
+---
 ## Entry points
 | Import | Contents | `"use client"` |

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@hakam-aldeen-kh/blix",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "Dev-tools panel for React apps — HTTP, Redux, Query and Realtime monitoring.",
   "keywords": [
     "devtools",
@@ -63,7 +63,8 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18"