@signal-tree/angular 15.0.0-rc.12 → 15.0.0-rc.15

package/README.md

@@ -1,8 +1,15 @@
-# @signal-tree/angular
+# `@signal-tree/angular`
 
-Angular realization for SignalTree. It uses native Angular `Signal` and
-`WritableSignal` carriers while keeping state, entity, and causal semantics in
-`@signal-tree/kernel`.
+Angular-native SignalTree realization. State, identity, entity behavior, and
+causal semantics remain in `@signal-tree/kernel`; terminal leaves are native
+Angular signals and work directly in templates and `computed()`.
+
+## Semantic Guidance
+
+The canonical v15 model and composition guidance ships with this package as
+[llms.txt](llms.txt). It explains the Angular facade rule, `link()`
+relationships, persistence composition, and causal explanations as projections
+rather than retained kernel facts.
 
 ## Install
 
@@ -11,13 +18,15 @@ npm install @signal-tree/angular
 ```
 
 `@signal-tree/angular` installs `@signal-tree/kernel` as an exact dependency.
-Angular itself remains a peer dependency supplied by the application.
+Angular itself remains a peer dependency supplied by the application. This is
+the complete SignalTree facade for Angular applications: import `signalTree`,
+markers, enhancers, and types from this package rather than mixing kernel
+imports into Angular application code.
 
 Angular applications should construct state through this package, not through
 the neutral kernel package:
 
 ```ts
-import { computed } from '@angular/core';
 import { asReadonly, batching, entityMap, signalTree } from '@signal-tree/angular';
 
 type User = { id: number; name: string };
@@ -30,13 +39,13 @@ const tree = signalTree(
   {
     enhancers: [batching()],
     derived: ($) => {
-      const selected = computed(() => {
+      const selected = () => {
         const id = $.selectedId();
         return id === null ? null : $.users.byId(id)?.() ?? null;
-      });
+      };
       return {
         selected,
-        selectedName: computed(() => selected()?.name ?? 'None'),
+        selectedName: () => selected()?.name ?? 'None',
       };
     },
   }
@@ -47,10 +56,28 @@ reader.$.selectedName();
 ```
 
 There is one construction grammar: state, enhancers, and one derived factory are
-declared together in `signalTree(...)`. Derived values compose through ordinary
-local `computed` references inside that factory.
+declared together in `signalTree(...)`. Derived values are zero-argument recipes
+that SignalTree memoizes as native readonly Angular signals.
+
+Use `defineStore` for Angular dependency injection. State leaves already have
+native Angular signal identity and methods:
+
+```ts
+tree.$.selectedId.set(42);
+tree.$.selectedId.update((id) => (id ?? 0) + 1);
+```
+
+`toWritableSignal()` remains useful for adapting a callable root or object
+branch to APIs such as Signal Forms. Passing an ordinary leaf without options
+returns that same `WritableSignal`; `{ undoable: true }` creates a distinct
+ingress that designates writes for restoration:
+
+```ts
+const profileModel = toWritableSignal(tree.$.profile, injector, {
+  undoable: true,
+});
+```
 
-Use `defineStore` for Angular dependency injection and `toWritableSignal` when a
-branch must cross an Angular writable-signal boundary. Application components
+Application components
 should normally receive a read-only `$` plus explicit operation services for
 writes and asynchronous work.

package/dist/index.js

@@ -1 +1 @@
-import{ANGULAR_TREE_REALIZATION}from"./lib/angular-realization.js";import{createSignalTreeFactory}from"@signal-tree/kernel/adapter";import{SignalTreeRollbackError,asReadonly,batching,devTools,entityMap,external,link,onTreeError,restoration,transactions,undoable}from"@signal-tree/kernel";import{defineStore}from"./lib/define-store.js";import{toWritableSignal}from"./lib/to-writable-signal.js";const signalTree=createSignalTreeFactory(ANGULAR_TREE_REALIZATION);export{SignalTreeRollbackError,asReadonly,batching,defineStore,devTools,entityMap,external,link,onTreeError,restoration,signalTree,toWritableSignal,transactions,undoable};
+import{ANGULAR_OBSERVATION_ADAPTER}from"./lib/observation-adapter.js";import{createSignalTreeFactory}from"@signal-tree/kernel/adapter";import{asReadonly as asReadonly$1}from"@signal-tree/kernel";export*from"@signal-tree/kernel";import{defineStore}from"./lib/define-store.js";import{toWritableSignal}from"./lib/to-writable-signal.js";const signalTree=createSignalTreeFactory(ANGULAR_OBSERVATION_ADAPTER);const asReadonly=asReadonly$1;export{asReadonly,defineStore,signalTree,toWritableSignal};

package/dist/lib/observation-adapter.js

@@ -0,0 +1 @@
+import{linkedSignal,untracked,computed,signal}from"@angular/core";const ANGULAR_OBSERVATION_ADAPTER={createToken(){const revision=signal(0);return{observe:()=>void revision(),invalidate:()=>revision.update(value=>value+1)}},createWritableCell:read=>{const cell=signal(read());const publish=cell.set.bind(cell);return{cell,peek:read,token:{observe:()=>void cell(),invalidate:()=>publish(read())}}},createReadonlyCell:compute=>computed(compute),createWritableProjection:compute=>{const cell=linkedSignal(compute);return{cell,peek:()=>untracked(cell)}},runInvalidationGroup(run){run()}};export{ANGULAR_OBSERVATION_ADAPTER};

package/dist/lib/to-writable-signal.js

@@ -1 +1 @@
-import{signal,runInInjectionContext,effect}from"@angular/core";import{withRestorationDesignation}from"@signal-tree/kernel/adapter";function toWritableSignal(node,injector,options){const sig=signal(node());const originalSet=sig.set.bind(sig);const runner=()=>{originalSet(node())};if(injector){runInInjectionContext(injector,()=>effect(runner))}else{try{effect(runner)}catch{if(typeof ngDevMode==="undefined"||ngDevMode){console.warn("[SignalTree] toWritableSignal called without injection context; pass Injector for reactivity.")}}}sig.set=value=>{if(options?.undoable){withRestorationDesignation(()=>{node(value)})}else{node(value)}originalSet(value)};sig.update=updater=>{sig.set(updater(sig()))};return sig}export{toWritableSignal};
+import{isSignal,signal,runInInjectionContext,effect}from"@angular/core";import{withRestorationDesignation,isNodeAccessor,replaceLocation}from"@signal-tree/kernel/adapter";function toWritableSignal(node,injector,options){if(isSignal(node)&&!options?.undoable){return node}const sig=signal(node());const originalSet=sig.set.bind(sig);const runner=()=>{originalSet(node())};if(injector){runInInjectionContext(injector,()=>effect(runner))}else{try{effect(runner)}catch{if(typeof ngDevMode==="undefined"||ngDevMode){console.warn("[SignalTree] toWritableSignal called without injection context; pass Injector for reactivity.")}}}const applyWrite=write=>{if(options?.undoable){withRestorationDesignation(write)}else{write()}originalSet(node())};sig.set=value=>{applyWrite(()=>{if(isSignal(node))node.set(value);else if(isNodeAccessor(node))node(value);else replaceLocation(node,value)})};sig.update=updater=>{applyWrite(()=>{if(isSignal(node))node.update(updater);else if(isNodeAccessor(node))node(updater);else node(updater)})};return sig}export{toWritableSignal};

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/angular",
-  "version": "15.0.0-rc.12",
+  "version": "15.0.0-rc.15",
   "description": "Angular realization 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.15"
   },
   "peerDependencies": {
     "@angular/core": "^20.0.0 || ^21.0.0 || ^22.0.0",

package/src/index.d.ts

@@ -1,37 +1,18 @@
-/**
- * `@signal-tree/angular` — SignalTree realized with native Angular signals.
- *
- * REALIZATION IS CONSTRUCTION-BOUND. This package exports the same semantic
- * factory grammar as the kernel, bound once to Angular's native mechanisms.
- *
- * That ordering is the fix for a MEASURED defect: entity APIs used without
- * first calling `signalTree()` silently received neutral kernel cells — no
- * `isSignal`, no `asReadonly`, no dependency tracking. The old monolith
- * installed Angular as a side effect of importing `signal-tree.ts`, so the
- * guarantee depended on which module a consumer happened to touch first.
- *
- *     REALIZATION IS SELECTED AT CONSTRUCTION AND OWNED FOR THE TREE LIFETIME.
- */
+/** Angular observation plus the complete SignalTree application surface. */
 import './lib/carrier.js';
-import type { EntityNodeOf, EntitySignalOf, EntitySignalWithSlicesOf, ReadonlyStoreOf, ISignalTreeOf, LeafOf, SignalTreeFactoryOf, TreeNodeOf } from '@signal-tree/kernel/adapter';
-/**
- * The kernel's `signalTree`, DECLARED with Angular's carrier.
- *
- * Same kernel construction authority, package-bound to Angular mechanisms.
- */
+import type { AccessibleNodeOf, EntityNodeOf, EntitySignalOf, EntitySignalWithSlicesOf, ISignalTreeOf, LeafOf, ReadonlyStoreOf, ReadonlyViewOf, SignalTreeFactoryOf, TreeNodeOf } from '@signal-tree/kernel/adapter';
 export declare const signalTree: SignalTreeFactoryOf<"angular">;
-export { entityMap, link, restoration, undoable, external, asReadonly, batching, devTools, transactions, onTreeError, SignalTreeRollbackError, } from '@signal-tree/kernel';
-export type { TreeConfig, NodeAccessor, AccessibleNode, Primitive, Enhancer, EnhancerCleanup, Link, LinkEndpoint, TreeId, TreeErrorEvent, EntityMapMarker, EntityMapBuilder, EntityMapComputedSlices, EntityMapMarkerWithSlices, ComputedSliceConfig, AddOptions, AddManyOptions, DefaultKey, RestorationMethods, RestorationHistoryEntry, BatchingConfig, BatchingMethods, DevToolsMethods, DevToolsLogEntry, TransactionMethods, } from '@signal-tree/kernel';
 export type TreeNode<T> = TreeNodeOf<T, 'angular'>;
 export type WritableLeaf<T> = LeafOf<T, 'angular'>;
-export type EntitySignal<E, K extends string | number = string> = EntitySignalOf<E, K, 'angular'>;
+export type AccessibleNode<T> = AccessibleNodeOf<T, 'angular'>;
+export type ISignalTree<T, TAccum = TreeNode<T>> = ISignalTreeOf<T, 'angular', TAccum>;
+export type SignalTree<T> = ISignalTree<T>;
 export type EntityNode<E> = EntityNodeOf<E, 'angular'>;
-export type ReadonlyStore<TSource, TAccum = TreeNode<TSource>> = ReadonlyStoreOf<TSource, TAccum, 'angular'>;
+export type EntitySignal<E, K extends string | number = string> = EntitySignalOf<E, K, 'angular'>;
 export type EntitySignalWithSlices<E, K extends string | number, Slices extends Record<string, unknown>> = EntitySignalWithSlicesOf<E, K, Slices, 'angular'>;
-/**
- * The Angular tree contract. Same one parameter users always wrote; the carrier
- * differs because THIS package installed the Angular realization.
- */
-export type SignalTree<T> = ISignalTreeOf<T, 'angular'>;
+export type ReadonlyView<T> = ReadonlyViewOf<T, 'angular'>;
+export type ReadonlyStore<TSource, TAccum = TreeNode<TSource>> = ReadonlyStoreOf<TSource, TAccum, 'angular'>;
+export declare const asReadonly: <TSource, TAccum>(tree: ISignalTreeOf<TSource, "angular", TAccum>) => ReadonlyStoreOf<TSource, TAccum, "angular">;
+export * from '@signal-tree/kernel';
 export { defineStore, type DefineStoreConfig } from './lib/define-store.js';
 export { toWritableSignal } from './lib/to-writable-signal.js';

package/src/lib/carrier.d.ts

@@ -1,27 +1,16 @@
-import type { WritableSignal } from '@angular/core';
-/**
- * Angular's leaf carrier — the shape `@signal-tree/angular` promises consumers.
- *
- * This lived in the kernel until TYPE-A-PACKAGE-BINDING-0 (TA-B). It cannot: it
- * extends `WritableSignal`, whose private `[SIGNAL]` / `[ɵWRITABLE_SIGNAL]`
- * brands are precisely what make the Angular carrier truthful — and what make a
- * neutral cell correctly NOT assignable to it. Describing it structurally in the
- * kernel would be a lie, and importing Angular to describe it would keep
- * `@angular/core` in kernel declarations forever.
- */
+import type { Signal, WritableSignal } from '@angular/core';
 export interface AngularLeaf<T> extends WritableSignal<T> {
     (): T;
+    asReadonly(): Signal<T>;
 }
-/**
- * Register the carrier with the kernel's canonical registry.
- *
- * Declaration merging against the module that DECLARES `LeafCarriers`, so
- * `LeafOf<T,'angular'>` and `TreeNodeOf<T,'angular'>` resolve to `AngularLeaf`.
- * Augmenting a re-export would create a second, unused interface and silently
- * leave the real registry unchanged.
- */
 declare module '@signal-tree/kernel/adapter' {
     interface LeafCarriers<T> {
         angular: AngularLeaf<T>;
     }
+    interface ReadonlyLeafCarriers<T> {
+        angular: Signal<T>;
+    }
+    interface ReadonlyViewLeafCarriers<T> {
+        angular: Signal<T>;
+    }
 }

package/src/lib/define-store.d.ts

@@ -1,7 +1,5 @@
 import { type Type } from '@angular/core';
-import type { ISignalTreeOf, ReadonlyStoreOf, TreeNodeOf } from '@signal-tree/kernel/adapter';
-type ReadonlyStore<T, TAccum = TreeNodeOf<T, 'angular'>> = ReadonlyStoreOf<T, TAccum, 'angular'>;
-type AngularSignalTree<T, TAccum = TreeNodeOf<T, 'angular'>> = ISignalTreeOf<T, 'angular', TAccum>;
+import type { ISignalTreeOf, ReadonlyStoreOf } from '@signal-tree/kernel/adapter';
 /**
  * Config for {@link defineStore}.
  */
@@ -49,7 +47,7 @@ export interface DefineStoreConfig {
  *
  * @example
  * ```ts
- * import { signalTree, defineStore } from '@signal-tree/kernel';
+ * import { signalTree, defineStore } from '@signal-tree/angular';
  *
  * export const CounterStore = defineStore(() =>
  *   signalTree({ count: 0 })
@@ -64,7 +62,7 @@ export interface DefineStoreConfig {
  * @Component({ providers: [CounterStore] })
  * export class Counter {
  *   readonly store = inject(CounterStore);
- *   inc() { this.store.$.count.update((n) => n + 1); }
+ *   inc() { this.store.$.count((n) => n + 1); }
  * }
  * ```
  *
@@ -79,13 +77,13 @@ export interface DefineStoreConfig {
  * export class Display {
  *   readonly store = inject(CounterStore);
  *   read() { return this.store.$.count(); } // ✅ read-only
- *   // this.store.$.count.set(1);           // ❌ type error — not on ReadonlyStore
+ *   // this.store.$.count(1);               // ❌ type error — not on ReadonlyStore
  * }
  * ```
  */
-export declare function defineStore<T, A>(factory: () => AngularSignalTree<T, A>, config: DefineStoreConfig & {
+export declare function defineStore<T, A>(factory: () => ISignalTreeOf<T, 'angular', A>, config: DefineStoreConfig & {
     expose: 'readonly';
-}): Type<ReadonlyStore<T, A>>;
+}): Type<ReadonlyStoreOf<T, A, 'angular'>>;
 /**
  * Fallback overload. `expose?: undefined` means a config variable WIDENED to
  * {@link DefineStoreConfig} matches neither overload — pass a config object
@@ -95,4 +93,3 @@ export declare function defineStore<T, A>(factory: () => AngularSignalTree<T, A>
 export declare function defineStore<R>(factory: () => R, config?: DefineStoreConfig & {
     expose?: undefined;
 }): Type<R>;
-export {};

package/src/lib/observation-adapter.d.ts

@@ -0,0 +1,3 @@
+import type { ObservationAdapter } from '@signal-tree/kernel/adapter';
+/** Angular dependency tracking for kernel-owned locations. */
+export declare const ANGULAR_OBSERVATION_ADAPTER: ObservationAdapter;

package/src/lib/to-writable-signal.d.ts

@@ -1,25 +1,29 @@
 import { type WritableSignal } from '@angular/core';
-import type { NodeAccessor } from '@signal-tree/kernel';
+import type { Location, NodeAccessor } from '@signal-tree/kernel';
 /**
- * Converts a NodeAccessor (SignalTree slice or whole tree) into a WritableSignal
- * for use with any API that expects a `WritableSignal` — e.g. as an Angular
+ * Converts a writable SignalTree branch into a WritableSignal, or returns an
+ * Angular-native leaf unchanged, for use with any API that expects a
+ * `WritableSignal` — e.g. as an Angular
  * Signal Forms model, or the value fed to `SignalFormControl`. (Note: Angular
  * has no `FormControl.connect(signal)` API — see `signalForm()` for the
  * signal-native forms bridge.)
  *
- * Creates a two-way binding between the NodeAccessor and a WritableSignal:
+ * Branch adaptation creates a two-way binding between the NodeAccessor and a
+ * WritableSignal:
  * - Reads all leaf values from the NodeAccessor and exposes them as a signal
  * - Writes to the WritableSignal update the underlying NodeAccessor
  *
- * **Important**: This function uses `effect()` internally for synchronization, which requires
- * an injection context. It can be called in:
+ * **Important**: Branch adaptation and `{ undoable: true }` wrappers use
+ * `effect()` internally for synchronization, which requires an injection
+ * context. Passing an ordinary native leaf without options returns it directly
+ * and needs no injection context. This function can be called in:
  * - Component/directive/pipe class field initializers
  * - Component/directive/pipe constructors
  * - Functions called from within an injection context
  *
  * @template T - The type of the node value
- * @param node - The NodeAccessor to convert (can be a slice or whole tree)
- * @returns A WritableSignal that stays in sync with the NodeAccessor
+ * @param node - The branch accessor or writable leaf to expose
+ * @returns The native leaf or a WritableSignal synchronized with the branch
  *
  * @example
  * ```typescript
@@ -30,11 +34,11 @@ import type { NodeAccessor } from '@signal-tree/kernel';
  * // Convert a slice to a WritableSignal (e.g. a Signal Forms model)
  * const userSignal = toWritableSignal(tree.$.user);
  *
- * // Leaves are already WritableSignal - no conversion needed
- * const nameSignal = tree.$.user.name; // ✅ Already a WritableSignal
+ * // A leaf is already native; this returns the same object.
+ * const nameSignal = toWritableSignal(tree.$.user.name);
  * ```
  */
-export declare function toWritableSignal<T>(node: NodeAccessor<T>, injector?: unknown, options?: {
+export declare function toWritableSignal<T>(node: NodeAccessor<T> | Location<T> | WritableSignal<T>, injector?: unknown, options?: {
     /**
      * Mark writes ENTERING through this adapter as designating their authored
      * causal turn undoable — the same designation {@link undoable} applies, for

package/dist/lib/angular-realization.js

@@ -1 +0,0 @@
-import{signal,computed,untracked,isSignal}from"@angular/core";import{ANGULAR_SCALAR_LEAF_REALIZATION}from"./scalar-leaf-realization.js";const ANGULAR_TREE_REALIZATION=Object.freeze({materialization:{isReactiveNode:node=>isSignal(node)},suppressTracking:fn=>untracked(fn),scalarLeaf:ANGULAR_SCALAR_LEAF_REALIZATION,derived:{createDerived:compute=>computed(compute)},cell:{createCell:(initial,equal)=>signal(initial,equal?{equal}:void 0)}});export{ANGULAR_TREE_REALIZATION};

package/dist/lib/scalar-leaf-realization.js

@@ -1 +0,0 @@
-import{linkedSignal,signal}from"@angular/core";const ANGULAR_SCALAR_LEAF_REALIZATION={createToken(){const token=signal(0);return{observe:()=>void token(),invalidate:()=>token.update(value=>value+1)}},createLeaf(compute){return linkedSignal(compute)},runInvalidationGroup(run){run()}};export{ANGULAR_SCALAR_LEAF_REALIZATION};

package/src/lib/angular-realization.d.ts

@@ -1,7 +0,0 @@
-import { type TreeRealization } from '@signal-tree/kernel/adapter';
-/**
- * Immutable Angular mechanisms captured by this package's bound tree factory.
- * Selection occurs at construction; tree-owned lazy allocation retains only
- * the capabilities it needs for that tree's lifetime.
- */
-export declare const ANGULAR_TREE_REALIZATION: TreeRealization;

package/src/lib/scalar-leaf-realization.d.ts

@@ -1,15 +0,0 @@
-import type { ScalarLeafRealization } from '@signal-tree/kernel/adapter';
-/**
- * The ANGULAR realization of scalar leaves. Framework mechanism only.
- *
- * SCALAR-REALIZATION-SEAM-0 = SR-A. What used to be a 200-line module owning
- * slot bookkeeping, publication rules, production accounting, membership
- * dormancy and reactivation is now this: a dependency token and a read-through
- * leaf. It imports NOTHING from the kernel but two type declarations — no
- * member-membership, no PhysicalCommitClock, no production stats, no physical
- * slot runtime, no position ids.
- *
- * That is the discriminator: a hypothetical `@signal-tree/fake-reactive` could
- * be written against this same contract with a counter and a closure.
- */
-export declare const ANGULAR_SCALAR_LEAF_REALIZATION: ScalarLeafRealization;