@stonecrop/nuxt 0.10.4 → 0.10.6

package/README.md

@@ -102,20 +102,26 @@ The module picks up this file and, if `pageComponent` is configured, registers a
 
 ### Wire Up Your Data Client
 
-After installing the module, add a client-side plugin to connect your data transport. The `useStonecropRegistry()` composable gives you a stable API for this — no need to reach into `globalProperties` directly:
+After installing the module, add a client-side plugin to connect your data transport. Use `useStonecropSetup()` in plugins — it's designed for the initialization context where Stonecrop may not be fully ready yet:
 
 ```typescript
 // app/plugins/stonecrop.client.ts
 import { StonecropClient } from '@stonecrop/graphql-client'
 
 export default defineNuxtPlugin(() => {
+  const { registerClient, registerMeta } = useStonecropSetup()
+
   const client = new StonecropClient({ endpoint: '/graphql' })
-  const { setMeta, setFetchRecord, setFetchRecords } = useStonecropRegistry()
 
-  // Map the route path/segments to a doctype name, then delegate to your client
-  setMeta(({ segments }) => client.getMeta({ doctype: segments[0] }))
-  setFetchRecord((doctype, id) => client.getRecord(doctype, id))
-  setFetchRecords((doctype) => client.getRecords(doctype))
+  // Register the data client for record fetching
+  registerClient(client)
+
+  // Configure metadata fetching for lazy-loaded doctypes
+  // Called by useStonecrop() when it needs doctype metadata
+  registerMeta(({ segments }) => {
+    const doctype = segments[0] // e.g., "task" from /task/123
+    return client.getMeta({ doctype })
+  })
 })
 ```
 
@@ -321,48 +327,87 @@ The module auto-registers:
 - **Self-Documenting**: Schemas serve as data model documentation
 - **Easy Updates**: Change schema, UI updates automatically
 
-## `useStonecropRegistry()` — Configuring the Framework After Install
-
-The `@stonecrop/nuxt` runtime plugin installs `StonecropPlugin` with a router but no data transport, because data clients (GraphQL, tRPC, REST) are application-defined and cannot be serialised through `nuxt.config.ts` module options.
+## `useStonecropSetup()` — Configuring the Framework in Plugins
 
-`useStonecropRegistry()` is the documented extension point for wiring your data transport after plugin install. Call it in a client-side plugin:
+When you need to configure Stonecrop during Nuxt plugin initialization (before components mount), use `useStonecropSetup()`. This composable is designed specifically for the plugin context and returns values that may be `undefined` if Stonecrop hasn't finished initializing.
 
 ```typescript
 // app/plugins/stonecrop.client.ts
+import { StonecropClient } from '@stonecrop/graphql-client'
+
 export default defineNuxtPlugin(() => {
-  const { setMeta, setFetchRecord, setFetchRecords } = useStonecropRegistry()
+  const { isReady, registerClient, registerMeta, registerDoctype } = useStonecropSetup()
 
-  // setMeta — resolves doctype metadata from the current route
-  // The context has { path, segments } from the router; adapt to your API.
-  setMeta(async ({ segments }) => {
-    // Example: segments[0] is the doctype slug, e.g. "task" from /task/123
-    const doctype = segments[0]
-    const meta = await $fetch(`/api/doctypes/${doctype}`)
-    return meta
-  })
+  // Check if Stonecrop is ready (module plugins run before project plugins)
+  if (!isReady) {
+    console.warn('Stonecrop not ready - ensure @stonecrop/nuxt module is installed')
+    return
+  }
 
-  // setFetchRecord — replaces the default REST stub in useStonecrop({ recordId })
-  setFetchRecord(async (doctype, id) => {
-    return await $fetch(`/api/${doctype.slug}/${id}`)
-  })
+  const client = new StonecropClient({ endpoint: '/graphql' })
+
+  // Register the data client
+  registerClient(client)
 
-  // setFetchRecords — replaces the default REST stub for list loading
-  setFetchRecords(async (doctype) => {
-    return await $fetch(`/api/${doctype.slug}`)
+  // Configure metadata fetching for lazy-loaded doctypes
+  registerMeta(({ segments }) => {
+    const doctype = segments[0]
+    return client.getMeta({ doctype })
   })
+
+  // Optionally pre-load doctypes into the Registry
+  const planDoctype = Doctype.fromObject({ name: 'plan', fields: [...] })
+  registerDoctype(planDoctype)
 })
 ```
 
-**Why a composable and not module options?** Nuxt module options are serialised at build time — functions cannot be passed through `nuxt.config.ts`. `useStonecropRegistry()` is the composable equivalent of `usePinia()` or `useNuxtApp()`: a stable, typed API for configuring the framework singleton after it has been installed.
+### `useStonecropSetup()` vs `useStonecropRegistry()`
+
+| Context | Use | Behavior |
+|---------|-----|----------|
+| **Plugin/initialization** | `useStonecropSetup()` | Returns values that may be `undefined`; provides `isReady` check |
+| **Component/runtime** | `useStonecropRegistry()` | Throws if Stonecrop isn't initialized (expected to be ready) |
+
+### `useStonecropSetup()` API
+
+| Property/Method | Type | Description |
+|-----------------|------|-------------|
+| `registry` | `Registry \| undefined` | The Registry instance (undefined if not ready) |
+| `stonecrop` | `Stonecrop \| undefined` | The Stonecrop instance (undefined if not ready) |
+| `isReady` | `boolean` | `true` when both registry and stonecrop are available |
+| `registerClient(client)` | `(client: DataClient) => void` | Set the data client for record fetching. Throws if stonecrop not available. |
+| `getClient()` | `() => DataClient \| undefined` | Get the currently configured client. |
+| `registerMeta(fn)` | `(fn: (ctx) => Doctype) => void` | Set the `getMeta` function on the Registry. Throws if registry not available. |
+| `registerDoctype(doctype)` | `(doctype: Doctype) => void` | Pre-load a doctype into the Registry. Throws if registry not available. |
+| `dispatchAction(...)` | `Promise<{ success, data, error }>` | Dispatch an action via the configured client. |
+
+## `useStonecropRegistry()` — Using the Framework in Components
+
+`useStonecropRegistry()` is for component/runtime context where the framework is expected to be fully initialized. Use it in components to access the configured registry and stonecrop instances.
+
+```typescript
+// In a component or composable
+const { registry, stonecrop, dispatchAction } = useStonecropRegistry()
+
+// Access doctype metadata
+const plan = registry.getDoctype('plan')
+
+// Dispatch actions
+await dispatchAction({ name: 'plan' }, 'SUBMIT', [recordId])
+```
+
+**Note**: If called before Stonecrop is initialized (e.g., in a plugin), this throws with guidance to use `useStonecropSetup()` instead.
 
-### API
+### `useStonecropRegistry()` API
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `setMeta` | `(fn: (ctx) => DoctypeMeta \| Promise<DoctypeMeta>) => void` | Sets the `getMeta` function on the Registry. Called by `useStonecrop()` to lazy-load doctype metadata for the current route. `ctx` = `{ path, segments }`. |
-| `setFetchRecord` | `(fn: (doctype, id) => Promise<Record \| null>) => void` | Replaces the default REST fetch stub in `Stonecrop.getRecord()`. Enables GraphQL-backed or any other custom transport. |
-| `setFetchRecords` | `(fn: (doctype) => Promise<Record[]>) => void` | Replaces the default REST fetch stub in `Stonecrop.getRecords()`. |
-| `registry` | `Registry` | The raw Registry instance, for advanced use cases. |
+| Property/Method | Type | Description |
+|-----------------|------|-------------|
+| `registry` | `Registry` | The Registry instance for doctype management. |
+| `stonecrop` | `Stonecrop` | The Stonecrop instance for HST and operation log access. Throws if not initialized. |
+| `setMeta(fn)` | `(fn: (ctx) => Doctype \| Promise<Doctype>) => void` | Sets the `getMeta` function on the Registry. Called by `useStonecrop()` to lazy-load doctype metadata for the current route. `ctx` = `{ path, segments }`. |
+| `setClient(client)` | `(client: DataClient) => void` | Set the data client for record fetching. Throws if stonecrop not available. |
+| `getClient()` | `() => DataClient \| undefined` | Get the currently configured client. |
+| `dispatchAction(doctype, action, args)` | `Promise<{ success, data, error }>` | Dispatch an action via the configured client. Returns error if doctype not found in registry. |
 
 ## Advanced Features
 

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@stonecrop/nuxt",
   "configKey": "stonecrop",
-  "version": "0.10.4",
+  "version": "0.10.6",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/runtime/app/composables/useStonecropRegistry.d.ts

@@ -1,8 +1,16 @@
-import type { DataClient, DoctypeMeta } from '@stonecrop/schema';
-import type { RouteContext } from '@stonecrop/stonecrop';
+import type { DataClient } from '@stonecrop/schema';
+import type { Doctype, Registry, RouteContext, Stonecrop } from '@stonecrop/stonecrop';
 /**
- * Provides a stable, documented API for accessing and configuring the Stonecrop
- * Registry instance after the `@stonecrop/nuxt` plugin has installed it.
+ * Provides a stable, documented API for accessing the configured Stonecrop
+ * Registry instance in components and composables.
+ *
+ * ## When to Use This vs useStonecropSetup()
+ *
+ * - **`useStonecropRegistry()`** - Call in components or composables to use the configured
+ *   framework. Throws if Stonecrop isn't initialized (expected to be ready at this point).
+ *
+ * - **`useStonecropSetup()`** - Call in Nuxt plugins to configure clients, metadata functions,
+ *   and pre-load doctypes. Returns values that may be `undefined` if Stonecrop isn't ready yet.
  *
  * ## Why This Composable Exists
  *
@@ -12,9 +20,8 @@ import type { RouteContext } from '@stonecrop/stonecrop';
  * - **@stonecrop/graphql-client**: Reference `DataClient` implementation using GraphQL
  * - **@stonecrop/nuxt**: Nuxt integration that bootstraps the Registry and Stonecrop instances
  *
- * This composable bridges Nuxt's plugin lifecycle with Stonecrop's registry, allowing
- * applications to inject their data client and configure metadata fetching after the
- * framework is mounted.
+ * This composable bridges Nuxt's plugin lifecycle with Stonecrop's registry, providing
+ * a clean API for components to interact with the configured framework.
  *
  * ## RouteContext vs DoctypeContext
  *
@@ -24,8 +31,8 @@ import type { RouteContext } from '@stonecrop/stonecrop';
  * - **DoctypeContext** (`{ doctype, recordId? }`): Semantic doctype context. Used by the
  *   data layer to identify "what we're working with" (e.g., `{ doctype: 'Plan', recordId: '123' }`).
  *
- * Your `setMeta` implementation bridges these: extract doctype/recordId from the route
- * segments and pass `DoctypeContext` to your data client.
+ * Your `setMeta` implementation (configured via `useStonecropSetup()`) bridges these:
+ * extract doctype/recordId from the route segments and pass `DoctypeContext` to your data client.
  *
  * ## Data Flow
  *
@@ -34,49 +41,42 @@ import type { RouteContext } from '@stonecrop/stonecrop';
  *     ↓
  * RouteContext ({ path: '/plan/123', segments: ['plan', '123'] })
  *     ↓
- * getMeta (your implementation)
+ * getMeta (configured in plugin via useStonecropSetup)
  *     ↓
  * DoctypeContext ({ doctype: 'Plan', recordId: '123' })
  *     ↓
- * DataClient.getMeta() → DoctypeMeta
+ * DataClient.getMeta() → Doctype
  * ```
  *
  * @example
  * ```ts
- * // app/plugins/stonecrop.client.ts
- * import { StonecropClient } from '@stonecrop/graphql-client'
- *
- * export default defineNuxtPlugin(() => {
- *   const client = new StonecropClient({ endpoint: '/graphql' })
- *   const { setClient, setMeta } = useStonecropRegistry()
- *
- *   // Set the data client for record fetching
- *   setClient(client)
- *
- *   // Bridge RouteContext → DoctypeContext for metadata fetching
- *   setMeta(({ segments }) => {
- *     const doctype = segments[0] // e.g. "plan" → doctype "Plan"
- *     return client.getMeta({ doctype }) // client expects DoctypeContext
- *   })
- * })
+ * // In a component or composable
+ * const { registry, stonecrop, dispatchAction } = useStonecropRegistry()
+ *
+ * // Access the registry
+ * const plan = registry.getDoctype('plan')
+ *
+ * // Dispatch an action
+ * await dispatchAction({ name: 'plan' }, 'SUBMIT', [recordId])
  * ```
  *
  * @public
  */
 export declare function useStonecropRegistry(): {
     /**
-     * The raw Registry instance, for advanced use cases.
-     * Prefer the typed setter methods below for normal configuration.
+     * The Registry instance for doctype management.
+     * Use this to access doctype metadata, resolve schemas, etc.
+     */
+    registry: Registry;
+    /**
+     * The Stonecrop instance for HST and operation log access.
      */
-    registry: {
-        getMeta?: (routeContext: RouteContext) => DoctypeMeta | Promise<DoctypeMeta>;
-    };
+    readonly stonecrop: Stonecrop;
     /**
      * Set the data client on the Stonecrop instance.
      * Required before fetching records or dispatching actions.
      *
      * @param client - DataClient implementation (e.g., StonecropClient from \@stonecrop/graphql-client)
-     *
      * @throws Error if Stonecrop instance is not available
      *
      * @example
@@ -95,7 +95,9 @@ export declare function useStonecropRegistry(): {
      * Dispatch an action to the server via the configured data client.
      * All state changes flow through this single mutation endpoint.
      *
-     * @param doctype - Doctype reference (name and optional slug)
+     * @param doctype - Doctype reference object with `name` and optional `slug` properties
+     * @param doctype.name - Doctype name (e.g., 'plan')
+     * @param doctype.slug - Optional doctype slug if it differs from the name (e.g., 'project-plan')
      * @param action - Action name to execute (e.g., 'SUBMIT', 'APPROVE', 'save')
      * @param args - Action arguments (typically record ID and/or form data)
      * @returns Action result with success status, response data, and any error
@@ -103,10 +105,10 @@ export declare function useStonecropRegistry(): {
      * @example
      * ```ts
      * // Save a record
-     * const result = await dispatchAction(doctype, 'save', [{ id: recordId, data: formData }])
+     * const result = await dispatchAction({ name: 'plan' }, 'save', [{ id: recordId, data: formData }])
      *
      * // Submit for approval
-     * const result = await dispatchAction(doctype, 'SUBMIT', [recordId])
+     * const result = await dispatchAction({ name: 'plan' }, 'SUBMIT', [recordId])
      * ```
      */
     dispatchAction(doctype: {
@@ -135,7 +137,7 @@ export declare function useStonecropRegistry(): {
      * })
      * ```
      *
-     * @param fn - Function that receives RouteContext and returns DoctypeMeta.
+     * @param fn - Function that receives RouteContext and returns Doctype.
      */
-    setMeta(fn: (routeContext: RouteContext) => DoctypeMeta | Promise<DoctypeMeta>): void;
+    setMeta(fn: (routeContext: RouteContext) => Doctype | Promise<Doctype>): void;
 };

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

@@ -4,22 +4,32 @@ export function useStonecropRegistry() {
   const registry = nuxtApp.$registry;
   if (!registry) {
     throw new Error(
-      "[useStonecropRegistry] The Stonecrop Registry is not available. Ensure @stonecrop/nuxt is installed and the plugin has run before calling this composable."
+      "[useStonecropRegistry] The Stonecrop Registry is not available. Ensure @stonecrop/nuxt is installed.\n\nIf you are calling this from a Nuxt plugin, use useStonecropSetup() instead, which is designed for the plugin initialization context."
     );
   }
   const stonecrop = nuxtApp.$stonecrop;
   return {
     /**
-     * The raw Registry instance, for advanced use cases.
-     * Prefer the typed setter methods below for normal configuration.
+     * The Registry instance for doctype management.
+     * Use this to access doctype metadata, resolve schemas, etc.
      */
     registry,
+    /**
+     * The Stonecrop instance for HST and operation log access.
+     */
+    get stonecrop() {
+      if (!stonecrop) {
+        throw new Error(
+          "[useStonecropRegistry] Stonecrop instance is not available. Ensure @stonecrop/nuxt is installed.\n\nIf you are calling this from a Nuxt plugin, use useStonecropSetup() instead."
+        );
+      }
+      return stonecrop;
+    },
     /**
      * Set the data client on the Stonecrop instance.
      * Required before fetching records or dispatching actions.
      *
      * @param client - DataClient implementation (e.g., StonecropClient from \@stonecrop/graphql-client)
-     *
      * @throws Error if Stonecrop instance is not available
      *
      * @example
@@ -31,7 +41,7 @@ export function useStonecropRegistry() {
     setClient(client) {
       if (!stonecrop) {
         throw new Error(
-          "[useStonecropRegistry] Stonecrop instance is not available. Ensure @stonecrop/nuxt is installed and the plugin has run."
+          "[useStonecropRegistry] Stonecrop instance is not available. Ensure @stonecrop/nuxt is installed.\n\nIf you are calling this from a Nuxt plugin, use useStonecropSetup() instead."
         );
       }
       stonecrop.setClient(client);
@@ -47,7 +57,9 @@ export function useStonecropRegistry() {
      * Dispatch an action to the server via the configured data client.
      * All state changes flow through this single mutation endpoint.
      *
-     * @param doctype - Doctype reference (name and optional slug)
+     * @param doctype - Doctype reference object with `name` and optional `slug` properties
+     * @param doctype.name - Doctype name (e.g., 'plan')
+     * @param doctype.slug - Optional doctype slug if it differs from the name (e.g., 'project-plan')
      * @param action - Action name to execute (e.g., 'SUBMIT', 'APPROVE', 'save')
      * @param args - Action arguments (typically record ID and/or form data)
      * @returns Action result with success status, response data, and any error
@@ -55,21 +67,29 @@ export function useStonecropRegistry() {
      * @example
      * ```ts
      * // Save a record
-     * const result = await dispatchAction(doctype, 'save', [{ id: recordId, data: formData }])
+     * const result = await dispatchAction({ name: 'plan' }, 'save', [{ id: recordId, data: formData }])
      *
      * // Submit for approval
-     * const result = await dispatchAction(doctype, 'SUBMIT', [recordId])
+     * const result = await dispatchAction({ name: 'plan' }, 'SUBMIT', [recordId])
      * ```
      */
     dispatchAction(doctype, action, args) {
       if (!stonecrop) {
         return Promise.reject(
           new Error(
-            "[useStonecropRegistry] Stonecrop instance is not available. Ensure @stonecrop/nuxt is installed and the plugin has run."
+            "[useStonecropRegistry] Stonecrop instance is not available. Ensure @stonecrop/nuxt is installed.\n\nIf you are calling this from a Nuxt plugin, use useStonecropSetup() instead."
           )
         );
       }
-      return stonecrop.dispatchAction(doctype, action, args);
+      const meta = registry.getDoctype(doctype.slug || doctype.name.toLowerCase());
+      if (!meta) {
+        return Promise.resolve({
+          success: false,
+          data: null,
+          error: `Doctype '${doctype.name}' not found in registry`
+        });
+      }
+      return stonecrop.dispatchAction(meta, action, args);
     },
     /**
      * Set the `getMeta` function on the Registry.
@@ -89,7 +109,7 @@ export function useStonecropRegistry() {
      * })
      * ```
      *
-     * @param fn - Function that receives RouteContext and returns DoctypeMeta.
+     * @param fn - Function that receives RouteContext and returns Doctype.
      */
     setMeta(fn) {
       registry.getMeta = fn;

package/dist/runtime/app/composables/useStonecropSetup.d.ts

@@ -0,0 +1,108 @@
+import type { DataClient } from '@stonecrop/schema';
+import type { Doctype, Registry, RouteContext, Stonecrop } from '@stonecrop/stonecrop';
+/**
+ * Composable for Stonecrop initialization in Nuxt plugins.
+ *
+ * Use this during the plugin/initialization phase to configure the framework
+ * before components mount. For component/runtime usage, use `useStonecropRegistry()` instead.
+ *
+ * ## When to Use This vs useStonecropRegistry()
+ *
+ * - **`useStonecropSetup()`** - Call in Nuxt plugins to configure clients, metadata functions,
+ *   and pre-load doctypes. Returns values that may be `undefined` if Stonecrop isn't ready yet.
+ *
+ * - **`useStonecropRegistry()`** - Call in components or composables to use the configured
+ *   framework. Throws if Stonecrop isn't initialized (expected to be ready at this point).
+ *
+ * ## Example
+ *
+ * ```ts
+ * // app/plugins/stonecrop.client.ts
+ * import { StonecropClient } from '@stonecrop/graphql-client'
+ *
+ * export default defineNuxtPlugin(() => {
+ *   const { registerClient, registerMeta, registerDoctype } = useStonecropSetup()
+ *
+ *   const client = new StonecropClient({ endpoint: '/graphql' })
+ *   registerClient(client)
+ *
+ *   // Configure metadata fetching for lazy-loaded doctypes
+ *   registerMeta(({ segments }) => {
+ *     const doctype = segments[0]
+ *     return client.getMeta({ doctype })
+ *   })
+ *
+ *   // Optionally pre-load doctypes
+ *   const plan = Doctype.fromObject({ name: 'plan', fields: [...] })
+ *   registerDoctype(plan)
+ * })
+ * ```
+ *
+ * @public
+ */
+export declare function useStonecropSetup(): {
+    /**
+     * The Registry instance.
+     * Returns `undefined` if the @stonecrop/nuxt plugin hasn't run yet.
+     */
+    readonly registry: Registry | undefined;
+    /**
+     * The Stonecrop instance.
+     * Returns `undefined` if the @stonecrop/nuxt plugin hasn't run yet.
+     */
+    readonly stonecrop: Stonecrop | undefined;
+    /**
+     * Check if Stonecrop is ready for configuration.
+     * Returns `true` when both Registry and Stonecrop instances are available.
+     */
+    readonly isReady: boolean;
+    /**
+     * Register the data client on the Stonecrop instance.
+     * Required before fetching records or dispatching actions.
+     *
+     * @param client - DataClient implementation (e.g., StonecropClient from \@stonecrop/graphql-client)
+     * @throws Error if the Stonecrop plugin is not installed
+     *
+     * @example
+     * ```ts
+     * const client = new StonecropClient({ endpoint: '/graphql' })
+     * registerClient(client)
+     * ```
+     */
+    registerClient(client: DataClient): void;
+    /**
+     * Set the `getMeta` function on the Registry.
+     * Called by `useStonecrop()` to lazy-load doctype metadata for the current route.
+     *
+     * You must bridge `RouteContext` → `DoctypeContext`:
+     * - Extract doctype name from `segments` (e.g., `segments[0]`)
+     * - Extract record ID from `segments` if present (e.g., `segments[1]`)
+     * - Pass `DoctypeContext` to your data client
+     *
+     * @param fn - Function that receives RouteContext and returns Doctype
+     * @throws Error if the Registry is not available
+     *
+     * @example
+     * ```ts
+     * registerMeta(({ segments }) => {
+     *   const doctype = segments[0] // /plan/123 → 'plan'
+     *   return client.getMeta({ doctype })
+     * })
+     * ```
+     */
+    registerMeta(fn: (routeContext: RouteContext) => Doctype | Promise<Doctype>): void;
+    /**
+     * Load a doctype into the Registry.
+     * Convenience method that calls `registry.addDoctype()` if available.
+     *
+     * @param doctype - The Doctype instance to register
+     * @throws Error if the Registry is not available
+     *
+     * @example
+     * ```ts
+     * const plan = Doctype.fromObject({ name: 'plan', fields: [...] })
+     * registerDoctype(plan)
+     * ```
+     */
+    registerDoctype(doctype: Doctype): void;
+};

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

@@ -0,0 +1,100 @@
+import { useNuxtApp } from "nuxt/app";
+export function useStonecropSetup() {
+  const nuxtApp = useNuxtApp();
+  return {
+    /**
+     * The Registry instance.
+     * Returns `undefined` if the @stonecrop/nuxt plugin hasn't run yet.
+     */
+    get registry() {
+      return nuxtApp.$registry;
+    },
+    /**
+     * The Stonecrop instance.
+     * Returns `undefined` if the @stonecrop/nuxt plugin hasn't run yet.
+     */
+    get stonecrop() {
+      return nuxtApp.$stonecrop;
+    },
+    /**
+     * Check if Stonecrop is ready for configuration.
+     * Returns `true` when both Registry and Stonecrop instances are available.
+     */
+    get isReady() {
+      return !!(nuxtApp.$registry && nuxtApp.$stonecrop);
+    },
+    /**
+     * Register the data client on the Stonecrop instance.
+     * Required before fetching records or dispatching actions.
+     *
+     * @param client - DataClient implementation (e.g., StonecropClient from \@stonecrop/graphql-client)
+     * @throws Error if the Stonecrop plugin is not installed
+     *
+     * @example
+     * ```ts
+     * const client = new StonecropClient({ endpoint: '/graphql' })
+     * registerClient(client)
+     * ```
+     */
+    registerClient(client) {
+      const stonecrop = nuxtApp.$stonecrop;
+      if (!stonecrop) {
+        throw new Error(
+          "[useStonecropSetup] Stonecrop instance not available. Ensure the @stonecrop/nuxt module is installed and its plugin has run before calling this."
+        );
+      }
+      stonecrop.setClient(client);
+    },
+    /**
+     * Set the `getMeta` function on the Registry.
+     * Called by `useStonecrop()` to lazy-load doctype metadata for the current route.
+     *
+     * You must bridge `RouteContext` → `DoctypeContext`:
+     * - Extract doctype name from `segments` (e.g., `segments[0]`)
+     * - Extract record ID from `segments` if present (e.g., `segments[1]`)
+     * - Pass `DoctypeContext` to your data client
+     *
+     * @param fn - Function that receives RouteContext and returns Doctype
+     * @throws Error if the Registry is not available
+     *
+     * @example
+     * ```ts
+     * registerMeta(({ segments }) => {
+     *   const doctype = segments[0] // /plan/123 → 'plan'
+     *   return client.getMeta({ doctype })
+     * })
+     * ```
+     */
+    registerMeta(fn) {
+      const registry = nuxtApp.$registry;
+      if (!registry) {
+        throw new Error(
+          "[useStonecropSetup] Registry not available. Ensure the @stonecrop/nuxt module is installed and its plugin has run before calling this."
+        );
+      }
+      registry.getMeta = fn;
+    },
+    /**
+     * Load a doctype into the Registry.
+     * Convenience method that calls `registry.addDoctype()` if available.
+     *
+     * @param doctype - The Doctype instance to register
+     * @throws Error if the Registry is not available
+     *
+     * @example
+     * ```ts
+     * const plan = Doctype.fromObject({ name: 'plan', fields: [...] })
+     * registerDoctype(plan)
+     * ```
+     */
+    registerDoctype(doctype) {
+      const registry = nuxtApp.$registry;
+      if (!registry) {
+        throw new Error(
+          "[useStonecropSetup] Registry not available. Ensure the @stonecrop/nuxt module is installed and its plugin has run before calling this."
+        );
+      }
+      registry.addDoctype(doctype);
+    }
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/nuxt",
-  "version": "0.10.4",
+  "version": "0.10.6",
   "description": "Nuxt module for Stonecrop",
   "license": "MIT",
   "type": "module",
@@ -44,14 +44,14 @@
     "jiti": "^2.4.2",
     "pathe": "^2.0.3",
     "prompts": "^2.4.2",
-    "@stonecrop/atable": "0.10.4",
-    "@stonecrop/aform": "0.10.4",
-    "@stonecrop/nuxt-grafserv": "0.10.4",
-    "@stonecrop/casl-middleware": "0.10.4",
-    "@stonecrop/graphql-middleware": "0.10.4",
-    "@stonecrop/node-editor": "0.10.4",
-    "@stonecrop/schema": "0.10.4",
-    "@stonecrop/stonecrop": "0.10.4"
+    "@stonecrop/atable": "0.10.6",
+    "@stonecrop/aform": "0.10.6",
+    "@stonecrop/casl-middleware": "0.10.6",
+    "@stonecrop/graphql-middleware": "0.10.6",
+    "@stonecrop/node-editor": "0.10.6",
+    "@stonecrop/nuxt-grafserv": "0.10.6",
+    "@stonecrop/schema": "0.10.6",
+    "@stonecrop/stonecrop": "0.10.6"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",