@signal-tree/react 15.0.0-rc.7 → 15.1.1

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());
 
@@ -35,6 +50,13 @@ const state = useSignalTree(tree, ($) => $());
 
 Use whole-root projection only when the component needs whole-root truth.
 
+## Server Rendering
+
+`useSignalTree()` reads the same canonical selector snapshot during server
+rendering, so React SSR does not require a mirrored store or a separate server
+adapter. Hydration should construct the tree from the same application state
+used by the server render before mounting the client tree.
+
 ## Selector Contract
 
 Selectors read synchronously from the supplied root location and must return an
@@ -67,6 +89,5 @@ SignalTree remains the only state authority. This package owns subscription,
 cleanup, and React snapshot observation. It does not mirror state, expose write
 APIs, own the tree lifecycle, or change SignalTree's causal semantics.
 
-SSR/hydration policy, React Native validation, custom equality, shared
-cross-component subscriptions, and first-party memoized selectors are not part
-of the initial surface.
+React Native validation, custom equality, shared cross-component subscriptions,
+and first-party memoized selectors are not part of the initial surface.

package/dist/index.js

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

package/dist/use-signal-tree.js

@@ -1 +1 @@
-import{useCallback,useSyncExternalStore}from"react";import{observeOwnerInvalidation}from"@signal-tree/kernel/adapter";function useSignalTree(owner,selector){const subscribe=useCallback(notify=>observeOwnerInvalidation(owner,notify),[owner]);const getSnapshot=useCallback(()=>selector(owner.$),[owner,selector]);return useSyncExternalStore(subscribe,getSnapshot)}export{useSignalTree};
+import{useCallback,useSyncExternalStore}from"react";import{observeOwnerInvalidation}from"@signal-tree/kernel/adapter";function useSignalTree(owner,selector){const subscribe=useCallback(notify=>observeOwnerInvalidation(owner,notify),[owner]);const getSnapshot=useCallback(()=>selector(owner.$),[owner,selector]);return useSyncExternalStore(subscribe,getSnapshot,getSnapshot)}export{useSignalTree};

package/llms.txt

@@ -0,0 +1,180 @@
+# 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
+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
+alias for anything under `@signal-tree/*`. Generate `@signal-tree/*` names for
+new v15 code:
+
+- `@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.7",
+  "version": "15.1.1",
   "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.7"
+    "@signal-tree/kernel": "15.1.1"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -32,5 +33,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JBorgia/signal-tree.git",
+    "directory": "packages/react"
   }
 }

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';