nuxt-state 0.1.0 → 0.3.0

package/README.md

@@ -83,6 +83,62 @@ Different server requests and different client apps receive different objects.
 The returned object is not cloned, wrapped, or transformed. Refs remain refs, computed
 refs remain computed refs, reactive objects remain reactive, and functions are unchanged.
 
+## Nuxt Layers
+
+Reusable Nuxt Layers can provide states from their resolved application directory:
+
+```text
+layers/
+└── admin/
+    ├── nuxt.config.ts
+    └── app/
+        └── states/
+            └── permissions.ts
+```
+
+```ts
+// layers/admin/app/states/permissions.ts
+export const usePermissions = defineState(() => {
+  const roles = ref(['reader'])
+  return { roles }
+})
+```
+
+`usePermissions()` is auto-imported in the consuming application. Local auto-discovered layers,
+layers listed in `extends`, package-provided layers, nested state directories, hydration, and
+request isolation use the same behavior as project states.
+
+nuxt-state follows Nuxt's normal layer priority. The project wins over every extended layer;
+higher-priority layers win over lower-priority layers when exports collide. No aliases or custom
+override API are generated.
+
+## DevTools
+
+Enable Nuxt DevTools normally:
+
+```ts
+export default defineNuxtConfig({
+  devtools: {
+    enabled: true,
+  },
+})
+```
+
+In development, the **Nuxt State** tab provides a read-only inspector. It shows active state
+instances, internal hydration keys, Hydrated/Client-only status, member classifications, bounded
+value previews, and a separate list of statically discovered states with project-relative source
+and layer origin.
+
+Opening the panel never executes a state factory. Values are queried while the view is visible;
+there are no permanent deep watchers. Functions are descriptors and cannot be invoked, large
+values are truncated, and cyclic/shared graphs use reference markers. v0.3.0 does not support
+editing, patching, resetting, deleting, or disposing application state.
+
+Nuxt DevTools 3.4's stable iframe integration is used. No alpha/nightly override is required.
+Runtime hydration hashes cannot currently be mapped safely back to export names without another
+compiler transform, so active cards use `State $<internal-key>` while the separate Known states
+list shows names, sources, and layer origins. The internal key is debug information, not API.
+
 ## Semantics
 
 - The factory is synchronous and takes no arguments.
@@ -90,6 +146,8 @@ refs remain computed refs, reactive objects remain reactive, and functions are u
 - The factory is lazy and runs at first use.
 - It runs once per Nuxt app instance.
 - The exact factory result is returned to all callers in that app.
+- The factory runs in a detached Vue effect scope owned by the Nuxt app, so effects and Nuxt
+  composables are not disposed with the first consuming component.
 - A module-local `WeakMap` keys instances by `NuxtApp`, providing request isolation while
   allowing old application instances to be garbage-collected.
 - Separate `defineState()` calls have separate closure-owned caches, including calls in
@@ -102,9 +160,9 @@ Expose an async function from synchronous state or use Nuxt's data-fetching APIs
 
 ## SSR hydration
 
-v0.1.0 transparently hydrates mutable top-level members returned by the factory when they are
-created with `ref()` or `reactive()`. Nuxt injects an internal call-site key at build time; the
-developer-facing call remains exactly `defineState(factory)`.
+Since v0.1.0, nuxt-state transparently hydrates mutable top-level members returned by the factory.
+Nuxt injects an internal call-site key at build time; the developer-facing call remains exactly
+`defineState(factory)`.
 
 On the server, the module captures the final values after rendering in one namespaced Nuxt
 payload entry. On the client, it runs the factory normally and patches those values into the
@@ -128,27 +186,74 @@ payload serializer. Functions, readonly computed refs, and plain runtime objects
 by the factory rather than serialized. Concurrent SSR requests retain separate Nuxt-app
 registries and cannot share user state.
 
+Snapshot discovery is intentionally limited to mutable members exposed by the factory. Reactive
+state that must survive SSR hydration currently needs to be exposed from the `defineState`
+factory. A private ref captured only by a computed value or function is not visible to the
+snapshot layer; if it is mutated during SSR, its client value can differ and cause a hydration
+mismatch. Discovering closure-private Vue state would require a new explicit API, compiler-level
+analysis, or undocumented reactivity inspection, none of which belongs in v0.2.0.
+
 `useFetch()` can remain inside a synchronous state factory. Its request caching and payload
 hydration still belong to Nuxt; `nuxt-state` neither replaces nor triggers a second fetch
 mechanism. If multiple sibling SSR components must all render completed data, await the returned
 Nuxt `AsyncData` promise in a parent/page as you would with normal Nuxt data fetching.
 
+When a returned `useFetch().data` ref is snapshotted, both Nuxt's data payload and the internal
+state snapshot refer to it. Nuxt's graph serializer preserves the shared object identity, so the
+response body is emitted once rather than copied into the HTML twice. There is still a small
+snapshot-metadata overhead.
+
+## Compatibility
+
+### Supported
+
+- `ref()` and `reactive()`, including nested serializable objects and arrays;
+- `shallowRef()` and `shallowReactive()` with their shallow semantics preserved;
+- `Date`, `Map`, `Set`, shared references, and cyclic graphs supported by Nuxt's payload
+  serializer;
+- readonly computed chains and functions as client-recreated runtime state;
+- readonly views when their mutable source is also returned and hydrated;
+- `useFetch()`, `useAsyncData()`, `callOnce()`, `useCookie()`, `useRuntimeConfig()`, `useRoute()`,
+  and `useRouter()` in valid Nuxt contexts;
+- project, local, explicit-extends, and package-provided Nuxt Layer states with native priority;
+- first use from plugins, route middleware, layouts, pages, and components;
+- state lifetime across client navigation and repeated component mount/unmount.
+
+`useFetch` and `useAsyncData` continue to own their request/payload behavior. nuxt-state's
+snapshot metadata points at the same payload graph rather than serializing response bodies again.
+`callOnce({ mode: 'navigation' })` retains Nuxt's normal per-navigation behavior.
+
+### Characterized or limited
+
+- A readonly view is not independent mutable state. If its mutable source is private, it follows
+  the private-state limitation below.
+- Writable computed refs are not supported hydration state. Vue exposes no public `isComputed`
+  check, and a writable computed currently looks like a mutable ref; restoring it invokes its
+  setter and may cause side effects. Return and hydrate its source refs instead.
+- Mutable reactive values that must survive SSR hydration need to be reachable through the
+  enumerable object returned from the factory.
+- The intended return is a composable-style object. Arbitrary ref, reactive-root, function, or
+  primitive returns still share per app, but the current member-based snapshot format does not
+  hydrate them.
+- Cycles are supported for Nuxt-serializable object graphs, not arbitrary native resources or
+  custom class instances.
+
 ## Current limitations
 
 - Nuxt 4 and Vue 3 only.
 - Synchronous factories only.
 - No persistence or browser-storage integration.
-- Hydration is guaranteed for standard `ref()` and `reactive()` members only. Advanced
-  primitives such as shallow/custom refs and writable-computed edge cases are not v0.1.0
-  guarantees.
+- Hydration is guaranteed for standard and shallow refs/reactives. `customRef()` and writable
+  computed hydration are not supported.
 - Hydrated values must be serializable by Nuxt's payload system; DOM nodes, sockets, functions
   inside refs, symbols, and arbitrary native/class resources are unsupported.
-- No Nuxt Layers support yet.
+- Closure-private mutable state is not discoverable; return any ref/reactive value whose SSR
+  mutations must hydrate.
 - State resets when its module is hot-reloaded; HMR preservation is not implemented.
-- Compatibility with every context-sensitive Nuxt composable inside a factory is not
-  guaranteed yet.
-- There is no reset API, keyed/multi-instance state, DevTools integration, or central
-  user-facing registry.
+- Context-sensitive composables must still be called while normal Nuxt context is available.
+- DevTools is read-only and development-only. Active hashes are not safely correlated with
+  static export names; there is no public or process-global state registry.
+- There is no reset API or keyed/multi-instance state.
 - The keyed transform is source-sensitive. The supported path is the module's auto-imported
   `defineState`; a barrel re-export or unrelated manual wrapper is not guaranteed to receive an
   internal hydration key.
@@ -167,6 +272,7 @@ pnpm fmt:check
 pnpm lint
 pnpm test:types
 pnpm test
+pnpm test:stress
 pnpm prepack
 pnpm dev:build
 ```

package/dist/module.json

@@ -4,7 +4,7 @@
     "nuxt": "^4.0.0"
   },
   "configKey": "nuxt-state",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,5 +1,22 @@
-import { resolve } from 'node:path';
-import { defineNuxtModule, createResolver, addImports, addPlugin, addImportsDir } from '@nuxt/kit';
+import { resolve, sep, relative, basename } from 'node:path';
+import { defineNuxtModule, createResolver, addImports, addPlugin, getLayerDirectories, addTemplate, addDevServerHandler, addImportsDir } from '@nuxt/kit';
+import { addCustomTab } from '@nuxt/devtools-kit';
+
+function registerDevtools(route, nuxt) {
+  addCustomTab(
+    {
+      name: "nuxt-state",
+      title: "Nuxt State",
+      icon: "carbon:data-vis-4",
+      category: "app",
+      view: {
+        type: "iframe",
+        src: route
+      }
+    },
+    nuxt
+  );
+}
 
 const module$1 = defineNuxtModule({
   meta: {
@@ -22,8 +39,147 @@ const module$1 = defineNuxtModule({
       argumentLength: 2
     });
     addPlugin(resolver.resolve("./runtime/app/plugins/hydration"));
-    addImportsDir(resolve(nuxt.options.srcDir, "states/**"));
+    const devtools = nuxt.options.devtools;
+    const devtoolsEnabled = nuxt.options.dev && devtools !== false && !(typeof devtools === "object" && devtools.enabled === false);
+    const layers = getLayerDirectories(nuxt);
+    const stateDirectories = layers.map((layer) => resolve(layer.app, "states"));
+    if (devtoolsEnabled) {
+      const devtoolsRoute = "/__nuxt_state_devtools__/";
+      let knownStates = [];
+      nuxt.hook("imports:extend", (imports) => {
+        const winners = /* @__PURE__ */ new Map();
+        for (const item of imports) {
+          const layerIndex = stateDirectories.findIndex(
+            (directory) => item.from === directory || item.from.startsWith(`${directory}${sep}`)
+          );
+          const name = item.as || item.name;
+          if (layerIndex < 0 || winners.has(name)) continue;
+          const layer = layers[layerIndex];
+          const projectRelative = relative(nuxt.options.rootDir, item.from);
+          const source = projectRelative.startsWith("..") ? basename(item.from) : projectRelative;
+          const layerRelative = relative(nuxt.options.rootDir, layer.root).replace(/\/$/, "");
+          winners.set(name, {
+            name,
+            source,
+            origin: layerIndex === 0 ? "Project" : layerRelative || basename(layer.root)
+          });
+        }
+        knownStates = [...winners.values()].sort((a, b) => a.name.localeCompare(b.name));
+      });
+      addTemplate({
+        filename: "nuxt-state/metadata.mjs",
+        getContents: () => `export default ${JSON.stringify(knownStates)}`
+      });
+      registerDevtools(devtoolsRoute, nuxt);
+      addPlugin(resolver.resolve("./runtime/app/plugins/devtools.client"));
+      addDevServerHandler({
+        route: devtoolsRoute,
+        handler(event) {
+          event.node.res.setHeader("content-type", "text/html; charset=utf-8");
+          return renderDevtoolsView();
+        }
+      });
+    }
+    addImportsDir(layers.map((layer) => resolve(layer.app, "states/**")));
   }
 });
+function renderDevtoolsView() {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>Nuxt State</title>
+  <style>
+    :root { color-scheme: light dark; font: 14px/1.5 ui-sans-serif, system-ui, sans-serif; }
+    * { box-sizing: border-box; }
+    body { margin: 0; color: #d9e1ea; background: #101418; }
+    header { position: sticky; top: 0; z-index: 1; display: flex; gap: 12px; align-items: center; padding: 14px 18px; border-bottom: 1px solid #2a343e; background: #101418ee; }
+    h1 { margin: 0 auto 0 0; font-size: 18px; }
+    input, button { border: 1px solid #34414d; border-radius: 7px; background: #182027; color: inherit; padding: 7px 10px; }
+    input { width: min(280px, 42vw); }
+    button { cursor: pointer; }
+    main { display: grid; gap: 12px; padding: 16px; }
+    article { border: 1px solid #2a343e; border-radius: 10px; background: #151b21; overflow: hidden; }
+    article > div { padding: 12px 14px; }
+    h2 { margin: 0; font-size: 15px; }
+    .meta { color: #94a3b1; font-size: 12px; overflow-wrap: anywhere; }
+    table { width: 100%; border-collapse: collapse; }
+    th, td { padding: 8px 14px; border-top: 1px solid #27313a; text-align: left; vertical-align: top; }
+    th { color: #91a0ad; font-size: 11px; text-transform: uppercase; }
+    td:nth-child(1) { width: 22%; font-weight: 600; }
+    td:nth-child(2) { width: 16%; color: #65d8a5; }
+    pre { margin: 0; white-space: pre-wrap; overflow-wrap: anywhere; font: 12px/1.45 ui-monospace, monospace; }
+    .empty, .error { padding: 36px; text-align: center; color: #91a0ad; }
+    .badge { display: inline-block; margin-left: 7px; padding: 1px 6px; border-radius: 999px; background: #263a32; color: #7ee2ad; font-size: 11px; }
+    @media (prefers-color-scheme: light) {
+      body { color: #202832; background: #f7f9fb; }
+      header { border-color: #d9e0e6; background: #f7f9fbee; }
+      input, button, article { border-color: #d7dfe6; background: white; }
+      th, td { border-color: #e3e8ed; }
+      .badge { background: #dff7ea; color: #176b43; }
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>Nuxt State <span class="badge">Read only</span></h1>
+    <input id="filter" type="search" placeholder="Filter active states">
+    <button id="refresh" type="button">Refresh</button>
+  </header>
+  <main id="states"><p class="empty">Connecting to the Nuxt app\u2026</p></main>
+  <script>
+    const root = document.querySelector('#states')
+    const filter = document.querySelector('#filter')
+    let activeStates = []
+    let knownStates = []
+    let timer
+    let visible = true
+    let refreshing = false
+
+    const escapeHTML = value => String(value).replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char])
+    const render = () => {
+      const query = filter.value.trim().toLowerCase()
+      const shown = activeStates.filter(state => (state.name + ' ' + state.key).toLowerCase().includes(query))
+      const known = knownStates.filter(state => (state.name + ' ' + state.source + ' ' + state.origin).toLowerCase().includes(query))
+      const activeHTML = shown.length
+        ? shown.map(state => '<article><div><h2>' + escapeHTML(state.name) + '<span class="badge">' + escapeHTML(state.hydration) + '</span></h2><div class="meta">Internal hydration key: ' + escapeHTML(state.key) + '</div></div><table><thead><tr><th>Member</th><th>Kind</th><th>Value preview</th></tr></thead><tbody>' + state.members.map(member => '<tr><td>' + escapeHTML(member.name) + '</td><td>' + escapeHTML(member.kind) + '</td><td><pre>' + escapeHTML(JSON.stringify(member.value, null, 2)) + '</pre></td></tr>').join('') + '</tbody></table></article>').join('')
+        : '<p class="empty">' + (activeStates.length ? 'No matching active states.' : 'No active states yet. Opening this panel does not instantiate lazy state.') + '</p>'
+      const knownHTML = known.length
+        ? '<article><div><h2>Known states</h2><div class="meta">Discovered statically; factories remain lazy.</div></div><table><thead><tr><th>Name</th><th>Origin</th><th>Source</th></tr></thead><tbody>' + known.map(state => '<tr><td>' + escapeHTML(state.name) + '</td><td>' + escapeHTML(state.origin) + '</td><td><pre>' + escapeHTML(state.source) + '</pre></td></tr>').join('') + '</tbody></table></article>'
+        : ''
+      root.innerHTML = activeHTML + knownHTML
+    }
+    const refresh = async () => {
+      if (!visible || refreshing) return
+      refreshing = true
+      try {
+        const client = window.__NUXT_DEVTOOLS__
+        if (!client?.host?.nuxt) throw new Error('Nuxt DevTools host is not connected.')
+        const request = { result: undefined }
+        await client.host.nuxt.callHook('nuxt-state:inspect', request)
+        activeStates = request.result?.active || []
+        knownStates = request.result?.known || []
+        render()
+      } catch (error) {
+        root.innerHTML = '<p class="error">' + escapeHTML(error?.message || error) + '</p>'
+      } finally {
+        refreshing = false
+      }
+    }
+    const observer = new IntersectionObserver(entries => {
+      visible = entries.some(entry => entry.isIntersecting)
+      if (visible) refresh()
+    })
+    observer.observe(document.documentElement)
+    filter.addEventListener('input', render)
+    document.querySelector('#refresh').addEventListener('click', refresh)
+    timer = setInterval(refresh, 1000)
+    addEventListener('pagehide', () => { clearInterval(timer); observer.disconnect() }, { once: true })
+    refresh()
+  <\/script>
+</body>
+</html>`;
+}
 
 export { module$1 as default };

package/dist/runtime/app/composables/defineState.js

@@ -1,4 +1,5 @@
 import { useNuxtApp } from "#app";
+import { effectScope } from "vue";
 import { registerHydratableState } from "../state-registry.js";
 import { restoreState, snapshotState } from "../state-snapshot.js";
 function isPromiseLike(value) {
@@ -11,18 +12,41 @@ export function defineState(factory, internalKey) {
     if (instances.has(nuxtApp)) {
       return instances.get(nuxtApp);
     }
-    const instance = factory();
+    const scope = effectScope(true);
+    let instance;
+    try {
+      instance = scope.run(factory);
+    } catch (error) {
+      scope.stop();
+      throw error;
+    }
     if (isPromiseLike(instance)) {
+      scope.stop();
       throw new TypeError(
         "[nuxt-state] State factories must be synchronous. Expose an async function from the state or use Nuxt data-fetching composables instead."
       );
     }
     instances.set(nuxtApp, instance);
+    const app = nuxtApp;
+    app.vueApp?.onUnmount?.(() => scope.stop());
     if (internalKey) {
-      registerHydratableState(nuxtApp, internalKey, {
+      const entry = {
         snapshot: () => snapshotState(instance),
-        restore: (snapshot) => restoreState(instance, snapshot)
-      });
+        restore: (snapshot) => restoreState(instance, snapshot),
+        dispose: () => scope.stop()
+      };
+      if (import.meta.dev) {
+        entry.debug = {
+          state: instance,
+          hydration: import.meta.server ? "Server" : "Client-only"
+        };
+        const restore = entry.restore;
+        entry.restore = (snapshot) => {
+          restore(snapshot);
+          entry.debug.hydration = "Hydrated";
+        };
+      }
+      registerHydratableState(nuxtApp, internalKey, entry);
     }
     return instance;
   };

package/dist/runtime/app/devtools-metadata.d.ts

@@ -0,0 +1,4 @@
+declare module '#build/nuxt-state/metadata' {
+  const states: Array<{ name: string; source: string; origin: string }>
+  export default states
+}

package/dist/runtime/app/plugins/devtools.client.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/app/plugins/devtools.client.js

@@ -0,0 +1,17 @@
+import { defineNuxtPlugin } from "#app";
+import knownStates from "#build/nuxt-state/metadata";
+import { inspectActiveStates } from "../state-inspector.js";
+export default defineNuxtPlugin({
+  name: "nuxt-state:devtools",
+  setup(nuxtApp) {
+    nuxtApp.hook(
+      "nuxt-state:inspect",
+      ((request) => {
+        request.result = {
+          active: inspectActiveStates(nuxtApp),
+          known: knownStates
+        };
+      })
+    );
+  }
+});

package/dist/runtime/app/plugins/hydration.js

@@ -1,5 +1,6 @@
 import { defineNuxtPlugin, useHydration } from "#app";
 import {
+  clearPendingStateSnapshots,
   collectStateSnapshots,
   receiveStateSnapshots
 } from "../state-registry.js";
@@ -10,4 +11,7 @@ export default defineNuxtPlugin((nuxtApp) => {
     () => collectStateSnapshots(nuxtApp),
     (snapshots) => receiveStateSnapshots(nuxtApp, snapshots)
   );
+  if (import.meta.client) {
+    nuxtApp.hook("app:mounted", () => clearPendingStateSnapshots(nuxtApp));
+  }
 });

package/dist/runtime/app/state-inspector.d.ts

@@ -0,0 +1,16 @@
+export interface StateInspectorMember {
+    name: string;
+    kind: string;
+    value: unknown;
+}
+export interface StateInspectorEntry {
+    key: string;
+    name: string;
+    source?: string;
+    origin?: string;
+    hydration: 'Hydrated' | 'Client-only' | 'Server';
+    members: StateInspectorMember[];
+}
+export declare function inspectActiveStates(nuxtApp: object): StateInspectorEntry[];
+export declare function classifyStateMember(value: unknown): string;
+export declare function previewValue(value: unknown): unknown;

package/dist/runtime/app/state-inspector.js

@@ -0,0 +1,149 @@
+import { isReactive, isReadonly, isRef, isShallow, toRaw } from "vue";
+import { getStateRegistry } from "./state-registry.js";
+const MAX_DEPTH = 4;
+const MAX_ITEMS = 40;
+const MAX_NODES = 200;
+const MAX_STRING = 500;
+export function inspectActiveStates(nuxtApp) {
+  const entries = [];
+  for (const [key, entry] of getStateRegistry(nuxtApp).active) {
+    if (!entry.debug) continue;
+    const state = entry.debug.state;
+    const members = inspectMembers(state);
+    entries.push({
+      key,
+      name: entry.debug.name || `State ${key}`,
+      source: entry.debug.source,
+      origin: entry.debug.origin,
+      hydration: entry.debug.hydration,
+      members
+    });
+  }
+  return entries;
+}
+export function classifyStateMember(value) {
+  if (typeof value === "function") return "function";
+  if (isRef(value)) {
+    if (isReadonly(value)) return "readonly ref";
+    return isShallow(value) ? "shallowRef" : "ref";
+  }
+  if (isReactive(value)) {
+    if (isReadonly(value)) return "readonly";
+    return isShallow(value) ? "shallowReactive" : "reactive";
+  }
+  if (isReadonly(value)) return "readonly";
+  return "other";
+}
+export function previewValue(value) {
+  try {
+    const context = { seen: /* @__PURE__ */ new WeakMap(), nodes: 0, truncated: false };
+    const preview = visit(value, 0, context);
+    return context.truncated ? { preview, truncated: true } : preview;
+  } catch (error) {
+    return { unavailable: safeErrorMessage(error) };
+  }
+}
+function inspectMembers(state) {
+  if (!isObjectLike(state)) {
+    return [{ name: "value", kind: classifyStateMember(state), value: previewValue(state) }];
+  }
+  try {
+    return Object.keys(state).map((name) => {
+      try {
+        const value = state[name];
+        return {
+          name,
+          kind: classifyStateMember(value),
+          value: previewValue(isRef(value) ? value.value : value)
+        };
+      } catch (error) {
+        return { name, kind: "unavailable", value: { unavailable: safeErrorMessage(error) } };
+      }
+    });
+  } catch (error) {
+    return [
+      {
+        name: "value",
+        kind: "unavailable",
+        value: { unavailable: safeErrorMessage(error) }
+      }
+    ];
+  }
+}
+function visit(value, depth, context) {
+  if (typeof value === "string") {
+    if (value.length <= MAX_STRING) return value;
+    context.truncated = true;
+    return `${value.slice(0, MAX_STRING)}\u2026`;
+  }
+  if (value === null || ["number", "boolean", "undefined"].includes(typeof value)) return value;
+  if (typeof value === "bigint") return `${value}n`;
+  if (typeof value === "symbol") return value.toString();
+  if (typeof value === "function") return `\u0192 ${value.name || "anonymous"}()`;
+  if (typeof value !== "object") return String(value);
+  const raw = isReactive(value) || isReadonly(value) ? toRaw(value) : value;
+  const known = context.seen.get(raw);
+  if (known) return { reference: `#${known}` };
+  const id = ++context.nodes;
+  context.seen.set(raw, id);
+  if (context.nodes > MAX_NODES || depth >= MAX_DEPTH) {
+    context.truncated = true;
+    return { id: `#${id}`, truncated: true };
+  }
+  if (raw instanceof Date) {
+    return {
+      id: `#${id}`,
+      type: "Date",
+      value: Number.isNaN(raw.valueOf()) ? "Invalid Date" : raw.toISOString()
+    };
+  }
+  if (raw instanceof Map) {
+    const items = [...raw.entries()];
+    if (items.length > MAX_ITEMS) context.truncated = true;
+    return {
+      id: `#${id}`,
+      type: "Map",
+      entries: items.slice(0, MAX_ITEMS).map(([key, item]) => [visit(key, depth + 1, context), visit(item, depth + 1, context)]),
+      ...items.length > MAX_ITEMS ? { truncated: true, total: items.length } : {}
+    };
+  }
+  if (raw instanceof Set) {
+    const items = [...raw];
+    if (items.length > MAX_ITEMS) context.truncated = true;
+    return {
+      id: `#${id}`,
+      type: "Set",
+      values: items.slice(0, MAX_ITEMS).map((item) => visit(item, depth + 1, context)),
+      ...items.length > MAX_ITEMS ? { truncated: true, total: items.length } : {}
+    };
+  }
+  if (Array.isArray(raw)) {
+    if (raw.length > MAX_ITEMS) context.truncated = true;
+    return {
+      id: `#${id}`,
+      type: "Array",
+      values: raw.slice(0, MAX_ITEMS).map((item) => visit(item, depth + 1, context)),
+      ...raw.length > MAX_ITEMS ? { truncated: true, total: raw.length } : {}
+    };
+  }
+  if (Object.getPrototypeOf(raw) !== Object.prototype && Object.getPrototypeOf(raw) !== null) {
+    const constructor = raw.constructor;
+    return { id: `#${id}`, unsupported: constructor?.name || "Object" };
+  }
+  const properties = Object.entries(raw);
+  if (properties.length > MAX_ITEMS) context.truncated = true;
+  return {
+    id: `#${id}`,
+    properties: Object.fromEntries(
+      properties.slice(0, MAX_ITEMS).map(([key, item]) => [key, visit(item, depth + 1, context)])
+    ),
+    ...properties.length > MAX_ITEMS ? { truncated: true, total: properties.length } : {}
+  };
+}
+function isObjectLike(value) {
+  return typeof value === "object" && value !== null || typeof value === "function";
+}
+function safeErrorMessage(error) {
+  if (error instanceof Error) return error.message.slice(0, 200);
+  return "Value could not be inspected";
+}

package/dist/runtime/app/state-registry.d.ts

@@ -2,6 +2,14 @@ export type StateHydrationPayload = Record<string, unknown>;
 export interface HydratableStateEntry {
     snapshot: () => unknown;
     restore: (snapshot: unknown) => void;
+    dispose?: () => void;
+    debug?: {
+        state: unknown;
+        name?: string;
+        source?: string;
+        origin?: string;
+        hydration: 'Hydrated' | 'Client-only' | 'Server';
+    };
 }
 interface StateRegistry {
     active: Map<string, HydratableStateEntry>;
@@ -11,4 +19,5 @@ export declare function getStateRegistry(nuxtApp: object): StateRegistry;
 export declare function registerHydratableState(nuxtApp: object, key: string, entry: HydratableStateEntry): void;
 export declare function collectStateSnapshots(nuxtApp: object): StateHydrationPayload;
 export declare function receiveStateSnapshots(nuxtApp: object, snapshots: StateHydrationPayload | undefined): void;
+export declare function clearPendingStateSnapshots(nuxtApp: object): void;
 export {};

package/dist/runtime/app/state-registry.js

@@ -12,6 +12,7 @@ export function getStateRegistry(nuxtApp) {
 }
 export function registerHydratableState(nuxtApp, key, entry) {
   const registry = getStateRegistry(nuxtApp);
+  registry.active.get(key)?.dispose?.();
   registry.active.set(key, entry);
   if (registry.hydration.has(key)) {
     const snapshot = registry.hydration.get(key);
@@ -36,3 +37,6 @@ export function receiveStateSnapshots(nuxtApp, snapshots) {
     entry.restore(snapshot);
   }
 }
+export function clearPendingStateSnapshots(nuxtApp) {
+  getStateRegistry(nuxtApp).hydration.clear();
+}

package/dist/runtime/app/state-snapshot.js

@@ -27,44 +27,48 @@ function isPlainRecord(value) {
   return Object.prototype.toString.call(value) === "[object Object]";
 }
 function canPatch(target, source) {
-  return Array.isArray(target) && Array.isArray(source) || isPlainRecord(target) && isPlainRecord(source);
+  return Array.isArray(target) && Array.isArray(source) || isPlainRecord(target) && !isRef(target) && isPlainRecord(source) && !isRef(source);
 }
-function patchValue(target, source) {
+function isTrackableObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function patchValue(target, source, seen) {
+  if (!isTrackableObject(source)) return source;
+  if (seen.has(source)) return seen.get(source);
+  if (!canPatch(target, source)) {
+    seen.set(source, source);
+    return source;
+  }
+  seen.set(source, target);
   if (Array.isArray(target) && Array.isArray(source)) {
     for (let index = 0; index < source.length; index++) {
-      if (canPatch(target[index], source[index])) {
-        patchValue(target[index], source[index]);
-      } else {
-        target[index] = source[index];
-      }
+      target[index] = patchValue(target[index], source[index], seen);
     }
     target.length = source.length;
-    return;
+    return target;
   }
-  if (!isPlainRecord(target) || !isPlainRecord(source)) return;
+  if (!isPlainRecord(target) || !isPlainRecord(source)) return source;
   for (const key of Object.keys(target)) {
     if (!(key in source)) delete target[key];
   }
   for (const [key, value] of Object.entries(source)) {
-    if (canPatch(target[key], value)) {
-      patchValue(target[key], value);
-    } else {
-      target[key] = value;
-    }
+    target[key] = patchValue(target[key], value, seen);
   }
+  return target;
 }
 function isStateSnapshotEntry(value) {
   return isPlainRecord(value) && (value.type === "ref" || value.type === "reactive") && Object.hasOwn(value, "value");
 }
 export function restoreState(state, snapshot) {
   if (!isObjectLike(state) || !isPlainRecord(snapshot)) return;
+  const seen = /* @__PURE__ */ new WeakMap();
   for (const [name, entry] of Object.entries(snapshot)) {
     if (!isStateSnapshotEntry(entry)) continue;
     const target = state[name];
     if (entry.type === "ref" && isRef(target) && !isReadonly(target)) {
       target.value = entry.value;
     } else if (entry.type === "reactive" && isReactive(target) && !isReadonly(target)) {
-      patchValue(target, entry.value);
+      patchValue(target, entry.value, seen);
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-state",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Define shared Nuxt state using the same Composition API you already use in composables.",
   "keywords": [
     "composable",
@@ -44,6 +44,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@nuxt/devtools-kit": "^3.4.2",
     "@nuxt/kit": "^4.5.2"
   },
   "devDependencies": {
@@ -77,8 +78,9 @@
     "fmt:check": "oxfmt --check",
     "test": "vitest run",
     "test:browser": "vitest run test/browser",
+    "test:stress": "vitest run --config vitest.stress.config.ts",
     "check": "pnpm run fmt:check && pnpm run lint",
     "test:watch": "vitest",
-    "test:types": "nuxt-module-build build && vue-tsc --noEmit && pnpm --dir playground exec vue-tsc --noEmit"
+    "test:types": "nuxt-module-build prepare && nuxt-module-build build && vue-tsc --noEmit && pnpm --dir playground exec vue-tsc --noEmit"
   }
 }