@zerotal/inertia 1.0.0

package/src/commands/InertiaBuildCommand.ts

@@ -0,0 +1,82 @@
+import { Command } from "@zerotal/core";
+import { pruneBuildOutput } from "@zerotal/core/dev";
+import { generatePageRegistry } from "../PageRegistry.ts";
+import { detectCssPlugins } from "../css.ts";
+import { detectVuePlugin } from "../vuePlugin.ts";
+
+/**
+ * `inertia:build` — regenerate the page registry and bundle the frontend with
+ * `Bun.build` (code-split into per-page chunks) into `public/assets/`. Pass
+ * `--production` (`-p`) for a minified, source-map-free build.
+ *
+ * @category Build
+ * @example
+ * ```ts
+ * // Dev build:
+ * // bun zt inertia:build
+ * // Production build:
+ * // bun zt inertia:build --production
+ * ```
+ */
+export class InertiaBuildCommand extends Command {
+  static override commandName = "inertia:build";
+  static override description =
+    "Build the Inertia frontend bundle and regenerate the page registry";
+  static override needsApp = false;
+
+  static override flags = [
+    {
+      name: "production",
+      short: "p",
+      type: "boolean" as const,
+      description: "Build for production (minified, no source maps)",
+      default: false,
+    },
+  ];
+
+  override async run(): Promise<void> {
+    const isProd = this.flags["production"] as boolean;
+    const cwd = process.cwd();
+
+    // Step 1: Regenerate the page registry
+    this.section("Regenerating page registry...");
+    await generatePageRegistry(cwd);
+    this.info("Page registry updated.");
+
+    // Step 2: Build the frontend bundle with Bun.build
+    this.section("Building frontend bundle...");
+
+    const plugins = [...(await detectCssPlugins(cwd)), ...(await detectVuePlugin(cwd))];
+    const outdir = `${cwd}/public/assets`;
+    const result = await Bun.build({
+      entrypoints: [`${cwd}/resources/js/app.tsx`],
+      outdir,
+      target: "browser",
+      splitting: true, // REQUIRED: creates per-page chunks from dynamic imports
+      minify: isProd,
+      sourcemap: isProd ? "none" : "external",
+      ...(plugins.length > 0 ? { plugins } : {}),
+    });
+
+    if (!result.success) {
+      for (const log of result.logs) {
+        this.error(String(log));
+      }
+      throw new Error("Frontend build failed.");
+    }
+
+    // Chunks are named after their content, so the ones this build replaced
+    // would otherwise stay behind — and ship.
+    const removed = await pruneBuildOutput(outdir, result.outputs);
+
+    this.info(`Build complete: ${result.outputs.length} files → public/assets/`);
+    if (removed.length > 0) this.dim(`  Removed ${removed.length} stale file(s).`);
+
+    this.table(
+      result.outputs.map((o) => [
+        o.path.replace(cwd, "").replace(/\\/g, "/"),
+        `${(o.size / 1024).toFixed(1)} KB`,
+      ]) as [string, string][],
+    );
+  }
+}

package/src/commands/MakePageCommand.ts

@@ -0,0 +1,207 @@
+import { Command, config } from "@zerotal/core";
+import { generatePageRegistry } from "../PageRegistry.ts";
+import { DEFAULT_PAGES_DIR } from "../config.ts";
+
+/**
+ * `make:page` — scaffold a new Inertia page component under the configured pages dir
+ * and regenerate the page registry. The framework (React `.tsx` / Vue `.vue`) is
+ * auto-detected from the installed adapter unless forced with `--framework`; pass
+ * `--layout` to wrap the page in a persistent layout.
+ *
+ * @category Scaffolding
+ * @example
+ * ```ts
+ * // bun zt make:page Users/Index
+ * // bun zt make:page Dashboard --layout MainLayout
+ * // bun zt make:page Settings --framework vue
+ * ```
+ */
+export class MakePageCommand extends Command {
+  static override commandName = "make:page";
+  static override description = "Create a new Inertia page component";
+  static override needsApp = false;
+
+  static override args = [
+    {
+      name: "name",
+      required: true,
+      description: "Page name, e.g. Dashboard or Users/Index",
+    },
+  ];
+
+  static override flags = [
+    {
+      name: "layout",
+      type: "string" as const,
+      description: "Wrap the page in a persistent layout, e.g. --layout MainLayout",
+      default: "",
+    },
+    {
+      name: "framework",
+      type: "string" as const,
+      description: "Force the frontend framework: 'vue' or 'react' (auto-detected by default)",
+      default: "",
+    },
+  ];
+
+  override async run(): Promise<void> {
+    const name = this.args["name"]!; // e.g. 'Users/Index'
+    const layout = (this.flags["layout"] as string | undefined) ?? "";
+    const pagesDir = config
+      .safe("inertia.pagesDir", DEFAULT_PAGES_DIR)
+      .replace(/\\/g, "/")
+      .replace(/\/+$/, "");
+
+    // Pick the framework: explicit --framework flag, else auto-detect from the
+    // installed Inertia adapter (@inertiajs/vue3 → vue, otherwise react).
+    const forced = (this.flags["framework"] as string | undefined)?.toLowerCase() ?? "";
+    const framework: Framework =
+      forced === "vue" || forced === "react"
+        ? (forced as Framework)
+        : _detectFramework(process.cwd());
+    const ext = framework === "vue" ? "vue" : "tsx";
+
+    const path = `${pagesDir}/${name}.${ext}`;
+
+    if (await Bun.file(path).exists()) {
+      this.error(`File already exists: ${path}`);
+      return;
+    }
+
+    const componentName = name.includes("/") ? name.split("/").pop()! : name;
+
+    // Compute how many levels deep the page is so the layout import is correct
+    const depth = name.split("/").length;
+    const prefix = "../".repeat(depth);
+    const stub =
+      framework === "vue"
+        ? layout
+          ? _vueLayoutPageStub(componentName, layout, prefix)
+          : _vuePageStub(componentName)
+        : layout
+          ? _reactLayoutPageStub(componentName, layout, prefix)
+          : _reactPageStub(componentName);
+
+    await Bun.write(path, stub);
+    this.info(`Created: ${path}`);
+
+    if (layout) {
+      this.dim(`  Layout: ${prefix}layouts/${layout}.${ext}`);
+      this.dim("  Adjust the import path if your layouts live elsewhere.");
+    }
+
+    this.dim("  Regenerating page registry...");
+    await generatePageRegistry(process.cwd());
+    this.info("Page registry updated.");
+  }
+}
+
+type Framework = "vue" | "react";
+
+/** Detect the frontend framework from the Inertia adapter installed in `cwd`. */
+function _detectFramework(cwd: string): Framework {
+  try {
+    Bun.resolveSync("@inertiajs/vue3", cwd);
+    return "vue";
+  } catch {
+    return "react";
+  }
+}
+
+function _reactPageStub(name: string): string {
+  return `import { Link, usePage } from '@inertiajs/react';
+
+// Define the props this page receives from the controller
+interface Props {
+  // TODO: add your props here
+}
+
+export default function ${name}({}: Props) {
+  const { auth } = usePage<{ auth: { user: { name: string } | null } }>().props;
+
+  return (
+    <main>
+      <h1>${name}</h1>
+      {auth.user && <p>Hello, {auth.user.name}</p>}
+      <Link href="/">Home</Link>
+    </main>
+  );
+}
+`;
+}
+
+function _reactLayoutPageStub(name: string, layout: string, prefix: string): string {
+  return `import type { ReactNode } from 'react';
+import { Link }          from '@inertiajs/react';
+// Adjust the path if your layouts directory is elsewhere
+import ${layout}         from '${prefix}layouts/${layout}.tsx';
+
+// Define the props this page receives from the controller
+interface Props {
+  // TODO: add your props here
+}
+
+function ${name}({}: Props) {
+  return (
+    <main>
+      <h1>${name}</h1>
+      <Link href="/">Home</Link>
+    </main>
+  );
+}
+
+// Inertia persistent layout — preserved across client-side navigations.
+// The layout renders once; only the page content re-renders on navigation.
+(${name} as { layout?: (page: ReactNode) => ReactNode }).layout =
+  (page) => <${layout}>{page}</${layout}>;
+
+export default ${name};
+`;
+}
+
+function _vuePageStub(name: string): string {
+  return `<script setup lang="ts">
+import { Link, usePage } from '@inertiajs/vue3';
+
+const page = usePage<{ auth: { user: { name: string } | null } }>();
+
+// Define the props this page receives from the controller
+defineProps<{
+  // TODO: add your props here
+}>();
+</script>
+
+<template>
+  <main>
+    <h1>${name}</h1>
+    <p v-if="page.props.auth.user">Hello, {{ page.props.auth.user.name }}</p>
+    <Link href="/">Home</Link>
+  </main>
+</template>
+`;
+}
+
+function _vueLayoutPageStub(name: string, layout: string, prefix: string): string {
+  return `<script setup lang="ts">
+import { Link } from '@inertiajs/vue3';
+// Adjust the path if your layouts directory is elsewhere
+import ${layout} from '${prefix}layouts/${layout}.vue';
+
+// Inertia persistent layout — preserved across client-side navigations.
+// The layout renders once; only the page content re-renders on navigation.
+defineOptions({ layout: ${layout} });
+
+// Define the props this page receives from the controller
+defineProps<{
+  // TODO: add your props here
+}>();
+</script>
+
+<template>
+  <main>
+    <h1>${name}</h1>
+    <Link href="/">Home</Link>
+  </main>
+</template>
+`;
+}

package/src/commands/index.ts

@@ -0,0 +1,3 @@
+/** The `@zerotal/inertia` CLI commands (`inertia:build`, `make:page`), registered by InertiaProvider. */
+export { InertiaBuildCommand } from "./InertiaBuildCommand.ts";
+export { MakePageCommand } from "./MakePageCommand.ts";

package/src/config.ts

@@ -0,0 +1,82 @@
+import { deepMerge } from "@zerotal/core";
+
+export interface InertiaConfigShape {
+  /** Path to the HTML template file. Default: './resources/app.html' */
+  htmlTemplate: string;
+  /** Asset version string for cache-busting. Default: '1' */
+  version: string;
+  /** Public URL prefix for built assets. Default: '/' */
+  assetsUrl: string;
+  /**
+   * Directory (relative to the project root) where Inertia page components live.
+   * Used by the page-registry generator, the SSR handler, and `inertiaStream()`.
+   * Default: 'resources/js/pages'
+   */
+  pagesDir: string;
+  /**
+   * Enable server-side rendering.
+   *
+   * When true, InertiaProvider registers POST /__ssr which accepts
+   * { component, props, url } and returns { body, head } - the same
+   * contract as the Inertia Node SSR server. The Inertia client calls
+   * this endpoint when rendering the first page load on the server.
+   *
+   * Pages are rendered with the framework they're authored in: React `.tsx`
+   * via `react-dom/server`, or Vue `.vue` via `@inertiajs/vue3` + `vue/server-renderer`.
+   * Install the server renderer for the framework(s) the app uses.
+   *
+   * Default: false
+   */
+  ssr: boolean;
+  /**
+   * Shared secret required to reach `POST /__ssr` from off-box.
+   *
+   * The endpoint is loopback-only by default, because it takes an arbitrary component name
+   * and a props bag and does real rendering work with them — upstream Inertia runs SSR as a
+   * separate process on a private port for exactly this reason. Set this (and send it as
+   * `X-Inertia-SSR-Secret`) only when the renderer runs on another host.
+   *
+   * Default: `""` — loopback only.
+   */
+  ssrSecret: string;
+  /**
+   * Encrypt browser history state by default for every page. Individual pages can still opt in/out
+   * per request via `Inertia.encryptHistory()` / `clearHistory()`. Default: false.
+   */
+  encryptHistory: boolean;
+}
+
+/** Default directory (relative to the project root) for Inertia page components. */
+export const DEFAULT_PAGES_DIR = "resources/js/pages";
+
+const defaults: InertiaConfigShape = {
+  htmlTemplate: "./resources/app.html",
+  version: "1",
+  assetsUrl: "/",
+  pagesDir: DEFAULT_PAGES_DIR,
+  ssr: false,
+  ssrSecret: "",
+  encryptHistory: false,
+};
+
+/**
+ * Create a typed Inertia configuration object with defaults.
+ *
+ * @example
+ * import { InertiaConfig } from '@zerotal/inertia';
+ * export default InertiaConfig({
+ *   htmlTemplate: './resources/app.html',
+ *   version:      Bun.env['ASSET_VERSION'] ?? '1',
+ *   ssr:          true,   // enable SSR endpoint at POST /__ssr
+ * });
+ */
+export function InertiaConfig(options: Partial<InertiaConfigShape> = {}): InertiaConfigShape {
+  return deepMerge(defaults, options);
+}
+
+// Register this package's config namespace for typed config() dot-paths.
+declare module "@zerotal/core" {
+  interface ConfigRegistry {
+    inertia: InertiaConfigShape;
+  }
+}

package/src/css.ts

@@ -0,0 +1,7 @@
+/**
+ * CSS plugin detection for Inertia's Bun.build() pipeline.
+ *
+ * Re-exports from @zerotal/core so Pulse and other packages can share the same
+ * detection logic without creating cross-package dependencies.
+ */
+export { detectCssPlugins } from "@zerotal/core/dev";

package/src/errors.ts

@@ -0,0 +1,40 @@
+import { ZerotalError } from "@zerotal/core";
+
+/** Base class for all @zerotal/inertia errors. */
+export class InertiaError extends ZerotalError {
+  constructor(
+    message: string,
+    code = "E_INERTIA",
+    status = 500,
+    context?: Record<string, unknown>,
+  ) {
+    super(message, code, status, context);
+  }
+}
+
+/**
+ * Thrown when `inertia()` / `inertiaStream()` runs before the HTML template has been
+ * loaded — almost always because `InertiaProvider` is not registered.
+ */
+export class InertiaTemplateNotLoadedError extends InertiaError {
+  constructor() {
+    super(
+      "[Zerotal Inertia] HTML template not loaded. Did you register InertiaProvider in bootstrap/app.ts?",
+      "E_INERTIA_TEMPLATE_NOT_LOADED",
+    );
+  }
+}
+
+/** Thrown when a component name is unsafe (path traversal) or has no resolvable default export. */
+export class InvalidComponentError extends InertiaError {
+  constructor(component: string, reason = "is not a valid component") {
+    super(
+      `[Zerotal Inertia] Invalid component name '${component}': ${reason}.`,
+      "E_INERTIA_INVALID_COMPONENT",
+      500,
+      {
+        component,
+      },
+    );
+  }
+}

package/src/facades/Inertia.ts

@@ -0,0 +1,55 @@
+import { inertia, inertiaStream } from "../inertia.ts";
+import { optional, lazy, always, defer, merge, deepMerge, scroll } from "../props/PropTypes.ts";
+import { share } from "../share.ts";
+import { encryptHistory, clearHistory } from "../historyState.ts";
+import { location } from "../location.ts";
+
+/**
+ * Unified Inertia facade.
+ *
+ * @example
+ * import { Inertia } from "@zerotal/inertia";
+ *
+ * async index(http: HttpContext) {
+ *   return Inertia.render("Users/Index", {
+ *     users: Inertia.optional(() => User.all()),       // only on partial reload
+ *     stats: Inertia.defer(() => computeStats()),      // loaded after first paint
+ *     feed:  Inertia.merge(() => Post.paginate()),     // append on "load more"
+ *   });
+ * }
+ *
+ * Standalone helpers (`optional`, `always`, `defer`, `merge`, `deepMerge`, `lazy`) are also exported
+ * for direct import if you prefer not to go through the facade.
+ */
+export const Inertia = {
+  /** Render an Inertia page (= the `inertia()` helper). */
+  render: inertia,
+  /** Render an Inertia page using React streaming SSR. */
+  stream: inertiaStream,
+
+  /** Prop only included when explicitly requested via a partial reload's `only`. */
+  optional,
+  /** Alias of {@link optional}. */
+  lazy,
+  /** Prop always included, even on partial reloads that would otherwise exclude it. */
+  always,
+  /** Prop deferred to a follow-up request after the initial render. */
+  defer,
+  /** Prop the client appends (merges) into existing data on partial reloads. */
+  merge,
+  /** Prop the client deep-merges into existing data on partial reloads. */
+  deepMerge,
+  /** Infinite-scroll prop: merges paginated data and emits scroll metadata. */
+  scroll,
+
+  /** Register shared props included on every page. */
+  share,
+
+  /** Encrypt the current page's browser history state. */
+  encryptHistory,
+  /** Clear any encrypted history state (e.g. on logout). */
+  clearHistory,
+
+  /** External redirect (full-page visit). */
+  location,
+} as const;

package/src/global.d.ts

@@ -0,0 +1,70 @@
+// Ambient declarations specific to this package.
+// Bun, Node (node:*), and bun:test types come from @types/bun (→ bun-types).
+// Only declarations bun-types does NOT provide are kept here.
+
+// ── Bun globals ───────────────────────────────────────────────────────────
+interface Request {
+  readonly params?: Record<string, string>;
+}
+
+// ── SQLInstance ───────────────────────────────────────────────────────────
+interface SQLInstance {
+  <T = Record<string, unknown>>(
+    strings: TemplateStringsArray,
+    ...values: unknown[]
+  ): Promise<T[]>;
+  begin<T>(fn: (tx: SQLInstance) => Promise<T>): Promise<T>;
+  end(): Promise<void>;
+}
+
+// ── React type stubs ──────────────────────────────────────────────────────
+declare module 'react' {
+  export function createElement(type: unknown, props?: unknown, ...children: unknown[]): unknown;
+  export const version: string;
+}
+
+declare module 'react-dom/client' {
+  export function createRoot(container: Element | null): { render(el: unknown): void };
+}
+
+declare module 'react-dom/server' {
+  /** Render a React element to an HTML string (SSR). */
+  export function renderToString(element: unknown): string;
+  /** Render a React element to a static HTML string (no data-react attributes). */
+  export function renderToStaticMarkup(element: unknown): string;
+  /** Render a React element to a streaming ReadableStream (React 18+). */
+  export function renderToReadableStream(
+    element: unknown,
+    options?: {
+      signal?: AbortSignal;
+      onError?: (error: unknown) => void;
+    },
+  ): Promise<ReadableStream<Uint8Array>>;
+}
+
+// ── @inertiajs/react type stub ────────────────────────────────────────────
+declare module '@inertiajs/react' {
+  export function createInertiaApp(options: {
+    resolve: (name: string) => unknown | Promise<unknown>;
+    setup:   (args: { el: Element; App: unknown; props: unknown }) => void;
+  }): Promise<void>;
+
+  export function usePage<T = Record<string, unknown>>(): { props: T };
+  export function Link(props: { href: string; children?: unknown }): unknown;
+  export const router: {
+    visit(url: string): void;
+    post(url: string, data?: unknown): void;
+    put(url: string, data?: unknown): void;
+    delete(url: string): void;
+  };
+  export function useForm<T extends Record<string, unknown>>(initial: T): {
+    data:       T;
+    errors:     Partial<Record<keyof T, string>>;
+    processing: boolean;
+    setData(key: keyof T, value: unknown): void;
+    post(url: string): void;
+    put(url: string): void;
+    delete(url: string): void;
+    reset(): void;
+  };
+}

package/src/historyState.ts

@@ -0,0 +1,82 @@
+import { RequestContext } from "@zerotal/core";
+
+/**
+ * Per-request Inertia history-encryption flags.
+ *
+ * The server does not encrypt anything itself — encryption happens client-side. The server's job is
+ * to set the `encryptHistory` / `clearHistory` flags on the page object; the Inertia client reacts
+ * to them. Flags are stored per-request (keyed by the active HttpContext) so concurrent requests
+ * don't interfere.
+ */
+interface HistoryFlags {
+  encrypt?: boolean;
+  clear?: boolean;
+}
+
+const _store = new WeakMap<object, HistoryFlags>();
+let _defaultEncrypt = false;
+
+/**
+ * Set the global default for history encryption (from `inertia.encryptHistory` config).
+ *
+ * @param on - When `true`, every page encrypts its history state unless overridden per request.
+ * @internal
+ */
+export function setHistoryEncryptionDefault(on: boolean): void {
+  _defaultEncrypt = on;
+}
+
+function flagsForCurrent(): HistoryFlags {
+  const ctx = RequestContext.get() as unknown as object;
+  let flags = _store.get(ctx);
+  if (!flags) {
+    flags = {};
+    _store.set(ctx, flags);
+  }
+  return flags;
+}
+
+/**
+ * Encrypt the current page's history state in the browser (protects props cached in
+ * `history.state` for a page holding sensitive data). Effective for the current request.
+ *
+ * @param on - Pass `false` to opt this page out when encryption is the global default. Default `true`.
+ * @example
+ * ```ts
+ * async show(http: HttpContext): Promise<void> {
+ *   Inertia.encryptHistory();
+ *   return inertia('Account/Settings', { account });
+ * }
+ * ```
+ */
+export function encryptHistory(on = true): void {
+  flagsForCurrent().encrypt = on;
+}
+
+/**
+ * Clear any previously encrypted history state — call on logout so cached page data
+ * can't be recovered via the browser Back button.
+ *
+ * @example
+ * ```ts
+ * async destroy(http: HttpContext): Promise<void> {
+ *   await Auth.logout();
+ *   Inertia.clearHistory();
+ *   return redirect('/login');
+ * }
+ * ```
+ */
+export function clearHistory(): void {
+  flagsForCurrent().clear = true;
+}
+
+/** @internal Resolve the effective flags for the current request, applying the global default. */
+export function readHistoryFlags(): { encryptHistory?: boolean; clearHistory?: boolean } {
+  const ctx = RequestContext.tryGet() as unknown as object | undefined;
+  const flags = ctx ? _store.get(ctx) : undefined;
+  const encrypt = flags?.encrypt ?? _defaultEncrypt;
+  const out: { encryptHistory?: boolean; clearHistory?: boolean } = {};
+  if (encrypt) out.encryptHistory = true;
+  if (flags?.clear) out.clearHistory = true;
+  return out;
+}