litestar-vite-plugin 0.26.1 → 0.28.0

package/README.md

@@ -20,19 +20,10 @@ npm install litestar-vite-plugin
 ## Quick Start
 
 ```python
-import os
-from pathlib import Path
 from litestar import Litestar
-from litestar_vite import PathConfig, ViteConfig, VitePlugin
+from litestar_vite import VitePlugin
 
-DEV_MODE = os.getenv("VITE_DEV_MODE", "true").lower() in ("true", "1", "yes")
-
-app = Litestar(
-    plugins=[VitePlugin(config=ViteConfig(
-        dev_mode=DEV_MODE,
-        paths=PathConfig(root=Path(__file__).parent),
-    ))]
-)
+app = Litestar(plugins=[VitePlugin()])
 ```
 
 ```bash
@@ -41,14 +32,42 @@ litestar assets install
 litestar run --reload
 ```
 
-## Documentation
+`VitePlugin()` detects development and production behavior without manual `VITE_DEV_MODE` parsing. The effective
+`litestar run --host/--port` values are also passed to the frontend environment and `.litestar.json` bridge.
+
+### Optional Granian native static serving
+
+Granian 0.16+ can serve eligible production bundle files before the request enters Python:
+
+```python
+from litestar import Litestar
+from litestar_granian import GranianPlugin
+from litestar_vite import VitePlugin
+
+app = Litestar(
+    plugins=[
+        VitePlugin(),
+        GranianPlugin(static="auto"),
+    ]
+)
+```
+
+This is an optimization, not a separate application configuration. The Litestar static route stays registered, so
+Uvicorn and other ASGI servers serve the same files. Granian automatically falls back to Litestar when assets are
+protected, customized, missing, or otherwise unsafe to intercept.
 
-- **[Usage Guide](https://litestar-org.github.io/litestar-vite/usage/index.html)**: Core concepts, configuration, and type generation.
-- **[Inertia](https://litestar-org.github.io/litestar-vite/frameworks/inertia/index.html)**: Fullstack protocols and SSR.
-- **[Frameworks](https://litestar-org.github.io/litestar-vite/frameworks/index.html)**: Guides for React, Vue, Svelte, Angular, Astro, and Nuxt.
-- **[Reference](https://litestar-org.github.io/litestar-vite/reference/index.html)**: API and CLI documentation.
+Native hits bypass ASGI middleware, guards, compression, custom headers, and Python access logging. Keep protected or
+customized assets on the Litestar fallback path. See the
+[production guide](https://litestar-org.github.io/litestar-vite/latest/usage/production.html) for the server matrix and
+advanced configuration.
+
+## Documentation
 
-For a full list of changes, see the [Changelog](https://litestar-org.github.io/litestar-vite/changelog.html).
+- Get started: <https://litestar-org.github.io/litestar-vite/latest/usage/index.html>
+- Framework guides: <https://litestar-org.github.io/litestar-vite/latest/frameworks/index.html>
+- Inertia: <https://litestar-org.github.io/litestar-vite/latest/frameworks/inertia/index.html>
+- API reference: <https://litestar-org.github.io/litestar-vite/latest/reference/index.html>
+- Changelog: <https://litestar-org.github.io/litestar-vite/latest/changelog.html>
 
 ## Common Commands
 
@@ -76,7 +95,7 @@ litestar-vite now defaults Inertia apps to script-element bootstrap. Inertia v3
 
 ## Links
 
-- Docs: <https://litestar-org.github.io/litestar-vite/>
+- Docs: <https://litestar-org.github.io/litestar-vite/latest/>
 - Examples: `examples/` (React, Vue, Svelte, HTMX, Inertia, Astro, Nuxt, SvelteKit, Angular)
 - Real-world example: [litestar-fullstack](https://github.com/litestar-org/litestar-fullstack)
 - Issues: <https://github.com/litestar-org/litestar-vite/issues/>

package/dist/js/astro.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { readBridgeConfig } from "./shared/bridge-schema.js";
+import { installManagedShutdown } from "./shared/managed-shutdown.js";
 import { normalizeHost, resolveHotFilePath, resolveLitestarPort } from "./shared/network.js";
 import { createLitestarTypeGenPlugin, resolveTypesConfig } from "./shared/typegen-plugin.js";
 import { hmrServerConfig } from "./shared/vite-compat.js";
@@ -91,6 +92,9 @@ function createProxyPlugin(config) {
           }
         }
       };
+    },
+    configureServer(server) {
+      installManagedShutdown(server);
     }
   };
 }

package/dist/js/dev-server-index.html

@@ -7,8 +7,8 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" />
-    <style rel="stylesheet" crossorigin>/*! tailwindcss v4.3.2 | MIT License | https://tailwindcss.com */
-@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){*,:before,:after,::backdrop{--tw-space-y-reverse:0;--tw-border-style:solid;--tw-leading:initial;--tw-font-weight:initial;--tw-tracking:initial;--tw-duration:initial;--tw-translate-x:0;--tw-translate-y:0;--tw-translate-z:0}}}@layer theme{:root,:host{--font-sans:"Inter", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;--font-mono:"JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;--spacing:.25rem;--container-lg:32rem;--text-xs:.75rem;--text-xs--line-height:calc(1 / .75);--text-sm:.875rem;--text-sm--line-height:calc(1.25 / .875);--text-base:1rem;--text-base--line-height:calc(1.5 / 1);--text-xl:1.25rem;--text-xl--line-height:calc(1.75 / 1.25);--text-2xl:1.5rem;--text-2xl--line-height:calc(2 / 1.5);--text-4xl:2.25rem;--text-4xl--line-height:calc(2.5 / 2.25);--font-weight-light:300;--font-weight-medium:500;--font-weight-semibold:600;--tracking-widest:.1em;--leading-relaxed:1.625;--default-transition-duration:.15s;--default-transition-timing-function:cubic-bezier(.4, 0, .2, 1);--default-font-family:var(--font-sans);--default-mono-font-family:var(--font-mono);--color-navy:#202235;--color-navy-surface:#2a2d40;--color-navy-surface-variant:#1a1c2e;--color-gold:#edb641;--color-gold-light:#ffd480;--color-on-surface:#f8fafc;--color-on-surface-muted:#cbd5e1;--color-on-surface-subtle:#94a3b8;--color-outline:#334155;--color-success:#4ade80;--radius-brand:8px;--radius-brand-lg:12px;--shadow-text-glow-dark:0 0 24px #edb64138}}@layer base{*,:after,:before,::backdrop{box-sizing:border-box;border:0 solid;margin:0;padding:0}::file-selector-button{box-sizing:border-box;border:0 solid;margin:0;padding:0}html,:host{-webkit-text-size-adjust:100%;tab-size:4;line-height:1.5;font-family:var(--default-font-family,ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji");font-feature-settings:var(--default-font-feature-settings,normal);font-variation-settings:var(--default-font-variation-settings,normal);-webkit-tap-highlight-color:transparent}hr{height:0;color:inherit;border-top-width:1px}abbr:where([title]){-webkit-text-decoration:underline dotted;text-decoration:underline dotted}h1,h2,h3,h4,h5,h6{font-size:inherit;font-weight:inherit}a{color:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;text-decoration:inherit}b,strong{font-weight:bolder}code,kbd,samp,pre{font-family:var(--default-mono-font-family,ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace);font-feature-settings:var(--default-mono-font-feature-settings,normal);font-variation-settings:var(--default-mono-font-variation-settings,normal);font-size:1em}small{font-size:80%}sub,sup{vertical-align:baseline;font-size:75%;line-height:0;position:relative}sub{bottom:-.25em}sup{top:-.5em}table{text-indent:0;border-color:inherit;border-collapse:collapse}:-moz-focusring{outline:auto}progress{vertical-align:baseline}summary{display:list-item}ol,ul,menu{list-style:none}img,svg,video,canvas,audio,iframe,embed,object{vertical-align:middle;display:block}img,video{max-width:100%;height:auto}button,input,select,optgroup,textarea{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;color:inherit;opacity:1;background-color:#0000;border-radius:0}::file-selector-button{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;color:inherit;opacity:1;background-color:#0000;border-radius:0}:where(select:is([multiple],[size])) optgroup{font-weight:bolder}:where(select:is([multiple],[size])) optgroup option{padding-inline-start:20px}::file-selector-button{margin-inline-end:4px}::placeholder{opacity:1}@supports (not ((-webkit-appearance:-apple-pay-button))) or (contain-intrinsic-size:1px){::placeholder{color:currentColor}@supports (color:color-mix(in lab, red, red)){::placeholder{color:color-mix(in oklab, currentcolor 50%, transparent)}}}textarea{resize:vertical}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-date-and-time-value{min-height:1lh;text-align:inherit}::-webkit-datetime-edit{display:inline-flex}::-webkit-datetime-edit-fields-wrapper{padding:0}::-webkit-datetime-edit{padding-block:0}::-webkit-datetime-edit-year-field{padding-block:0}::-webkit-datetime-edit-month-field{padding-block:0}::-webkit-datetime-edit-day-field{padding-block:0}::-webkit-datetime-edit-hour-field{padding-block:0}::-webkit-datetime-edit-minute-field{padding-block:0}::-webkit-datetime-edit-second-field{padding-block:0}::-webkit-datetime-edit-millisecond-field{padding-block:0}::-webkit-datetime-edit-meridiem-field{padding-block:0}::-webkit-calendar-picker-indicator{line-height:1}:-moz-ui-invalid{box-shadow:none}button,input:where([type=button],[type=reset],[type=submit]){appearance:button}::file-selector-button{appearance:button}::-webkit-inner-spin-button{height:auto}::-webkit-outer-spin-button{height:auto}[hidden]:where(:not([hidden=until-found])){display:none!important}}@layer components;@layer utilities{.absolute{position:absolute}.relative{position:relative}.mt-8{margin-top:calc(var(--spacing) * 8)}.mb-3{margin-bottom:calc(var(--spacing) * 3)}.mb-4{margin-bottom:calc(var(--spacing) * 4)}.mb-10{margin-bottom:calc(var(--spacing) * 10)}.mb-12{margin-bottom:calc(var(--spacing) * 12)}.ml-auto{margin-left:auto}.block{display:block}.flex{display:flex}.inline{display:inline}.inline-flex{display:inline-flex}.h-2\.5{height:calc(var(--spacing) * 2.5)}.h-3\.5{height:calc(var(--spacing) * 3.5)}.h-12{height:calc(var(--spacing) * 12)}.h-14{height:calc(var(--spacing) * 14)}.h-full{height:100%}.min-h-screen{min-height:100vh}.w-2\.5{width:calc(var(--spacing) * 2.5)}.w-3\.5{width:calc(var(--spacing) * 3.5)}.w-auto{width:auto}.w-full{width:100%}.max-w-lg{max-width:var(--container-lg)}.min-w-0{min-width:0}.flex-1{flex:1}.flex-none{flex:none}.animate-pulse-dot{animation:2s ease-in-out infinite pulse-dot}.items-center{align-items:center}.justify-center{justify-content:center}.gap-2{gap:calc(var(--spacing) * 2)}.gap-3{gap:calc(var(--spacing) * 3)}.gap-6{gap:calc(var(--spacing) * 6)}:where(.space-y-8>:not(:last-child)){--tw-space-y-reverse:0;margin-block-start:calc(calc(var(--spacing) * 8) * var(--tw-space-y-reverse));margin-block-end:calc(calc(var(--spacing) * 8) * calc(1 - var(--tw-space-y-reverse)))}.rounded-brand{border-radius:var(--radius-brand)}.rounded-brand-lg{border-radius:var(--radius-brand-lg)}.rounded-full{border-radius:3.40282e38px}.border{border-style:var(--tw-border-style);border-width:1px}.border-b{border-bottom-style:var(--tw-border-style);border-bottom-width:1px}.border-l-\[3px\]{border-left-style:var(--tw-border-style);border-left-width:3px}.border-outline{border-color:var(--color-outline)}.border-l-gold{border-left-color:var(--color-gold)}.bg-navy-surface{background-color:var(--color-navy-surface)}.bg-navy-surface-variant{background-color:var(--color-navy-surface-variant)}.bg-success{background-color:var(--color-success)}.px-4{padding-inline:calc(var(--spacing) * 4)}.px-6{padding-inline:calc(var(--spacing) * 6)}.px-8{padding-inline:calc(var(--spacing) * 8)}.py-3{padding-block:calc(var(--spacing) * 3)}.py-5{padding-block:calc(var(--spacing) * 5)}.py-8{padding-block:calc(var(--spacing) * 8)}.py-16{padding-block:calc(var(--spacing) * 16)}.text-center{text-align:center}.font-mono{font-family:var(--font-mono)}.text-2xl{font-size:var(--text-2xl);line-height:var(--tw-leading,var(--text-2xl--line-height))}.text-base{font-size:var(--text-base);line-height:var(--tw-leading,var(--text-base--line-height))}.text-sm{font-size:var(--text-sm);line-height:var(--tw-leading,var(--text-sm--line-height))}.text-xl{font-size:var(--text-xl);line-height:var(--tw-leading,var(--text-xl--line-height))}.text-xs{font-size:var(--text-xs);line-height:var(--tw-leading,var(--text-xs--line-height))}.leading-none{--tw-leading:1;line-height:1}.leading-relaxed{--tw-leading:var(--leading-relaxed);line-height:var(--leading-relaxed)}.font-light{--tw-font-weight:var(--font-weight-light);font-weight:var(--font-weight-light)}.font-medium{--tw-font-weight:var(--font-weight-medium);font-weight:var(--font-weight-medium)}.font-semibold{--tw-font-weight:var(--font-weight-semibold);font-weight:var(--font-weight-semibold)}.tracking-widest{--tw-tracking:var(--tracking-widest);letter-spacing:var(--tracking-widest)}.break-all{word-break:break-all}.text-gold{color:var(--color-gold)}.text-on-surface{color:var(--color-on-surface)}.text-on-surface-muted{color:var(--color-on-surface-muted)}.text-on-surface-subtle{color:var(--color-on-surface-subtle)}.uppercase{text-transform:uppercase}.opacity-60{opacity:.6}.transition-colors{transition-property:color,background-color,border-color,outline-color,text-decoration-color,fill,stroke,--tw-gradient-from,--tw-gradient-via,--tw-gradient-to;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.transition-opacity{transition-property:opacity;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.transition-transform{transition-property:transform,translate,scale,rotate;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.duration-200{--tw-duration:.2s;transition-duration:.2s}.select-all{-webkit-user-select:all;user-select:all}.text-brand-glow{text-shadow:var(--shadow-text-glow-dark)}@media (hover:hover){.group-hover\:translate-x-0\.5:is(:where(.group):hover *){--tw-translate-x:calc(var(--spacing) * .5);translate:var(--tw-translate-x) var(--tw-translate-y)}.group-hover\:opacity-100:is(:where(.group):hover *){opacity:1}.hover\:bg-navy:hover{background-color:var(--color-navy)}.hover\:text-gold:hover{color:var(--color-gold)}.hover\:text-gold-light:hover{color:var(--color-gold-light)}.hover\:opacity-80:hover{opacity:.8}}@media (width>=40rem){.sm\:px-10{padding-inline:calc(var(--spacing) * 10)}.sm\:py-10{padding-block:calc(var(--spacing) * 10)}.sm\:text-4xl{font-size:var(--text-4xl);line-height:var(--tw-leading,var(--text-4xl--line-height))}}}html{font-family:var(--font-sans);-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}body{background-color:var(--color-navy);color:var(--color-on-surface-muted);background-image:radial-gradient(#f8fafc0a 1px,#0000 1px);background-size:24px 24px}@keyframes pulse-dot{0%,to{opacity:1;transform:scale(1)}50%{opacity:.55;transform:scale(.92)}}@property --tw-space-y-reverse{syntax:"*";inherits:false;initial-value:0}@property --tw-border-style{syntax:"*";inherits:false;initial-value:solid}@property --tw-leading{syntax:"*";inherits:false}@property --tw-font-weight{syntax:"*";inherits:false}@property --tw-tracking{syntax:"*";inherits:false}@property --tw-duration{syntax:"*";inherits:false}@property --tw-translate-x{syntax:"*";inherits:false;initial-value:0}@property --tw-translate-y{syntax:"*";inherits:false;initial-value:0}@property --tw-translate-z{syntax:"*";inherits:false;initial-value:0}
+    <style rel="stylesheet" crossorigin>/*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */
+@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){*,:before,:after,::backdrop{--tw-space-y-reverse:0;--tw-border-style:solid;--tw-leading:initial;--tw-font-weight:initial;--tw-tracking:initial;--tw-duration:initial;--tw-translate-x:0;--tw-translate-y:0;--tw-translate-z:0}}}@layer theme{:root,:host{--font-sans:"Inter", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;--font-mono:"JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;--spacing:.25rem;--container-lg:32rem;--text-xs:.75rem;--text-xs--line-height:calc(1 / .75);--text-sm:.875rem;--text-sm--line-height:calc(1.25 / .875);--text-base:1rem;--text-base--line-height:calc(1.5 / 1);--text-xl:1.25rem;--text-xl--line-height:calc(1.75 / 1.25);--text-2xl:1.5rem;--text-2xl--line-height:calc(2 / 1.5);--text-4xl:2.25rem;--text-4xl--line-height:calc(2.5 / 2.25);--font-weight-light:300;--font-weight-medium:500;--font-weight-semibold:600;--tracking-widest:.1em;--leading-relaxed:1.625;--default-transition-duration:.15s;--default-transition-timing-function:cubic-bezier(.4, 0, .2, 1);--default-font-family:var(--font-sans);--default-mono-font-family:var(--font-mono);--color-navy:#202235;--color-navy-surface:#2a2d40;--color-navy-surface-variant:#1a1c2e;--color-gold:#edb641;--color-gold-light:#ffd480;--color-on-surface:#f8fafc;--color-on-surface-muted:#cbd5e1;--color-on-surface-subtle:#94a3b8;--color-outline:#334155;--color-success:#4ade80;--radius-brand:8px;--radius-brand-lg:12px;--shadow-text-glow-dark:0 0 24px #edb64138}}@layer base{*,:after,:before,::backdrop{box-sizing:border-box;border:0 solid;margin:0;padding:0}::file-selector-button{box-sizing:border-box;border:0 solid;margin:0;padding:0}html,:host{-webkit-text-size-adjust:100%;tab-size:4;line-height:1.5;font-family:var(--default-font-family,-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji");font-feature-settings:var(--default-font-feature-settings,normal);font-variation-settings:var(--default-font-variation-settings,normal);-webkit-tap-highlight-color:transparent}hr{height:0;color:inherit;border-top-width:1px}abbr:where([title]){-webkit-text-decoration:underline dotted;text-decoration:underline dotted}h1,h2,h3,h4,h5,h6{font-size:inherit;font-weight:inherit}a{color:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;text-decoration:inherit}b,strong{font-weight:bolder}code,kbd,samp,pre{font-family:var(--default-mono-font-family,ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace);font-feature-settings:var(--default-mono-font-feature-settings,normal);font-variation-settings:var(--default-mono-font-variation-settings,normal);font-size:1em}small{font-size:80%}sub,sup{vertical-align:baseline;font-size:75%;line-height:0;position:relative}sub{bottom:-.25em}sup{top:-.5em}table{text-indent:0;border-color:inherit;border-collapse:collapse}:-moz-focusring:where(:not(iframe)){outline:auto}progress{vertical-align:baseline}summary{display:list-item}ol,ul,menu{list-style:none}img,svg,video,canvas,audio,iframe,embed,object{vertical-align:middle;display:block}img,video{max-width:100%;height:auto}button,input,select,optgroup,textarea{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;color:inherit;opacity:1;background-color:#0000;border-radius:0}::file-selector-button{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;color:inherit;opacity:1;background-color:#0000;border-radius:0}:where(select:is([multiple],[size])) optgroup{font-weight:bolder}:where(select:is([multiple],[size])) optgroup option{padding-inline-start:20px}::file-selector-button{margin-inline-end:4px}::placeholder{opacity:1}@supports (not ((-webkit-appearance:-apple-pay-button))) or (contain-intrinsic-size:1px){::placeholder{color:currentColor}@supports (color:color-mix(in lab, red, red)){::placeholder{color:color-mix(in oklab, currentcolor 50%, transparent)}}}textarea{resize:vertical}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-date-and-time-value{min-height:1lh;text-align:inherit}::-webkit-datetime-edit{display:inline-flex}::-webkit-datetime-edit-fields-wrapper{padding:0}::-webkit-datetime-edit{padding-block:0}::-webkit-datetime-edit-year-field{padding-block:0}::-webkit-datetime-edit-month-field{padding-block:0}::-webkit-datetime-edit-day-field{padding-block:0}::-webkit-datetime-edit-hour-field{padding-block:0}::-webkit-datetime-edit-minute-field{padding-block:0}::-webkit-datetime-edit-second-field{padding-block:0}::-webkit-datetime-edit-millisecond-field{padding-block:0}::-webkit-datetime-edit-meridiem-field{padding-block:0}::-webkit-calendar-picker-indicator{line-height:1}:-moz-ui-invalid{box-shadow:none}button,input:where([type=button],[type=reset],[type=submit]){appearance:button}::file-selector-button{appearance:button}::-webkit-inner-spin-button{height:auto}::-webkit-outer-spin-button{height:auto}[hidden]:where(:not([hidden=until-found])){display:none!important}}@layer components;@layer utilities{.absolute{position:absolute}.relative{position:relative}.mt-8{margin-top:calc(var(--spacing) * 8)}.mb-3{margin-bottom:calc(var(--spacing) * 3)}.mb-4{margin-bottom:calc(var(--spacing) * 4)}.mb-10{margin-bottom:calc(var(--spacing) * 10)}.mb-12{margin-bottom:calc(var(--spacing) * 12)}.ml-auto{margin-left:auto}.block{display:block}.flex{display:flex}.inline{display:inline}.inline-flex{display:inline-flex}.h-2\.5{height:calc(var(--spacing) * 2.5)}.h-3\.5{height:calc(var(--spacing) * 3.5)}.h-12{height:calc(var(--spacing) * 12)}.h-14{height:calc(var(--spacing) * 14)}.h-full{height:100%}.min-h-screen{min-height:100vh}.w-2\.5{width:calc(var(--spacing) * 2.5)}.w-3\.5{width:calc(var(--spacing) * 3.5)}.w-auto{width:auto}.w-full{width:100%}.max-w-lg{max-width:var(--container-lg)}.min-w-0{min-width:0}.flex-1{flex:1}.flex-none{flex:none}.animate-pulse-dot{animation:2s ease-in-out infinite pulse-dot}.items-center{align-items:center}.justify-center{justify-content:center}.gap-2{gap:calc(var(--spacing) * 2)}.gap-3{gap:calc(var(--spacing) * 3)}.gap-6{gap:calc(var(--spacing) * 6)}:where(.space-y-8>:not(:last-child)){--tw-space-y-reverse:0;margin-block-start:calc(calc(var(--spacing) * 8) * var(--tw-space-y-reverse));margin-block-end:calc(calc(var(--spacing) * 8) * calc(1 - var(--tw-space-y-reverse)))}.rounded-brand{border-radius:var(--radius-brand)}.rounded-brand-lg{border-radius:var(--radius-brand-lg)}.rounded-full{border-radius:3.40282e38px}.border{border-style:var(--tw-border-style);border-width:1px}.border-b{border-bottom-style:var(--tw-border-style);border-bottom-width:1px}.border-l-\[3px\]{border-left-style:var(--tw-border-style);border-left-width:3px}.border-outline{border-color:var(--color-outline)}.border-l-gold{border-left-color:var(--color-gold)}.bg-navy-surface{background-color:var(--color-navy-surface)}.bg-navy-surface-variant{background-color:var(--color-navy-surface-variant)}.bg-success{background-color:var(--color-success)}.px-4{padding-inline:calc(var(--spacing) * 4)}.px-6{padding-inline:calc(var(--spacing) * 6)}.px-8{padding-inline:calc(var(--spacing) * 8)}.py-3{padding-block:calc(var(--spacing) * 3)}.py-5{padding-block:calc(var(--spacing) * 5)}.py-8{padding-block:calc(var(--spacing) * 8)}.py-16{padding-block:calc(var(--spacing) * 16)}.text-center{text-align:center}.font-mono{font-family:var(--font-mono)}.text-2xl{font-size:var(--text-2xl);line-height:var(--tw-leading,var(--text-2xl--line-height))}.text-base{font-size:var(--text-base);line-height:var(--tw-leading,var(--text-base--line-height))}.text-sm{font-size:var(--text-sm);line-height:var(--tw-leading,var(--text-sm--line-height))}.text-xl{font-size:var(--text-xl);line-height:var(--tw-leading,var(--text-xl--line-height))}.text-xs{font-size:var(--text-xs);line-height:var(--tw-leading,var(--text-xs--line-height))}.leading-none{--tw-leading:1;line-height:1}.leading-relaxed{--tw-leading:var(--leading-relaxed);line-height:var(--leading-relaxed)}.font-light{--tw-font-weight:var(--font-weight-light);font-weight:var(--font-weight-light)}.font-medium{--tw-font-weight:var(--font-weight-medium);font-weight:var(--font-weight-medium)}.font-semibold{--tw-font-weight:var(--font-weight-semibold);font-weight:var(--font-weight-semibold)}.tracking-widest{--tw-tracking:var(--tracking-widest);letter-spacing:var(--tracking-widest)}.break-all{word-break:break-all}.text-gold{color:var(--color-gold)}.text-on-surface{color:var(--color-on-surface)}.text-on-surface-muted{color:var(--color-on-surface-muted)}.text-on-surface-subtle{color:var(--color-on-surface-subtle)}.uppercase{text-transform:uppercase}.opacity-60{opacity:.6}.transition-colors{transition-property:color,background-color,border-color,outline-color,text-decoration-color,fill,stroke,--tw-gradient-from,--tw-gradient-via,--tw-gradient-to;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.transition-opacity{transition-property:opacity;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.transition-transform{transition-property:transform,translate,scale,rotate;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.duration-200{--tw-duration:.2s;transition-duration:.2s}.select-all{-webkit-user-select:all;user-select:all}.text-brand-glow{text-shadow:var(--shadow-text-glow-dark)}@media (hover:hover){.group-hover\:translate-x-0\.5:is(:where(.group):hover *){--tw-translate-x:calc(var(--spacing) * .5);translate:var(--tw-translate-x) var(--tw-translate-y)}.group-hover\:opacity-100:is(:where(.group):hover *){opacity:1}.hover\:bg-navy:hover{background-color:var(--color-navy)}.hover\:text-gold:hover{color:var(--color-gold)}.hover\:text-gold-light:hover{color:var(--color-gold-light)}.hover\:opacity-80:hover{opacity:.8}}@media (width>=40rem){.sm\:px-10{padding-inline:calc(var(--spacing) * 10)}.sm\:py-10{padding-block:calc(var(--spacing) * 10)}.sm\:text-4xl{font-size:var(--text-4xl);line-height:var(--tw-leading,var(--text-4xl--line-height))}}}html{font-family:var(--font-sans);-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}body{background-color:var(--color-navy);color:var(--color-on-surface-muted);background-image:radial-gradient(#f8fafc0a 1px,#0000 1px);background-size:24px 24px}@keyframes pulse-dot{0%,to{opacity:1;transform:scale(1)}50%{opacity:.55;transform:scale(.92)}}@property --tw-space-y-reverse{syntax:"*";inherits:false;initial-value:0}@property --tw-border-style{syntax:"*";inherits:false;initial-value:solid}@property --tw-leading{syntax:"*";inherits:false}@property --tw-font-weight{syntax:"*";inherits:false}@property --tw-tracking{syntax:"*";inherits:false}@property --tw-duration{syntax:"*";inherits:false}@property --tw-translate-x{syntax:"*";inherits:false;initial-value:0}@property --tw-translate-y{syntax:"*";inherits:false;initial-value:0}@property --tw-translate-z{syntax:"*";inherits:false;initial-value:0}
 /*$vite$:1*/</style>
   </head>
   <body class="flex min-h-screen items-center justify-center px-6 py-16">

package/dist/js/helpers/channels.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Browser helper for WebSocket routes generated by Litestar's ChannelsPlugin.
+ *
+ * @example
+ * ```ts
+ * import { createChannelsStream } from "litestar-vite-plugin/helpers"
+ *
+ * const stream = createChannelsStream({
+ *   basePath: "/ws",
+ *   channel: "notifications",
+ *   onEvent: (event) => console.log(event),
+ * })
+ * stream.connect()
+ * ```
+ *
+ * @module
+ */
+import { type EventStream, type EventStreamConfig } from "./stream.js";
+export type ChannelName = string | (() => string);
+export interface ChannelsStreamOptions<TFrame = unknown> extends Omit<EventStreamConfig<TFrame>, "EventSourceCtor" | "sseEvents" | "transport"> {
+    channel: ChannelName;
+    basePath?: string;
+    transformUrl?: (url: URL) => string | URL;
+}
+/**
+ * Create a stream for a WebSocket route generated by ChannelsPlugin.
+ *
+ * @param options - Channel name, server route prefix, and stream callbacks.
+ * @returns A disposable stream that connects only when `connect()` is called.
+ */
+export declare function createChannelsStream<TFrame = unknown>(options: ChannelsStreamOptions<TFrame>): EventStream;

package/dist/js/helpers/channels.js

@@ -0,0 +1,37 @@
+/**
+ * Browser helper for WebSocket routes generated by Litestar's ChannelsPlugin.
+ *
+ * @example
+ * ```ts
+ * import { createChannelsStream } from "litestar-vite-plugin/helpers"
+ *
+ * const stream = createChannelsStream({
+ *   basePath: "/ws",
+ *   channel: "notifications",
+ *   onEvent: (event) => console.log(event),
+ * })
+ * stream.connect()
+ * ```
+ *
+ * @module
+ */
+import { createEventStream, resolveStreamUrl } from "./stream.js";
+/**
+ * Create a stream for a WebSocket route generated by ChannelsPlugin.
+ *
+ * @param options - Channel name, server route prefix, and stream callbacks.
+ * @returns A disposable stream that connects only when `connect()` is called.
+ */
+export function createChannelsStream(options) {
+    const { basePath = "/", channel, transformUrl, ...streamOptions } = options;
+    return createEventStream({
+        ...streamOptions,
+        buildUrl: () => {
+            const channelName = typeof channel === "function" ? channel() : channel;
+            const prefix = basePath.endsWith("/") ? basePath : `${basePath}/`;
+            const url = new URL(resolveStreamUrl(`${prefix}${encodeURIComponent(channelName)}`, "websocket"));
+            return transformUrl?.(url) ?? url;
+        },
+        transport: "websocket",
+    });
+}

package/dist/js/helpers/index.d.ts

@@ -39,5 +39,9 @@
  * @module
  */
 export { csrfFetch, csrfHeaders, getCsrfToken } from "./csrf.js";
+export { createChannelsStream, type ChannelName, type ChannelsStreamOptions } from "./channels.js";
 export { addDirective, registerHtmxExtension, setDebug as setHtmxDebug, swapJson } from "./htmx.js";
+export { createQueueEventStream, QUEUE_SSE_EVENTS, type QueueEventStreamOptions, type QueueStreamTarget, type QueueStreamValue } from "./queues.js";
 export { createRouteHelpers, currentRoute, isCurrentRoute, isRoute, type RouteDefinition, type RouteDefinitions, type RouteHelpers, toRoute } from "./routes.js";
+export { createEventStream, type EventStream, type EventStreamOptions, type StreamGap } from "./stream.js";
+export { defineStreamElement, LitestarStreamElement, type StreamElementOptions } from "./stream-element.js";

package/dist/js/helpers/index.js

@@ -40,7 +40,15 @@
  */
 // CSRF utilities
 export { csrfFetch, csrfHeaders, getCsrfToken } from "./csrf.js";
+// Litestar Channels utilities
+export { createChannelsStream } from "./channels.js";
 // HTMX utilities
 export { addDirective, registerHtmxExtension, setDebug as setHtmxDebug, swapJson } from "./htmx.js";
+// Litestar Queues utilities
+export { createQueueEventStream, QUEUE_SSE_EVENTS } from "./queues.js";
 // Route matching utilities
 export { createRouteHelpers, currentRoute, isCurrentRoute, isRoute, toRoute } from "./routes.js";
+// Realtime stream utilities
+export { createEventStream } from "./stream.js";
+// Declarative realtime stream element
+export { defineStreamElement, LitestarStreamElement } from "./stream-element.js";

package/dist/js/helpers/queues.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Browser helper for routes generated by Litestar Queues EventStreamConfig.
+ *
+ * @example
+ * ```ts
+ * import { createQueueEventStream } from "litestar-vite-plugin/helpers"
+ *
+ * const stream = createQueueEventStream({
+ *   scope: "task",
+ *   taskId: "01J...",
+ *   onEvent: (event) => console.log(event),
+ * })
+ * stream.connect()
+ * ```
+ *
+ * @module
+ */
+import { type EventStream, type EventStreamConfig, type StreamUrl } from "./stream.js";
+export declare const QUEUE_SSE_EVENTS: readonly ["task.started", "task.progress", "task.log", "task.event", "task.completed", "task.failed", "task.cancelled", "task.claim_lost", "task.stale_failed", "worker.heartbeat", "worker.stale_recovery"];
+export type QueueStreamValue = string | (() => string);
+export type QueueStreamTarget = {
+    scope: "task";
+    taskId: QueueStreamValue;
+} | {
+    scope: "queue";
+    queue: QueueStreamValue;
+} | {
+    scope: "worker";
+    workerId: QueueStreamValue;
+} | {
+    scope: "global";
+} | {
+    scope: "custom";
+    scopeKey: QueueStreamValue;
+};
+type QueueRouteStreamOptions = QueueStreamTarget & {
+    url?: never;
+    buildUrl?: never;
+    basePath?: string;
+};
+type QueueDirectStreamOptions = {
+    url: StreamUrl;
+    buildUrl?: never;
+    basePath?: never;
+} | {
+    url?: never;
+    buildUrl: () => string | URL;
+    basePath?: never;
+};
+export type QueueEventStreamOptions<TFrame = unknown> = EventStreamConfig<TFrame> & (QueueRouteStreamOptions | QueueDirectStreamOptions) & {
+    basePath?: string;
+    transformUrl?: (url: URL) => string | URL;
+};
+/**
+ * Create a stream for routes generated by QueuePlugin EventStreamConfig.
+ *
+ * @param options - Queue target, transport, and stream callbacks.
+ * @returns A disposable stream that connects only when `connect()` is called.
+ */
+export declare function createQueueEventStream<TFrame = unknown>(options: QueueEventStreamOptions<TFrame>): EventStream;
+export {};

package/dist/js/helpers/queues.js

@@ -0,0 +1,117 @@
+/**
+ * Browser helper for routes generated by Litestar Queues EventStreamConfig.
+ *
+ * @example
+ * ```ts
+ * import { createQueueEventStream } from "litestar-vite-plugin/helpers"
+ *
+ * const stream = createQueueEventStream({
+ *   scope: "task",
+ *   taskId: "01J...",
+ *   onEvent: (event) => console.log(event),
+ * })
+ * stream.connect()
+ * ```
+ *
+ * @module
+ */
+import { createEventStream, resolveStreamUrl } from "./stream.js";
+export const QUEUE_SSE_EVENTS = [
+    "task.started",
+    "task.progress",
+    "task.log",
+    "task.event",
+    "task.completed",
+    "task.failed",
+    "task.cancelled",
+    "task.claim_lost",
+    "task.stale_failed",
+    "worker.heartbeat",
+    "worker.stale_recovery",
+];
+function asRecord(value) {
+    return typeof value === "object" && value !== null ? value : undefined;
+}
+function defaultQueueIsHeartbeat(frame) {
+    return asRecord(frame)?.type === "ping";
+}
+function defaultQueueGetEventKey(frame) {
+    const record = asRecord(frame);
+    const key = record?.eventKey ?? record?.id;
+    return typeof key === "string" ? key : undefined;
+}
+function defaultQueueGetSequence(frame) {
+    const record = asRecord(frame);
+    const sequence = record?.sequence;
+    const taskId = record?.taskId;
+    const attempt = record?.attempt;
+    if (typeof sequence !== "number" || !Number.isFinite(sequence) || typeof taskId !== "string" || (typeof attempt !== "string" && typeof attempt !== "number")) {
+        return undefined;
+    }
+    return { stream: `${taskId}:${attempt}`, value: sequence };
+}
+function resolveValue(value) {
+    return typeof value === "function" ? value() : value;
+}
+function queueRouteSuffix(target) {
+    switch (target.scope) {
+        case "task":
+            return `tasks/${encodeURIComponent(resolveValue(target.taskId))}`;
+        case "queue":
+            return `queues/${encodeURIComponent(resolveValue(target.queue))}`;
+        case "worker":
+            return `workers/${encodeURIComponent(resolveValue(target.workerId))}`;
+        case "global":
+            return "global";
+        case "custom":
+            return `custom/${encodeURIComponent(resolveValue(target.scopeKey))}`;
+    }
+}
+function queueStreamUrl(target, basePath, transport) {
+    const root = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+    const transportPath = transport === "sse" ? "sse/" : "";
+    return new URL(resolveStreamUrl(`${root}/${transportPath}${queueRouteSuffix(target)}`, transport));
+}
+/**
+ * Create a stream for routes generated by QueuePlugin EventStreamConfig.
+ *
+ * @param options - Queue target, transport, and stream callbacks.
+ * @returns A disposable stream that connects only when `connect()` is called.
+ */
+export function createQueueEventStream(options) {
+    const { baseDelayMs, basePath = "/queues/events", dedupWindow, EventSourceCtor, getEventKey = defaultQueueGetEventKey, getSequence = defaultQueueGetSequence, isHeartbeat = defaultQueueIsHeartbeat, maxDelayMs, onEvent, onClose, onGap, onHealthChange, onOpen, onReconnect, parseFrame, shouldReconnect, sseEvents = QUEUE_SSE_EVENTS, transformUrl, transport = "websocket", WebSocketCtor, } = options;
+    return createEventStream({
+        baseDelayMs,
+        buildUrl: () => {
+            let endpoint;
+            if ("buildUrl" in options && options.buildUrl !== undefined) {
+                endpoint = options.buildUrl();
+            }
+            else if ("url" in options && options.url !== undefined) {
+                endpoint = typeof options.url === "function" ? options.url() : options.url;
+            }
+            else {
+                endpoint = queueStreamUrl(options, basePath, transport);
+            }
+            const url = new URL(resolveStreamUrl(endpoint, transport));
+            return transformUrl?.(url) ?? url;
+        },
+        dedupWindow,
+        EventSourceCtor,
+        getEventKey,
+        getSequence,
+        isHeartbeat,
+        maxDelayMs,
+        onEvent,
+        onClose,
+        onGap,
+        onHealthChange,
+        onOpen,
+        onReconnect,
+        parseFrame,
+        shouldReconnect,
+        sseEvents,
+        transport,
+        WebSocketCtor,
+    });
+}

package/dist/js/helpers/stream-element.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Declarative lifecycle binding for JSON WebSocket and SSE streams.
+ *
+ * This element replaces `htmx-ext-ws` and `htmx-ext-sse` for JSON streams.
+ * Do not layer both reconnect implementations on the same endpoint.
+ *
+ * @example
+ * ```html
+ * <litestar-stream url="/events" transport="sse" swap="json">
+ *   <template ls-for="item in $data.items"><p>${item}</p></template>
+ * </litestar-stream>
+ * ```
+ *
+ * @module
+ */
+import { type EventStreamConfig } from "./stream.js";
+type StreamCallbackConfig = Pick<EventStreamConfig, "EventSourceCtor" | "WebSocketCtor" | "getEventKey" | "getSequence" | "isHeartbeat" | "onEvent" | "onGap" | "onHealthChange" | "onReconnect" | "parseFrame" | "shouldReconnect">;
+type HTMLElementConstructor = new (...args: never[]) => HTMLElement;
+declare const HTMLElementBase: HTMLElementConstructor;
+export interface StreamElementOptions {
+    tagName?: string;
+}
+export declare class LitestarStreamElement extends HTMLElementBase {
+    static readonly observedAttributes: string[];
+    private stream;
+    private _buildUrl;
+    private _onEvent;
+    private _onGap;
+    private _onHealthChange;
+    private _onReconnect;
+    private _shouldReconnect;
+    private _isHeartbeat;
+    private _getEventKey;
+    private _getSequence;
+    private _parseFrame;
+    private _WebSocketCtor;
+    private _EventSourceCtor;
+    constructor();
+    get buildUrl(): (() => string | URL) | undefined;
+    set buildUrl(value: (() => string | URL) | undefined);
+    get onEvent(): StreamCallbackConfig["onEvent"] | undefined;
+    set onEvent(value: StreamCallbackConfig["onEvent"] | undefined);
+    get onGap(): StreamCallbackConfig["onGap"];
+    set onGap(value: StreamCallbackConfig["onGap"]);
+    get onHealthChange(): StreamCallbackConfig["onHealthChange"];
+    set onHealthChange(value: StreamCallbackConfig["onHealthChange"]);
+    get onReconnect(): StreamCallbackConfig["onReconnect"];
+    set onReconnect(value: StreamCallbackConfig["onReconnect"]);
+    get shouldReconnect(): StreamCallbackConfig["shouldReconnect"];
+    set shouldReconnect(value: StreamCallbackConfig["shouldReconnect"]);
+    get isHeartbeat(): StreamCallbackConfig["isHeartbeat"];
+    set isHeartbeat(value: StreamCallbackConfig["isHeartbeat"]);
+    get getEventKey(): StreamCallbackConfig["getEventKey"];
+    set getEventKey(value: StreamCallbackConfig["getEventKey"]);
+    get getSequence(): StreamCallbackConfig["getSequence"];
+    set getSequence(value: StreamCallbackConfig["getSequence"]);
+    get parseFrame(): StreamCallbackConfig["parseFrame"];
+    set parseFrame(value: StreamCallbackConfig["parseFrame"]);
+    get WebSocketCtor(): StreamCallbackConfig["WebSocketCtor"];
+    set WebSocketCtor(value: StreamCallbackConfig["WebSocketCtor"]);
+    get EventSourceCtor(): StreamCallbackConfig["EventSourceCtor"];
+    set EventSourceCtor(value: StreamCallbackConfig["EventSourceCtor"]);
+    get healthy(): boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    private upgradeProperty;
+    private start;
+    private stop;
+    private restart;
+    private dispatchStreamEvent;
+}
+/**
+ * Register the declarative stream element.
+ *
+ * @param options - Optional custom tag name.
+ */
+export declare function defineStreamElement(options?: StreamElementOptions): void;
+export {};