@zerotal/inertia 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -4,10 +4,86 @@ All notable changes to this package are documented here. The format is
 based on [Keep a Changelog](https://keepachangelog.com/); this package
 follows the Zerotal monorepo's unified versioning.
 
-**Maturity: `beta`**
+**Maturity: `stable`**
 
 ## [Unreleased]
 
+## [1.5.0] — 2026-08-15
+
+### Added
+
+- **Typed pages: `Inertia.render(component, props)` is checked against the page component.**
+  The name must be a page that exists — a renamed or misspelled component was a runtime
+  500 before, the kind that reaches production because the route it lives on is the one
+  nobody clicked — and the props are checked against the props that component declares.
+
+  Nothing new is annotated to make this work. `resources/js/pages.generated.ts` already
+  holds an `import()` thunk per page, and an `import()` thunk carries the module's full
+  type; the file's `Record<string, () => Promise<{ default: unknown }>>` annotation was
+  throwing all of it away — widening every page name to `string` and every default export
+  to `unknown`, which is precisely what typed props need. It is now written with
+  `satisfies`: same constraint enforced, types kept, nothing changed at runtime. One
+  type-only `declare module` line in that same file hands them to the server, which keeps
+  the server's only view of the client component graph in exactly one place.
+
+  The check runs in the cheap direction: the **component** declares its props (which a
+  React component does anyway) and the **controller** is checked against them.
+
+  Three details worth knowing:
+
+  - **Wrappers are unwrapped, and carry their payload.** A prop accepts its value, a
+    factory, or a wrapper — and `merge(() => [1, 2])` for a `Post[]` prop is an error.
+  - **`optional()` and `defer()` are rejected on a required prop.** They are absent on
+    first paint by definition, so a component typing such a prop as required is wrong
+    about its own contract; a type that accepted it would launder that bug into something
+    the compiler had signed off on. Declare the prop `?`.
+  - **Shared props are never required.** `auth`/`flash`/`errors`/`old` are merged in, so a
+    page declaring one does not force every controller to pass it. Declare your own
+    `Inertia.share()` keys on the `SharedProps` interface and they behave the same way.
+
+  Vue pages are checked by **name** only: a `.vue` SFC resolves through a
+  `declare module '*.vue'` shim whose default export is `DefineComponent<{}, {}, any>`, so
+  its props are invisible to TypeScript without `vue-tsc` in the typecheck path. Those
+  pages accept any props rather than failing on a shape nobody can see — documented rather
+  than silently degraded.
+
+- **`Inertia.render.dynamic(name, props)` / `inertia.dynamic()`** — render a page whose
+  name is only known at runtime (an error page chosen by status code, a component from
+  config), with no checking. A separate function rather than a `string` overload: an
+  overload that accepts every string is matched by every string, which would make the
+  checked signature decorative. `inertiaStream.dynamic()` is its streaming counterpart.
+
+- **The prop wrappers are generic.** `optional`, `lazy`, `always`, `defer`, `merge` and
+  `deepMerge` carry what they resolve to (`defer(() => stats())` is a `DeferProp<Stats>`),
+  which is what lets the wrapper be checked against the prop it fills. Existing calls are
+  unaffected — the parameter defaults to `unknown`.
+
+- **Tests for `PrecognitionMiddleware`.** A precognitive request validates a form
+  without running the controller's side effects, answering 204 or 422 instead of the
+  real response — so those answers must never be confused with real ones by a cache.
+  Without the `Vary`, a shared cache can serve a precognitive 204 to an actual form
+  submission, and the user's data silently never reaches the controller. Pinned:
+  the header is added only for `Precognition: true` (not `1`, not `TRUE`), it is
+  appended to an existing `Vary` rather than replacing it — replacing would discard
+  the app's own content negotiation — it is not duplicated when already present, and
+  the decorated response keeps its status and body. 76 tests → 84.
+
+- **The prop wrapper classes, the error classes and `SsrHandler` are documented.**
+  `OptionalProp`, `AlwaysProp`, `DeferProp`, `MergeProp` and `InfiniteScrollProp` are
+  what the prop helpers return; the reference now says so, and names `InertiaProp` as
+  the type to accept for "any wrapped prop". `InertiaError`, `InvalidComponentError`
+  and `InertiaTemplateNotLoadedError` gained a table of what throws each.
+
+### Changed
+
+- **`detectVuePlugin` is marked `@internal`** — build plumbing for `inertia:build`,
+  reached only by the build command. With the eight markers already present the
+  promise is 30 exports, not 39.
+
+- **Maturity is now `stable`** — the public API follows SemVer strictly for the rest
+  of the 1.x line. Every promised export is documented across seven guide pages, and
+  the only dependency is `@zerotal/core`.
+
 ## [1.0.3] — 2026-08-07
 
 ### Changed

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zerotal/inertia",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "license": "MIT",
-  "maturity": "beta",
+  "maturity": "stable",
   "private": false,
   "type": "module",
   "main": "./src/index.ts",
@@ -32,7 +32,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.4.0"
+    "@zerotal/core": "1.5.0"
   },
   "peerDependencies": {
     "react": "^18 || ^19",

package/src/PageRegistry.ts

@@ -85,9 +85,23 @@ export async function generatePageRegistry(
     "// Bun.build with splitting:true creates one .js chunk per page.",
     "// Converting to static imports will bundle ALL pages into app.js.",
     "",
-    "export const pages: Record<string, () => Promise<{ default: unknown }>> = {",
+    // `satisfies`, not `: Record<string, …>`. The annotation checked the shape and
+    // then threw away everything else the thunks knew — the page names widened to
+    // `string` and every default export to `unknown`, which is precisely what
+    // typed props need. `satisfies` enforces the same constraint and keeps the
+    // types. Nothing changes at runtime.
+    "export const pages = {",
     ...thunks,
-    "};",
+    "} satisfies Record<string, () => Promise<{ default: unknown }>>;",
+    "",
+    "// Type-only: lets a controller's `Inertia.render(name, props)` be checked",
+    "// against the props each page component declares. Erased at runtime — and",
+    "// it is the ONLY place the server side touches the client component graph.",
+    'declare module "@zerotal/inertia" {',
+    "  interface InertiaPageRegistry {",
+    "    pages: typeof pages;",
+    "  }",
+    "}",
     // Trailing newline: the file is written on every dev rebuild, and without it
     // a formatter in the app would rewrite it right back, forever.
     "",

package/src/augment.ts

@@ -1,19 +1,23 @@
 import type { MiddlewareClass, RouteRegistration } from "@zerotal/core";
+import type { PageTarget, RenderProps } from "./pages.ts";
 
 declare module "@zerotal/core" {
   interface RouterMacros {
     /**
      * Register a GET route that renders an Inertia page without a controller.
      *
+     * The component name and props are checked against the generated page
+     * registry, exactly as `Inertia.render` is.
+     *
      * @example
      * Router.inertia('/about', 'About/Index');
      * Router.inertia('/home',  'Home/Index', { greeting: 'Hello' });
      * Router.inertia('/admin', 'Admin/Dashboard', [AuthMiddleware]);
      */
-    inertia(
+    inertia<N extends PageTarget>(
       path: string,
-      component: string,
-      props?: Record<string, unknown> | MiddlewareClass[],
+      component: N,
+      props?: RenderProps<N> | MiddlewareClass[],
       middleware?: MiddlewareClass[],
     ): RouteRegistration;
   }

package/src/index.ts

@@ -50,12 +50,25 @@ export {
   _setHtmlTemplate,
   _getHtmlTemplate,
 } from "./inertia.ts";
+export type { PageRenderer } from "./inertia.ts";
 export { InertiaProvider } from "./provider/InertiaProvider.ts";
 export { InertiaMiddleware } from "./middleware/InertiaMiddleware.ts";
 export { PrecognitionMiddleware } from "./middleware/PrecognitionMiddleware.ts";
 export { sharedProps } from "./SharedProps.ts";
 export { assetVersion, setAssetVersion } from "./version.ts";
 export { generatePageRegistry } from "./PageRegistry.ts";
+// The typed page registry: `InertiaPageRegistry` is what `pages.generated.ts`
+// augments, `SharedProps` is what the app declares for `Inertia.share()`.
+export type {
+  InertiaPageRegistry,
+  SharedProps,
+  PageName,
+  PageTarget,
+  PropsOf,
+  PropInput,
+  RenderProps,
+  RenderArgs,
+} from "./pages.ts";
 export { detectVuePlugin } from "./vuePlugin.ts";
 export type { PageObject, InertiaProviderOptions } from "./types.ts";
 

package/src/inertia.ts

@@ -9,6 +9,35 @@ import { readHistoryFlags } from "./historyState.ts";
 import { allSharedKeys } from "./share.ts";
 import { resolvePageModule, renderInertiaPage } from "./ssr/renderPage.ts";
 import type { PageObject } from "./types.ts";
+import type { PageTarget, RenderArgs } from "./pages.ts";
+
+/**
+ * A page-render helper — {@link inertia} and {@link inertiaStream} — with the
+ * `dynamic` escape hatch beside its checked call signature.
+ */
+export interface PageRenderer {
+  /**
+   * Render page `component` with props checked against that page's component.
+   *
+   * @param component - Page component name/path relative to the pages dir, without extension.
+   * @param args - Props for the page; omit when the page requires none.
+   */
+  <N extends PageTarget>(component: N, ...args: RenderArgs<N>): Promise<void>;
+
+  /**
+   * Render a page whose name isn't known at compile time — an error page chosen
+   * by status code, a component name from config or the database.
+   *
+   * A separate function rather than a `string` overload: an overload that
+   * accepts every string is matched by every string, which would make the
+   * checked signature decorative. This one is greppable and says what it is
+   * giving up.
+   *
+   * @param component - Page component name, resolved at runtime.
+   * @param props - Props for the page, unchecked.
+   */
+  dynamic(component: string, props?: Record<string, unknown>): Promise<void>;
+}
 
 /**
  * Build the full Inertia page object for the current request: merges shared props, runs the v3
@@ -147,7 +176,7 @@ function _devBustAssets(html: string): string {
  * Reach it from a controller via `Inertia.stream(...)`.
  *
  * @param component - Page component name (path relative to the pages dir, no extension), e.g. `"Posts/Show"`.
- * @param props - Props passed to the page; may include prop wrappers (`optional`/`defer`/`merge`/…).
+ * @param args - Props passed to the page; may include prop wrappers (`optional`/`defer`/`merge`/…). Checked against the page component's own props, like {@link inertia}.
  * @throws {@link InertiaTemplateNotLoadedError} When the HTML template has not been loaded (InertiaProvider not registered).
  * @throws {@link InvalidComponentError} When the component name contains path-traversal sequences.
  *
@@ -159,10 +188,16 @@ function _devBustAssets(html: string): string {
  * }
  * ```
  */
-export async function inertiaStream(
-  component: string,
-  props: Record<string, unknown> = {},
-): Promise<void> {
+export const inertiaStream: PageRenderer = Object.assign(
+  <N extends PageTarget>(component: N, ...args: RenderArgs<N>): Promise<void> =>
+    _inertiaStream(component, (args[0] ?? {}) as Record<string, unknown>),
+  {
+    dynamic: (component: string, props: Record<string, unknown> = {}): Promise<void> =>
+      _inertiaStream(component, props),
+  },
+);
+
+async function _inertiaStream(component: string, props: Record<string, unknown>): Promise<void> {
   const ctx = RequestContext.get();
 
   if (!_htmlTemplate) {
@@ -290,8 +325,16 @@ export async function inertiaStream(
  * For streaming SSR (better TTFB) use {@link inertiaStream} instead; to force a
  * full-page/external redirect use {@link location}.
  *
+ * @remarks
+ * Both arguments are type-checked against the generated page registry
+ * (`resources/js/pages.generated.ts`): the component name must be a page that
+ * exists, and the props are checked against the props that page's component
+ * declares, with `optional`/`defer`/`merge` wrappers unwrapped. Shared props
+ * are optional — the framework merges them in. Until the registry is rebuilt,
+ * any name and any props compile, as before.
+ *
  * @param component - Page component name/path relative to the pages dir, without extension (e.g. `"Users/Index"`).
- * @param props - Props for the page. Values may be plain data or prop wrappers (`optional`/`defer`/`merge`/`scroll`/…). Defaults to `{}`.
+ * @param args - Props for the page. Values may be plain data, a factory, or prop wrappers (`optional`/`defer`/`merge`/`scroll`/…). Omit when the page needs none.
  * @returns A promise that resolves once `ctx.response` has been set (no value).
  * @throws {@link InertiaTemplateNotLoadedError} On a full-page load when the HTML template has not been loaded (InertiaProvider not registered).
  *
@@ -304,10 +347,16 @@ export async function inertiaStream(
  * }
  * ```
  */
-export async function inertia(
-  component: string,
-  props: Record<string, unknown> = {},
-): Promise<void> {
+export const inertia: PageRenderer = Object.assign(
+  <N extends PageTarget>(component: N, ...args: RenderArgs<N>): Promise<void> =>
+    _inertia(component, (args[0] ?? {}) as Record<string, unknown>),
+  {
+    dynamic: (component: string, props: Record<string, unknown> = {}): Promise<void> =>
+      _inertia(component, props),
+  },
+);
+
+async function _inertia(component: string, props: Record<string, unknown>): Promise<void> {
   const ctx = RequestContext.get();
   const isInertiaRequest = ctx.request.headers.get("X-Inertia") === "true";
 

package/src/middleware/InertiaMiddleware.ts

@@ -22,7 +22,7 @@ import { assetVersion } from "../version.ts";
  *    Ensures browser cache treats HTML and JSON versions as distinct.
  */
 export class InertiaMiddleware extends BaseMiddleware {
-  protected options: {} = {};
+  protected options: Record<string, never> = {};
 
   async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
     const isInertia = http.request.headers.get("X-Inertia") === "true";

package/src/middleware/PrecognitionMiddleware.ts

@@ -13,7 +13,7 @@ import { BaseMiddleware, withHeaders } from "@zerotal/core";
  * Register it globally (before route middleware) when using precognitive forms.
  */
 export class PrecognitionMiddleware extends BaseMiddleware {
-  protected options: {} = {};
+  protected options: Record<string, never> = {};
 
   async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
     const isPrecognitive = http.request.headers.get("Precognition") === "true";

package/src/pages.ts

@@ -0,0 +1,186 @@
+/**
+ * The typed page registry: what turns `Inertia.render("Users/Index", props)`
+ * from two strings and a bag of `unknown` into a checked call.
+ *
+ * The generated `resources/js/pages.generated.ts` already knows everything
+ * needed — it holds one `() => import("./pages/Users/Index.tsx")` thunk per
+ * page, and an `import()` thunk carries the module's full type. It used to be
+ * annotated `Record<string, () => Promise<{ default: unknown }>>`, which
+ * enforced the shape and discarded the rest. Written with `satisfies` instead,
+ * the same file names every page and every page's props.
+ *
+ * It reaches the server through one declaration-merged interface:
+ *
+ * ```ts
+ * declare module "@zerotal/inertia" {
+ *   interface InertiaPageRegistry { pages: typeof pages }
+ * }
+ * ```
+ *
+ * That indirection is the point. `pages.generated.ts` lives in `resources/js`
+ * and imports `.tsx` files; a controller that imported it directly would drag
+ * the whole component graph into the server's type-check, and a broken
+ * component would fail the server's build. The augmentation is type-only, so
+ * the coupling exists in exactly one file and nothing is emitted.
+ *
+ * **The direction is the good part.** The page component declares its props —
+ * which a React component does anyway — and the controller is checked against
+ * them. Neither side writes an annotation it wasn't already writing.
+ */
+import type {
+  AlwaysProp,
+  DeferProp,
+  InfiniteScrollProp,
+  MergeProp,
+  OptionalProp,
+  PaginatorLike,
+} from "./props/PropTypes.ts";
+
+/**
+ * Augmentation target for the generated page map. Filled in by
+ * `resources/js/pages.generated.ts` with `{ pages: typeof pages }`.
+ *
+ * Empty until then, which is why every Inertia helper keeps a `string`
+ * fallback: an app that has not rebuilt its registry still compiles.
+ *
+ * @category Extension registries
+ */
+export interface InertiaPageRegistry {}
+
+/**
+ * Props merged into every page by the framework, so a controller never passes
+ * them. Augment it to match your app's `Inertia.share()` calls and the props
+ * they contribute become optional in `Inertia.render` rather than missing:
+ *
+ * ```ts
+ * declare module "@zerotal/inertia" {
+ *   interface SharedProps {
+ *     auth: { user: { id: number; name: string } | null };
+ *     appName: string;
+ *   }
+ * }
+ * ```
+ *
+ * Hand-written on purpose. `share(key, value)` is a runtime call in a provider,
+ * so no generator can see it; the list is small, stable, and app-specific.
+ *
+ * @category Extension registries
+ */
+export interface SharedProps {}
+
+/**
+ * The shared props the framework merges on every request whatever the app does
+ * — see `sharedProps()`. Kept separate from {@link SharedProps} rather than
+ * declared in it: an app that types `auth.user` as its own `User` would
+ * otherwise be redeclaring a member of the same interface, which is a merge
+ * conflict rather than a refinement.
+ */
+interface BuiltInSharedProps {
+  auth: { user: unknown };
+  flash: { success: string | null; error: string | null };
+  errors: Record<string, string>;
+  old: Record<string, unknown>;
+}
+
+/** Everything a controller may leave out because something else supplies it. */
+type AllSharedProps = SharedProps & BuiltInSharedProps;
+
+/** The generated `pages` map, or an empty map before the registry exists. */
+type PageModules = InertiaPageRegistry extends { pages: infer Map } ? Map : Record<never, never>;
+
+/** Every page name in the generated registry. `never` until it is generated. */
+export type PageName = Extract<keyof PageModules, string>;
+
+/**
+ * What the Inertia helpers accept as a component name: the generated page names
+ * once the registry exists, any string before that.
+ */
+export type PageTarget = [PageName] extends [never] ? string : PageName;
+
+/** The default export of page `N`'s module. */
+type PageComponent<N extends string> = N extends keyof PageModules
+  ? PageModules[N] extends () => Promise<{ default: infer Component }>
+    ? Component
+    : unknown
+  : unknown;
+
+/**
+ * The props a component declares, read off its own signature.
+ *
+ * Structural on purpose — `@zerotal/inertia` must not import React types (React
+ * is an optional peer; a Vue app never installs it). A function component's
+ * first parameter and a class component's constructor prop both match here.
+ *
+ * Anything else — a `React.memo()` wrapper, or a `.vue` SFC resolved through a
+ * `declare module '*.vue'` shim that types the default export as
+ * `DefineComponent<{}, {}, any>` — has no readable props, and falls back to an
+ * open record so those pages keep compiling rather than failing on a shape
+ * nobody can see. See the Vue note in the props docs.
+ */
+type PropsOfComponent<Component> = Component extends (
+  props: infer Props,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- matching any component signature, whose extra args (React's legacy context) are irrelevant here.
+  ...rest: any[]
+) => // eslint-disable-next-line @typescript-eslint/no-explicit-any -- a component returns JSX, ReactNode, a Promise of either…
+any
+  ? Props
+  : Component extends abstract new (
+        props: infer Props,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ...rest: any[]
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      ) => any
+    ? Props
+    : Record<string, unknown>;
+
+/** The props page `N`'s component declares. */
+export type PropsOf<N extends string> = PropsOfComponent<PageComponent<N>>;
+
+/**
+ * What a controller may pass for a prop the component declares as `T`.
+ *
+ * The two sides genuinely differ: the controller passes `optional(() => posts)`
+ * and the component receives `Post[]`. So each prop accepts its value, a
+ * factory for it, or a wrapper carrying it.
+ *
+ * **`optional` and `defer` are only allowed where `T` admits `undefined`.**
+ * They are absent on first paint by definition, so a component that declares
+ * the prop as required is wrong about its own contract — and a type that
+ * accepted them anyway would launder that bug into something the compiler
+ * signed off on. `always`, `merge` and `scroll` are present on first paint, so
+ * they are allowed everywhere.
+ */
+export type PropInput<T> =
+  | T
+  | (() => T | Promise<T>)
+  | AlwaysProp<T>
+  | MergeProp<T>
+  // `scroll()` resolves to the paginator it was given, so it only fits a prop
+  // the component declares as paginator-shaped.
+  | (T extends PaginatorLike ? InfiniteScrollProp : never)
+  | (undefined extends T ? OptionalProp<T> | DeferProp<T> : never);
+
+/** Apply {@link PropInput} to every prop, preserving optional and readonly modifiers. */
+type PropInputs<T> = { [K in keyof T]: PropInput<T[K]> };
+
+/**
+ * The props `Inertia.render(N, …)` requires: everything page `N` declares, each
+ * accepting its wrappers — minus the shared props, which the framework merges
+ * in. Shared props stay *accepted* (a controller may override `auth` for one
+ * page) but are never required, and a page component that declares one doesn't
+ * make every controller pass it.
+ */
+export type RenderProps<N extends string> = [PageName] extends [never]
+  ? Record<string, unknown>
+  : Omit<PropInputs<PropsOf<N>>, keyof AllSharedProps> & Partial<PropInputs<AllSharedProps>>;
+
+/**
+ * `render()`'s arguments after the component name: the props bag is optional
+ * only when the page requires nothing of it.
+ */
+export type RenderArgs<N extends string> = [PageName] extends [never]
+  ? [props?: Record<string, unknown>]
+  : // "every prop is optional" — an empty object satisfies the page.
+    Record<never, never> extends RenderProps<N>
+    ? [props?: RenderProps<N>]
+    : [props: RenderProps<N>];

package/src/props/PropTypes.ts

@@ -8,8 +8,14 @@
  * Optional/Always/Defer/Merge prop wrappers, adapted to TypeScript.
  */
 
-/** A prop value: a concrete value, or a (possibly async) factory evaluated on demand. */
-export type PropFactory = () => unknown | Promise<unknown>;
+/**
+ * A prop value: a concrete value, or a (possibly async) factory evaluated on demand.
+ *
+ * Generic so a wrapper can carry what it will resolve to — that is what lets
+ * `Inertia.render` check `defer(() => stats())` against the `stats` prop the
+ * page component declares, instead of checking that *something* was passed.
+ */
+export type PropFactory<T = unknown> = () => T | Promise<T>;
 
 /** Resolved merge configuration contributed by a mergeable prop. */
 export interface MergeConfig {
@@ -120,12 +126,12 @@ export abstract class InertiaProp {
  *
  * @category Props
  */
-export class OptionalProp extends InertiaProp {
+export class OptionalProp<T = unknown> extends InertiaProp {
   override readonly ignoreFirstLoad = true;
-  constructor(private readonly callback: PropFactory) {
+  constructor(private readonly callback: PropFactory<T>) {
     super();
   }
-  resolve(): unknown | Promise<unknown> {
+  resolve(): T | Promise<T> {
     return this.callback();
   }
 }
@@ -136,12 +142,12 @@ export class OptionalProp extends InertiaProp {
  *
  * @category Props
  */
-export class AlwaysProp extends InertiaProp {
-  constructor(private readonly value: unknown | PropFactory) {
+export class AlwaysProp<T = unknown> extends InertiaProp {
+  constructor(private readonly value: T | PropFactory<T>) {
     super();
   }
-  resolve(): unknown | Promise<unknown> {
-    return typeof this.value === "function" ? (this.value as PropFactory)() : this.value;
+  resolve(): T | Promise<T> {
+    return typeof this.value === "function" ? (this.value as PropFactory<T>)() : this.value;
   }
 }
 
@@ -152,16 +158,16 @@ export class AlwaysProp extends InertiaProp {
  *
  * @category Props
  */
-export class DeferProp extends InertiaProp {
+export class DeferProp<T = unknown> extends InertiaProp {
   override readonly ignoreFirstLoad = true;
   constructor(
-    private readonly callback: PropFactory,
+    private readonly callback: PropFactory<T>,
     readonly group: string = "default",
     readonly rescue: boolean = false,
   ) {
     super();
   }
-  resolve(): unknown | Promise<unknown> {
+  resolve(): T | Promise<T> {
     return this.callback();
   }
 }
@@ -172,13 +178,13 @@ export class DeferProp extends InertiaProp {
  *
  * @category Props
  */
-export class MergeProp extends InertiaProp {
-  constructor(private readonly value: unknown | PropFactory) {
+export class MergeProp<T = unknown> extends InertiaProp {
+  constructor(private readonly value: T | PropFactory<T>) {
     super();
     this._merge = true;
   }
-  resolve(): unknown | Promise<unknown> {
-    return typeof this.value === "function" ? (this.value as PropFactory)() : this.value;
+  resolve(): T | Promise<T> {
+    return typeof this.value === "function" ? (this.value as PropFactory<T>)() : this.value;
   }
 }
 
@@ -256,7 +262,7 @@ export class InfiniteScrollProp extends InertiaProp {
  * });
  * ```
  */
-export function optional(callback: PropFactory): OptionalProp {
+export function optional<T>(callback: PropFactory<T>): OptionalProp<T> {
   return new OptionalProp(callback);
 }
 
@@ -267,7 +273,7 @@ export function optional(callback: PropFactory): OptionalProp {
  * @returns An {@link OptionalProp} wrapper.
  * @category Props
  */
-export function lazy(callback: PropFactory): OptionalProp {
+export function lazy<T>(callback: PropFactory<T>): OptionalProp<T> {
   return new OptionalProp(callback);
 }
 
@@ -279,7 +285,12 @@ export function lazy(callback: PropFactory): OptionalProp {
  * @returns An {@link AlwaysProp} wrapper.
  * @category Props
  */
-export function always(value: unknown | PropFactory): AlwaysProp {
+// Two overloads, not one `T | PropFactory<T>` parameter: given a callback, a
+// single union parameter lets TypeScript infer `T` as the callback itself, and
+// the wrapper would then advertise a function where the page expects data.
+export function always<T>(value: PropFactory<T>): AlwaysProp<T>;
+export function always<T>(value: T): AlwaysProp<T>;
+export function always<T>(value: T | PropFactory<T>): AlwaysProp<T> {
   return new AlwaysProp(value);
 }
 
@@ -302,11 +313,11 @@ export function always(value: unknown | PropFactory): AlwaysProp {
  * });
  * ```
  */
-export function defer(
-  callback: PropFactory,
+export function defer<T>(
+  callback: PropFactory<T>,
   group = "default",
   options: { rescue?: boolean } = {},
-): DeferProp {
+): DeferProp<T> {
   return new DeferProp(callback, group, options.rescue ?? false);
 }
 
@@ -323,7 +334,9 @@ export function defer(
  * return inertia('Feed', { posts: merge(() => Post.paginate(15, page)) });
  * ```
  */
-export function merge(value: unknown | PropFactory): MergeProp {
+export function merge<T>(value: PropFactory<T>): MergeProp<T>;
+export function merge<T>(value: T): MergeProp<T>;
+export function merge<T>(value: T | PropFactory<T>): MergeProp<T> {
   return new MergeProp(value);
 }
 
@@ -335,7 +348,9 @@ export function merge(value: unknown | PropFactory): MergeProp {
  * @returns A {@link MergeProp} wrapper configured for deep merging.
  * @category Props
  */
-export function deepMerge(value: unknown | PropFactory): MergeProp {
+export function deepMerge<T>(value: PropFactory<T>): MergeProp<T>;
+export function deepMerge<T>(value: T): MergeProp<T>;
+export function deepMerge<T>(value: T | PropFactory<T>): MergeProp<T> {
   return new MergeProp(value).deepMerge();
 }
 

package/src/route.ts

@@ -1,6 +1,7 @@
 import { Router } from "@zerotal/core";
 import type { MiddlewareClass, RouteRegistration } from "@zerotal/core";
 import { inertia } from "./inertia.ts";
+import type { PageTarget, RenderProps } from "./pages.ts";
 
 /**
  * Register a GET route that renders an Inertia page directly — no controller
@@ -22,10 +23,10 @@ import { inertia } from "./inertia.ts";
  * Router.inertia('/admin', 'Admin/Dashboard', [AuthMiddleware]);
  * ```
  */
-export function inertiaRoute(
+export function inertiaRoute<N extends PageTarget>(
   path: string,
-  component: string,
-  props?: Record<string, unknown> | MiddlewareClass[],
+  component: N,
+  props?: RenderProps<N> | MiddlewareClass[],
   middleware: MiddlewareClass[] = [],
 ): RouteRegistration {
   let resolvedProps: Record<string, unknown> = {};
@@ -34,12 +35,15 @@ export function inertiaRoute(
   if (Array.isArray(props)) {
     resolvedMiddleware = props; // shorthand: Router.inertia('/x', 'X', [AuthMiddleware])
   } else if (props) {
-    resolvedProps = props;
+    resolvedProps = props as Record<string, unknown>;
   }
 
   const handler = class InertiaRouteHandler {
     async handle(): Promise<void> {
-      await inertia(component, resolvedProps);
+      // Props were checked against the component above; the runtime call takes
+      // the erased bag, which `RenderProps<N>` cannot be proven to be while `N`
+      // is still a type variable.
+      await inertia.dynamic(component, resolvedProps);
     }
   };
 

package/src/vuePlugin.ts

@@ -38,6 +38,8 @@ interface SfcDescriptor {
 /**
  * Resolve `@vue/compiler-sfc` from `cwd` and return a Bun plugin that compiles
  * `.vue` files. Returns `[]` when the compiler is not installed.
+ *
+ * @internal Build plumbing for `inertia:build`; apps do not call it.
  */
 export async function detectVuePlugin(cwd: string): Promise<BunPlugin[]> {
   let compilerPath: string;