@jk2908/solas 0.3.1 → 0.3.3

package/dist/internal/browser-router/router.d.ts

@@ -0,0 +1,184 @@
+import type { RscPayload } from '../env/rsc.js';
+import { Solas } from '../../solas.js';
+export declare namespace BrowserRouter {
+    export type Params = Record<string, string>;
+    export type Query = Record<string, string | number | boolean>;
+    export type Path = keyof Solas.Routes & string;
+    type Replace = {
+        replace?: boolean;
+    };
+    export type GoOptions = {
+        replace?: boolean;
+        query?: Query;
+        params?: Params;
+    };
+    /**
+     * These targets are used as-is. They are not matched against the route table,
+     * so this covers normal external URLs and hash-only links
+     */
+    export type ExternalTarget = `${string}:${string}` | `//${string}` | `#${string}`;
+    export function isHashOnlyTarget(target: string): boolean;
+    export function isExternalTarget(target: string, origin: string): boolean;
+    /**
+     * Turn a route pattern into the real path shape a caller can use. In practice,
+     * every ':param' or '*' part becomes a plain string slot
+     *
+     * @example
+     * ```ts
+     * // '/p/:id' becomes '/p/${string}'
+     * // '/test/*' becomes '/test/${string}'
+     * // '/posts' stays '/posts'
+     * ```
+     *
+     * @example
+     * ```ts
+     * type A = ResolvedPath<'/posts/:id'>
+     * // '/posts/${string}'
+     * ```
+     *
+     * @example
+     * ```ts
+     * type B = ResolvedPath<'/docs/*'>
+     * // '/docs/${string}'
+     * ```
+     */
+    export type ResolvedPath<TPath extends string> = TPath extends `${infer Start}:${string}/${infer Rest}` ? `${Start}${string}/${ResolvedPath<Rest>}` : TPath extends `${infer Start}:${string}` ? `${Start}${string}` : TPath extends `${infer Start}*${infer Rest}` ? `${Start}${string}${ResolvedPath<Rest>}` : TPath;
+    /**
+     * Once we have a real path, also allow the usual query-string and hash forms
+     *
+     * @example
+     * ```ts
+     * type A = TargetSuffix<'/posts/123'>
+     * // '/posts/123' | '/posts/123?${string}' | '/posts/123#${string}' | '/posts/123?${string}#${string}'
+     * ```
+     */
+    export type TargetSuffix<TPath extends string> = TPath | `${TPath}?${string}` | `${TPath}#${string}` | `${TPath}?${string}#${string}`;
+    /**
+     * This is the final string form a caller can navigate to. It can be an external
+     * URL, or a concrete URL that matches one of the  known routes
+     *
+     * @example
+     * ```ts
+     * type A = Target
+     * // 'https://example.com'
+     * // '#intro'
+     * // '/posts/123'
+     * // '/posts/123?draft=true'
+     * ```
+     */
+    export type Target = ExternalTarget | TargetSuffix<ResolvedPath<Path>>;
+    /**
+     * Extra options for callers who already have a finished target string
+     *
+     * @example
+     * ```ts
+     * const a: TargetConfig = { query: { page: 2 } }
+     * // params is rejected here because the path is already complete
+     * ```
+     */
+    type TargetConfig = {
+        params?: never;
+        query?: Query;
+    };
+    /**
+     * Extra options for callers who pass a route pattern and params separately.
+     * If the route definition says that route needs params, this type makes
+     * those params required. If the route has no params, it rejects them
+     *
+     * @example
+     * ```ts
+     * // if Solas.Routes['/posts/:id'] is { params: { id: string } }
+     * type A = PatternConfig<'/posts/:id'>
+     * // { query?: Query } & { params: { id: string } }
+     * ```
+     *
+     * @example
+     * ```ts
+     * // if Solas.Routes['/about'] has no params field
+     * type B = PatternConfig<'/about'>
+     * // { query?: Query } & { params?: never }
+     * ```
+     */
+    type PatternConfig<TPath extends Path> = {
+        query?: Query;
+    } & (Solas.Routes[TPath] extends {
+        params: infer TParams extends Params;
+    } ? {
+        params: TParams;
+    } : {
+        params?: never;
+    });
+    /**
+     * Typed <Link /> props, using `href` instead of the internal `to` name
+     *
+     * `query` is always allowed
+     * `params` are only allowed when `href` is a known route pattern
+     *
+     * @example
+     * ```ts
+     * const a: LinkProps = { href: '/posts/:id', params: { id: '123' } }
+     * const b: LinkProps = { href: '/posts/123?draft=true' }
+     * ```
+     */
+    export type LinkProps = ({
+        href: Target;
+    } & TargetConfig) | (keyof Solas.Routes extends never ? never : {
+        [TPath in Path]: {
+            href: TPath;
+        } & PatternConfig<TPath>;
+    }[Path]);
+    /**
+     * Typed input for router.go(), using the same route rules as <Link />
+     *
+     * @example
+     * ```ts
+     * go('/p/post-2')
+     * go('/?foo=bar', { replace: true })
+     * ```
+     *
+     * @example
+     * ```ts
+     * go('/p/:id', { params: { id: 'post-2' }, replace: true })
+     * ```
+     *
+     * The last overload is the fallback for plain `string` values. The
+     * `string extends TTo` check stops that fallback from taking over
+     * when TypeScript already knows the caller passed a more specific
+     * string literal
+     *
+     * @example
+     * ```ts
+     * declare const dynamicPath: string
+     * go(dynamicPath, { replace: true })
+     * ```
+     */
+    export type Go = {
+        <TTo extends Path>(to: TTo, opts?: PatternConfig<TTo> & Replace): Promise<string>;
+        <TTo extends Target>(to: TTo, opts?: TargetConfig & Replace): Promise<string>;
+        <TTo extends string>(to: string extends TTo ? TTo : never, opts?: GoOptions): Promise<string>;
+    };
+    /**
+     * Convert a route pattern and params into a real path string. This is used internally
+     * to implement <Link /> and router.go
+     */
+    export function toTarget(path: string, params?: Record<string, string>, query?: BrowserRouter.Query): string;
+    export {};
+}
+export declare const BrowserRouterContext: import("react").Context<{
+    go: BrowserRouter.Go;
+    prefetch: (path: string) => void;
+    isNavigating: boolean;
+    url: {
+        pathname?: string | undefined;
+        search?: string | undefined;
+    };
+}>;
+export declare function BrowserRouterProvider({ children, setPayload, isNavigating, url }: {
+    children: React.ReactNode;
+    setPayload?: (payload: RscPayload) => void;
+    isNavigating?: boolean;
+    url?: {
+        pathname?: string;
+        search?: string;
+    };
+}): import("react/jsx-runtime").JSX.Element;

package/dist/internal/{router/router-provider.js → browser-router/router.js}

@@ -1,17 +1,85 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { createContext, useCallback, useEffect, useMemo, useRef } from 'react';
 import { createFromFetch } from '@vitejs/plugin-rsc/browser';
 import { Logger } from '../../utils/logger.js';
 import { Solas } from '../../solas.js';
-import { Prefetcher } from './prefetcher.js';
-import { RouterContext } from './router-context.js';
+import { Prefetcher } from './../prefetcher.js';
+export { BrowserRouter };
+var BrowserRouter;
+(function (BrowserRouter) {
+    function isHashOnlyTarget(target) {
+        return target.startsWith('#');
+    }
+    BrowserRouter.isHashOnlyTarget = isHashOnlyTarget;
+    function isExternalTarget(target, origin) {
+        if (isHashOnlyTarget(target))
+            return false;
+        try {
+            return new URL(target, origin).origin !== origin;
+        }
+        catch {
+            return false;
+        }
+    }
+    BrowserRouter.isExternalTarget = isExternalTarget;
+    /**
+     * Convert a route pattern and params into a real path string. This is used internally
+     * to implement <Link /> and router.go
+     */
+    function toTarget(path, params, query) {
+        // keep track of which params were consumed by named `:param` slots
+        const used = new Set();
+        // replace each named route param with its URL-encoded value
+        let to = path.replaceAll(/:([A-Za-z0-9_]+)/g, (_, key) => {
+            const value = params?.[key];
+            if (value == null) {
+                throw new Error(`[Link]: missing route param: ${key}`);
+            }
+            used.add(key);
+            return encodeURIComponent(value);
+        });
+        if (to.includes('*')) {
+            // wildcard routes use the one param that was not already matched by a named slot
+            const remaining = Object.entries(params ?? {}).filter(([key]) => !used.has(key));
+            if (remaining.length !== 1) {
+                throw new Error('[Link]: wildcard routes require exactly one unmatched param');
+            }
+            // encode each path segment separately so embedded '/' still acts like a path separator
+            to = to.replace('*', remaining[0][1].split('/').map(encodeURIComponent).join('/'));
+        }
+        if (!query)
+            return to;
+        // split the URL up so new query params can be merged without losing an existing hash
+        const hashIndex = to.indexOf('#');
+        const hash = hashIndex >= 0 ? to.slice(hashIndex) : '';
+        const pathWithSearch = hashIndex >= 0 ? to.slice(0, hashIndex) : to;
+        const searchIndex = pathWithSearch.indexOf('?');
+        const pathname = searchIndex >= 0 ? pathWithSearch.slice(0, searchIndex) : pathWithSearch;
+        const currentSearch = searchIndex >= 0 ? pathWithSearch.slice(searchIndex + 1) : '';
+        const search = new URLSearchParams(currentSearch);
+        // later values win, so passed query props overwrite any existing query string values
+        for (const [key, value] of Object.entries(query)) {
+            search.set(key, String(value));
+        }
+        const value = search.toString();
+        // rebuild the URL in the same order: pathname, optional query string, then hash
+        return `${pathname}${value.length > 0 ? `?${value}` : ''}${hash}`;
+    }
+    BrowserRouter.toTarget = toTarget;
+})(BrowserRouter || (BrowserRouter = {}));
+export const BrowserRouterContext = createContext({
+    go: async () => '',
+    prefetch: () => { },
+    isNavigating: false,
+    url: {},
+});
 const DEFAULT_GO_CONFIG = {
     replace: false,
 };
 const logger = new Logger();
 const prefetcher = new Prefetcher();
-export function RouterProvider({ children, setPayload, isNavigating = false, url, }) {
+export function BrowserRouterProvider({ children, setPayload, isNavigating = false, url, }) {
     // id to track active navigations
     const id = useRef(0);
     // abort controller for in-flight navigation
@@ -35,16 +103,15 @@ export function RouterProvider({ children, setPayload, isNavigating = false, url
         // opportunistically for this navigation
         let existing = false;
         try {
-            const url = new URL(to, window.location.origin);
-            if (opts?.query) {
-                for (const [key, value] of Object.entries(opts.query)) {
-                    url.searchParams.set(key, String(value));
-                }
+            const target = BrowserRouter.toTarget(to, opts.params, opts.query);
+            if (BrowserRouter.isExternalTarget(target, window.location.origin)) {
+                throw new Error('[router.go]: external URLs are not supported. Use <a> instead');
             }
+            const url = new URL(target, window.location.origin);
             const key = Prefetcher.key(url.toString(), window.location.origin);
             if (!key)
                 throw new Error('Invalid navigation url');
-            // switch to the normalized target once the url is valid
+            // switch to the normalised target once the url is valid
             path = key;
             // if the target was already prefetched, use the cached response promise
             // and set existing to true so we don't remove it from cache
@@ -128,7 +195,9 @@ export function RouterProvider({ children, setPayload, isNavigating = false, url
         prefetcher.set(key, fetch(key, { headers: { Accept: 'text/x-component' } }));
     }, []);
     useEffect(() => {
-        const handler = () => go(window.location.href, { replace: true });
+        const handler = () => go(BrowserRouter.toTarget(window.location.pathname + window.location.search), {
+            replace: true,
+        });
         window.addEventListener('popstate', handler);
         return () => {
             controller.current?.abort();
@@ -145,5 +214,5 @@ export function RouterProvider({ children, setPayload, isNavigating = false, url
             search: url?.search,
         },
     }), [go, prefetch, isNavigating, url]);
-    return _jsx(RouterContext, { value: value, children: children });
+    return _jsx(BrowserRouterContext, { value: value, children: children });
 }

package/dist/internal/{router → browser-router}/use-router.d.ts

@@ -1,5 +1,5 @@
 export declare function useRouter(): {
-    go: (to: string, opts?: import("./router-context.js").Navigation.GoOptions | undefined) => Promise<string>;
+    go: import("./router.js").BrowserRouter.Go;
     prefetch: (path: string) => void;
     isNavigating: boolean;
     url: {

package/dist/internal/browser-router/use-router.js

@@ -0,0 +1,5 @@
+import { use } from 'react';
+import { BrowserRouterContext } from './router.js';
+export function useRouter() {
+    return use(BrowserRouterContext);
+}

package/dist/internal/browser-router/use-search-params.d.ts

@@ -0,0 +1 @@
+export declare function useSearchParams(): URLSearchParams;

package/dist/internal/browser-router/use-search-params.js

@@ -0,0 +1,15 @@
+import { useMemo, useSyncExternalStore } from 'react';
+import { Solas } from '../../solas.js';
+import { useRouter } from '../browser-router/use-router.js';
+export function useSearchParams() {
+    const { url } = useRouter();
+    const search = useSyncExternalStore(fn => {
+        window.addEventListener('popstate', fn);
+        window.addEventListener(Solas.Events.names.NAVIGATION, fn);
+        return () => {
+            window.removeEventListener('popstate', fn);
+            window.removeEventListener(Solas.Events.names.NAVIGATION, fn);
+        };
+    }, () => window.location.search, () => url?.search);
+    return useMemo(() => new URLSearchParams(search), [search]);
+}

package/dist/internal/build.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { Solas } from '../solas.js';
 import { Logger } from '../utils/logger.js';
-import { normalisePathname } from './router/utils.js';
+import { Solas } from '../solas.js';
+import { normalisePathname } from './http-router/utils.js';
 import { Prerender } from './prerender.js';
 export { Build };
 /**

package/dist/internal/codegen/types.d.ts

@@ -0,0 +1,5 @@
+import { Manifest } from '../../types.js';
+/**
+ * Generates runtime types
+ */
+export declare function writeTypes(manifest: Manifest): string;

package/dist/internal/codegen/types.js

@@ -0,0 +1,48 @@
+import { Solas } from '../../solas.js';
+import { Build } from '../build.js';
+import { AUTOGEN_MSG, source } from './utils.js';
+function render(path, params) {
+    if (!params || params.length === 0) {
+        return `\t\t\t'${path}': {}`;
+    }
+    const fields = params.map(param => `\t\t\t\t\t${param}: string`).join('\n');
+    return [`\t\t\t'${path}': {`, `\t\t\t\tparams: {`, fields, `\t\t\t\t}`, `\t\t\t}`].join('\n');
+}
+/**
+ * Generates runtime types
+ */
+export function writeTypes(manifest) {
+    const routes = new Map();
+    for (const path in manifest) {
+        const route = manifest[path];
+        if (Array.isArray(route)) {
+            for (const r of route) {
+                if (r.__kind !== Build.EntryKind.PAGE)
+                    continue;
+                routes.set(r.__path, r.__params);
+            }
+        }
+        else {
+            if (route.__kind !== Build.EntryKind.PAGE)
+                continue;
+            routes.set(route.__path, route.__params);
+        }
+    }
+    const body = [...routes.entries()]
+        // sort routes by path for stable output
+        .toSorted(([a], [b]) => a.localeCompare(b))
+        .map(([path, params]) => render(path, params))
+        .join('\n');
+    return source `
+   ${AUTOGEN_MSG}
+
+	 import '${Solas.Config.PKG_NAME}'
+
+	 declare module '${Solas.Config.PKG_NAME}' {
+		export namespace Solas {
+			export interface Routes {
+				${body}
+			}
+		}
+	 }`;
+}

package/dist/internal/env/browser.js

@@ -2,18 +2,18 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { StrictMode, Suspense, useCallback, useState, useTransition } from 'react';
 import { hydrateRoot } from 'react-dom/client';
 import { createFromFetch, createFromReadableStream, createTemporaryReferenceSet, encodeReply, setServerCallback, } from '@vitejs/plugin-rsc/browser';
-import { rscStream } from 'rsc-html-stream/client';
+import { BrowserRouterProvider } from '../browser-router/router.js';
 import { RedirectBoundary } from '../navigation/redirect-boundary.js';
 import { Head } from '../render/head.js';
-import { RouterProvider } from '../router/router-provider.js';
 import { ErrorBoundary } from '../ui/error-boundary.js';
+import { rscStream } from './flight.js';
 /**
  * Browser RSC hydration entry point
  */
 export async function browser() {
-    const payload = await createFromReadableStream(rscStream, {
-        unstable_allowPartialStream: true,
-    });
+    // read the initial payload from the inline __FLIGHT_DATA pushes that were
+    // injected into the html document during ssr/prerender
+    const payload = await createFromReadableStream(rscStream);
     const payloadSetter = {
         current: () => { },
     };
@@ -28,7 +28,7 @@ export async function browser() {
         // make the latest payload updater available to action/hmr callbacks
         // immediately during render, without waiting for an effect to run
         payloadSetter.current = setPayloadInTransition;
-        return (_jsx(RedirectBoundary, { children: _jsxs(RouterProvider, { setPayload: setPayloadInTransition, isNavigating: isPending, url: p.url, children: [
+        return (_jsx(RedirectBoundary, { children: _jsxs(BrowserRouterProvider, { setPayload: setPayloadInTransition, isNavigating: isPending, url: p.url, children: [
                     _jsx(ErrorBoundary, { fallback: null, children: _jsx(Suspense, { fallback: null, children: _jsx(Head, { metadata: p.metadata }) }) }), p.root] }) }));
     }
     setServerCallback(async (id, args) => {

package/dist/internal/env/flight.d.ts

@@ -0,0 +1,29 @@
+type Chunk = string | Uint8Array;
+type Opts = {
+    nonce?: string;
+};
+declare global {
+    interface Window {
+        __FLIGHT_DATA?: Chunk[];
+    }
+}
+/**
+ * Capture only the payload rows that are already buffered in a stream.
+ * Used by ppr prerender so the cached prelude carries the static
+ * payload, while postponed work is left for request-time resume
+ */
+export declare function captureBuffered(stream: ReadableStream<Uint8Array>): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
+/**
+ * Read the inline payload rows written into the html document. Stays open
+ * for the lifetime of the document so ppr resume can keep appending rows
+ * without tripping React's connection-closed path
+ */
+export declare const rscStream: ReadableStream<Uint8Array<ArrayBufferLike>>;
+/**
+ * Inject the payload into the outgoing HTML as small inline script pushes. This keeps
+ * hydration on the first document load instead of doing a follow-up fetch. HTML still
+ * streams through, but the closing body/html tags are held back until the payload
+ * is written
+ */
+export declare function injectPayload(payload: ReadableStream<Uint8Array>, opts?: Opts): TransformStream<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>;
+export {};

package/dist/internal/env/flight.js

@@ -0,0 +1,190 @@
+const encoder = new TextEncoder();
+const HTML_TRAIL = '</body></html>';
+/**
+ * Capture only the payload rows that are already buffered in a stream.
+ * Used by ppr prerender so the cached prelude carries the static
+ * payload, while postponed work is left for request-time resume
+ */
+export async function captureBuffered(stream) {
+    const reader = stream.getReader();
+    const chunks = [];
+    try {
+        while (true) {
+            // only take what is already queued. anything still pending belongs
+            // to the later resume step, not the cached prelude
+            const result = await Promise.race([
+                reader.read(),
+                new Promise(r => setTimeout(r, 0, null)),
+            ]);
+            if (result === null || result.done)
+                break;
+            if (result.value)
+                chunks.push(result.value);
+        }
+    }
+    finally {
+        reader.cancel();
+    }
+    return new ReadableStream({
+        start(controller) {
+            for (const chunk of chunks)
+                controller.enqueue(chunk);
+            controller.close();
+        },
+    });
+}
+/**
+ * Read the inline payload rows written into the html document. Stays open
+ * for the lifetime of the document so ppr resume can keep appending rows
+ * without tripping React's connection-closed path
+ */
+export const rscStream = new ReadableStream({
+    start(controller) {
+        if (typeof window === 'undefined')
+            return;
+        // start with any rows already written into the page. Later resume
+        // work keeps adding to this same array
+        const flightData = (window.__FLIGHT_DATA ??= []);
+        // save the real array push before we replace it. We still want
+        // __FLIGHT_DATA to behave like a normal array
+        const push = flightData.push.bind(flightData);
+        // each row can be plain text or binary. normalise both into bytes
+        // before handing them to the browser-side RSC reader
+        function handle(entry) {
+            controller.enqueue(typeof entry === 'string' ? encoder.encode(entry) : entry);
+        }
+        // replay anything the page already wrote before this stream started.
+        // That lets hydration read the early rows first
+        for (const entry of flightData)
+            handle(entry);
+        // clear the array to release memory
+        window.__FLIGHT_DATA.length = 0;
+        // later inline scripts call __FLIGHT_DATA.push(...). Forward each new row
+        // into the open stream, then clear the array so old rows do not pile up
+        // in memory
+        flightData.push = (...entries) => {
+            const length = push(...entries);
+            for (const entry of entries)
+                handle(entry);
+            // once React has the row, we no longer need to keep it in the array
+            if (typeof window !== 'undefined' && window.__FLIGHT_DATA) {
+                window.__FLIGHT_DATA.length = 0;
+            }
+            // return the new length so the array behaves as expected
+            return length;
+        };
+    },
+});
+/**
+ * Inject the payload into the outgoing HTML as small inline script pushes. This keeps
+ * hydration on the first document load instead of doing a follow-up fetch. HTML still
+ * streams through, but the closing body/html tags are held back until the payload
+ * is written
+ */
+export function injectPayload(payload, opts = {}) {
+    const decoder = new TextDecoder();
+    let payloadWrite;
+    let buffered = [];
+    let timeout;
+    function flush(controller) {
+        for (const chunk of buffered) {
+            let html = decoder.decode(chunk, { stream: true });
+            // hold the final closing tags back so payload scripts land inside the document,
+            // not after it
+            if (html.endsWith(HTML_TRAIL))
+                html = html.slice(0, -HTML_TRAIL.length);
+            // write the buffered html before the payload scripts, so they are guaranteed to be
+            // parsed in the right place
+            if (html)
+                controller.enqueue(encoder.encode(html));
+        }
+        // flush any decoder state left over from split utf-8/html chunks
+        let remaining = decoder.decode();
+        // if the remaining buffered html ends with the closing tags, remove them so they
+        // can be re-appended after the payload
+        if (remaining.endsWith(HTML_TRAIL))
+            remaining = remaining.slice(0, -HTML_TRAIL.length);
+        // if there is any html left after removing the closing tags, write it before the payload
+        if (remaining)
+            controller.enqueue(encoder.encode(remaining));
+        buffered = [];
+        timeout = undefined;
+    }
+    function start(controller) {
+        // only start writing payload rows once, even if html keeps arriving
+        payloadWrite ??= writePayload(payload, controller, opts.nonce);
+        return payloadWrite;
+    }
+    return new TransformStream({
+        transform(chunk, controller) {
+            // collect html first so we can decide where the payload scripts belong
+            buffered.push(chunk);
+            if (timeout != null)
+                return;
+            // html can arrive split in awkward places, so wait one tick before flushing.
+            // That gives the next chunk a chance to join up and keeps scripts out of
+            // half a tag
+            timeout = setTimeout(() => {
+                try {
+                    // once the buffered html is safe to write, start the payload writer too
+                    flush(controller);
+                }
+                catch (err) {
+                    controller.error(err);
+                    return;
+                }
+                start(controller).catch(err => controller.error(err));
+            }, 0);
+        },
+        async flush(controller) {
+            if (timeout != null) {
+                clearTimeout(timeout);
+                flush(controller);
+            }
+            // finish every payload row before restoring the closing html tags
+            await start(controller);
+            controller.enqueue(encoder.encode(HTML_TRAIL));
+        },
+    });
+}
+/**
+ * Turn each payload row into a tiny inline script that pushes into __FLIGHT_DATA.
+ * Text rows stay as strings when possible, and binary rows fall back to base64.
+ * The browser-side patched push then forwards those rows into the open stream
+ */
+async function writePayload(payload, controller, nonce) {
+    const decoder = new TextDecoder('utf-8', { fatal: true });
+    for await (const chunk of payload) {
+        try {
+            // most payload rows are plain text, so write the simplest script we can
+            writePayloadScript(JSON.stringify(decoder.decode(chunk, { stream: true })), controller, nonce);
+        }
+        catch {
+            // most rows are text, but keep binary chunks intact when a payload
+            // row cannot be decoded as utf-8
+            const base64 = JSON.stringify(window.btoa(String.fromCodePoint(...chunk)));
+            writePayloadScript(`Uint8Array.from(atob(${base64}), value => value.codePointAt(0))`, controller, nonce);
+        }
+    }
+    // flush any trailing decoder state after the stream ends
+    const remaining = decoder.decode();
+    if (remaining) {
+        writePayloadScript(JSON.stringify(remaining), controller, nonce);
+    }
+}
+/**
+ * Wrap one payload row in a script tag that appends into the shared browser queue.
+ * The script stays deliberately small: just push the row and let the patched push
+ * do the rest
+ */
+function writePayloadScript(chunk, controller, nonce) {
+    // each script only does a normal __FLIGHT_DATA.push(...). The patched push
+    // above forwards that row into the open stream. Escape the inline JS first
+    // so HTML parsing cannot break the script body
+    const script = `<script${nonce ? ` nonce="${nonce}"` : ''}>${escapeInlineScript(`(self.__FLIGHT_DATA||=[]).push(${chunk})`)}</script>`;
+    controller.enqueue(encoder.encode(script));
+}
+// Escape closing script tags and HTML comments inside inline JS
+function escapeInlineScript(script) {
+    return script.replace(/<!--/g, '<\\!--').replace(/<\/(script)/gi, '</\\$1');
+}