@stonecrop/nuxt 0.16.6 → 0.18.0

package/README.md

@@ -125,7 +125,7 @@ export default defineNuxtPlugin(() => {
 })
 ```
 
-This wires `useStonecrop()`'s automatic record loading to your GraphQL (or any other) backend. Without this step, `useStonecrop({ doctype, recordId })` falls back to a REST fetch stub that may not exist in your app.
+This wires record loading to your GraphQL (or any other) backend. It is the seam Desktop reads through as well. There is no fallback: without a registered client, `getRecord` and `getRecords` throw naming `setClient`, and Desktop skips the read and renders empty.
 
 ### Use the Stonecrop Composable
 
@@ -400,7 +400,7 @@ await dispatchAction({ name: 'plan' }, 'SUBMIT', [recordId])
 |-----------------|------|-------------|
 | `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 }`. |
+| `setMeta(fn)` | `(fn: (ctx) => Doctype \| Promise<Doctype>) => void` | Sets the `getMeta` function on the Registry. Called by `useStonecrop({ doctype: 'slug' })` to lazy-load that doctype's metadata. `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. |

package/dist/module.json

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

package/dist/runtime/app/components/DocBuilderFieldsPanel.d.vue.ts

@@ -1,4 +1,4 @@
-type Field = Record<string, unknown>;
+import { type Field } from './docbuilderFields.js';
 type __VLS_Props = {
     modelValue: Field[];
 };

package/dist/runtime/app/components/DocBuilderFieldsPanel.vue

@@ -129,6 +129,7 @@
 import { ATable, ARow } from "@stonecrop/atable";
 import { CANONICAL_COMPONENTS, INTROSPECTED_IDENTITY_PROPS } from "@stonecrop/schema";
 import { computed, nextTick, ref, useId } from "vue";
+import { updateFieldAt } from "./docbuilderFields";
 const IDENTITY_PROPS = new Set(INTROSPECTED_IDENTITY_PROPS);
 const isIdentity = (key) => IDENTITY_PROPS.has(key);
 const componentListId = useId();
@@ -230,17 +231,7 @@ function collapseAllRows() {
   });
 }
 function update(realIndex, key, val) {
-  emit(
-    "update:modelValue",
-    props.modelValue.map((f, i) => i === realIndex ? setOrDelete(f, key, val) : f)
-  );
-}
-function setOrDelete(field, key, val) {
-  if (val === void 0) {
-    const { [key]: _omit, ...rest } = field;
-    return rest;
-  }
-  return { ...field, [key]: val };
+  emit("update:modelValue", updateFieldAt(props.modelValue, realIndex, key, val));
 }
 const jsonErrors = ref({});
 function jsonStr(v) {

package/dist/runtime/app/components/DocBuilderFieldsPanel.vue.d.ts

@@ -1,4 +1,4 @@
-type Field = Record<string, unknown>;
+import { type Field } from './docbuilderFields.js';
 type __VLS_Props = {
     modelValue: Field[];
 };

package/dist/runtime/app/components/docbuilderFields.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pure write helpers backing {@link DocBuilderFieldsPanel}. Extracted from the SFC so they are
+ * unit-testable in a plain node environment, matching {@link docbuilderActions}.
+ *
+ * These are hop 3 of the four that must each preserve keys the builder never displays: the graph
+ * edit rebuilds `workflow.actions`, the actions panel writes a cell, **this** writes a field cell,
+ * then the server merges onto what is on disk. The invariant has regressed twice upstream — once
+ * dropping `clientHandler`, once dropping `triggers` — both times because a hop enumerated the
+ * named keys it knew about instead of spreading whatever was there.
+ *
+ * This hop is the one with the widest blast radius, because the server replaces `fields` wholesale
+ * with whatever the client sends. A key dropped here is dropped on disk. On the FAB app that is
+ * `filterFunction` x7, `isAsync` x7, `collapsible` x4, nested `schema` x4, `options` x1 and
+ * `source` x325 — none of which the panel renders, all of which must survive editing a label.
+ */
+/** A doctype field as authored on disk: known keys plus anything the builder does not model. */
+export type Field = Record<string, unknown>;
+/**
+ * Set `key` on `field`, or remove it when `val` is `undefined`.
+ *
+ * Clearing a cell must delete the key rather than write `undefined`: the doctype is serialised with
+ * `JSON.stringify`, which drops `undefined` values silently, so writing one would make "cleared" and
+ * "never set" indistinguishable on disk while still differing in memory.
+ */
+export declare function setOrDelete(field: Field, key: string, val: unknown): Field;
+/**
+ * Rebuild the full field array with one cell changed at `realIndex`.
+ *
+ * Rebuilds every entry by index rather than splicing, so fields at other indices are returned
+ * untouched and order is preserved. An out-of-range index is a no-op returning an equal array.
+ */
+export declare function updateFieldAt(fields: readonly Field[], realIndex: number, key: string, val: unknown): Field[];

package/dist/runtime/app/components/docbuilderFields.js

@@ -0,0 +1,10 @@
+export function setOrDelete(field, key, val) {
+  if (val === void 0) {
+    const { [key]: _omit, ...rest } = field;
+    return rest;
+  }
+  return { ...field, [key]: val };
+}
+export function updateFieldAt(fields, realIndex, key, val) {
+  return fields.map((f, i) => i === realIndex ? setOrDelete(f, key, val) : f);
+}

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

@@ -1,30 +1,13 @@
-import type { ActionEventPayload } from '@stonecrop/desktop';
 /**
- * Result of dispatching an action to its server handler.
- */
-export type ActionDispatchResult = {
-    success: boolean;
-    data: unknown;
-    error: string | null;
-};
-/**
- * Shared executor for doctype action clicks. A host's Desktop `@action` handler delegates
- * here so every host runs the same logic from one definition:
- *
- * - If the clicked action carries a `clientHandler`, run it. The handler **owns
- *   orchestration** — it calls `runAction` itself when it needs the server, navigates via
- *   `router`, reads `record`, or queries `graphql`. It supersedes the default dispatch.
- * - Otherwise dispatch the action to its server `handler` (the pre-existing behavior),
- *   so actions without a `clientHandler` are unchanged.
+ * The shared action executor, re-exported so Nuxt hosts keep getting it as an auto-import.
  *
- * `runAction` is the only blessed write: it dispatches **and** writes the returned record
- * back into HST, keeping the store consistent — the same invariant the host handler
- * previously upheld inline (`addRecord(result.data)` after dispatch).
+ * It used to be defined here, which made the one blessed write path a Nuxt-only privilege while
+ * every other Vue host hand-rolled sixty lines of identity reconciliation — and both hosts that
+ * did got the create case wrong in the same way. Nothing in it was ever Nuxt-specific, so it now
+ * lives in `@stonecrop/stonecrop` alongside the store it writes to.
  *
- * The composable owns the `[{ id, data }]` argument envelope every server handler reads
- * (`const [{ id }] = args`), so an authored handler calls `runAction('Assign')` without
- * knowing that shape; an optional second argument is merged in for handlers needing more.
+ * This file stays because `addImportsDir` scans this directory: deleting it would silently remove
+ * the auto-import that every scaffolded app's `@action="run"` binding depends on.
  */
-export declare function useClientAction(): {
-    run: (payload: ActionEventPayload) => Promise<void>;
-};
+export { useClientAction } from '@stonecrop/stonecrop';
+export type { ActionArgsContext, ActionDispatchResult, ActionFailure, FollowRecordContext, UseClientActionOptions, } from '@stonecrop/stonecrop';

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

@@ -1,51 +1 @@
-import { executeClientHandler, useStonecrop } from "@stonecrop/stonecrop";
-import { useRouter } from "vue-router";
-function notifyActionError(message) {
-  console.error("Action failed:", message);
-  if (typeof window !== "undefined") window.alert(message);
-}
-export function useClientAction() {
-  const { stonecrop } = useStonecrop();
-  const router = useRouter();
-  async function dispatchAndWriteback(doctypeSlug, recordId, data, action, extra) {
-    const sc = stonecrop.value;
-    if (!sc) return { success: false, data: null, error: "Stonecrop is not initialized" };
-    const doctype = sc.registry.getDoctype(doctypeSlug);
-    if (!doctype) return { success: false, data: null, error: `Unknown doctype: ${doctypeSlug}` };
-    const result = await sc.dispatchAction(doctype, action, [{ id: recordId, data, ...extra ?? {} }]);
-    if (result.success && result.data && recordId) {
-      sc.addRecord(doctypeSlug, recordId, result.data);
-    }
-    return result;
-  }
-  async function run(payload) {
-    const sc = stonecrop.value;
-    if (!sc) return;
-    const { name, doctype: doctypeSlug, recordId, data } = payload;
-    const doctype = sc.registry.getDoctype(doctypeSlug);
-    const workflow = doctype?.workflow;
-    const clientHandler = workflow?.actions?.[name]?.clientHandler;
-    try {
-      if (!clientHandler) {
-        const result = await dispatchAndWriteback(doctypeSlug, recordId, data, name);
-        if (!result.success) notifyActionError(result.error ?? `Action "${name}" failed`);
-        return;
-      }
-      const record = sc.getRecordById(doctypeSlug, recordId)?.get("") ?? data;
-      const runAction = (action, extra) => dispatchAndWriteback(doctypeSlug, recordId, data, action, extra);
-      const graphql = {
-        query(query, variables) {
-          const client = sc.getClient();
-          if (!client?.query) {
-            return Promise.reject(new Error("The configured data client does not support graphql.query"));
-          }
-          return client.query(query, variables);
-        }
-      };
-      await executeClientHandler(clientHandler, { router, record, runAction, graphql });
-    } catch (error) {
-      notifyActionError(error instanceof Error ? error.message : String(error));
-    }
-  }
-  return { run };
-}
+export { useClientAction } from "@stonecrop/stonecrop";

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

@@ -95,6 +95,11 @@ export declare function useStonecropRegistry(): {
      * Dispatch an action to the server via the configured data client.
      * All state changes flow through this single mutation endpoint.
      *
+     * This is the raw dispatch: it returns the result and writes nothing to the store. Prefer
+     * `useClientAction`, which also runs a declared `clientHandler` and writes the result back
+     * under the identity the *server* settled on — storing it under the id you dispatched
+     * strands a newly created record under a key nothing can fetch.
+     *
      * @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')
@@ -121,7 +126,7 @@ export declare function useStonecropRegistry(): {
     }>;
     /**
      * Set the `getMeta` function on the Registry.
-     * Called by `useStonecrop()` to lazy-load doctype metadata for the current route.
+     * Called by `useStonecrop({ doctype: 'slug' })` to lazy-load that doctype's metadata.
      *
      * You must bridge `RouteContext` → `DoctypeContext`:
      * - Extract doctype name from `segments` (e.g., `segments[0]`)

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

@@ -57,6 +57,11 @@ export function useStonecropRegistry() {
      * Dispatch an action to the server via the configured data client.
      * All state changes flow through this single mutation endpoint.
      *
+     * This is the raw dispatch: it returns the result and writes nothing to the store. Prefer
+     * `useClientAction`, which also runs a declared `clientHandler` and writes the result back
+     * under the identity the *server* settled on — storing it under the id you dispatched
+     * strands a newly created record under a key nothing can fetch.
+     *
      * @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')
@@ -93,7 +98,7 @@ export function useStonecropRegistry() {
     },
     /**
      * Set the `getMeta` function on the Registry.
-     * Called by `useStonecrop()` to lazy-load doctype metadata for the current route.
+     * Called by `useStonecrop({ doctype: 'slug' })` to lazy-load that doctype's metadata.
      *
      * You must bridge `RouteContext` → `DoctypeContext`:
      * - Extract doctype name from `segments` (e.g., `segments[0]`)

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

@@ -72,7 +72,7 @@ export declare function useStonecropSetup(): {
     registerClient(client: DataClient): void;
     /**
      * Set the `getMeta` function on the Registry.
-     * Called by `useStonecrop()` to lazy-load doctype metadata for the current route.
+     * Called by `useStonecrop({ doctype: 'slug' })` to lazy-load that doctype's metadata.
      *
      * You must bridge `RouteContext` → `DoctypeContext`:
      * - Extract doctype name from `segments` (e.g., `segments[0]`)

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

@@ -47,7 +47,7 @@ export function useStonecropSetup() {
     },
     /**
      * Set the `getMeta` function on the Registry.
-     * Called by `useStonecrop()` to lazy-load doctype metadata for the current route.
+     * Called by `useStonecrop({ doctype: 'slug' })` to lazy-load that doctype's metadata.
      *
      * You must bridge `RouteContext` → `DoctypeContext`:
      * - Extract doctype name from `segments` (e.g., `segments[0]`)

package/dist/runtime/server/api/docbuilder/mergeDoctype.d.ts

@@ -9,3 +9,28 @@
  * the intended one: re-imposing it keeps saves byte-stable while still honouring adds/removes.
  */
 export declare function orderKeysByReference<T>(next: Record<string, T> | undefined, reference: Record<string, T> | undefined): Record<string, T> | undefined;
+/** The subset of the save request body this merge reads. Extra keys are ignored, not written. */
+export interface SaveDoctypeBody {
+    fields: unknown[];
+    workflow?: unknown;
+}
+/**
+ * Build the object the docbuilder save writes to disk, from the file already there plus the
+ * builder's submission.
+ *
+ * This is the last of four hops that must each preserve keys the builder never displays — the
+ * graph edit, the actions-panel edit, the fields-panel edit, then this. The invariant has already
+ * regressed twice upstream (once dropping `clientHandler`, once dropping `triggers`), both times
+ * because a hop enumerated named keys instead of spreading, so it is worth stating exactly what
+ * this hop does and does not guarantee:
+ *
+ * - **Top-level keys survive** by spread. Anything on disk that the builder doesn't model —
+ *   `links`, `primaryKey`, `source`, a consumer's own key — is carried through untouched.
+ * - **Field-level keys are NOT this hop's job.** `fields` is replaced wholesale with what the
+ *   client sent, so a key dropped in the browser is dropped here too. Hop 3 owns that.
+ *
+ * @param existing - The parsed doctype already on disk, or `{}` when creating one
+ * @param body - The builder's submission
+ * @param requestedName - The slug the builder asked to save, used only as a `name` fallback
+ */
+export declare function mergeSavedDoctype(existing: Record<string, unknown>, body: SaveDoctypeBody, requestedName: string): Record<string, unknown>;

package/dist/runtime/server/api/docbuilder/mergeDoctype.js

@@ -10,3 +10,21 @@ export function orderKeysByReference(next, reference) {
   }
   return result;
 }
+export function mergeSavedDoctype(existing, body, requestedName) {
+  const doctypeData = {
+    ...existing,
+    fields: body.fields
+  };
+  if (body.workflow !== void 0 && body.workflow !== null) {
+    const existingActions = existing.workflow?.actions;
+    const workflow = body.workflow;
+    doctypeData.workflow = workflow.actions ? { ...workflow, actions: orderKeysByReference(workflow.actions, existingActions) } : workflow;
+  } else if (doctypeData.workflow === null || doctypeData.workflow === void 0) {
+    delete doctypeData.workflow;
+  }
+  if (typeof doctypeData.name !== "string" || doctypeData.name.length === 0) {
+    doctypeData.name = requestedName;
+  }
+  delete doctypeData.schema;
+  return doctypeData;
+}

package/dist/runtime/server/api/docbuilder/save.post.js

@@ -3,7 +3,7 @@ import { readFile, readdir, writeFile } from "node:fs/promises";
 import { basename, resolve } from "node:path";
 import { createError, defineEventHandler, readBody } from "h3";
 import { useRuntimeConfig } from "#imports";
-import { orderKeysByReference } from "./mergeDoctype.js";
+import { mergeSavedDoctype } from "./mergeDoctype.js";
 export default defineEventHandler(async (event) => {
   const body = await readBody(event);
   if (!body.doctype || typeof body.doctype !== "string") {
@@ -50,21 +50,7 @@ export default defineEventHandler(async (event) => {
     } catch {
     }
   }
-  const doctypeData = {
-    ...existing,
-    fields: body.fields
-  };
-  if (body.workflow !== void 0 && body.workflow !== null) {
-    const existingActions = existing.workflow?.actions;
-    const workflow = body.workflow;
-    doctypeData.workflow = workflow.actions ? { ...workflow, actions: orderKeysByReference(workflow.actions, existingActions) } : workflow;
-  } else if (doctypeData.workflow === null || doctypeData.workflow === void 0) {
-    delete doctypeData.workflow;
-  }
-  if (typeof doctypeData.name !== "string" || doctypeData.name.length === 0) {
-    doctypeData.name = requested;
-  }
-  delete doctypeData.schema;
+  const doctypeData = mergeSavedDoctype(existing, body, requested);
   try {
     await writeFile(filePath, JSON.stringify(doctypeData, null, "	") + "\n", "utf-8");
     return { success: true, path: `doctypes/${basename(filePath)}` };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/nuxt",
-  "version": "0.16.6",
+  "version": "0.18.0",
   "description": "Nuxt module for Stonecrop",
   "repository": {
     "type": "git",
@@ -45,18 +45,18 @@
     "pathe": "^2.0.3",
     "pinia": "^3.0.4",
     "prompts": "^2.4.2",
-    "@stonecrop/aform": "0.16.6",
-    "@stonecrop/desktop": "0.16.6",
-    "@stonecrop/casl-middleware": "0.16.6",
-    "@stonecrop/graphql-client": "0.16.6",
-    "@stonecrop/code-editor": "0.16.6",
-    "@stonecrop/graphql-middleware": "0.16.6",
-    "@stonecrop/node-editor": "0.16.6",
-    "@stonecrop/schema": "0.16.6",
-    "@stonecrop/nuxt-grafserv": "0.16.6",
-    "@stonecrop/stonecrop": "0.16.6",
-    "@stonecrop/themes": "0.16.6",
-    "@stonecrop/atable": "0.16.6"
+    "@stonecrop/aform": "0.18.0",
+    "@stonecrop/casl-middleware": "0.18.0",
+    "@stonecrop/atable": "0.18.0",
+    "@stonecrop/code-editor": "0.18.0",
+    "@stonecrop/desktop": "0.18.0",
+    "@stonecrop/graphql-client": "0.18.0",
+    "@stonecrop/node-editor": "0.18.0",
+    "@stonecrop/graphql-middleware": "0.18.0",
+    "@stonecrop/nuxt-grafserv": "0.18.0",
+    "@stonecrop/schema": "0.18.0",
+    "@stonecrop/stonecrop": "0.18.0",
+    "@stonecrop/themes": "0.18.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -103,7 +103,7 @@
     "prepublish": "rushx dev:prepare && nuxt-module-build build",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage.enabled --coverage.provider=istanbul",
-    "test:types": "vue-tsc --noEmit -p tsconfig.runtime.json && cd playground && vue-tsc --noEmit && cd ../fullstack && vue-tsc --noEmit && vue-tsc --noEmit -p server/tsconfig.json",
+    "test:types": "vue-tsc --noEmit -p tsconfig.runtime.json && vue-tsc --noEmit -p tsconfig.templates-app.json && vue-tsc --noEmit -p tsconfig.templates-server.json && cd playground && vue-tsc --noEmit && cd ../fullstack && vue-tsc --noEmit && vue-tsc --noEmit -p server/tsconfig.json",
     "test:ui": "vitest --ui",
     "test:watch": "vitest watch"
   }

package/templates/Project.json

@@ -39,7 +39,8 @@
 		"actions": {
 			"save": {
 				"label": "Save",
-				"stateless": true
+				"stateless": true,
+				"selfTransition": true
 			},
 			"archive": {
 				"label": "Archive Project",

package/templates/Task.json

@@ -51,6 +51,11 @@
 		"actions": {
 			"save": {
 				"label": "Save",
+				"stateless": true,
+				"selfTransition": true
+			},
+			"snooze": {
+				"label": "Snooze a Week",
 				"stateless": true
 			},
 			"start_task": {

package/templates/index.vue

@@ -1,11 +1,6 @@
 <template>
 	<ClientOnly>
-		<Desktop
-			:available-doctypes="availableDoctypes"
-			:route-adapter="routeAdapter"
-			@action="handleAction"
-			@load-records="handleLoadRecords"
-			@load-record="handleLoadRecord" />
+		<Desktop :available-doctypes="availableDoctypes" :route-adapter="routeAdapter" @action="run" />
 		<template #fallback>
 			<div class="sc-loading">
 				<p>Loading...</p>
@@ -15,76 +10,24 @@
 </template>
 
 <script setup lang="ts">
-import {
-	Desktop,
-	type ActionEventPayload,
-	type LoadRecordEventPayload,
-	type LoadRecordsEventPayload,
-} from '@stonecrop/desktop'
-import { useStonecrop } from '@stonecrop/stonecrop'
+import { Desktop } from '@stonecrop/desktop'
 
 import { useRouteAdapter } from '~/composables/useRouteAdapter'
-import {
-	doctypeMap,
-	useDoctypeConfig,
-	fetchDoctypeRecords,
-	fetchDoctypeRecord,
-	runDoctypeAction,
-} from '~/composables/useDoctypes'
+import { doctypeMap } from '~/composables/useDoctypes'
 
 const routeAdapter = useRouteAdapter()
-const { stonecrop } = useStonecrop()
-
+// Shared action executor, auto-imported from @stonecrop/nuxt: it runs an action's clientHandler
+// when the doctype declares one, otherwise dispatches to the server, and writes the result back
+// into the store under the identity the server settled on — a Save against a record that does not
+// exist creates it, so that identity is not always the one the form dispatched. Bound straight to
+// Desktop's @action; a host-written wrapper would have to restate all of that.
+const { run } = useClientAction()
+
+// Reads are not bound here either. The StonecropClient registered in `stonecrop.client.ts` is this
+// app's whole data layer: Stonecrop fetches through it and keys each result by the doctype's
+// declared identity. A handler here would only race that fetch with a second copy of the same rule,
+// which is how a hardcoded `record.id` once dropped every row of a natural-keyed doctype.
 const availableDoctypes = computed(() => Array.from(doctypeMap.keys()))
-
-async function handleLoadRecords(payload: LoadRecordsEventPayload) {
-	const doctypeConfig = useDoctypeConfig(payload.doctype)
-	if (!doctypeConfig || !stonecrop.value) return
-
-	try {
-		const { data } = await fetchDoctypeRecords({ name: doctypeConfig.name })
-		for (const record of data) {
-			const recordId = record.id as string
-			if (recordId) stonecrop.value.addRecord(payload.doctype, recordId, record)
-		}
-	} catch (error) {
-		console.error('Failed to load records:', error)
-	}
-}
-
-async function handleLoadRecord(payload: LoadRecordEventPayload) {
-	if (!stonecrop.value || payload.recordId.startsWith('new-')) return
-
-	const doctypeConfig = useDoctypeConfig(payload.doctype)
-	if (!doctypeConfig) return
-
-	try {
-		const record = await fetchDoctypeRecord({ name: doctypeConfig.name }, payload.recordId)
-		if (record) stonecrop.value.addRecord(payload.doctype, payload.recordId, record)
-	} catch (error) {
-		console.error('Failed to load record:', error)
-	}
-}
-
-async function handleAction(payload: ActionEventPayload) {
-	const doctypeConfig = useDoctypeConfig(payload.doctype)
-	if (!doctypeConfig) return
-
-	try {
-		const result = await runDoctypeAction(doctypeConfig, payload.name, {
-			id: payload.recordId,
-			data: payload.data,
-		})
-
-		if (result.success && result.data && stonecrop.value && payload.recordId) {
-			stonecrop.value.addRecord(payload.doctype, payload.recordId, result.data as Record<string, unknown>)
-		}
-
-		if (!result.success) console.error('Action failed:', result.error)
-	} catch (error) {
-		console.error('Action error:', error)
-	}
-}
 </script>
 
 <style>

package/templates/plugins.ts

@@ -5,7 +5,10 @@
  * @see https://grafast.org/grafserv/plugins
  */
 
-import type { GraphileConfig } from 'graphile-config'
+// `GraphileConfig` is an ambient global declared by graphile-config's own types, so it needs no
+// import. The `import type { GraphileConfig } from 'graphile-config'` that used to be here never
+// resolved — graphile-config is an optional peer dependency, so it is not installed — and an
+// unresolved type silently degrades everything annotated with it to `any`.
 
 /**
  * Example: Request logging plugin
@@ -17,9 +20,13 @@ const loggingPlugin: GraphileConfig.Plugin = {
 		middleware: {
 			processGraphQLRequestBody: async (next, event) => {
 				const start = Date.now()
+
+				// `event.request` is optional: a GraphQL-over-WebSocket message carries no HTTP request.
+				// It is grafserv's own RequestDigest, not a Web `Request` — the path lives on `path`
+				// (there is no `url`), and headers are read with `getHeader()`, not `headers.get()`.
 				console.log('[GraphQL] Request started:', {
-					path: event.request.url,
-					method: event.request.method,
+					path: event.request?.path,
+					method: event.request?.method,
 				})
 
 				const result = await next()
@@ -42,8 +49,9 @@ const _authPlugin: GraphileConfig.Plugin = {
 	grafserv: {
 		middleware: {
 			processGraphQLRequestBody: async (next, event) => {
-				// Extract authentication from headers
-				const authHeader = event.request.headers.get('authorization')
+				// Extract authentication from headers. See the logging plugin above for why `request`
+				// is optional and why this is `getHeader()` rather than `headers.get()`.
+				const authHeader = event.request?.getHeader('authorization')
 
 				if (authHeader?.startsWith('Bearer ')) {
 					const token = authHeader.slice(7)
@@ -60,18 +68,29 @@ const _authPlugin: GraphileConfig.Plugin = {
 }
 
 /**
- * Export all plugins
- * Import these in your nuxt.config.ts:
+ * Export all plugins.
+ *
+ * Reference them from your PostGraphile preset file — `grafserv.preset` is a **path to that file**,
+ * not an inline object. Inline presets are not supported: Nitro's build/runtime split cannot
+ * serialize the functions and plugin instances a preset contains.
+ *
+ * ```ts
+ * // server/graphile.preset.ts
+ * import { createStonecropPreset, makePgService, createStonecropPlugin } from '@stonecrop/graphql-middleware'
+ * import plugins from './plugins'
  *
- * import plugins from './server/plugins'
+ * export default {
+ *   extends: [createStonecropPreset()],
+ *   pgServices: [makePgService({ connectionString: process.env.DATABASE_URL, schemas: ['public'] })],
+ *   plugins: [createStonecropPlugin(), ...plugins],
+ * }
  *
+ * // nuxt.config.ts
  * export default defineNuxtConfig({
- *   grafserv: {
- *     preset: {
- *       plugins
- *     }
- *   }
+ *   modules: ['@stonecrop/nuxt-grafserv'],
+ *   grafserv: { type: 'postgraphile', preset: './server/graphile.preset.ts' },
  * })
+ * ```
  */
 export const plugins: GraphileConfig.Plugin[] = [
 	loggingPlugin,

package/templates/resolvers.ts

@@ -9,9 +9,10 @@
  * - loadOne($step, fn)        — batch-load data ASYNCHRONOUSLY (for DB queries)
  * - object({ ... })           — group multiple steps into a single step object
  *
- * Data reads go through loadOne. Workflow state transitions are applied by the
- * stonecropAction resolver itself (server-owns-transition, guarded by allowedStates);
- * side-effecting saves go through registered handlers (project:save, task:save).
+ * Data reads go through loadOne. Workflow outcomes are applied by the stonecropAction
+ * resolver itself (server-owns-transition, guarded by allowedStates), and anything a
+ * doctype cannot express — a Command with no state change — goes through the
+ * `actionHandlers` map below.
  *
  * To connect a real database, replace the imports from ./data with your
  * PostGraphile setup. See: https://stonecrop.io/docs/guides/postgraphile
@@ -19,7 +20,7 @@
 
 import { constant, lambda, loadOne, object } from 'grafast'
 import { getMeta, getAllMeta, applyGuardedTransition } from '@stonecrop/graphql-middleware'
-import { getPrimaryKeyField } from '@stonecrop/schema'
+import { getRecordIdField } from '@stonecrop/schema'
 import type { DoctypeMeta } from '@stonecrop/schema'
 import { projects, tasks, type Project, type Task } from './data'
 
@@ -68,12 +69,13 @@ export function formatDoctypeMeta(meta: DoctypeMeta) {
  *
  * The `id` fallback covers doctypes that declare no `primaryKey`. Every doctype in this repo now
  * declares one, enforced by test/doctype-fixtures.test.ts, so in-repo the fallback is inert.
- * It stays for consumer doctypes that have not adopted the rule: the Postgres adapter refuses
- * those outright (`data: null`), and this host stays permissive. The conformance suite records
- * that difference rather than asserting one answer.
+ * It stays for consumer doctypes that have not adopted the rule, and every host now applies it —
+ * the Postgres adapter used to omit it and refuse those doctypes outright, which is what made the
+ * hosts disagree. This is a thin wrapper on the shared rule, kept for the `meta`-shaped signature
+ * the resolvers call it with.
  */
 export function recordLookupField(meta: DoctypeMeta): string {
-	return getPrimaryKeyField(meta.fields)?.fieldname ?? 'id'
+	return getRecordIdField(meta.fields)
 }
 
 function getRecord(doctype: string, id: string, lookupField = 'id'): Project | Task | null {
@@ -91,6 +93,19 @@ function getRecord(doctype: string, id: string, lookupField = 'id'): Project | T
 	return null
 }
 
+/**
+ * Write a record into its store under `key`.
+ *
+ * `key` is the record's identity under the doctype's declared `primaryKey` — the same field
+ * `getRecord` matches against — so the store is keyed by whatever the doctype says identifies a
+ * record, not by a hardcoded `id`. Both doctypes here declare `id`, so the two coincide today.
+ */
+function setRecord(doctype: string, key: string, record: Record<string, unknown>): void {
+	const d = doctype.toLowerCase()
+	if (d === 'project') projects.set(key, record as unknown as Project)
+	else if (d === 'task') tasks.set(key, record as unknown as Task)
+}
+
 function getRecords(doctype: string, filters?: Record<string, unknown>): (Project | Task)[] {
 	const d = doctype.toLowerCase()
 	if (d === 'project') {
@@ -113,6 +128,51 @@ function nextId(doctype: string): string {
 	return String(max + 1)
 }
 
+// ============================================================
+// Server-side action effects
+// ============================================================
+// A doctype's workflow says whether an action may run (`allowedStates`) and what state results
+// (`nextState`, `selfTransition`). It deliberately says nothing about what the action *does*: a
+// doctype is runtime data edited in DocBuilder, and it must not name server code a different
+// author owns. So the routing from action to effect lives here, keyed `[doctype name][action
+// key]`, and is never published to the client.
+//
+// This is what makes a Command executable at all. An action with no `nextState` and no
+// `selfTransition` has nothing for the dispatcher to apply, and without an entry here it fails
+// loudly rather than reporting a false success.
+//
+// Add your own by registering under the doctype's `name`. Throwing rejects the action; returning
+// the updated record makes it the client writeback payload.
+
+type ActionHandler = (context: {
+	recordId?: string
+	/** Record field data the client sent. Unvalidated browser input — validate before trusting it. */
+	data: Record<string, unknown>
+	/** The state the guard read, or undefined when nothing about the action required reading it. */
+	currentState?: string
+}) => Promise<unknown>
+
+export const actionHandlers: Record<string, Record<string, ActionHandler>> = {
+	Task: {
+		/**
+		 * Push the due date out by a week.
+		 *
+		 * The example is deliberately a *stateless* command: snoozing does not move the task
+		 * through its workflow, so there is no state for the doctype to declare — only an effect.
+		 */
+		async snooze({ recordId }) {
+			const task = recordId != null ? tasks.get(recordId) : undefined
+			if (!task) throw new Error(`Task ${recordId ?? '(none)'} not found`)
+
+			const from = task.dueDate ? new Date(task.dueDate) : new Date()
+			from.setDate(from.getDate() + 7)
+			const updated: Task = { ...task, dueDate: from.toISOString().slice(0, 10) }
+			tasks.set(task.id, updated)
+			return Promise.resolve(updated)
+		},
+	},
+}
+
 // ============================================================
 // Resolvers (Grafast plan format)
 // ============================================================
@@ -154,7 +214,7 @@ export const resolvers = {
 				})
 			},
 
-			stonecropRecords(_: unknown, { $doctype, $filters, $orderBy, $limit, $offset, $options }: any) {
+			stonecropRecords(_: unknown, { $doctype, $filters, $orderBy, $limit, $offset, $includeTotal, $options }: any) {
 				return loadOne(
 					object({
 						doctype: $doctype,
@@ -162,6 +222,7 @@ export const resolvers = {
 						orderBy: $orderBy,
 						limit: $limit,
 						offset: $offset,
+						includeTotal: $includeTotal,
 						options: $options,
 					}),
 					async (specs: readonly any[]) => {
@@ -169,10 +230,15 @@ export const resolvers = {
 							const all = getRecords(spec.doctype, spec.filters ?? {})
 							const offset = spec.offset ?? 0
 							const limit = spec.limit ?? 100
+							const page = all.slice(offset, offset + limit)
 							return {
-								data: all.slice(offset, offset + limit),
+								data: page,
 								doctype: spec.doctype,
-								count: all.length,
+								hasMore: offset + page.length < all.length,
+								// This store is in memory, so counting is free — but it stays opt-in anyway,
+								// because the scaffold is what a real adapter gets copied from and a backend
+								// that answers a total nobody asked for teaches the wrong default.
+								count: spec.includeTotal === true ? all.length : null,
 							}
 						})
 					}
@@ -201,6 +267,11 @@ export const resolvers = {
 								const recordId = argList[0]?.id != null ? String(argList[0].id) : undefined
 								const recordData: Record<string, unknown> = argList[0]?.data ?? {}
 								const d = spec.doctype.toLowerCase()
+								const handler = actionHandlers[meta.name]?.[String(spec.action)]
+								// The field a record is identified by. The read path already resolved records
+								// through this; the action path used to assume `id`, so an action on a
+								// natural-keyed doctype looked up a key the client never sent.
+								const lookupField = recordLookupField(meta)
 
 								try {
 									// The server owns the transition: read current state, guard against allowedStates,
@@ -210,28 +281,61 @@ export const resolvers = {
 										actionDef,
 										{
 											readState: async () => {
-												if (recordId == null) return undefined
-												const record = getRecord(d, recordId)
-												return record?.status == null ? undefined : String(record.status)
+												// `null` means "no such record" and `undefined` means "exists, no
+												// state" — the dispatcher rejects the first outright. Returning
+												// `undefined` for both is what let a Save on a record that was
+												// never created report success while persisting nothing.
+												if (recordId == null) return null
+												const record = getRecord(d, recordId, lookupField)
+												if (!record) return null
+												return record.status == null ? undefined : String(record.status)
 											},
 											writeState: async (nextState: string) => {
 												if (recordId == null) return
-												const existing = getRecord(d, recordId)
+												const existing = getRecord(d, recordId, lookupField)
 												if (!existing) return
-												if (d === 'project') projects.set(recordId, { ...existing, status: nextState } as Project)
-												else if (d === 'task') tasks.set(recordId, { ...existing, status: nextState } as Task)
+												setRecord(d, recordId, { ...existing, status: nextState })
 											},
-											// Self-transition data write: merge the edited fields into the record (status
-											// untouched) and return the full record for the client writeback.
-											writeData: async (patch: Record<string, unknown>) => {
-												if (recordId == null) return {}
-												const existing = getRecord(d, recordId)
-												if (!existing) return {}
-												const updated = { ...existing, ...patch }
-												if (d === 'project') projects.set(recordId, updated as Project)
-												else if (d === 'task') tasks.set(recordId, updated as Task)
-												return updated as Record<string, unknown>
+											// Save is an upsert, and it is the only write path — there is no create action
+											// and no create mutation. Updating merges the edited fields in place (status
+											// untouched); creating derives the identity from the doctype's declared
+											// primary key when the submitted data carries it, which is how a
+											// natural-keyed doctype is identified, and mints one only otherwise.
+											// Either way the full record comes back for the client writeback.
+											writeData: async (patch: Record<string, unknown>, exists: boolean) => {
+												if (exists) {
+													if (recordId == null) return {}
+													const existing = getRecord(d, recordId, lookupField)
+													if (!existing) return {}
+													const updated = { ...existing, ...patch }
+													setRecord(d, recordId, updated)
+													return updated as Record<string, unknown>
+												}
+
+												const declared = patch[lookupField]
+												const identity =
+													typeof declared === 'string' && declared !== ''
+														? declared
+														: typeof declared === 'number'
+															? String(declared)
+															: nextId(d)
+												const defaults =
+													d === 'project'
+														? { status: 'Active', description: '' }
+														: { status: 'Todo', description: '', dueDate: null }
+												const record = {
+													...defaults,
+													...patch,
+													[lookupField]: identity,
+													createdAt: new Date().toISOString(),
+												}
+												setRecord(d, identity, record)
+												return record
 											},
+											// The server-owned effect for this action, if one is registered above.
+											runEffect: handler
+												? (currentState: string | undefined) => handler({ recordId, data: recordData, currentState })
+												: undefined,
 										},
 										recordData
 									)
@@ -243,64 +347,6 @@ export const resolvers = {
 					}
 				)
 			},
-
-			stonecropCreate(_: unknown, { $doctype, $input }: any) {
-				return loadOne(object({ doctype: $doctype, input: $input }), async (specs: readonly any[]) => {
-					return specs.map(spec => {
-						const d = spec.doctype.toLowerCase()
-						const id = nextId(d)
-						const now = new Date().toISOString()
-						if (d === 'project') {
-							const record: Project = { id, createdAt: now, status: 'Active', description: '', ...spec.input }
-							projects.set(id, record)
-							return { data: record, doctype: spec.doctype }
-						}
-						if (d === 'task') {
-							const record: Task = { id, createdAt: now, status: 'Todo', description: '', dueDate: null, ...spec.input }
-							tasks.set(id, record)
-							return { data: record, doctype: spec.doctype }
-						}
-						return { data: null, doctype: spec.doctype }
-					})
-				})
-			},
-
-			stonecropUpdate(_: unknown, { $doctype, $id, $patch }: any) {
-				return loadOne(object({ doctype: $doctype, id: $id, patch: $patch }), async (specs: readonly any[]) => {
-					return specs.map(spec => {
-						const d = spec.doctype.toLowerCase()
-						const existing = getRecord(d, spec.id)
-						if (!existing) return null
-						if (d === 'project') {
-							const updated = { ...existing, ...spec.patch } as Project
-							projects.set(spec.id, updated)
-							return { data: updated, doctype: spec.doctype }
-						}
-						if (d === 'task') {
-							const updated = { ...existing, ...spec.patch } as Task
-							tasks.set(spec.id, updated)
-							return { data: updated, doctype: spec.doctype }
-						}
-						return null
-					})
-				})
-			},
-
-			stonecropDelete(_: unknown, { $doctype, $id }: any) {
-				return loadOne(object({ doctype: $doctype, id: $id }), async (specs: readonly any[]) => {
-					return specs.map(spec => {
-						const d = spec.doctype.toLowerCase()
-						let deleted = false
-						if (d === 'project') deleted = projects.delete(spec.id)
-						else if (d === 'task') deleted = tasks.delete(spec.id)
-						return {
-							success: deleted,
-							data: deleted ? { id: spec.id } : null,
-							error: deleted ? null : 'Record not found',
-						}
-					})
-				})
-			},
 		},
 	},
 }

package/templates/schema.graphql

@@ -89,7 +89,10 @@ type RecordResult {
 type RecordsResult {
 	data: [JSON!]!
 	doctype: String!
-	count: Int!
+	"Whether further records exist beyond this page."
+	hasMore: Boolean!
+	"Total matching the filters. Null unless the query asked for it with includeTotal."
+	count: Int
 }
 
 type ActionResult {
@@ -137,6 +140,7 @@ type Query {
 		orderBy: String
 		limit: Int
 		offset: Int
+		includeTotal: Boolean
 		options: JSON
 	): RecordsResult
 }
@@ -150,19 +154,4 @@ type Mutation {
 	Execute a doctype action
 	"""
 	stonecropAction(doctype: String!, action: String!, args: JSON): ActionResult!
-
-	"""
-	Create a new record
-	"""
-	stonecropCreate(doctype: String!, input: JSON!): RecordResult!
-
-	"""
-	Update an existing record
-	"""
-	stonecropUpdate(doctype: String!, id: String!, patch: JSON!): RecordResult
-
-	"""
-	Delete a record
-	"""
-	stonecropDelete(doctype: String!, id: String!): ActionResult!
 }

package/templates/useDoctypes.ts

@@ -1,6 +1,4 @@
-import type { DoctypeRef } from '@stonecrop/schema'
 import type { DoctypeConfig } from '@stonecrop/stonecrop'
-import { useNuxtApp } from 'nuxt/app'
 
 const modules = import.meta.glob<DoctypeConfig>('../../doctypes/*.json', {
 	eager: true,
@@ -22,32 +20,15 @@ export function useDoctypeConfig(slug: string): DoctypeConfig | undefined {
 	return doctypeMap.get(slug)
 }
 
-export async function fetchDoctypeRecords(doctype: DoctypeRef, limit = 200): Promise<{ data: any[]; count: number }> {
-	const { $stonecropClient } = useNuxtApp()
-	const data = (await $stonecropClient.getRecords({ name: doctype.name }, { limit })) as any[]
-	return { data, count: data.length }
-}
-
-export async function fetchDoctypeRecord(
-	doctype: DoctypeRef,
-	recordId: string
-): Promise<Record<string, unknown> | null> {
-	const { $stonecropClient } = useNuxtApp()
-	const result = await $stonecropClient.getRecord(doctype, recordId)
-	return result.record
-}
-
-export interface ActionResult {
-	success: boolean
-	data?: unknown
-	error?: string | null
-}
-
-export async function runDoctypeAction(
-	doctype: DoctypeConfig,
-	action: string,
-	args: { id: string; data?: Record<string, unknown> }
-): Promise<ActionResult> {
-	const { $stonecropClient } = useNuxtApp()
-	return $stonecropClient.runAction({ name: doctype.name }, action, [args])
-}
+// There are deliberately no fetch helpers here. Fetching is not the whole job: the result has to
+// land in the store under the identity the doctype declares, and something has to decide whether a
+// read is warranted at all. `Stonecrop.getRecord`/`getRecords` own all of it and reach your backend
+// through the client registered in `stonecrop.client.ts` — call those instead.
+//
+// The pair that used to live here also hardcoded `limit = 200`, which is a decision about what the
+// backend can afford and therefore the server's to make, not a page's.
+
+// Actions are deliberately not dispatched from here. Dispatching is only half the job: the result
+// has to land in the store under the identity the server settled on, which is not always the id
+// that was dispatched — a Save against a record that does not exist creates one. `useClientAction`
+// (auto-imported from @stonecrop/nuxt) owns both halves; app/pages/index.vue binds it directly.