fix: address 0.26.0 release review regressions (#318)

Summary
- Fix Inertia partial reload filtering for plain dict route props,
explicit scrollProps keying, and sessionless scope shared props.
- Fix Deno package/bin fallback argv for typegen and JS install-hint
execution.
- Fix Vite dev-server auto-restart retry accounting so stable restarts
reset the retry budget while crash loops still cap out.
- Add 0.26.0 changelog migration notes and release-review fix entries.

Author: cofin

docs/changelog.rst

@@ -10,20 +10,32 @@ Litestar Vite Changelog
 0.26.0 - 2026-07-05
 -------------------
 
+Migration notes
+~~~~~~~~~~~~~~~
+
+- Inertia asset-version mismatches now follow the protocol more strictly: stale ``GET`` visits receive the ``409`` refresh response, while stale non-``GET`` submissions continue to their handlers. Review handlers that relied on non-``GET`` mismatch short-circuiting.
+- Inertia infinite-scroll metadata is now emitted as ``scrollProps`` keyed by data prop name. Frontend code that read a single flat scroll config should read ``scrollProps.<propName>`` instead.
+- Type generation now fails production builds by default when generation fails. Set ``TypeGenConfig(fail_on_error=False)`` or ``types.failOnError = false`` to keep warn-only build behavior.
+
 - Fixed Inertia asset-version mismatch handling so only ``GET`` requests can return the protocol ``409`` refresh response; non-GET submissions now continue to their handlers instead of being downgraded and losing the request body. (#306)
 - Fixed ``share()`` with Inertia redirects so top-level sync special props are materialized before session storage and async special props are skipped instead of crashing session serialization. (#306)
+- Fixed request-scope Inertia shared props so they are still rendered on routes without session middleware.
 - Fixed Inertia infinite-scroll ``scrollProps`` to emit a record keyed by data prop name, matching the official client protocol. (#306)
+- Fixed explicit Inertia ``scroll_props=`` responses so metadata is keyed by the returned data prop when there is a single route prop.
 - Fixed auto-wrapped Inertia responses so non-Inertia JSON handlers preserve Litestar's resolved ``201``/``204`` status codes while user-created ``InertiaResponse`` statuses still win. (#306)
 - Fixed Precognition validation success handling for handlers without an explicit ``request`` parameter by using the middleware request context. (#306)
 - Fixed Inertia SSR serialization so app, handler, and response type encoders are honored for custom page prop values. (#306)
 - Fixed Inertia partial reloads so ``deferredProps`` metadata is omitted on partial responses while initial responses still advertise deferred props. (#306)
+- Fixed Inertia partial reloads so plain dict route props honor ``X-Inertia-Partial-Data`` and ``X-Inertia-Partial-Except`` independently.
 - Fixed ``litestar assets init`` so generated ``package.json`` files no longer emit duplicate dependency keys. (#302, #303)
 - Fixed type generation so the JS plugin resolves local ``@hey-api/openapi-ts`` installs first, uses a pinned package-manager fallback when needed, fails production builds loudly by default, and lets ``TypeGenConfig(fail_on_error=False)`` or ``types.failOnError = false`` opt out. (#311, #314)
+- Fixed Deno type-generation fallback execution when the providing npm package exposes a binary with a different name.
 - Fixed type generation reliability for generated outputs by preserving queued dev regenerations, checking that expected output files exist before reusing caches, watching ``routes.json``, emitting ``static-props.ts`` from the shared CLI path, and handling semantic aliases and nested hey-api operation types. (#311, #314)
 - Fixed Vite dev-server resilience by revalidating hotfile targets by mtime, recovering after missing or replaced hotfiles, tolerating additive/corrupt bridge config files, aligning TLS certificate env vars, and preserving static-files defaults when user overrides leave fields unset. (#312, #314)
 - Fixed ``litestar assets init`` scaffold correctness for framework variants without dedicated directories, Tailwind CSS/PostCSS dependencies and entry inputs, current hey-api/TanStack/Vite template APIs, transactional writes, and non-interactive collision handling. (#313, #314)
 - Updated npm publishing to use trusted publishing with provenance and no npm token. (#314)
 - Fixed Vite dev-server lifecycle handling so unexpected exits are restarted with capped backoff and intentional shutdowns do not trigger restarts. (#317)
+- Fixed Vite dev-server auto-restart so each recovered crash gets a fresh retry budget instead of exhausting the lifetime budget.
 - Changed SPA/proxy route-prefix fallbacks so ``/docs`` is no longer reserved unless Litestar actually registers docs there or ``RuntimeConfig.extra_route_prefixes`` includes it. (#317)
 - Added ``ViteConfig(enabled=...)`` and ``VITE_ENABLED`` so Vite routes and lifespans can be disabled in CLI, worker, and test contexts while keeping asset CLI commands available. (#301, #310)
 - Added ``RuntimeConfig.extra_route_prefixes`` for deliberately reserving custom backend prefixes from SPA/proxy fallbacks. (#317)

src/js/src/install-hint.ts

@@ -106,14 +106,31 @@ export interface PackageExecutorArgvOptions {
   binName?: string
 }
 
+function getPackageNameFromSpec(packageSpec: string): string {
+  if (packageSpec.startsWith("@")) {
+    const versionIndex = packageSpec.indexOf("@", packageSpec.indexOf("/") + 1)
+    return versionIndex === -1 ? packageSpec : packageSpec.slice(0, versionIndex)
+  }
+  const versionIndex = packageSpec.indexOf("@")
+  return versionIndex === -1 ? packageSpec : packageSpec.slice(0, versionIndex)
+}
+
+function resolveDenoPackageSpec(packageSpec: string, binName?: string): string {
+  if (!binName) return packageSpec
+
+  const packageName = getPackageNameFromSpec(packageSpec)
+  const defaultBinName = packageName.split("/").pop()
+  return defaultBinName === binName ? packageSpec : `${packageSpec}/${binName}`
+}
+
 export function resolvePackageExecutorArgv(args: string[], executor?: string, options: PackageExecutorArgvOptions = {}): string[] {
   const runtime = executor || detectExecutor()
   const { packageSpec, binName } = options
   switch (runtime) {
     case "bun":
       return ["bunx", ...(packageSpec ? [packageSpec, ...args] : args)]
     case "deno":
-      return ["deno", "run", "-A", ...(packageSpec ? [`npm:${packageSpec}`, ...args] : args)]
+      return ["deno", "run", "-A", ...(packageSpec ? [`npm:${resolveDenoPackageSpec(packageSpec, binName)}`, ...args] : args)]
     case "pnpm":
       return ["pnpm", "dlx", ...(packageSpec ? [packageSpec, ...args] : args)]
     case "yarn":

src/js/tests/install-hint.test.ts

@@ -387,5 +387,14 @@ describe("install-hint", () => {
         "openapi-ts.config.ts",
       ])
     })
+
+    it("uses the package binary path for deno when package name and bin differ", () => {
+      expect(
+        resolvePackageExecutorArgv(["--verbose"], "deno", {
+          packageSpec: "litestar-vite-plugin",
+          binName: "litestar-vite-typegen",
+        }),
+      ).toEqual(["deno", "run", "-A", "npm:litestar-vite-plugin/litestar-vite-typegen", "--verbose"])
+    })
   })
 })

src/py/litestar_vite/cli.py

@@ -1013,7 +1013,8 @@ def _get_package_executor_cmd(executor: "str | None", binary: str, *, package_na
         case "bun":
             return ["bunx", "--package", package, binary] if package_name else ["bunx", binary]
         case "deno":
-            return ["deno", "run", "-A", f"npm:{package}"]
+            deno_package = f"{package}/{binary}" if package != binary else package
+            return ["deno", "run", "-A", f"npm:{deno_package}"]
         case "yarn":
             return ["yarn", "dlx", "--package", package, binary] if package_name else ["yarn", "dlx", binary]
         case "pnpm":

src/py/litestar_vite/inertia/helpers.py

@@ -1375,15 +1375,28 @@ def get_shared_props(
     once_props_entries: "list[_OncePropEntry]" = []
     error_bag = request.headers.get("X-Inertia-Error-Bag", None)
 
+    session_available = True
+    session_shared_props: Mapping[str, Any] = {}
+    scope_shared_props = cast("dict[str, Any]", request.scope).pop(_RAW_SHARED_SCOPE_KEY, {})
     try:
         errors = request.session.pop("_errors", {})
-        session_shared_props = request.session.pop("_shared", {})
-        scope_shared_props = cast("dict[str, Any]", request.scope).pop(_RAW_SHARED_SCOPE_KEY, {})
-        shared_props = (
-            {**cast("Mapping[str, Any]", session_shared_props), **cast("Mapping[str, Any]", scope_shared_props)}
-            if isinstance(session_shared_props, Mapping) and isinstance(scope_shared_props, Mapping)
-            else cast("dict[str,Any]", session_shared_props)
+        raw_session_shared_props = request.session.pop("_shared", {})
+    except (AttributeError, ImproperlyConfiguredException):
+        session_available = False
+        msg = "Unable to generate all shared props.  A valid session was not found for this request."
+        request.logger.warning(msg)
+    else:
+        session_shared_props = (
+            cast("Mapping[str, Any]", raw_session_shared_props) if isinstance(raw_session_shared_props, Mapping) else {}
         )
+
+    shared_props = (
+        {**session_shared_props, **cast("Mapping[str, Any]", scope_shared_props)}
+        if isinstance(scope_shared_props, Mapping)
+        else dict(session_shared_props)
+    )
+
+    try:
         inertia_plugin = cast("InertiaPlugin", request.app.plugins.get("InertiaPlugin"))
 
         once_props_entries = _extract_once_prop_entries(shared_props, partial_data, partial_except)
@@ -1407,20 +1420,22 @@ def get_shared_props(
             else:
                 props[key] = value
 
-        for message in cast("list[dict[str,Any]]", request.session.pop("_messages", [])):
-            flash[message["category"]].append(message["message"])
+        if session_available:
+            for message in cast("list[dict[str,Any]]", request.session.pop("_messages", [])):
+                flash[message["category"]].append(message["message"])
 
         for key, value in inertia_plugin.config.extra_static_page_props.items():
             if should_render(value, partial_data, partial_except, key=key):
                 props[key] = value
 
-        for session_prop in inertia_plugin.config.extra_session_page_props:
-            if (
-                session_prop not in props
-                and session_prop in request.session
-                and should_render(None, partial_data, partial_except, key=session_prop)
-            ):
-                props[session_prop] = request.session.get(session_prop)
+        if session_available:
+            for session_prop in inertia_plugin.config.extra_session_page_props:
+                if (
+                    session_prop not in props
+                    and session_prop in request.session
+                    and should_render(None, partial_data, partial_except, key=session_prop)
+                ):
+                    props[session_prop] = request.session.get(session_prop)
 
     except (AttributeError, ImproperlyConfiguredException):
         msg = "Unable to generate all shared props.  A valid session was not found for this request."

src/py/litestar_vite/inertia/response.py

@@ -208,6 +208,7 @@ def _build_page_props(
         content: Any = self.content
         route_content: Any | None = None
         route_once_props: "list[tuple[str, str]]" = []
+        route_prop_keys: list[str] = []
 
         # v2.2+ protocol: Extract deferred props metadata before filtering.
         # Route props override shared props with the same key, so discard any
@@ -225,7 +226,7 @@ def _build_page_props(
             filtered_content: Any = lazy_render(cast("Any", content), partial_data, partial_except, except_once_props)
             if filtered_content is not None:
                 route_content = filtered_content
-        elif isinstance(content, Mapping) and partial_data and partial_except:
+        elif isinstance(content, Mapping) and (partial_data or partial_except):
             route_content = lazy_render(
                 cast("Mapping[str, Any]", content), partial_data, partial_except, except_once_props
             )
@@ -239,11 +240,14 @@ def _build_page_props(
                     if self.prop_filter is not None and not self.prop_filter.should_include(str(key)):
                         continue
                     shared_props[key] = value
+                    route_prop_keys.append(str(key))
             elif is_pagination_container(route_content):
                 prop_key = _get_route_prop_key(route_handler)
                 shared_props[prop_key] = route_content
+                route_prop_keys.append(prop_key)
             else:
                 shared_props["content"] = route_content
+                route_prop_keys.append("content")
 
         # Drop keys this partial reload just resolved, or the client loops on loadDeferredProps.
         deferred_props = _resolve_deferred_props(deferred_props_map, partial_data, is_partial_render)
@@ -259,7 +263,10 @@ def _build_page_props(
             shared_props = unwrap_merge_props(shared_props)
 
         scroll_props = _apply_pagination_props(
-            shared_props, route_handler=route_handler, explicit_scroll_props=self.scroll_props
+            shared_props,
+            route_handler=route_handler,
+            explicit_scroll_props=self.scroll_props,
+            explicit_scroll_props_key=_get_explicit_scroll_props_key(route_prop_keys, route_handler),
         )
 
         encrypt_history = _resolve_encrypt_history(self.encrypt_history, inertia_plugin)
@@ -1057,12 +1064,22 @@ def _get_route_prop_key(route_handler: Any) -> str:
     return (route_handler.opt.get("key", "items") if route_handler else "items") or "items"
 
 
+def _get_explicit_scroll_props_key(route_prop_keys: list[str], route_handler: Any) -> str:
+    if len(route_prop_keys) == 1:
+        return route_prop_keys[0]
+    return _get_route_prop_key(route_handler)
+
+
 def _apply_pagination_props(
-    shared_props: "dict[str, Any]", *, route_handler: Any, explicit_scroll_props: "ScrollPropsConfig | None"
+    shared_props: "dict[str, Any]",
+    *,
+    route_handler: Any,
+    explicit_scroll_props: "ScrollPropsConfig | None",
+    explicit_scroll_props_key: str,
 ) -> "dict[str, ScrollPropsConfig] | None":
     scroll_props_map: "dict[str, ScrollPropsConfig]" = {}
     if explicit_scroll_props is not None:
-        scroll_props_map[_get_route_prop_key(route_handler)] = explicit_scroll_props
+        scroll_props_map[explicit_scroll_props_key] = explicit_scroll_props
 
     infinite_scroll_enabled = bool(route_handler and route_handler.opt.get("infinite_scroll", False))
     for key in tuple(shared_props):

src/py/litestar_vite/plugin/_process.py

@@ -29,6 +29,7 @@ class ViteProcess:
     _signals_registered: bool = False
     _original_handlers: "dict[int, Any]" = {}
     _RESTART_BACKOFFS: ClassVar[tuple[float, ...]] = (1.0, 2.0, 4.0)
+    _RESTART_STABILITY_SECONDS: ClassVar[float] = 5.0
 
     def __init__(self, executor: "JSExecutor") -> None:
         """Initialize the Vite process manager.
@@ -200,7 +201,9 @@ def _watch_process(self, generation: int) -> None:
                 command = self._restart_command
                 cwd = self._restart_cwd
 
+            wait_started = time.monotonic()
             exit_code = process.wait()
+            process_runtime = time.monotonic() - wait_started
             self._terminate_exited_process_group(process, timeout=0.5)
 
             with self._lock:
@@ -210,6 +213,10 @@ def _watch_process(self, generation: int) -> None:
                 if command is None or cwd is None:
                     return
 
+            if process_runtime >= self._RESTART_STABILITY_SECONDS:
+                attempts = 0
+                last_error = None
+
             restarted = False
             while attempts < len(self._RESTART_BACKOFFS):
                 backoff = self._RESTART_BACKOFFS[attempts]

src/py/tests/unit/inertia/test_helpers.py

@@ -4,6 +4,7 @@
 from unittest.mock import MagicMock
 
 from litestar import Request, get
+from litestar.exceptions import ImproperlyConfiguredException
 from litestar.middleware.session.server_side import ServerSideSessionConfig
 from litestar.stores.memory import MemoryStore
 from litestar.template.config import TemplateConfig
@@ -42,6 +43,27 @@ def test_get_shared_props_includes_csrf_token_from_scope() -> None:
     assert shared_props["csrf_token"] == "scope-csrf-token"
 
 
+def test_get_shared_props_includes_scope_props_when_session_is_unavailable() -> None:
+    """Request-scope shared props should survive requests excluded from session middleware."""
+    from litestar_vite.inertia.helpers import _RAW_SHARED_SCOPE_KEY, get_shared_props
+
+    request = MagicMock()
+    request.headers.get.return_value = None
+    request.session.pop.side_effect = ImproperlyConfiguredException("No session")
+    request.scope = {_RAW_SHARED_SCOPE_KEY: {"auth": {"user": "Ada"}}}
+    request.logger = MagicMock()
+
+    inertia_plugin = MagicMock()
+    inertia_plugin.config.extra_static_page_props = {}
+    inertia_plugin.config.extra_session_page_props = []
+    request.app.plugins.get.return_value = inertia_plugin
+
+    shared_props = get_shared_props(request)
+
+    assert shared_props["auth"] == {"user": "Ada"}
+    assert _RAW_SHARED_SCOPE_KEY not in request.scope
+
+
 def test_scroll_props_helper_creates_config() -> None:
     """Test scroll_props() helper creates correct ScrollPropsConfig."""
     config = scroll_props(page_name="page", current_page=2, previous_page=1, next_page=3)
@@ -255,7 +277,7 @@ async def handler(request: Request[Any, Any, Any]) -> dict[str, Any]:
         share(request, "user", {"name": "Alice"})
         share(request, "settings", {"theme": "dark"})
         share(request, "notifications", ["msg1", "msg2"])
-        # Route handler props are always included
+        # Route handler props are filtered by the same partial-data keys
         return {"posts": [1, 2, 3], "comments": [4, 5, 6]}
 
     with create_test_client(
@@ -286,9 +308,9 @@ async def handler(request: Request[Any, Any, Any]) -> dict[str, Any]:
         partial_props = partial_response.json()["props"]
         # user is requested and present in shared props
         assert "user" in partial_props
-        # Route handler props are always included (posts, comments)
+        # Route handler props follow partial-data filtering
         assert "posts" in partial_props
-        assert "comments" in partial_props
+        assert "comments" not in partial_props
         # Shared props not requested are filtered out
         assert "settings" not in partial_props
         assert "notifications" not in partial_props