j-templates 9.0.0 → 10.0.0

package/Node/vNode.js

@@ -312,6 +312,8 @@ function ScheduledAssignment(assign) {
             return;
         scheduled = true;
         NodeConfig.scheduleUpdate(function () {
+            if (ObservableScope.IsDestroyed(scope))
+                return;
             scheduled = false;
             const value = ObservableScope.Peek(scope);
             assign(value);

package/SYNTAX_PRIMER.md

@@ -8,7 +8,7 @@ Reference for building apps with j-templates 8.1.0. Every behavioral claim was c
 
 Read Mental model, then Templates and State decorators before writing a component. Check the Traps checklist before shipping.
 
-- **Version:** j-templates 8.1.0. The 8.0.19 claims were tested in jsdom with TypeScript (`experimentalDecorators`). 8.0.21 changed `peek`, how `@Computed` notifies readers, and emitter re-entry. 8.0.23 moved `Bound()` after the first render and added `Connected()`. 8.0.24 fixed dotted projection reads through keyed entities. 8.0.27 batches `StoreAsync` changes. 8.1.0 added `PushStore` and `DiffTreeWriter`, and moved the diff types and `PROJECTION_PREFIX` to `j-templates/Store/Diff`. Each of those sections was re-verified in jsdom against the version that changed it.
+- **Version:** j-templates 8.1.0. The 8.0.19 claims were tested in jsdom with TypeScript (`experimentalDecorators`). 8.0.21 changed `peek`, how `@Computed` notifies readers, and emitter re-entry. 8.0.23 moved `Bound()` after the first render and added `Connected()`. 8.0.24 fixed dotted projection reads through keyed entities. 8.0.27 batches `StoreAsync` changes. 8.1.0 added `PushStore` and `DiffTreeWriter`, and moved the diff types and `PROJECTION_PREFIX` to `j-templates/Store/Diff`. Unreleased (this branch): `ObservableDiffTree`, `HostPublisher` and a `StoreAsync` that applies the tree's commits replace `PushStore`, `DiffTreeWriter`, `WorkerQueue` and `ConnectWorkerToDiffTree`; those sections were verified against the test suite. Each of those sections was re-verified in jsdom against the version that changed it.
 - **Not verified:** a real browser `Worker` (a structured-clone shim stood in), real focus behavior, and the `docs/`, `examples/` and `src/` folders the package does not ship.
 - **Convention:** `this.x` in examples is a component field decorated with `@Value` or `@State` unless shown otherwise. Imports are omitted after the first example.
 
@@ -55,11 +55,11 @@ npm install j-templates
 | --- | --- |
 | `j-templates` | `Component`, `scope`, `gate`, `peek`, `mapped`; type `vNode` |
 | `j-templates/DOM` | element functions (below), `text`, `fragment`, `CreateRootPropertyAssignment`, `CreateEventAssignment`, `PropertyAssignment`, `EventAssignment` |
-| `j-templates/Utils` | `Value`, `State`, `Computed`, `ComputedAsync`, `Scope`, `Watch`, `Inject`, `Destroy`, `Bound`, `Animation`, `AnimationType`, `Injector`; type `IDestroyable` |
-| `j-templates/Store` | `ReadStore`, `Store`, `StoreSync`, `StoreAsync`, `PushStore`, `ObservableScope`, `ObservableNode` |
-| `j-templates/Store/Diff` | `PROJECTION_PREFIX`, `DIFF_TREE_EVENT`, `DIFF_TREE_ERROR`; types `DiffTreeProjectionMap`, `DiffTreeProjectionDefinition`, `DiffTreeProjectionFunc`, `IDiffPushEvent`, `DiffSpliceResult`, `IDiffTree` and the batch types. Types and constants only, so a worker bundle can import it. |
+| `j-templates/Utils` | `Value`, `State`, `Computed`, `Scope`, `Watch`, `Inject`, `Destroy`, `Bound`, `Animation`, `AnimationType`, `Injector`, `SubscriptionManager`; types `IDestroyable`, `KeyFilter`, `ISubscriptionMatch` |
+| `j-templates/Store` | `ReadStore`, `Store`, `StoreSync`, `StoreAsync`, `ObservableScope`, `ObservableNode`, `Opaque`; types `IStoreOptions`, `IStoreAsyncOptions`, `IStoreSyncOptions` |
+| `j-templates/Store/Diff` | `PROJECTION_PREFIX`, `MESSAGE_PREFIX`; types `DiffTreeProjectionMap`, `DiffTreeProjectionDefinition`, `DiffTreeProjectionFunc`, `DiffSpliceResult`, `IDiffTree`, the batch types, the tree's `IObservableDiffTreeConfig`, `DeliveryForm`, `ISubscribeOptions`, `IDiffPost`, `ISnapshotUpdate`, and the channel's `IChannel`, `IHostRequest`, `IHostMessage`, `IConnectMessage`, `IWorkerLease`, `ILocalLease`, and the endpoint's `IDiffTreeEndpoint` and its option types; `FollowRoutes`, and `DiffTreeEndpoint`. Nothing that reads `window`, so a worker bundle can import it. |
 
-**Deep imports used below:** `j-templates/Store/Diff/diffTree` (`DiffTree`), `j-templates/Store/Diff/diffTreeWorker` (`ConnectWorkerToDiffTree`), `j-templates/Store/Diff/diffTreeWriter` (`DiffTreeWriter`), `j-templates/Node/vNode` (`vNode.Destroy`). `j-templates/Store/Diff/defaultDiffTreeWorker` runs worker code on import and throws outside a worker (`self is not defined`).
+**Deep imports used below:** `j-templates/Store/Diff/diffTree` (`DiffTree`), `j-templates/Store/Diff/observableDiffTree` (`ObservableDiffTree`), `j-templates/Store/Diff/hostPublisher` (`HostPublisher`), `j-templates/Store/Diff/channelClient` (`Subscribe`, `Once`, `ChannelClient`), `j-templates/Store/Diff/diffTreeHub` (`DiffTreeHub`), `j-templates/Store/Diff/diffTreeEndpoint` (`DiffTreeEndpoint`), `j-templates/Store/Diff/onConnect` (`OnConnect`), `j-templates/Node/vNode` (`vNode.Destroy`). `j-templates/Store/Diff/defaultDiffTreeWorker` runs worker code on import and throws outside a worker (`self is not defined`).
 
 **Element functions** (all verified present):
 
@@ -283,7 +283,6 @@ Decorators work on component classes only. Services use `ObservableScope`, `Obse
 | `@State()` | plain objects and arrays mutated in place | a deep reactive proxy | on any tracked write |
 | `@Scope()` getter | cheap derivations; filters/sorts of existing objects | whatever the getter returns (new object each run if it builds one) | lazily, on the next read after a change |
 | `@Computed()` getter | building new objects consumed in several places | the **same** object every time, updated in place | eagerly, when a dependency changes |
-| `@ComputedAsync(default)` getter | as `@Computed`, diffed off-thread | same object every time; `default` until first result | eagerly |
 | `@Watch(sel)` method | side effects on change | — | — |
 | `@Inject(Type)` field | dependency injection | — | — |
 | `@Destroy()` field | calling `.Destroy()` at teardown | — | — |
@@ -340,19 +339,6 @@ Tracked array methods: `push`, `pop`, `shift`, `unshift`, `splice`, `sort`, `rev
 - The copy step reads every property of the result, so all of them become dependencies. Returning a `@State` array therefore re-runs the getter when any item property changes (verified).
 - No arguments. Prefer `@Scope` or a plain getter for cheap values.
 
-### @ComputedAsync
-
-```typescript
-@ComputedAsync(null) get user(): User | null {
-  return { id: this.userId, name: lookupName(this.userId) }; // must be synchronous
-}
-```
-
-- The getter must be synchronous. "Async" refers to the backend: results are diffed in a `StoreAsync` worker.
-- Returns `default` first, then the computed object, with the same reference across updates (verified).
-- Each instance creates `new Worker(new URL("../Store/Diff/defaultDiffTreeWorker.js", import.meta.url), { type: "module" })` (from source). It needs a real `Worker` and a bundler that handles `new URL(…, import.meta.url)`. In jsdom tests, stub `globalThis.Worker` (see Scheduling, errors and testing).
-- For genuinely async data, use `@Scope()` + `scope(async () => …)` or `ObservableScope.Create(async () => …)`.
-
 ### @Watch
 
 ```typescript
@@ -533,15 +519,16 @@ class Injector {
 
 ## Store
 
-A store holds reactive data under string keys and diffs every write into existing objects in place. Use `StoreSync` unless diffing large data blocks the main thread. Use `PushStore` when a worker produces the data itself, such as the result of a computation it runs.
+A store holds reactive data under string keys and diffs every write into existing objects in place. Use `StoreSync` unless diffing large data blocks the main thread. Use `StoreAsync` when the tree lives in a worker, whether the main thread writes it, the worker produces the data itself, or both.
 
-|  | `StoreSync` | `StoreAsync` | `PushStore` |
-| --- | --- | --- | --- |
-| Constructor | `new StoreSync(keyFunc?, projections?)` | `new StoreAsync(worker, keyFunc?)` | `new PushStore(source, keyFunc?)` |
-| Diffing | main thread, synchronous | in the `Worker` you supply | in the `DiffTreeWriter` that pushes to it |
-| Writes | `void`; readable immediately | `Promise`; batched per tick, readable only after `await` | none; read-only. Changes arrive when the writer calls `Commit()` |
-| `Destroy()` | none | required; terminates the worker | required; stops listening, leaves the worker running |
-| Backs | nothing (`@Computed` uses `ObservableNode` directly) | `@ComputedAsync` | nothing |
+|  | `StoreSync` | `StoreAsync` |
+| --- | --- | --- |
+| Constructor | `new StoreSync(tree?, options?)`: `tree` is `hub.OpenLocal(name)`, an `ObservableDiffTree` (for routes), or left out for an empty tree of its own | `new StoreAsync(channel, options?)`; the channel may be `hub.Open(name)` |
+| Options | `{ keyFunc?, roots?, opaque? }`. `keyFunc` only for a tree with none to give: a lease's is the endpoint's and a given tree's its own, and giving one there too throws | `{ keyFunc?, roots?, opaque? }`. `keyFunc` only over a plain channel; a lease's is the endpoint's, and giving one too throws |
+| Diffing | main thread, synchronous | in the worker's `ObservableDiffTree`, served by `HostPublisher` |
+| Writes | `void`; readable immediately | `Promise`; batched per tick, readable once it resolves. Optional: without writes it's a read-only view of the tree |
+| Changes from elsewhere | commits made on `store.Tree` | every commit the worker's tree makes, whatever caused it |
+| `Destroy()` | stops applying commits; over a lease, releases it | required; unsubscribes and stops listening. Over a lease, releases it; over a channel, leaves the worker running |
 
 ### API
 
@@ -555,14 +542,14 @@ Push(key: string, ...items: unknown[]);      // append to the array at key
 Splice(key: string, start: number, deleteCount?: number, ...items: unknown[]); // returns removed items
 ```
 
-`StoreAsync` has the same methods; the four writers return promises. It also has `Flush()` (see below). `PushStore` has only `Get` and `Has`, plus `Error` (see PushStore and DiffTreeWriter).
+`StoreAsync` has the same methods; the four writers return promises. It also has `Flush()` (see below).
 
 ### keyFunc and flattening
 
 `keyFunc(value)` returns an id for any object (or `undefined`). On `Write`/`Push`, every nested object with an id is also stored under that id, so it can be patched directly while `Get` still returns the original shape.
 
 ```typescript
-const store = new StoreSync((v: any) => v?.id);
+const store = new StoreSync(undefined, { keyFunc: (v: any) => v?.id });
 store.Write([{ id: "a", done: false }, { id: "b", done: false }], "todos");
 store.Patch("a", { done: true });              // targets the nested item by id
 store.Get<Todo[]>("todos", [])[0].done;        // true
@@ -575,42 +562,48 @@ store.Get<Todo[]>("todos", [])[0].done;        // true
 
 ### StoreAsync and its worker
 
-Supply a running `Worker` whose entry file connects a `DiffTree`. Any `keyFunc` or projections used for diffing must live in that file; the constructor's `keyFunc` only resolves ids on the main thread.
+Supply a channel to a worker whose entry file hosts an `ObservableDiffTree`: a `Worker`, or a `MessagePort` to one. Any `keyFunc` or projections used for diffing must live in that file; the constructor's `keyFunc` only resolves ids on the main thread.
 
 ```typescript
 // diff-worker.ts (bundled as its own worker entry)
-import { DiffTree } from "j-templates/Store/Diff/diffTree";
-import { ConnectWorkerToDiffTree } from "j-templates/Store/Diff/diffTreeWorker";
-ConnectWorkerToDiffTree(new DiffTree((v: any) => v?.id), self as any as Worker);
+import { ObservableDiffTree } from "j-templates/Store/Diff/observableDiffTree";
+import { HostPublisher } from "j-templates/Store/Diff/hostPublisher";
+HostPublisher(new ObservableDiffTree({ keyFunc: (v: any) => v?.id }), self as any);
 
 // main thread
 const worker = new Worker(new URL("./diff-worker.ts", import.meta.url), { type: "module" });
-const store = new StoreAsync(worker, (v: any) => v?.id);
+const store = new StoreAsync(worker, { keyFunc: (v: any) => v?.id });
 await store.Write(todos, "todos");
-store.Get("todos");   // only now defined
+store.Get("todos");   // defined once the write resolves
 store.Destroy();      // when done
+worker.terminate();   // the worker is yours to end
 ```
 
 Data crosses the worker boundary by structured clone. Class instances arrive as plain objects without their methods; functions cannot be sent. Store plain data.
 
-**Batching (8.0.27).** Every `Write`, `Patch`, `Push` and `Splice` made in the same tick goes to the worker as one message and is applied in call order. The worker runs projections once per batch, after the last change, not after each one. Verified: a `Write`, a `Push` and a `Patch` in one tick sent one message and ran a projection once.
+**The store subscribes to the tree.** On construction it sends `jt-subscribe` and applies every commit the tree posts, in arrival order: its own batches, other writers', and the worker's own work. A store created after the tree has committed starts from the committed state. `options.roots` limits the roots it receives (exact keys and `task_*` patterns); a root it writes but doesn't receive is never read back. The channel can carry the app's own messages too: `HostPublisher` and the store use `addEventListener` and handle only `jt-` messages.
+
+**Batching (8.0.27).** Every `Write`, `Patch`, `Push` and `Splice` made in the same tick goes to the worker as one `jt-batch` and is applied in call order. The worker runs projections once per batch, after the last change, and commits. At most one batch waits behind the one in flight.
 
+- A change's promise resolves on its batch's `jt-ack`, which the host sends after the commit's posts, so the change has been applied when it resolves. A commit the worker makes while the batch is in flight is applied too, but doesn't resolve it.
 - You don't have to await a change before making the next one. `Patch`, `Push` and `Splice` accept a key whose `Write` is still pending, and `Patch` merges in the worker, on top of everything before it.
 - The pending-key check covers only the key passed to `Write`. Entities that `keyFunc` will flatten out of that write don't exist yet: `Patch("a", …)` right after an un-awaited `Write([{ id: "a" }], "todos")` rejects with `Key not found in store` (verified). Await the write first.
-- `await store.Flush()` waits for every change made before the call. Changes made after it go in a later batch.
-- **A failed change stops the store.** After any change fails in the worker (for example `Splice` on a value that isn't an array), every later `Write`, `Patch`, `Push`, `Splice` and `Flush` rejects with that same error (verified). Validate before writing; a store in this state has to be replaced.
+- `await store.Flush()` waits for every batch sent before the call to be acknowledged, and resolves at once when none is in flight. It rejects with the first error among those batches. Changes made after it go in a later batch.
+- **A failed batch rejects only itself.** When a change fails in the worker (for example `Splice` on a value that isn't an array), the calls after it and the batch's projections are skipped, what the batch applied before it is committed, and every change in that batch rejects with the error. Later batches carry on, and the next one's projections catch up. A projection that throws fails its batch the same way.
 
 ### Projections
 
-A projection is a derived value the store computes and stores under `$projection_<name>`. Pass them as `StoreSync`'s second argument (for `StoreAsync`, to the worker's `DiffTree`).
+A projection is a derived value the store computes and stores under `$projection_<name>`. Give them to the tree's root route, and the tree to `StoreSync` (for `StoreAsync`, to the worker's tree). The store takes the tree's keyFunc.
 
 ```typescript
 import { PROJECTION_PREFIX } from "j-templates/Store/Diff"; // "$projection_"
 
-const store = new StoreSync((v: any) => v?.id, {
+import { ObservableDiffTree } from "j-templates/Store/Diff/observableDiffTree";
+
+const store = new StoreSync(new ObservableDiffTree({ keyFunc: (v: any) => v?.id, routes: { "/": { projections: {
   activeCount: { reads: ["todos"], projection: (keys, todos) => todos.filter((t) => !t.done).length },
   doubled: { reads: [`${PROJECTION_PREFIX}activeCount`], projection: (keys, n) => n * 2 },
-});
+} } } }));
 store.Write(todos, "todos");
 store.Get<number>(`${PROJECTION_PREFIX}activeCount`);
 ```
@@ -621,38 +614,136 @@ store.Get<number>(`${PROJECTION_PREFIX}activeCount`);
 - A projection has no value until every read resolves. It re-runs when a read's value changes.
 - A cycle or a read of an undefined projection throws at construction.
 - A dotted read can pass through a keyed entity (`"doc.owner.name"`, where `owner` has an id). It reads the entity's own root, so a `Patch` to the entity reruns the projection with the new value (verified; before 8.0.24 such a read returned the stale embedded copy).
-- `StoreSync` and the `StoreAsync` worker run projections for you, and a `DiffTreeWriter` runs them in `Commit()`. `DiffTree.DiffPath`, `PatchPath`, `PushPath` and `SplicePath` don't (8.0.27): code that drives a `DiffTree` directly, such as a test, must call `tree.RunProjections()` after its writes (verified).
+- `StoreSync` and the `StoreAsync` worker run projections for each batch. An `ObservableDiffTree`'s `Commit()` doesn't run them. `DiffTree.DiffPath`, `PatchPath`, `PushPath` and `SplicePath` don't (8.0.27): code that drives a `DiffTree` directly, such as a test, must call `tree.RunProjections()` after its writes (verified).
+
+### Opaque roots
+
+A root that only grows with the data, such as a drawing of every row, is expensive to diff field by field and to read through proxies. List its key in the store's `opaque` option to hold it whole:
+
+```typescript
+const layoutConfig = { opaque: ["$projection_layout"] };   // the tree writes it whole, the store holds it whole
+const store = new StoreSync(new ObservableDiffTree({ keyFunc, routes, ...layoutConfig }), layoutConfig);
+const layout = store.Get<Layout>("$projection_layout"); // the raw value: no proxies inside it
+```
+
+- The key can be a written root or a projection's `$projection_<key>`. The tree writes it whole whenever it changes (`DiffTree.MarkOpaque`): a `StoreSync` marks the empty tree it creates (`new StoreSync(undefined, { opaque })`), and a tree it's given has the keys in its config. `StoreAsync` sends the keys to its worker ahead of the first change. A store on a hub's tree needs the tree to write the key whole too: give both the same keys from a file both import (`new ObservableDiffTree({ endpoint, routes, ...searchConfig })`, `new StoreAsync(hub.Open("search"), searchConfig)`).
+- `Get` returns the same reference until the root changes, and only that change updates its readers. A write that changes nothing updates no one.
+- The value is the store's own: treat it as read-only. A change made inside it notifies no one, and under `StoreSync` it is also the `DiffTree`'s committed snapshot.
+- Write the raw value. Don't pass an `Opaque` to `Write`, `Patch`, `Push` or `Splice`, at any depth: the store boxes the root itself, and a box written to a store isn't opened (under `StoreAsync` it arrives as a plain `{ value }`).
+- An opaque root can't be read through a key: a `keyFunc` alias that resolves to one throws.
+
+### ObservableDiffTree
+
+An `ObservableDiffTree` is a `DiffTree` that delivers every `Commit()` to its subscribers: the tree's whole API (`WritePath`, `PatchPath`, `PushPath`, `SplicePath`, `ApplyDiff`, `DeleteRoot`, `DeleteRoute`, `RunProjections`, `MarkOpaque`, `ReadPath`, `Snapshot`, `Committed`, `CommittedKeys`), with `Commit()` delivering what it diffs. `StoreSync` subscribes to one it creates, exposed as `store.Tree`.
+
+```typescript
+import { ObservableDiffTree } from "j-templates/Store/Diff/observableDiffTree";
+const tree = new ObservableDiffTree({ keyFunc, routes });   // and `endpoint`, `opaque`: IObservableDiffTreeConfig
+const stop = tree.Subscribe({ roots: ["loading", "$projection_*"] }, post => { /* post.diff, post.seq */ });
+tree.Subscribe({ roots: ["index", "task_*"], form: "snapshot" }, update => { /* update.roots, update.deleted */ });
+
+tree.WritePath("loading", true);
+tree.Commit();              // delivered now, before the work below
+tree.WritePath("results", computeResults());
+tree.RunProjections();      // Commit() doesn't run them
+tree.Commit();
+
+const { index, revision } = await tree.Once(["index", "revision"]); // the first commit holding both
+```
+
+- A subscription first gets the committed state of the roots it names, inside `Subscribe` and in the same shape as every later delivery, so one handler applies them all; nothing is sent when no root matches. Then every commit that touches them follows. Uncommitted writes arrive with the next commit. To subscribe again, clear what the earlier subscription delivered first.
+- `roots` takes exact keys and patterns ending in `*`; omitted, every root. With a `keyFunc`, name the entity roots too (`task_*`): editing an entity commits only the entity's root, not the roots that refer to it.
+- `"diff"` (the default) delivers diff records, which a store applies. `"snapshot"` delivers each changed root whole, the tree's committed value itself: read-only.
+- Delivery is synchronous. A subscriber may write to another tree, but writing to or committing the tree delivering to it throws. A subscriber's error doesn't stop the others; `Commit()` throws it after.
+- `SubscriberCount(key)` counts the subscriptions naming a key exactly, and `OnReleased(pattern, callback)` reports when a key loses its last one. Deleting the key is the caller's (`DeleteRoot` and `Commit`, from a timer: the callback can run inside a delivery).
 
-### PushStore and DiffTreeWriter
+### A worker's own commits
 
-`StoreAsync` only changes when the main thread writes. When a worker produces the data itself, the worker owns the tree instead: it writes into a `DiffTreeWriter` and calls `Commit()`, which runs projections and posts every change since the last commit as one message. A `PushStore` on the main thread applies each message as it arrives (8.1.0).
+A worker that produces data itself (a computation's result, data it fetched) writes to its hosted tree and commits. The commit reaches every subscriber, the main thread's `StoreAsync` included, with no round trip. A store that never writes is a read-only view of the tree.
 
 ```typescript
 // engine-worker.ts (bundled as its own worker entry)
-import { DiffTreeWriter } from "j-templates/Store/Diff/diffTreeWriter";
-const tree = new DiffTreeWriter(self, (v: any) => v?.id, projections);
-self.onmessage = async (e) => {
-  const results = await compute(e.data);   // the worker's own work
-  tree.DiffPath("results", results);
-  tree.DiffPath("meta", { finishedAt: Date.now() });
-  tree.Commit();                          // one message: both writes and the projections
-};
+const tree = new ObservableDiffTree({ keyFunc: (v: any) => v?.id, routes });
+HostPublisher(tree, self as any);
+self.addEventListener("message", async (e) => {
+  if (e.data?.type !== "run") return;      // the app's own message, beside the jt- ones
+  tree.WritePath("status", "running");
+  tree.Commit();                           // posted now; projections not rerun
+  tree.WritePath("results", await compute(e.data));
+  tree.WritePath("status", "done");
+  tree.RunProjections();
+  tree.Commit();
+});
 
 // main thread
-const worker = new Worker(new URL("./engine-worker.ts", import.meta.url), { type: "module" });
-const store = new PushStore(worker, (v: any) => v?.id);   // before the first Commit()
-store.Get("results");   // reactive; undefined until the first commit
-store.Destroy();        // stops listening; terminate the worker yourself
+const store = new StoreAsync(worker, { keyFunc: (v: any) => v?.id });   // created whenever: it starts from the committed state
+store.Get("results");   // reactive; undefined until a commit holds it
 ```
 
-- The writer is a `DiffTree`: write with `DiffPath`, `PatchPath`, `PushPath` and `SplicePath`. Nothing reaches the store until `Commit()`, and a `Commit()` with no changes posts nothing (verified).
-- Projections run once per `Commit()`, after the batch's writes, and their results arrive in the same message, so readers never see a projection out of step with the writes it came from (verified). Calling `RunProjections()` on a writer throws (from source).
-- Use the same `keyFunc` on both sides. Keyed entities resolve through their own roots, as in any store (verified).
-- `source` is any `EventTarget` that delivers the writer's messages as `"message"` events: a `Worker`, a `MessagePort` (started for you), or a plain `EventTarget` on the same thread. The store ignores messages whose `type` isn't `DIFF_TREE_EVENT` or `DIFF_TREE_ERROR` (verified). It listens with `addEventListener` and never sets `onmessage` (from source). The worker can carry its own requests and replies on the same channel.
-- **Create the store before the first `Commit()`.** Messages are diffs against the writer's tree, so a store created later misses the earlier changes and holds partial roots (from source). There is no catch-up message.
-- **A failed change doesn't stop either side.** After a write throws, every later write before `Commit()` throws the same error. `Commit()` still sends the writes made before the failure, skips projections, then posts `DIFF_TREE_ERROR`. The store applies the changes and sets `Error` (verified). The next commit brings projections up to date.
-- `store.Error` is reactive: the last commit's error, or `null`. It's cleared when a later commit's changes arrive (verified).
-- The store deep-clones every value it applies, so even a same-thread `EventTarget` that delivers the writer's own objects never leaves the store sharing them with the writer's tree (from source).
+- Nothing reaches subscribers until `Commit()`, and a commit with no changes posts nothing. Errors in the worker's own writes throw to the worker's code; nothing is posted for them.
+- `HostPublisher(tree, self)` serves the worker's own channel; `host.Serve(port)` serves a `MessagePort` it's given, so another worker can subscribe.
+- Another worker subscribes over a port with `Subscribe(port, { roots, form: "snapshot" }, update => …)` and writes the roots it receives under a route of its own tree, which is never posted on. `Once(port, keys, { signal })` waits for the first commit that holds every key. Values arrive as structured-cloned copies.
+
+### DiffTreeHub: trees by endpoint
+
+On the main thread, a `DiffTreeHub` owns the app's trees. One key is one tree in the app's dependency graph, running in a worker or on the main thread. The hub creates each tree from a factory when it's first needed, hands out leases on it, connects each tree to the ones it follows, re-creates one on request, and ends each one when its last lease ends. It never carries data.
+
+An **endpoint** describes a key once, as plain data: its name, what it follows and its keyFunc. The main thread registers it, the tree is built from it, and the trees that follow it read their paths from it. It imports nothing that reads `window`, so workers import the same definitions. The tree's own configuration (routes, projections, `opaque`) is one object given to its constructor, in a file only its worker imports; config its stores share with it, `opaque` say, goes in a file both import.
+
+```typescript
+// endpoints.ts: imported by the main thread and the workers
+import { DiffTreeEndpoint } from "j-templates/Store/Diff/diffTreeEndpoint";
+export const engineEndpoint = DiffTreeEndpoint.Define("engine", undefined, { keyFunc });
+export const engineConfig = { opaque: ["view"] };   // shared by the engine's tree and its stores
+export const traceEndpoint = DiffTreeEndpoint.Define("trace", remote => ({
+  engine: remote(engineEndpoint, ["index", "task_*"]),   // { index: "/engine/index", "task_*": "/engine/task_*" }
+}));
+export const filterEndpoint = DiffTreeEndpoint.Define("filter", remote => ({
+  trace: remote(traceEndpoint, ["$projection_count"]),
+}));
+
+// trace-tree.ts: builds the tree; the endpoint gives its keyFunc and a follow route per source
+export const newTraceTree = () => new ObservableDiffTree({
+  endpoint: traceEndpoint,
+  routes: { "/": { projections: { count: { reads: [traceEndpoint.config.engine.index], projection: countOf } } } },
+});
+
+// trace-worker.ts: serves the tree and follows its sources into it
+DiffTreeEndpoint.Host(traceEndpoint, newTraceTree(), self as any);
+
+// main thread
+import { DiffTreeHub } from "j-templates/Store/Diff/diffTreeHub";
+const hub = new DiffTreeHub();
+hub.Register(engineEndpoint, () => {
+  const worker = new Worker(new URL("./engine-worker.ts", import.meta.url), { type: "module" });
+  worker.postMessage({ type: "load", project });   // starting intent: runs on every start
+  return worker;
+});
+hub.Register(traceEndpoint, () => new Worker(new URL("./trace-worker.ts", import.meta.url), { type: "module" }), {
+  releaseDebounce: 5000,
+});
+hub.Register(filterEndpoint, newFilterTree);       // returns the tree: it runs on this thread
+
+const engine = new StoreAsync(hub.Open("engine"), engineConfig);  // a worker's tree, over a port; held for the app's lifetime
+const trace = new StoreAsync(hub.Open("trace"));    // starts trace; its lease on its source keeps engine open
+const filter = new StoreSync(hub.OpenLocal("filter"));  // a tree on this thread, directly
+// teardown: each store releases its lease
+trace.Destroy();                                    // trace ends 5 s later unless reopened
+hub.Restart("engine");                              // a new engine; every store on it starts over with it
+hub.Destroy();                                      // every tree ended
+```
+
+- `Register(endpoint, factory)` creates nothing; the first lease does. The endpoint's sources come from its definition, and each must be registered before it. While a tree runs, the hub holds a lease on each source and gives the tree a port to it, again whenever either restarts.
+- The factory returns a worker, or an `ObservableDiffTree` to run on this thread, which the hub hosts with the same `DiffTreeEndpoint.Host` on a channel of its own. The first start fixes the key's kind. A factory that returns neither, or the other kind on a restart, throws.
+- `Open` returns an `IWorkerLease`, for `StoreAsync`; `OpenLocal` returns an `ILocalLease`, for `StoreSync`. A store given the other kind's lease doesn't compile, and opening a key as the other kind throws. Any number of stores may be opened on one tree. A store owns its lease, takes its keyFunc from the endpoint, and releases the lease on `Destroy()`.
+- A `StoreSync` on a hub's tree shares it: a change from any store on it, and from the trees it follows, reaches every one of them before it returns.
+- `DiffTreeEndpoint.Host(endpoint, tree, scope, { onFollow })` throws for a tree built from another endpoint, or from none when `endpoint` follows sources: build it with `new ObservableDiffTree({ endpoint })`. It applies each source's post at `/<source>/` and then, by default, runs the projections and commits. An `onFollow(tree, source)` replaces that, for a tree that acts at the end of the turn. An `onConnect(tree, source, port)` runs with each new port to a source, for a tree that also reads from the source outside the follow (a one-off `Once`); it may return a cleanup, which runs before the next port's call.
+- **The tree is the source of truth.** `Restart` is the app choosing to start a tree over; the hub doesn't restart on `error`. Every store on the tree starts over with the new one, as when it first subscribed: its state is applied in place, so readers keep their objects, and the roots it lacks are deleted. Nothing a store wrote is written back, and changes the old tree hadn't acknowledged reject. State that must outlive a restart goes in a tree of its own, which the restarted tree follows.
+- A tree is released when its last lease ends: at once, or after `releaseDebounce` ms, unless a lease is opened meanwhile. Releasing ends it and its leases on its sources. Keep a store open on a tree that must outlive every view.
+- The hub tells each tree its sources first, on every start. `OnConnect` for a source the endpoint doesn't follow throws: at once if the list has arrived, otherwise when it does, as the worker's uncaught error (the `Worker`'s `error` event on the main thread). The factory runs again on `Restart` and on the next lease after a release, so it should send whatever the worker needs to start.
+- `Unregister(name)` ends one tree, and throws while another registered endpoint follows it; `Destroy()` ends all of them, the last registered first. `KindOf(name)` says where a key's tree runs, once it has started.
+- Keep a worker's factory a literal `new Worker(new URL(...), { type: "module" })` at registration: bundlers compile only that form into a worker bundle.
+- A tree that wires its connections by hand serves itself with `HostPublisher` and follows with `OnConnect(source, port => …)` and a `ChannelSubscription`; `DiffTreeEndpoint.Host` does this for every source.
 
 ## ObservableScope and ObservableNode
 
@@ -691,7 +782,7 @@ A service deriving from a store:
 
 ```typescript
 class TodoService implements IDestroyable {
-  private store = new StoreSync((v: any) => v?.id);
+  private store = new StoreSync(undefined, { keyFunc: (v: any) => v?.id });
   private active = ObservableScope.Create(() =>
     this.store.Get<Todo[]>("todos", []).filter((t) => !t.done));
   get Active() { return ObservableScope.Value(this.active); }
@@ -712,6 +803,7 @@ ObservableNode.CreateFactory(alias?)  // proxy factory with aliasing (used by st
 
 - `Snapshot` returns the same object on repeated calls until a write. After a write, unchanged nested parts are shared (`===`) with the previous snapshot. Snapshots are **not frozen**; treat them as read-only.
 - `JSON.stringify(node)` and `node.toJSON()` use the cached snapshot.
+- **`Opaque`** (`j-templates/Store`) holds a value whole inside a node. Assign one (`node.view = new Opaque(view)`), push or splice it into a node's array, or return it inside a `@Computed` result. The node stores the box and every read opens it, so readers get the raw value, never proxied, and re-run only when the box is replaced. Array callbacks, `pop`, `shift`, `splice`'s removed items and a `sort` comparator get raw values too. Spread, `Object.assign`, property descriptors, snapshots and `JSON.stringify` give the raw value too, so an object composed from reads holds no box. `Unwrap` gives the node's storage, boxes included (`Create(Unwrap(node))` is `node` itself), and `Clone` keeps a box it's given: fine to write back into a node, not to a store.
 - `ApplyDiff`, `ApplySplice` and `Touch` also exist; they are internal to the stores. `ApplyDiff` and `ApplySplice` deep-clone what they write, so the node never shares objects with the caller.
 
 **Snapshot reads do not subscribe.** `JSON.stringify(node)`, `node.toJSON()` and `ObservableNode.Snapshot(node)` register no dependencies, so a scope that reads only through them never updates (verified). Read properties directly, or use `ObservableNode.Clone(node)`, which tracks every nested field and leaves the source untouched:
@@ -751,38 +843,26 @@ Verification used tsx with jsdom; Vitest with jsdom should behave the same. Requ
 
 1. Create `window`, `document` and the DOM classes as globals **before** importing j-templates.
 2. Set `SYNC_SCHEDULING=true` for synchronous assertions, or await a timeout (100–150 ms was reliable in testing) after each action.
-3. For `@ComputedAsync` or `StoreAsync`, stub `Worker` with an in-process shim:
+3. For `StoreAsync`, stub `Worker` with an in-process shim: two `EventTarget`s that deliver structured-cloned copies a tick later, with a `HostPublisher` on one side. Await a timeout before reading a commit the worker made on its own:
 
 ```typescript
-import { DiffTree } from "j-templates/Store/Diff/diffTree";
-import { ConnectWorkerToDiffTree } from "j-templates/Store/Diff/diffTreeWorker";
-
-function fakeWorker(tree = new DiffTree()) {
-  const inner: any = { onmessage: null,
-    postMessage: (d: any) => queueMicrotask(() => outer.onmessage?.({ data: structuredClone(d) })) };
-  const outer: any = { onmessage: null, onerror: null, terminate() {},
-    postMessage: (d: any) => queueMicrotask(() => inner.onmessage?.({ data: structuredClone(d) })) };
-  ConnectWorkerToDiffTree(tree, inner);
-  return outer;
+import { ObservableDiffTree } from "j-templates/Store/Diff/observableDiffTree";
+import { HostPublisher } from "j-templates/Store/Diff/hostPublisher";
+
+function fakeWorker(tree = new ObservableDiffTree()) {
+  const main: any = new EventTarget(), inner: any = new EventTarget();
+  const send = (to: EventTarget) => (d: unknown) =>
+    setTimeout(() => to.dispatchEvent(new MessageEvent("message", { data: structuredClone(d) })));
+  main.postMessage = send(inner); inner.postMessage = send(main); main.terminate = () => {};
+  HostPublisher(tree, inner);
+  return main;
 }
-(globalThis as any).Worker = class { constructor() { return fakeWorker(); } }; // for @ComputedAsync
-const store = new StoreAsync(fakeWorker(new DiffTree((v: any) => v?.id)), (v: any) => v?.id);
-```
-
-4. For `PushStore`, use a plain `EventTarget` as the channel. Deliver copies a tick later, as a worker would, and await a timeout before reading:
-
-```typescript
-import { DiffTreeWriter } from "j-templates/Store/Diff/diffTreeWriter";
-
-const target = new EventTarget();
-const port = { postMessage: (d: unknown) => setTimeout(() =>
-  target.dispatchEvent(new MessageEvent("message", { data: structuredClone(d) }))) };
-const writer = new DiffTreeWriter(port);
-const store = new PushStore(target);
+const tree = new ObservableDiffTree({ keyFunc: (v: any) => v?.id });
+const store = new StoreAsync(fakeWorker(tree), { keyFunc: (v: any) => v?.id });
 
-writer.DiffPath("a", { value: 1 });
-writer.Commit();
-await new Promise((r) => setTimeout(r));
+tree.WritePath("a", { value: 1 });
+tree.Commit();
+await new Promise((r) => setTimeout(r, 10));
 store.Get<any>("a").value;   // 1
 ```
 
@@ -968,13 +1048,15 @@ Component.Attach(document.getElementById("app")!, app({}));
 18. **Native DOM listeners belong on elements you render**, not the host.
 19. **`svg()` is HTML-namespace.** Use namespaced components or `innerHTML` for SVG.
 20. **`ObservableScope.Create` with no reactive reads is static** and ignores `Update()`. Use `Basic`.
-21. **`StoreAsync` writes must be awaited** before reading; data crosses by structured clone (class methods are lost). Changes in one tick are batched, and one failed change makes every later change reject.
+21. **`StoreAsync` writes must be awaited** before reading; data crosses by structured clone (class methods are lost). Changes in one tick are batched, and a failed change rejects every change in its batch, and only those.
 22. **The package needs a bundler or TypeScript runner**; plain Node cannot import it.
 
 23) **Equal-value writes still notify.** Assigning the current value again re-runs every reader. Guard repeated writes or read through `gate()`.
 24) **`JSON.stringify(node)` and `ObservableNode.Snapshot(node)` don't subscribe.** Read properties directly, or `ObservableNode.Clone(node)` to track everything.
 25) **Don't update a scope from its own emit.** Calling `ObservableScope.Update(s)` from a `Watch(s, …)` callback, or any write that re-emits the emitter currently notifying, throws `Emitter.Emit: re-entry during emit is not supported` (verified). Defer the write (`queueMicrotask`) or restructure.
-26) **A `PushStore` sees only what's committed after it exists.** Create it before the writer's first `Commit()`, and call `Commit()` after every batch of writes.
+26) **A worker's own writes reach no one until `Commit()`, and `Commit()` doesn't run projections.** Call `RunProjections()` before it when the change should update them.
+27) **An opaque value read and written elsewhere is plain data again.** A read opens the box, so writing the value into another node or returning it from `@Computed` proxies it there, and a `@Computed` result merges into it in place. Build from it, or box it again (`new Opaque(value)`). Never mutate it.
+28) **Don't write to an `ObservableDiffTree` (or its `StoreSync`) from its own delivery.** A subscriber that writes to, commits or runs projections on the tree delivering to it throws `ObservableDiffTree: a subscriber can't write to or commit the tree delivering to it.` Write to another tree, or defer the write.
 
 ## Debugging
 
@@ -1003,13 +1085,11 @@ Component.Attach(document.getElementById("app")!, app({}));
 | `Emitter.Emit: re-entry during emit is not supported` | a `Watch`/`OnUpdated` callback updates the scope or value that is notifying it | defer the write, or move it out of the callback |
 | `scope() must be called within a watch context` inside `peek()` | tracking is off inside `peek` | call `scope()`/`gate()` outside the `peek` callback |
 | `Key not found in store` from `StoreAsync.Patch` right after a `Write` | the key is an entity id flattened out of a write that hasn't been applied yet | await the `Write` first |
-| Every `StoreAsync` change rejects with the same old error | an earlier change failed in the worker | fix that change; replace the store |
+| Every `StoreAsync` change in one batch rejects | one change in the batch failed in the worker, or a projection threw | fix that change; later batches apply as usual |
 | A test's projection never updates | the test drives a `DiffTree` directly | call `tree.RunProjections()` after each write |
-| `PushStore` never gets the writer's data | the worker wrote but didn't call `Commit()` | call `Commit()` after each batch |
-| `PushStore` holds partial or missing roots that the writer has | the store was created after the writer's first `Commit()` | create the store with the worker, before any commit |
-| Every `DiffTreeWriter` write throws the same old error | an earlier write in the batch failed | call `Commit()`: it sends the applied writes and the error, and the next batch starts clean |
-| `RunProjections` throws on a `DiffTreeWriter` | projections run in `Commit()` | call `Commit()` instead |
-| `PROJECTION_PREFIX` is `undefined`, projection keys read `"undefined<id>"` | imported from `j-templates/Store/Diff/diffTree`, its path before 8.1.0 | import it from `j-templates/Store/Diff` |
+| `StoreAsync` never gets the worker's own data | the worker wrote but didn't call `Commit()` | call `Commit()` after the work |
+| A worker commit arrives but projections are stale | `Commit()` doesn't run projections | call `RunProjections()` before `Commit()` |
+| `StoreAsync.Destroy()` leaves the worker running | by design: the creator terminates it | call `worker.terminate()` |
 
 ## Corrections from the v5 primer
 

package/Store/Diff/channelClient.d.ts

@@ -0,0 +1,106 @@
+import { IChannel, IDiffMethodBatch, IDiffPost, ISnapshotUpdate, ISubscribeOptions } from "./diffTree.types";
+/**
+ * The client side of a `HostPublisher` channel: it sends batches and subscriptions, and routes
+ * the host's posts and acks back by id. Messages for ids it didn't send are left alone, so
+ * other clients and the app's own messages share the channel.
+ */
+export declare class ChannelClient {
+    private channel;
+    private subscriptions;
+    private batches;
+    private listener;
+    constructor(channel: IChannel);
+    /**
+     * Sends a batch of calls.
+     * @returns A promise that resolves on the batch's `jt-ack`, after the commit's posts have been
+     *   delivered, or rejects with the batch's error.
+     */
+    Batch(calls: IDiffMethodBatch): Promise<void>;
+    /** Rejects the batches waiting for an ack with `error`; this client stops waiting for them */
+    RejectBatches(error: unknown): void;
+    /** See `DiffTree.MarkOpaque` */
+    MarkOpaque(keys: readonly string[]): void;
+    /**
+     * Subscribes to the host's tree. Deliveries arrive as the host posts them.
+     * @param onSubscribed Called once the host has posted the first state, with its error when
+     *   subscribing failed.
+     * @returns The subscription's id.
+     */
+    Subscribe(options: ISubscribeOptions, callback: (delivery: any) => void, onSubscribed?: (error?: unknown) => void): number;
+    Unsubscribe(sub: number): void;
+    /**
+     * Ends this client's subscriptions and stops listening. Batches waiting for an ack are left
+     * unsettled. The channel stays open.
+     */
+    Destroy(): void;
+    private Receive;
+}
+/**
+ * A subscription to a tree served on a channel that outlives the channel: when the tree is
+ * replaced (a restarted worker, given on a new port), `Connect` subscribes to the new one, and its
+ * first state also deletes the roots this subscription delivered that the new tree doesn't hold. A
+ * subscriber that applies every delivery, a store or a tree, then holds the new tree's state, and
+ * a wildcard read of it reads nothing the old tree left behind.
+ *
+ * - The first state after a reconnect is one delivery: the new tree's roots, then a `delete` record
+ *   (in the `"diff"` form) or a `deleted` key (in the `"snapshot"` form) for each root gone, so
+ *   nothing applied in between holds both. With no roots in the new tree, it's the deletes alone.
+ * - A root is delivered while it was written by the last delivery that touched it, and gone once a
+ *   delivery deletes it, as a `HostPublisher`'s deliveries say.
+ *
+ * @example
+ * const engine = new ChannelSubscription({ roots: ["run", "$projection_*"] }, (post, first) => {
+ *   tree.ApplyDiff(post.diff, "/engine/");
+ *   tree.RunProjections();
+ *   tree.Commit();
+ * });
+ * OnConnect("engine", port => engine.Connect(port));
+ */
+export declare class ChannelSubscription {
+    private options;
+    private callback;
+    /** The source's root keys delivered and not deleted */
+    private delivered;
+    private client?;
+    private ownClient;
+    private sub?;
+    /**
+     * @param options The roots, and the form, as `ObservableDiffTree.Subscribe` takes them.
+     * @param callback Each delivery, and whether it's the first state of a `Connect`.
+     */
+    constructor(options: ISubscribeOptions, callback: (delivery: any, first: boolean) => void);
+    /**
+     * Subscribes over a channel, or a client of one, in place of the last: the first state arrives
+     * as one delivery, with the deletes for the roots the last tree had and this one hasn't.
+     * @param onSubscribed Called once the first state is out, with the error when subscribing failed.
+     * @returns What ends this connection's subscription.
+     */
+    Connect(channel: IChannel | ChannelClient, onSubscribed?: (error?: unknown) => void): () => void;
+    /** Ends the subscription on the current channel; what it delivered is kept for the next `Connect` */
+    Stop(): void;
+    private Track;
+}
+/**
+ * Subscribes to the tree a `HostPublisher` serves on a channel, such as a port to another worker.
+ * The deliveries are the same as `ObservableDiffTree.Subscribe`'s, but they arrive asynchronously:
+ * the first state as the host's first post, then each commit. Values are structured-cloned copies.
+ * @returns A function that ends the subscription.
+ */
+export declare function Subscribe(channel: IChannel, options: ISubscribeOptions & {
+    form: "snapshot";
+}, callback: (update: ISnapshotUpdate) => void): () => void;
+export declare function Subscribe(channel: IChannel, options: ISubscribeOptions & {
+    form?: "diff";
+}, callback: (post: IDiffPost) => void): () => void;
+/**
+ * Waits on a channel for the first delivery in which every key has a value: at once when they
+ * all have one, otherwise the commit that adds the last. See `ObservableDiffTree.Once`.
+ * @param keys Exact root keys; no patterns.
+ * @param options `signal` cancels the wait, rejecting with its reason.
+ * @returns Each key's value.
+ */
+export declare function Once(channel: IChannel, keys: readonly string[], options?: {
+    signal?: AbortSignal;
+}): Promise<{
+    [key: string]: unknown;
+}>;