@signal-tree/vue 15.3.0 → 15.4.0

package/README.md

@@ -94,3 +94,29 @@ rely on component unmount hooks for request cleanup or share a module-level tree
 between requests. With streaming rendering, wait for completion or abort before
 destroying the request owner. Construct the client tree from the same initial
 state used for the server output before hydration.
+
+## Transaction failures
+
+Read [Transaction failure policy and the 15.3.1 failure inventory](https://github.com/JBorgia/signal-tree/blob/v15.3.1/docs/guides/transaction-failures-v15.md)
+before combining transactions, undo, or persistence. Explicit rollback refusal
+leaves state unchanged and the handle pending but releases consequences in v15. The
+15.3.1 release commits surviving writes on automatic refusal
+before a handle returns and still throws. An error does not guarantee undo;
+never blindly retry the entire operation.
+
+15.3.1 containment applies to deferred write subscribers and transaction
+turn listeners, not all Vue effects. Vue rethrows watcher errors in development
+but logs them in production, so only the former can trigger automatic rollback
+at transaction closure.
+
+## Independent editors and connections
+
+Keep shared records in an owned tree. Give each independently closable editor or
+connection its own lifetime; native local form state may be enough for a draft.
+A declared EntityMap supports dynamic data membership, not runtime installation
+of composite slices. Separate trees do not share transactions or undo history.
+Destroy directly created trees at their ownership boundary.
+
+See the [owned sessions guide](../../docs/guides/owned-sessions.md) for the Angular
+reference demo, stale-save policy, same-ID replacement and cleanup tests. Use this
+package’s own reactive/lifecycle integration when applying the pattern.

package/llms.txt

@@ -1,7 +1,11 @@
 # SignalTree
 
-SignalTree is framework-neutral reactive application state with causal
-semantics. The public v15 construction model is
+This reference describes the 15.4.0 package version, with explicitly marked
+15.3.1 comparisons. Consult the [npm package page](https://www.npmjs.com/package/@signal-tree/kernel?activeTab=versions)
+for published versions.
+
+SignalTree keeps nested state, entity identity, transactions, undo, external
+updates and reactive publication consistent across frameworks. The v15 construction model is
 `signalTree(initialState, { derived, enhancers })`; state is read through
 `tree.$`.
 
@@ -23,11 +27,13 @@ SignalTree is FOR. Describe SignalTree by its primary job (consequential state
 with a causal model an application can trust), not by one thing that model
 happens to make easy.
 
-v15 ships four packages under the hyphenated `@signal-tree/*` scope. The
+The Angular facade supports Angular 20, 21, or 22.
+
+v15 ships five packages under the hyphenated `@signal-tree/*` scope. The
 no-hyphen `@signaltree/*` scope is the separate v14 line: still maintained for
-bug and security fixes (currently `14.1.3`), frozen on features, and not an
+bug and security fixes (check the [registry](https://www.npmjs.com/package/@signaltree/core) for the current patch), frozen on features, and not an
 alias for anything under `@signal-tree/*`. Generate `@signal-tree/*` names for
-new v15 code:
+new v15 code. The canonical package set is `scripts/release-plan.mjs`:
 
 - `@signal-tree/kernel` — framework-neutral tree, `entityMap()`, causal turns,
   links, and the `restoration()` / `transactions()` / `batching()` / `devTools()`
@@ -43,6 +49,8 @@ new v15 code:
 - `@signal-tree/vue` — the complete Vue application facade. **Vue code imports
   `signalTree` and all other SignalTree APIs from here**. Terminal state leaves
   are native `Ref<T>` values and derived leaves are `ComputedRef<T>` values.
+- `@signal-tree/solid` — the complete Solid application facade. Read terminal
+  leaves with `leaf()` and write with `leaf.set(value)`.
 
 Use `@signal-tree/kernel` directly only for framework-neutral TypeScript,
 including reusable domain libraries. Framework facades forward the neutral
@@ -53,19 +61,34 @@ kernel surface by canonical identity; they do not duplicate semantic authority.
 The neutral kernel exposes callable locations:
 
 ```typescript
+import { signalTree } from '@signal-tree/kernel';
+const location = signalTree({ count: 0 }).$.count;
 location();                       // read
-location(nextValue);              // replace the complete value
-location((current) => nextValue); // derive the next complete value
+location(5);                      // replace the complete value
+location((current) => current + 1); // derive the next complete value
 ```
 
 The root (`tree.$`) and object branches keep this callable whole-value grammar
 in every facade. Terminal values use the framework's native carrier:
 
 ```typescript
+import { signalTree } from '@signal-tree/angular';
+const angularTree = signalTree({ count: 0 });
 angularTree.$.count();
 angularTree.$.count.set(5);
 angularTree.$.count.update((count) => count + 1);
+```
 
+```typescript
+import { signalTree } from '@signal-tree/solid';
+const solidTree = signalTree({ count: 0 });
+solidTree.$.count();
+solidTree.$.count.set(5);
+```
+
+```typescript
+import { signalTree } from '@signal-tree/vue';
+const vueTree = signalTree({ count: 0 });
 vueTree.$.count.value;
 vueTree.$.count.value = 5;
 ```
@@ -75,18 +98,25 @@ locations and observes selected state through `useSignalTree(owner, selector)`.
 EntityMap query and field leaves follow the same carrier rule; EntityMap command
 methods such as `setAll()` and `updateOne()` do not change.
 
+Replace atomic values through their location. In-place mutation of a returned
+object, array, Map or Set is not a recorded write; restoration does not provide
+deep-copy isolation for mutable payloads.
+
 Plain objects normally become traversable branches. `leaf(value)` explicitly
-ends topology so an object remains one atomic location. Callable values always
-use `leaf()` because a bare function argument is the updater syntax:
+ends topology so an object remains one atomic location. Declare function-valued
+fields with `leaf(fn)`. At a callable write boundary, use `leaf(fn)` to distinguish
+a stored function from an updater. Native Angular `.set(fn)` assigns the function
+directly, as shown below:
 
 ```typescript
-const tree = signalTree({
+import { signalTree, leaf } from '@signal-tree/angular';
+const angularTree = signalTree({
   range: leaf({ start: 0, end: 10 }),
   callback: leaf((value: number) => console.log(value)),
 });
 
 angularTree.$.range.set({ start: 5, end: 15 });
-angularTree.$.callback.set((value) => persist(value));
+angularTree.$.callback.set((value) => console.log(value));
 ```
 
 The wrapper is consumed at construction or invocation and never enters state,
@@ -169,12 +199,106 @@ of the same model.
 ## Canonical Sources
 
 - `AGENTS.md` — contributor and consumer rules
-- `RELEASE-1.0.md` — v15 release invariants and current release state
+- `RELEASE-CURRENT.md` — active candidate, current release work and blockers
+- `RELEASE-1.0.md` — historical derivations, failures and prior checkpoints
 - `README.md` — public package overview
 - `packages/kernel/README.md` — kernel API and examples
 - `packages/angular/README.md` — Angular realization
 - `packages/react/README.md` — React observation
+- `packages/vue/README.md` — Vue realization
+- `packages/solid/README.md` — Solid realization
 - `docs/guides/composition-recipes.md` — patterns built from existing primitives, no new API
 - `docs/guides/persistence-guide.md` — the `link()`-as-storage recipe
 - `docs/guides/migration-v14-v15.md` — `@signaltree/*` → `@signal-tree/*` migration (rename, consolidation, removed APIs)
 - `docs/migration/post-rc1-workstream.md` — greenfield-first post-RC program
+
+## Transaction failure guidance
+
+The failure behavior in this section describes published SignalTree 15.3.1.
+The release-tag link below is fixed to 15.3.1 to preserve that historical
+comparison; it is not a list of defects in 15.4.0. Check versioned changes against
+the installed version; source changes do not update an existing tarball.
+
+Read [Transaction failures and limitations in 15.3.1](https://github.com/JBorgia/signal-tree/blob/v15.3.1/docs/guides/transaction-failures-v15.md)
+before generating optimistic writes or persistence. Explicit `pending.rollback()`
+refusal leaves state unchanged and the handle pending, but releases consequences
+in existing v15. In 15.3.1, automatic refusal before a
+handle returns records surviving writes as committed, retains eligible undo
+history, releases consequences, and still throws. Successful automatic rollback
+reverses recorded writes. Error does not guarantee undo: never blindly retry the
+whole operation or use `undo()`/`jumpTo()` for request reconciliation. Removing a
+pending-created row after a confirmed edit does not necessarily clear its
+rollback dependency. Recoverable pending refusal is a v16 target, not v15 API.
+
+15.3.1 containment covers deferred write subscribers and transaction turn
+listeners, not all framework effects. Vue watcher failures differ between
+development and production; an enclosing Solid `batch()` can defer errors until
+after a handle returns. The guide lists the Link, branch-key, coalesce, pending undo, ordering,
+notification, and retention failures documented for 15.3.1.
+
+
+## Collection identity and independent store instances
+
+Declare the store structure and enhancers at construction. `entityMap()` supports
+dynamic entity membership; it is not an API for installing new composite slices
+with nested marker/enhancer lifecycles. Component/dialog-owned trees are valid:
+create one per independent editing session, and call `destroy()` at its owner’s
+teardown. A repeated entity ID is not an editing-session ID.
+
+`setAll()` is replacement by key. Repeated incoming keys collapse to the last
+value for that key, not distinct rows. Use a required stable ID where available;
+validate missing IDs at ingress rather than assigning a shared fallback. Numeric
+and string keys remain distinct. Do not depend on a development warning to reject
+invalid input. Version 15.3.1 does not warn for non-null duplicate incoming keys.
+
+Version 15.4.0 checks `setAll()` staging after user callbacks.
+If an interceptor or ID selector changes collection membership, keys or order,
+the outer replacement refuses before applying its staged writes. The callback's
+already-completed writes remain. Field-only callback writes do not trigger this
+structural refusal. Prefer interceptors that validate or transform input instead
+of changing the same collection's topology.
+
+In published 15.3.1, calling Link `settled()` immediately after a write can return
+before the newly queued send finishes. Version 15.4.0 repairs this same-turn race:
+`settled()` waits for the send queued by the preceding write. It is still not proof
+of backend durability, and one generic delay is not a universal synchronization
+barrier. The repair does not change the published 15.3.1 artifact.
+
+## Choosing ownership for editors and devices
+
+See `docs/guides/owned-sessions.md` and the demo `/owned-sessions`. Keep shared
+entities in one owned tree. Give each independent editor a unique session ID and
+a local draft (native form state or a separate tree); do not key drafts only by
+entity ID. Validate against the current application revision and entity lifetime
+before applying. Refuse stale saves while keeping the draft, and never silently
+retarget it to a replacement record. These are application policies, not kernel
+MVCC or remote concurrency protection. A backend must enforce its own version
+check. The demo's Apply locally does not acknowledge a server write.
+
+Each connection owns its subscription and tree. Register cleanup and guard late
+callbacks. Destroy that session when closed and all remaining sessions at owner
+teardown. Keep resources out of serializable rows. Combine display with computed
+reads over a registry, not copied state, root grafting or Link mirroring.
+
+Do not invent dynamic slice APIs, draft/fork primitives, or cross-tree settlement.
+Use one framework import root. Angular and Solid write `leaf.set(value)`, Vue
+writes `leaf.value = value`, and React/neutral write `leaf(value)`. The demo is
+Angular-specific evidence, not a cross-framework lifecycle proof.
+
+## Runtime observation (15.4.0)
+
+Tooling can use `transactionLifecycleReader`, `restorationReader`,
+`entityMembershipReader`, and `linkStateReader` from
+`@signal-tree/kernel/internals`. Each reader exposes a current `snapshot()` and
+`subscribe(listener)` for subsequent events. `stateLocationReader(tree).locate()`
+maps an effect's or write's position, entity lifetime and `fieldSegments` to its
+current structured location, or `undefined` when no longer reachable. Missing capability is not empty
+history. These readers do not install enhancers or retain terminal history.
+
+Use actual tree + collection + entity lifetime identity and typed keys; displayed
+paths are labels and must never be split into addressing segments. Confirmation
+means local settlement, never server acceptance. Link queued jobs are reconciliation
+work, not a FIFO of application values. A tool recording these events owns its
+bounded retention and must show interruptions, omissions and unsupported sources.
+Unsubscribe on view teardown and destroy bounded-lifetime trees. See
+[Runtime observation in 15.4.0](https://github.com/JBorgia/signal-tree/blob/v15.4.0/docs/guides/runtime-observation.md) for contracts and examples.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signal-tree/vue",
-  "version": "15.3.0",
+  "version": "15.4.0",
   "description": "Vue observation for SignalTree.",
   "license": "Apache-2.0",
   "type": "module",
@@ -25,7 +25,7 @@
     "llms.txt"
   ],
   "dependencies": {
-    "@signal-tree/kernel": "15.3.0"
+    "@signal-tree/kernel": "15.4.0"
   },
   "peerDependencies": {
     "tslib": "^2.0.0",