litestar-vite-plugin 0.27.0 → 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/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 {};

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

@@ -0,0 +1,229 @@
+/**
+ * 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 { swapJson } from "./htmx.js";
+import { createQueueEventStream } from "./queues.js";
+import { createEventStream } from "./stream.js";
+const HTMLElementBase = (typeof HTMLElement === "undefined" ? class {
+} : HTMLElement);
+export class LitestarStreamElement extends HTMLElementBase {
+    static observedAttributes = ["url", "transport", "sse-events", "preset", "swap", "disabled"];
+    stream = null;
+    _buildUrl;
+    _onEvent;
+    _onGap;
+    _onHealthChange;
+    _onReconnect;
+    _shouldReconnect;
+    _isHeartbeat;
+    _getEventKey;
+    _getSequence;
+    _parseFrame;
+    _WebSocketCtor;
+    _EventSourceCtor;
+    constructor() {
+        super();
+        for (const property of [
+            "buildUrl",
+            "onEvent",
+            "onGap",
+            "onHealthChange",
+            "onReconnect",
+            "shouldReconnect",
+            "isHeartbeat",
+            "getEventKey",
+            "getSequence",
+            "parseFrame",
+            "WebSocketCtor",
+            "EventSourceCtor",
+        ]) {
+            this.upgradeProperty(property);
+        }
+    }
+    get buildUrl() {
+        return this._buildUrl;
+    }
+    set buildUrl(value) {
+        this._buildUrl = value;
+        this.restart();
+    }
+    get onEvent() {
+        return this._onEvent;
+    }
+    set onEvent(value) {
+        this._onEvent = value;
+    }
+    get onGap() {
+        return this._onGap;
+    }
+    set onGap(value) {
+        this._onGap = value;
+    }
+    get onHealthChange() {
+        return this._onHealthChange;
+    }
+    set onHealthChange(value) {
+        this._onHealthChange = value;
+    }
+    get onReconnect() {
+        return this._onReconnect;
+    }
+    set onReconnect(value) {
+        this._onReconnect = value;
+    }
+    get shouldReconnect() {
+        return this._shouldReconnect;
+    }
+    set shouldReconnect(value) {
+        this._shouldReconnect = value;
+    }
+    get isHeartbeat() {
+        return this._isHeartbeat;
+    }
+    set isHeartbeat(value) {
+        this._isHeartbeat = value;
+    }
+    get getEventKey() {
+        return this._getEventKey;
+    }
+    set getEventKey(value) {
+        this._getEventKey = value;
+    }
+    get getSequence() {
+        return this._getSequence;
+    }
+    set getSequence(value) {
+        this._getSequence = value;
+    }
+    get parseFrame() {
+        return this._parseFrame;
+    }
+    set parseFrame(value) {
+        this._parseFrame = value;
+    }
+    get WebSocketCtor() {
+        return this._WebSocketCtor;
+    }
+    set WebSocketCtor(value) {
+        this._WebSocketCtor = value;
+    }
+    get EventSourceCtor() {
+        return this._EventSourceCtor;
+    }
+    set EventSourceCtor(value) {
+        this._EventSourceCtor = value;
+    }
+    get healthy() {
+        return this.stream?.healthy ?? false;
+    }
+    connectedCallback() {
+        this.start();
+    }
+    disconnectedCallback() {
+        this.stop();
+    }
+    attributeChangedCallback(name, oldValue, newValue) {
+        if (oldValue === newValue || name === "swap") {
+            return;
+        }
+        this.restart();
+    }
+    upgradeProperty(property) {
+        if (!Object.prototype.hasOwnProperty.call(this, property)) {
+            return;
+        }
+        const value = this[property];
+        delete this[property];
+        this[property] = value;
+    }
+    start() {
+        if (!this.isConnected || this.hasAttribute("disabled") || this.stream !== null) {
+            return;
+        }
+        const url = this.getAttribute("url");
+        if (this._buildUrl === undefined && url === null) {
+            return;
+        }
+        const transport = this.getAttribute("transport") === "sse" ? "sse" : "websocket";
+        const sseEvents = this.getAttribute("sse-events")
+            ?.split(",")
+            .map((event) => event.trim())
+            .filter(Boolean);
+        const config = {
+            EventSourceCtor: this._EventSourceCtor,
+            WebSocketCtor: this._WebSocketCtor,
+            getEventKey: this._getEventKey,
+            getSequence: this._getSequence,
+            isHeartbeat: this._isHeartbeat,
+            onClose: () => this.dispatchStreamEvent("litestar:stream-close", {}),
+            onEvent: (frame) => {
+                this._onEvent?.(frame);
+                this.dispatchStreamEvent("litestar:stream-event", frame);
+                if (this.getAttribute("swap") === "json") {
+                    swapJson(this, frame);
+                }
+            },
+            onGap: (gap) => {
+                this._onGap?.(gap);
+                this.dispatchStreamEvent("litestar:stream-gap", gap);
+            },
+            onHealthChange: (healthy) => {
+                this._onHealthChange?.(healthy);
+                this.dispatchStreamEvent("litestar:stream-health", { healthy });
+            },
+            onOpen: (resolvedUrl) => this.dispatchStreamEvent("litestar:stream-open", { url: resolvedUrl }),
+            onReconnect: () => this._onReconnect?.(),
+            parseFrame: this._parseFrame,
+            shouldReconnect: this._shouldReconnect,
+            sseEvents,
+            transport: transport,
+        };
+        const endpoint = this._buildUrl === undefined ? { url: url } : { buildUrl: this._buildUrl };
+        this.stream = this.getAttribute("preset") === "queues" ? createQueueEventStream({ ...config, ...endpoint }) : createEventStream({ ...config, ...endpoint });
+        this.stream.connect();
+    }
+    stop() {
+        const stream = this.stream;
+        this.stream = null;
+        stream?.dispose();
+    }
+    restart() {
+        if (!this.isConnected) {
+            return;
+        }
+        this.stop();
+        this.start();
+    }
+    dispatchStreamEvent(type, detail) {
+        this.dispatchEvent(new CustomEvent(type, { bubbles: true, composed: false, detail }));
+    }
+}
+/**
+ * Register the declarative stream element.
+ *
+ * @param options - Optional custom tag name.
+ */
+export function defineStreamElement(options = {}) {
+    if (typeof window === "undefined" || typeof customElements === "undefined") {
+        return;
+    }
+    const tagName = options.tagName ?? "litestar-stream";
+    if (customElements.get(tagName) !== undefined) {
+        return;
+    }
+    const ElementClass = tagName === "litestar-stream" ? LitestarStreamElement : class extends LitestarStreamElement {
+    };
+    customElements.define(tagName, ElementClass);
+}