@signal-tree/vue 15.1.1 → 15.1.3

package/README.md

@@ -35,3 +35,62 @@ console.log(tree.$.greeting.value); // Hello, Grace
 The ref can be passed directly to `watch()`, `computed()`, or `v-model`.
 Object branches and the root `$` remain callable whole-value accessors. Vue owns
 dependency tracking; the kernel remains the only state and write authority.
+
+## Initial values and external reactivity
+
+Pass plain initial values to `signalTree()`. Existing Vue refs, computed refs,
+and reactive or readonly proxies at the root or a nested branch are rejected
+with a path-specific error. Ref types are also rejected by TypeScript; proxies
+require runtime checks because their types can look like ordinary objects.
+
+```ts
+import { ref } from 'vue';
+import { leaf, signalTree } from '@signal-tree/vue';
+
+const existing = ref(1);
+const tree = signalTree({ count: leaf(existing.value) });
+```
+
+This takes an independent scalar snapshot. For objects, copy the needed values
+into plain data; `toRaw()` alone shares the underlying object and is not an
+independent copy. `leaf(existing)` explicitly stores a ref or proxy as data.
+Its inner mutations remain outside tree transactions and restoration.
+
+Validation stops at explicit `leaf(...)`, marker definitions, arrays and built-in
+terminal values. Their contents remain data, not separately owned tree locations.
+Ordinary functions remain valid callable data. These checks apply to initial
+construction, not arbitrary later writes or foreign reactivity from other libraries.
+
+## Ownership and disposal
+
+`signalTree()` constructs a tree; it does not register scope cleanup. A tree owns
+runtime resources until `destroy()` is called. Dropping its last reference is not
+prompt resource reclamation.
+
+For a component- or composable-owned tree, construct it inside the active Vue
+scope and register its disposal there:
+
+```ts
+import { onScopeDispose } from 'vue';
+import { signalTree } from '@signal-tree/vue';
+
+// Call synchronously during setup() or inside an active effectScope().
+function useCounter() {
+  const tree = signalTree({ count: 0 });
+  onScopeDispose(() => tree.destroy());
+  return tree;
+}
+```
+
+Stopping the owning scope destroys the tree. A component that receives a tree
+through props or `inject()` only borrows it: do not register destruction in that
+consumer's scope. Shared application stores belong to the application owner,
+which can use ordinary `provide()`/`inject()` to distribute them and call
+`destroy()` after unmounting the application.
+
+For SSR, construct a fresh tree for each request, provide it to that request's
+application, and destroy it in `finally` after awaited rendering finishes. Do not
+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.

package/dist/index.js

@@ -1 +1 @@
-import{asReadonly as asReadonly$1}from"@signal-tree/kernel";export*from"@signal-tree/kernel";import{createSignalTreeFactory}from"@signal-tree/kernel/adapter";import{createVueObservationAdapter}from"./lib/vue-observation.js";const signalTree=(initialState,config)=>createSignalTreeFactory(createVueObservationAdapter())(initialState,config);const asReadonly=asReadonly$1;export{asReadonly,signalTree};
+import{asReadonly as asReadonly$1}from"@signal-tree/kernel";export*from"@signal-tree/kernel";import{createSignalTreeFactory}from"@signal-tree/kernel/adapter";import{prepareConstructionInput}from"./lib/construction-input.js";import{createVueObservationAdapter}from"./lib/vue-observation.js";const signalTree=(initialState,config)=>createSignalTreeFactory(createVueObservationAdapter())(prepareConstructionInput(initialState),config);const asReadonly=asReadonly$1;export{asReadonly,signalTree};

package/dist/lib/construction-input.js

@@ -0,0 +1 @@
+import{isRef,isProxy}from"vue";import{isConstructionBranch}from"@signal-tree/kernel/adapter";function prepareConstructionInput(initialState){const branches=new WeakMap;const visit=(value,path)=>{if(isRef(value)||isProxy(value)){throw new TypeError(`SignalTree: Vue ref or proxy at ${path}. Pass plain initial values (copy ref.value into an independent snapshot). Use leaf(existing) only to store the reactive object as data; its writes remain external to the tree.`)}if(!isConstructionBranch(value))return value;const previous=branches.get(value);if(previous)return previous;const prepared=Object.create(null);branches.set(value,prepared);for(const key of Object.getOwnPropertySymbols(value)){const descriptor=Object.getOwnPropertyDescriptor(value,key);if(descriptor)Object.defineProperty(prepared,key,descriptor)}for(const[key,child]of Object.entries(value)){prepared[key]=key==="__proto__"?child:visit(child,`${path}[${JSON.stringify(key)}]`)}return prepared};return visit(initialState,"$")}export{prepareConstructionInput};

package/package.json

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

package/src/index.d.ts

@@ -6,9 +6,10 @@
  * @packageDocumentation
  */
 import './lib/carrier.js';
-import { type AccessibleNodeOf, type EntityNodeOf, type EntitySignalOf, type EntitySignalWithSlicesOf, type ISignalTreeOf, type LeafOf, type ReadonlyStoreOf, type ReadonlyViewOf, type SignalTreeFactoryOf, type TreeNodeOf } from '@signal-tree/kernel/adapter';
+import { type AccessibleNodeOf, type EntityNodeOf, type EntitySignalOf, type EntitySignalWithSlicesOf, type ISignalTreeOf, type LeafOf, type ReadonlyStoreOf, type ReadonlyViewOf, type TreeNodeOf } from '@signal-tree/kernel/adapter';
+import { type FrameworkSignalTreeFactory } from './lib/construction-input.js';
 /** Construct a SignalTree whose leaves are native Vue refs. */
-export declare const signalTree: SignalTreeFactoryOf<"vue">;
+export declare const signalTree: FrameworkSignalTreeFactory;
 export type TreeNode<T> = TreeNodeOf<T, 'vue'>;
 export type WritableLeaf<T> = LeafOf<T, 'vue'>;
 export type AccessibleNode<T> = AccessibleNodeOf<T, 'vue'>;

package/src/lib/construction-input.d.ts

@@ -0,0 +1,9 @@
+import { type Ref } from 'vue';
+import type { SignalTreeFactoryOf } from '@signal-tree/kernel/adapter';
+export type FrameworkSignalTreeFactory = SignalTreeFactoryOf<'vue', Ref<unknown>>;
+/**
+ * Read each branch property once, so accessor-backed definitions cannot change
+ * between validation and construction. Terminal data retains its identity.
+ * No reactive primitive is read, subscribed to, or adopted here.
+ */
+export declare function prepareConstructionInput(initialState: object): object;