j-templates 8.0.27 → 8.1.0

package/SYNTAX_PRIMER.md

@@ -1,14 +1,14 @@
 # j-templates Syntax Primer
 
-Oct 3, 2026 · @Jay Landrum
+Oct 17, 2026 · @Jay Landrum
 
-Reference for building apps with j-templates 8.0.21. Every behavioral claim was checked by running the library in jsdom; claims taken from type declarations or source alone are marked as such.
+Reference for building apps with j-templates 8.1.0. Every behavioral claim was checked by running the library in jsdom; claims taken from type declarations or source alone are marked as such.
 
 ## How to use this document
 
 Read Mental model, then Templates and State decorators before writing a component. Check the Traps checklist before shipping.
 
-- **Version:** j-templates 8.0.21. 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; those sections were re-verified against 8.0.21 in jsdom.
+- **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.
 - **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.
 
@@ -56,9 +56,10 @@ 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` | `Store`, `StoreSync`, `StoreAsync`, `ObservableScope`, `ObservableNode` |
+| `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. |
 
-**Deep imports used below:** `j-templates/Store/Diff/diffTree` (`DiffTree`, `PROJECTION_PREFIX`), `j-templates/Store/Diff/diffTreeWorker` (`ConnectWorkerToDiffTree`), `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/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`).
 
 **Element functions** (all verified present):
 
@@ -102,20 +103,27 @@ Component.Attach(document.getElementById("app")!, counter({}));
 **Members:**
 
 - `Template(): vNode | vNode[]` — override to render. May return an array. Not overriding renders an empty host.
-- `Bound()` / `Destroy()` — optional overrides. If you override either, call `super.Bound()` / `super.Destroy()`. `super.Bound()` starts `@Watch`; `super.Destroy()` tears down scopes and runs `@Destroy` properties.
+- `Bound()` / `Connected()` / `Destroy()` — optional overrides. If you override `Bound()` or `Destroy()`, call `super.Bound()` / `super.Destroy()`. `super.Bound()` starts `@Watch`; `super.Destroy()` tears down scopes and runs `@Destroy` properties. The base `Connected()` is empty.
 - `Fire(event, payload?)` — sends a component event to the parent's `on:` handler. The payload is optional.
-- `this.Data`, `this.Templates`, `this.Injector`, `this.VNode` (host vNode; `this.VNode.node` is the host element), `this.Destroyed`.
+- `this.Data`, `this.Templates`, `this.Injector`, `this.VNode` (host vNode; `this.VNode.node` is the host element), `this.IsConnected`, `this.Destroyed`.
 - Never override the constructor. Use field initializers and `Bound()`.
 
-**Lifecycle (verified order):**
+**Lifecycle (verified order, 8.0.23+):**
 
 1. Field initializers run.
-2. `Bound()` runs. The host element exists but is **not in the document and has no children**. `@Watch` handlers fire here with their initial values.
-3. `Template()` runs.
-4. Children functions run and build the DOM. By default this happens **after** `Attach` returns; with `SYNC_SCHEDULING=true`, before.
-5. The host is in the document.
+2. `Template()` runs and its children functions build the DOM. Child components go through their own steps 1–3 here, so a child's `Bound()` runs before its parent's.
+3. `Bound()` runs once the initial subtree is in the host: `querySelector` on the host finds rendered elements, including a child component's content. `@Watch` handlers fire inside `super.Bound()` with their initial values, so they can use those elements too. Code placed before `super.Bound()` runs before the first `@Watch` call.
+4. `Connected()` runs once the host is first in the document, after `Bound()`. It runs parent first, then children. It fires once per component instance; a component that is removed and rendered again is a new instance and fires again.
 
-To touch rendered DOM from `Bound()`, defer with `requestAnimationFrame` or `setTimeout` (verified: host connected and children present by then). Attach native listeners to an element you render, not to the host.
+By default steps 2–4 happen **after** `Attach` returns; with `SYNC_SCHEDULING=true`, before.
+
+The host is in the document during `Bound()` only for the component passed to `Component.Attach(document.body, …)`. A child's host joins the document when its parent's children are placed, after the child's `Bound()`. So:
+
+- Find and wire up the elements you render in `Bound()`.
+- Put work that needs layout (measuring, sizes), focus, or the document in `Connected()`.
+- An element that a later change renders isn't there at `Bound()` or `Connected()`. Reach it from the code that renders it, or watch for it.
+
+`Connected()` only fires when j-templates itself puts a node in the document. A tree attached to a detached element never gets `Connected()`, even after you append that element to the document (verified). Attach native listeners to an element you render, not to the host.
 
 **Host element.** The name passed to `ToFunction` is the host's tag. `Template()` output renders inside it:
 
@@ -352,7 +360,7 @@ Tracked array methods: `push`, `pop`, `shift`, `unshift`, `splice`, `sort`, `rev
 syncFilter(value: FilterType) { this.localFilter = value; }
 ```
 
-- Fires once in `super.Bound()` with the initial value, then on every change.
+- Fires once in `super.Bound()` with the initial value, then on every change. Since `Bound()` runs after the first render, that first call can use rendered elements.
 - Several synchronous writes in one tick produce one call with the latest value (`n = 1; n = 2; n = 3` → one call with `3`).
 - Without `super.Bound()` it never fires.
 - Use it for side effects and for copying parent `Data` into local `@Value` state. Don't use it to drive rendering; reads in templates are already reactive.
@@ -525,15 +533,15 @@ 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.
+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.
 
-|  | `StoreSync` | `StoreAsync` |
-| --- | --- | --- |
-| Constructor | `new StoreSync(keyFunc?, projections?)` | `new StoreAsync(worker, keyFunc?)` |
-| Diffing | main thread, synchronous | in the `Worker` you supply |
-| Writes | `void`; readable immediately | `Promise`; readable only after `await` |
-| `Destroy()` | none | required; terminates the worker |
-| Backs | nothing (`@Computed` uses `ObservableNode` directly) | `@ComputedAsync` |
+|  | `StoreSync` | `StoreAsync` | `PushStore` |
+| --- | --- | --- | --- |
+| Constructor | `new StoreSync(keyFunc?, projections?)` | `new StoreAsync(worker, keyFunc?)` | `new PushStore(source, keyFunc?, cloneData?)` |
+| 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 |
 
 ### API
 
@@ -547,7 +555,7 @@ 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.
+`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).
 
 ### keyFunc and flattening
 
@@ -585,12 +593,19 @@ store.Destroy();      // when done
 
 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.
+
+- 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.
+
 ### 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`).
 
 ```typescript
-import { PROJECTION_PREFIX } from "j-templates/Store/Diff/diffTree"; // "$projection_"
+import { PROJECTION_PREFIX } from "j-templates/Store/Diff"; // "$projection_"
 
 const store = new StoreSync((v: any) => v?.id, {
   activeCount: { reads: ["todos"], projection: (keys, todos) => todos.filter((t) => !t.done).length },
@@ -605,6 +620,39 @@ store.Get<number>(`${PROJECTION_PREFIX}activeCount`);
 - The last read may be a root wildcard such as `"task_*"`: each matching root's key is added to `keys` and its value appended (verified: `[["task_1","task_2"], v1, v2]`).
 - 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).
+
+### PushStore and DiffTreeWriter
+
+`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).
+
+```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
+};
+
+// 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
+```
+
+- 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).
+- `cloneData` (default `false`): a `Worker` or `MessagePort` already delivers a structured-clone copy, so no copy is made. A same-thread `EventTarget` delivers the writer's own objects; post copies, or pass `true`. The flag only covers new roots and splices; changes to an existing root are always copied (from source).
 
 ## ObservableScope and ObservableNode
 
@@ -722,6 +770,23 @@ function fakeWorker(tree = new DiffTree()) {
 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);
+
+writer.DiffPath("a", { value: 1 });
+writer.Commit();
+await new Promise((r) => setTimeout(r));
+store.Get<any>("a").value;   // 1
+```
+
 jsdom has no `innerText`; use `textContent` in tests.
 
 ## Worked example: Smart Tasks
@@ -895,7 +960,7 @@ Component.Attach(document.getElementById("app")!, app({}));
 9. **`@State` deep-tracks plain objects and arrays only**, not class instances, `Map` or `Set`.
 10. **`@Scope` has no equality check**; consumers re-run on every change of its inputs. `gate()` it if it returns a primitive.
 11. **`@Computed` returns a copy**, not the object the getter returned. Its identity changes only when the result's type changes or an object result loses a key.
-12. **`Bound()` runs before `Template()`**, with the host detached and empty. Defer DOM access with `requestAnimationFrame`. Forgetting `super.Bound()` silences `@Watch`.
+12. **`Bound()` runs after the first render**, but a child's host isn't in the document yet. Do layout and focus work in `Connected()`. Forgetting `super.Bound()` silences `@Watch`.
 13. **`@Watch` fires immediately** with the initial value, and coalesces synchronous changes into one call.
 14. **`scope()`, `gate()` and `mapped()` outside a scope throw**, including in `on:` handlers and inside `peek()` callbacks. `peek()` works anywhere.
 15. **Conditional `scope()`/`gate()` calls need ids**, or a later call takes a skipped call's scope. Callbacks are fixed at first run: don't close over locals.
@@ -904,12 +969,13 @@ 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**; data crosses by structured clone (class methods are lost).
+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.
 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.
 
 ## Debugging
 
@@ -927,7 +993,9 @@ Component.Attach(document.getElementById("app")!, app({}));
 | `gate()` doesn't stop re-runs | gated value is a new object/array each time | gate a primitive, or use `@Computed` |
 | Async value never resolves (shows a Promise) | callback lacks `async` | `async () => …` |
 | Async value doesn't refresh | reactive read after `await` | read before the first `await` |
-| `querySelector` in `Bound()` finds nothing | children not built yet | `requestAnimationFrame(() => …)` |
+| `querySelector` in `Bound()` finds nothing | the element is rendered later by a change, not by the first render | reach it where it's rendered, or watch for it |
+| Measured size is 0, or `focus()` does nothing, in `Bound()` | the host isn't in the document yet | move the work to `Connected()` |
+| `Connected()` never fires | the tree was attached to a detached element and appended later | attach to an element that's already in the document |
 | Manual service scope never updates | `ObservableScope.Create` with no reactive reads | `ObservableScope.Basic` |
 | Test sees old DOM after a write | asynchronous rendering | `SYNC_SCHEDULING=true` or await a timeout |
 | `ReferenceError: self is not defined` | importing `defaultDiffTreeWorker` on the main thread | write your own worker entry file |
@@ -935,19 +1003,27 @@ Component.Attach(document.getElementById("app")!, app({}));
 | A watcher or scope over JSON.stringify/Snapshot never fires | snapshot reads register no dependencies | read properties directly, or JSON.stringify(ObservableNode.Clone(node)) |
 | `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 |
+| 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` |
 
 ## Corrections from the v5 primer
 
 For maintainers comparing against the previous `SYNTAX_PRIMER.md`. Builders can skip this section.
 
-| Previous claim | Observed in 8.0.18 and 8.0.19 |
+| Previous claim | Observed (8.0.18 and 8.0.19 unless a version is named) |
 | --- | --- |
 | `Injector` is not exported from any public entry point | exported from `j-templates/Utils` |
 | `@Computed` returning `this.tasks` won't re-run on item property changes | it re-runs |
 | a second un-ID'd `scope()`/`gate()` call silently resolves to the first | unconditional duplicates are independent; conditional ones mis-pair |
 | exceptions in children functions/getters propagate uncaught | children-function and `Template()` exceptions are caught and logged; `props:`/`attrs:`/`data:` exceptions halt all rendering |
 | children functions can't return `null`/`undefined` | allowed as the sole return value; forbidden inside arrays |
-| `Bound()` runs with the DOM attached, after the template renders | runs before `Template()`, host detached and empty |
+| `Bound()` runs with the DOM attached, after the template renders | before 8.0.23: ran before `Template()`, host detached and empty. Since 8.0.23: runs after the first render; the host is in the document only for the attached root, and `Connected()` marks entry into the document |
 | `gate()` and `@Scope` are incompatible | fine for primitive-returning getters |
 | `data: this.value` (non-function) in the granular-scopes example | throws `data is not a function` |
 | `StoreAsync` data must be JSON-serialisable (no `Date`, `Map`, `Set`) | transport is structured clone: `Date`, `Map`, `Set` survive; class methods and functions do not |

package/Store/Diff/diffSync.d.ts

@@ -1,5 +1,5 @@
 import { JsonDiffResult } from "../../Utils/json";
-import { DiffSpliceResult, DiffTreeProjectionMap, IDiffTree } from "./diffTree";
+import { DiffSpliceResult, DiffTreeProjectionMap, IDiffTree } from "./diffTree.types";
 /**
  * Synchronous diff implementation.
  * Computes diffs immediately without queuing or workers.

package/Store/Diff/diffTree.d.ts

@@ -1,72 +1,5 @@
 import { type JsonDiffResult } from "../../Utils/json";
-/**
- * Interface for diff tree operations.
- */
-export interface IDiffTree {
-    /**
-     * Computes the diff between a new value and the current value at a path.
-     * @param path - Dot-separated path to the value
-     * @param value - The new value to compare
-     * @returns Diff results showing changes
-     */
-    DiffPath(path: string, value: any): JsonDiffResult;
-    PatchPath(path: string, patch: any): JsonDiffResult;
-    SplicePath(path: string, start: number, deleteCount: number | undefined, items: any[]): DiffSpliceResult;
-    PushPath(path: string, items: any[]): JsonDiffResult;
-}
-/**
- * Constructor interface for IDiffTree.
- */
-export interface IDiffTreeConstructor {
-    /**
-     * Creates a new IDiffTree instance.
-     * @param keyFunc - Optional function to extract a key from a value
-     * @param projections - Optional map of derived-value projections, keyed by id
-     */
-    new (keyFunc?: {
-        (val: any): string;
-    }, projections?: DiffTreeProjectionMap): IDiffTree;
-}
-/**
- * A pure function computing a derived value from the current values at `reads`. Called with
- * the resolved read paths (`keys`) first, then each value positionally in the same order as
- * `reads`, so each value parameter can be typed at the call site instead of cast out of a
- * generic read. A trailing wildcard read expands to one key/value pair per matched root key,
- * so `keys` lets the function tell which root each trailing value came from.
- */
-export type DiffTreeProjectionFunc = (keys: string[], ...values: any[]) => any;
-/**
- * A projection's declaration: the dot-separated paths it reads (a plain tree path, an
- * entity's key, or another projection's `$projection_<id>` key for chaining) and the
- * function computing its result from their current values, positionally. Declaring `reads`
- * up front lets the tree topologically sort projections and reject a dependency cycle at
- * construction instead of on first write.
- *
- * The final entry in `reads` may instead be a wildcard root key (e.g. `"user_*"`, no dot
- * nesting) matching every root key with that prefix; each match is read and passed to the
- * projection as its own trailing key/value pair. A wildcard read can't be chained off a
- * projection's `$projection_<id>` key and can't appear anywhere but last.
- */
-export type DiffTreeProjectionDefinition = {
-    reads: string[];
-    projection: DiffTreeProjectionFunc;
-};
-/** A map of projection id to its declaration, keyed by the id used in `$projection_<id>`. */
-export type DiffTreeProjectionMap = {
-    [id: string]: DiffTreeProjectionDefinition;
-};
-/** Reserved key prefix a projection's result is stored under: `$projection_<id>`. */
-export declare const PROJECTION_PREFIX = "$projection_";
-export type DiffSpliceResult<T = unknown> = {
-    /** Array path segments (strings for object keys, numbers for array indices) */
-    path: (string | number)[];
-    /** Required by the splice operation **/
-    start: number;
-    deleteCount: number;
-    items: any[];
-    spliceResult: any[];
-    diffResult: JsonDiffResult;
-};
+import { DiffSpliceResult, DiffTreeProjectionMap } from "./diffTree.types";
 /**
  * Diff tree implementation. Maintains root state and computes diffs for path/value updates.
  * Used directly by `DiffSync`, and is the building block for a `StoreAsync` worker entry
@@ -98,7 +31,7 @@ export declare class DiffTree {
     DiffPath(path: string, value: any): JsonDiffResult;
     PatchPath(path: string, patch: any): JsonDiffResult;
     PushPath(path: string, items: unknown[]): JsonDiffResult;
-    SplicePath(path: string, start: number, deleteCount: number, items: any[]): DiffSpliceResult<unknown>;
+    SplicePath(path: string, start: number, deleteCount: number, items: any[]): DiffSpliceResult;
     /**
      * Retrieves the current value at a path.
      * @param path - Dot-separated path to the value

package/Store/Diff/diffTree.js

@@ -1,7 +1,6 @@
 import { ArraysEqual } from "../../Utils/array";
 import { JsonDeepClone, JsonDiff, JsonMerge, JsonType } from "../../Utils/json";
-/** Reserved key prefix a projection's result is stored under: `$projection_<id>`. */
-export const PROJECTION_PREFIX = "$projection_";
+import { PROJECTION_PREFIX } from "./diffTree.types";
 /**
  * Flattens nested objects/arrays, extracting keyed objects to root.
  * @param root - Root object to store flattened values

package/Store/Diff/diffTree.types.d.ts

@@ -0,0 +1,105 @@
+import type { JsonDiffResult } from "../../Utils/json";
+/**
+ * `type` of the message a `DiffTreeWriter` posts on `Commit()`: the batch's diff results,
+ * which a `PushStore` applies.
+ */
+export declare const DIFF_TREE_EVENT = "DIFF_TREE_EVENT";
+/**
+ * `type` of the message a `DiffTreeWriter` posts on `Commit()` when a change in the batch
+ * failed, after the `DIFF_TREE_EVENT` carrying the changes that were applied.
+ */
+export declare const DIFF_TREE_ERROR = "DIFF_TREE_ERROR";
+/**
+ * Interface for diff tree operations.
+ */
+export interface IDiffTree {
+    /**
+     * Computes the diff between a new value and the current value at a path.
+     * @param path - Dot-separated path to the value
+     * @param value - The new value to compare
+     * @returns Diff results showing changes
+     */
+    DiffPath(path: string, value: any): JsonDiffResult;
+    PatchPath(path: string, patch: any): JsonDiffResult;
+    SplicePath(path: string, start: number, deleteCount: number | undefined, items: any[]): DiffSpliceResult;
+    PushPath(path: string, items: any[]): JsonDiffResult;
+}
+/**
+ * Constructor interface for IDiffTree.
+ */
+export interface IDiffTreeConstructor {
+    /**
+     * Creates a new IDiffTree instance.
+     * @param keyFunc - Optional function to extract a key from a value
+     * @param projections - Optional map of derived-value projections, keyed by id
+     */
+    new (keyFunc?: {
+        (val: any): string;
+    }, projections?: DiffTreeProjectionMap): IDiffTree;
+}
+/**
+ * A pure function computing a derived value from the current values at `reads`. Called with
+ * the resolved read paths (`keys`) first, then each value positionally in the same order as
+ * `reads`, so each value parameter can be typed at the call site instead of cast out of a
+ * generic read. A trailing wildcard read expands to one key/value pair per matched root key,
+ * so `keys` lets the function tell which root each trailing value came from.
+ */
+export type DiffTreeProjectionFunc = (keys: string[], ...values: any[]) => any;
+/**
+ * A projection's declaration: the dot-separated paths it reads (a plain tree path, an
+ * entity's key, or another projection's `$projection_<id>` key for chaining) and the
+ * function computing its result from their current values, positionally. Declaring `reads`
+ * up front lets the tree topologically sort projections and reject a dependency cycle at
+ * construction instead of on first write.
+ *
+ * The final entry in `reads` may instead be a wildcard root key (e.g. `"user_*"`, no dot
+ * nesting) matching every root key with that prefix; each match is read and passed to the
+ * projection as its own trailing key/value pair. A wildcard read can't be chained off a
+ * projection's `$projection_<id>` key and can't appear anywhere but last.
+ */
+export type DiffTreeProjectionDefinition = {
+    reads: string[];
+    projection: DiffTreeProjectionFunc;
+};
+/** A map of projection id to its declaration, keyed by the id used in `$projection_<id>`. */
+export type DiffTreeProjectionMap = {
+    [id: string]: DiffTreeProjectionDefinition;
+};
+/** Reserved key prefix a projection's result is stored under: `$projection_<id>`. */
+export declare const PROJECTION_PREFIX = "$projection_";
+export type DiffSpliceResult<T = unknown> = {
+    /** Array path segments (strings for object keys, numbers for array indices) */
+    path: (string | number)[];
+    /** Required by the splice operation **/
+    start: number;
+    deleteCount: number;
+    items: T[];
+    spliceResult: T[];
+    diffResult: JsonDiffResult;
+};
+export type IDiffMethodBatch = IDiffMethod[];
+export type IDiffMethodBatchResult = ({
+    type: "diff";
+    result: JsonDiffResult;
+} | {
+    type: "splice";
+    result: DiffSpliceResult;
+})[];
+/**
+ * A message a `DiffTreeWriter` posts to its `PushStore`. Both arrive as ordinary
+ * `"message"` events, so the channel can carry other traffic too; listeners tell them apart
+ * by `type`.
+ */
+export type IDiffPushEvent = {
+    type: typeof DIFF_TREE_EVENT;
+    data: IDiffMethodBatchResult;
+} | {
+    type: typeof DIFF_TREE_ERROR;
+    data: any;
+};
+export interface IDiffMethod {
+    /** The method to call */
+    method: "diffpath" | "splicepath" | "pushpath" | "patchpath";
+    /** Arguments for the method call */
+    arguments: Array<any>;
+}

package/Store/Diff/diffTree.types.js

@@ -0,0 +1,12 @@
+/**
+ * `type` of the message a `DiffTreeWriter` posts on `Commit()`: the batch's diff results,
+ * which a `PushStore` applies.
+ */
+export const DIFF_TREE_EVENT = "DIFF_TREE_EVENT";
+/**
+ * `type` of the message a `DiffTreeWriter` posts on `Commit()` when a change in the batch
+ * failed, after the `DIFF_TREE_EVENT` carrying the changes that were applied.
+ */
+export const DIFF_TREE_ERROR = "DIFF_TREE_ERROR";
+/** Reserved key prefix a projection's result is stored under: `$projection_<id>`. */
+export const PROJECTION_PREFIX = "$projection_";

package/Store/Diff/diffTreeWorker.d.ts

@@ -1,17 +1,2 @@
-import { JsonDiffResult } from "../../Utils/json";
-import { DiffSpliceResult, DiffTree } from "./diffTree";
-export type IDiffMethodBatch = IDiffMethod[];
-export type IDiffMethodBatchResult = ({
-    type: "diff";
-    result: JsonDiffResult;
-} | {
-    type: "splice";
-    result: DiffSpliceResult;
-})[];
-export interface IDiffMethod {
-    /** The method to call */
-    method: "diffpath" | "splicepath" | "pushpath" | "patchpath";
-    /** Arguments for the method call */
-    arguments: Array<any>;
-}
+import { DiffTree } from "./diffTree";
 export declare function ConnectWorkerToDiffTree(diffTree: DiffTree, worker: Worker): void;

package/Store/Diff/diffTreeWriter.d.ts

@@ -0,0 +1,103 @@
+import { JsonDiffResult } from "../../Utils/json";
+import { DiffTree } from "./diffTree";
+import { DiffSpliceResult, DiffTreeProjectionMap } from "./diffTree.types";
+/**
+ * A `DiffTree` that pushes its changes to a `PushStore` instead of answering a store's
+ * requests. Use it inside a worker that produces data itself (for example, the result of a
+ * computation it runs): write with the usual `DiffTree` methods, then call `Commit()` to run
+ * projections and post everything since the last commit as one message.
+ *
+ * - Push only: don't pass a `DiffTreeWriter` to `ConnectWorkerToDiffTree`. It would record
+ *   the request/response batches too and send them again on the next `Commit()`.
+ * - After a change fails, every later change before `Commit()` throws that same error. The
+ *   changes made before the failure are already in the tree, so `Commit()` still sends them,
+ *   followed by a `DIFF_TREE_ERROR` message. Projections aren't run for that batch; the next
+ *   `Commit()` brings them up to date.
+ * - A `PushStore` only receives the changes committed after it starts listening, so
+ *   create it before the writer's first `Commit()`.
+ *
+ * @example
+ * // engine-worker.ts
+ * const tree = new DiffTreeWriter(self, undefined, projections);
+ * tree.DiffPath("results", computeResults());
+ * tree.Commit();
+ *
+ * // main thread
+ * const store = new PushStore(worker);
+ *
+ * @see PushStore
+ */
+export declare class DiffTreeWriter extends DiffTree {
+    private worker;
+    private uncommittedError;
+    private uncommitted;
+    /**
+     * Creates a DiffTreeWriter.
+     * @param worker Where `Commit()` posts its messages: the worker's `self`, or a `MessagePort`.
+     *   On the same thread as the store, anything whose `postMessage` dispatches a `"message"`
+     *   event on the store's `EventTarget`; post copies, or construct the store with `cloneData`.
+     * @param keyFunc Optional function to extract a key from objects. Pass the same key logic to
+     *   the `PushStore` that receives the changes.
+     * @param projections Optional map of derived-value projections, keyed by id. They run once
+     *   per `Commit()`, after the batch's changes.
+     */
+    constructor(worker: {
+        postMessage(message: unknown): void;
+    }, keyFunc?: {
+        (val: any): string;
+    }, projections?: DiffTreeProjectionMap);
+    /**
+     * Not available on a DiffTreeWriter: `Commit()` runs projections once per batch, after its
+     * changes. Running them earlier would push a projection result computed from part of a batch.
+     * @throws Always.
+     */
+    RunProjections(): JsonDiffResult;
+    /**
+     * Computes the diff between a new value and the current value at a path, and records it
+     * for the next `Commit()`.
+     * @param path - Dot-separated path to the value
+     * @param value - The new value to compare
+     * @returns Diff results showing changes
+     * @throws The change's error, or an earlier uncommitted change's error.
+     */
+    DiffPath(path: string, value: any): JsonDiffResult;
+    /**
+     * Merges a patch into the current value at a path, and records the diff for the next
+     * `Commit()`.
+     * @param path - Dot-separated path to the value
+     * @param patch - The value to merge into the current value
+     * @returns Diff results showing changes
+     * @throws The change's error, or an earlier uncommitted change's error.
+     */
+    PatchPath(path: string, patch: any): JsonDiffResult;
+    /**
+     * Appends items to the array at a path, and records the diff for the next `Commit()`.
+     * @param path - Dot-separated path to the array
+     * @param items - The items to append
+     * @returns Diff results showing changes
+     * @throws The change's error, or an earlier uncommitted change's error.
+     */
+    PushPath(path: string, items: unknown[]): JsonDiffResult;
+    /**
+     * Splices the array at a path, and records the splice for the next `Commit()`.
+     * @param path - Dot-separated path to the array
+     * @param start - The position at which to start changing the array
+     * @param deleteCount - The number of elements to delete
+     * @param items - The elements to insert
+     * @returns The splice and its diff results
+     * @throws The change's error, or an earlier uncommitted change's error.
+     */
+    SplicePath(path: string, start: number, deleteCount: number, items: any[]): DiffSpliceResult<unknown>;
+    /**
+     * Runs projections and posts every change since the last commit as one `DIFF_TREE_EVENT`
+     * message, which a `PushStore` applies as a unit. Posts nothing when nothing changed.
+     *
+     * If a change in the batch failed, projections are skipped, the applied changes are still
+     * posted, and a `DIFF_TREE_ERROR` message follows with the error; `Commit()` itself doesn't
+     * throw, since the failed change already did. If a projection throws, the batch's changes
+     * and the error are posted the same way, then `Commit()` rethrows. Either way the next batch
+     * starts clean.
+     * @throws A projection's error.
+     */
+    Commit(): void;
+}

package/Store/Diff/diffTreeWriter.js

@@ -0,0 +1,188 @@
+import { DiffTree } from "./diffTree";
+import { DIFF_TREE_ERROR, DIFF_TREE_EVENT } from "./diffTree.types";
+/**
+ * A `DiffTree` that pushes its changes to a `PushStore` instead of answering a store's
+ * requests. Use it inside a worker that produces data itself (for example, the result of a
+ * computation it runs): write with the usual `DiffTree` methods, then call `Commit()` to run
+ * projections and post everything since the last commit as one message.
+ *
+ * - Push only: don't pass a `DiffTreeWriter` to `ConnectWorkerToDiffTree`. It would record
+ *   the request/response batches too and send them again on the next `Commit()`.
+ * - After a change fails, every later change before `Commit()` throws that same error. The
+ *   changes made before the failure are already in the tree, so `Commit()` still sends them,
+ *   followed by a `DIFF_TREE_ERROR` message. Projections aren't run for that batch; the next
+ *   `Commit()` brings them up to date.
+ * - A `PushStore` only receives the changes committed after it starts listening, so
+ *   create it before the writer's first `Commit()`.
+ *
+ * @example
+ * // engine-worker.ts
+ * const tree = new DiffTreeWriter(self, undefined, projections);
+ * tree.DiffPath("results", computeResults());
+ * tree.Commit();
+ *
+ * // main thread
+ * const store = new PushStore(worker);
+ *
+ * @see PushStore
+ */
+export class DiffTreeWriter extends DiffTree {
+    /**
+     * Creates a DiffTreeWriter.
+     * @param worker Where `Commit()` posts its messages: the worker's `self`, or a `MessagePort`.
+     *   On the same thread as the store, anything whose `postMessage` dispatches a `"message"`
+     *   event on the store's `EventTarget`; post copies, or construct the store with `cloneData`.
+     * @param keyFunc Optional function to extract a key from objects. Pass the same key logic to
+     *   the `PushStore` that receives the changes.
+     * @param projections Optional map of derived-value projections, keyed by id. They run once
+     *   per `Commit()`, after the batch's changes.
+     */
+    constructor(worker, keyFunc, projections) {
+        super(keyFunc, projections);
+        this.worker = worker;
+        this.uncommittedError = null;
+        this.uncommitted = [];
+    }
+    /**
+     * Not available on a DiffTreeWriter: `Commit()` runs projections once per batch, after its
+     * changes. Running them earlier would push a projection result computed from part of a batch.
+     * @throws Always.
+     */
+    RunProjections() {
+        throw new Error("RunProjections is called during Commit()");
+    }
+    /**
+     * Computes the diff between a new value and the current value at a path, and records it
+     * for the next `Commit()`.
+     * @param path - Dot-separated path to the value
+     * @param value - The new value to compare
+     * @returns Diff results showing changes
+     * @throws The change's error, or an earlier uncommitted change's error.
+     */
+    DiffPath(path, value) {
+        if (this.uncommittedError)
+            throw this.uncommittedError;
+        try {
+            const result = super.DiffPath(path, value);
+            result.length > 0 && this.uncommitted.push({
+                type: "diff",
+                result
+            });
+            return result;
+        }
+        catch (err) {
+            this.uncommittedError = err;
+            throw err;
+        }
+    }
+    /**
+     * Merges a patch into the current value at a path, and records the diff for the next
+     * `Commit()`.
+     * @param path - Dot-separated path to the value
+     * @param patch - The value to merge into the current value
+     * @returns Diff results showing changes
+     * @throws The change's error, or an earlier uncommitted change's error.
+     */
+    PatchPath(path, patch) {
+        if (this.uncommittedError)
+            throw this.uncommittedError;
+        try {
+            const result = super.PatchPath(path, patch);
+            result.length > 0 && this.uncommitted.push({
+                type: "diff",
+                result
+            });
+            return result;
+        }
+        catch (err) {
+            this.uncommittedError = err;
+            throw err;
+        }
+    }
+    /**
+     * Appends items to the array at a path, and records the diff for the next `Commit()`.
+     * @param path - Dot-separated path to the array
+     * @param items - The items to append
+     * @returns Diff results showing changes
+     * @throws The change's error, or an earlier uncommitted change's error.
+     */
+    PushPath(path, items) {
+        if (this.uncommittedError)
+            throw this.uncommittedError;
+        try {
+            const result = super.PushPath(path, items);
+            result.length > 0 && this.uncommitted.push({
+                type: "diff",
+                result
+            });
+            return result;
+        }
+        catch (err) {
+            this.uncommittedError = err;
+            throw err;
+        }
+    }
+    /**
+     * Splices the array at a path, and records the splice for the next `Commit()`.
+     * @param path - Dot-separated path to the array
+     * @param start - The position at which to start changing the array
+     * @param deleteCount - The number of elements to delete
+     * @param items - The elements to insert
+     * @returns The splice and its diff results
+     * @throws The change's error, or an earlier uncommitted change's error.
+     */
+    SplicePath(path, start, deleteCount, items) {
+        if (this.uncommittedError)
+            throw this.uncommittedError;
+        try {
+            const result = super.SplicePath(path, start, deleteCount, items);
+            this.uncommitted.push({
+                type: "splice",
+                result
+            });
+            return result;
+        }
+        catch (err) {
+            this.uncommittedError = err;
+            throw err;
+        }
+    }
+    /**
+     * Runs projections and posts every change since the last commit as one `DIFF_TREE_EVENT`
+     * message, which a `PushStore` applies as a unit. Posts nothing when nothing changed.
+     *
+     * If a change in the batch failed, projections are skipped, the applied changes are still
+     * posted, and a `DIFF_TREE_ERROR` message follows with the error; `Commit()` itself doesn't
+     * throw, since the failed change already did. If a projection throws, the batch's changes
+     * and the error are posted the same way, then `Commit()` rethrows. Either way the next batch
+     * starts clean.
+     * @throws A projection's error.
+     */
+    Commit() {
+        try {
+            const result = !this.uncommittedError ? super.RunProjections() : [];
+            result.length > 0 && this.uncommitted.push({
+                type: "diff",
+                result
+            });
+        }
+        catch (err) {
+            this.uncommittedError = err;
+            throw err;
+        }
+        finally {
+            this.uncommitted.length > 0 && this.worker.postMessage({
+                type: DIFF_TREE_EVENT,
+                data: this.uncommitted
+            });
+            if (this.uncommittedError) {
+                this.worker.postMessage({
+                    type: DIFF_TREE_ERROR,
+                    data: this.uncommittedError
+                });
+            }
+            this.uncommitted = [];
+            this.uncommittedError = null;
+        }
+    }
+}

package/Store/Diff/index.d.ts

@@ -0,0 +1 @@
+export * from "./diffTree.types";

package/Store/Diff/index.js

@@ -0,0 +1 @@
+export * from "./diffTree.types";

package/Store/Store/pushStore.d.ts

@@ -0,0 +1,57 @@
+import { ReadStore } from "./store";
+/**
+ * A read-only store whose changes are pushed to it by a `DiffTreeWriter`. The writer decides
+ * when data changes and pushes it with `Commit()`; this store applies each pushed batch as it
+ * arrives, and readers update the same way they do for any other store.
+ *
+ * The source is any `EventTarget` that delivers the writer's messages as `"message"` events:
+ * usually a `Worker` or a `MessagePort`, or a plain `EventTarget` when the writer runs on the
+ * same thread. The store ignores any message that isn't a `DIFF_TREE_EVENT` or
+ * `DIFF_TREE_ERROR`, so the source can carry other traffic too. It never takes over the
+ * source's `onmessage` or terminates a worker; that stays with the source's owner. It doesn't
+ * listen for the source's `"error"` events either: the writer's errors arrive as
+ * `DIFF_TREE_ERROR` messages (see `Error`).
+ *
+ * Changes are diffs against the writer's tree, so create the store before the writer's
+ * first `Commit()`. A store created later misses the earlier changes.
+ *
+ * @example
+ * const worker = new Worker(new URL("./engine-worker.ts", import.meta.url), { type: "module" });
+ * const store = new PushStore(worker);
+ * store.Get<Results>("results");   // reactive; undefined until the first commit
+ * store.Destroy();                 // stops listening; doesn't terminate the worker
+ *
+ * @see DiffTreeWriter
+ * @see StoreAsync
+ */
+export declare class PushStore extends ReadStore {
+    private eventTarget;
+    private error;
+    private errorScope;
+    /**
+     * The error the writer reported with its last commit, or null. Reactive. It's cleared when
+     * a later commit's changes arrive, so it reflects the most recent push, not a stopped store:
+     * the writer's later changes are still applied after an error.
+     */
+    get Error(): any;
+    private messageHandler;
+    /**
+     * Creates a PushStore and starts listening to the source. A `MessagePort` is started for
+     * you, since `addEventListener` doesn't start a port the way assigning `onmessage` does.
+     * @param eventTarget The source of the `DiffTreeWriter`'s messages: a `Worker`, a
+     *   `MessagePort`, or any `EventTarget` that dispatches them as `"message"` events.
+     * @param keyFunc Optional function to generate a key for a given data value, used to
+     *   resolve root objects. Pass the same key logic the `DiffTreeWriter` was constructed
+     *   with, if any.
+     * @param cloneData Whether to deep-clone the values the store adopts (false by default).
+     *   A `Worker` or `MessagePort` already delivers a structured-clone copy of every message.
+     *   A same-thread `EventTarget` delivers the writer's own objects, so either the writer
+     *   posts copies or this is true; otherwise the store and the writer's tree share objects.
+     */
+    constructor(eventTarget: EventTarget, keyFunc?: (value: any) => string | undefined, cloneData?: boolean);
+    /**
+     * Stops listening to the source and destroys the error scope. The source stays open (a
+     * worker keeps running); closing or terminating it is up to its owner.
+     */
+    Destroy(): void;
+}

package/Store/Store/pushStore.js

@@ -0,0 +1,96 @@
+import { DIFF_TREE_ERROR, DIFF_TREE_EVENT } from "../Diff/diffTree.types";
+import { ObservableScope } from "../Tree/observableScope";
+import { ReadStore } from "./store";
+/**
+ * A read-only store whose changes are pushed to it by a `DiffTreeWriter`. The writer decides
+ * when data changes and pushes it with `Commit()`; this store applies each pushed batch as it
+ * arrives, and readers update the same way they do for any other store.
+ *
+ * The source is any `EventTarget` that delivers the writer's messages as `"message"` events:
+ * usually a `Worker` or a `MessagePort`, or a plain `EventTarget` when the writer runs on the
+ * same thread. The store ignores any message that isn't a `DIFF_TREE_EVENT` or
+ * `DIFF_TREE_ERROR`, so the source can carry other traffic too. It never takes over the
+ * source's `onmessage` or terminates a worker; that stays with the source's owner. It doesn't
+ * listen for the source's `"error"` events either: the writer's errors arrive as
+ * `DIFF_TREE_ERROR` messages (see `Error`).
+ *
+ * Changes are diffs against the writer's tree, so create the store before the writer's
+ * first `Commit()`. A store created later misses the earlier changes.
+ *
+ * @example
+ * const worker = new Worker(new URL("./engine-worker.ts", import.meta.url), { type: "module" });
+ * const store = new PushStore(worker);
+ * store.Get<Results>("results");   // reactive; undefined until the first commit
+ * store.Destroy();                 // stops listening; doesn't terminate the worker
+ *
+ * @see DiffTreeWriter
+ * @see StoreAsync
+ */
+export class PushStore extends ReadStore {
+    /**
+     * The error the writer reported with its last commit, or null. Reactive. It's cleared when
+     * a later commit's changes arrive, so it reflects the most recent push, not a stopped store:
+     * the writer's later changes are still applied after an error.
+     */
+    get Error() {
+        return ObservableScope.Value(this.errorScope);
+    }
+    /**
+     * Creates a PushStore and starts listening to the source. A `MessagePort` is started for
+     * you, since `addEventListener` doesn't start a port the way assigning `onmessage` does.
+     * @param eventTarget The source of the `DiffTreeWriter`'s messages: a `Worker`, a
+     *   `MessagePort`, or any `EventTarget` that dispatches them as `"message"` events.
+     * @param keyFunc Optional function to generate a key for a given data value, used to
+     *   resolve root objects. Pass the same key logic the `DiffTreeWriter` was constructed
+     *   with, if any.
+     * @param cloneData Whether to deep-clone the values the store adopts (false by default).
+     *   A `Worker` or `MessagePort` already delivers a structured-clone copy of every message.
+     *   A same-thread `EventTarget` delivers the writer's own objects, so either the writer
+     *   posts copies or this is true; otherwise the store and the writer's tree share objects.
+     */
+    constructor(eventTarget, keyFunc, cloneData = false) {
+        super(keyFunc, cloneData);
+        this.eventTarget = eventTarget;
+        this.error = null;
+        this.errorScope = ObservableScope.Basic(() => this.error);
+        this.messageHandler = (event) => {
+            const messageData = event.data;
+            if (messageData && messageData.type === DIFF_TREE_EVENT) {
+                const data = messageData.data;
+                for (let x = 0; x < data.length; x++) {
+                    const result = data[x];
+                    switch (result.type) {
+                        case "diff": {
+                            this.UpdateRootMap(result.result);
+                            break;
+                        }
+                        case "splice": {
+                            const spliceResult = result.result;
+                            this.UpdateRootMap(spliceResult.diffResult);
+                            this.SpliceRootObject(spliceResult.path[0], spliceResult.start, spliceResult.deleteCount, spliceResult.items);
+                            break;
+                        }
+                    }
+                }
+                if (this.error !== null) {
+                    this.error = null;
+                    ObservableScope.Update(this.errorScope);
+                }
+            }
+            else if (messageData && messageData.type === DIFF_TREE_ERROR) {
+                this.error = messageData.data;
+                ObservableScope.Update(this.errorScope);
+            }
+        };
+        eventTarget.addEventListener("message", this.messageHandler);
+        eventTarget.start?.();
+    }
+    /**
+     * Stops listening to the source and destroys the error scope. The source stays open (a
+     * worker keeps running); closing or terminating it is up to its owner.
+     */
+    Destroy() {
+        this.eventTarget.removeEventListener("message", this.messageHandler);
+        ObservableScope.Destroy(this.errorScope);
+    }
+}

package/Store/Store/store.d.ts

@@ -1,18 +1,19 @@
 import { JsonDiffResult } from "../../Utils/json";
 /**
- * Base class for observable data store management.
- * Stores root objects as ObservableNode instances and manages updates through diff operations.
+ * Base class for reading observable data: holds root objects as ObservableNode instances
+ * and applies diff results to them. Subclasses decide where the diffs come from: `Store`
+ * adds the write methods, and `PushStore` takes them from a `DiffTreeWriter`.
  *
- * @see StoreSync
- * @see StoreAsync
+ * @see Store
+ * @see PushStore
  */
-export declare abstract class Store {
+export declare abstract class ReadStore {
     protected keyFunc?: (value: any) => string | undefined;
     private cloneData;
     private rootMap;
     private createNode;
     /**
-     * Creates an instance of Store.
+     * Creates an instance of ReadStore.
      * @param keyFunc Optional function to generate a key for a given data value.
      * When provided, enables alias functionality where values can reference other root objects.
      */
@@ -33,10 +34,6 @@ export declare abstract class Store {
      */
     Get<O>(id: string, defaultValue: O): O;
     Has(id: string): boolean;
-    abstract Write(data: unknown, key?: string): Promise<void> | void;
-    abstract Patch(key: string, patch: unknown): Promise<void> | void;
-    abstract Push(key: string, ...data: unknown[]): Promise<void> | void;
-    abstract Splice(key: string, start: number, deleteCount?: number, ...items: unknown[]): Promise<any[]> | any[];
     /**
      * Updates the root map with diff results by grouping changes by root path.
      * @param results - Array of diff results to apply
@@ -54,3 +51,16 @@ export declare abstract class Store {
      */
     private UpdateRootObject;
 }
+/**
+ * Base class for observable data store management.
+ * Stores root objects as ObservableNode instances and manages updates through diff operations.
+ *
+ * @see StoreSync
+ * @see StoreAsync
+ */
+export declare abstract class Store extends ReadStore {
+    abstract Write(data: unknown, key?: string): Promise<void> | void;
+    abstract Patch(key: string, patch: unknown): Promise<void> | void;
+    abstract Push(key: string, ...data: unknown[]): Promise<void> | void;
+    abstract Splice(key: string, start: number, deleteCount?: number, ...items: unknown[]): Promise<any[]> | any[];
+}

package/Store/Store/store.js

@@ -1,15 +1,16 @@
 import { JsonDeepClone } from "../../Utils/json";
 import { ObservableNode } from "../Tree/observableNode";
 /**
- * Base class for observable data store management.
- * Stores root objects as ObservableNode instances and manages updates through diff operations.
+ * Base class for reading observable data: holds root objects as ObservableNode instances
+ * and applies diff results to them. Subclasses decide where the diffs come from: `Store`
+ * adds the write methods, and `PushStore` takes them from a `DiffTreeWriter`.
  *
- * @see StoreSync
- * @see StoreAsync
+ * @see Store
+ * @see PushStore
  */
-export class Store {
+export class ReadStore {
     /**
-     * Creates an instance of Store.
+     * Creates an instance of ReadStore.
      * @param keyFunc Optional function to generate a key for a given data value.
      * When provided, enables alias functionality where values can reference other root objects.
      */
@@ -85,3 +86,12 @@ export class Store {
         ObservableNode.ApplyDiff(rootObject, results);
     }
 }
+/**
+ * Base class for observable data store management.
+ * Stores root objects as ObservableNode instances and manages updates through diff operations.
+ *
+ * @see StoreSync
+ * @see StoreAsync
+ */
+export class Store extends ReadStore {
+}

package/Store/Store/storeSync.d.ts

@@ -1,4 +1,4 @@
-import { DiffTreeProjectionMap } from "../Diff/diffTree";
+import { DiffTreeProjectionMap } from "../Diff/diffTree.types";
 import { Store } from "./store";
 /**
  * StoreSync class extends the base Store class to provide synchronous data management operations.
@@ -70,5 +70,5 @@ export declare class StoreSync extends Store {
      * @param items Optional elements to insert into the array.
      * @returns The array of deleted elements.
      */
-    Splice(key: string, start: number, deleteCount?: number, ...items: unknown[]): any[];
+    Splice(key: string, start: number, deleteCount?: number, ...items: unknown[]): unknown[];
 }

package/Store/Tree/observableScope.d.ts

@@ -188,7 +188,7 @@ export declare namespace ObservableScope {
      * @param scope The scope to stop watching.
      * @param callback The callback function to remove.
      */
-    function Unwatch<T>(scope: IObservableScope<T>, callback: (scope: IObservableScope<T>) => void): void;
+    function Unwatch<T>(scope: IObservableScope<T> | IBasicObservableScope<T>, callback: (scope: IObservableScope<T>) => void): void;
     /**
      * Registers a callback to be invoked when the scope's value is updated.
      * Only applies to dynamic scopes; no-op for static scopes.

package/Store/index.d.ts

@@ -1,5 +1,6 @@
-export { Store } from "./Store/store";
+export { ReadStore, Store } from "./Store/store";
 export { StoreSync } from "./Store/storeSync";
 export { StoreAsync } from "./Store/storeAsync";
+export { PushStore } from "./Store/pushStore";
 export { ObservableScope } from "./Tree/observableScope";
 export { ObservableNode } from "./Tree/observableNode";

package/Store/index.js

@@ -1,5 +1,6 @@
-export { Store } from "./Store/store";
+export { ReadStore, Store } from "./Store/store";
 export { StoreSync } from "./Store/storeSync";
 export { StoreAsync } from "./Store/storeAsync";
+export { PushStore } from "./Store/pushStore";
 export { ObservableScope } from "./Tree/observableScope";
 export { ObservableNode } from "./Tree/observableNode";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "j-templates",
-  "version": "8.0.27",
+  "version": "8.1.0",
   "description": "j-templates",
   "license": "MIT",
   "repository": "https://github.com/TypesInCode/jTemplates",