@rsc-kit/core 0.20.2 → 0.20.4

package/dist/earlyHints.d.ts

@@ -0,0 +1,17 @@
+export interface CriticalAssets {
+    /** Stylesheets the document links: `<link rel="stylesheet">`. */
+    styles: string[];
+    /** The client entry: `<script type="module">`'s import. */
+    modules: string[];
+    /** Fonts the document preloads: `<link rel="preload" as="font">`. */
+    fonts: string[];
+}
+/** One `Link` header value for the set. Empty string for an empty set. */
+export declare function linkHeader(assets: CriticalAssets): string;
+/**
+ * What a stored document's head names: its stylesheets and preloaded fonts.
+ * The first 16 KB, which is the head of any document this build writes.
+ */
+export declare function criticalAssetsOf(html: string): CriticalAssets;
+/** One set over another: the document's own names first, the build's where the document has none. */
+export declare function mergeAssets(primary: CriticalAssets, fallback: CriticalAssets | null): CriticalAssets;

package/dist/earlyHints.js

@@ -0,0 +1,65 @@
+// The Link header a document answers with, for a CDN to send ahead as 103
+// Early Hints - so the stylesheet, the client entry and the fonts are on
+// their way while the HTML is still being written. Cloudflare turns the
+// header into hints and caches them at the edge for the next visitor;
+// anything else passes it through, where a browser still reads it as the
+// document arrives.
+//
+// The critical set and nothing more: a hint promotes whatever it names, and
+// naming every chunk demotes the document behind them. The stylesheet and
+// the client entry come from the build's own manifest, the same names the
+// document carries. The fonts are the app's - preloaded in its layout - and
+// are read from a stored document's own head; a rendered document's head is
+// not known until it is rendered, after its headers have gone.
+/** One `Link` header value for the set. Empty string for an empty set. */
+export function linkHeader(assets) {
+    const parts = [];
+    for (const href of assets.styles)
+        parts.push(`<${href}>; rel=preload; as=style`);
+    for (const href of assets.modules)
+        parts.push(`<${href}>; rel=modulepreload`);
+    for (const href of assets.fonts)
+        parts.push(`<${href}>; rel=preload; as=font; crossorigin`);
+    return parts.join(', ');
+}
+const HEAD_LIMIT = 16_384;
+const LINK = /<link\s[^>]*>/g;
+const ATTR = (name, tag) => {
+    const match = new RegExp(`\\b${name}=["']([^"']*)["']`, 'i').exec(tag);
+    return match ? match[1] : null;
+};
+/**
+ * What a stored document's head names: its stylesheets and preloaded fonts.
+ * The first 16 KB, which is the head of any document this build writes.
+ */
+export function criticalAssetsOf(html) {
+    const head = html.slice(0, HEAD_LIMIT);
+    const found = { styles: [], modules: [], fonts: [] };
+    for (const tag of head.match(LINK) ?? []) {
+        const rel = ATTR('rel', tag)?.toLowerCase();
+        const href = ATTR('href', tag);
+        if (!href || !href.startsWith('/'))
+            continue;
+        if (rel === 'stylesheet')
+            found.styles.push(href);
+        else if (rel === 'preload' && ATTR('as', tag)?.toLowerCase() === 'font')
+            found.fonts.push(href);
+    }
+    // The bootstrap script is the last thing in the body, after the shell; its
+    // import names the entry. The tail, then, and the head for a short page.
+    const entry = /import\(["'](\/[^"']+\.js)["']\)/.exec(html.slice(-4096)) ?? /import\(["'](\/[^"']+\.js)["']\)/.exec(head);
+    if (entry)
+        found.modules.push(entry[1]);
+    return found;
+}
+/** One set over another: the document's own names first, the build's where the document has none. */
+export function mergeAssets(primary, fallback) {
+    if (!fallback)
+        return primary;
+    return {
+        styles: primary.styles.length ? primary.styles : fallback.styles,
+        modules: primary.modules.length ? primary.modules : fallback.modules,
+        fonts: primary.fonts.length ? primary.fonts : fallback.fonts,
+    };
+}
+//# sourceMappingURL=earlyHints.js.map

package/dist/earlyHints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"earlyHints.js","sourceRoot":"","sources":["../src/earlyHints.ts"],"names":[],"mappings":"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","sourcesContent":["// The Link header a document answers with, for a CDN to send ahead as 103\n// Early Hints - so the stylesheet, the client entry and the fonts are on\n// their way while the HTML is still being written. Cloudflare turns the\n// header into hints and caches them at the edge for the next visitor;\n// anything else passes it through, where a browser still reads it as the\n// document arrives.\n//\n// The critical set and nothing more: a hint promotes whatever it names, and\n// naming every chunk demotes the document behind them. The stylesheet and\n// the client entry come from the build's own manifest, the same names the\n// document carries. The fonts are the app's - preloaded in its layout - and\n// are read from a stored document's own head; a rendered document's head is\n// not known until it is rendered, after its headers have gone.\n\nexport interface CriticalAssets {\n  /** Stylesheets the document links: `<link rel=\"stylesheet\">`. */\n  styles: string[];\n  /** The client entry: `<script type=\"module\">`'s import. */\n  modules: string[];\n  /** Fonts the document preloads: `<link rel=\"preload\" as=\"font\">`. */\n  fonts: string[];\n}\n\n/** One `Link` header value for the set. Empty string for an empty set. */\nexport function linkHeader(assets: CriticalAssets): string {\n  const parts: string[] = []\n\n  for (const href of assets.styles) parts.push(`<${href}>; rel=preload; as=style`)\n  for (const href of assets.modules) parts.push(`<${href}>; rel=modulepreload`)\n  for (const href of assets.fonts) parts.push(`<${href}>; rel=preload; as=font; crossorigin`)\n\n  return parts.join(', ')\n}\n\nconst HEAD_LIMIT = 16_384\nconst LINK = /<link\\s[^>]*>/g\nconst ATTR = (name: string, tag: string): string | null => {\n  const match = new RegExp(`\\\\b${name}=[\"']([^\"']*)[\"']`, 'i').exec(tag)\n\n  return match ? match[1] : null\n}\n\n/**\n * What a stored document's head names: its stylesheets and preloaded fonts.\n * The first 16 KB, which is the head of any document this build writes.\n */\nexport function criticalAssetsOf(html: string): CriticalAssets {\n  const head = html.slice(0, HEAD_LIMIT)\n  const found: CriticalAssets = { styles: [], modules: [], fonts: [] }\n\n  for (const tag of head.match(LINK) ?? []) {\n    const rel = ATTR('rel', tag)?.toLowerCase()\n    const href = ATTR('href', tag)\n\n    if (!href || !href.startsWith('/')) continue\n\n    if (rel === 'stylesheet') found.styles.push(href)\n    else if (rel === 'preload' && ATTR('as', tag)?.toLowerCase() === 'font') found.fonts.push(href)\n  }\n\n  // The bootstrap script is the last thing in the body, after the shell; its\n  // import names the entry. The tail, then, and the head for a short page.\n  const entry = /import\\([\"'](\\/[^\"']+\\.js)[\"']\\)/.exec(html.slice(-4096)) ?? /import\\([\"'](\\/[^\"']+\\.js)[\"']\\)/.exec(head)\n\n  if (entry) found.modules.push(entry[1])\n\n  return found\n}\n\n/** One set over another: the document's own names first, the build's where the document has none. */\nexport function mergeAssets(primary: CriticalAssets, fallback: CriticalAssets | null): CriticalAssets {\n  if (!fallback) return primary\n\n  return {\n    styles: primary.styles.length ? primary.styles : fallback.styles,\n    modules: primary.modules.length ? primary.modules : fallback.modules,\n    fonts: primary.fonts.length ? primary.fonts : fallback.fonts,\n  }\n}\n"]}

package/dist/host.d.ts

@@ -3,6 +3,7 @@
  * from `@rsc-kit/core/revalidate`.
  */
 export { revalidate } from "./revalidate.js";
+import { type CriticalAssets } from "./earlyHints.js";
 /**
  * @internal For a host adapter that embeds the engine. An app imports this
  * from `@rsc-kit/core/redirect` - the one the guides teach, and the one an
@@ -18,6 +19,10 @@ import type { RouteManifest } from "./manifest.js";
 export interface RscEngine {
     /** The route table this bundle was built from. */
     manifest?(): RouteManifest;
+    /** A short id of this build's client, for the version the host answers with when given none. */
+    buildId?(): Promise<string>;
+    /** The stylesheet and client entry every document links, for the Link header a CDN sends ahead. */
+    criticalAssets?(): CriticalAssets;
     installHostFn(fn: (name: string, ...args: unknown[]) => unknown): void;
     handleRscStream(component: string, props?: Record<string, unknown>, layouts?: {
         component: string;
@@ -143,10 +148,11 @@ export interface RscHostOptions {
     /** Serve a built browser asset. Return null for anything not found. */
     assets?: (pathname: string, request: Request) => Promise<Response | null> | Response | null;
     /**
-     * Identifies this build to the client, which compares it on every
-     * navigation and falls back to a full load when it changes. Without one a
-     * client keeps talking to a deployment that no longer exists — worst behind
-     * a CDN, where the shell it holds may already be from an older build.
+     * Identifies this build to the client, which says it back on every
+     * navigation and is sent to load the document when it differs. For an
+     * engine with no `buildId` of its own; the generated one has, and every
+     * document it renders says that id, so a version named here would
+     * disagree with what the client was told and refuse every navigation.
      */
     version?: string;
     /**

package/dist/host.js

@@ -27,6 +27,7 @@ import { currentNotFound, withRedirect } from "./redirect.js";
 import { compressed } from "./compress.js";
 import { withCache } from "./cache.js";
 import { takeAfterWork, withRequest, withResponseDraft } from "./request.js";
+import { criticalAssetsOf, linkHeader, mergeAssets } from "./earlyHints.js";
 /**
  * @internal For a host adapter that embeds the engine. An app imports this
  * from `@rsc-kit/core/redirect` - the one the guides teach, and the one an
@@ -286,7 +287,13 @@ function matchPage(routes, url) {
     return matchRoute(routes, url.pathname, hostOf.get(url) ?? null);
 }
 export function createRscHandler(options) {
-    const { engine, assets, version } = options;
+    const { engine, assets } = options;
+    // The build's own id, which is also what every document says it is - the
+    // two must agree, or a client's honest claim is a 409 on every request.
+    // A version named by the app applies only to an engine with no id of its
+    // own. Resolved on the first request: the engine reads it from a build
+    // product it only has at runtime.
+    let version = engine.buildId ? undefined : options.version;
     const maxActionBody = options.maxActionBody ?? DEFAULT_MAX_ACTION_BODY;
     const compress = options.compress ?? true;
     // Annotated rather than inferred: the narrowing below is lost inside the
@@ -350,6 +357,10 @@ export function createRscHandler(options) {
     const identify = Boolean(manifest.build?.identify);
     /** How a response was answered, for X-RSC-Kit: a file the build wrote, or a shell of one. */
     const servedFrom = new WeakMap();
+    /** What a stored document's head names, read once per file, for the Link header. */
+    const hinted = new WeakMap();
+    const hintsByKey = new Map();
+    const EMPTY_ASSETS = { styles: [], modules: [], fonts: [] };
     /**
      * The page a payload url belongs to, if this is one.
      *
@@ -421,6 +432,8 @@ export function createRscHandler(options) {
         return [version ?? "", url.pathname + url.search, ...varies].join("\n");
     }
     return async function handle(request) {
+        if (version === undefined && engine.buildId)
+            version = await engine.buildId();
         return await withRequest(request, () => withCache(() => 
         // Open for the whole request and sealed the moment an answer exists,
         // so middleware — which runs before any rendering — can put headers on
@@ -449,6 +462,16 @@ export function createRscHandler(options) {
             // Network tab, the way X-Nextjs-Cache is. Always: it names no
             // product, and a CDN rule or a check can key on it.
             response.headers.set("X-RSC-Kit", servedFrom.get(response) ?? "rendered");
+            // What the document needs first, as a Link header: a CDN sends it
+            // ahead as 103 Early Hints, and the stylesheet, the entry and the
+            // fonts download while the HTML is still being written. Every
+            // document, stored ones included - a stored document's own head
+            // names its fonts; a rendered one's is not known until too late.
+            if (response.status === 200 && (response.headers.get("Content-Type") ?? "").startsWith("text/html")) {
+                const link = linkHeader(mergeAssets(hinted.get(response) ?? EMPTY_ASSETS, engine.criticalAssets?.() ?? null));
+                if (link)
+                    response.headers.set("Link", link);
+            }
             // What built it. The name only, never the version - a version in
             // every response is what a vulnerability scanner filters on - and
             // off for a team whose policy strips every framework identifier.
@@ -583,6 +606,20 @@ export function createRscHandler(options) {
         const formPost = await formPostOf(request, url);
         if (!formPost && request.method !== "GET" && request.method !== "HEAD")
             return null;
+        // A client saying which build it runs, and it is not this one: its
+        // manifest cannot load what this build's payload names - a client
+        // component added since is "client reference not found" and the route's
+        // error boundary, on a page that worked a click ago. Under a service
+        // worker that serves the last build's document first, that is every
+        // returning visitor's first navigation after a deploy, not an open tab.
+        // A 409 sends the client to load the document instead, from this build.
+        const claimed = request.headers.get(HEADER.version);
+        if (claimed !== null && claimed !== "" && version && claimed !== version && request.headers.get(HEADER.rsc) !== null) {
+            return new Response(null, {
+                status: 409,
+                headers: withVersion({ "X-RSC-Location": url.pathname + url.search, "Cache-Control": "no-store" }),
+            });
+        }
         // One named region of this page, asked for without mutating anything to
         // earn it. What an action invalidated does not come through here — that
         // travels back inside the action's own answer, which is the whole point of
@@ -936,7 +973,7 @@ export function createRscHandler(options) {
             const whole = await read(`${key}.html`);
             // A whole page is finished. Nothing to resume, nothing to render.
             if (whole !== null) {
-                return new Response(whole, {
+                const response = new Response(whole, {
                     headers: withVersion({
                         "Content-Type": HTML_TYPE,
                         Vary: VARY_ON_RSC,
@@ -945,6 +982,14 @@ export function createRscHandler(options) {
                             : REVALIDATE,
                     }),
                 });
+                // Its head is in hand, so its fonts are too. Read once per file.
+                let found = hintsByKey.get(key);
+                if (!found) {
+                    found = criticalAssetsOf(whole);
+                    hintsByKey.set(key, found);
+                }
+                hinted.set(response, found);
+                return response;
             }
             // Then a shell, under this url or under the route's pattern. Which of the
             // two answered is tracked, because the state that resumes it sits beside
@@ -1010,6 +1055,13 @@ export function createRscHandler(options) {
                 }),
             });
             servedFrom.set(withHoles, "shell");
+            // The shell's head is the document's head; its fonts are known too.
+            let found = hintsByKey.get(shellKey);
+            if (!found) {
+                found = criticalAssetsOf(shell);
+                hintsByKey.set(shellKey, found);
+            }
+            hinted.set(withHoles, found);
             return withHoles;
         }
         // Only the document is ever served frozen for a shell. The payload is what