@reporters/web 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## [1.3.0](https://github.com/MoLow/reporters/compare/web-v1.2.0...web-v1.3.0) (2026-07-02)
+
+
+### Features
+
+* pluggable viewer report sources and custom s3 viewer links ([#222](https://github.com/MoLow/reporters/issues/222)) ([e553e89](https://github.com/MoLow/reporters/commit/e553e89a6e0c9ba9323483ca52a3142c8e70f8ce))
+
+## [1.2.0](https://github.com/MoLow/reporters/compare/web-v1.1.0...web-v1.2.0) (2026-07-02)
+
+
+### Features
+
+* **web:** let sinks set the viewer poll cadence via a poll query param ([#219](https://github.com/MoLow/reporters/issues/219)) ([a78404d](https://github.com/MoLow/reporters/commit/a78404d61cf924d0c8e221ee41b8b0337f3d1023))
+
+
+### Bug Fixes
+
+* **web:** stay a pure emitter under mux via symbol-declared default options ([#217](https://github.com/MoLow/reporters/issues/217)) ([96a7d14](https://github.com/MoLow/reporters/commit/96a7d14e82f69c6dc6d8d363645f94c09733fbda))
+
+## [1.1.0](https://github.com/MoLow/reporters/compare/web-v1.0.0...web-v1.1.0) (2026-07-02)
+
+
+### Features
+
+* @reporters/mux environment-aware reporter routing + web NDJSON redesign ([#203](https://github.com/MoLow/reporters/issues/203)) ([82d1e20](https://github.com/MoLow/reporters/commit/82d1e205949e6daa90b13aec5838ddb0c7e931a5))
+* live and web tree reporters ([#193](https://github.com/MoLow/reporters/issues/193)) ([0fae33e](https://github.com/MoLow/reporters/commit/0fae33e3c87f3a28d68b783a457ef9638cec2f17))
+* **web:** implement the Panel design for the web report & live viewer ([#195](https://github.com/MoLow/reporters/issues/195)) ([f93b76b](https://github.com/MoLow/reporters/commit/f93b76bb8536adda53d57b7691b8912c86208cee))
+* **web:** read destination from execArgv; auto-open the report locally ([#197](https://github.com/MoLow/reporters/issues/197)) ([d8eb056](https://github.com/MoLow/reporters/commit/d8eb056c117b1a35120dc9e898b600ff853d43bb))
+* **web:** render ANSI colors in the report (fancy-ansi) ([#206](https://github.com/MoLow/reporters/issues/206)) ([a2c938e](https://github.com/MoLow/reporters/commit/a2c938e2d2ada1ecd0f2aea636c253e619dd084a))
+* **web:** replace density toggle with a dark/light mode toggle ([#202](https://github.com/MoLow/reporters/issues/202)) ([47fbf7c](https://github.com/MoLow/reporters/commit/47fbf7c180dd7383d31eda75061631b41fc5c060))
+* **web:** viewer design round 2 + live-viewer transition choreography ([#205](https://github.com/MoLow/reporters/issues/205)) ([b99d9c6](https://github.com/MoLow/reporters/commit/b99d9c62b4729a530922e18a2b4566ed219bd9a5))
+
+
+### Bug Fixes
+
+* **tree-core:** group top-level stdout/stderr with their file's tests ([#200](https://github.com/MoLow/reporters/issues/200)) ([27a510d](https://github.com/MoLow/reporters/commit/27a510deb42a85de9a82782e85e84b68477599ea))
+* **web:** auto-refresh the embedded report while streaming ([#196](https://github.com/MoLow/reporters/issues/196)) ([68090dc](https://github.com/MoLow/reporters/commit/68090dc3fbade1b2f01bba150310b9263aa0336c))
+* **web:** honor REPORTERS_OPEN instead of REPORTERS_WEB_OPEN ([#208](https://github.com/MoLow/reporters/issues/208)) ([fe3716d](https://github.com/MoLow/reporters/commit/fe3716d499cf8ab592c66d7519fce8c9c50ae060))
+* **web:** open the standalone live view even without a file destination ([#204](https://github.com/MoLow/reporters/issues/204)) ([cf6d465](https://github.com/MoLow/reporters/commit/cf6d4657efee5fdb6a5daa63e2be475be27bcab2))
+* **web:** use the live viewer URL in the load-error hint ([#201](https://github.com/MoLow/reporters/issues/201)) ([acf6dec](https://github.com/MoLow/reporters/commit/acf6dec6701c8b42d98ab703fdd74965c7d94aff))
+
+
+### Documentation
+
+* flag-order fixes and the gh collapsible actions log ([#216](https://github.com/MoLow/reporters/issues/216)) ([131f410](https://github.com/MoLow/reporters/commit/131f4107712d6d0b899d3b8ca7a39496b6e05276))
+* rewrite package READMEs with demos and clearer positioning ([#209](https://github.com/MoLow/reporters/issues/209)) ([e1265e5](https://github.com/MoLow/reporters/commit/e1265e5f6b8a0f34b80ef7ee725cede4ed16b6da))
+
+
+### Miscellaneous Chores
+
+* address review feedback on the tree reporters ([#194](https://github.com/MoLow/reporters/issues/194)) ([fada74a](https://github.com/MoLow/reporters/commit/fada74aa9be27f1a0a2f217de0115c5ae8de4851))
+* route this repo's tests through @reporters/mux ([#207](https://github.com/MoLow/reporters/issues/207)) ([85a5973](https://github.com/MoLow/reporters/commit/85a59737bc3d631b0293edf343b77fd82e0c459d))
+* use the gh reporter for tree-core/live/web tests ([#198](https://github.com/MoLow/reporters/issues/198)) ([cc1fefa](https://github.com/MoLow/reporters/commit/cc1fefa5e4f9d04eda6067c4134a83b4cf46aa4f))

package/README.md

@@ -41,7 +41,7 @@ The NDJSON is rendered by the tree viewer, reached three ways:
   // mux.config.js
   import { httpServer } from '@reporters/web/sink';
   export default {
-    // pass `options: { open: false }` on the route if it shouldn't open a browser
+    // pass `open: false` on the route if it shouldn't open a browser
     local: [{ reporter: '@reporters/web', sink: httpServer() }],
   };
   ```
@@ -60,3 +60,29 @@ The NDJSON is rendered by the tree viewer, reached three ways:
 Built on the shared [`@reporters/tree-core`](https://github.com/MoLow/reporters/tree/main/packages/tree-core)
 model (also used by [`@reporters/live`](https://github.com/MoLow/reporters/tree/main/packages/live)) —
 the same run state, rendered in the browser instead of the terminal.
+
+## Custom report sources (`@reporters/web/viewer`)
+
+The hosted viewer reads `?src=<url>` with plain `fetch`. To serve reports that
+need authentication (private buckets, SSO), build your own viewer page on the
+same UI with a custom source resolver:
+
+```ts
+import { startViewer } from '@reporters/web/viewer';
+
+startViewer({
+  resolveSource: async (params) => {
+    if (params.get('src') || !params.get('key')) return null; // default handling
+    const credentials = await acquireCredentialsSomehow();
+    return { url: params.get('key')!, fetch: authenticatedFetch(credentials) };
+  },
+});
+```
+
+`resolveSource` runs before anything renders. Return `null`/`undefined` to fall
+through to the default `?src=` handling; return `{ url, fetch?, pollMs? }` to
+take over. The custom `fetch` receives the reader's `Range` header and must
+return a standard `Response`; a thrown error shows the viewer's load-error
+screen, and a promise that never resolves is fine while an auth redirect is in
+flight. The export is a self-contained browser ESM module (React inlined) —
+bundle it with your resolver into a static HTML page.

package/dist/{chunk-MZ7XNO2N.js → chunk-X6OHEYIN.js}

@@ -9,7 +9,7 @@ function viewerPage() {
     return '<!doctype html><meta charset="utf-8"><p>viewer bundle missing \u2014 run the package build</p>';
   }
 }
-function startViewerServer(host = "127.0.0.1") {
+function startViewerServer(host = "127.0.0.1", pollMs = 250) {
   const page = viewerPage();
   let buffer = Buffer.alloc(0);
   return new Promise((resolve) => {
@@ -41,7 +41,9 @@ function startViewerServer(host = "127.0.0.1") {
     server.listen(0, host, () => {
       const { port } = server.address();
       resolve({
-        url: `http://${host}:${port}/?src=/run.ndjson`,
+        // Serving from memory on localhost is cheap, so ask the viewer to poll
+        // fast; remote sinks (S3/gist) omit `poll` and get the slower default.
+        url: `http://${host}:${port}/?src=/run.ndjson&poll=${pollMs}`,
         push(chunk) {
           buffer = Buffer.concat([buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
         },

package/dist/index.d.ts

@@ -43,8 +43,8 @@ interface WebOptions {
  * Run standalone on a dev machine it also serves a live browser view and opens
  * it, the same way it behaves through `@reporters/mux`'s `httpServer()` sink.
  * Control this with the `open` option or `REPORTERS_OPEN=1|0`; it never opens
- * in CI by default. Through mux the reporter is a pure emitter and the sink owns
- * viewing.
+ * in CI by default. Through mux the reporter is a pure emitter and the sink
+ * owns viewing — it declares `{ open: false }` as its under-mux default options.
  */
 declare function web(source: AsyncIterable<TestEvent>, options?: WebOptions): AsyncGenerator<string>;
 

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   startViewerServer
-} from "./chunk-MZ7XNO2N.js";
+} from "./chunk-X6OHEYIN.js";
 
 // ../tree-core/src/wire.ts
 function flattenError(raw) {
@@ -116,6 +116,7 @@ async function* web(source, options = {}) {
   if (process.stdin.isTTY) return;
   await server.close();
 }
+Object.assign(web, { [/* @__PURE__ */ Symbol.for("reporters.mux.defaultOptions")]: { open: false } });
 export {
   web as default
 };

package/dist/sink.d.ts

@@ -6,12 +6,19 @@ interface Sink {
     flush?(): Promise<void>;
     /** The run ended; release resources. */
     close(): Promise<void>;
-    /** How a human views what was written, if anything. */
+    /**
+     * How a human views what was written, if anything. Valid once `start()` has
+     * resolved; under mux, every sink in the profile has started before any
+     * reporter receives events, so a getter wired into another route's
+     * `options` is live from the first event.
+     */
     viewerUrl?(): string | undefined;
 }
 
 interface HttpServerOptions {
     host?: string;
+    /** Viewer polling cadence in ms (default 250; the viewer clamps to 100–10000). */
+    pollMs?: number;
 }
 /**
  * A sink that serves the run locally: the viewer page at `/` and the growing

package/dist/sink.js

@@ -1,13 +1,13 @@
 import {
   startViewerServer
-} from "./chunk-MZ7XNO2N.js";
+} from "./chunk-X6OHEYIN.js";
 
 // src/sink.ts
 function httpServer(opts = {}) {
   let server;
   return {
     async start() {
-      server = await startViewerServer(opts.host);
+      server = await startViewerServer(opts.host, opts.pollMs);
     },
     write(chunk) {
       server?.push(chunk);

package/dist/start.d.ts

@@ -0,0 +1,24 @@
+type FetchLike = (url: string, init?: {
+    headers?: Record<string, string>;
+}) => Promise<Response>;
+
+interface ReportSource {
+    /** Passed to the NDJSON reader as the URL/identifier. */
+    url: string;
+    /** Transport for reads; defaults to the global fetch. Receives the reader's
+     *  Range header and must return a standard Response. */
+    fetch?: FetchLike;
+    /** Poll cadence override; else resolved from ?poll= as today. */
+    pollMs?: number;
+}
+interface ViewerOptions {
+    /** Called first with the page's query params. Return a source to use it;
+     *  return null/undefined to fall through to the default ?src= handling.
+     *  A never-resolving promise is legitimate (e.g. an auth redirect is in
+     *  flight). A thrown error shows the viewer's load-error screen. */
+    resolveSource?: (params: URLSearchParams) => Promise<ReportSource | null | undefined>;
+}
+
+declare function startViewer(options?: ViewerOptions): Promise<void>;
+
+export { type FetchLike, type ReportSource, type ViewerOptions, startViewer };