@rsc-kit/core 0.1.0

package/dist/streaming.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Read every chunk a stream already has queued, then stop.
+ *
+ * A queued chunk settles its read in a microtask, so it always beats the
+ * macrotask this races it against. A read that loses means the producer is
+ * waiting on data rather than still writing — for React's SSR stream, the
+ * moment the shell is fully out.
+ *
+ * The losing read is handed back rather than dropped, so the caller resumes
+ * without losing a chunk.
+ */
+export declare function drainQueuedChunks<T>(reader: {
+    read(): Promise<{
+        done: boolean;
+        value?: T;
+    }>;
+}, onChunk: (chunk: T) => void): Promise<{
+    pending: Promise<{
+        done: boolean;
+        value?: T;
+    }> | null;
+    done: boolean;
+}>;
+export interface DeferredHost {
+    /** Installed in place of the real host fn for the whole request. */
+    hostFn: (fn: string, ...args: unknown[]) => Promise<unknown>;
+    /** Start queueing. Called once metadata is resolved. */
+    begin: () => void;
+    /** Release the queue. Called once React's first payload is on the socket. */
+    flush: () => void;
+}
+/**
+ * Queue host calls made during the render, so React's first payload — the HTML
+ * shell, or the Flight root model and fallback rows — is on the socket before
+ * PHP blocks on one.
+ *
+ * PHP runs a host callback synchronously on the same thread that pumps that
+ * socket. Once a call starts, nothing the worker writes reaches the browser
+ * until it returns, so anything React had not yet produced is stranded for the
+ * duration. Both streaming paths share this: it is the difference between a
+ * page painting its skeletons at once and painting nothing for the length of
+ * the slowest call in it.
+ */
+export declare function createDeferredHost(realHostFn: (fn: string, ...args: unknown[]) => Promise<unknown>): DeferredHost;
+/**
+ * Write a React stream out, releasing the deferred host calls at the one safe
+ * moment: after everything already queued — the shell, or the Flight root model
+ * and fallback rows — is on the socket, and before anything that arrives later.
+ *
+ * Both worker paths stream through this so the ordering cannot drift between
+ * them. It already had: the HTML path released after its first chunk and the
+ * Flight path never deferred at all, so a slow host call blocked PHP with most
+ * of the payload still unwritten and the browser rendered nothing until the
+ * call returned.
+ */
+export declare function streamWithDeferredRelease<T>(reader: {
+    read(): Promise<{
+        done: boolean;
+        value?: T;
+    }>;
+}, onChunk: (chunk: T) => void, release: () => void, idle?: () => Promise<void>): Promise<void>;
+//# sourceMappingURL=streaming.d.ts.map

package/dist/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../src/streaming.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,MAAM,EAAE;IAAE,IAAI,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,CAAC,CAAA;KAAE,CAAC,CAAA;CAAE,EACzD,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAC1B,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,CAAC,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAenF;AAED,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D,wDAAwD;IACxD,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,YAAY,CA4CjH;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,MAAM,EAAE;IAAE,IAAI,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,CAAC,CAAA;KAAE,CAAC,CAAA;CAAE,EACzD,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,EAC3B,OAAO,EAAE,MAAM,IAAI,EACnB,IAAI,GAAE,MAAM,OAAO,CAAC,IAAI,CAAoB,GAC3C,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/streaming.js

@@ -0,0 +1,108 @@
+// Streaming coordination shared by both worker paths — initial-load HTML and
+// SPA-navigation Flight.
+//
+// Both stream React output over a socket that PHP pumps on the same thread it
+// runs host callbacks on. That single fact drives everything here: React's
+// first payload has to be on the socket before a callback can block, or the
+// browser sees nothing until the slowest call in the page returns.
+import { yieldToEventLoop } from './runtime.js';
+/**
+ * Read every chunk a stream already has queued, then stop.
+ *
+ * A queued chunk settles its read in a microtask, so it always beats the
+ * macrotask this races it against. A read that loses means the producer is
+ * waiting on data rather than still writing — for React's SSR stream, the
+ * moment the shell is fully out.
+ *
+ * The losing read is handed back rather than dropped, so the caller resumes
+ * without losing a chunk.
+ */
+export async function drainQueuedChunks(reader, onChunk) {
+    let pending = reader.read();
+    while (true) {
+        const settled = await Promise.race([
+            pending.then((result) => ({ result })),
+            yieldToEventLoop().then(() => null),
+        ]);
+        if (settled === null)
+            return { pending, done: false };
+        if (settled.result.done)
+            return { pending: null, done: true };
+        onChunk(settled.result.value);
+        pending = reader.read();
+    }
+}
+/**
+ * Queue host calls made during the render, so React's first payload — the HTML
+ * shell, or the Flight root model and fallback rows — is on the socket before
+ * PHP blocks on one.
+ *
+ * PHP runs a host callback synchronously on the same thread that pumps that
+ * socket. Once a call starts, nothing the worker writes reaches the browser
+ * until it returns, so anything React had not yet produced is stranded for the
+ * duration. Both streaming paths share this: it is the difference between a
+ * page painting its skeletons at once and painting nothing for the length of
+ * the slowest call in it.
+ */
+export function createDeferredHost(realHostFn) {
+    const pendingCalls = [];
+    let flushed = false;
+    let deferring = false;
+    let backstop;
+    const flush = () => {
+        if (flushed)
+            return;
+        flushed = true;
+        clearTimeout(backstop);
+        for (const call of pendingCalls) {
+            realHostFn(call.fn, ...call.args).then(call.resolve, call.reject);
+        }
+        pendingCalls.length = 0;
+    };
+    return {
+        hostFn: (functionName, ...args) => {
+            if (!deferring || flushed)
+                return realHostFn(functionName, ...args);
+            return new Promise((resolve, reject) => {
+                pendingCalls.push({ fn: functionName, args, resolve, reject });
+            });
+        },
+        // Deferral covers the render only. Metadata resolves before any payload
+        // exists, so a host call there has nothing to strand — queueing it would
+        // just stall generateMetadata until the backstop fired.
+        begin: () => {
+            deferring = true;
+            // Backstop only, for a render that awaits a host call before it can
+            // produce the payload that would release the queue. The build rejects
+            // such a page unless it ships a loading.tsx, whose shell does not block,
+            // so in practice the drain always gets there first. Long on purpose: it
+            // must never race a cold start.
+            backstop = setTimeout(flush, 5000);
+        },
+        flush,
+    };
+}
+/**
+ * Write a React stream out, releasing the deferred host calls at the one safe
+ * moment: after everything already queued — the shell, or the Flight root model
+ * and fallback rows — is on the socket, and before anything that arrives later.
+ *
+ * Both worker paths stream through this so the ordering cannot drift between
+ * them. It already had: the HTML path released after its first chunk and the
+ * Flight path never deferred at all, so a slow host call blocked PHP with most
+ * of the payload still unwritten and the browser rendered nothing until the
+ * call returned.
+ */
+export async function streamWithDeferredRelease(reader, onChunk, release, idle = yieldToEventLoop) {
+    let { pending, done } = await drainQueuedChunks(reader, onChunk);
+    release();
+    while (!done) {
+        const result = await (pending ?? reader.read());
+        pending = null;
+        if (result.done)
+            break;
+        onChunk(result.value);
+        await idle();
+    }
+}
+//# sourceMappingURL=streaming.js.map

package/dist/streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.js","sourceRoot":"","sources":["../src/streaming.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,yBAAyB;AACzB,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,4EAA4E;AAC5E,mEAAmE;AAEnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAE/C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAyD,EACzD,OAA2B;IAE3B,IAAI,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAA;IAE3B,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;YACjC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;YACtC,gBAAgB,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;SACpC,CAAC,CAAA;QAEF,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;QACrD,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;QAE7D,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAU,CAAC,CAAA;QAClC,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAA;IACzB,CAAC;AACH,CAAC;AAWD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAgE;IACjG,MAAM,YAAY,GAGb,EAAE,CAAC;IACR,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,QAAmD,CAAC;IAExD,MAAM,KAAK,GAAG,GAAG,EAAE;QACjB,IAAI,OAAO;YAAE,OAAO;QACpB,OAAO,GAAG,IAAI,CAAC;QACf,YAAY,CAAC,QAAQ,CAAC,CAAC;QACvB,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;YAChC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACpE,CAAC;QACD,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC;IAC1B,CAAC,CAAC;IAEF,OAAO;QACL,MAAM,EAAE,CAAC,YAAoB,EAAE,GAAG,IAAe,EAAoB,EAAE;YACrE,IAAI,CAAC,SAAS,IAAI,OAAO;gBAAE,OAAO,UAAU,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,CAAC;YAEpE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACrC,YAAY,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YACjE,CAAC,CAAC,CAAC;QACL,CAAC;QAED,wEAAwE;QACxE,yEAAyE;QACzE,wDAAwD;QACxD,KAAK,EAAE,GAAG,EAAE;YACV,SAAS,GAAG,IAAI,CAAC;YAEjB,oEAAoE;YACpE,sEAAsE;YACtE,yEAAyE;YACzE,wEAAwE;YACxE,gCAAgC;YAChC,QAAQ,GAAG,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACrC,CAAC;QAED,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAAyD,EACzD,OAA2B,EAC3B,OAAmB,EACnB,IAAI,GAAwB,gBAAgB;IAE5C,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,MAAM,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAEhE,OAAO,EAAE,CAAA;IAET,OAAO,CAAC,IAAI,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;QAC/C,OAAO,GAAG,IAAI,CAAA;QAEd,IAAI,MAAM,CAAC,IAAI;YAAE,MAAK;QAEtB,OAAO,CAAC,MAAM,CAAC,KAAU,CAAC,CAAA;QAC1B,MAAM,IAAI,EAAE,CAAA;IACd,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,82 @@
+// Ambient types for an RSC app. Copied into the project's source directory by
+// the host's build, so a page can annotate its metadata without importing
+// anything.
+//
+// The host global (rpc) is NOT declared here: its name is configurable, so the
+// host generates that declaration with the name it actually installed. Two
+// ambient declarations of the same function would conflict.
+
+/**
+ * Page metadata for RSC pages.
+ *
+ * @example
+ * ```tsx
+ * export const metadata: Metadata = {
+ *   title: 'My Page',
+ *   description: 'Page description',
+ *   keywords: ['react', 'laravel'],
+ * };
+ * ```
+ */
+interface IconDescriptor {
+  url: string | URL;
+  type?: string;
+  sizes?: string;
+  color?: string;
+  rel?: string;
+  media?: string;
+  fetchPriority?: 'high' | 'low' | 'auto';
+}
+
+type IconURL = string | URL;
+
+interface Icons {
+  icon?: IconURL | IconDescriptor | (IconURL | IconDescriptor)[];
+  apple?: IconURL | IconDescriptor | (IconURL | IconDescriptor)[];
+  shortcut?: IconURL | IconDescriptor | (IconURL | IconDescriptor)[];
+  other?: IconDescriptor | IconDescriptor[];
+}
+
+/** A layout's title, wrapping the titles of the pages beneath it. */
+interface TitleTemplate {
+  /** `%s` stands in for the page's own title. */
+  template?: string;
+  /** Used by a page that exports no title of its own. */
+  default?: string;
+}
+
+interface Metadata {
+  /** A string on a page; a template on a layout, applied to the pages below it. */
+  title?: string | TitleTemplate;
+  description?: string;
+  keywords?: string | string[];
+  author?: string;
+  robots?: string;
+  icons?: IconURL | (IconURL | IconDescriptor)[] | Icons | null;
+  'og:title'?: string;
+  'og:description'?: string;
+  'og:image'?: string;
+  'og:url'?: string;
+  'og:type'?: string;
+  'og:site_name'?: string;
+  'twitter:card'?: string;
+  'twitter:title'?: string;
+  'twitter:description'?: string;
+  'twitter:image'?: string;
+  'twitter:site'?: string;
+  [key: string]: string | string[] | TitleTemplate | Icons | IconURL | (IconURL | IconDescriptor)[] | null | undefined;
+}
+
+/**
+ * Metadata that depends on the request.
+ *
+ * Receives the same awaitables a page does, so one shape is learned rather
+ * than two:
+ *
+ *     export const generateMetadata: GenerateMetadata<{ slug: string }> =
+ *       async ({ params }) => ({ title: (await params).slug })
+ */
+type GenerateMetadata<P = Record<string, string>> = (args: {
+  params: Promise<P>;
+  searchParams: Promise<URLSearchParams>;
+}) => Metadata | Promise<Metadata>;

package/dist/vite.d.ts

@@ -0,0 +1,109 @@
+import type { PluginOption } from 'vite';
+export interface RscRoutesOptions {
+    /** Project root. Defaults to RSC_PROJECT_ROOT, then cwd. */
+    projectRoot?: string;
+    /** Directory holding the app/ route tree. Defaults to `src`. */
+    sourceDir?: string;
+    /** Where the server bundles and generated entries go. Defaults to `.rsc`. */
+    outDir?: string;
+    /** Where the browser bundle is written. Defaults to `dist/client`. */
+    assetsDir?: string;
+    /** Public URL the browser bundle is served from. Defaults to `/`. */
+    assetsUrl?: string;
+    /**
+     * This package's directory, holding the client runtime the browser entry
+     * imports. Vite stages configs through node_modules/.vite-temp, so
+     * import.meta.dir is not this file's real location by the time the plugin
+     * runs — a host invoking the build out of process passes the real path
+     * through RSC_PACKAGE_DIR.
+     */
+    packageDir?: string;
+    /**
+     * Name of the global the host installs for calling its own functions from a
+     * server component — `await rpc('getUser', id)`. The mechanism is
+     * host-agnostic; only the name is a convention, so a host that prefers
+     * something else can say so.
+     */
+    hostGlobal?: string;
+    /**
+     * JSON file of `{urlPattern, slot}` entries naming the routes the client
+     * router should intercept rather than navigate to. Written by the host,
+     * which owns route discovery.
+     */
+    interceptManifestFile?: string;
+    /**
+     * Bare-specifier prefix for importing the client runtime, as in
+     * `import Link from '<prefix>/Link'`, aliased to this package's js/
+     * directory.
+     *
+     * Only needed when this package is not resolvable from the project's
+     * node_modules — a host that vendors it through its own package manager,
+     * say. Installed from npm, the package name resolves on its own and no
+     * alias is required.
+     */
+    packageAlias?: string;
+    /**
+     * Origin the Vite dev server is reachable at, e.g. `http://localhost:5173`.
+     *
+     * Set only when running under the dev server. @vitejs/plugin-rsc emits its
+     * bootstrap and CSS links root-relative in dev and no Vite setting moves
+     * them, so with the host serving the page the browser would ask the host for
+     * modules only Vite can answer. Given this, the SSR entry rewrites them onto
+     * the dev origin — see devUrls.ts. Empty in a build, where the URLs are real
+     * built assets.
+     */
+    devOrigin?: string;
+    /**
+     * What the build produces.
+     *
+     *   'server'  the default: pages are served by a host, and a payload is
+     *             asked for with a header on the page's own url.
+     *   'export'  files any static host can serve. Payloads get addresses of
+     *             their own, because a host serving files cannot act on a
+     *             header, and the client is built to ask for those instead.
+     */
+    output?: 'server' | 'export';
+    /** Where an exported site is written, relative to the project root. */
+    exportPath?: string;
+    /**
+     * Filename payloads are served under on a static host, e.g. `index.rsc`.
+     *
+     * Only for an exported build. Normally the payload shares the page's url and
+     * is asked for with a header; a host that serves files cannot answer that,
+     * so the payload needs an address of its own.
+     */
+    staticPayloads?: string;
+    /**
+     * How to tell that a route's props are resolved dynamically by the host, so
+     * the page cannot be prerendered whole.
+     *
+     * Entirely host-defined: a host that writes a config file beside the page
+     * names that file and the pattern that marks it dynamic. Omitted, no page is
+     * classified dynamic on this basis.
+     */
+    routeConfig?: {
+        file: string;
+        dynamicPattern: RegExp;
+    };
+    /**
+     * Functions the host exposes to the app, as `{ exportedName: target }`.
+     *
+     * The build writes a "use server" module of stubs for these, each one
+     * calling the host global with its target — so app code imports an ordinary
+     * async function and never names the transport. Discovery belongs to the
+     * host, whose functions these are; only the rendering is here, because the
+     * module has to land beside the app's source and that path is the build's.
+     *
+     * A host whose functions are already JavaScript passes nothing.
+     */
+    hostActions?: Record<string, string>;
+    /**
+     * Freeze what can be frozen at the end of `vite build`. Defaults to true.
+     *
+     * Off, the build produces bundles and nothing else, and every route renders
+     * per request. See the note on the hook for when you would want that.
+     */
+    prerender?: boolean;
+}
+export declare function rscRoutes(options?: RscRoutesOptions): PluginOption[];
+//# sourceMappingURL=vite.d.ts.map

package/dist/vite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAU,YAAY,EAAkB,MAAM,MAAM,CAAA;AAGhE,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC5B,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAA;IACtD;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACpC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAoxDD,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,YAAY,EAAE,CAsMxE"}