@arkstack/inertia 0.15.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toneflix Technologies Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/commands/InertiaSsrCommand.d.ts

@@ -0,0 +1,17 @@
+import { Command } from "@h3ravel/musket";
+
+//#region src/commands/InertiaSsrCommand.d.ts
+/**
+ * Run the Inertia SSR server (the app's built SSR bundle) as a long-running
+ * process, restarting it if it crashes.
+ *
+ * The bundle is built separately (e.g. `vite build --ssr src/ssr.ts --outDir
+ * dist-ssr`); this command supervises it.
+ */
+declare class InertiaSsrCommand extends Command {
+  protected signature: string;
+  protected description: string;
+  handle(): Promise<void>;
+}
+//#endregion
+export { InertiaSsrCommand };

package/dist/commands/InertiaSsrCommand.js

@@ -0,0 +1,43 @@
+import { n as resolveSsrBundle, o as inertiaConfig, r as superviseProcess } from "../ssr-process-DkRTrGvf.js";
+import { Arkstack } from "@arkstack/contract";
+import { Command } from "@h3ravel/musket";
+import { existsSync } from "node:fs";
+//#region src/commands/InertiaSsrCommand.ts
+/**
+* Run the Inertia SSR server (the app's built SSR bundle) as a long-running
+* process, restarting it if it crashes.
+*
+* The bundle is built separately (e.g. `vite build --ssr src/ssr.ts --outDir
+* dist-ssr`); this command supervises it.
+*/
+var InertiaSsrCommand = class extends Command {
+	signature = `inertia:ssr
+        {--bundle= : Path to the built SSR bundle. Defaults to inertia.ssr.bundle or dist-ssr/ssr.js.}
+        {--no-restart : Do not restart the SSR server when it exits.}
+    `;
+	description = "Run the Inertia SSR server as a long-running process, restarting it if it crashes";
+	async handle() {
+		const bundle = resolveSsrBundle(Arkstack.rootDir(), this.option("bundle"), inertiaConfig().ssr.bundle);
+		if (!existsSync(bundle)) {
+			this.error(`Inertia SSR bundle not found at ${bundle}. Build it first, e.g. \`vite build --ssr src/ssr.ts --outDir dist-ssr\`.`);
+			return;
+		}
+		const restart = this.option("restart") !== false;
+		this.info(`Starting Inertia SSR server (${bundle})`);
+		const controller = superviseProcess(process.execPath, [bundle], {
+			cwd: Arkstack.rootDir(),
+			restart,
+			onExit: (code, willRestart) => {
+				if (willRestart) this.warn(`Inertia SSR server exited (code ${code}); restarting…`);
+			},
+			onError: (error) => {
+				this.error(`Failed to start Inertia SSR server: ${error.message}`);
+			}
+		});
+		process.once("SIGINT", () => controller.stop());
+		process.once("SIGTERM", () => controller.stop());
+		await controller.done;
+	}
+};
+//#endregion
+export { InertiaSsrCommand };

package/dist/index.d.ts

@@ -0,0 +1,377 @@
+import { Response } from "@arkstack/http";
+
+//#region src/types.d.ts
+/**
+ * A bag of props passed to an Inertia page. Values may be plain JSON-serializable
+ * data, synchronous/asynchronous callbacks (evaluated lazily when included), or
+ * one of the special prop wrappers ({@link LazyPropContract}, {@link AlwaysPropContract},
+ * {@link DeferPropContract}).
+ */
+type PageProps = Record<string, unknown>;
+/**
+ * The page object Inertia exchanges with the client. It is serialized to JSON for
+ * Inertia XHR visits and embedded in the root template's `data-page` attribute on
+ * the initial full-page visit.
+ *
+ * @see https://inertiajs.com/the-protocol
+ */
+interface InertiaPage {
+  /** The client-side page component to render, e.g. `Users/Index`. */
+  component: string;
+  /** The resolved props for the component. */
+  props: PageProps;
+  /** The URL of the current page (path + query). */
+  url: string;
+  /** The current asset version string. */
+  version: string;
+  /** Deferred prop keys grouped by fetch group, sent so the client can request them after load. */
+  deferredProps?: Record<string, string[]>;
+  /** Prop keys the client should merge into existing data instead of replacing. */
+  mergeProps?: string[];
+  /** Whether to clear the client-side history encryption state. */
+  clearHistory?: boolean;
+  /** Whether to encrypt the client-side history entry. */
+  encryptHistory?: boolean;
+}
+/** Configuration for the Inertia adapter, read from `config('inertia')`. */
+interface InertiaConfig {
+  /**
+   * The root Edge template that wraps the SPA and renders the `data-page`
+   * element. Defaults to `app`. When the view does not exist a minimal
+   * built-in template is used.
+   */
+  root_view: string;
+  /**
+   * The id of the root DOM element the client mounts onto (the element that
+   * carries the `data-page` attribute). Defaults to `app`.
+   */
+  root_id: string;
+  /**
+   * The asset version. A string, or a function returning one. When the client
+   * reports a different version on a GET visit, the adapter responds with a
+   * `409` and an `X-Inertia-Location` header so the client performs a full
+   * reload. Defaults to `null` (versioning disabled).
+   */
+  version: string | null | (() => string | null | Promise<string | null>);
+  /** Server-side rendering options. */
+  ssr: {
+    /** Whether the initial visit is rendered by the external SSR server. */enabled: boolean; /** The SSR server's render endpoint. Defaults to the standard Inertia address. */
+    url?: string;
+    /**
+     * Path to the built SSR bundle run by `ark inertia:ssr`. Relative paths
+     * are resolved from the app root. Defaults to `dist-ssr/ssr.js`.
+     */
+    bundle?: string;
+  };
+}
+/**
+ * The normalized, driver-agnostic view of the current request that the Inertia
+ * adapter needs. Each driver middleware constructs one of these from its native
+ * request object.
+ */
+interface InertiaRequest {
+  /** The HTTP method, upper-cased (e.g. `GET`, `POST`, `PUT`). */
+  method: string;
+  /** The request URL used as `page.url` (path + query string). */
+  url: string;
+  /** Read a request header by (case-insensitive) name. */
+  header(name: string): string | undefined;
+}
+/** Marker contract for a prop that is only included on matching partial reloads. */
+interface LazyPropContract {
+  readonly __inertia: 'lazy';
+  call(): unknown;
+}
+/** Marker contract for a prop that is always included, even on partial reloads. */
+interface AlwaysPropContract {
+  readonly __inertia: 'always';
+  call(): unknown;
+}
+/**
+ * Marker contract for a prop excluded from the initial response and fetched by
+ * the client in a follow-up request, optionally grouped with other deferred props.
+ */
+interface DeferPropContract {
+  readonly __inertia: 'defer';
+  readonly group: string;
+  call(): unknown;
+}
+/** Any of the special Inertia prop wrappers. */
+type InertiaPropWrapper = LazyPropContract | AlwaysPropContract | DeferPropContract;
+//#endregion
+//#region src/props.d.ts
+/**
+ * A prop that is excluded from the initial page load and only resolved when the
+ * client explicitly requests it via a partial reload. Use for expensive data the
+ * first render does not need.
+ */
+declare class LazyProp implements LazyPropContract {
+  private readonly callback;
+  readonly __inertia: "lazy";
+  constructor(callback: () => unknown);
+  call(): unknown;
+}
+/**
+ * A prop that is always included in the response — even on partial reloads that
+ * do not list it — and cannot be filtered out by `only`/`except`.
+ */
+declare class AlwaysProp implements AlwaysPropContract {
+  private readonly value;
+  readonly __inertia: "always";
+  constructor(value: unknown);
+  call(): unknown;
+}
+/**
+ * A prop excluded from the initial response and fetched by the client in a
+ * follow-up request after the page loads. Deferred props sharing a `group` are
+ * fetched together in a single request.
+ */
+declare class DeferProp implements DeferPropContract {
+  private readonly callback;
+  readonly group: string;
+  readonly __inertia: "defer";
+  constructor(callback: () => unknown, group?: string);
+  call(): unknown;
+}
+/** Narrow an arbitrary value to one of the Inertia prop wrappers. */
+declare const isPropWrapper: (value: unknown) => value is InertiaPropWrapper;
+declare const isLazyProp: (value: unknown) => value is LazyPropContract;
+declare const isAlwaysProp: (value: unknown) => value is AlwaysPropContract;
+declare const isDeferProp: (value: unknown) => value is DeferPropContract;
+//#endregion
+//#region src/Inertia.d.ts
+/**
+ * The Inertia adapter. Build server-driven SPA responses: controllers return
+ * `Inertia.render('Page', props)` and the adapter emits either a JSON page object
+ * (for Inertia XHR visits) or a full HTML document embedding the page (for the
+ * initial visit). Shared props, partial reloads, asset versioning, deferred and
+ * lazy props, and redirect status semantics are all handled here.
+ *
+ * @see https://inertiajs.com/the-protocol
+ */
+declare class Inertia {
+  /** Require an active request context, throwing a clear error otherwise. */
+  private static request;
+  /**
+   * Render an Inertia page. Returns a {@link Response} the runtime serializes:
+   * a JSON page object for Inertia visits, or a full HTML document for the
+   * initial page load.
+   *
+   * @param component  The client component name, e.g. `Users/Index`.
+   * @param props      Props for the component (plain values, callbacks, or prop wrappers).
+   */
+  static render(component: string, props?: PageProps): Promise<Response>;
+  /**
+   * Redirect to an external URL. On an Inertia visit this responds `409` with
+   * an `X-Inertia-Location` header so the client performs a full page visit;
+   * otherwise it issues a normal `302` redirect.
+   */
+  static location(url: string): Response;
+  /**
+   * Redirect within the app. For `PUT`/`PATCH`/`DELETE` requests the status is
+   * upgraded to `303 See Other` (per the Inertia protocol) unless an explicit
+   * status is given, so the client follows the redirect with a `GET`.
+   */
+  static redirect(url: string, status?: number): Response;
+  /** Redirect back to the referring URL (or `fallback`). */
+  static back(fallback?: string): Response;
+  /** A `409` response carrying an `X-Inertia-Location` header. */
+  private static conflict;
+  /**
+   * Share props with every Inertia response. Called inside a request the data
+   * is scoped to that request; called outside (e.g. at boot) it applies globally.
+   */
+  static share(key: string, value: unknown): void;
+  static share(data: PageProps): void;
+  /** Read the currently shared props (request-scoped when in a request). */
+  static shared(): PageProps;
+  /** Set the asset version used for cache-busting, overriding config. */
+  static version(version: InertiaConfig['version']): void;
+  /** Override Inertia configuration at runtime (e.g. enable SSR programmatically). */
+  static configure(partial: Partial<InertiaConfig>): void;
+  /**
+   * A prop only resolved on a partial reload that explicitly requests it.
+   * Excluded from the initial page load.
+   */
+  static lazy(callback: () => unknown): LazyProp;
+  /** Alias of {@link Inertia.lazy} matching the modern Inertia client naming. */
+  static optional(callback: () => unknown): LazyProp;
+  /** A prop always included in the response, even on partial reloads. */
+  static always(value: unknown): AlwaysProp;
+  /**
+   * A prop excluded from the initial response and fetched by the client after
+   * load. Deferred props sharing a `group` are fetched together.
+   */
+  static defer(callback: () => unknown, group?: string): DeferProp;
+}
+//#endregion
+//#region src/helpers.d.ts
+/**
+ * Render an Inertia page, or — when called with no arguments — return the
+ * {@link Inertia} manager for chaining (`inertia().share(...)`,
+ * `inertia().version(...)`).
+ *
+ * @example
+ * ```ts
+ * // In a controller
+ * return inertia('Users/Index', { users: await User.all() })
+ *
+ * // Share data with every response
+ * inertia().share('appName', config('app.name'))
+ * ```
+ */
+declare function inertia(): typeof Inertia;
+declare function inertia(component: string, props?: PageProps): Promise<Response>;
+//#endregion
+//#region src/resolve.d.ts
+interface ResolvedProps {
+  props: PageProps;
+  deferredProps?: Record<string, string[]>;
+}
+/**
+ * Filter and evaluate page props for the current request, honouring Inertia's
+ * partial-reload semantics:
+ *
+ * - On a full visit or a non-matching partial, lazy and deferred props are
+ *   excluded; `always` and plain props are included.
+ * - On a partial reload matching this component, only the requested keys
+ *   (`X-Inertia-Partial-Data`) are kept — minus `X-Inertia-Partial-Except` —
+ *   while `always` props are always kept.
+ *
+ * Deferred props are advertised under `deferredProps` (grouped) on the initial
+ * response so the client can request them afterwards.
+ */
+declare const resolveProps: (component: string, props: PageProps, request: InertiaRequest) => Promise<ResolvedProps>;
+//#endregion
+//#region src/html.d.ts
+/** Escape a string for safe inclusion in a double-quoted HTML attribute. */
+declare const escapeHtmlAttribute: (value: string) => string;
+/**
+ * Build the root mount element carrying the serialized page object in its
+ * `data-page` attribute — the element the Inertia client adapter hydrates.
+ */
+declare const renderDataPage: (page: InertiaPage, rootId: string) => string;
+/** Minimal built-in root document used when the configured root view is absent. */
+declare const builtInTemplate: (mount: string, head?: string) => string;
+/**
+ * Render the full HTML document for an initial (non-XHR) visit.
+ *
+ * When SSR is enabled the page is rendered by the external SSR server and its
+ * markup + head tags are embedded; if the SSR server is unavailable it falls back
+ * to a client-rendered mount element. The result is wrapped by the configured
+ * `root_view` Edge template (which receives `inertia` and `inertiaHead`
+ * variables), or a minimal built-in document when that view is absent.
+ */
+declare const renderRootHtml: (page: InertiaPage, config: InertiaConfig) => Promise<string>;
+//#endregion
+//#region src/ssr.d.ts
+/** The default address the Inertia SSR server listens on. */
+declare const DEFAULT_SSR_URL = "http://127.0.0.1:13714/render";
+/** The payload returned by an Inertia SSR server for a rendered page. */
+interface SsrResponse {
+  /** HTML strings to inject into the document `<head>` (title, meta, style). */
+  head: string[];
+  /** The rendered `<div id="app" data-page="…">…</div>` mount element. */
+  body: string;
+}
+/**
+ * Render a page via an external Inertia SSR server.
+ *
+ * POSTs the page object to the SSR endpoint (a Node process running the app's SSR
+ * bundle) and returns its `{ head, body }`. Returns `null` on any failure — an
+ * unreachable server, a non-2xx response, or a malformed payload — so the caller
+ * can fall back to client-side rendering rather than failing the request.
+ *
+ * @see https://inertiajs.com/server-side-rendering
+ */
+declare const renderViaSsr: (page: InertiaPage, url?: string) => Promise<SsrResponse | null>;
+//#endregion
+//#region src/ssr-process.d.ts
+/** The default location of the built SSR bundle, relative to the app root. */
+declare const DEFAULT_SSR_BUNDLE = "dist-ssr/ssr.js";
+/**
+ * Resolve the SSR bundle path run by `ark inertia:ssr`.
+ *
+ * Precedence: an explicit `--bundle` option, then `inertia.ssr.bundle` config,
+ * then {@link DEFAULT_SSR_BUNDLE}. Relative paths are resolved from `rootDir`.
+ */
+declare const resolveSsrBundle: (rootDir: string, option?: string, configured?: string) => string;
+interface SuperviseOptions {
+  /** Working directory for the spawned process. */
+  cwd?: string;
+  /** Restart the process when it exits unexpectedly (default `true`). */
+  restart?: boolean;
+  /** Delay before restarting after a crash, in ms (default `1000`). */
+  restartDelayMs?: number;
+  /** Called when the child exits; `willRestart` reflects the restart decision. */
+  onExit?: (code: number | null, willRestart: boolean) => void;
+  /** Called when the child fails to spawn. */
+  onError?: (error: Error) => void;
+}
+/** Handle to a supervised process. */
+interface SsrProcessController {
+  /** Stop the process and prevent further restarts. */
+  stop(): void;
+  /** Resolves when the process has stopped (and will not restart). */
+  done: Promise<void>;
+}
+/**
+ * Spawn and supervise a long-running process, restarting it when it crashes
+ * until {@link SsrProcessController.stop} is called. Used by `ark inertia:ssr` to
+ * keep the Inertia SSR server alive.
+ */
+declare const superviseProcess: (command: string, args: string[], options?: SuperviseOptions) => SsrProcessController;
+//#endregion
+//#region src/config.d.ts
+/** The defaults applied when an app provides no (or partial) `inertia` config. */
+declare const defaultConfig: InertiaConfig;
+/**
+ * Override Inertia configuration at runtime, taking precedence over
+ * `src/config/inertia.ts`. Useful for programmatic setups and tests. Merges
+ * shallowly, with `ssr` merged one level deep.
+ */
+declare const configure: (partial: Partial<InertiaConfig>) => void;
+/** Clear any runtime configuration overrides (primarily for tests). */
+declare const resetConfig: () => void;
+/**
+ * Read the merged Inertia configuration. Runtime overrides ({@link configure})
+ * are layered over the app's `src/config/inertia.ts`, which is layered over
+ * {@link defaultConfig}. Never throws — a missing config file falls back entirely
+ * to the defaults.
+ */
+declare const inertiaConfig: () => InertiaConfig;
+/** Set the asset version at runtime, taking precedence over config. */
+declare const setVersion: (version: InertiaConfig["version"]) => void;
+/** Resolve the current asset version to a string (empty string when disabled). */
+declare const resolveVersion: () => Promise<string>;
+//#endregion
+//#region src/context.d.ts
+/** Per-request state the Inertia adapter carries through the request lifecycle. */
+interface InertiaStore {
+  /** The normalized current request. */
+  request: InertiaRequest;
+  /** Props shared for the duration of this request (seeded from the global bag). */
+  shared: PageProps;
+}
+/** Run `callback` with `request` bound as the active Inertia context. */
+declare const runInertia: <T>(request: InertiaRequest, callback: () => T) => T;
+/** The active store, or `undefined` when called outside an Inertia request. */
+declare const currentStore: () => InertiaStore | undefined;
+/** Merge data into the shared bag — the current request's if active, else the global one. */
+declare const shareData: (data: PageProps) => void;
+/** Read the effective shared bag (request-scoped when active, else global). */
+declare const sharedData: () => PageProps;
+/** Remove every globally shared prop (primarily for tests). */
+declare const flushShared: () => void;
+//#endregion
+//#region src/protocol.d.ts
+/** Methods whose redirects must use `303 See Other` so the Inertia client re-issues a GET. */
+declare const SEE_OTHER_METHODS: Set<string>;
+/**
+ * Whether a `302` redirect produced for the given method should be upgraded to a
+ * `303 See Other` on an Inertia visit. Inertia's client follows a `303` with a
+ * `GET`, which is required after `PUT`/`PATCH`/`DELETE` mutations.
+ */
+declare const shouldUpgradeRedirect: (method: string, status: number) => boolean;
+//#endregion
+export { AlwaysProp, AlwaysPropContract, DEFAULT_SSR_BUNDLE, DEFAULT_SSR_URL, DeferProp, DeferPropContract, Inertia, InertiaConfig, InertiaPage, InertiaPropWrapper, InertiaRequest, type InertiaStore, LazyProp, LazyPropContract, PageProps, SEE_OTHER_METHODS, type SsrProcessController, type SsrResponse, type SuperviseOptions, builtInTemplate, configure, currentStore, defaultConfig, escapeHtmlAttribute, flushShared, inertia, inertiaConfig, isAlwaysProp, isDeferProp, isLazyProp, isPropWrapper, renderDataPage, renderRootHtml, renderViaSsr, resetConfig, resolveProps, resolveSsrBundle, resolveVersion, runInertia, setVersion, shareData, sharedData, shouldUpgradeRedirect, superviseProcess };

package/dist/index.js

@@ -0,0 +1,394 @@
+import { a as defaultConfig, c as resolveVersion, i as configure, l as setVersion, n as resolveSsrBundle, o as inertiaConfig, r as superviseProcess, s as resetConfig, t as DEFAULT_SSR_BUNDLE } from "./ssr-process-DkRTrGvf.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Response } from "@arkstack/http";
+//#region src/props.ts
+/**
+* A prop that is excluded from the initial page load and only resolved when the
+* client explicitly requests it via a partial reload. Use for expensive data the
+* first render does not need.
+*/
+var LazyProp = class {
+	callback;
+	__inertia = "lazy";
+	constructor(callback) {
+		this.callback = callback;
+	}
+	call() {
+		return this.callback();
+	}
+};
+/**
+* A prop that is always included in the response — even on partial reloads that
+* do not list it — and cannot be filtered out by `only`/`except`.
+*/
+var AlwaysProp = class {
+	value;
+	__inertia = "always";
+	constructor(value) {
+		this.value = value;
+	}
+	call() {
+		return typeof this.value === "function" ? this.value() : this.value;
+	}
+};
+/**
+* A prop excluded from the initial response and fetched by the client in a
+* follow-up request after the page loads. Deferred props sharing a `group` are
+* fetched together in a single request.
+*/
+var DeferProp = class {
+	callback;
+	group;
+	__inertia = "defer";
+	constructor(callback, group = "default") {
+		this.callback = callback;
+		this.group = group;
+	}
+	call() {
+		return this.callback();
+	}
+};
+/** Narrow an arbitrary value to one of the Inertia prop wrappers. */
+const isPropWrapper = (value) => {
+	return Boolean(value && typeof value === "object" && "__inertia" in value && typeof value.call === "function");
+};
+const isLazyProp = (value) => isPropWrapper(value) && value.__inertia === "lazy";
+const isAlwaysProp = (value) => isPropWrapper(value) && value.__inertia === "always";
+const isDeferProp = (value) => isPropWrapper(value) && value.__inertia === "defer";
+//#endregion
+//#region src/context.ts
+/**
+* Async-local store binding the current request to the Inertia helpers. The
+* driver middleware runs the downstream handler inside {@link runInertia} so that
+* `inertia()` / `Inertia.*` can resolve the active request and shared props
+* without threading them through every call — mirroring how resora binds its
+* `{ req, res }` context.
+*/
+const storage = new AsyncLocalStorage();
+/**
+* Props shared across every request (set outside a request, e.g. at boot). Each
+* request seeds its own {@link InertiaStore.shared} bag from this so per-request
+* sharing never leaks between requests.
+*/
+const globalShared = {};
+/** Run `callback` with `request` bound as the active Inertia context. */
+const runInertia = (request, callback) => {
+	return storage.run({
+		request,
+		shared: { ...globalShared }
+	}, callback);
+};
+/** The active store, or `undefined` when called outside an Inertia request. */
+const currentStore = () => storage.getStore();
+/** Merge data into the shared bag — the current request's if active, else the global one. */
+const shareData = (data) => {
+	const target = storage.getStore()?.shared ?? globalShared;
+	Object.assign(target, data);
+};
+/** Read the effective shared bag (request-scoped when active, else global). */
+const sharedData = () => {
+	return storage.getStore()?.shared ?? globalShared;
+};
+/** Remove every globally shared prop (primarily for tests). */
+const flushShared = () => {
+	for (const key of Object.keys(globalShared)) delete globalShared[key];
+};
+//#endregion
+//#region src/protocol.ts
+/** Methods whose redirects must use `303 See Other` so the Inertia client re-issues a GET. */
+const SEE_OTHER_METHODS = new Set([
+	"PUT",
+	"PATCH",
+	"DELETE"
+]);
+/**
+* Whether a `302` redirect produced for the given method should be upgraded to a
+* `303 See Other` on an Inertia visit. Inertia's client follows a `303` with a
+* `GET`, which is required after `PUT`/`PATCH`/`DELETE` mutations.
+*/
+const shouldUpgradeRedirect = (method, status) => {
+	return status === 302 && SEE_OTHER_METHODS.has(method.toUpperCase());
+};
+//#endregion
+//#region src/ssr.ts
+/** The default address the Inertia SSR server listens on. */
+const DEFAULT_SSR_URL = "http://127.0.0.1:13714/render";
+/**
+* Render a page via an external Inertia SSR server.
+*
+* POSTs the page object to the SSR endpoint (a Node process running the app's SSR
+* bundle) and returns its `{ head, body }`. Returns `null` on any failure — an
+* unreachable server, a non-2xx response, or a malformed payload — so the caller
+* can fall back to client-side rendering rather than failing the request.
+*
+* @see https://inertiajs.com/server-side-rendering
+*/
+const renderViaSsr = async (page, url = DEFAULT_SSR_URL) => {
+	try {
+		const response = await fetch(url, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(page)
+		});
+		if (!response.ok) return null;
+		const data = await response.json();
+		if (!data || typeof data.body !== "string") return null;
+		return {
+			head: Array.isArray(data.head) ? data.head : [],
+			body: data.body
+		};
+	} catch {
+		return null;
+	}
+};
+//#endregion
+//#region src/html.ts
+/** Escape a string for safe inclusion in a double-quoted HTML attribute. */
+const escapeHtmlAttribute = (value) => {
+	return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/'/g, "&#39;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+};
+/**
+* Build the root mount element carrying the serialized page object in its
+* `data-page` attribute — the element the Inertia client adapter hydrates.
+*/
+const renderDataPage = (page, rootId) => {
+	return `<div id="${rootId}" data-page="${escapeHtmlAttribute(JSON.stringify(page))}"></div>`;
+};
+/** Minimal built-in root document used when the configured root view is absent. */
+const builtInTemplate = (mount, head = "") => {
+	return [
+		"<!DOCTYPE html>",
+		"<html>",
+		"<head>",
+		"<meta charset=\"utf-8\">",
+		"<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">",
+		...head ? [head] : [],
+		"</head>",
+		"<body>",
+		mount,
+		"</body>",
+		"</html>"
+	].join("\n");
+};
+/**
+* Render the full HTML document for an initial (non-XHR) visit.
+*
+* When SSR is enabled the page is rendered by the external SSR server and its
+* markup + head tags are embedded; if the SSR server is unavailable it falls back
+* to a client-rendered mount element. The result is wrapped by the configured
+* `root_view` Edge template (which receives `inertia` and `inertiaHead`
+* variables), or a minimal built-in document when that view is absent.
+*/
+const renderRootHtml = async (page, config) => {
+	let mount = renderDataPage(page, config.root_id);
+	let head = "";
+	if (config.ssr?.enabled) {
+		const ssr = await renderViaSsr(page, config.ssr.url);
+		if (ssr) {
+			mount = ssr.body;
+			head = ssr.head.join("\n");
+		}
+	}
+	try {
+		const { view } = await import("@arkstack/view");
+		if (view().exists(config.root_view)) return await view(config.root_view, {
+			page,
+			inertia: mount,
+			inertiaHead: head
+		}).render();
+	} catch {}
+	return builtInTemplate(mount, head);
+};
+//#endregion
+//#region src/resolve.ts
+/** Parse a comma-separated partial-reload header into a trimmed, non-empty list. */
+const csv = (value) => {
+	if (!value) return [];
+	return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+};
+/** Recursively evaluate prop wrappers and callbacks within a value. */
+const evaluate = async (value) => {
+	if (isPropWrapper(value)) return evaluate(value.call());
+	if (typeof value === "function") return evaluate(value());
+	if (value && typeof value.then === "function") return evaluate(await value);
+	if (Array.isArray(value)) return Promise.all(value.map((entry) => evaluate(entry)));
+	if (value && typeof value === "object" && value.constructor === Object) {
+		const entries = await Promise.all(Object.entries(value).map(async ([key, val]) => [key, await evaluate(val)]));
+		return Object.fromEntries(entries);
+	}
+	return value;
+};
+/**
+* Filter and evaluate page props for the current request, honouring Inertia's
+* partial-reload semantics:
+*
+* - On a full visit or a non-matching partial, lazy and deferred props are
+*   excluded; `always` and plain props are included.
+* - On a partial reload matching this component, only the requested keys
+*   (`X-Inertia-Partial-Data`) are kept — minus `X-Inertia-Partial-Except` —
+*   while `always` props are always kept.
+*
+* Deferred props are advertised under `deferredProps` (grouped) on the initial
+* response so the client can request them afterwards.
+*/
+const resolveProps = async (component, props, request) => {
+	const isPartial = request.header("x-inertia") === "true" && request.header("x-inertia-partial-component") === component;
+	const only = csv(request.header("x-inertia-partial-data"));
+	const except = csv(request.header("x-inertia-partial-except"));
+	const deferred = {};
+	const included = {};
+	for (const [key, value] of Object.entries(props)) {
+		let include;
+		if (!isPartial) {
+			if (isDeferProp(value)) (deferred[value.group] ??= []).push(key);
+			include = !isLazyProp(value) && !isDeferProp(value);
+		} else {
+			include = only.length ? only.includes(key) : true;
+			if (except.length && except.includes(key)) include = false;
+			if (isDeferProp(value) && !only.includes(key)) include = false;
+		}
+		if (isAlwaysProp(value)) include = true;
+		if (include) included[key] = await evaluate(value);
+	}
+	return {
+		props: included,
+		deferredProps: !isPartial && Object.keys(deferred).length ? deferred : void 0
+	};
+};
+//#endregion
+//#region src/Inertia.ts
+const isInertiaRequest = (request) => request.header("x-inertia") === "true";
+const jsonResponse = (page) => {
+	return new Response({
+		statusCode: 200,
+		body: page
+	}).header("Content-Type", "application/json; charset=utf-8").header("Vary", "X-Inertia").header("X-Inertia", "true");
+};
+const htmlResponse = (html) => {
+	return new Response({
+		statusCode: 200,
+		body: html
+	}).header("Content-Type", "text/html; charset=utf-8").header("Vary", "X-Inertia");
+};
+/**
+* The Inertia adapter. Build server-driven SPA responses: controllers return
+* `Inertia.render('Page', props)` and the adapter emits either a JSON page object
+* (for Inertia XHR visits) or a full HTML document embedding the page (for the
+* initial visit). Shared props, partial reloads, asset versioning, deferred and
+* lazy props, and redirect status semantics are all handled here.
+*
+* @see https://inertiajs.com/the-protocol
+*/
+var Inertia = class Inertia {
+	/** Require an active request context, throwing a clear error otherwise. */
+	static request() {
+		const store = currentStore();
+		if (!store) throw new Error("Inertia called outside of a request. Ensure the Inertia middleware is registered.");
+		return store.request;
+	}
+	/**
+	* Render an Inertia page. Returns a {@link Response} the runtime serializes:
+	* a JSON page object for Inertia visits, or a full HTML document for the
+	* initial page load.
+	*
+	* @param component  The client component name, e.g. `Users/Index`.
+	* @param props      Props for the component (plain values, callbacks, or prop wrappers).
+	*/
+	static async render(component, props = {}) {
+		const request = Inertia.request();
+		const config = inertiaConfig();
+		const version = await resolveVersion();
+		if (isInertiaRequest(request) && request.method === "GET" && (request.header("x-inertia-version") ?? "") !== version) return Inertia.conflict(request.url);
+		const { props: resolved, deferredProps } = await resolveProps(component, {
+			...sharedData(),
+			...props
+		}, request);
+		const page = {
+			component,
+			props: resolved,
+			url: request.url,
+			version,
+			...deferredProps ? { deferredProps } : {}
+		};
+		if (isInertiaRequest(request)) return jsonResponse(page);
+		return htmlResponse(await renderRootHtml(page, config));
+	}
+	/**
+	* Redirect to an external URL. On an Inertia visit this responds `409` with
+	* an `X-Inertia-Location` header so the client performs a full page visit;
+	* otherwise it issues a normal `302` redirect.
+	*/
+	static location(url) {
+		if (isInertiaRequest(Inertia.request())) return Inertia.conflict(url);
+		return Inertia.redirect(url, 302);
+	}
+	/**
+	* Redirect within the app. For `PUT`/`PATCH`/`DELETE` requests the status is
+	* upgraded to `303 See Other` (per the Inertia protocol) unless an explicit
+	* status is given, so the client follows the redirect with a `GET`.
+	*/
+	static redirect(url, status) {
+		const method = Inertia.request().method;
+		return new Response({
+			statusCode: status ?? (SEE_OTHER_METHODS.has(method) ? 303 : 302),
+			body: null
+		}).header("Location", url);
+	}
+	/** Redirect back to the referring URL (or `fallback`). */
+	static back(fallback = "/") {
+		const request = Inertia.request();
+		return Inertia.redirect(request.header("referer") || request.header("referrer") || fallback);
+	}
+	/** A `409` response carrying an `X-Inertia-Location` header. */
+	static conflict(url) {
+		return new Response({
+			statusCode: 409,
+			body: null
+		}).header("X-Inertia-Location", url);
+	}
+	static share(keyOrData, value) {
+		shareData(typeof keyOrData === "string" ? { [keyOrData]: value } : keyOrData);
+	}
+	/** Read the currently shared props (request-scoped when in a request). */
+	static shared() {
+		return { ...sharedData() };
+	}
+	/** Set the asset version used for cache-busting, overriding config. */
+	static version(version) {
+		setVersion(version);
+	}
+	/** Override Inertia configuration at runtime (e.g. enable SSR programmatically). */
+	static configure(partial) {
+		configure(partial);
+	}
+	/**
+	* A prop only resolved on a partial reload that explicitly requests it.
+	* Excluded from the initial page load.
+	*/
+	static lazy(callback) {
+		return new LazyProp(callback);
+	}
+	/** Alias of {@link Inertia.lazy} matching the modern Inertia client naming. */
+	static optional(callback) {
+		return new LazyProp(callback);
+	}
+	/** A prop always included in the response, even on partial reloads. */
+	static always(value) {
+		return new AlwaysProp(value);
+	}
+	/**
+	* A prop excluded from the initial response and fetched by the client after
+	* load. Deferred props sharing a `group` are fetched together.
+	*/
+	static defer(callback, group = "default") {
+		return new DeferProp(callback, group);
+	}
+};
+//#endregion
+//#region src/helpers.ts
+function inertia(component, props = {}) {
+	if (component === void 0) return Inertia;
+	return Inertia.render(component, props);
+}
+//#endregion
+export { AlwaysProp, DEFAULT_SSR_BUNDLE, DEFAULT_SSR_URL, DeferProp, Inertia, LazyProp, SEE_OTHER_METHODS, builtInTemplate, configure, currentStore, defaultConfig, escapeHtmlAttribute, flushShared, inertia, inertiaConfig, isAlwaysProp, isDeferProp, isLazyProp, isPropWrapper, renderDataPage, renderRootHtml, renderViaSsr, resetConfig, resolveProps, resolveSsrBundle, resolveVersion, runInertia, setVersion, shareData, sharedData, shouldUpgradeRedirect, superviseProcess };

package/dist/setup.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/setup.js

@@ -0,0 +1,30 @@
+import { Publisher } from "@arkstack/common";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/setup.ts
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+/**
+* Register the artifacts `@arkstack/inertia` publishes into the application.
+*
+* Run `ark publish --package @arkstack/inertia` to copy the Inertia config and
+* the root Edge template into the app, then customize them for your front-end
+* (Vite tags, title, meta, etc.).
+*/
+Publisher.publishes({
+	package: "@arkstack/inertia",
+	tag: "inertia-config",
+	entries: [{
+		from: join(root, "stubs/config/inertia.ts.stub"),
+		to: "src/config/inertia.ts"
+	}]
+});
+Publisher.publishes({
+	package: "@arkstack/inertia",
+	tag: "inertia-views",
+	entries: [{
+		from: join(root, "stubs/views/app.edge.stub"),
+		to: "src/resources/views/app.edge"
+	}]
+});
+//#endregion
+export {};

package/dist/ssr-process-DkRTrGvf.js

@@ -0,0 +1,127 @@
+import { config } from "@arkstack/common";
+import { spawn } from "node:child_process";
+import { isAbsolute, join } from "node:path";
+//#region src/config.ts
+/** The defaults applied when an app provides no (or partial) `inertia` config. */
+const defaultConfig = {
+	root_view: "app",
+	root_id: "app",
+	version: null,
+	ssr: { enabled: false }
+};
+/** Runtime overrides applied on top of file config via {@link configure}. */
+let configOverrides = {};
+/**
+* Override Inertia configuration at runtime, taking precedence over
+* `src/config/inertia.ts`. Useful for programmatic setups and tests. Merges
+* shallowly, with `ssr` merged one level deep.
+*/
+const configure = (partial) => {
+	configOverrides = {
+		...configOverrides,
+		...partial,
+		...partial.ssr ? { ssr: {
+			...configOverrides.ssr,
+			...partial.ssr
+		} } : {}
+	};
+};
+/** Clear any runtime configuration overrides (primarily for tests). */
+const resetConfig = () => {
+	configOverrides = {};
+};
+/**
+* Read the merged Inertia configuration. Runtime overrides ({@link configure})
+* are layered over the app's `src/config/inertia.ts`, which is layered over
+* {@link defaultConfig}. Never throws — a missing config file falls back entirely
+* to the defaults.
+*/
+const inertiaConfig = () => {
+	let userConfig;
+	try {
+		userConfig = config("inertia", {});
+	} catch {
+		userConfig = void 0;
+	}
+	return {
+		...defaultConfig,
+		...userConfig ?? {},
+		...configOverrides,
+		ssr: {
+			...defaultConfig.ssr,
+			...userConfig?.ssr ?? {},
+			...configOverrides.ssr ?? {}
+		}
+	};
+};
+/** A version override set at runtime via `Inertia.version(...)`, if any. */
+let versionOverride;
+/** Set the asset version at runtime, taking precedence over config. */
+const setVersion = (version) => {
+	versionOverride = version;
+};
+/** Resolve the current asset version to a string (empty string when disabled). */
+const resolveVersion = async () => {
+	const source = versionOverride ?? inertiaConfig().version;
+	const value = typeof source === "function" ? await source() : source;
+	return value == null ? "" : String(value);
+};
+//#endregion
+//#region src/ssr-process.ts
+/** The default location of the built SSR bundle, relative to the app root. */
+const DEFAULT_SSR_BUNDLE = "dist-ssr/ssr.js";
+/**
+* Resolve the SSR bundle path run by `ark inertia:ssr`.
+*
+* Precedence: an explicit `--bundle` option, then `inertia.ssr.bundle` config,
+* then {@link DEFAULT_SSR_BUNDLE}. Relative paths are resolved from `rootDir`.
+*/
+const resolveSsrBundle = (rootDir, option, configured) => {
+	const bundle = option || configured || "dist-ssr/ssr.js";
+	return isAbsolute(bundle) ? bundle : join(rootDir, bundle);
+};
+/**
+* Spawn and supervise a long-running process, restarting it when it crashes
+* until {@link SsrProcessController.stop} is called. Used by `ark inertia:ssr` to
+* keep the Inertia SSR server alive.
+*/
+const superviseProcess = (command, args, options = {}) => {
+	const { cwd, restart = true, restartDelayMs = 1e3 } = options;
+	let child;
+	let timer;
+	let stopping = false;
+	let resolveDone = () => {};
+	const done = new Promise((resolve) => {
+		resolveDone = resolve;
+	});
+	const start = () => {
+		child = spawn(command, args, {
+			cwd,
+			stdio: "inherit"
+		});
+		child.on("error", (error) => {
+			options.onError?.(error);
+			resolveDone();
+		});
+		child.on("exit", (code) => {
+			const willRestart = !stopping && restart;
+			options.onExit?.(code, willRestart);
+			if (!willRestart) {
+				resolveDone();
+				return;
+			}
+			timer = setTimeout(start, restartDelayMs);
+		});
+	};
+	start();
+	return {
+		stop() {
+			stopping = true;
+			if (timer) clearTimeout(timer);
+			child?.kill("SIGTERM");
+		},
+		done
+	};
+};
+//#endregion
+export { defaultConfig as a, resolveVersion as c, configure as i, setVersion as l, resolveSsrBundle as n, inertiaConfig as o, superviseProcess as r, resetConfig as s, DEFAULT_SSR_BUNDLE as t };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@arkstack/inertia",
+  "version": "0.15.0",
+  "type": "module",
+  "description": "InertiaJS server-side adapter for Arkstack, building the modern monolith with server-driven SPAs.",
+  "homepage": "https://arkstack.toneflix.net/guide/inertia",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arkstack-hq/arkstack.git",
+    "directory": "packages/inertia"
+  },
+  "keywords": [
+    "inertia",
+    "inertiajs",
+    "spa",
+    "monolith",
+    "vue",
+    "react",
+    "svelte",
+    "arkstack"
+  ],
+  "files": [
+    "dist",
+    "stubs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./commands/InertiaSsrCommand": "./dist/commands/InertiaSsrCommand.js",
+    "./setup": "./dist/setup.js",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@arkstack/common": "^0.15.0"
+  },
+  "peerDependencies": {
+    "@h3ravel/musket": "^2.2.1",
+    "@arkstack/http": "^0.15.0",
+    "@arkstack/view": "^0.15.0",
+    "@arkstack/contract": "^0.15.0"
+  },
+  "peerDependenciesMeta": {
+    "@arkstack/view": {
+      "optional": true
+    },
+    "@h3ravel/musket": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest",
+    "version:patch": "pnpm version patch"
+  }
+}

package/stubs/config/inertia.ts.stub

@@ -0,0 +1,40 @@
+import type { InertiaConfig } from '@arkstack/inertia';
+import { env } from '@arkstack/common';
+
+/**
+ * Inertia adapter configuration.
+ *
+ * @see https://arkstack.toneflix.net/guide/inertia
+ */
+export default (): InertiaConfig => {
+  return {
+    /**
+     * The root Edge template that wraps the SPA. It renders the `{{{ inertia }}}`
+     * mount element and loads your client bundle (e.g. via Vite tags).
+     */
+    root_view: 'app',
+
+    /** The id of the DOM element the Inertia client mounts onto. */
+    root_id: 'app',
+
+    /**
+     * Asset version used for cache-busting. When the client's version differs on
+     * a GET visit, Inertia forces a full reload so stale assets are replaced.
+     * Return a string (e.g. a build hash) or `null` to disable versioning.
+     */
+    version: env('INERTIA_VERSION', null),
+
+    /**
+     * Server-side rendering. When enabled, the initial page is rendered by an
+     * external SSR server (your built SSR bundle) and the markup is embedded in
+     * the response; if that server is unreachable the adapter falls back to
+     * client-side rendering. `url` is the SSR server's render endpoint, and
+     * `bundle` is the built SSR entry run by `ark inertia:ssr`.
+     */
+    ssr: {
+      enabled: env('INERTIA_SSR', false),
+      url: env('INERTIA_SSR_URL', 'http://127.0.0.1:13714/render'),
+      bundle: 'dist-ssr/ssr.js',
+    },
+  };
+};

package/stubs/views/app.edge.stub

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    {{{ inertiaHead }}}
+    {{-- Replace with your Vite client + entry tags, e.g.: --}}
+    {{-- <script type="module" src="http://localhost:5173/@@vite/client"></script> --}}
+    {{-- <script type="module" src="http://localhost:5173/src/main.ts"></script> --}}
+</head>
+<body>
+    {{{ inertia }}}
+</body>
+</html>