@netkitty/analysis 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this package are documented here, following
+[Semantic Versioning](https://semver.org/). From the next release onward, entries
+are generated automatically from Conventional Commits.
+
+## 1.0.0 - 2026-07-22
+
+First stable release.
+
+- Streaming, Wireshark-style cross-packet analysis over a capture file
+  (conversations, endpoints, TCP streams) running off a worker.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alex Ma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/myq1991/netkitty/main/assets/NetKittyLogo.webp" alt="NetKitty" width="180">
+</p>
+
+# @netkitty/analysis
+
+Streaming, cross-packet analysis for capture files — a programmable, Wireshark-style front door over
+pcap/pcapng. The same `Analysis` facade runs in **node and the browser**: heavy work (read → parse →
+partial-decode → columnar index → decode) lives in a single worker, so `open()` never blocks the
+caller and `close()` releases everything by terminating the worker.
+
+> 中文文档见 [README.zh-CN.md](./README.zh-CN.md)。
+
+Built on [`@netkitty/codec`](../codec) (protocol decoding) and [`@netkitty/pcap-core`](../pcap-core)
+(pcap/pcapng parsing) — both pure-buffer and browser-safe.
+
+## Install
+
+```bash
+npm i @netkitty/analysis
+# or use the aggregate package: import ... from 'netkitty/analysis'
+```
+
+## Quick start (node)
+
+```ts
+import {Analysis, ConversationsReducer} from '@netkitty/analysis'
+
+const analysis = new Analysis()
+await analysis.open('/path/to/capture.pcap')      // bounded file: index, then emit 'complete'
+
+analysis.frameCount()                              // total frames indexed
+const rows = await analysis.getFrames(0, 100)      // lightweight rows (no decoded layers)
+const frame = await analysis.getFrame(42)          // one frame WITH decoded layers
+const tcp = await analysis.filter('tcp')           // matching frame indices
+
+const conversations = new ConversationsReducer()
+await analysis.attachReducer(conversations)        // replays every indexed frame, then follows live
+conversations.result()                             // rolling snapshot (no finalize)
+
+await analysis.close()                             // terminate the worker, release everything
+```
+
+## Reducers
+
+A reducer is a pluggable rolling analysis fed every frame; `result()` is a snapshot at any time (there
+is no finalize). `attachReducer` **replays** the whole indexed backlog first, then follows the live
+stream — so stats are complete the moment it resolves.
+
+- **Built-in** (exported): `ConversationsReducer`, `EndpointsReducer`, `TcpStreamReducer`
+  (retransmissions / duplicate ACKs / RTT). For Conversations/Endpoints prefer the shortcut methods
+  `analysis.conversations()` / `analysis.endpoints()` — they compute the same result **entirely inside
+  the worker** by scanning the index columns (no re-decode, no per-frame cross-thread transfer, zero
+  main-thread work), so they stay fast even at hundreds of millions of frames.
+- **Factories**: `reduceReducer(seed, fold)`, `groupByReducer(keyOf, seed, fold)`.
+- **Custom**: implement `IAnalysisReducer<T>` — see [Writing a custom reducer](#writing-a-custom-reducer).
+
+```ts
+import {reduceReducer, groupByReducer} from '@netkitty/analysis'
+
+const totalBytes = reduceReducer(0, (sum, frame) => sum + frame.length)
+const perProtocol = groupByReducer(f => f.topProtocol, 0, count => count + 1)
+```
+
+### Writing a custom reducer
+
+A reducer is a plain object (or class) implementing `IAnalysisReducer<T>`:
+
+```ts
+interface IAnalysisReducer<T> {
+  update(frame: Frame, context: UpdateContext): void  // called once per frame (replay, then live)
+  result(): T                                          // rolling snapshot — callable any time, no finalize
+  reset(): void                                        // clear all accumulated state
+  readonly needs?: string[]                            // optional: layer ids you read (projection)
+  readonly indexOnly?: boolean                         // optional: correctness/perf contract, see below
+}
+```
+
+- **`update(frame, context)`** runs for every frame. `frame` carries `index`, `timestamp`, `length`,
+  `topProtocol`, `conversationKey`, and `layers` (the decoded protocol tree). `context` carries `index`,
+  `total`, and `phase` — `'replay'` while catching up on the already-indexed backlog, `'live'` while
+  tailing under `watch()`.
+- **`result()`** is a rolling snapshot; there is **no finalize**, so call it whenever (mid-replay,
+  mid-tail). **`reset()`** clears state.
+- Keep state bounded **per conversation/endpoint**, not per frame — the built-ins hold a first/last
+  index span instead of a member-frame list, so memory stays flat across hundreds of millions of frames.
+- **`needs`** (optional): the layer ids you actually read, e.g. `['ipv4', 'tcp']`. The worker then
+  transfers only those layers across the thread boundary instead of the whole tree — pure bandwidth win,
+  no behavioural change.
+- **`indexOnly`** (optional — a **correctness contract**, not just a hint): set `true` **only if**
+  `update` reads nothing beyond frame metadata (`index` / `timestamp` / `length` / `topProtocol` /
+  `conversationKey`) and the five-tuple carried in `layers` — the endpoint addresses and ports
+  (`eth` `smac`/`dmac`, `ipv4`/`ipv6` `sip`/`dip`, `tcp`/`udp` `srcport`/`dstport`). Replay then feeds
+  frames **synthesized straight from the index columns, skipping the per-frame re-decode** — measured
+  ~13× faster on large captures. ⚠️ If you set it while reading any deeper field (`ipv4.ttl`,
+  `tcp.flags`, TLS SNI, payload …), that field is simply **absent** on replay and your result is
+  silently wrong. When unsure, leave it unset — full decode is the safe default. `ConversationsReducer`
+  and `EndpointsReducer` set it (five-tuple only); `TcpStreamReducer` does not (it reads seq/ack/flags).
+
+```ts
+import {IAnalysisReducer, Frame, UpdateContext} from '@netkitty/analysis'
+
+//Counts frames per top-level protocol. Reads only metadata → indexOnly is safe.
+class ProtocolCounter implements IAnalysisReducer<Record<string, number>> {
+  readonly indexOnly = true
+  #counts: Record<string, number> = {}
+  update(frame: Frame, _context: UpdateContext): void {
+    this.#counts[frame.topProtocol] = (this.#counts[frame.topProtocol] ?? 0) + 1
+  }
+  result(): Record<string, number> { return {...this.#counts} }
+  reset(): void { this.#counts = {} }
+}
+```
+
+A reducer runs **on the main thread** — its `update` is a function, so it can't be copied into the
+worker to run there. That is fine: `update` is just cheap arithmetic; the expensive part (read + decode)
+already happened in the worker, and `indexOnly`/`needs` decide how much of that data is sent back. A
+reducer may also extend an event emitter and push its own `progress`/`update` events from `update()`.
+
+## Live capture (watch)
+
+`watch()` follows a capture file that is still being written, feeding each new frame to reducers with
+phase `'live'`. The index is **unbounded by default** (the memory is yours to manage). `maxFrames` is an
+optional guard: once the index passes the cap, the oldest entries are dropped first-in-first-out
+(a Wireshark-style ring buffer), keeping a long-running tail bounded — only the in-memory index is
+dropped, the file on disk is untouched.
+
+```ts
+const analysis = new Analysis()                         // default: unbounded index
+analysis.on('frame', row => { /* new indexed frame */ })
+await analysis.watch('/path/to/growing.pcap')           // tails the file; reducers get phase 'live'
+
+// optional memory guard for a long-running tail:
+// new Analysis({maxFrames: 1_000_000})  // FIFO-evict the oldest past the cap → bounded memory
+```
+
+## Browser
+
+The facade is environment-agnostic — inject a browser worker channel; the worker is a bundled
+`analysisWorkerBrowser` entry (esbuild + Buffer polyfill), and the source is a `File`/`Blob`:
+
+```ts
+import {Analysis, WebWorkerChannel} from '@netkitty/analysis'
+
+const worker = new Worker(/* bundled analysisWorkerBrowser.js */)
+const analysis = new Analysis({}, () => new WebWorkerChannel(worker))
+await analysis.open(file)   // file: a File/Blob
+```
+
+node and browser produce field-for-field identical results.

package/README.zh-CN.md

@@ -0,0 +1,146 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/myq1991/netkitty/main/assets/NetKittyLogo.webp" alt="NetKitty" width="180">
+</p>
+
+# @netkitty/analysis
+
+对抓包文件做流式的跨包分析——一个可编程的、类似 Wireshark 的 pcap/pcapng 入口。同一个 `Analysis` 类
+**在 Node 和浏览器里都能用**:读取、解析、部分解码、建立索引这些重活都放在一个后台工作线程里做,所以
+`open()` 不会卡住调用方,`close()` 只要结束这个线程,就能把占用的内存一次性全部释放。
+
+> English docs: [README.md](./README.md)
+
+它底层用到 [`@netkitty/codec`](../codec)(协议解码)和 [`@netkitty/pcap-core`](../pcap-core)
+(pcap/pcapng 解析),两者都只处理内存里的字节,可以安全地在浏览器中运行。
+
+## 安装
+
+```bash
+npm i @netkitty/analysis
+# 或者用聚合包:import ... from 'netkitty/analysis'
+```
+
+## 快速上手(Node)
+
+```ts
+import {Analysis, ConversationsReducer} from '@netkitty/analysis'
+
+const analysis = new Analysis()
+await analysis.open('/path/to/capture.pcap')      // 读一个完整文件:建好索引,完成后触发 'complete'
+
+analysis.frameCount()                              // 已索引的总帧数
+const rows = await analysis.getFrames(0, 100)      // 轻量的帧行(不含解码后的各层)
+const frame = await analysis.getFrame(42)          // 单帧,含解码后的各层
+const tcp = await analysis.filter('tcp')           // 命中的帧序号
+
+const conversations = new ConversationsReducer()
+await analysis.attachReducer(conversations)        // 先把已索引的历史帧全部重放,再跟随后续实时帧
+conversations.result()                             // 随时取当前结果(没有收尾这一步)
+
+await analysis.close()                             // 结束工作线程,释放全部内存
+```
+
+## 什么是 reducer
+
+reducer 是一个可插拔的、"边读边算"的统计器:每来一帧都会喂给它,你随时都能用 `result()` 拿到当前的
+统计结果(没有"结束/收尾"这一步)。调用 `attachReducer` 时,它会先把已经建好索引的历史帧整个重放一遍,
+再继续跟着后续的新帧走——所以这个方法一返回,统计结果就已经是完整的("一打开,统计就在那儿")。
+
+- **内置(已导出)**:`ConversationsReducer`、`EndpointsReducer`、`TcpStreamReducer`
+  (统计重传、重复 ACK、往返时延)。其中会话表和端点表建议直接用快捷方法 `analysis.conversations()`
+  和 `analysis.endpoints()`——它们**全程在工作线程里**扫描索引列算出同样的结果,不重新解码、不逐帧在
+  线程之间搬数据、主线程几乎不干活,所以哪怕上亿帧也很快。
+- **便利工厂**:`reduceReducer(seed, fold)`、`groupByReducer(keyOf, seed, fold)`,用来快速拼一个
+  简单的 reducer。
+- **自定义**:实现 `IAnalysisReducer<T>` 接口——见下面的[编写自定义 reducer](#编写自定义-reducer)。
+
+```ts
+import {reduceReducer, groupByReducer} from '@netkitty/analysis'
+
+const totalBytes = reduceReducer(0, (sum, frame) => sum + frame.length)
+const perProtocol = groupByReducer(f => f.topProtocol, 0, count => count + 1)
+```
+
+### 编写自定义 reducer
+
+一个 reducer 就是实现了 `IAnalysisReducer<T>` 的普通对象或类:
+
+```ts
+interface IAnalysisReducer<T> {
+  update(frame: Frame, context: UpdateContext): void  // 每来一帧调用一次(先重放历史,再走实时)
+  result(): T                                          // 随时取当前结果,没有收尾这一步
+  reset(): void                                        // 清空已累积的状态
+  readonly needs?: string[]                            // 可选:声明你会用到哪几层协议
+  readonly indexOnly?: boolean                         // 可选:一条关乎正确性的约定,见下文
+}
+```
+
+- **`update(frame, context)`**:每来一帧调用一次。`frame` 里有 `index`、`timestamp`、`length`、
+  `topProtocol`、`conversationKey`,以及 `layers`(解码好的各层协议)。`context` 里有 `index`、
+  `total` 和 `phase`——重放历史帧时是 `'replay'`,用 `watch()` 跟读实时流时是 `'live'`。
+- **`result()`**:随时都能调,返回当前这一刻的统计结果,没有收尾这一步。**`reset()`**:清空已累积的
+  状态。
+- 累积状态时请按**会话或端点**来聚合,不要一帧一条地堆。内置 reducer 只记录每个会话首帧和末帧的序号,
+  而不是把所有成员帧列出来,所以就算几亿帧,内存占用也基本是平的。
+- **`needs`(可选)**:声明你真正会读到的协议层,比如 `['ipv4', 'tcp']`。这样工作线程只把这几层的
+  数据回传给你,而不是整棵协议树——纯粹省流量,不影响结果。
+- **`indexOnly`(可选,是一条关乎正确性的约定,不只是性能开关)**:只有当你的 `update` 除了帧的基本
+  信息(`index`、`timestamp`、`length`、`topProtocol`、`conversationKey`)之外,**只读取五元组**——
+  也就是收发双方的地址和端口(`eth` 的 `smac`/`dmac`,`ipv4`/`ipv6` 的 `sip`/`dip`,`tcp`/`udp`
+  的 `srcport`/`dstport`)——时,才可以设成 `true`。设成 `true` 之后,重放历史帧会直接用索引列拼出
+  帧、跳过逐帧重新解码,实测在大文件上快大约 13 倍。⚠️ 但如果你设了 `true`,却又读了更深的字段(比如
+  `ipv4.ttl`、`tcp.flags`、TLS 的 SNI、载荷等),这些字段在重放时是**取不到的**,结果会悄悄算错。
+  拿不准就别设,默认走完整解码最稳妥。内置的 `ConversationsReducer` 和 `EndpointsReducer` 设了它
+  (只用五元组);`TcpStreamReducer` 没设(因为它要读序列号、确认号、标志位)。
+
+```ts
+import {IAnalysisReducer, Frame, UpdateContext} from '@netkitty/analysis'
+
+// 按顶层协议统计帧数。只读基本信息,所以设 indexOnly 是安全的。
+class ProtocolCounter implements IAnalysisReducer<Record<string, number>> {
+  readonly indexOnly = true
+  #counts: Record<string, number> = {}
+  update(frame: Frame, _context: UpdateContext): void {
+    this.#counts[frame.topProtocol] = (this.#counts[frame.topProtocol] ?? 0) + 1
+  }
+  result(): Record<string, number> { return {...this.#counts} }
+  reset(): void { this.#counts = {} }
+}
+```
+
+reducer 是跑在**主线程**上的——它的 `update` 是个函数,没办法被复制到工作线程里去执行。这不要紧:
+`update` 本身只是些很轻的加加减减;真正费时的读取和解码早在工作线程里做完了,而 `indexOnly` 和 `needs`
+决定了其中有多少数据要回传到主线程。如果需要,reducer 还可以顺带继承一个事件发射器,在 `update()`
+里推送自己的 `progress`/`update` 事件。
+
+## 实时抓包(watch)
+
+`watch()` 会持续跟读一个还在不断写入的抓包文件,把每一新帧以 `'live'` 阶段喂给 reducer。索引**默认
+不设上限**(内存多少由你自己把控)。`maxFrames` 是一个可选的内存护栏:一旦超过这个数,就按先进先出的
+方式淘汰最老的索引条目(类似 Wireshark 的环形缓冲),让长时间跟读也能把内存控制住——注意这只丢内存里
+的索引,磁盘上的原始文件不受影响。
+
+```ts
+const analysis = new Analysis()                         // 默认:索引不设上限
+analysis.on('frame', row => { /* 新索引到的一帧 */ })
+await analysis.watch('/path/to/growing.pcap')           // 跟读文件;reducer 收到 'live' 阶段
+
+// 长时间跟读时的可选内存护栏:
+// new Analysis({maxFrames: 1_000_000})  // 超出上限就先进先出淘汰最老的帧 → 内存有上限
+```
+
+## 浏览器
+
+`Analysis` 这个入口本身不依赖具体运行环境——你只要给它注入一个浏览器版的工作线程通道就行。这个工作线程
+是打包好的 `analysisWorkerBrowser` 入口(用 esbuild 打包,并带上 Buffer 垫片),数据源换成 `File`
+或 `Blob`:
+
+```ts
+import {Analysis, WebWorkerChannel} from '@netkitty/analysis'
+
+const worker = new Worker(/* 打包后的 analysisWorkerBrowser.js */)
+const analysis = new Analysis({}, () => new WebWorkerChannel(worker))
+await analysis.open(file)   // file 是一个 File/Blob
+```
+
+Node 和浏览器下算出来的结果逐字段完全一致。

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Streaming capture-file analysis — the Analysis facade over a single worker, pluggable reducers, a
+ * display filter, and the pluggable backend seams. node (worker_threads) and browser (Web Worker)
+ * share one environment-agnostic API, verified field-for-field in both.
+ */
+export { Analysis } from './lib/streaming/Analysis';
+export type { AnalysisOptions } from './lib/streaming/types/AnalysisOptions';
+export type { AnalysisSource } from './lib/streaming/types/AnalysisSource';
+export type { AnalysisEvents } from './lib/streaming/types/AnalysisEvents';
+export type { AnalysisPhase } from './lib/streaming/types/AnalysisPhase';
+export type { UpdateContext } from './lib/streaming/types/UpdateContext';
+export type { Frame } from './lib/streaming/types/Frame';
+export type { FrameRow } from './lib/streaming/types/FrameRow';
+export type { FrameIndexRecord } from './lib/streaming/types/FrameIndexRecord';
+export type { IAnalysisReducer } from './lib/streaming/interfaces/IAnalysisReducer';
+export type { IReadBackend } from './lib/streaming/interfaces/IReadBackend';
+export type { IWorkerChannel } from './lib/streaming/interfaces/IWorkerChannel';
+export type { IIndexStore } from './lib/streaming/interfaces/IIndexStore';
+/**
+ * Built-in reducers (exported, not baked into Analysis) — attach them for Wireshark-style stats.
+ */
+export { ConversationsReducer } from './lib/streaming/reducers/ConversationsReducer';
+export type { ConversationSummary } from './lib/streaming/reducers/ConversationsReducer';
+export { EndpointsReducer } from './lib/streaming/reducers/EndpointsReducer';
+export type { EndpointSummary } from './lib/streaming/reducers/EndpointsReducer';
+export { TcpStreamReducer } from './lib/streaming/reducers/TcpStreamReducer';
+export type { RttSample, TcpStreamDiagnostic } from './lib/streaming/reducers/TcpStreamReducer';
+export { reduceReducer, groupByReducer } from './lib/streaming/reducers/ReducerFactories';
+export { parseFilter, matchesFilter, matchesIndexed, indexableEval } from './lib/streaming/filter/FilterExpression';
+export type { FilterExpression, FilterPredicate } from './lib/streaming/filter/FilterExpression';

package/dist/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.indexableEval = exports.matchesIndexed = exports.matchesFilter = exports.parseFilter = exports.groupByReducer = exports.reduceReducer = exports.TcpStreamReducer = exports.EndpointsReducer = exports.ConversationsReducer = exports.Analysis = void 0;
+/**
+ * Streaming capture-file analysis — the Analysis facade over a single worker, pluggable reducers, a
+ * display filter, and the pluggable backend seams. node (worker_threads) and browser (Web Worker)
+ * share one environment-agnostic API, verified field-for-field in both.
+ */
+var Analysis_1 = require("./lib/streaming/Analysis");
+Object.defineProperty(exports, "Analysis", { enumerable: true, get: function () { return Analysis_1.Analysis; } });
+/**
+ * Built-in reducers (exported, not baked into Analysis) — attach them for Wireshark-style stats.
+ */
+var ConversationsReducer_1 = require("./lib/streaming/reducers/ConversationsReducer");
+Object.defineProperty(exports, "ConversationsReducer", { enumerable: true, get: function () { return ConversationsReducer_1.ConversationsReducer; } });
+var EndpointsReducer_1 = require("./lib/streaming/reducers/EndpointsReducer");
+Object.defineProperty(exports, "EndpointsReducer", { enumerable: true, get: function () { return EndpointsReducer_1.EndpointsReducer; } });
+var TcpStreamReducer_1 = require("./lib/streaming/reducers/TcpStreamReducer");
+Object.defineProperty(exports, "TcpStreamReducer", { enumerable: true, get: function () { return TcpStreamReducer_1.TcpStreamReducer; } });
+var ReducerFactories_1 = require("./lib/streaming/reducers/ReducerFactories");
+Object.defineProperty(exports, "reduceReducer", { enumerable: true, get: function () { return ReducerFactories_1.reduceReducer; } });
+Object.defineProperty(exports, "groupByReducer", { enumerable: true, get: function () { return ReducerFactories_1.groupByReducer; } });
+var FilterExpression_1 = require("./lib/streaming/filter/FilterExpression");
+Object.defineProperty(exports, "parseFilter", { enumerable: true, get: function () { return FilterExpression_1.parseFilter; } });
+Object.defineProperty(exports, "matchesFilter", { enumerable: true, get: function () { return FilterExpression_1.matchesFilter; } });
+Object.defineProperty(exports, "matchesIndexed", { enumerable: true, get: function () { return FilterExpression_1.matchesIndexed; } });
+Object.defineProperty(exports, "indexableEval", { enumerable: true, get: function () { return FilterExpression_1.indexableEval; } });

package/dist/lib/streaming/Analysis.d.ts

@@ -0,0 +1,54 @@
+import { AnalysisOptions } from './types/AnalysisOptions';
+import { AnalysisSource } from './types/AnalysisSource';
+import { AnalysisEvents } from './types/AnalysisEvents';
+import { Frame } from './types/Frame';
+import { FrameRow } from './types/FrameRow';
+import { IAnalysisReducer } from './interfaces/IAnalysisReducer';
+import { IWorkerChannel } from './interfaces/IWorkerChannel';
+import { ConversationSummary } from './reducers/ConversationsReducer';
+import { EndpointSummary } from './reducers/EndpointsReducer';
+/**
+ * Capture-file analysis facade — a programmable Wireshark-style front door over a pcap/pcapng file.
+ * Environment-agnostic: it holds no fs/File/codec at runtime, only talks to a worker channel. Heavy
+ * work (read → parse → index → decode) lives in a single worker so open() never blocks the caller and
+ * close() releases everything by terminating it. The node channel factory is loaded lazily (require)
+ * so this module never statically imports worker_threads; a browser build injects its own factory.
+ */
+export declare class Analysis {
+    #private;
+    constructor(options?: AnalysisOptions, spawnChannel?: () => IWorkerChannel);
+    /** Read a bounded capture: build the frame index, emit 'complete'. Resolves once indexing finishes. */
+    open(source: AnalysisSource): Promise<void>;
+    /**
+     * Tail a capture being written live: the worker indexes appended frames continuously and pushes
+     * each one here, where it updates frameCount, emits a 'frame' row, and feeds every attached reducer
+     * with phase 'live'. Never emits 'complete'. Index memory is bounded by AnalysisOptions.maxFrames.
+     */
+    watch(source: AnalysisSource): Promise<void>;
+    /** Terminate the worker and release the index, cache, and parse state in one shot. */
+    close(): Promise<void>;
+    frameCount(): number;
+    /**
+     * Conversation table, computed inside the worker by scanning the index columns — no re-decode, no
+     * per-frame cross-thread transfer, no main-thread work. Equivalent to attaching a ConversationsReducer.
+     */
+    conversations(): Promise<ConversationSummary[]>;
+    /** Per-endpoint tx/rx totals, computed inside the worker over the index columns (see conversations()). */
+    endpoints(): Promise<EndpointSummary[]>;
+    /** A single frame with decoded layers (served through the worker's on-demand re-parse). */
+    getFrame(index: number): Promise<Frame | null>;
+    /** A range of lightweight rows (no decoded layers), for list display. Half-open [from, to). */
+    getFrames(from: number, to: number): Promise<FrameRow[]>;
+    /** Evaluate a display filter (v1 subset), returning the matching frame indices. */
+    filter(displayFilter: string): Promise<number[]>;
+    /**
+     * Attach a reducer and replay every already-indexed frame into it (phase 'replay'), so stats are
+     * complete the moment attach resolves — Wireshark-style "open the stats and they're already there".
+     * Frames are pulled from the worker in bounded batches. (watch live-feed is added with watch().)
+     */
+    attachReducer(reducer: IAnalysisReducer<unknown>): Promise<void>;
+    /** Detach a reducer: stop feeding it and drop the internal reference (its state is the caller's). */
+    detachReducer(reducer: IAnalysisReducer<unknown>): void;
+    on<E extends keyof AnalysisEvents>(event: E, listener: AnalysisEvents[E]): this;
+    off<E extends keyof AnalysisEvents>(event: E, listener: AnalysisEvents[E]): this;
+}

package/dist/lib/streaming/Analysis.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Analysis = void 0;
+//How many frames to pull per replay batch — bounds memory and back-pressures the worker naturally.
+const REPLAY_BATCH = 512;
+/**
+ * Capture-file analysis facade — a programmable Wireshark-style front door over a pcap/pcapng file.
+ * Environment-agnostic: it holds no fs/File/codec at runtime, only talks to a worker channel. Heavy
+ * work (read → parse → index → decode) lives in a single worker so open() never blocks the caller and
+ * close() releases everything by terminating it. The node channel factory is loaded lazily (require)
+ * so this module never statically imports worker_threads; a browser build injects its own factory.
+ */
+class Analysis {
+    #options;
+    #spawnChannel;
+    #channel = null;
+    #frameCount = 0;
+    #reducers = new Set();
+    #listeners = new Map();
+    constructor(options = {}, spawnChannel) {
+        this.#options = options;
+        this.#spawnChannel = spawnChannel !== undefined ? spawnChannel : () => {
+            //Lazy require keeps this module environment-agnostic — it never statically imports the
+            //node-only worker_threads channel (a browser build injects its own factory instead).
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const factory = require('./worker/spawnNodeAnalysisChannel');
+            return factory.spawnNodeAnalysisChannel();
+        };
+    }
+    /** Read a bounded capture: build the frame index, emit 'complete'. Resolves once indexing finishes. */
+    async open(source) {
+        const channel = this.#start();
+        const result = await channel.request('open', { source: source });
+        this.#frameCount = result.frameCount;
+    }
+    /**
+     * Tail a capture being written live: the worker indexes appended frames continuously and pushes
+     * each one here, where it updates frameCount, emits a 'frame' row, and feeds every attached reducer
+     * with phase 'live'. Never emits 'complete'. Index memory is bounded by AnalysisOptions.maxFrames.
+     */
+    async watch(source) {
+        const channel = this.#start();
+        channel.on('frame', (payload) => {
+            const frame = payload;
+            if (frame.index + 1 > this.#frameCount)
+                this.#frameCount = frame.index + 1;
+            const row = { index: frame.index, timestamp: frame.timestamp, length: frame.length, topProtocol: frame.topProtocol, conversationKey: frame.conversationKey, info: frame.info };
+            this.#emit('frame', row);
+            for (const reducer of this.#reducers) {
+                reducer.update(frame, { index: frame.index, total: this.#frameCount, phase: 'live' });
+            }
+        });
+        const result = await channel.request('watch', { source: source, maxFrames: this.#options.maxFrames });
+        if (result.frameCount > this.#frameCount)
+            this.#frameCount = result.frameCount;
+    }
+    /** Terminate the worker and release the index, cache, and parse state in one shot. */
+    async close() {
+        if (this.#channel) {
+            this.#channel.terminate();
+            this.#channel = null;
+        }
+        this.#frameCount = 0;
+    }
+    frameCount() {
+        return this.#frameCount;
+    }
+    /**
+     * Conversation table, computed inside the worker by scanning the index columns — no re-decode, no
+     * per-frame cross-thread transfer, no main-thread work. Equivalent to attaching a ConversationsReducer.
+     */
+    async conversations() {
+        return this.#require().request('conversations');
+    }
+    /** Per-endpoint tx/rx totals, computed inside the worker over the index columns (see conversations()). */
+    async endpoints() {
+        return this.#require().request('endpoints');
+    }
+    /** A single frame with decoded layers (served through the worker's on-demand re-parse). */
+    async getFrame(index) {
+        return this.#require().request('getFrame', { index: index });
+    }
+    /** A range of lightweight rows (no decoded layers), for list display. Half-open [from, to). */
+    async getFrames(from, to) {
+        return this.#require().request('getFrames', { from: from, to: to });
+    }
+    /** Evaluate a display filter (v1 subset), returning the matching frame indices. */
+    async filter(displayFilter) {
+        return this.#require().request('filter', { displayFilter: displayFilter });
+    }
+    /**
+     * Attach a reducer and replay every already-indexed frame into it (phase 'replay'), so stats are
+     * complete the moment attach resolves — Wireshark-style "open the stats and they're already there".
+     * Frames are pulled from the worker in bounded batches. (watch live-feed is added with watch().)
+     */
+    async attachReducer(reducer) {
+        const channel = this.#require();
+        this.#reducers.add(reducer);
+        const needs = reducer.needs;
+        const indexOnly = reducer.indexOnly === true;
+        const total = this.#frameCount;
+        for (let from = 0; from < total; from += REPLAY_BATCH) {
+            const to = Math.min(from + REPLAY_BATCH, total);
+            const frames = await channel.request('getFrameBatch', { from: from, to: to, needs: needs, indexOnly: indexOnly });
+            for (const frame of frames) {
+                const context = { index: frame.index, total: total, phase: 'replay' };
+                reducer.update(frame, context);
+            }
+        }
+    }
+    /** Detach a reducer: stop feeding it and drop the internal reference (its state is the caller's). */
+    detachReducer(reducer) {
+        this.#reducers.delete(reducer);
+    }
+    on(event, listener) {
+        let set = this.#listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.#listeners.set(event, set);
+        }
+        set.add(listener);
+        return this;
+    }
+    off(event, listener) {
+        this.#listeners.get(event)?.delete(listener);
+        return this;
+    }
+    #start() {
+        const channel = this.#spawnChannel();
+        this.#channel = channel;
+        channel.on('progress', (payload) => {
+            const p = payload;
+            this.#frameCount = p.frames;
+            this.#emit('progress', p.bytesRead, p.totalBytes);
+        });
+        channel.on('complete', (payload) => {
+            const c = payload;
+            this.#frameCount = c.frameCount;
+            this.#emit('complete');
+        });
+        channel.on('error', (payload) => {
+            this.#emit('error', payload instanceof Error ? payload : new Error(String(payload)));
+        });
+        return channel;
+    }
+    #require() {
+        if (!this.#channel)
+            throw new Error('Analysis has no open source; call open() or watch() first');
+        return this.#channel;
+    }
+    #emit(event, ...args) {
+        const set = this.#listeners.get(event);
+        if (!set)
+            return;
+        for (const listener of set)
+            listener(...args);
+    }
+}
+exports.Analysis = Analysis;

package/dist/lib/streaming/backends/BrowserFileReadBackend.d.ts

@@ -0,0 +1,14 @@
+import { IReadBackend } from '../interfaces/IReadBackend';
+/**
+ * Browser IReadBackend over a File/Blob: Blob.slice gives random access (for on-demand re-parsing)
+ * and a chunked async iterator (for index building), both via arrayBuffer(). A Blob is immutable, so
+ * there is nothing to tail (watch is absent) and no handle to release (close is absent). Works in any
+ * environment with the Blob API — node (>=18) included, which is how it is unit-tested.
+ */
+export declare class BrowserFileReadBackend implements IReadBackend {
+    #private;
+    constructor(source: Blob, chunkSize?: number);
+    size(): Promise<number>;
+    read(offset: number, length: number): Promise<Uint8Array>;
+    createStream(): AsyncIterableIterator<Uint8Array>;
+}

package/dist/lib/streaming/backends/BrowserFileReadBackend.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserFileReadBackend = void 0;
+/**
+ * Browser IReadBackend over a File/Blob: Blob.slice gives random access (for on-demand re-parsing)
+ * and a chunked async iterator (for index building), both via arrayBuffer(). A Blob is immutable, so
+ * there is nothing to tail (watch is absent) and no handle to release (close is absent). Works in any
+ * environment with the Blob API — node (>=18) included, which is how it is unit-tested.
+ */
+class BrowserFileReadBackend {
+    #blob;
+    #chunkSize;
+    constructor(source, chunkSize = 1 << 16) {
+        this.#blob = source;
+        this.#chunkSize = chunkSize;
+    }
+    async size() {
+        return this.#blob.size;
+    }
+    async read(offset, length) {
+        const slice = this.#blob.slice(offset, offset + length);
+        return new Uint8Array(await slice.arrayBuffer());
+    }
+    async *createStream() {
+        let position = 0;
+        while (position < this.#blob.size) {
+            const slice = this.#blob.slice(position, position + this.#chunkSize);
+            const bytes = new Uint8Array(await slice.arrayBuffer());
+            if (bytes.length === 0)
+                break;
+            position += bytes.length;
+            yield bytes;
+        }
+    }
+}
+exports.BrowserFileReadBackend = BrowserFileReadBackend;