@gravito/ion 3.0.1 → 4.0.0

package/dist/index.d.ts

@@ -1,201 +1,736 @@
 import { GravitoContext, GravitoVariables, GravitoOrbit, PlanetCore } from '@gravito/core';
 
 /**
- * @fileoverview Inertia.js Service for Gravito
+ * @fileoverview Type definitions for Inertia v2 protocol features.
  *
- * Provides server-side Inertia.js integration for building modern
- * single-page applications with server-side routing.
+ * This module provides type definitions for advanced Inertia features:
+ * - Deferred Props: Delay loading of specific props to initial render
+ * - Merge Props: Replace, prepend, or deep-merge props during partial reloads
+ * - History Encryption: Control browser history handling
+ * - Error Bags: Organize form validation errors by category
+ *
+ * @module @gravito/ion/types
+ */
+/**
+ * Marks a prop for deferred loading.
+ *
+ * Deferred props are not executed during the initial page render, but are listed
+ * in the `deferredProps` field of the Inertia page object. The client fetches them
+ * separately after the initial render is complete.
+ *
+ * @template T - Type of the deferred value (inferred from factory return type).
+ *
+ * @example
+ * ```typescript
+ * inertia.render('Dashboard', {
+ *   user: { id: 1, name: 'Carl' },
+ *   // Heavy computation deferred to later
+ *   slowStats: InertiaService.defer(() => calculateStats()),
+ *   // Grouped deferred props
+ *   notifications: InertiaService.defer(
+ *     () => fetchNotifications(),
+ *     'notifications-group'
+ *   )
+ * });
+ * ```
+ */
+interface DeferredPropDefinition<T = unknown> {
+    readonly _type: 'deferred';
+    readonly factory: () => T | Promise<T>;
+    readonly group?: string;
+}
+/**
+ * Marks a prop for merging rather than replacement.
+ *
+ * Used during partial reloads (X-Inertia-Partial-Data) to control how props
+ * are combined with existing data on the client:
+ * - `merge`: Shallow merge at top level
+ * - `prepend`: Add items to the beginning of an array
+ * - `deepMerge`: Recursive merge for nested objects
+ *
+ * @template T - Type of the prop value.
+ *
+ * @example
+ * ```typescript
+ * inertia.render('Products/List', {
+ *   // Deep merge filters with existing data
+ *   filters: InertiaService.deepMerge({ status: 'active', price: 100 }),
+ *   // Prepend new items to the beginning of the list
+ *   items: InertiaService.prepend([newProduct]),
+ *   // Shallow merge config with existing data
+ *   config: InertiaService.merge({ sortBy: 'name' })
+ * });
+ * ```
+ */
+interface MergedPropDefinition<T = unknown> {
+    readonly _type: 'merge' | 'prepend' | 'deepMerge';
+    readonly value: T;
+    readonly matchOn?: string | string[];
+}
+/**
+ * Configuration for error bags in form validation.
+ *
+ * Organizes form validation errors into named categories, allowing multiple
+ * validation failure scenarios to coexist (e.g., 'default' and 'import-csv').
+ *
+ * @example
+ * ```typescript
+ * inertia.withErrors({
+ *   email: 'Email is required',
+ *   password: 'Must be at least 8 characters'
+ * }, 'login');  // Bag name: 'login'
+ *
+ * inertia.withErrors({
+ *   line_1: 'Invalid CSV at row 1',
+ *   line_2: 'Invalid CSV at row 2'
+ * }, 'import');  // Bag name: 'import'
+ * ```
+ */
+interface ErrorBagDefinition {
+    readonly bag: string;
+    readonly errors: Record<string, string | string[]>;
+}
+/**
+ * Inertia page object structure for the initial render response.
+ *
+ * This is the JSON structure sent to the frontend containing component metadata
+ * and all resolved props. Extended with Inertia v2 features.
+ *
+ * @template P - Shape of the props object.
+ */
+interface InertiaPageObject<P extends Record<string, unknown> = Record<string, unknown>> {
+    /** Frontend component name (e.g., 'Pages/Dashboard') */
+    component: string;
+    /** Resolved and merged props for the component */
+    props: P;
+    /** Current URL without query string */
+    url: string;
+    /** Asset version (cache-busting identifier) */
+    version?: string;
+    /** Deferred prop groups and their factories (Inertia v2) */
+    deferredProps?: Record<string, string[]>;
+    /** Keys marked for merge/prepend/deepMerge (Inertia v2) */
+    mergeProps?: {
+        keys: string[];
+        mode: 'merge' | 'prepend' | 'deepMerge';
+    }[];
+    /** Whether to encrypt browser history (Inertia v2) */
+    encryptHistory?: boolean;
+    /** Whether to clear browser history (Inertia v2) */
+    clearHistory?: boolean;
+    /** Error bags organized by category (Inertia v2) */
+    errorBags?: Record<string, Record<string, string | string[]>>;
+}
+/**
+ * Inertia response metadata for partial reloads.
+ *
+ * Controls how the frontend should process the props update:
+ * - Handles reset scenarios (X-Inertia-Reset header)
+ * - Tracks which keys should be reset to undefined
+ */
+interface PartialReloadMetadata {
+    /** Keys to reset to undefined before merging new props */
+    resetKeys?: string[];
+    /** Merge strategy for the reload response */
+    mergeStrategy?: 'replace' | 'merge' | 'deepMerge';
+}
+
+/**
+ * @fileoverview Inertia.js Service for Gravito.
+ *
+ * This service implements the Inertia.js server-side protocol, enabling
+ * seamless page transitions and data synchronization for monolith SPAs.
  *
  * @module @gravito/ion
- * @since 1.0.0
  */
 
 /**
- * Configuration options for InertiaService
+ * Configuration options for the InertiaService instance.
+ *
+ * Defines how the service interacts with the root template, manages asset versioning,
+ * and handles Server-Side Rendering (SSR).
  */
 interface InertiaConfig {
     /**
-     * The root view template name
-     * @default 'app'
+     * The name of the root view template used for the initial page load.
+     *
+     * This template must contain the `{{{ page }}}` placeholder to inject the
+     * Inertia page object.
+     *
+     * @defaultValue 'app'
      */
     rootView?: string;
     /**
-     * Asset version for cache busting
+     * Asset version string or resolver.
+     *
+     * Used by Inertia to detect if the client-side assets are out of sync with the server.
+     * If the version sent by the client (X-Inertia-Version) doesn't match, the server
+     * triggers a full page reload via a 409 Conflict response.
      */
-    version?: string;
+    version?: string | (() => string | Promise<string>);
+    /**
+     * Minimum logging level for internal operations.
+     *
+     * @defaultValue 'info'
+     */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
+    /**
+     * Performance monitoring callback triggered after each render.
+     *
+     * Useful for tracking rendering latency and prop payload sizes in production.
+     */
+    onRender?: (metrics: RenderMetrics) => void;
+    /**
+     * SSR configuration options.
+     *
+     * Enables pre-rendering of components on the server to improve SEO and
+     * initial load performance.
+     */
+    ssr?: {
+        /** Whether SSR is enabled for the current environment. */
+        enabled: boolean;
+        /**
+         * Function to handle SSR rendering.
+         *
+         * Should interface with your frontend framework's SSR renderer (e.g., React's `renderToString`).
+         */
+        render?: (page: any) => Promise<{
+            head: string[];
+            body: string;
+        }>;
+    };
 }
 /**
- * InertiaService - Server-side Inertia.js adapter
+ * Encapsulates performance and status metrics for a single render operation.
  *
- * This service handles the Inertia.js protocol for seamless
- * SPA-like navigation with server-side routing.
+ * Provides insights into the rendering lifecycle, including component name,
+ * execution time, and payload complexity.
+ */
+interface RenderMetrics {
+    /** Name of the frontend component rendered. */
+    component: string;
+    /** Time taken in milliseconds for the entire render lifecycle. */
+    duration: number;
+    /** Indicates if the request was an Inertia AJAX request (true) or a full page load (false). */
+    isInertiaRequest: boolean;
+    /** Number of top-level props passed to the component after resolution. */
+    propsCount: number;
+    /** Epoch timestamp of when the operation completed. */
+    timestamp: number;
+    /** Resulting HTTP status code of the response. */
+    status?: number;
+}
+/**
+ * Server-side adapter for the Inertia.js protocol.
+ *
+ * The `InertiaService` is responsible for:
+ * 1. Resolving component props (including lazy/async props).
+ * 2. Handling partial reloads (filtering props based on `X-Inertia-Partial-Data`).
+ * 3. Managing asset versioning to ensure client-server synchronization.
+ * 4. Orchestrating SSR pre-rendering when enabled.
+ * 5. Generating the final HTTP response (JSON for AJAX, HTML for initial load).
  *
  * @example
  * ```typescript
- * // In a controller
- * async index(ctx: GravitoContext) {
- *   const inertia = ctx.get('inertia') as InertiaService
- *   return inertia.render('Home', { users: await User.all() })
- * }
+ * const inertia = new InertiaService(ctx, {
+ *   version: () => getGitHash(),
+ *   rootView: 'main'
+ * });
+ *
+ * // Share global data
+ * inertia.share('user', ctx.get('user'));
+ *
+ * // Render a component
+ * return await inertia.render('Dashboard/Index', {
+ *   stats: async () => await fetchStats() // Lazy prop
+ * });
  * ```
  */
 declare class InertiaService {
     private context;
     private config;
     private sharedProps;
+    private errorBags;
+    private encryptHistoryFlag;
+    private clearHistoryFlag;
+    private readonly logLevel;
+    private readonly onRenderCallback?;
+    /**
+     * Creates a deferred prop that will be loaded after the initial render.
+     *
+     * @param factory - Function that resolves to the prop value.
+     * @param group - Optional group name for organizing deferred props.
+     * @returns A deferred prop definition.
+     *
+     * @example
+     * ```typescript
+     * props: {
+     *   user: { id: 1 },
+     *   stats: InertiaService.defer(() => fetchStats())
+     * }
+     * ```
+     */
+    static defer<T = unknown>(factory: () => T | Promise<T>, group?: string): DeferredPropDefinition<T>;
+    /**
+     * Marks a prop to be merged (shallow) with existing data during partial reloads.
+     *
+     * @param value - The prop value to merge.
+     * @param matchOn - Optional key(s) to match on when merging arrays.
+     * @returns A merge prop definition.
+     */
+    static merge<T = unknown>(value: T, matchOn?: string | string[]): MergedPropDefinition<T>;
+    /**
+     * Marks a prop to prepend to an array during partial reloads.
+     *
+     * @param value - The prop value to prepend.
+     * @returns A prepend prop definition.
+     */
+    static prepend<T = unknown>(value: T): MergedPropDefinition<T>;
+    /**
+     * Marks a prop to be deep-merged with existing data during partial reloads.
+     *
+     * @param value - The prop value to deep merge.
+     * @returns A deep merge prop definition.
+     */
+    static deepMerge<T = unknown>(value: T): MergedPropDefinition<T>;
     /**
-     * Create a new InertiaService instance
+     * Initializes a new instance of the Inertia service.
      *
-     * @param context - The Gravito request context
-     * @param config - Optional configuration
+     * @param context - The current Gravito request context.
+     * @param config - Instance configuration options.
      */
     constructor(context: GravitoContext<GravitoVariables>, config?: InertiaConfig);
     /**
-     * Escape a string for safe use in HTML attributes
+     * Internal logging helper that respects the configured log level.
      *
-     * Strategy: JSON.stringify already escapes special characters including
-     * quotes as \". We need to escape these for HTML attributes, but we must
-     * be careful not to break JSON escape sequences.
+     * Routes logs to the Gravito context logger if available.
      *
-     * The solution: Escape backslash-quote sequences (\" from JSON.stringify)
-     * as \\&quot; so they become \\&quot; in HTML, which the browser decodes
-     * to \\" (valid JSON), not \&quot; (invalid JSON).
+     * @param level - Log severity level.
+     * @param message - Descriptive message.
+     * @param data - Optional metadata for the log.
+     */
+    private log;
+    /**
+     * Escapes a string for safe embedding into a single-quoted HTML attribute.
      *
-     * @param value - The string to escape.
-     * @returns The escaped string.
+     * This ensures that JSON strings can be safely passed to the frontend
+     * via the `data-page` attribute without breaking the HTML structure or
+     * introducing XSS vulnerabilities.
+     *
+     * @param value - Raw JSON or text string.
+     * @returns Safely escaped HTML attribute value.
      */
     private escapeForSingleQuotedHtmlAttribute;
     /**
-     * Render an Inertia component
+     * Renders an Inertia component and returns the appropriate HTTP response.
+     *
+     * This method handles the entire Inertia lifecycle:
+     * - Detects if the request is an Inertia AJAX request.
+     * - Validates asset versions.
+     * - Resolves props (executes functions, handles partial reloads).
+     * - Performs SSR if configured.
+     * - Wraps the result in a JSON response or the root HTML template.
+     *
+     * @param component - Frontend component name (e.g., 'Users/Profile').
+     * @param props - Data passed to the component. Can include functions for lazy evaluation.
+     * @param rootVars - Variables passed to the root HTML template (only used on initial load).
+     * @param status - Optional HTTP status code.
+     * @returns A promise that resolves to a Gravito HTTP Response.
      *
-     * @param component - The component name to render
-     * @param props - Props to pass to the component
-     * @param rootVars - Additional variables for the root template
-     * @returns HTTP Response
+     * @throws {@link InertiaError}
+     * Thrown if:
+     * - The `ViewService` is missing from the context (required for initial load).
+     * - Prop serialization fails due to circular references or non-serializable data.
      *
      * @example
      * ```typescript
-     * return inertia.render('Users/Index', {
-     *   users: await User.all(),
-     *   filters: { search: ctx.req.query('search') }
-     * })
+     * // Standard render
+     * return await inertia.render('Welcome', { name: 'Guest' });
+     *
+     * // Partial reload support (only 'stats' will be resolved if requested)
+     * return await inertia.render('Dashboard', {
+     *   user: auth.user,
+     *   stats: () => db.getStats()
+     * });
      * ```
      */
-    render(component: string, props?: Record<string, unknown>, rootVars?: Record<string, unknown>): Response;
+    render<T extends Record<string, unknown> = Record<string, unknown>>(component: string, props?: T, rootVars?: Record<string, unknown>, status?: number): Promise<Response>;
     /**
-     * Share data with all Inertia responses
+     * Registers a piece of data to be shared with all Inertia responses for the current request.
      *
-     * Shared props are merged with component-specific props on every render.
+     * Shared props are automatically merged with component-specific props during the render phase.
+     * This is the primary mechanism for providing global state like authentication details,
+     * flash messages, or configuration to the frontend.
      *
-     * @param key - The prop key
-     * @param value - The prop value
+     * @param key - Identifier for the shared prop.
+     * @param value - Value to share. Must be JSON serializable.
      *
      * @example
      * ```typescript
-     * // In middleware
-     * inertia.share('auth', { user: ctx.get('auth')?.user() })
-     * inertia.share('flash', ctx.get('session')?.getFlash('message'))
+     * inertia.share('appName', 'Gravito Store');
+     * inertia.share('auth', { user: ctx.get('user') });
      * ```
      */
     share(key: string, value: unknown): void;
     /**
-     * Share multiple props at once
+     * Shares multiple props in a single operation.
+     *
+     * Merges the provided object into the existing shared props state. Existing keys
+     * with the same name will be overwritten.
+     *
+     * @param props - Object containing key-value pairs to merge into the shared state.
      *
-     * @param props - Object of props to share
+     * @example
+     * ```typescript
+     * inertia.shareAll({
+     *   version: '1.2.0',
+     *   environment: 'production',
+     *   features: ['chat', 'search']
+     * });
+     * ```
      */
     shareAll(props: Record<string, unknown>): void;
     /**
-     * Get all shared props
+     * Returns a shallow copy of the current shared props.
      *
-     * @returns A shallow copy of the shared props object.
+     * Useful for inspecting the shared state or for manual prop merging in advanced scenarios.
+     *
+     * @returns A dictionary containing all currently registered shared props.
+     *
+     * @example
+     * ```typescript
+     * const shared = inertia.getSharedProps();
+     * if (!shared.auth) {
+     *   console.warn('Authentication data is missing from shared props');
+     * }
+     * ```
      */
     getSharedProps(): Record<string, unknown>;
+    /**
+     * Instructs the Inertia client to navigate to a different URL.
+     *
+     * For Inertia AJAX requests, this returns a 409 Conflict with the `X-Inertia-Location` header.
+     * For regular page loads, this returns a 302 Found redirect.
+     *
+     * This is useful for server-side redirects triggered by authentication or authorization checks.
+     *
+     * @param url - The URL to redirect to.
+     * @returns A redirect response.
+     *
+     * @example
+     * ```typescript
+     * if (!ctx.get('user')) {
+     *   return inertia.location('/login');
+     * }
+     * ```
+     */
+    location(url: string): Response;
+    /**
+     * Controls whether the Inertia client should encrypt browser history.
+     *
+     * When enabled, history is not written to the browser's History API,
+     * preventing users from using the browser back button to return to previous pages.
+     *
+     * @param encrypt - Whether to encrypt history (defaults to true).
+     * @returns The service instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * return await inertia.encryptHistory(true).render('SecurePage');
+     * ```
+     */
+    encryptHistory(encrypt?: boolean): this;
+    /**
+     * Clears the browser history after the page load.
+     *
+     * Useful for sensitive operations or multi-step wizards where you don't want
+     * users navigating back to previous states.
+     *
+     * @returns The service instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * return await inertia.clearHistory().render('SuccessPage');
+     * ```
+     */
+    clearHistory(): this;
+    /**
+     * Registers form validation errors organized into named bags.
+     *
+     * Error bags allow multiple validation failure scenarios to coexist.
+     * For example, you might have 'default' errors and 'import' errors from different forms.
+     *
+     * @param errors - Validation errors, with field names as keys and error messages as values.
+     * @param bag - The error bag name (defaults to 'default').
+     * @returns The service instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * inertia.withErrors({
+     *   email: 'Email is required',
+     *   password: 'Must be 8+ characters'
+     * }, 'login');
+     *
+     * inertia.withErrors({
+     *   line_1: 'Invalid CSV format'
+     * }, 'import');
+     * ```
+     */
+    withErrors(errors: Record<string, string | string[]>, bag?: string): this;
 }
 
 /**
- * @fileoverview Orbit Inertia - Inertia.js integration for Gravito
+ * Base error class for all Inertia-related operations in Gravito.
+ */
+declare class InertiaError extends Error {
+    readonly code: string;
+    readonly httpStatus: number;
+    readonly details?: Record<string, any> | undefined;
+    constructor(code: string, httpStatus?: number, details?: Record<string, any> | undefined);
+    toJSON(): {
+        name: string;
+        code: string;
+        httpStatus: number;
+        message: string;
+        details: Record<string, any> | undefined;
+    };
+}
+/**
+ * Configuration errors - e.g., missing services.
+ */
+declare class InertiaConfigError extends InertiaError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Data/Serialization errors - e.g., circular references or resolution failure.
+ */
+declare class InertiaDataError extends InertiaError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Template/Rendering errors.
+ */
+declare class InertiaTemplateError extends InertiaError {
+    constructor(message: string, details?: Record<string, any>);
+}
+
+/**
+ * @fileoverview Orbit Inertia - Inertia.js integration for Gravito.
  *
- * Provides server-side Inertia.js integration for building modern
- * single-page applications with server-side routing.
+ * This module provides the core Orbit definition and helper interfaces for
+ * building modern single-page applications using server-side routing.
  *
  * @module @gravito/ion
- * @since 1.0.0
  */
 
 /**
- * InertiaHelper is a callable function and service suite injected into the Gravito context.
- * It allows you to render Inertia components directly or manage shared data.
+ * Enhanced helper interface for Inertia operations within the Gravito context.
+ *
+ * This interface is both a callable function for quick rendering and a
+ * service container for managing shared data and accessing the underlying service.
+ * It is typically accessed via `ctx.get('inertia')`.
  *
  * @example
  * ```typescript
- * // Direct call rendering
- * return ctx.get('inertia')('Welcome', { user });
+ * // 1. Direct rendering (Callable)
+ * export const index = async (ctx: Context) => {
+ *   return await ctx.get('inertia')('Home', { title: 'Welcome' });
+ * };
+ *
+ * // 2. Sharing global data
+ * ctx.get('inertia').share('app_name', 'My Project');
  *
- * // Using shared data
- * ctx.get('inertia').share('appName', 'Gravito App');
+ * // 3. Accessing the underlying service
+ * const service = ctx.get('inertia').service;
  * ```
- * @public
  */
 interface InertiaHelper {
     /**
-     * Render an Inertia component.
-     * Shortcut for context.get('inertia').render()
+     * Renders an Inertia component.
+     *
+     * This is a shortcut for calling `render()` on the underlying service.
+     *
+     * @param component - Frontend component name (e.g., 'Pages/Dashboard').
+     * @param props - Data object passed to the component. Supports lazy/async props.
+     * @param rootVars - Variables passed to the root HTML template (initial load only).
+     * @param status - Optional HTTP status code (defaults to 200).
+     * @returns A promise resolving to a Gravito-compatible HTTP Response.
+     *
+     * @throws {@link InertiaError}
+     * Thrown if serialization fails or the ViewService is missing during initial load.
+     */
+    <T extends Record<string, unknown> = Record<string, unknown>>(component: string, props?: T, rootVars?: Record<string, unknown>, status?: number): Promise<Response>;
+    /**
+     * Shares a single piece of data with all subsequent Inertia responses for this request.
      *
-     * @param component - The name of the frontend component (e.g., 'Pages/Home')
-     * @param props - Data to pass to the component
-     * @param rootVars - Variables for the root HTML template (e.g., meta tags)
+     * @param key - Unique identifier for the shared prop.
+     * @param value - Data value. Must be JSON serializable.
      */
-    (component: string, props?: Record<string, unknown>, rootVars?: Record<string, unknown>): Response;
-    /** Share data with all Inertia responses for the remainder of the request */
     share(key: string, value: unknown): void;
-    /** Share multiple props at once */
+    /**
+     * Shares multiple props simultaneously by merging them into the shared state.
+     *
+     * @param props - Key-value pairs to merge into shared props.
+     */
     shareAll(props: Record<string, unknown>): void;
-    /** Get all currently shared props */
+    /**
+     * Retrieves a copy of all currently shared props for the current request.
+     *
+     * @returns Current shared props dictionary.
+     */
     getSharedProps(): Record<string, unknown>;
-    /** Explicitly render an Inertia component */
-    render(component: string, props?: Record<string, unknown>, rootVars?: Record<string, unknown>): Response;
-    /** Direct access to the low-level Inertia service instance */
+    /**
+     * Explicitly renders an Inertia component.
+     *
+     * Identical to the callable interface but provided for semantic clarity.
+     *
+     * @param component - Frontend component name.
+     * @param props - Component data.
+     * @param rootVars - Template variables.
+     * @param status - HTTP status code.
+     * @returns A promise resolving to an HTTP Response.
+     *
+     * @throws {@link InertiaError}
+     * Thrown if the rendering lifecycle encounters a fatal error.
+     */
+    render<T extends Record<string, unknown> = Record<string, unknown>>(component: string, props?: T, rootVars?: Record<string, unknown>, status?: number): Promise<Response>;
+    /**
+     * Instructs the client to navigate to a different URL.
+     *
+     * @param url - The URL to navigate to.
+     * @returns A redirect response.
+     */
+    location(url: string): Response;
+    /**
+     * Encrypts the browser history to prevent navigation via back button.
+     *
+     * @param encrypt - Whether to enable history encryption (defaults to true).
+     * @returns The helper for method chaining.
+     */
+    encryptHistory(encrypt?: boolean): InertiaHelper;
+    /**
+     * Clears the browser history after page load.
+     *
+     * @returns The helper for method chaining.
+     */
+    clearHistory(): InertiaHelper;
+    /**
+     * Registers form validation errors organized by bag name.
+     *
+     * @param errors - Error map with field names as keys.
+     * @param bag - The error bag name (defaults to 'default').
+     * @returns The helper for method chaining.
+     */
+    withErrors(errors: Record<string, string | string[]>, bag?: string): InertiaHelper;
+    /**
+     * Direct access to the low-level `InertiaService` instance.
+     *
+     * Use this for advanced operations not exposed by the helper interface.
+     */
     service: InertiaService;
 }
 /**
- * Options for configuring OrbitIon.
- * @public
+ * Configuration options for the OrbitIon extension.
+ *
+ * Controls how the Inertia protocol is integrated into the Gravito ecosystem.
  */
 interface OrbitIonOptions {
-    /** Current asset version to detect staleness (X-Inertia-Version) */
-    version?: string;
-    /** The root HTML template view (default: 'app') */
+    /**
+     * Asset version string or resolver used for cache busting.
+     *
+     * If not provided, it defaults to the `APP_VERSION` defined in the core configuration.
+     *
+     * @defaultValue '1.0.0'
+     */
+    version?: string | (() => string | Promise<string>);
+    /**
+     * The name of the root HTML template file (without extension).
+     *
+     * This template is used for the initial page load.
+     *
+     * @defaultValue 'app'
+     */
     rootView?: string;
+    /**
+     * SSR configuration options.
+     *
+     * Enables server-side pre-rendering of components.
+     */
+    ssr?: {
+        /** Whether SSR is enabled for this application. */
+        enabled: boolean;
+        /**
+         * Function to handle SSR rendering.
+         *
+         * Receives the Inertia page object and should return the rendered HTML.
+         */
+        render?: (page: any) => Promise<{
+            head: string[];
+            body: string;
+        }>;
+    };
+    /**
+     * CSRF protection configuration.
+     *
+     * Automatically sets the XSRF-TOKEN cookie for CSRF protection.
+     *
+     * @defaultValue { enabled: true, cookieName: 'XSRF-TOKEN' }
+     */
+    csrf?: {
+        /** Whether CSRF protection is enabled. */
+        enabled?: boolean;
+        /** Name of the CSRF token cookie (commonly read by Axios). */
+        cookieName?: string;
+    };
 }
 /**
  * OrbitIon provides official Inertia.js integration for Gravito.
  *
- * It handles Inertia requests, partial reloads, asset versioning, and seamless
- * data sharing between the server and your frontend application (React, Vue, etc.).
- *
- * It injects an `InertiaHelper` into the context, allowing you to render
- * components with a simple function call: `c.get('inertia')('Page', { props })`.
+ * As an infrastructure extension (Orbit), it:
+ * 1. Registers a global middleware to handle the Inertia protocol.
+ * 2. Manages asset version synchronization (X-Inertia-Version).
+ * 3. Injects the `InertiaHelper` into the request context for easy access in controllers.
+ * 4. Supports partial reloads and SSR out of the box.
  *
  * @example
  * ```typescript
  * import { OrbitIon } from '@gravito/ion';
  *
+ * // In your application bootstrap
  * core.addOrbit(new OrbitIon({
- *   version: '1.0.0',
- *   rootView: 'app'
+ *   version: 'v2.1.0',
+ *   rootView: 'layouts/app',
+ *   ssr: {
+ *     enabled: process.env.SSR === 'true',
+ *     render: async (page) => await mySsrRenderer(page)
+ *   }
  * }));
  * ```
- *
- * @public
- * @since 3.0.0
  */
 declare class OrbitIon implements GravitoOrbit {
     private options;
+    /**
+     * Initializes the Orbit with custom configuration.
+     *
+     * @param options - Configuration overrides for the Inertia service.
+     */
     constructor(options?: OrbitIonOptions);
     /**
-     * Install the inertia orbit into PlanetCore
+     * Registers the Inertia middleware and service factory into PlanetCore.
+     *
+     * This method is called automatically by Gravito during the boot process.
+     * It sets up the `InertiaService` for each request and attaches
+     * the `InertiaHelper` proxy to the context.
+     *
+     * @param core - The Gravito micro-kernel instance.
+     *
+     * @example
+     * ```typescript
+     * const ion = new OrbitIon({ version: '1.0' });
+     * ion.install(core);
+     * ```
      */
     install(core: PlanetCore): void;
 }
 
-export { type InertiaConfig, type InertiaHelper, InertiaService, OrbitIon, type OrbitIonOptions, OrbitIon as default };
+export { type DeferredPropDefinition, type ErrorBagDefinition, type InertiaConfig, InertiaConfigError, InertiaDataError, InertiaError, type InertiaHelper, type InertiaPageObject, InertiaService, InertiaTemplateError, type MergedPropDefinition, OrbitIon, type OrbitIonOptions, type PartialReloadMetadata, type RenderMetrics, OrbitIon as default };