cantraceviewer 0.1.0-rc.0

package/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Tom Ford
+
+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,131 @@
+# cantraceviewer
+
+`cantraceviewer` parses DBC files and CAN traces, then decodes selected signal series. It supports ASC, PCAN TRC 1.x/2.x, BLF, and MF4 traces.
+
+The package has three ESM entries:
+
+- `cantraceviewer` — asynchronous browser client using one dedicated Web Worker
+- `cantraceviewer/direct` — synchronous in-process WebAssembly client
+- `cantraceviewer/node` — asynchronous Node.js client using one dedicated worker thread
+
+The browser and Node clients are transports over the same direct implementation. The package has no server component and does not persist input data.
+
+## Browser
+
+Create the client in browser code, not during server-side rendering. `openTrace` transfers and detaches the exact input `ArrayBuffer`.
+
+```ts
+import { createCanTraceClient } from 'cantraceviewer';
+
+const client = await createCanTraceClient();
+const { handle: dbc, catalog } = await client.openDbc(await dbcFile.text());
+const trace = await client.openTrace('asc', await traceFile.arrayBuffer());
+
+const message = catalog.messages[0];
+const signal = message.signals[0];
+const series = await client.getSignalValues(
+	dbc,
+	trace.handle,
+	{
+		canId: message.canId,
+		isExtended: message.isExtended,
+		sizeBytes: message.sizeBytes
+	},
+	signal.name
+);
+
+await client.closeTrace(trace.handle);
+await client.closeDbc(dbc);
+await client.close();
+```
+
+`openTrace` also returns metadata, parse warnings, embedded DBC files, and the native MF4 signal catalog where applicable.
+
+## Direct
+
+The direct client is fully synchronous. The caller must read, fetch, or asynchronously compile the WASM before creating it. The exported `wasmUrl` identifies the package-local binary.
+
+```ts
+import { readFile } from 'node:fs/promises';
+import { createDirectClient, wasmUrl } from 'cantraceviewer/direct';
+
+const wasm = await readFile(wasmUrl);
+const client = createDirectClient(wasm);
+const { handle: dbc, catalog } = client.openDbc(dbcText);
+const trace = client.openTrace('blf', traceBytes);
+const message = catalog.messages[0];
+const series = client.getSignalValues(
+	dbc,
+	trace.handle,
+	{
+		canId: message.canId,
+		isExtended: message.isExtended,
+		sizeBytes: message.sizeBytes
+	},
+	message.signals[0].name
+);
+
+client.closeTrace(trace.handle);
+client.closeDbc(dbc);
+client.close();
+```
+
+`createDirectClient` also accepts a precompiled `WebAssembly.Module`. WebAssembly initializes once per JavaScript realm; later direct clients reuse that runtime while retaining separate handle ownership. Closing handles releases their Rust allocations, but WebAssembly memory pages are not guaranteed to return to the operating system until the realm or process ends.
+
+Direct parsing and decoding block the calling thread. Do not use this entry on a browser UI thread or Electron main thread. It is intended for an existing Worker, worker thread, isolated process, benchmark, or controlled test.
+
+## Node.js
+
+The Node entry has the same asynchronous API as the browser entry. It owns the direct client and all handles inside one `worker_threads` worker.
+
+```ts
+import { readFile } from 'node:fs/promises';
+import { createCanTraceClient } from 'cantraceviewer/node';
+
+const client = await createCanTraceClient();
+const { handle: dbc, catalog } = await client.openDbc(await readFile('network.dbc', 'utf8'));
+const file = await readFile('drive.blf');
+const buffer = Uint8Array.from(file).buffer;
+const trace = await client.openTrace('blf', buffer);
+
+// Decode as in the browser example, using dbc and trace.handle.
+
+await client.closeTrace(trace.handle);
+await client.closeDbc(dbc);
+await client.close();
+```
+
+The copy in this example creates an exact `ArrayBuffer`. If a Node buffer already spans an ordinary `ArrayBuffer` exactly, that underlying buffer can be passed directly.
+
+## Electron
+
+Two arrangements are supported:
+
+1. Use `cantraceviewer` in the renderer. Parsing and decoding run in its browser Web Worker. Serve the renderer over HTTP(S) or a standard, secure custom protocol so its ESM Worker and WASM assets can load; a bare `file://` renderer is not supported.
+2. Use `cantraceviewer/node` in the main process and expose application-specific operations to the renderer through a context-isolated preload and Electron IPC. Parsing and decoding run in the package's worker thread.
+
+Do not import `cantraceviewer/direct` in the renderer or main process because it blocks that thread.
+
+## Handles and lifecycle
+
+DBC and trace handles are opaque and belong to the client that created them. A handle cannot be used with another client. Closing a handle is idempotent. Closing a client invalidates all of its remaining handles.
+
+Each asynchronous client processes requests in call order. A worker startup failure, crash, message failure, or unexpected Node worker exit is fatal for that client. Pending and future operations reject, all handles become invalid, and the package does not restart the worker automatically. Create a new client to recover.
+
+Errors are standard `Error` objects. Their names and messages are diagnostics, not stable values for application branching.
+
+## Transfer semantics
+
+The browser and Node clients require the exact ordinary `ArrayBuffer` containing a trace. The buffer is transferred to the worker and detached immediately, including when parsing later fails. Typed-array views are rejected rather than copied implicitly. Node buffers marked as untransferable are rejected before posting and remain attached.
+
+Decoded `timesMs` and `values` are two `Float64Array` views over one exactly sized `ArrayBuffer` transferred from the worker. Transferring that shared buffer elsewhere detaches both views.
+
+The direct client accepts a `Uint8Array` and does not detach it.
+
+## Supported environments
+
+- Node.js 22.12 or newer for `cantraceviewer/node`
+- Browsers and Electron renderers with ESM, module Workers, WebAssembly, and transferable `ArrayBuffer` support for `cantraceviewer`
+- ESM-aware bundlers that preserve the standard `new Worker(new URL(..., import.meta.url))` asset pattern
+
+The package does not support CommonJS, server persistence, browser environments without module Workers, synchronous browser UI-thread use, or synchronous Electron main-thread use.

package/dist/client.d.ts

@@ -0,0 +1,21 @@
+import { type CanTraceClient } from './rpc-client.js';
+export type { CanTraceClient } from './rpc-client.js';
+/** Worker surface the browser transport depends on; production uses a real module Worker. @internal */
+export type ClientWorkerEvent = {
+    data?: unknown;
+    message?: string;
+};
+/** @internal */
+export type ClientWorker = {
+    postMessage(message: unknown, transfer: Transferable[]): void;
+    addEventListener(type: 'message' | 'error' | 'messageerror', listener: (event: ClientWorkerEvent) => void): void;
+    terminate(): void;
+};
+/**
+ * Create a client backed by a new dedicated module Worker. Call in the browser only; nothing is
+ * instantiated at module import time, so importing this package is SSR/prerender safe. This module
+ * never touches Node built-ins, so it stays bundleable for the browser.
+ */
+export declare function createCanTraceClient(): Promise<CanTraceClient>;
+/** Internal seam for deterministic tests; not exported from the package root. @internal */
+export declare function createCanTraceClientForWorker(createWorker: () => ClientWorker): Promise<CanTraceClient>;

package/dist/client.js

@@ -0,0 +1,37 @@
+import { createRpcClient } from "./rpc-client.js";
+/**
+ * Create a client backed by a new dedicated module Worker. Call in the browser only; nothing is
+ * instantiated at module import time, so importing this package is SSR/prerender safe. This module
+ * never touches Node built-ins, so it stays bundleable for the browser.
+ */
+export async function createCanTraceClient() {
+    if (typeof Worker === 'undefined') {
+        throw new Error('createCanTraceClient requires Web Worker support; call it in the browser');
+    }
+    // Keep this constructor call in literal `new Worker(new URL(...), ...)` form so bundlers
+    // detect it and emit the worker entry chunk.
+    return createCanTraceClientForWorker(() => new Worker(new URL('./worker.js', import.meta.url), { type: 'module' }));
+}
+/** Internal seam for deterministic tests; not exported from the package root. @internal */
+export async function createCanTraceClientForWorker(createWorker) {
+    return createRpcClient((handlers) => browserTransport(createWorker(), handlers));
+}
+/** Web Worker events mapped onto the shared client core. */
+function browserTransport(worker, handlers) {
+    worker.addEventListener('message', (event) => handlers.message(event.data));
+    worker.addEventListener('error', (event) => {
+        handlers.fail(new Error(`worker crashed${event.message ? `: ${event.message}` : ''}`));
+    });
+    worker.addEventListener('messageerror', () => {
+        handlers.fail(new Error('worker message failed to deserialize'));
+    });
+    return {
+        postMessage(message, transfer) {
+            worker.postMessage(message, transfer);
+        },
+        async terminate() {
+            // Web Worker termination is immediate and synchronous; nothing to await.
+            worker.terminate();
+        }
+    };
+}

package/dist/direct.d.ts

@@ -0,0 +1,39 @@
+/// <reference lib="dom" />
+import type { DbcHandle, DbcMessageIdentity, DecodedSignalSeries, OpenDbcResult, OpenTraceResult, TraceHandle, TraceType } from './types.js';
+export type * from './types.js';
+/** WASM bytes or an already compiled module. Compilation of bytes is synchronous. */
+export type DirectWasmInput = BufferSource | WebAssembly.Module;
+/** Package-local WASM asset URL. Read, fetch, or compile it before synchronous initialization. */
+export declare const wasmUrl: URL;
+/**
+ * Fully synchronous in-process client. Every operation compiles, parses, or decodes on the calling
+ * thread and returns its result directly; nothing here creates a Worker or a promise.
+ *
+ * Use it only where blocking is acceptable: inside a Worker or worker thread, in a dedicated
+ * process, in benchmarks, or in tests. Do not call it on a browser UI thread or an Electron main
+ * thread; use the asynchronous browser or Node clients there.
+ */
+export type DirectClient = {
+    openDbc(text: string): OpenDbcResult;
+    /** Idempotent for handles this client issued; repeat calls do nothing. */
+    closeDbc(handle: DbcHandle): void;
+    openTrace(traceType: TraceType, bytes: Uint8Array): OpenTraceResult;
+    /** Idempotent for handles this client issued; repeat calls do nothing. */
+    closeTrace(handle: TraceHandle): void;
+    /**
+     * Decode one DBC signal over the trace's raw frames. Both returned arrays are views over one
+     * exactly-sized ArrayBuffer, so transports can transfer the result without copying.
+     */
+    getSignalValues(dbcHandle: DbcHandle, traceHandle: TraceHandle, messageIdentity: DbcMessageIdentity, signalName: string): DecodedSignalSeries;
+    /** Read one signal the trace already carries decoded, identified by its MF4 catalog id. */
+    getMf4SignalValues(traceHandle: TraceHandle, signalId: number): DecodedSignalSeries;
+    /** Idempotent. Frees every handle this client still owns. */
+    close(): void;
+};
+/**
+ * Create a synchronous client over one WASM instance. WASM initialization happens once per
+ * JavaScript realm: later clients reuse that instance and ignore their input, but each client owns
+ * its own handles. Fetching or reading the bytes is the caller's job and can be asynchronous; this
+ * call is not.
+ */
+export declare function createDirectClient(wasm: DirectWasmInput): DirectClient;

package/dist/direct.js

@@ -0,0 +1,143 @@
+/// <reference lib="dom" />
+import { createHandleRegistry } from "./handles.js";
+import { initSync, Dbc as WasmDbc, Trace as WasmTrace } from './wasm-bindgen/cantraceviewer.js';
+/** Package-local WASM asset URL. Read, fetch, or compile it before synchronous initialization. */
+export const wasmUrl = new URL('./wasm-bindgen/cantraceviewer_bg.wasm', import.meta.url);
+/**
+ * Create a synchronous client over one WASM instance. WASM initialization happens once per
+ * JavaScript realm: later clients reuse that instance and ignore their input, but each client owns
+ * its own handles. Fetching or reading the bytes is the caller's job and can be asynchronous; this
+ * call is not.
+ */
+export function createDirectClient(wasm) {
+    // The generated `initSync` returns the existing instance when it is already initialized.
+    withWasmErrors(() => initSync({ module: wasm }));
+    const handles = createHandleRegistry();
+    let clientClosed = false;
+    function assertClientOpen() {
+        if (clientClosed)
+            throw new Error('client is closed');
+    }
+    return {
+        openDbc(text) {
+            assertClientOpen();
+            const dbc = withWasmErrors(() => WasmDbc.parse(text));
+            try {
+                const catalog = JSON.parse(withWasmErrors(() => dbc.catalogJson()));
+                return { handle: handles.issue('dbc', dbc), catalog };
+            }
+            catch (error) {
+                dbc.free();
+                throw error;
+            }
+        },
+        closeDbc(handle) {
+            freeHandle(handles.release('dbc', handle));
+        },
+        openTrace(traceType, bytes) {
+            assertClientOpen();
+            const trace = withWasmErrors(() => parseTrace(traceType, bytes));
+            try {
+                const metadata = {
+                    measurementStartMs: trace.measurementStartMs ?? null,
+                    validMessageCount: trace.validMessageCount,
+                    skippedLineCount: trace.skippedLineCount,
+                    durationNs: trace.durationNs ?? null
+                };
+                const isMf4 = traceType === 'mf4';
+                const hasRawFrames = trace.hasRawFrames;
+                const mf4Catalog = isMf4
+                    ? JSON.parse(withWasmErrors(() => trace.mf4CatalogJson()))
+                    : null;
+                const embeddedDbcs = isMf4
+                    ? JSON.parse(withWasmErrors(() => trace.mf4EmbeddedDbcsJson()))
+                    : [];
+                const warnings = isMf4
+                    ? JSON.parse(withWasmErrors(() => trace.mf4WarningsJson()))
+                    : [];
+                return {
+                    handle: handles.issue('trace', trace),
+                    metadata,
+                    hasRawFrames,
+                    mf4Catalog,
+                    embeddedDbcs,
+                    warnings
+                };
+            }
+            catch (error) {
+                trace.free();
+                throw error;
+            }
+        },
+        closeTrace(handle) {
+            freeHandle(handles.release('trace', handle));
+        },
+        getSignalValues(dbcHandle, traceHandle, messageIdentity, signalName) {
+            assertClientOpen();
+            const dbc = handles.payload('dbc', dbcHandle);
+            const trace = handles.payload('trace', traceHandle);
+            return unpackSeries(withWasmErrors(() => dbc.decodeSignal(trace, messageIdentity.canId, messageIdentity.isExtended, messageIdentity.sizeBytes, signalName)));
+        },
+        getMf4SignalValues(traceHandle, signalId) {
+            assertClientOpen();
+            const trace = handles.payload('trace', traceHandle);
+            return unpackSeries(withWasmErrors(() => trace.decodeMf4Signal(signalId)));
+        },
+        close() {
+            if (clientClosed)
+                return;
+            clientClosed = true;
+            let firstError;
+            for (const payload of handles.releaseAll()) {
+                try {
+                    freeHandle(payload);
+                }
+                catch (error) {
+                    firstError ??= error;
+                }
+            }
+            if (firstError)
+                throw firstError;
+        }
+    };
+}
+function freeHandle(payload) {
+    if (payload)
+        withWasmErrors(() => payload.free());
+}
+function parseTrace(traceType, bytes) {
+    switch (traceType) {
+        case 'asc':
+            return WasmTrace.parseAsc(bytes);
+        case 'trc':
+            return WasmTrace.parseTrc(bytes);
+        case 'blf':
+            return WasmTrace.parseBlf(bytes);
+        case 'mf4':
+            return WasmTrace.parseMf4(bytes);
+    }
+}
+function unpackSeries(packed) {
+    const count = packed.length / 2;
+    return {
+        timesMs: packed.subarray(0, count),
+        values: packed.subarray(count)
+    };
+}
+function withWasmErrors(operation) {
+    try {
+        return operation();
+    }
+    catch (error) {
+        throw normalizeWasmError(error);
+    }
+}
+function normalizeWasmError(error) {
+    if (error instanceof WebAssembly.RuntimeError) {
+        return new Error(`WebAssembly execution failed: ${error.message}`);
+    }
+    if (error instanceof WebAssembly.CompileError || error instanceof WebAssembly.LinkError) {
+        return new Error(`WebAssembly failed to load: ${error.message}`);
+    }
+    return error;
+}

package/dist/handles.d.ts

@@ -0,0 +1,24 @@
+import type { DbcHandle, TraceHandle } from './types.js';
+export type HandleKind = 'dbc' | 'trace';
+type HandleFor = {
+    dbc: DbcHandle;
+    trace: TraceHandle;
+};
+/**
+ * Owns the handles one client issued. `Payloads` maps each handle kind to what the client needs to
+ * act on it: the direct client stores wasm-bindgen objects, the transport clients store wire IDs.
+ */
+export type HandleRegistry<Payloads extends Record<HandleKind, unknown>> = {
+    issue<K extends HandleKind>(kind: K, payload: Payloads[K]): HandleFor[K];
+    /** Payload of an owned, open handle. Throws for foreign, wrong-kind, or closed handles. */
+    payload<K extends HandleKind>(kind: K, handle: HandleFor[K]): Payloads[K];
+    /**
+     * Mark an owned handle closed and return its payload for cleanup, or null when it was already
+     * closed. Throws for foreign or wrong-kind handles.
+     */
+    release<K extends HandleKind>(kind: K, handle: HandleFor[K]): Payloads[K] | null;
+    /** Mark every live handle closed and return their payloads in issue order. */
+    releaseAll(): Payloads[HandleKind][];
+};
+export declare function createHandleRegistry<Payloads extends Record<HandleKind, unknown>>(): HandleRegistry<Payloads>;
+export {};

package/dist/handles.js

@@ -0,0 +1,54 @@
+/**
+ * Client-local handle identity, shared by the synchronous direct client and the asynchronous
+ * transport clients. @internal
+ *
+ * Each handle carries one private symbol token. The token is a primitive, so arbitrary reactive
+ * proxies return it unchanged and object spreads copy it. The mutable state stays in this
+ * client-local registry rather than on the handle, so proxies cannot duplicate or wrap it.
+ */
+const HandleToken = Symbol('CAN Trace Viewer handle token');
+export function createHandleRegistry() {
+    const entries = new Map();
+    function entryFor(kind, handle) {
+        const token = handle[HandleToken];
+        const entry = token ? entries.get(token) : undefined;
+        if (!entry || entry.kind !== kind) {
+            throw new Error(`${kind} handle does not belong to this client`);
+        }
+        return entry;
+    }
+    return {
+        issue(kind, payload) {
+            const token = Symbol(`CAN Trace Viewer ${kind} handle`);
+            entries.set(token, { closed: false, kind, payload: payload });
+            // Object spread copies this enumerable symbol while proxies preserve its primitive value.
+            return { [HandleToken]: token };
+        },
+        payload(kind, handle) {
+            const entry = entryFor(kind, handle);
+            if (entry.closed)
+                throw new Error(`${kind} handle is closed`);
+            return entry.payload;
+        },
+        release(kind, handle) {
+            const entry = entryFor(kind, handle);
+            if (entry.closed)
+                return null;
+            entry.closed = true;
+            const payload = entry.payload;
+            entry.payload = null;
+            return payload;
+        },
+        releaseAll() {
+            const payloads = [];
+            for (const entry of entries.values()) {
+                if (entry.closed)
+                    continue;
+                entry.closed = true;
+                payloads.push(entry.payload);
+                entry.payload = null;
+            }
+            return payloads;
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createCanTraceClient } from './client.js';
+export type { CanTraceClient } from './client.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { createCanTraceClient } from "./client.js";

package/dist/node-transport.d.ts

@@ -0,0 +1,12 @@
+import { type CanTraceClient } from './rpc-client.js';
+/** worker_threads surface used by the private Node transport and its tests. @internal */
+export type NodeClientWorker = {
+    postMessage(message: unknown, transfer?: readonly ArrayBuffer[]): void;
+    on(event: 'message', listener: (data: unknown) => void): unknown;
+    on(event: 'messageerror', listener: (error: Error) => void): unknown;
+    on(event: 'error', listener: (error: Error) => void): unknown;
+    on(event: 'exit', listener: (code: number) => void): unknown;
+    terminate(): Promise<unknown>;
+};
+/** Private seam for deterministic transport tests. @internal */
+export declare function createNodeClientForWorker(createWorker: () => NodeClientWorker): Promise<CanTraceClient>;

package/dist/node-transport.js

@@ -0,0 +1,38 @@
+import { isMarkedAsUntransferable } from 'node:worker_threads';
+import { createRpcClient } from "./rpc-client.js";
+/** Private seam for deterministic transport tests. @internal */
+export async function createNodeClientForWorker(createWorker) {
+    return createRpcClient((handlers) => nodeTransport(createWorker(), handlers));
+}
+/** worker_threads EventEmitter events mapped onto the shared client core. */
+function nodeTransport(worker, handlers) {
+    let stopping = false;
+    worker.on('message', (data) => handlers.message(data));
+    worker.on('error', (error) => {
+        handlers.fail(new Error(`worker thread crashed: ${describe(error)}`, { cause: error }));
+    });
+    worker.on('messageerror', (error) => {
+        handlers.fail(new Error(`worker thread message failed to deserialize: ${describe(error)}`));
+    });
+    worker.on('exit', (code) => {
+        // A requested terminate always ends in an exit event; only an unrequested one is a failure.
+        if (stopping)
+            return;
+        handlers.fail(new Error(`worker thread exited unexpectedly with code ${code}`));
+    });
+    return {
+        postMessage(message, transfer) {
+            if (transfer.some(isMarkedAsUntransferable)) {
+                throw new Error('openTrace cannot transfer an ArrayBuffer marked as untransferable');
+            }
+            worker.postMessage(message, transfer);
+        },
+        async terminate() {
+            stopping = true;
+            await worker.terminate();
+        }
+    };
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/node-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/node-worker.js

@@ -0,0 +1,27 @@
+import { readFile } from 'node:fs/promises';
+import { parentPort } from 'node:worker_threads';
+// Relative imports carry `.ts` extensions throughout this package because Node loads this worker
+// entry from source through type stripping, which resolves specifiers literally. `tsc` rewrites
+// them to `.js` when it emits the packaged build.
+import { createDirectClient } from "./direct.js";
+import { startWorkerRuntime } from "./worker-runtime.js";
+// Dedicated worker-thread entry: one per Node client, created by createCanTraceClient(). It reads
+// the packaged WASM binary from disk, compiles it, and owns the direct client for its lifetime.
+const port = parentPort;
+if (!port) {
+    throw new Error('the cantraceviewer worker entry must run inside a worker thread');
+}
+const endpoint = {
+    postMessage(message, transfer = []) {
+        // Transfer lists are ArrayBuffers only, which worker_threads transfers like postMessage.
+        port.postMessage(message, transfer);
+    },
+    addEventListener(_type, listener) {
+        port.on('message', (data) => listener({ data }));
+    }
+};
+startWorkerRuntime(endpoint, async () => {
+    const bytes = await readFile(new URL('./wasm-bindgen/cantraceviewer_bg.wasm', import.meta.url));
+    // Compiling here keeps the only asynchronous step outside the synchronous direct client.
+    return createDirectClient(await WebAssembly.compile(bytes));
+});

package/dist/node.d.ts

@@ -0,0 +1,12 @@
+import type { CanTraceClient } from './rpc-client.js';
+export type { CanTraceClient } from './rpc-client.js';
+export type * from './types.js';
+/**
+ * Create a client backed by one new dedicated worker thread. Same interface, lifecycle, and
+ * ordering guarantees as the browser client; the worker reads the packaged WASM binary from disk
+ * instead of fetching it.
+ *
+ * Nothing is instantiated at module import time. Import this entry only from Node; the package root
+ * stays free of Node built-ins for browser bundles.
+ */
+export declare function createCanTraceClient(): Promise<CanTraceClient>;

package/dist/node.js

@@ -0,0 +1,25 @@
+import { Worker } from 'node:worker_threads';
+import { createNodeClientForWorker } from "./node-transport.js";
+/**
+ * Create a client backed by one new dedicated worker thread. Same interface, lifecycle, and
+ * ordering guarantees as the browser client; the worker reads the packaged WASM binary from disk
+ * instead of fetching it.
+ *
+ * Nothing is instantiated at module import time. Import this entry only from Node; the package root
+ * stays free of Node built-ins for browser bundles.
+ */
+export async function createCanTraceClient() {
+    return createNodeClientForWorker(() => new Worker(workerEntry(), { execArgv: workerExecArgv() }));
+}
+/**
+ * The packaged build ships compiled JavaScript siblings. A source checkout runs this file as
+ * TypeScript, where Node's type stripping loads the TypeScript worker entry directly.
+ */
+function workerEntry() {
+    const entry = import.meta.url.endsWith('.ts') ? './node-worker.ts' : './node-worker.js';
+    return new URL(entry, import.meta.url);
+}
+/** Flags such as `--input-type` are valid only for eval/stdin and break a file-backed Worker. */
+function workerExecArgv() {
+    return process.execArgv.filter((argument) => argument !== '--input-type' && !argument.startsWith('--input-type='));
+}