nuxt-state 0.2.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.
@@ -159,6 +215,7 @@ snapshot-metadata overhead.
 - 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.
 
@@ -192,11 +249,11 @@ snapshot metadata points at the same payload graph rather than serializing respo
   inside refs, symbols, and arbitrary native/class resources are unsupported.
 - Closure-private mutable state is not discoverable; return any ref/reactive value whose SSR
   mutations must hydrate.
-- No Nuxt Layers support yet.
 - State resets when its module is hot-reloaded; HMR preservation is not implemented.
 - Context-sensitive composables must still be called while normal Nuxt context is available.
-- There is no reset API, keyed/multi-instance state, DevTools integration, or central
-  user-facing registry.
+- 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.

package/dist/module.json

@@ -4,7 +4,7 @@
     "nuxt": "^4.0.0"
   },
   "configKey": "nuxt-state",
-  "version": "0.2.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

@@ -30,11 +30,23 @@ export function defineState(factory, internalKey) {
     const app = nuxtApp;
     app.vueApp?.onUnmount?.(() => scope.stop());
     if (internalKey) {
-      registerHydratableState(nuxtApp, internalKey, {
+      const entry = {
         snapshot: () => snapshotState(instance),
         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/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

@@ -3,6 +3,13 @@ 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>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-state",
-  "version": "0.2.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": {