feat: named page actions with per-mutation type safety

Export `actions` (plural) from .server.ts for pages with multiple mutations.
Each named action gets its own typed validator, body type, and error keys.

- Scanner detects `actions` export alongside existing `action`
- Codegen emits pre-processed mapped types (no action key parsing needed)
- Runtime dispatches via `?actionName` query string suffix
- `useForm("/path?action", defaults)` and `action("/path?action", data)`
- Template literal types parse `?name` suffix for per-action type resolution
- Module-level `setActionRouter()` for `action()` helper in all adapters
- Migrated pg-test playground from intent pattern to named actions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: yyx990803

docs/guide/type-safety.md

@@ -162,7 +162,42 @@ const form = useForm("/users/:id", { name: "" }, { params: { id: "42" } });
 form.put(); // submits to /users/42
 ```
 
-Actions without validators still get URL autocomplete — the body falls back to `Record<string, unknown>`. See [Pages Routing — Forms](./pages-routing/forms) for the full API.
+Actions without validators still get URL autocomplete — the body falls back to `Record<string, unknown>`. See [Pages Routing — Forms](./pages-routing/actions-and-forms) for the full API.
+
+### Named Actions
+
+When a page exports [named actions](./pages-routing/actions-and-forms#named-actions), each action gets its own typed validator. The `?actionName` suffix on the URL selects the correct types:
+
+```ts
+// pages/users/edit.server.ts
+export const actions = {
+  update: defineHandler.withValidator({
+    body: updateUserSchema,
+  })(async (c, { body }) => {
+    await db
+      .update(users)
+      .set(body)
+      .where(eq(users.id, c.req.param("id")));
+  }),
+
+  delete: defineHandler.withValidator({
+    body: z.object({ id: z.string() }),
+  })(async (c, { body }) => {
+    await db.delete(users).where(eq(users.id, body.id));
+  }),
+};
+```
+
+```ts
+// Component
+const updateForm = useForm("/users/:id?update", { name: "", email: "" }, { params: { id } });
+updateForm.errors.email; // typed from updateUserSchema
+
+const deleteForm = useForm("/users/:id?delete", { id: "" }, { params: { id } });
+deleteForm.errors.id; // typed from the delete schema
+```
+
+The `action()` helper gets the same type checking — URLs, data payloads, and dynamic params are all validated at compile time.
 
 ## What Gets Checked
 
@@ -172,6 +207,7 @@ Actions without validators still get URL autocomplete — the body falls back to
 | Handlers     | `c.env` bindings, validator input, return type                                                   |
 | Fetch client | Route paths, HTTP methods, `body`/`query`/`params`, response type                                |
 | `useForm`    | Page action URLs, `data` fields, `errors` keys, `reset()`/`clearErrors()` args, dynamic `params` |
+| `action()`   | Page action URLs, `data` payload, dynamic `params`                                               |
 
 ## Serialization
 

packages/react/src/plugin-pages.ts

@@ -198,7 +198,7 @@ function generateClientEntry(
 import React, { useSyncExternalStore } from "react";
 import { hydrateRoot } from "react-dom/client";
 import { flushSync } from "react-dom";
-import { SharedContext, ErrorsContext, RouterContext } from "@void-x/react/runtime";
+import { SharedContext, ErrorsContext, RouterContext, setActionRouter } from "@void-x/react/runtime";
 import { createPageRouter } from "void/pages-client";
 import { parseCacheFor } from "void/pages-prefetch";
 
@@ -254,6 +254,8 @@ const { router, initialPageData, initialComponent, initialLayouts, start } =
     prefetchDefaultCacheFor: parseCacheFor(${JSON.stringify(prefetch?.cacheFor ?? "30s")}),
   });
 
+setActionRouter(router);
+
 state = {
   component: initialComponent,
   props: initialPageData.props,

packages/react/src/runtime/action.ts

@@ -0,0 +1,47 @@
+import type {
+  ActionUrl,
+  ResolveActionBody,
+  ResolveActionParams,
+  HasActionParams,
+} from "void/routes";
+
+type ActionOptions<U extends string> =
+  HasActionParams<U> extends true ? { params: ResolveActionParams<U> } : { params?: never };
+
+let _router: any = null;
+
+/** Called during app initialization to store the router instance */
+export function setActionRouter(router: any): void {
+  _router = router;
+}
+
+/** Programmatic one-shot page action call with Inertia page update */
+export async function action<U extends ActionUrl & string>(
+  url: U,
+  ...args: HasActionParams<U> extends true
+    ? [data?: ResolveActionBody<U>, options?: ActionOptions<U>]
+    : [data?: ResolveActionBody<U>]
+): Promise<void> {
+  if (!_router) throw new Error("action() called before router initialized");
+
+  const data = args[0];
+  const options = args[1] as ActionOptions<U> | undefined;
+
+  let resolvedUrl: string = url;
+  let actionQuery = "";
+
+  const qIdx = resolvedUrl.indexOf("?");
+  if (qIdx !== -1) {
+    actionQuery = resolvedUrl.slice(qIdx);
+    resolvedUrl = resolvedUrl.slice(0, qIdx);
+  }
+
+  if ((options as any)?.params) {
+    for (const [key, value] of Object.entries((options as any).params)) {
+      resolvedUrl = resolvedUrl.replace(`:${key}`, encodeURIComponent(value as string));
+    }
+  }
+
+  resolvedUrl = resolvedUrl + actionQuery;
+  await _router.visit(resolvedUrl, { method: "POST", data });
+}

packages/react/src/runtime/index.ts

@@ -4,4 +4,5 @@ export { useShared } from "./use-shared";
 export { useForm } from "./use-form";
 export { useNavigation } from "./use-navigation";
 export { useIslandForm } from "./use-island-form";
+export { action, setActionRouter } from "./action";
 export { SharedContext, ErrorsContext, RouterContext } from "./context";

packages/react/src/runtime/use-form.ts

@@ -1,30 +1,19 @@
 import { useState, useRef, useCallback, useContext, useMemo } from "react";
-import type { PageActionMap } from "void/routes";
+import type { ActionUrl, ResolveActionBody, ActionFormOptions } from "void/routes";
 import { RouterContext } from "./context";
 
-type HasParams<U extends keyof PageActionMap> = PageActionMap[U] extends { params: infer P }
-  ? P extends Record<string, string>
-    ? true
-    : false
-  : false;
-
-type FormOptions<U extends keyof PageActionMap> =
-  HasParams<U> extends true
-    ? { params: PageActionMap[U] extends { params: infer P } ? P : never }
-    : { params?: never };
-
 // Typed overload — full inference from PageActionMap (requires codegen)
-export function useForm<U extends keyof PageActionMap & string>(
+export function useForm<U extends ActionUrl & string>(
   url: U,
-  defaults: PageActionMap[U]["body"],
-  options?: FormOptions<U>,
+  defaults: ResolveActionBody<U>,
+  options?: ActionFormOptions<U>,
 ): {
-  data: PageActionMap[U]["body"];
-  setData: <K extends keyof PageActionMap[U]["body"] & string>(
+  data: ResolveActionBody<U>;
+  setData: <K extends keyof ResolveActionBody<U> & string>(
     field: K,
-    value: PageActionMap[U]["body"][K],
+    value: ResolveActionBody<U>[K],
   ) => void;
-  errors: Partial<Record<keyof PageActionMap[U]["body"] & string, string>>;
+  errors: Partial<Record<keyof ResolveActionBody<U> & string, string>>;
   processing: boolean;
   isDirty: boolean;
   wasSuccessful: boolean;
@@ -33,8 +22,8 @@ export function useForm<U extends keyof PageActionMap & string>(
   put(opts?: any): void;
   patch(opts?: any): void;
   delete(opts?: any): void;
-  reset(...fields: (keyof PageActionMap[U]["body"] & string)[]): void;
-  clearErrors(...fields: (keyof PageActionMap[U]["body"] & string)[]): void;
+  reset(...fields: (keyof ResolveActionBody<U> & string)[]): void;
+  clearErrors(...fields: (keyof ResolveActionBody<U> & string)[]): void;
 };
 
 // Untyped fallback — manual generic for use without codegen
@@ -64,12 +53,23 @@ export function useForm(
   options?: { params?: Record<string, string> },
 ): any {
   let resolvedUrl = url;
+
+  // Strip ?action query before param resolution, then re-append
+  let actionQuery = "";
+  const qIdx = resolvedUrl.indexOf("?");
+  if (qIdx !== -1) {
+    actionQuery = resolvedUrl.slice(qIdx);
+    resolvedUrl = resolvedUrl.slice(0, qIdx);
+  }
+
   if (options?.params) {
     for (const [key, value] of Object.entries(options.params)) {
       resolvedUrl = resolvedUrl.replace(`:${key}`, encodeURIComponent(value));
     }
   }
 
+  resolvedUrl = resolvedUrl + actionQuery;
+
   const router = useContext(RouterContext);
   const [data, setDataState] = useState<Record<string, unknown>>({ ...defaults });
   const [errors, setErrors] = useState<Record<string, string>>({});

packages/solid/src/plugin-pages.ts

@@ -179,7 +179,7 @@ function generateClientEntry(
   return `
 import { createSignal, createComponent, batch } from "solid-js";
 import { hydrate } from "solid-js/web";
-import { SharedContext, ErrorsContext, RouterContext } from "@void-x/solid/runtime";
+import { SharedContext, ErrorsContext, RouterContext, setActionRouter } from "@void-x/solid/runtime";
 import { createPageRouter } from "void/pages-client";
 import { parseCacheFor } from "void/pages-prefetch";
 
@@ -217,6 +217,8 @@ const { router, initialPageData, initialComponent, initialLayouts, start } =
     prefetchDefaultCacheFor: parseCacheFor(${JSON.stringify(prefetch?.cacheFor ?? "30s")}),
   });
 
+setActionRouter(router);
+
 batch(() => {
   setComponent(() => initialComponent);
   setPageProps(initialPageData.props);

packages/solid/src/runtime/action.ts

@@ -0,0 +1,47 @@
+import type {
+  ActionUrl,
+  ResolveActionBody,
+  ResolveActionParams,
+  HasActionParams,
+} from "void/routes";
+
+type ActionOptions<U extends string> =
+  HasActionParams<U> extends true ? { params: ResolveActionParams<U> } : { params?: never };
+
+let _router: any = null;
+
+/** Called during app initialization to store the router instance */
+export function setActionRouter(router: any): void {
+  _router = router;
+}
+
+/** Programmatic one-shot page action call with Inertia page update */
+export async function action<U extends ActionUrl & string>(
+  url: U,
+  ...args: HasActionParams<U> extends true
+    ? [data?: ResolveActionBody<U>, options?: ActionOptions<U>]
+    : [data?: ResolveActionBody<U>]
+): Promise<void> {
+  if (!_router) throw new Error("action() called before router initialized");
+
+  const data = args[0];
+  const options = args[1] as ActionOptions<U> | undefined;
+
+  let resolvedUrl: string = url;
+  let actionQuery = "";
+
+  const qIdx = resolvedUrl.indexOf("?");
+  if (qIdx !== -1) {
+    actionQuery = resolvedUrl.slice(qIdx);
+    resolvedUrl = resolvedUrl.slice(0, qIdx);
+  }
+
+  if ((options as any)?.params) {
+    for (const [key, value] of Object.entries((options as any).params)) {
+      resolvedUrl = resolvedUrl.replace(`:${key}`, encodeURIComponent(value as string));
+    }
+  }
+
+  resolvedUrl = resolvedUrl + actionQuery;
+  await _router.visit(resolvedUrl, { method: "POST", data });
+}

packages/solid/src/runtime/index.ts

@@ -4,4 +4,5 @@ export { useShared } from "./use-shared";
 export { useForm } from "./use-form";
 export { useNavigation } from "./use-navigation";
 export { useIslandForm } from "./use-island-form";
+export { action, setActionRouter } from "./action";
 export { SharedContext, ErrorsContext, RouterContext } from "./context";

packages/solid/src/runtime/use-form.ts

@@ -1,31 +1,20 @@
 import { createSignal, createMemo, useContext } from "solid-js";
 import { createStore, reconcile } from "solid-js/store";
 import { RouterContext, ErrorsContext } from "./context";
-import type { PageActionMap } from "void/routes";
-
-type HasParams<U extends keyof PageActionMap> = PageActionMap[U] extends { params: infer P }
-  ? P extends Record<string, string>
-    ? true
-    : false
-  : false;
-
-type FormOptions<U extends keyof PageActionMap> =
-  HasParams<U> extends true
-    ? { params: PageActionMap[U] extends { params: infer P } ? P : never }
-    : { params?: never };
+import type { ActionUrl, ResolveActionBody, ActionFormOptions } from "void/routes";
 
 // Typed overload — full inference from PageActionMap (requires codegen)
-export function useForm<U extends keyof PageActionMap & string>(
+export function useForm<U extends ActionUrl & string>(
   url: U,
-  defaults: PageActionMap[U]["body"],
-  options?: FormOptions<U>,
+  defaults: ResolveActionBody<U>,
+  options?: ActionFormOptions<U>,
 ): {
-  data: PageActionMap[U]["body"];
-  setData: <K extends keyof PageActionMap[U]["body"] & string>(
+  data: ResolveActionBody<U>;
+  setData: <K extends keyof ResolveActionBody<U> & string>(
     field: K,
-    value: PageActionMap[U]["body"][K],
+    value: ResolveActionBody<U>[K],
   ) => void;
-  errors: Partial<Record<keyof PageActionMap[U]["body"] & string, string>>;
+  errors: Partial<Record<keyof ResolveActionBody<U> & string, string>>;
   processing: boolean;
   isDirty: boolean;
   wasSuccessful: boolean;
@@ -34,8 +23,8 @@ export function useForm<U extends keyof PageActionMap & string>(
   put(opts?: any): void;
   patch(opts?: any): void;
   delete(opts?: any): void;
-  reset(...fields: (keyof PageActionMap[U]["body"] & string)[]): void;
-  clearErrors(...fields: (keyof PageActionMap[U]["body"] & string)[]): void;
+  reset(...fields: (keyof ResolveActionBody<U> & string)[]): void;
+  clearErrors(...fields: (keyof ResolveActionBody<U> & string)[]): void;
 };
 
 // Untyped fallback — manual generic for use without codegen
@@ -65,12 +54,23 @@ export function useForm(
   options?: { params?: Record<string, string> },
 ): any {
   let resolvedUrl = url;
+
+  // Strip ?action query before param resolution, then re-append
+  let actionQuery = "";
+  const qIdx = resolvedUrl.indexOf("?");
+  if (qIdx !== -1) {
+    actionQuery = resolvedUrl.slice(qIdx);
+    resolvedUrl = resolvedUrl.slice(0, qIdx);
+  }
+
   if (options?.params) {
     for (const [key, value] of Object.entries(options.params)) {
       resolvedUrl = resolvedUrl.replace(`:${key}`, encodeURIComponent(value));
     }
   }
 
+  resolvedUrl = resolvedUrl + actionQuery;
+
   const router = useContext(RouterContext);
   // ErrorsContext provides the errors signal accessor — a reactive function
   // that returns the current global errors object. This allows useForm to

packages/svelte/src/plugin-pages.ts

@@ -164,6 +164,7 @@ function generateClientEntry(
 import { hydrate } from "svelte";
 import { writable } from "svelte/store";
 import App from "@void-x/svelte/App.svelte";
+import { setActionRouter } from "@void-x/svelte/runtime";
 import { createPageRouter } from "void/pages-client";
 import { parseCacheFor } from "void/pages-prefetch";
 
@@ -199,6 +200,8 @@ const { router, initialPageData, initialComponent, initialLayouts, start } =
     prefetchDefaultCacheFor: parseCacheFor(${JSON.stringify(prefetch?.cacheFor ?? "30s")}),
   });
 
+setActionRouter(router);
+
 pageStore.set(initialComponent);
 propsStore.set(initialPageData.props);
 layoutsStore.set(initialLayouts);