@reicek/neataptic-ts 0.1.26 → 0.1.27

package/src/methods/mutation/README.md

@@ -1,117 +1,63 @@
 # methods/mutation
 
-## methods/mutation/mutation.ts
-
-### mutation
-
-Defines various mutation methods used in neuroevolution algorithms.
-
-Mutation introduces genetic diversity into the population by randomly
-altering parts of an individual's genome (the neural network structure or parameters).
-This is crucial for exploring the search space and escaping local optima.
-
-Common mutation strategies include adding or removing nodes and connections,
-modifying connection weights and node biases, and changing node activation functions.
-These operations allow the network topology and parameters to adapt over generations.
-
-The methods listed here are inspired by techniques used in algorithms like NEAT
-and particularly the Instinct algorithm, providing a comprehensive set of tools
-for evolving network architectures.
-
-Read this file as a mutation toolbox organized by what kind of change you
-want evolution to make:
-
-- topology-growth operators such as `ADD_NODE`, `ADD_CONN`,
-  `ADD_SELF_CONN`, and `ADD_BACK_CONN` make the graph more expressive,
-- topology-pruning operators such as `SUB_NODE`, `SUB_CONN`,
-  `SUB_SELF_CONN`, and `SUB_BACK_CONN` remove structure and can simplify an
-  overgrown search,
-- parameter-tuning operators such as `MOD_WEIGHT`, `MOD_BIAS`, and
-  `REINIT_WEIGHT` change numeric behavior without rewriting the graph,
-- behavior-shaping operators such as `MOD_ACTIVATION`, `ADD_GATE`,
-  `SUB_GATE`, and `SWAP_NODES` change how existing structure computes,
-- architecture-expansion operators such as `ADD_LSTM_NODE` and
-  `ADD_GRU_NODE` introduce memory-oriented building blocks.
-
-A practical reading order is:
-
-1. start with `MOD_WEIGHT` and `MOD_BIAS` to understand the gentlest search
-   moves,
-2. then compare `ADD_CONN` and `ADD_NODE` to see how structure starts to
-   grow,
-3. then read the recurrent and gating operators when you want temporal
-   behavior or context-sensitive routing,
-4. finish with `ALL` and `FFW`, which summarize which operators belong in a
-   broad search versus a strictly feedforward one.
-
-A practical chooser for first experiments:
-
-- begin with weight and bias mutations when the topology is already plausible
-  and you mainly want numeric refinement,
-- allow `ADD_CONN` and `ADD_NODE` when the current architecture feels too
-  rigid or too shallow,
-- enable gating or back-connections only when temporal memory or dynamic
-  routing is actually part of the task,
-- prefer `FFW` as the safe shelf when a run must remain strictly
-  feedforward.
+Mutation policy shelf for neuroevolution runs.
+
+This chapter belongs in `methods/` rather than `architecture/network/mutate/`
+because it does not execute one mutation against one concrete graph. It
+defines the reusable operator vocabulary that higher-level controllers pick
+from before any specific network is touched. The network chapter later uses
+that vocabulary to dispatch real edits.
+
+Read the shelf in five families. Growth operators add structure. Pruning
+operators remove it. Parameter operators retune weights and biases without
+rewriting topology. Behavior operators change activation or gating policy.
+Memory operators add recurrent building blocks when the search should be
+allowed to invent stateful behavior.
+
+Those families matter because mutation is where an evolutionary run decides
+whether it is mostly refining a plausible graph or still exploring new
+architectures. A shelf dominated by `MOD_WEIGHT` and `MOD_BIAS` behaves like
+local numeric search. A shelf that also allows `ADD_NODE`, `ADD_CONN`, and
+gating or recurrent operators gives the run permission to change what the
+network can represent at all.
+
+`ALL` and `FFW` are the two convenience summaries at the bottom of the
+chapter. `ALL` keeps the widest search surface, including recurrence and
+memory additions. `FFW` keeps the feedforward-safe subset for runs that must
+remain acyclic.
 
 ```mermaid
 flowchart TD
-  Mutation[Mutation toolbox] --> Grow[Grow structure]
+  Mutation[Mutation shelf] --> Grow[Grow structure]
   Mutation --> Prune[Prune structure]
   Mutation --> Tune[Tune parameters]
   Mutation --> Shape[Reshape behavior]
   Mutation --> Memory[Add memory blocks]
-  Grow --> GrowItems[ADD_NODE ADD_CONN ADD_SELF_CONN ADD_BACK_CONN]
-  Prune --> PruneItems[SUB_NODE SUB_CONN SUB_SELF_CONN SUB_BACK_CONN]
-  Tune --> TuneItems[MOD_WEIGHT MOD_BIAS REINIT_WEIGHT]
-  Shape --> ShapeItems[MOD_ACTIVATION ADD_GATE SUB_GATE SWAP_NODES]
-  Memory --> MemoryItems[ADD_LSTM_NODE ADD_GRU_NODE]
 ```
 
-Minimal workflow:
+For compact background on why mutation pressure matters in evolutionary
+search, see Wikipedia contributors,
+[Mutation (genetic algorithm)](https://en.wikipedia.org/wiki/Mutation_(genetic_algorithm)).
+
+Example: keep a feedforward-safe shelf for searches that must remain simple
+and acyclic.
 
 ```ts
-const safeFeedforwardShelf = mutation.FFW;
+const feedforwardOnly = mutation.FFW;
+```
 
-const structuralSearchShelf = [
+Example: widen the shelf when structural exploration is part of the goal.
+
+```ts
+const structuralExploration = [
   mutation.ADD_CONN,
   mutation.ADD_NODE,
   mutation.MOD_WEIGHT,
-  mutation.MOD_BIAS,
-];
-
-const recurrentSearchShelf = [
-  ...structuralSearchShelf,
   mutation.ADD_GATE,
-  mutation.ADD_BACK_CONN,
 ];
 ```
 
-Supported mutation families:
-
-- `ADD_NODE`: Adds a new node by splitting an existing connection.
-- `SUB_NODE`: Removes a hidden node and its connections.
-- `ADD_CONN`: Adds a new connection between two unconnected nodes.
-- `SUB_CONN`: Removes an existing connection.
-- `MOD_WEIGHT`: Modifies the weight of an existing connection.
-- `MOD_BIAS`: Modifies the bias of a node.
-- `MOD_ACTIVATION`: Changes the activation function of a node.
-- `ADD_SELF_CONN`: Adds a self-connection (recurrent loop) to a node.
-- `SUB_SELF_CONN`: Removes a self-connection from a node.
-- `ADD_GATE`: Adds a gating mechanism to a connection.
-- `SUB_GATE`: Removes a gating mechanism from a connection.
-- `ADD_BACK_CONN`: Adds a recurrent (backward) connection between nodes.
-- `SUB_BACK_CONN`: Removes a recurrent (backward) connection.
-- `SWAP_NODES`: Swaps the roles (bias and activation) of two nodes.
-- `REINIT_WEIGHT`: Reinitializes all weights for a node.
-- `BATCH_NORM`: Marks a node for batch normalization (stub).
-- `ADD_LSTM_NODE`: Adds a new LSTM node (memory cell with gates).
-- `ADD_GRU_NODE`: Adds a new GRU node (gated recurrent unit).
-
-Summary shelves:
-- `ALL`: all mutation methods, including recurrent and memory-oriented ones.
-- `FFW`: the feedforward-safe subset that avoids recurrence and gating.
+## methods/mutation/mutation.ts
 
 ### MutationConfig
 

package/src/methods/mutation/mutation.ts

@@ -1,3 +1,61 @@
+/**
+ * Mutation policy shelf for neuroevolution runs.
+ *
+ * This chapter belongs in `methods/` rather than `architecture/network/mutate/`
+ * because it does not execute one mutation against one concrete graph. It
+ * defines the reusable operator vocabulary that higher-level controllers pick
+ * from before any specific network is touched. The network chapter later uses
+ * that vocabulary to dispatch real edits.
+ *
+ * Read the shelf in five families. Growth operators add structure. Pruning
+ * operators remove it. Parameter operators retune weights and biases without
+ * rewriting topology. Behavior operators change activation or gating policy.
+ * Memory operators add recurrent building blocks when the search should be
+ * allowed to invent stateful behavior.
+ *
+ * Those families matter because mutation is where an evolutionary run decides
+ * whether it is mostly refining a plausible graph or still exploring new
+ * architectures. A shelf dominated by `MOD_WEIGHT` and `MOD_BIAS` behaves like
+ * local numeric search. A shelf that also allows `ADD_NODE`, `ADD_CONN`, and
+ * gating or recurrent operators gives the run permission to change what the
+ * network can represent at all.
+ *
+ * `ALL` and `FFW` are the two convenience summaries at the bottom of the
+ * chapter. `ALL` keeps the widest search surface, including recurrence and
+ * memory additions. `FFW` keeps the feedforward-safe subset for runs that must
+ * remain acyclic.
+ *
+ * ```mermaid
+ * flowchart TD
+ *   Mutation[Mutation shelf] --> Grow[Grow structure]
+ *   Mutation --> Prune[Prune structure]
+ *   Mutation --> Tune[Tune parameters]
+ *   Mutation --> Shape[Reshape behavior]
+ *   Mutation --> Memory[Add memory blocks]
+ * ```
+ *
+ * For compact background on why mutation pressure matters in evolutionary
+ * search, see Wikipedia contributors,
+ * [Mutation (genetic algorithm)](https://en.wikipedia.org/wiki/Mutation_(genetic_algorithm)).
+ *
+ * Example: keep a feedforward-safe shelf for searches that must remain simple
+ * and acyclic.
+ *
+ * ```ts
+ * const feedforwardOnly = mutation.FFW;
+ * ```
+ *
+ * Example: widen the shelf when structural exploration is part of the goal.
+ *
+ * ```ts
+ * const structuralExploration = [
+ *   mutation.ADD_CONN,
+ *   mutation.ADD_NODE,
+ *   mutation.MOD_WEIGHT,
+ *   mutation.ADD_GATE,
+ * ];
+ * ```
+ */
 import Activation from '../activation/activation';
 
 /**

package/src/multithreading/README.md

@@ -1,24 +1,112 @@
 # multithreading
 
-Shared types for multithreading helpers and test workers.
+Worker-oriented evaluation helpers and serialization compatibility shelf.
+
+This chapter exists for a practical scaling problem: evolutionary evaluation
+is usually embarrassingly parallel, but live `Network` instances, activation
+closures, and environment-specific worker APIs do not cross thread boundaries
+cleanly. The multithreading root turns that mismatch into a teachable
+contract: flatten the network and dataset into portable numeric arrays, keep
+activation functions in a stable index order, and let browser or Node workers
+evaluate the same payload shape without needing the whole runtime object
+graph.
+
+The most important idea here is not "threads are faster." It is boundary
+control. A worker can only do useful NEAT work if the training host and the
+worker agree on three things: how a network is serialized, how activations
+are decoded, and how the result comes back as a scalar score. This root file
+keeps that contract explicit so the rest of the library can talk about
+parallel evaluation without hand-waving away the serialization boundary.
+
+The chapter is intentionally narrow. It does not implement a generic
+scheduler or a broad actor framework. It exposes a small compatibility shelf
+around two tasks that matter for evaluation: ship datasets and networks
+across a worker boundary, and run the same ordered activation logic on the
+other side. That makes the boundary useful both for actual worker-backed
+evaluation and for teaching how data-parallel neural evaluation is shaped.
+
+Read the root in three passes:
+
+1. `serializeDataSet()` and `deserializeDataSet()` for the portable sample
+   format.
+2. `activations` and `activateSerializedNetwork()` for the flat execution
+   contract.
+3. `getBrowserTestWorker()` and `getNodeTestWorker()` for the runtime-
+   specific loader boundary.
+
+`browser/` and `node/` own the environment-specific worker wrappers, while
+`multi.utils.ts` owns the flat-array execution mechanics. The root stays
+orchestration-first for the same reason as the rest of the repo: readers
+should see the contract before they see the inner loops.
+
+The background idea here is close to what distributed-systems and HPC writing
+often call an embarrassingly parallel workload: each genome can be evaluated
+independently once its inputs and scoring context are serialized. See
+Wikipedia contributors,
+[Embarrassingly parallel](https://en.wikipedia.org/wiki/Embarrassingly_parallel),
+for compact background on why evolutionary evaluation is such a natural fit
+for worker-style execution.
+
+```mermaid
+flowchart LR
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+
+  Host[Training or test host]:::base --> Serialize[Flatten dataset and network]:::accent
+  Serialize --> Worker[Browser or Node worker]:::base
+  Worker --> Activate[Run ordered activation logic]:::base
+  Activate --> Score[Return scalar evaluation]:::accent
+```
+
+```mermaid
+flowchart TD
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+
+  Multi[Multi root facade]:::accent --> Dataset[serializeDataSet / deserializeDataSet]:::base
+  Multi --> Runtime[Browser and Node worker loaders]:::base
+  Multi --> Activations[Stable activation index registry]:::base
+  Activations --> FlatExecution[activateSerializedNetwork]:::base
+  Runtime --> Workers[workers/]:::base
+```
+
+Example: serialize one dataset once and evaluate a network in a Node worker.
+
+```ts
+const serializedSet = Multi.serializeDataSet([
+  { input: [0, 0], output: [0] },
+  { input: [1, 1], output: [1] },
+]);
+
+const NodeWorker = await Multi.getNodeTestWorker();
+const worker = new NodeWorker(serializedSet, { name: 'mse' });
+const score = await worker.evaluate(network);
+worker.terminate();
+```
+
+Example: run the worker-compatible flat activation path locally.
+
+```ts
+const [activationValues, stateValues, serializedNetwork] = network.serialize();
+const outputValues = Multi.activateSerializedNetwork(
+  [0, 1],
+  activationValues.slice(),
+  stateValues.slice(),
+  serializedNetwork,
+  Multi.activations,
+);
+```
 
 ## multithreading/multi.ts
 
-### multi
-
-Multi-threading utilities for neural network operations.
-
-This class provides methods for serializing datasets, activating serialized networks,
-and testing serialized datasets. These utilities align with the Instinct algorithm's
-emphasis on efficient evaluation and mutation of neural networks in parallel environments.
-
 ### Multi
 
-Multi-threading utilities for neural network operations.
+Stable compatibility facade for worker-oriented evaluation helpers.
 
-This class provides methods for serializing datasets, activating serialized networks,
-and testing serialized datasets. These utilities align with the Instinct algorithm's
-emphasis on efficient evaluation and mutation of neural networks in parallel environments.
+Read `Multi` as the small public shelf around three related contracts:
+portable dataset serialization, flat-array network activation, and runtime-
+specific worker loading. The heavier mechanics live in `multi.utils.ts` and
+`workers/`, but the class keeps the outside-facing API compact and familiar.
 
 ### default
 
@@ -301,6 +389,13 @@ Workers for multi-threading
 
 ## multithreading/types.ts
 
+Shared contracts for the multithreading boundary.
+
+These types keep the worker-facing evaluation surface small: ordered
+activation functions, serialized input/output samples, a serializable network
+shape, and the worker constructor protocol used by the browser and Node test
+worker wrappers.
+
 ### ActivationFn
 
 ```ts
@@ -309,7 +404,12 @@ ActivationFn(
 ): number
 ```
 
-Shared types for multithreading helpers and test workers.
+Shared contracts for the multithreading boundary.
+
+These types keep the worker-facing evaluation surface small: ordered
+activation functions, serialized input/output samples, a serializable network
+shape, and the worker constructor protocol used by the browser and Node test
+worker wrappers.
 
 ### SerializableNetwork
 

package/src/multithreading/docs.order.json

@@ -0,0 +1,5 @@
+{
+  "introFile": "multi.ts",
+  "fileOrder": ["multi.ts", "types.ts", "multi.utils.ts"],
+  "folderOrder": ["workers"]
+}

package/src/multithreading/multi.ts

@@ -1,3 +1,101 @@
+/**
+ * Worker-oriented evaluation helpers and serialization compatibility shelf.
+ *
+ * This chapter exists for a practical scaling problem: evolutionary evaluation
+ * is usually embarrassingly parallel, but live `Network` instances, activation
+ * closures, and environment-specific worker APIs do not cross thread boundaries
+ * cleanly. The multithreading root turns that mismatch into a teachable
+ * contract: flatten the network and dataset into portable numeric arrays, keep
+ * activation functions in a stable index order, and let browser or Node workers
+ * evaluate the same payload shape without needing the whole runtime object
+ * graph.
+ *
+ * The most important idea here is not "threads are faster." It is boundary
+ * control. A worker can only do useful NEAT work if the training host and the
+ * worker agree on three things: how a network is serialized, how activations
+ * are decoded, and how the result comes back as a scalar score. This root file
+ * keeps that contract explicit so the rest of the library can talk about
+ * parallel evaluation without hand-waving away the serialization boundary.
+ *
+ * The chapter is intentionally narrow. It does not implement a generic
+ * scheduler or a broad actor framework. It exposes a small compatibility shelf
+ * around two tasks that matter for evaluation: ship datasets and networks
+ * across a worker boundary, and run the same ordered activation logic on the
+ * other side. That makes the boundary useful both for actual worker-backed
+ * evaluation and for teaching how data-parallel neural evaluation is shaped.
+ *
+ * Read the root in three passes:
+ *
+ * 1. `serializeDataSet()` and `deserializeDataSet()` for the portable sample
+ *    format.
+ * 2. `activations` and `activateSerializedNetwork()` for the flat execution
+ *    contract.
+ * 3. `getBrowserTestWorker()` and `getNodeTestWorker()` for the runtime-
+ *    specific loader boundary.
+ *
+ * `browser/` and `node/` own the environment-specific worker wrappers, while
+ * `multi.utils.ts` owns the flat-array execution mechanics. The root stays
+ * orchestration-first for the same reason as the rest of the repo: readers
+ * should see the contract before they see the inner loops.
+ *
+ * The background idea here is close to what distributed-systems and HPC writing
+ * often call an embarrassingly parallel workload: each genome can be evaluated
+ * independently once its inputs and scoring context are serialized. See
+ * Wikipedia contributors,
+ * [Embarrassingly parallel](https://en.wikipedia.org/wiki/Embarrassingly_parallel),
+ * for compact background on why evolutionary evaluation is such a natural fit
+ * for worker-style execution.
+ *
+ * ```mermaid
+ * flowchart LR
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   Host[Training or test host]:::base --> Serialize[Flatten dataset and network]:::accent
+ *   Serialize --> Worker[Browser or Node worker]:::base
+ *   Worker --> Activate[Run ordered activation logic]:::base
+ *   Activate --> Score[Return scalar evaluation]:::accent
+ * ```
+ *
+ * ```mermaid
+ * flowchart TD
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   Multi[Multi root facade]:::accent --> Dataset[serializeDataSet / deserializeDataSet]:::base
+ *   Multi --> Runtime[Browser and Node worker loaders]:::base
+ *   Multi --> Activations[Stable activation index registry]:::base
+ *   Activations --> FlatExecution[activateSerializedNetwork]:::base
+ *   Runtime --> Workers[workers/]:::base
+ * ```
+ *
+ * Example: serialize one dataset once and evaluate a network in a Node worker.
+ *
+ * ```ts
+ * const serializedSet = Multi.serializeDataSet([
+ *   { input: [0, 0], output: [0] },
+ *   { input: [1, 1], output: [1] },
+ * ]);
+ *
+ * const NodeWorker = await Multi.getNodeTestWorker();
+ * const worker = new NodeWorker(serializedSet, { name: 'mse' });
+ * const score = await worker.evaluate(network);
+ * worker.terminate();
+ * ```
+ *
+ * Example: run the worker-compatible flat activation path locally.
+ *
+ * ```ts
+ * const [activationValues, stateValues, serializedNetwork] = network.serialize();
+ * const outputValues = Multi.activateSerializedNetwork(
+ *   [0, 1],
+ *   activationValues.slice(),
+ *   stateValues.slice(),
+ *   serializedNetwork,
+ *   Multi.activations,
+ * );
+ * ```
+ */
 import { Workers } from './workers/workers';
 import type {
   ActivationFn,
@@ -29,14 +127,12 @@ import {
 } from './multi.utils';
 
 /**
- * Multi-threading utilities for neural network operations.
- *
- * This class provides methods for serializing datasets, activating serialized networks,
- * and testing serialized datasets. These utilities align with the Instinct algorithm's
- * emphasis on efficient evaluation and mutation of neural networks in parallel environments.
+ * Stable compatibility facade for worker-oriented evaluation helpers.
  *
- * @see Instinct Algorithm - Section 4 Constraints
- * @see {@link https://medium.com/data-science/neuro-evolution-on-steroids-82bd14ddc2f6}
+ * Read `Multi` as the small public shelf around three related contracts:
+ * portable dataset serialization, flat-array network activation, and runtime-
+ * specific worker loading. The heavier mechanics live in `multi.utils.ts` and
+ * `workers/`, but the class keeps the outside-facing API compact and familiar.
  */
 export default class Multi {
   /** Workers for multi-threading */

package/src/multithreading/types.ts

@@ -1,5 +1,10 @@
 /**
- * Shared types for multithreading helpers and test workers.
+ * Shared contracts for the multithreading boundary.
+ *
+ * These types keep the worker-facing evaluation surface small: ordered
+ * activation functions, serialized input/output samples, a serializable network
+ * shape, and the worker constructor protocol used by the browser and Node test
+ * worker wrappers.
  */
 export type ActivationFn = (x: number) => number;
 

package/src/multithreading/workers/README.md

@@ -1,12 +1,82 @@
 # multithreading/workers
 
-Utility class for managing workers in both Node.js and browser environments.
+Runtime loader shelf for browser and Node evaluation workers.
+
+The multithreading root explains the serialization contract. This file
+answers a narrower question: once a dataset and a network have already been
+flattened into portable arrays, which runtime-specific worker wrapper should
+own the evaluation run?
+
+Keeping that choice behind one tiny loader shelf has two benefits. The host
+runtime can defer importing browser-only or Node-only code until it actually
+needs it, and the rest of the library can talk about one worker boundary
+without pretending that Web Workers and forked Node helpers expose the same
+constructor surface.
+
+`getBrowserTestWorker()` loads the wrapper that creates a blob-backed worker
+in the browser. `getNodeTestWorker()` loads the wrapper that forks a helper
+process in Node. Both wrappers consume the same serialized payload shape and
+return the same scalar evaluation contract.
+
+```mermaid
+flowchart LR
+  Host[Host runtime] --> Choose[Choose worker wrapper]
+  Choose --> Browser[Browser worker facade]
+  Choose --> Node[Node worker facade]
+  Browser --> Score[Scalar evaluation]
+  Node --> Score
+```
+
+Example: choose the runtime-specific worker facade without importing both
+implementations up front.
+
+```ts
+const WorkerClass =
+  typeof window === 'undefined'
+    ? await Workers.getNodeTestWorker()
+    : await Workers.getBrowserTestWorker();
+```
 
 ## multithreading/workers/workers.ts
 
 ### Workers
 
-Utility class for managing workers in both Node.js and browser environments.
+Runtime loader shelf for browser and Node evaluation workers.
+
+The multithreading root explains the serialization contract. This file
+answers a narrower question: once a dataset and a network have already been
+flattened into portable arrays, which runtime-specific worker wrapper should
+own the evaluation run?
+
+Keeping that choice behind one tiny loader shelf has two benefits. The host
+runtime can defer importing browser-only or Node-only code until it actually
+needs it, and the rest of the library can talk about one worker boundary
+without pretending that Web Workers and forked Node helpers expose the same
+constructor surface.
+
+`getBrowserTestWorker()` loads the wrapper that creates a blob-backed worker
+in the browser. `getNodeTestWorker()` loads the wrapper that forks a helper
+process in Node. Both wrappers consume the same serialized payload shape and
+return the same scalar evaluation contract.
+
+```mermaid
+flowchart LR
+  Host[Host runtime] --> Choose[Choose worker wrapper]
+  Choose --> Browser[Browser worker facade]
+  Choose --> Node[Node worker facade]
+  Browser --> Score[Scalar evaluation]
+  Node --> Score
+```
+
+Example: choose the runtime-specific worker facade without importing both
+implementations up front.
+
+```ts
+const WorkerClass =
+  typeof window === 'undefined'
+    ? await Workers.getNodeTestWorker()
+    : await Workers.getBrowserTestWorker();
+```
 
 #### getBrowserTestWorker
 

package/src/multithreading/workers/browser/README.md

@@ -1,5 +1,44 @@
 # multithreading/workers/browser
 
+Browser-side evaluation worker wrapper for serialized networks.
+
+This chapter is the Web Worker half of the multithreading boundary. It does
+not teach activation math again. Its job is to take the flat dataset and
+network contract from `multithreading/`, package it into browser-friendly
+transfer buffers, and return one scalar error without blocking the main
+thread.
+
+The lifecycle is intentionally coarse grained. The constructor transfers the
+dataset once and creates a blob-backed worker program. Each `evaluate()` call
+then sends only the activation, state, and connection buffers for one
+candidate network. That keeps the wrapper focused on whole-network scoring
+jobs rather than chatty per-layer messaging.
+
+Read the file in runtime order: constructor first, `evaluate()` second,
+`_createBlobString()` last. That matches the actual browser story: bootstrap
+a worker, run repeated evaluations, then inspect how the inline worker code
+is assembled.
+
+```mermaid
+flowchart LR
+  Host[Browser host] --> Dataset[Transfer dataset once]
+  Dataset --> Blob[Create blob worker]
+  Blob --> Evaluate[Transfer network buffers]
+  Evaluate --> Error[Return scalar error]
+```
+
+For background on the browser primitive behind this wrapper, see MDN Web
+Docs,
+[Using Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers).
+
+Example: create one browser worker and reuse it across repeated evaluations.
+
+```ts
+const worker = new TestWorker(serializedSet, { name: 'mse' });
+const score = await worker.evaluate(network);
+worker.terminate();
+```
+
 ## multithreading/workers/browser/testworker.ts
 
 ### CostFunction