litestar-vite 0.15.0__py3-none-any.whl → 0.15.0rc2__py3-none-any.whl

litestar_vite/{config/__init__.py → config.py}

@@ -26,28 +26,13 @@ Example usage::
 import logging
 import os
 from dataclasses import dataclass, field, replace
+from importlib.util import find_spec
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal, Protocol, cast, runtime_checkable
 
 from litestar.exceptions import SerializationException
 from litestar.serialization import decode_json
 
-from litestar_vite.config._constants import (  # pyright: ignore[reportPrivateUsage]
-    FSSPEC_INSTALLED,
-    JINJA_INSTALLED,
-    TRUE_VALUES,
-)
-from litestar_vite.config._deploy import DeployConfig  # pyright: ignore[reportPrivateUsage]
-from litestar_vite.config._inertia import (  # pyright: ignore[reportPrivateUsage]
-    InertiaConfig,
-    InertiaSSRConfig,
-    InertiaTypeGenConfig,
-)
-from litestar_vite.config._paths import PathConfig  # pyright: ignore[reportPrivateUsage]
-from litestar_vite.config._runtime import ExternalDevServer, RuntimeConfig  # pyright: ignore[reportPrivateUsage]
-from litestar_vite.config._spa import LoggingConfig, SPAConfig  # pyright: ignore[reportPrivateUsage]
-from litestar_vite.config._types import TypeGenConfig  # pyright: ignore[reportPrivateUsage]
-
 logger = logging.getLogger("litestar_vite")
 
 if TYPE_CHECKING:
@@ -100,6 +85,657 @@ class PaginationContainer(Protocol):
     items: "Sequence[Any]"
 
 
+TRUE_VALUES = {"True", "true", "1", "yes", "Y", "T"}
+JINJA_INSTALLED = bool(find_spec("jinja2"))
+FSSPEC_INSTALLED = bool(find_spec("fsspec"))
+
+
+def _empty_dict_factory() -> dict[str, Any]:
+    """Return an empty ``dict[str, Any]``.
+
+    Returns:
+        An empty dictionary.
+    """
+    return {}
+
+
+def _empty_set_factory() -> set[str]:
+    """Return an empty ``set[str]``.
+
+    Returns:
+        An empty set.
+    """
+    return set()
+
+
+def _default_content_types() -> dict[str, str]:
+    """Default content-type mappings keyed by file extension.
+
+    Returns:
+        Dictionary mapping file extensions to MIME types.
+    """
+    return {
+        ".js": "application/javascript",
+        ".mjs": "application/javascript",
+        ".cjs": "application/javascript",
+        ".css": "text/css",
+        ".html": "text/html",
+        ".json": "application/json",
+        ".svg": "image/svg+xml",
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".webp": "image/webp",
+        ".woff2": "font/woff2",
+        ".woff": "font/woff",
+    }
+
+
+def _default_storage_options() -> dict[str, Any]:
+    """Return an empty storage options dictionary.
+
+    Returns:
+        An empty dictionary.
+    """
+    return {}
+
+
+@dataclass
+class DeployConfig:
+    """CDN deployment configuration.
+
+    Attributes:
+        enabled: Enable deployment features.
+        storage_backend: fsspec URL for the target location (e.g., ``gcs://bucket/path``).
+        storage_options: Provider options forwarded to ``fsspec`` (credentials, region, etc.).
+        delete_orphaned: Remove remote files not present in the local bundle.
+        include_manifest: Upload ``manifest.json`` alongside assets.
+        content_types: Optional content-type overrides keyed by file extension.
+    """
+
+    enabled: bool = False
+    storage_backend: "str | None" = field(default_factory=lambda: os.getenv("VITE_DEPLOY_STORAGE"))
+    storage_options: dict[str, Any] = field(default_factory=_default_storage_options)
+    delete_orphaned: bool = field(default_factory=lambda: os.getenv("VITE_DEPLOY_DELETE", "true") in TRUE_VALUES)
+    include_manifest: bool = True
+    content_types: dict[str, str] = field(default_factory=_default_content_types)
+
+    def __post_init__(self) -> None:
+        """Apply environment fallbacks."""
+        if self.storage_backend is None:
+            self.storage_backend = os.getenv("VITE_DEPLOY_STORAGE")
+
+    def with_overrides(
+        self,
+        storage_backend: "str | None" = None,
+        storage_options: "dict[str, Any] | None" = None,
+        delete_orphaned: "bool | None" = None,
+    ) -> "DeployConfig":
+        """Return a copy with overrides applied.
+
+        Args:
+            storage_backend: Override for the storage URL.
+            storage_options: Override for backend options.
+            delete_orphaned: Override deletion behaviour.
+
+        Returns:
+            DeployConfig copy with updated fields.
+        """
+        return replace(
+            self,
+            storage_backend=storage_backend or self.storage_backend,
+            storage_options=storage_options or self.storage_options,
+            delete_orphaned=self.delete_orphaned if delete_orphaned is None else delete_orphaned,
+        )
+
+
+@dataclass
+class InertiaSSRConfig:
+    """Server-side rendering settings for Inertia.js.
+
+    Inertia SSR runs a separate Node server that renders the initial HTML for an
+    Inertia page object. Litestar sends the page payload to the SSR server (by
+    default at ``http://127.0.0.1:13714/render``) and injects the returned head
+    tags and body markup into the HTML response.
+
+    Notes:
+        - This is *not* Litestar-Vite's ``mode="ssr"`` (Astro/Nuxt/SvelteKit proxy mode).
+        - When enabled, failures to contact the SSR server are treated as errors (no silent fallback).
+    """
+
+    enabled: bool = True
+    url: str = "http://127.0.0.1:13714/render"
+    timeout: float = 2.0
+
+
+@dataclass
+class InertiaConfig:
+    """Configuration for InertiaJS support.
+
+    This is the canonical configuration class for Inertia.js integration.
+    Presence of an InertiaConfig instance indicates Inertia is enabled.
+
+    Note:
+        SPA mode (HTML transformation vs Jinja2 templates) is controlled by
+        ViteConfig.mode='hybrid'. The app_selector for data-page injection
+        is configured via SPAConfig.app_selector.
+
+    Attributes:
+        root_template: Name of the root template to use.
+        component_opt_keys: Identifiers for getting inertia component from route opts.
+        redirect_unauthorized_to: Path for unauthorized request redirects.
+        redirect_404: Path for 404 request redirects.
+        extra_static_page_props: Static props added to every page response.
+        extra_session_page_props: Session keys to include in page props.
+    """
+
+    root_template: str = "index.html"
+    """Name of the root template to use.
+
+    This must be a path that is found by the Vite Plugin template config
+    """
+    component_opt_keys: "tuple[str, ...]" = ("component", "page")
+    """Identifiers to use on routes to get the inertia component to render.
+
+    The first key found in the route handler opts will be used. This allows
+    semantic flexibility - use "component" or "page" depending on preference.
+
+    Example:
+        # All equivalent:
+        @get("/", component="Home")
+        @get("/", page="Home")
+
+        # Custom keys:
+        InertiaConfig(component_opt_keys=("view", "component", "page"))
+    """
+    redirect_unauthorized_to: "str | None" = None
+    """Optionally supply a path where unauthorized requests should redirect."""
+    redirect_404: "str | None" = None
+    """Optionally supply a path where 404 requests should redirect."""
+    extra_static_page_props: "dict[str, Any]" = field(default_factory=_empty_dict_factory)
+    """A dictionary of values to automatically add in to page props on every response."""
+    extra_session_page_props: "set[str]" = field(default_factory=_empty_set_factory)
+    """A set of session keys for which the value automatically be added (if it exists) to the response."""
+    encrypt_history: bool = False
+    """Enable browser history encryption globally (v2 feature).
+
+    When True, all Inertia responses will include `encryptHistory: true`
+    in the page object. The Inertia client will encrypt history state
+    using browser's crypto API before pushing to history.
+
+    This prevents sensitive data from being visible in browser history
+    after a user logs out. Individual responses can override this setting.
+
+    Note: Encryption happens client-side; requires HTTPS in production.
+    See: https://inertiajs.com/history-encryption
+    """
+    type_gen: "InertiaTypeGenConfig | None" = None
+    """Type generation options for Inertia page props.
+
+    Controls default types in generated page-props.ts. Set to InertiaTypeGenConfig()
+    or leave as None for defaults. Use InertiaTypeGenConfig(include_default_auth=False)
+    to disable default User/AuthData interfaces for non-standard user models.
+    """
+
+    ssr: "InertiaSSRConfig | bool | None" = None
+    """Enable server-side rendering (SSR) for Inertia responses.
+
+    When enabled, full-page HTML responses will be pre-rendered by a Node SSR server
+    and injected into the SPA HTML before returning to the client.
+
+    Supports:
+        - True: enable with defaults -> ``InertiaSSRConfig()``
+        - False/None: disabled -> ``None``
+        - InertiaSSRConfig: use as-is
+    """
+
+    def __post_init__(self) -> None:
+        """Normalize optional sub-configs."""
+        if self.ssr is True:
+            self.ssr = InertiaSSRConfig()
+        elif self.ssr is False:
+            self.ssr = None
+
+    @property
+    def ssr_config(self) -> "InertiaSSRConfig | None":
+        """Return the SSR config when enabled, otherwise None.
+
+        Returns:
+            The resolved SSR config when enabled, otherwise None.
+        """
+        if isinstance(self.ssr, InertiaSSRConfig) and self.ssr.enabled:
+            return self.ssr
+        return None
+
+
+@dataclass
+class InertiaTypeGenConfig:
+    """Type generation options for Inertia page props.
+
+    Controls which default types are included in the generated page-props.ts file.
+    This follows Laravel Jetstream patterns - sensible defaults for common auth patterns.
+
+    Attributes:
+        include_default_auth: Include default User and AuthData interfaces.
+            Default User has: id, email, name. Users extend via module augmentation.
+            Set to False if your User model doesn't have these fields (uses uuid, username, etc.)
+        include_default_flash: Include default FlashMessages interface.
+            Uses { [category: string]: string[] } pattern for flash messages.
+
+    Example:
+        Standard auth (95% of users) - just extend defaults::
+
+            # Python: use defaults
+            ViteConfig(inertia=InertiaConfig())
+
+            # TypeScript: extend User interface
+            declare module 'litestar-vite-plugin/inertia' {
+                interface User {
+                    avatarUrl?: string
+                    roles: Role[]
+                }
+            }
+
+        Custom auth (5% of users) - define from scratch::
+
+            # Python: disable defaults
+            ViteConfig(inertia=InertiaConfig(
+                type_gen=InertiaTypeGenConfig(include_default_auth=False)
+            ))
+
+            # TypeScript: define your custom User
+            declare module 'litestar-vite-plugin/inertia' {
+                interface User {
+                    uuid: string  // No id!
+                    username: string  // No email!
+                }
+            }
+    """
+
+    include_default_auth: bool = True
+    """Include default User and AuthData interfaces.
+
+    When True, generates:
+    - User: { id: string, email: string, name?: string | null }
+    - AuthData: { isAuthenticated: boolean, user?: User }
+
+    Users extend via TypeScript module augmentation.
+    Set to False if your User model has different required fields.
+    """
+
+    include_default_flash: bool = True
+    """Include default FlashMessages interface.
+
+    When True, generates:
+    - FlashMessages: { [category: string]: string[] }
+
+    Standard flash message pattern used by most web frameworks.
+    """
+
+
+def _resolve_proxy_mode() -> "Literal['vite', 'direct', 'proxy'] | None":
+    """Resolve proxy_mode from environment variable.
+
+    Reads VITE_PROXY_MODE env var. Valid values:
+    - "vite" (default): Proxy to internal Vite server (allow list - assets only)
+    - "direct": Expose Vite port directly (no proxy)
+    - "proxy": Proxy everything except Litestar routes (deny list)
+    - "none": Disable proxy (for production)
+
+    Raises:
+        ValueError: If an invalid value is provided.
+
+    Returns:
+        The resolved proxy mode, or None if disabled.
+    """
+    env_value = os.getenv("VITE_PROXY_MODE")
+    match env_value.strip().lower() if env_value is not None else None:
+        case None:
+            return "vite"
+        case "none":
+            return None
+        case "direct":
+            return "direct"
+        case "proxy":
+            return "proxy"
+        case "vite":
+            return "vite"
+        case _:
+            msg = f"Invalid VITE_PROXY_MODE: {env_value!r}. Expected one of: vite, direct, proxy, none"
+            raise ValueError(msg)
+
+
+@dataclass
+class PathConfig:
+    """File system paths configuration.
+
+    Attributes:
+        root: The root directory of the project. Defaults to current working directory.
+        bundle_dir: Location of compiled assets and manifest.json.
+        resource_dir: TypeScript/JavaScript source directory (equivalent to ./src in Vue/React).
+        static_dir: Static public assets directory (served as-is by Vite).
+        manifest_name: Name of the Vite manifest file.
+        hot_file: Name of the hot file indicating dev server URL.
+        asset_url: Base URL for static asset references (prepended to Vite output).
+        ssr_output_dir: SSR output directory (optional).
+    """
+
+    root: "str | Path" = field(default_factory=Path.cwd)
+    bundle_dir: "str | Path" = field(default_factory=lambda: Path("public"))
+    resource_dir: "str | Path" = field(default_factory=lambda: Path("src"))
+    static_dir: "str | Path" = field(default_factory=lambda: Path("public"))
+    manifest_name: str = "manifest.json"
+    hot_file: str = "hot"
+    asset_url: str = field(default_factory=lambda: os.getenv("ASSET_URL", "/static/"))
+    ssr_output_dir: "str | Path | None" = None
+
+    def __post_init__(self) -> None:
+        """Normalize path types to Path objects.
+
+        This also adjusts defaults to prevent Vite's ``publicDir`` (input) from
+        colliding with ``outDir`` (output). ``bundle_dir`` is treated as the build
+        output directory. When ``static_dir`` equals ``bundle_dir``, Vite may warn
+        and effectively disable public asset copying, so ``static_dir`` defaults to
+        ``<resource_dir>/public`` in that case.
+        """
+        if isinstance(self.root, str):
+            object.__setattr__(self, "root", Path(self.root))
+        if isinstance(self.bundle_dir, str):
+            object.__setattr__(self, "bundle_dir", Path(self.bundle_dir))
+        if isinstance(self.resource_dir, str):
+            object.__setattr__(self, "resource_dir", Path(self.resource_dir))
+        if isinstance(self.static_dir, str):
+            object.__setattr__(self, "static_dir", Path(self.static_dir))
+        if isinstance(self.ssr_output_dir, str):
+            object.__setattr__(self, "ssr_output_dir", Path(self.ssr_output_dir))
+
+        if (
+            isinstance(self.bundle_dir, Path)
+            and isinstance(self.static_dir, Path)
+            and self.static_dir == self.bundle_dir
+        ):
+            object.__setattr__(self, "static_dir", Path(self.resource_dir) / "public")
+
+
+@dataclass
+class ExternalDevServer:
+    """Configuration for external (non-Vite) dev servers.
+
+    Use this when your frontend uses a framework with its own dev server
+    (Angular CLI, Next.js, Create React App, etc.) instead of Vite.
+
+    For SSR frameworks (Astro, Nuxt, SvelteKit) using Vite internally, leave
+    target as None - the proxy will read the dynamic port from the hotfile.
+
+    Attributes:
+        target: The URL of the external dev server (e.g., "http://localhost:4200").
+            If None, the proxy reads the target URL from the Vite hotfile.
+        command: Custom command to start the dev server (e.g., ["ng", "serve"]).
+            If None and start_dev_server=True, uses executor's default start command.
+        build_command: Custom command to build for production (e.g., ["ng", "build"]).
+            If None, uses executor's default build command (e.g., "npm run build").
+        http2: Enable HTTP/2 for proxy connections.
+        enabled: Whether the external proxy is enabled.
+    """
+
+    target: "str | None" = None
+    command: "list[str] | None" = None
+    build_command: "list[str] | None" = None
+    http2: bool = False
+    enabled: bool = True
+
+
+@dataclass
+class RuntimeConfig:
+    """Runtime execution settings.
+
+    Attributes:
+        dev_mode: Enable development mode with HMR/watch.
+        proxy_mode: Proxy handling mode:
+            - "vite" (default): Proxy Vite assets only (allow list - SPA mode)
+            - "direct": Expose Vite port directly (no proxy)
+            - "proxy": Proxy everything except Litestar routes (deny list - SSR mode)
+            - None: No proxy (production mode)
+        external_dev_server: Configuration for external dev server (used with proxy_mode="proxy").
+        host: Vite dev server host.
+        port: Vite dev server port.
+        protocol: Protocol for dev server (http/https).
+        executor: JavaScript runtime executor (node, bun, deno).
+        run_command: Custom command to run Vite dev server (auto-detect if None).
+        build_command: Custom command to build with Vite (auto-detect if None).
+        build_watch_command: Custom command for watch mode build.
+        serve_command: Custom command to run production server (for SSR frameworks).
+        install_command: Custom command to install dependencies.
+        is_react: Enable React Fast Refresh support.
+        ssr_enabled: Enable Server-Side Rendering.
+        health_check: Enable health check for dev server startup.
+        detect_nodeenv: Detect and use nodeenv in virtualenv (opt-in).
+        set_environment: Set Vite environment variables from config.
+        set_static_folders: Automatically configure static file serving.
+        csp_nonce: Content Security Policy nonce for inline scripts.
+        spa_handler: Auto-register catch-all SPA route when mode="spa".
+        http2: Enable HTTP/2 for proxy HTTP requests (better multiplexing).
+            WebSocket traffic (HMR) uses a separate connection and is unaffected.
+    """
+
+    dev_mode: bool = field(default_factory=lambda: os.getenv("VITE_DEV_MODE", "False") in TRUE_VALUES)
+    proxy_mode: "Literal['vite', 'direct', 'proxy'] | None" = field(default_factory=_resolve_proxy_mode)
+    external_dev_server: "ExternalDevServer | str | None" = None
+    host: str = field(default_factory=lambda: os.getenv("VITE_HOST", "127.0.0.1"))
+    port: int = field(default_factory=lambda: int(os.getenv("VITE_PORT", "5173")))
+    protocol: Literal["http", "https"] = "http"
+    executor: "Literal['node', 'bun', 'deno', 'yarn', 'pnpm'] | None" = None
+    run_command: "list[str] | None" = None
+    build_command: "list[str] | None" = None
+    build_watch_command: "list[str] | None" = None
+    serve_command: "list[str] | None" = None
+    install_command: "list[str] | None" = None
+    is_react: bool = False
+    ssr_enabled: bool = False
+    health_check: bool = field(default_factory=lambda: os.getenv("VITE_HEALTH_CHECK", "False") in TRUE_VALUES)
+    detect_nodeenv: bool = False
+    set_environment: bool = True
+    set_static_folders: bool = True
+    csp_nonce: "str | None" = None
+    spa_handler: bool = True
+    http2: bool = True
+    start_dev_server: bool = True
+
+    def __post_init__(self) -> None:
+        """Normalize runtime settings and apply derived defaults."""
+        if isinstance(self.external_dev_server, str):
+            self.external_dev_server = ExternalDevServer(target=self.external_dev_server)
+
+        if self.external_dev_server is not None and self.proxy_mode in {None, "vite"}:
+            self.proxy_mode = "proxy"
+
+        if self.executor is None:
+            self.executor = "node"
+
+        executor_commands = {
+            "node": {
+                "run": ["npm", "run", "dev"],
+                "build": ["npm", "run", "build"],
+                "build_watch": ["npm", "run", "watch"],
+                "serve": ["npm", "run", "serve"],
+                "install": ["npm", "install"],
+            },
+            "bun": {
+                "run": ["bun", "run", "dev"],
+                "build": ["bun", "run", "build"],
+                "build_watch": ["bun", "run", "watch"],
+                "serve": ["bun", "run", "serve"],
+                "install": ["bun", "install"],
+            },
+            "deno": {
+                "run": ["deno", "task", "dev"],
+                "build": ["deno", "task", "build"],
+                "build_watch": ["deno", "task", "watch"],
+                "serve": ["deno", "task", "serve"],
+                "install": ["deno", "install"],
+            },
+            "yarn": {
+                "run": ["yarn", "dev"],
+                "build": ["yarn", "build"],
+                "build_watch": ["yarn", "watch"],
+                "serve": ["yarn", "serve"],
+                "install": ["yarn", "install"],
+            },
+            "pnpm": {
+                "run": ["pnpm", "dev"],
+                "build": ["pnpm", "build"],
+                "build_watch": ["pnpm", "watch"],
+                "serve": ["pnpm", "serve"],
+                "install": ["pnpm", "install"],
+            },
+        }
+
+        if self.executor in executor_commands:
+            cmds = executor_commands[self.executor]
+            if self.run_command is None:
+                self.run_command = cmds["run"]
+            if self.build_command is None:
+                self.build_command = cmds["build"]
+            if self.build_watch_command is None:
+                self.build_watch_command = cmds["build_watch"]
+            if self.serve_command is None:
+                self.serve_command = cmds["serve"]
+            if self.install_command is None:
+                self.install_command = cmds["install"]
+
+
+@dataclass
+class TypeGenConfig:
+    """Type generation settings.
+
+    Presence of this config enables type generation. Use ``types=None`` or
+    ``types=False`` in ViteConfig to disable.
+
+    Attributes:
+        output: Output directory for generated types.
+        openapi_path: Path to export OpenAPI schema.
+        routes_path: Path to export routes metadata (JSON format).
+        routes_ts_path: Path to export typed routes TypeScript file.
+        generate_zod: Generate Zod schemas from OpenAPI.
+        generate_sdk: Generate SDK client from OpenAPI.
+        generate_routes: Generate typed routes.ts file (Ziggy-style).
+        generate_page_props: Generate Inertia page props TypeScript file.
+            Auto-enabled when both types and inertia are configured.
+        page_props_path: Path to export page props metadata (JSON format).
+        watch_patterns: File patterns to watch for type regeneration.
+        global_route: Register route() function globally on window object.
+            When True, adds ``window.route = route`` to generated routes.ts,
+            providing Laravel/Ziggy-style global access without imports.
+        fallback_type: Fallback value type for untyped containers in generated Inertia props.
+            Controls whether untyped dict/list become `unknown` (default) or `any`.
+        type_import_paths: Map schema/type names to TypeScript import paths for props types
+            that are not present in OpenAPI (e.g., internal/excluded schemas).
+    """
+
+    output: Path = field(default_factory=lambda: Path("src/generated"))
+    openapi_path: "Path | None" = field(default=None)
+    routes_path: "Path | None" = field(default=None)
+    routes_ts_path: "Path | None" = field(default=None)
+    generate_zod: bool = False
+    generate_sdk: bool = True
+    generate_routes: bool = True
+    generate_page_props: bool = True
+    global_route: bool = False
+    """Register route() function globally on window object.
+
+    When True, the generated routes.ts will include code that registers
+    the type-safe route() function on ``window.route``, similar to Laravel's
+    Ziggy library. This allows using route() without imports:
+
+    .. code-block:: typescript
+
+        // With global_route=True, no import needed:
+        window.route('user-profile', { userId: 123 })
+
+        // TypeScript users should add to global.d.ts:
+        // declare const route: typeof import('@/generated/routes').route
+
+    Default is False to encourage explicit imports for better tree-shaking.
+    """
+    fallback_type: "Literal['unknown', 'any']" = "unknown"
+    type_import_paths: dict[str, str] = field(default_factory=lambda: cast("dict[str, str]", {}))
+    """Map schema/type names to TypeScript import paths for Inertia props.
+
+    Use this for prop types that are not present in OpenAPI (e.g., internal schemas).
+    """
+    page_props_path: "Path | None" = field(default=None)
+    """Path to export page props metadata JSON.
+
+    The Vite plugin reads this file to generate page-props.ts.
+    Defaults to output / "inertia-pages.json".
+    """
+    watch_patterns: list[str] = field(
+        default_factory=lambda: ["**/routes.py", "**/handlers.py", "**/controllers/**/*.py"]
+    )
+
+    def __post_init__(self) -> None:
+        """Normalize path types and compute defaults based on output directory."""
+        if isinstance(self.output, str):
+            self.output = Path(self.output)
+        if self.openapi_path is None:
+            self.openapi_path = self.output / "openapi.json"
+        elif isinstance(self.openapi_path, str):
+            self.openapi_path = Path(self.openapi_path)
+        if self.routes_path is None:
+            self.routes_path = self.output / "routes.json"
+        elif isinstance(self.routes_path, str):
+            self.routes_path = Path(self.routes_path)
+        if self.routes_ts_path is None:
+            self.routes_ts_path = self.output / "routes.ts"
+        elif isinstance(self.routes_ts_path, str):
+            self.routes_ts_path = Path(self.routes_ts_path)
+        if self.page_props_path is None:
+            self.page_props_path = self.output / "inertia-pages.json"
+        elif isinstance(self.page_props_path, str):
+            self.page_props_path = Path(self.page_props_path)
+
+
+@dataclass
+class SPAConfig:
+    """Configuration for SPA HTML transformations.
+
+    This configuration controls how the SPA HTML is transformed before serving,
+    including CSRF token injection and Inertia.js page data handling.
+
+    Note:
+        Route metadata is now generated as TypeScript (routes.ts) at build time
+        instead of runtime injection. Use TypeGenConfig.generate_routes to enable.
+
+    Attributes:
+        inject_csrf: Whether to inject CSRF token into HTML (as window.__LITESTAR_CSRF__).
+        csrf_var_name: Global variable name for CSRF token (e.g., window.__LITESTAR_CSRF__).
+        app_selector: CSS selector for the app root element (used for data attributes).
+        cache_transformed_html: Cache transformed HTML in production; disabled when inject_csrf=True because CSRF tokens are per-request.
+    """
+
+    inject_csrf: bool = True
+    csrf_var_name: str = "__LITESTAR_CSRF__"
+    app_selector: str = "#app"
+    cache_transformed_html: bool = True
+
+
+def _get_default_log_level() -> "Literal['quiet', 'normal', 'verbose']":
+    """Get default log level from environment variable.
+
+    Checks LITESTAR_VITE_LOG_LEVEL environment variable.
+    Falls back to "normal" if not set or invalid.
+
+    Returns:
+        The log level from environment or "normal" default.
+    """
+    env_level = os.getenv("LITESTAR_VITE_LOG_LEVEL", "").lower()
+    match env_level:
+        case "quiet" | "normal" | "verbose":
+            return env_level
+        case _:
+            return "normal"
+
+
 def _to_root_path(root_dir: Path, path: Path) -> Path:
     """Resolve a path relative to the configured root directory.
 
@@ -113,6 +749,49 @@ def _to_root_path(root_dir: Path, path: Path) -> Path:
     return path if path.is_absolute() else (root_dir / path)
 
 
+@dataclass
+class LoggingConfig:
+    """Logging configuration for console output.
+
+    Controls the verbosity and style of console output from both Python
+    and TypeScript (via .litestar.json bridge).
+
+    Attributes:
+        level: Logging verbosity level.
+            - "quiet": Minimal output (errors only)
+            - "normal": Standard operational messages (default)
+            - "verbose": Detailed debugging information
+            Can also be set via LITESTAR_VITE_LOG_LEVEL environment variable.
+            Precedence: explicit config > env var > default ("normal")
+        show_paths_absolute: Show absolute paths instead of relative paths.
+            Default False shows cleaner relative paths in output.
+        suppress_npm_output: Suppress npm/yarn/pnpm script echo lines.
+            When True, hides lines like "> dev" / "> vite" from output.
+        suppress_vite_banner: Suppress the Vite startup banner.
+            When True, only the LITESTAR banner is shown.
+        timestamps: Include timestamps in log messages.
+
+    Example:
+        Quiet mode for CI/CD::
+
+            ViteConfig(logging=LoggingConfig(level="quiet"))
+
+        Verbose debugging::
+
+            ViteConfig(logging=LoggingConfig(level="verbose", show_paths_absolute=True))
+
+        Environment variable::
+
+            export LITESTAR_VITE_LOG_LEVEL=quiet
+    """
+
+    level: "Literal['quiet', 'normal', 'verbose']" = field(default_factory=_get_default_log_level)
+    show_paths_absolute: bool = False
+    suppress_npm_output: bool = False
+    suppress_vite_banner: bool = False
+    timestamps: bool = False
+
+
 @dataclass
 class ViteConfig:
     """Root Vite configuration.
@@ -142,7 +821,7 @@ class ViteConfig:
     - Explicit mode parameter overrides auto-detection
 
     Attributes:
-        mode: Serving mode - "spa", "template", "htmx", "hybrid", "framework", "ssr", "ssg", or "external".
+        mode: Serving mode - "spa", "template", "htmx", "hybrid", "ssr", "ssg", or "external".
             Auto-detected if not set. Use "external" for non-Vite frameworks (Angular CLI, etc.)
             that have their own build system - auto-serves bundle_dir in production.
         paths: File system paths configuration.
@@ -152,11 +831,11 @@ class ViteConfig:
         spa: SPA transformation settings (True enables with defaults, False disables).
         logging: Logging configuration (True enables with defaults, None uses defaults).
         dev_mode: Convenience shortcut for runtime.dev_mode.
-        base_url: Base URL for the app entry point.
+        base_url: Base URL for production assets (CDN support).
         deploy: Deployment configuration for CDN publishing.
     """
 
-    mode: "Literal['spa', 'template', 'htmx', 'hybrid', 'inertia', 'framework', 'ssr', 'ssg', 'external'] | None" = None
+    mode: "Literal['spa', 'template', 'htmx', 'hybrid', 'inertia', 'ssr', 'ssg', 'external'] | None" = None
     paths: PathConfig = field(default_factory=PathConfig)
     runtime: RuntimeConfig = field(default_factory=RuntimeConfig)
     types: "TypeGenConfig | bool | None" = None
@@ -170,7 +849,7 @@ class ViteConfig:
     """Custom guards for the SPA catch-all route.
 
     When set, these guards are applied to the SPA handler route that serves the
-    SPA index.html (mode="spa"/"framework" with spa_handler=True).
+    SPA index.html (mode="spa"/"ssr" with spa_handler=True).
     """
     exclude_static_from_auth: bool = True
     """Exclude static file routes from authentication.
@@ -214,7 +893,7 @@ class ViteConfig:
         self._auto_detect_mode()
         self._auto_configure_inertia()
         self._auto_detect_react()
-        self._apply_framework_mode_defaults()
+        self._apply_ssr_mode_defaults()
         self._normalize_deploy()
         self._ensure_spa_default()
         self._auto_enable_dev_mode()
@@ -259,20 +938,17 @@ class ViteConfig:
         """Normalize mode aliases.
 
         Aliases:
-        - 'framework': Canonical name for meta-framework integration mode (Astro/Nuxt/SvelteKit, etc.)
-          that uses dev-time proxying to a frontend dev server and optional SSR/SSG output handling.
-
-        - 'ssr' / 'ssg' → 'framework': Aliases for framework proxy mode.
-          Static Site Generation (SSG) uses the same dev-time proxy behavior as SSR:
-          forward non-API routes to the framework dev server. SSG pre-renders at build time,
-          SSR renders per-request, but their dev-time proxy behavior is identical.
+        - 'ssg' → 'ssr': Static Site Generation uses the same proxy behavior as SSR.
+          Both use deny list proxy in dev mode (forward non-API routes to framework's
+          dev server). SSG pre-renders at build time, SSR renders per-request, but
+          their dev-time proxy behavior is identical.
 
         - 'inertia' → 'hybrid': Inertia.js apps without Jinja templates use hybrid mode.
           This is clearer terminology since "hybrid" refers to the SPA-with-server-routing
           pattern that Inertia implements.
         """
-        if self.mode in {"ssr", "ssg"}:
-            self.mode = "framework"
+        if self.mode == "ssg":
+            self.mode = "ssr"
         elif self.mode == "inertia":
             self.mode = "hybrid"
 
@@ -337,10 +1013,10 @@ class ViteConfig:
         if isinstance(self.inertia, InertiaConfig) and isinstance(self.spa, SPAConfig) and not self.spa.inject_csrf:
             self.spa = replace(self.spa, inject_csrf=True)
 
-    def _apply_framework_mode_defaults(self) -> None:
-        """Apply intelligent defaults for framework proxy mode.
+    def _apply_ssr_mode_defaults(self) -> None:
+        """Apply intelligent defaults for mode='ssr'.
 
-        When mode='framework' is set, automatically configure proxy_mode and spa_handler
+        When mode='ssr' is set, automatically configure proxy_mode and spa_handler
         based on dev_mode and whether built assets exist:
 
         - Dev mode: proxy_mode='proxy', spa_handler=False
@@ -350,7 +1026,7 @@ class ViteConfig:
         - Prod mode without built assets: proxy_mode=None, spa_handler=False
           (True SSR - Node server handles HTML, Litestar only serves API)
         """
-        if self.mode != "framework":
+        if self.mode != "ssr":
             return
 
         if self.runtime.dev_mode:
@@ -461,14 +1137,14 @@ class ViteConfig:
         if self.runtime.external_dev_server is not None:
             return
 
-        candidates = self.candidate_manifest_paths()
-        manifest_locations = " or ".join(str(path) for path in candidates)
+        bundle_path = self._resolve_to_root(self.bundle_dir)
+        manifest_path = bundle_path / ".vite" / self.manifest_name
         logger.warning(
             "Vite manifest not found at %s. "
             "Run 'litestar assets build' (or 'npm run build') to build assets, "
             "or set dev_mode=True for development. "
             "Assets will not load correctly without built files or a running Vite dev server.",
-            manifest_locations,
+            manifest_path,
         )
 
     def _detect_mode(self) -> Literal["spa", "template", "htmx", "hybrid"]:
@@ -692,49 +1368,11 @@ class ViteConfig:
             unique.append(path)
         return unique
 
-    def candidate_manifest_paths(self) -> list[Path]:
-        """Return possible manifest.json locations in the bundle directory.
-
-        Some meta-frameworks emit the manifest under a ``.vite/`` subdirectory
-        (e.g. ``<bundle_dir>/.vite/manifest.json``), while plain Vite builds may
-        write it directly to ``<bundle_dir>/manifest.json``.
-
-        Returns:
-            A de-duplicated list of candidate manifest paths, ordered by preference.
-        """
-        bundle_path = self._resolve_to_root(self.bundle_dir)
-        manifest_rel = Path(self.manifest_name)
-
-        candidates: list[Path] = [bundle_path / manifest_rel]
-        if not manifest_rel.is_absolute() and (not manifest_rel.parts or manifest_rel.parts[0] != ".vite"):
-            candidates.append(bundle_path / ".vite" / manifest_rel)
-
-        unique: list[Path] = []
-        seen: set[Path] = set()
-        for path in candidates:
-            if path in seen:
-                continue
-            seen.add(path)
-            unique.append(path)
-        return unique
-
-    def resolve_manifest_path(self) -> Path:
-        """Resolve the most likely manifest path.
-
-        Returns:
-            The first existing manifest path, or the highest-priority candidate when none exist.
-        """
-        candidates = self.candidate_manifest_paths()
-        for candidate in candidates:
-            if candidate.exists():
-                return candidate
-        return candidates[0]
-
     def has_built_assets(self) -> bool:
         """Check if production assets exist in the bundle directory.
 
         Returns:
-            True if a manifest or built index.html exists in bundle_dir.
+            True if manifest.json or built index.html exists in bundle_dir.
 
         Note:
             This method checks the bundle_dir (output directory) for built artifacts,
@@ -742,9 +1380,10 @@ class ViteConfig:
             does not indicate built assets exist.
         """
         bundle_path = self._resolve_to_root(self.bundle_dir)
+        manifest_path = bundle_path / self.manifest_name
         index_path = bundle_path / "index.html"
 
-        return any(path.exists() for path in self.candidate_manifest_paths()) or index_path.exists()
+        return manifest_path.exists() or index_path.exists()
 
     @property
     def host(self) -> str:
@@ -777,7 +1416,7 @@ class ViteConfig:
     def hot_reload(self) -> bool:
         """Check if hot reload is enabled (derived from dev_mode and proxy_mode).
 
-        HMR requires dev_mode=True AND a Vite-based proxy mode (vite, direct, or proxy).
+        HMR requires dev_mode=True AND a Vite-based mode (vite, direct, or proxy/ssr).
         All modes support HMR since even SSR frameworks use Vite internally.
 
         Returns:
@@ -803,6 +1442,15 @@ class ViteConfig:
         """
         return self.runtime.is_react
 
+    @property
+    def ssr_enabled(self) -> bool:
+        """Check if SSR is enabled.
+
+        Returns:
+            True if SSR is enabled, otherwise False.
+        """
+        return self.runtime.ssr_enabled
+
     @property
     def run_command(self) -> list[str]:
         """Get the run command.
@@ -927,27 +1575,6 @@ class ViteConfig:
         """
         return self.runtime.http2
 
-    @property
-    def csp_nonce(self) -> "str | None":
-        """Return the CSP nonce used for injected inline scripts.
-
-        Returns:
-            CSP nonce string when configured, otherwise None.
-        """
-        return self.runtime.csp_nonce
-
-    @property
-    def trusted_proxies(self) -> "list[str] | str | None":
-        """Get trusted proxies configuration.
-
-        When set, enables ProxyHeadersMiddleware to handle X-Forwarded-* headers
-        from reverse proxies (Railway, Heroku, AWS ALB, nginx, etc.).
-
-        Returns:
-            The trusted proxies configuration, or None if disabled.
-        """
-        return self.runtime.trusted_proxies
-
     @property
     def ssr_output_dir(self) -> "Path | None":
         """Get SSR output directory.