@sigrea/vue 0.4.0 → 0.6.0

package/README.md

@@ -33,7 +33,7 @@
 npm install @sigrea/vue @sigrea/core vue
 ```
 
-Requires Vue 3.4+ and Node.js 20 or later.
+Requires Vue 3.4+ and Node.js 24 or later.
 
 ## Quick Start
 
@@ -57,20 +57,36 @@ const value = useSignal(count);
 
 ```ts
 // CounterMolecule.ts
-import { molecule, signal } from "@sigrea/core";
+import { molecule, readonly, signal } from "@sigrea/core";
 
-export const CounterMolecule = molecule((props: { initialCount: number }) => {
+type CounterProps = {
+  initialCount: number;
+  initialStep: number;
+};
+
+export const CounterMolecule = molecule((props: CounterProps) => {
   const count = signal(props.initialCount);
+  const step = signal(props.initialStep);
 
-  const increment = () => {
-    count.value += 1;
-  };
+  function setStep(next: number) {
+    step.value = next;
+  }
+
+  function increment() {
+    count.value += step.value;
+  }
 
-  const reset = () => {
+  function reset() {
     count.value = props.initialCount;
-  };
+  }
 
-  return { count, increment, reset };
+  return {
+    count: readonly(count),
+    step: readonly(step),
+    setStep,
+    increment,
+    reset,
+  };
 });
 ```
 
@@ -80,16 +96,23 @@ export const CounterMolecule = molecule((props: { initialCount: number }) => {
 import { useMolecule, useSignal } from "@sigrea/vue";
 import { CounterMolecule } from "./CounterMolecule";
 
-const props = defineProps<{ initialCount: number }>();
-const counter = useMolecule(CounterMolecule, props);
-const value = useSignal(counter.count);
+const props = defineProps<{ initialCount: number; initialStep: number }>();
+
+const counter = useMolecule(CounterMolecule, {
+  initialCount: props.initialCount,
+  initialStep: props.initialStep,
+});
+
+const count = useSignal(counter.count);
+const step = useSignal(counter.step);
 </script>
 
 <template>
   <div>
-    <span>{{ value }}</span>
+    <span>{{ count }}</span>
     <button @click="counter.increment">Increment</button>
     <button @click="counter.reset">Reset</button>
+    <button @click="counter.setStep(step + 1)">Step +</button>
   </div>
 </template>
 ```
@@ -122,7 +145,7 @@ const model = useMutableSignal(count);
 import { deepSignal } from "@sigrea/core";
 import { useDeepSignal } from "@sigrea/vue";
 
-const profile = deepSignal({ name: "Sigrea" });
+const profile = deepSignal({ name: "Mendako" });
 const model = useDeepSignal(profile);
 </script>
 
@@ -140,11 +163,11 @@ const model = useDeepSignal(profile);
 
 ```ts
 function useSignal<T>(
-  signal: Signal<T> | ReadonlySignal<T>
+  signal: Signal<T> | ReadonlySignal<T> | Computed<T>
 ): DeepReadonly<ShallowRef<T>>
 ```
 
-Subscribes to a signal or computed value and returns a readonly Vue ref that updates when the signal changes. The subscription is cleaned up when the component unmounts.
+Subscribes to a signal or computed value and returns a readonly Vue ref that updates when the signal changes. The subscription is cleaned up when the component unmounts, or after server rendering, including any `onServerPrefetch()` work, completes.
 
 ### useComputed
 
@@ -152,7 +175,7 @@ Subscribes to a signal or computed value and returns a readonly Vue ref that upd
 function useComputed<T>(source: Computed<T>): DeepReadonly<ShallowRef<T>>
 ```
 
-Subscribes to a computed value and returns a readonly Vue ref that updates when the computed value changes. The subscription is cleaned up when the component unmounts.
+Subscribes to a computed value and returns a readonly Vue ref that updates when the computed value changes. The subscription is cleaned up when the component unmounts, or after server rendering, including any `onServerPrefetch()` work, completes.
 
 ### useDeepSignal
 
@@ -160,7 +183,7 @@ Subscribes to a computed value and returns a readonly Vue ref that updates when
 function useDeepSignal<T extends object>(signal: DeepSignal<T>): ShallowRef<T>
 ```
 
-Subscribes to a deep signal and returns a mutable Vue ref. Updates to the deep signal trigger reactivity, and the subscription is cleaned up when the component unmounts. Templates unwrap the ref automatically, so accessing nested properties requires no `.value`. In script blocks, use `state.value` to access the underlying object.
+Subscribes to a deep signal and returns a mutable Vue ref. Updates to the deep signal trigger reactivity, and the subscription is cleaned up when the component unmounts, or after server rendering, including any `onServerPrefetch()` work, completes. Templates unwrap the ref automatically, so accessing nested properties requires no `.value`. In script blocks, use `state.value` to access the underlying object.
 
 ### useMutableSignal
 
@@ -173,7 +196,7 @@ Wraps a Sigrea signal as a Vue `WritableComputedRef` for two-way bindings like `
 ### useMolecule
 
 ```ts
-function useMolecule<TReturn extends object, TProps = void>(
+function useMolecule<TReturn extends object, TProps extends object | void = void>(
   molecule: MoleculeFactory<TReturn, TProps>,
   ...args: MoleculeArgs<TProps>
 ): MoleculeInstance<TReturn>
@@ -181,6 +204,24 @@ function useMolecule<TReturn extends object, TProps = void>(
 
 Mounts a molecule factory and returns its MoleculeInstance. Sigrea augments the molecule with lifecycle metadata: `onMount` callbacks run after the component mounts, and `onUnmount` callbacks run before it unmounts.
 
+**Server Rendering**
+
+During server rendering, `useMolecule` creates the molecule instance for the render pass but does not mount it. `onMount`, `watch`, `watchEffect`, `onActivated`, and `onDeactivated` do not run on the server. Unmounted instances created during SSR are disposed automatically in a microtask after server rendering, including any `onServerPrefetch()` work, completes.
+
+**KeepAlive Support**
+
+When used inside Vue's `<KeepAlive>`, molecule side effects are automatically managed for optimal resource efficiency:
+
+- **On deactivation** (`onDeactivated`): `watch` effects and ongoing work are paused via `unmountMolecule`. The molecule instance itself remains alive, preserving its internal state.
+- **On reactivation** (`onActivated`): Side effects resume via `mountMolecule`, allowing watches and subscriptions to pick up where they left off.
+- **On final unmount**: The molecule is fully disposed via `disposeMolecule`, releasing all resources.
+
+This design prevents unnecessary computation and subscriptions while components are cached but invisible, reducing CPU and memory usage without losing state.
+
+**Props Handling**
+
+Props are treated as an initial snapshot. Updating component props does not recreate the molecule instance or update the snapshot; model dynamic values via signals or explicit molecule methods (for example, `setStep`).
+
 ## Testing
 
 ```ts
@@ -227,7 +268,7 @@ createApp(App).mount("#app");
 
 ## Development
 
-This repo targets Node.js 20 or later.
+This repo targets Node.js 24 or later.
 
 If you use mise:
 

package/dist/index.cjs

@@ -3,15 +3,145 @@
 const vue = require('vue');
 const core = require('@sigrea/core');
 
+const IS_SERVER = typeof window === "undefined";
+const cleanupStates = /* @__PURE__ */ new WeakMap();
+const wrappedSsrRenderComponents = /* @__PURE__ */ new WeakSet();
+function getCleanupState(instance) {
+  const existing = cleanupStates.get(instance);
+  if (existing !== void 0) {
+    return existing;
+  }
+  const state = {
+    cleanups: [],
+    registered: false,
+    renderWrapped: false,
+    flushed: false
+  };
+  cleanupStates.set(instance, state);
+  return state;
+}
+function flushSsrCleanups(instance, state) {
+  if (state.flushed) {
+    return;
+  }
+  state.flushed = true;
+  cleanupStates.delete(instance);
+  const errors = [];
+  const cleanups = state.cleanups.splice(0);
+  for (const cleanup of cleanups) {
+    try {
+      cleanup();
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length === 1) {
+    throw errors[0];
+  }
+  if (errors.length > 1) {
+    throw new AggregateError(errors, "Failed to run SSR cleanups.");
+  }
+}
+function queueSsrCleanup(instance, state) {
+  queueMicrotask(() => {
+    flushSsrCleanups(instance, state);
+  });
+}
+function wrapInstanceRender(instance, state) {
+  if (state.renderWrapped || state.flushed) {
+    return;
+  }
+  const renderInstance = instance;
+  const render = renderInstance.render;
+  if (typeof render !== "function") {
+    return;
+  }
+  state.renderWrapped = true;
+  renderInstance.render = ((...args) => {
+    try {
+      return render(...args);
+    } finally {
+      queueSsrCleanup(instance, state);
+    }
+  });
+}
+function wrapComponentSsrRender(component) {
+  if (wrappedSsrRenderComponents.has(component)) {
+    return;
+  }
+  const ssrRender = component.ssrRender;
+  if (typeof ssrRender !== "function") {
+    return;
+  }
+  wrappedSsrRenderComponents.add(component);
+  component.ssrRender = ((...args) => {
+    const instance = vue.getCurrentInstance();
+    const state = instance === null ? void 0 : cleanupStates.get(instance);
+    try {
+      return ssrRender(...args);
+    } finally {
+      if (instance !== null && state !== void 0) {
+        queueSsrCleanup(instance, state);
+      }
+    }
+  });
+}
+function registerSsrCleanup(cleanup) {
+  if (!IS_SERVER) {
+    return;
+  }
+  const instance = vue.getCurrentInstance();
+  if (instance === null) {
+    return;
+  }
+  const state = getCleanupState(instance);
+  state.cleanups.push(cleanup);
+  if (state.registered) {
+    return;
+  }
+  state.registered = true;
+  vue.onServerPrefetch(() => {
+    wrapInstanceRender(instance, state);
+    wrapComponentSsrRender(instance.type);
+  });
+}
+
 function useMolecule(molecule, ...args) {
   if (vue.getCurrentInstance() === null) {
     throw new Error(
       "useMolecule can only be used within a Vue component setup()."
     );
   }
-  const instance = molecule(...args);
-  vue.onScopeDispose(() => {
+  const props = args.length === 0 ? void 0 : args[0];
+  if (props !== void 0 && (typeof props !== "object" || props === null)) {
+    throw new TypeError("useMolecule props must be an object.");
+  }
+  const snapshot = props === void 0 ? void 0 : { ...vue.toRaw(props) };
+  const moleculeArgs = snapshot === void 0 ? [] : [snapshot];
+  const instance = molecule(...moleculeArgs);
+  const disposeState = { disposed: false };
+  const dispose = () => {
+    if (disposeState.disposed) {
+      return;
+    }
+    disposeState.disposed = true;
     core.disposeMolecule(instance);
+  };
+  registerSsrCleanup(dispose);
+  vue.onMounted(() => {
+    core.mountMolecule(instance);
+  });
+  vue.onActivated(() => {
+    core.mountMolecule(instance);
+  });
+  vue.onDeactivated(() => {
+    core.unmountMolecule(instance);
+  });
+  vue.onBeforeUnmount(() => {
+    core.unmountMolecule(instance);
+  });
+  vue.onScopeDispose(() => {
+    dispose();
   });
   return instance;
 }
@@ -32,8 +162,17 @@ function useSnapshot(handler, options) {
     vue.triggerRef(state);
   };
   const unsubscribe = handler.subscribe(update);
-  vue.onScopeDispose(() => {
+  const unsubscribeState = { active: true };
+  const cleanup = () => {
+    if (!unsubscribeState.active) {
+      return;
+    }
+    unsubscribeState.active = false;
     unsubscribe();
+  };
+  registerSsrCleanup(cleanup);
+  vue.onScopeDispose(() => {
+    cleanup();
   });
   if (options?.mode === "mutable") {
     return state;

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal
 import * as vue from 'vue';
 import { DeepReadonly, ShallowRef } from 'vue';
 
-declare function useMolecule<TReturn extends object, TProps = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
+declare function useMolecule<TReturn extends object, TProps extends object | void = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
 
 type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
 declare function useSignal<T>(source: ReadableSignal<T>): Readonly<vue.Ref<vue.DeepReadonly<T>, vue.DeepReadonly<T>>>;

package/dist/index.d.mts

@@ -2,7 +2,7 @@ import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal
 import * as vue from 'vue';
 import { DeepReadonly, ShallowRef } from 'vue';
 
-declare function useMolecule<TReturn extends object, TProps = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
+declare function useMolecule<TReturn extends object, TProps extends object | void = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
 
 type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
 declare function useSignal<T>(source: ReadableSignal<T>): Readonly<vue.Ref<vue.DeepReadonly<T>, vue.DeepReadonly<T>>>;

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { MoleculeFactory, MoleculeArgs, MoleculeInstance, Signal, ReadonlySignal
 import * as vue from 'vue';
 import { DeepReadonly, ShallowRef } from 'vue';
 
-declare function useMolecule<TReturn extends object, TProps = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
+declare function useMolecule<TReturn extends object, TProps extends object | void = void>(molecule: MoleculeFactory<TReturn, TProps>, ...args: MoleculeArgs<TProps>): MoleculeInstance<TReturn>;
 
 type ReadableSignal<T> = Signal<T> | ReadonlySignal<T>;
 declare function useSignal<T>(source: ReadableSignal<T>): Readonly<vue.Ref<vue.DeepReadonly<T>, vue.DeepReadonly<T>>>;

package/dist/index.mjs

@@ -1,5 +1,108 @@
-import { getCurrentInstance, onScopeDispose, shallowRef, readonly, triggerRef, computed } from 'vue';
-import { disposeMolecule, createSignalHandler, createComputedHandler, createDeepSignalHandler } from '@sigrea/core';
+import { getCurrentInstance, onServerPrefetch, toRaw, onMounted, onActivated, onDeactivated, onBeforeUnmount, onScopeDispose, shallowRef, readonly, triggerRef, computed } from 'vue';
+import { mountMolecule, unmountMolecule, disposeMolecule, createSignalHandler, createComputedHandler, createDeepSignalHandler } from '@sigrea/core';
+
+const IS_SERVER = typeof window === "undefined";
+const cleanupStates = /* @__PURE__ */ new WeakMap();
+const wrappedSsrRenderComponents = /* @__PURE__ */ new WeakSet();
+function getCleanupState(instance) {
+  const existing = cleanupStates.get(instance);
+  if (existing !== void 0) {
+    return existing;
+  }
+  const state = {
+    cleanups: [],
+    registered: false,
+    renderWrapped: false,
+    flushed: false
+  };
+  cleanupStates.set(instance, state);
+  return state;
+}
+function flushSsrCleanups(instance, state) {
+  if (state.flushed) {
+    return;
+  }
+  state.flushed = true;
+  cleanupStates.delete(instance);
+  const errors = [];
+  const cleanups = state.cleanups.splice(0);
+  for (const cleanup of cleanups) {
+    try {
+      cleanup();
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length === 1) {
+    throw errors[0];
+  }
+  if (errors.length > 1) {
+    throw new AggregateError(errors, "Failed to run SSR cleanups.");
+  }
+}
+function queueSsrCleanup(instance, state) {
+  queueMicrotask(() => {
+    flushSsrCleanups(instance, state);
+  });
+}
+function wrapInstanceRender(instance, state) {
+  if (state.renderWrapped || state.flushed) {
+    return;
+  }
+  const renderInstance = instance;
+  const render = renderInstance.render;
+  if (typeof render !== "function") {
+    return;
+  }
+  state.renderWrapped = true;
+  renderInstance.render = ((...args) => {
+    try {
+      return render(...args);
+    } finally {
+      queueSsrCleanup(instance, state);
+    }
+  });
+}
+function wrapComponentSsrRender(component) {
+  if (wrappedSsrRenderComponents.has(component)) {
+    return;
+  }
+  const ssrRender = component.ssrRender;
+  if (typeof ssrRender !== "function") {
+    return;
+  }
+  wrappedSsrRenderComponents.add(component);
+  component.ssrRender = ((...args) => {
+    const instance = getCurrentInstance();
+    const state = instance === null ? void 0 : cleanupStates.get(instance);
+    try {
+      return ssrRender(...args);
+    } finally {
+      if (instance !== null && state !== void 0) {
+        queueSsrCleanup(instance, state);
+      }
+    }
+  });
+}
+function registerSsrCleanup(cleanup) {
+  if (!IS_SERVER) {
+    return;
+  }
+  const instance = getCurrentInstance();
+  if (instance === null) {
+    return;
+  }
+  const state = getCleanupState(instance);
+  state.cleanups.push(cleanup);
+  if (state.registered) {
+    return;
+  }
+  state.registered = true;
+  onServerPrefetch(() => {
+    wrapInstanceRender(instance, state);
+    wrapComponentSsrRender(instance.type);
+  });
+}
 
 function useMolecule(molecule, ...args) {
   if (getCurrentInstance() === null) {
@@ -7,9 +110,36 @@ function useMolecule(molecule, ...args) {
       "useMolecule can only be used within a Vue component setup()."
     );
   }
-  const instance = molecule(...args);
-  onScopeDispose(() => {
+  const props = args.length === 0 ? void 0 : args[0];
+  if (props !== void 0 && (typeof props !== "object" || props === null)) {
+    throw new TypeError("useMolecule props must be an object.");
+  }
+  const snapshot = props === void 0 ? void 0 : { ...toRaw(props) };
+  const moleculeArgs = snapshot === void 0 ? [] : [snapshot];
+  const instance = molecule(...moleculeArgs);
+  const disposeState = { disposed: false };
+  const dispose = () => {
+    if (disposeState.disposed) {
+      return;
+    }
+    disposeState.disposed = true;
     disposeMolecule(instance);
+  };
+  registerSsrCleanup(dispose);
+  onMounted(() => {
+    mountMolecule(instance);
+  });
+  onActivated(() => {
+    mountMolecule(instance);
+  });
+  onDeactivated(() => {
+    unmountMolecule(instance);
+  });
+  onBeforeUnmount(() => {
+    unmountMolecule(instance);
+  });
+  onScopeDispose(() => {
+    dispose();
   });
   return instance;
 }
@@ -30,8 +160,17 @@ function useSnapshot(handler, options) {
     triggerRef(state);
   };
   const unsubscribe = handler.subscribe(update);
-  onScopeDispose(() => {
+  const unsubscribeState = { active: true };
+  const cleanup = () => {
+    if (!unsubscribeState.active) {
+      return;
+    }
+    unsubscribeState.active = false;
     unsubscribe();
+  };
+  registerSsrCleanup(cleanup);
+  onScopeDispose(() => {
+    cleanup();
   });
   if (options?.mode === "mutable") {
     return state;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sigrea/vue",
-	"version": "0.4.0",
+	"version": "0.6.0",
 	"description": "Vue adapter bindings for Sigrea molecule modules.",
 	"license": "MIT",
 	"type": "module",
@@ -17,7 +17,7 @@
 		"url": "https://github.com/sigrea/vue/issues"
 	},
 	"engines": {
-		"node": ">=20"
+		"node": ">=24"
 	},
 	"sideEffects": false,
 	"exports": {
@@ -29,16 +29,8 @@
 	},
 	"main": "./dist/index.cjs",
 	"types": "./dist/index.d.ts",
-	"files": [
-		"dist"
-	],
-	"keywords": [
-		"signals",
-		"reactivity",
-		"vue",
-		"molecule",
-		"typescript"
-	],
+	"files": ["dist"],
+	"keywords": ["signals", "reactivity", "vue", "molecule", "typescript"],
 	"scripts": {
 		"dev": "vite --config playground/vite.config.ts",
 		"build": "unbuild",
@@ -53,28 +45,27 @@
 		"cicheck": "pnpm test && pnpm typecheck && pnpm format:fix"
 	},
 	"peerDependencies": {
-		"@sigrea/core": "^0.4.3",
+		"@sigrea/core": "^0.6.0",
 		"vue": "^3.4.0"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "1.9.4",
+		"@sigrea/core": "^0.6.0",
 		"@vitejs/plugin-vue": "^5.1.4",
-		"@vue/test-utils": "^2.4.0",
 		"@vitest/coverage-v8": "^3.2.4",
+		"@vue/test-utils": "^2.4.0",
+		"baseline-browser-mapping": "^2.9.13",
 		"changelogen": "^0.6.2",
+		"jsdom": "^24.1.3",
 		"lefthook": "1.13.6",
 		"tsx": "^4.20.5",
 		"typescript": "5.9.3",
 		"unbuild": "3.6.1",
 		"vite": "^5.4.6",
 		"vitest": "^3.2.4",
-		"vue": "^3.4.0",
-		"jsdom": "^24.1.3"
+		"vue": "^3.4.0"
 	},
 	"pnpm": {
-		"onlyBuiltDependencies": [
-			"lefthook",
-			"@biomejs/biome"
-		]
+		"onlyBuiltDependencies": ["lefthook", "@biomejs/biome"]
 	}
 }