@signal-tree/react 15.0.0-rc.12 → 15.0.0-rc.14

package/README.md

@@ -1,21 +1,36 @@
-# @signal-tree/react
+# `@signal-tree/react`
 
 React observation for SignalTree. It connects React's external-store lifecycle
 to canonical SignalTree reads without copying state into React.
 
+## Semantic Guidance
+
+The canonical v15 model and composition guidance ships with this package as
+[llms.txt](llms.txt). It explains the React facade rule, `link()`
+relationships, persistence composition, and causal explanations as projections
+rather than retained kernel facts.
+
 ## Install
 
 ```bash
-npm install @signal-tree/react @signal-tree/kernel
+npm install @signal-tree/react
+```
+
+React 18 or 19 is required as a peer dependency. `@signal-tree/react` installs
+the framework-neutral kernel as its dependency, so React applications should
+construct and enhance trees through this package:
+
+```tsx
+import { entityMap, signalTree, useSignalTree } from '@signal-tree/react';
+
+const tree = signalTree({ orders: entityMap<{ id: string; status: string }>() });
 ```
 
-React 18 or 19 is required as a peer dependency.
+Framework-neutral libraries may import from `@signal-tree/kernel` directly.
 
 ## Observe A Projection
 
 ```tsx
-import { useSignalTree } from '@signal-tree/react';
-
 function OrderStatus({ tree, orderId }) {
   const status = useSignalTree(tree, ($) => $.orders.byIdOrFail(orderId).status());
 

package/dist/index.js

@@ -1 +1,2 @@
+export * from '@signal-tree/kernel';
 export { useSignalTree } from './use-signal-tree.js';

package/llms.txt

@@ -0,0 +1,177 @@
+# SignalTree
+
+SignalTree is framework-neutral reactive application state with causal
+semantics. The public v15 construction model is
+`signalTree(initialState, { derived, enhancers })`; state is read through
+`tree.$`.
+
+## What SignalTree is — and is not
+
+```text
+IS:     framework-independent consequential application state, stable subject
+      identity, authored versus external authority, coherent operation
+      boundaries, causal/restoration semantics, and link-based relationships
+
+IS NOT: primarily an undo library, event log, query library, sync engine, or
+      persistence framework
+```
+
+Undo/redo, event replay, query composition, live synchronization, and
+persistence are all things applications correctly BUILD on top of SignalTree's
+causal model — see "Composition patterns" below — but none of them is what
+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 pre-15
+`@signaltree/*` scope, no hyphen, stopped at 14.1.1):
+
+- `@signal-tree/kernel` — framework-neutral tree, `entityMap()`, causal turns,
+  links, and the `restoration()` / `transactions()` / `batching()` / `devTools()`
+  enhancers. Also `@signal-tree/kernel/adapter`, the realization SDK.
+- `@signal-tree/angular` — the complete Angular application facade. **Angular
+  code imports `signalTree` and all other SignalTree APIs from here**. Terminal
+  state leaves are native `WritableSignal<T>` values and derived leaves are
+  native `Signal<T>` values. Adds `defineStore()` and `toWritableSignal()` for
+  adapting callable object branches or designating form ingress.
+- `@signal-tree/react` — the complete React application facade. **React code
+  imports `signalTree`, markers, enhancers, and `useSignalTree(owner, selector)`
+  from here**; React observes the canonical kernel tree without copying it.
+- `@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.
+
+Use `@signal-tree/kernel` directly only for framework-neutral TypeScript,
+including reusable domain libraries. Framework facades forward the neutral
+kernel surface by canonical identity; they do not duplicate semantic authority.
+
+## Accessor grammar and terminal values
+
+The neutral kernel exposes callable locations:
+
+```typescript
+location();                       // read
+location(nextValue);              // replace the complete value
+location((current) => nextValue); // 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
+angularTree.$.count();
+angularTree.$.count.set(5);
+angularTree.$.count.update((count) => count + 1);
+
+vueTree.$.count.value;
+vueTree.$.count.value = 5;
+```
+
+React has no persistent signal primitive, so `@signal-tree/react` keeps neutral
+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.
+
+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:
+
+```typescript
+const tree = 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));
+```
+
+The wrapper is consumed at construction or invocation and never enters state,
+snapshots, persistence, restoration, links, or causal payloads.
+
+There is no v15 forms, persistence, validation, events, or realtime package;
+those are application-owned. `.with()`, positional `derived`, and the
+`stored`/`asyncSource`/`asyncQuery`/`form`/`status` markers were all removed.
+
+## Migration Rule
+
+Never design SignalTree around a legacy application's intermediate state.
+
+1. Determine the canonical greenfield v15 architecture.
+2. Implement and validate that architecture independently.
+3. Migrate applications toward that target.
+4. Prefer deleting obsolete concepts over adapting them.
+5. Never add compatibility APIs merely to reduce migration work.
+6. A migration may falsify the target architecture, but legacy usage does not
+   define it.
+
+Do not create intermediate APIs intended to be removed later. Do not add
+compatibility layers because a migration is large. Do not preserve old
+ownership because moving it is inconvenient. Do not design framework adapters
+from legacy application idioms. Do not optimize for minimal migration diff.
+Optimize for the architecture applications should use five years from now.
+
+`@signal-tree/kernel/adapter` is the SDK for realization ownership, not a
+compatibility layer. New exports must be framework-neutral semantic facts owned
+by the kernel and required by correct realizations.
+
+## Framework Realization Rule
+
+Framework packages may realize SignalTree truth for their runtime. They must
+not create another state authority.
+
+Never use process-global mutable framework installation merely to make a legacy
+integration work if construction-bound ownership can express the long-term
+architecture. A migration cannot determine realization ownership.
+
+## Framework Ownership Ratchet
+
+`@signal-tree/kernel` owns framework-independent SignalTree semantics.
+`@signal-tree/kernel/adapter` owns only neutral ports for semantic questions
+the kernel owns. Framework packages own their implementations, lifecycle,
+diagnostics, schedulers, rendering behavior, primitive identity rules, and
+quirks. Neutral naming does not establish neutral ownership.
+
+Every new realization contract must state its SignalTree semantic job, provide
+a neutral implementation, be implementable by a tiny framework-free fake, and
+name the kernel authority deciding when and why it runs. Reject contracts that
+exist only for one framework. If Angular, React, and Vue disappeared, the
+contract must remain meaningful to SignalTree or another reactive runtime.
+
+## Composition patterns
+
+Several capabilities that look like missing features are compositions of
+primitives that already ship — see `docs/guides/composition-recipes.md` for
+the full recipes with executable-spec citations. Do not propose a new marker
+or kernel API for any of these before reading it:
+
+- a standard enhancer policy, a reusable entity-CRUD Ops base, a selection
+  read-model
+- optimistic writes with server reconciliation (`transactions()`'s
+  pending/confirm/rollback lifecycle)
+- staged/draft editing (an application-owned draft, one authored commit — no
+  `beginStage()` session API)
+- one-shot loading (`external()`, no `link()` needed for a single fetch) versus
+  a persistent relationship with an external authority (`link()`'s three
+  composable directions: PULL/PUSH-IN/PUSH-OUT)
+- accepted external truth is distinct from authored application work, so an
+  external write is not automatically a retained causal-history turn
+- a human-readable explanation projected from the causal record (the
+  explanation is a PROJECTION of causal truth — the kernel does not store
+  prose, actor names, or timestamps merely to make one convenient)
+
+`docs/guides/persistence-guide.md` is the `link()`-as-storage specialization
+of the same model.
+
+## Canonical Sources
+
+- `AGENTS.md` — contributor and consumer rules
+- `RELEASE-1.0.md` — v15 release invariants and current release state
+- `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
+- `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signal-tree/react",
-  "version": "15.0.0-rc.12",
+  "version": "15.0.0-rc.14",
   "description": "React observation for SignalTree.",
   "license": "Apache-2.0",
   "type": "module",
@@ -21,10 +21,11 @@
     "src/**/*.d.ts",
     "README.md",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "llms.txt"
   ],
   "dependencies": {
-    "@signal-tree/kernel": "15.0.0-rc.12"
+    "@signal-tree/kernel": "15.0.0-rc.14"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/index.d.ts

@@ -1 +1,11 @@
+/**
+ * `@signal-tree/react` - React observation plus the complete SignalTree
+ * application surface.
+ *
+ * React observes framework-neutral SignalTree truth through
+ * `useSyncExternalStore`; it does not replace the kernel's tree carrier. React
+ * applications therefore construct, synchronize, and enhance trees through
+ * this package, then observe them with `useSignalTree`.
+ */
+export * from '@signal-tree/kernel';
 export { useSignalTree } from './use-signal-tree.js';