| FazBrowse GitHub Viewer | Trending | | Home |
| Tools: [Download Repo ZIP] [Original HTTPS Page] |
| Name | Name | Last commit date | ||
|---|---|---|---|---|
ReplayCase makes constrained telemetry incidents reproducible.
ReplayCase records live UDP or serial telemetry through an identified, content-addressed decoder pack, turns the capture into an immutable local replay, and provides a synchronized incident-review workspace. Every new capture carries the exact pack and runtime identity alongside durable transport anomalies, explicit endpoint or device provenance, a capture-scoped bridge journal where applicable, and a terminal integrity receipt. One playhead based on integer microsecond offsets drives link health, packet families, decoder state, diagnostics, markers, and decoded signals; the selected interval can then be exported as a reproducible evidence bundle. A receiving engineer can verify that untrusted bundle in the application and continue from the exact included incident without needing the original replay or capture laptop.
The application is local-first. The packaged distribution starts the production workspace and authenticated UDP bridge together on loopback; the browser uses a same-origin application relay, while the bridge credential remains internal to the managed process and never requires operator copying. Its UDP socket binds the operator-selected interface. Serial ingest uses the browser's Web Serial connection. Capture, saved sessions, worker-isolated replay processing, annotations, comparison, evidence generation, and receiver verification stay on the operator's or receiving engineer's machine. ReplayCase has no telemetry upload, cloud account, or hosted dependency.
Upgrading from NarrowsLink? Follow the rename migration before installing. ReplayCase retains the same local storage and evidence formats.
ReplayCase v0.4.0 is a self-contained package with zero runtime npm dependencies. It contains the production UI, managed UDP bridge, deterministic Harbor relay fixture, decoder-pack tools, application and CLI evidence receivers, and comparison workflow. It requires Node.js 20.19 or newer, but it does not require a repository checkout, Vite, or project dependencies.
Download these four assets from the v0.4.0 GitHub Release:
On macOS, verify the assets, install the package without lifecycle scripts, confirm its identity, and start the application:
shasum -a 256 -c SHA256SUMS
npm install --global ./replaycase-0.4.0.tgz --ignore-scripts
replaycase version --json
replaycase serveOn GNU/Linux, use sha256sum -c SHA256SUMS for the checksum step.
replaycase serve opens the production application at http://127.0.0.1:47890/ and starts its authenticated bridge in the same managed process. The UI discovers the bridge and UDP defaults automatically; no token, manual URL, second terminal, source tree, or external network service is required. Press Ctrl+C in the serving terminal to stop both the application server and bridge cleanly.
The external release manifest identifies the exact version, commit, source tree, build epoch, toolchain, lockfile, and packaged-file hashes. The CycloneDX SBOM describes the shipped application, and SHA256SUMS covers the package, manifest, and SBOM. These same-channel checks establish byte consistency, not independent publisher or build-environment authenticity.
Continue with the guided first run.
ReplayCase currently supports five end-to-end operator outcomes:
| ID | Use case | Primary output |
|---|---|---|
| UC-001 | Record live field telemetry | Version 2 .nlsession |
| UC-002 | Investigate a recorded telemetry fault | Exact operator-authored incident range |
| UC-003 | Audit capture-path integrity | Integrity assessment and transport evidence |
| UC-004 | Compare captures and prove regressions | Checksummed .nlcompare.json finding |
| UC-005 | Hand off a verifiable incident bundle | .nlb archive and verified receiver workspace |
See the canonical use-case log for actors, supported workflows, current constraints, and implementation evidence.
ReplayCase opens the bundled Harbor relay downlink replay automatically. An operator can replace it with a validated local file, reopen a saved session, or record live UDP or serial traffic. The normal capture-to-evidence path is:
For a controlled before-and-after investigation, select the baseline incident or open the received bundle, choose Compare, load the candidate session or bundle, and declare either range-start or shared-event alignment. ReplayCase compares only the aligned intersection, exposes unmatched tails and non-comparable evidence, and lets the operator export a separate finding that cites both exact inputs, ranges, decoder identities, metric evidence, limitations, and the authored conclusion.
The user guide provides the full procedure, UI labels, recovery steps, and authenticity boundaries.
Saved sessions use IndexedDB at the stable http://127.0.0.1:47890 browser origin. Markers, notes, and authored ranges use separate storage tied to the same session identity and origin. Upgrade on the same 127.0.0.1 application port and browser profile to retain access to that library. Changing the application port or browser profile selects different browser storage and can make the prior library appear absent.
Uninstalling the package does not delete the local session library, operator workspace, downloaded .nlsession files, or exported .nlb bundles. Follow the upgrade and removal guide before replacing the package or intentionally clearing site data.
The installed release offers UDP bridge and Serial port from the Live capture dialog.
For UDP, the managed process keeps its bridge credential internal and exposes bind, port, and optional multicast settings in the dialog. Command-line UDP flags populate dialog defaults; no socket starts until the operator selects Run UDP preflight. The preflight uses a temporary capture identity and retains only bounded aggregate observations. Start recording stops and discards that probe before opening a new capture identity, so probe traffic cannot silently become evidence. The chosen bind controls which local interface receives telemetry, so 0.0.0.0 should be used only when listening on every local IPv4 interface is intentional.
For serial, the operator selects port settings and then chooses the device through the browser's native Web Serial prompt with Select port & preflight. Start recording keeps that open port, resets the framing state, and sends only subsequent reads to the recorder. Web Serial requires a supporting Chromium browser and a secure loopback context. Automated coverage exercises the application path with an injected standards-based serial API; physical adapters, drivers, native chooser behavior, and operating-system disconnect handling remain a manual boundary.
Stopping either source with Stop, save & replay downloads a version 2 .nlsession, opens the validated finalized capture, and attempts to retain it in the local session library. Follow the UDP procedure or serial procedure before connecting a field source.
Source development, fixture regeneration, test commands, and the manual bearer-token bridge belong to CONTRIBUTING.md. The complete npm run check gate covers TypeScript, unit and integration tests, production builds, source browser workflows, the maximum-record replay corpus, deterministic release packaging, and the unpacked-distribution capture-to-verification workflow in Chromium, Firefox, and WebKit.
This matrix separates automated browser-engine evidence from hardware and assistive-technology certification. A Playwright WebKit pass is engine-level evidence, not a claim that every Safari, operating-system, or device combination has been manually certified.
| Workflow | Playwright Chromium | Playwright Firefox | Playwright WebKit | Current verification |
|---|---|---|---|---|
| Replay, local import, saved-session library, timeline review, markers, notes, and .nlb export | Automated | Automated | Automated | Invalid-file recovery, validated import, exact-content deduplication, playback/rate controls, per-session workspace restoration, guarded removal, and storage failure states |
| Maximum-record replay processing | Automated | Automated | Automated | A deterministic 52,378,445-byte, 200,000-record session is imported with visible progress, saved, cancelled during reopen without state loss, reopened, compared over an exact 10,000-record range, cancelled during bundle construction without a download, rebuilt, and verified through the production receiver; the gate rejects a heartbeat gap above five seconds or accumulated timer delay above half of the measured operation, and Chromium records heap growth against the published budget |
| Live UDP through the local bridge | Automated | Automated | Automated | A real ephemeral loopback bridge records NSL-01 and a non-bundled file-loaded NMEA 0183 pack, stops with reconciled v2 integrity, reimports the .nlsession, replays it, and completes production receiver verification |
| Simulated Web Serial capture-to-evidence | Automated | Automated | Automated | An injected standards-based serial stream exercises device selection, fragmented reads, NSL-01 assembly, partial-byte retention, reconciled v2 integrity, durable reopen, replay, exact-range export, and production receiver verification |
| Independent .nlb receipt and verification | Automated | Automated | Automated | NSL-01 and NMEA browser downloads are passed back through the production verifier, opened as bounded receiver documents, inspected, rejected safely when invalid, and reopened with separate receiver notes; ZIP structure, canonical paths, half-open boundaries, required transport evidence, artifact schemas, record counts, semantics, hashes, and SHA256SUMS are verified |
| Comparative replay and regression finding | Automated | Automated | Automated | Two real loopback UDP captures with one controlled integrity failure are compared as a validated session and independently verified bundle; the gate checks explicit alignment, overlap, comparability, source traceability, bounded assessment, and semantic validation of the downloaded .nlcompare.json. The unpacked release also compares a received bundle with its exact source session. |
| Keyboard, dialogs, and responsive access | Automated | Automated | Automated | axe rules tagged WCAG A/AA cover the replay and receiver workspaces plus critical dialogs; focus handoffs, 960, 640, and 390 CSS-pixel reflow, keyboard scrollers, and forced-color cues run in all three engines |
| Physical Web Serial hardware | Manual boundary | Manual boundary | Manual boundary | The application path is automated with an injected API, but native device choosers, transient activation, USB drivers, operating-system disconnect behavior, and packaged-browser combinations are not certified |
See ACCESSIBILITY.md for the tested interaction matrix, claim boundary, and remaining manual screen-reader work.
public/fixtures/harbor-relay-session.json is a deterministic synthetic session designed to exercise the production pipeline:
Fixture regeneration and review requirements are documented in CONTRIBUTING.md.
npm run fixture:large streams a deterministic session to output/large-session/scale-acceptance-200k.nlsession without keeping the generated document in Git. The full corpus is 52,378,445 canonical UTF-8 bytes, contains 200,000 records, and defines a 10-second incident with exactly 10,000 records. Source and unpacked-release Playwright gates use it to prove worker progress and cancellation, exact-byte persistence, deterministic reopen, bounded comparison, bundle cancellation without download, and production verification in Chromium, Firefox, and WebKit.
The current importer accepts JSON files with .json or .nlsession extensions using narrowslink/session format version 1 or 2. Version 1 remains a strict, unchanged legacy contract. New live recordings use version 2:
Session
├── UTC start, display time zone, and duration in microseconds
├── one source descriptor and one decoder descriptor
├── exact decoder pack, schema, runtime, revision, and content identity (new v2 captures)
├── immutable source records
│ ├── integer offsetUs
│ ├── captured frame bytes as hexadecimal
│ ├── transport provenance and byte counts
│ └── optional RSSI/SNR provenance
├── immutable transport events (v2)
│ ├── point, interval, or session scope
│ ├── UDP, serial, backpressure, limit, or shutdown evidence
│ └── stable identity, severity, and structured counters or codes
├── terminal capture-integrity receipt (v2)
│ ├── verified, incomplete, or unknown assessment
│ ├── stop disposition and event-log completeness
│ └── observed, transport-reported, and retained totals
├── structured transport provenance (new v2 captures)
│ ├── UDP capture identity, bind and multicast configuration
│ ├── per-record remote endpoint attribution and bounded bridge journal
│ ├── measured or explicitly unavailable host UDP socket-drop evidence
│ ├── observed payload, estimated UDP, minimum IP, and unavailable link/radio bytes
│ ├── serial device identifiers and negotiated settings
│ └── explicit unavailable observations and provenance issue codes
└── zero or more incident presets using [startUs, endUs)
Records must be ordered by nondecreasing offsetUs, reference the declared source, fit inside durationUs, and declare byte counts that match their hexadecimal payload. Version 2 additionally requires ordered, uniquely identified transport events and a receipt whose retained totals exactly match the records. New captures also preserve a validated provenance document: UDP endpoint-attribution totals and journal counters must reconcile with immutable records and the receipt, a measured host drop count must match its event and receipt issue, and byte-accounting estimates must recompute exactly from the journal. Serial device and negotiated-setting values remain bounded and explicit. A verified UDP receipt requires bridge, browser, recorder, journal, and endpoint parity with no measured host drops; a verified serial receipt requires clean stop, retained-byte parity, and explicit serial provenance. Format validation is implemented in src/domain/types.ts and src/domain/session.ts.
Receipt assessment bases state what was actually observed. udp-bridge-reconciled includes terminal bridge counters; udp-browser-observed leaves unavailable bridge totals null and cannot be verified; web-serial-observed reconciles observed serial bytes; and recorder-only records that no adapter finalization evidence was supplied. UDP and serial counter disagreements require their own issue code and exact counter evidence. When a bounded event log is complete, every transport issue must have a matching immutable event. If its evidence budget is exhausted, the receipt explicitly marks the log incomplete while preserving the known issue codes and terminal counters.
Imported v1 evidence is not rewritten. Replay normalizes it to an in-memory unknown · legacy replay assessment because the original file has no durable capture receipt. Earlier valid v2 sessions without the optional provenance field also remain unchanged; the workspace and bundle artifacts report provenance as unavailable instead of inferring it from retained records.
The NSL-01 binary envelope is little-endian after its A55A sync word and includes protocol version, family ID, sequence, payload length, device time, payload, and CRC-16/CCITT-FALSE. The NMEA 0183 runtime accepts bounded printable-ASCII sentences with XOR-8 checksums and declarative sentence fields. Every new capture embeds the selected pack; its descriptor binds the pack SHA-256, schema SHA-256, runtime ID, runtime revision, pack ID, and pack revision. Legacy NSL-01 sessions without pack metadata continue through the same registry by a compatibility adapter and are not rewritten. See DECODER_PACKS.md for the bounded contract and authoring workflow.
An .nlb file is an ordinary ZIP archive generated entirely in the browser. Depending on the inclusion controls, it contains:
manifest.json
SHA256SUMS
transport/events.json
transport/provenance.json
transport/journal.json
transport/integrity-receipt.json
raw/source-records.ndjson
decoded/packets.csv
diagnostics/diagnostics.json
diagnostics/diagnostics.csv
markers/markers.json
notes/notes.json
schema/schema.json
Range-scoped events, records, decoded packets, diagnostics, markers, and notes are filtered to the selected half-open interval. Point transport events at startUs are included and events at endUs are excluded; overlapping intervals and session-scoped integrity events are included. The mandatory transport/integrity-receipt.json, transport/provenance.json, and transport/journal.json instead preserve whole-session evidence, including explicit unavailable states for legacy or pre-provenance input. All four transport artifacts are mandatory even when every optional evidence group is excluded.
manifest.json records the session, decoder pack, schema, and parser-runtime identities, declared session duration, capture-integrity receipt, provenance availability and summary, exact selection, actual inclusions, media types, byte sizes, record counts, and artifact hashes. Those values describe the generated bytes, unlike the selected-group and size estimates shown before generation. decoded/packets.csv retains complete integrity JSON for forensic failures, and schema/schema.json includes the reproducible decoder definition plus the exact pack for pack-identified sessions. SHA256SUMS covers the manifest and each included evidence artifact.
In ReplayCase v0.4.0, choose Open evidence in the Sessions rail or top bar and select the .nlb. ReplayCase reads the file as untrusted input, verifies it in a worker with the production verifier, and does not replace the current workspace unless every required archive and semantic check succeeds.
The receiver workspace preserves the source session identity and exact half-open selection while projecting only included raw records, decoded packets, diagnostics, source annotations, and transport evidence. Excluded artifact groups and unavailable whole-session context remain explicit. Internal consistency, evidence completeness, and source authenticity are shown as separate claims. The Notes tab stores a receiver-owned finding separately under the whole-bundle SHA-256; it does not alter the received bytes or become source evidence.
The CLI remains available when a terminal or stable JSON report is required. After installing the v0.4.0 package, a receiving engineer can verify a version 3 or 4 bundle locally without a repository checkout, application server, browser workspace, or network access:
replaycase verify path/to/incident.nlb
replaycase verify path/to/incident.nlb --jsonThe production verifier bounds and preflights the archive before decompression, then checks canonical paths, schemas, inclusions, checksums, counts, range semantics, receipts, provenance, journals, and decoder identity. Do not extract an untrusted .nlb before this verification.
Exit status 0 means the archive is internally consistent. Exit 1 means it is invalid, tampered, unsafe, or unsupported. Exit 2 means command usage or local file I/O failed. A consistent bundle can still report incomplete or unknown capture evidence. Version 3 and 4 bundles are unsigned, so authenticity remains not-established.
Follow the receiver procedure to interpret the report and exchange the bundle identity through a separately trusted channel.
The comparison workspace exports a canonical JSON document with the suffix .nlcompare.json. It records:
The semantic validator rejects altered hashes and internally contradictory ranges, anchors, overlap, comparability rows, metrics, deltas, directions, or assessments. The hash establishes the finding's internal content identity; it does not authenticate the author or either source. A finding cites but does not embed its .nlsession or .nlb inputs, so another engineer needs the same two identified source files to reproduce the comparison.
| Folder | Responsibility |
|---|---|
| src/ | Browser workspace, capture, pure telemetry domain, replay, workers, and local persistence |
| verifier/ | Production evidence verification shared by the browser and CLI |
| scripts/ | CLI, managed server, UDP bridge, and fixture tools |
| scripts/release/ | Deterministic packaging and release evidence |
| tests/e2e/ and tests/release/ | Source-browser and unpacked-distribution acceptance gates |
| public/ | Shipped assets and deterministic demo fixture |
| docs/ | Architecture, design evidence, field proofs, releases, and guide navigation |
Use the repository map for clickable source entry points, execution paths, test routing, and Graphify refresh boundaries. Detailed contracts live in the architecture index.
Raw source records remain immutable. Frames, fields, metrics, diagnostics, incidents, and bundle artifacts are derived through the same pipeline for the bundled fixture, imported files, and finalized captures.
Serial capture, session-library persistence, replay parsing, marker and note persistence, evidence generation, received-bundle verification, and comparative replay happen locally in the browser. Long replay, comparison, and bundle operations use local Web Workers; they do not send session bytes to a service. Validated canonical session documents and their identifying metadata are stored in IndexedDB; markers, authored ranges, and notes use separate per-session local storage. Receiver findings use a separate local-storage record keyed by the exact bundle SHA-256 and can be cleared from the receiver Notes tab; they never modify the archive or become source evidence. Comparison inputs and authored conclusions remain in memory until the operator downloads a separate .nlcompare.json; the finding cites but does not contain either source. Removing a saved replay attempts to clear its two session stores, leaves any active replay open, and does not affect previously exported files or receiver findings. If the replay document is removed but workspace cleanup fails, ReplayCase keeps a visible warning that residual operator context may remain in browser storage. UDP payloads move only from the local socket bridge to the local page. In the installed release, the browser uses a same-origin relay and the managed process authenticates to the loopback-only bridge with an internal short-lived credential that is not returned in runtime metadata, URLs, cookies, readiness output, or logs. The UDP listener itself binds exactly the interface selected by the operator. ReplayCase has no account system, analytics service, telemetry upload, or cloud synchronization.
Local does not automatically mean safe to share. A saved replay or evidence bundle can contain raw bytes, device identifiers, coordinates, signal observations, and operator notes. Review and sanitize captures before committing them or sending them to someone else. Browser IndexedDB and local storage are convenient persistence mechanisms, not encrypted secrets stores.
| Document | Purpose |
|---|---|
| Documentation index | Task-based entry point to operator, contributor, design, proof, and release documentation |
| Repository map | Folder boundaries, linked implementation entry points, execution paths, tests, and generated-map policy |
| USER_GUIDE.md | Step-by-step installation, capture, replay, incident, evidence handoff, upgrade, removal, and troubleshooting |
| USE_CASES.md | Stable catalog of supported operator outcomes, constraints, and implementation evidence |
| CHANGELOG.md | Canonical record of notable completed changes and tagged releases |
| ROADMAP.md | Planned work, constraints, and exit criteria; completed work moves to the changelog |
| CONTRIBUTING.md | Development setup, engineering invariants, review expectations, and changelog policy |
| ACCESSIBILITY.md | Current automated accessibility evidence, keyboard contract, support boundary, and manual certification matrix |
| design-qa.md | Current accepted visual baseline and verification evidence |
| docs/architecture/udp-capture-attribution.md | Host UDP drop-counter, byte-accounting, compatibility, and claim boundaries |
| docs/field-proofs/ | Pilot plan, release-readiness evidence, and independent real-source handoff procedure and records |
| docs/releases/ | Immutable operator-facing summaries and installation notes for each published tag |
For step-by-step operation, use the user guide. For problem reporting, see SUPPORT.md. Report vulnerabilities through the private process in SECURITY.md, and review CODE_OF_CONDUCT.md before participating in project spaces.
ReplayCase is available under the MIT License.
| Back | FazBrowse Home | New Git URL |