@rsc-kit/core 0.20.12 → 0.21.0

package/dist/vite.js

@@ -20,7 +20,8 @@ import { spawnSync } from "node:child_process";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import rsc, { getPluginApi } from "@vitejs/plugin-rsc";
-import { loadEnv } from "vite";
+import { loadEnv, parseAst } from "vite";
+import { stampDisplayNames } from "./stableNames.js";
 import { REPORT_FILE, buildReport } from "./buildReport.js";
 import { MANIFEST_PATH, manifestWarning, webManifest } from "./webManifest.js";
 import { ASSET_BASE, allAppAssets, appAssets, headTags, typeOf, } from "./appAssets.js";
@@ -192,6 +193,8 @@ let foundAssets = {
     favicon: null,
     icons: [],
     appleIcon: null,
+    appleSplash: [],
+    screenshots: [],
     openGraph: null,
     twitter: null,
 };
@@ -390,6 +393,16 @@ function resolvePaths(options) {
             icons: foundAssets.icons.map((icon) => icon.href),
         };
     }
+    // Screenshots the same way: found by name, their size and form factor read
+    // from it when the manifest is written.
+    if (webManifestOptions &&
+        !webManifestOptions.screenshots?.length &&
+        foundAssets.screenshots.length) {
+        webManifestOptions = {
+            ...webManifestOptions,
+            screenshots: foundAssets.screenshots.map((shot) => shot.href),
+        };
+    }
     hostActions = options.hostActions ?? fileHostActions(projectRoot);
 }
 function log(...args) {
@@ -620,6 +633,10 @@ function routeManifest() {
             // A synthesised robots.txt or sitemap.xml runs no guard: it exists to be
             // read by anyone, and a guard on the root would 401 the crawler.
             middleware: generated ? [] : ancestors(name, "middleware"),
+            // And the host's, for the same reason: `export const middleware =
+            // ['auth']` on a directory guards the route.ts files in it, or adding
+            // an endpoint under a guarded path opened a hole in it.
+            hostMiddleware: generated ? [] : hostMiddleware(dirOf(name)),
         })),
     };
 }
@@ -1222,6 +1239,15 @@ function copyAppAssets(clientDir) {
         copyFileSync(join(sourceDir, "app", asset.file), to);
     }
     log(`icons: ${all.length} copied from app/`);
+    // A launch screen whose size no device has would be a media query that
+    // matches nothing - served, linked from no page, shown to no one. Named
+    // here, with the sizes that do exist a click away in the guide.
+    const unmatched = foundAssets.appleSplash.filter((splash) => splash.media === null).map((splash) => splash.file);
+    if (unmatched.length) {
+        log(`apple-splash: ${unmatched.join(", ")} ${unmatched.length === 1 ? "matches" : "match"} no iPhone or iPad screen, ` +
+            "so no page links to it. Name each file by the device's size in pixels, portrait or landscape - " +
+            "apple-splash-1179x2556.png is an iPhone 15. The sizes are in the PWA guide.");
+    }
 }
 function writeWebManifest(clientDir, options) {
     if (!existsSync(clientDir))
@@ -1230,6 +1256,9 @@ function writeWebManifest(clientDir, options) {
     const warning = manifestWarning(options);
     if (warning)
         log(warning);
+    else if (!options.screenshots?.length)
+        log(`manifest: ${options.name} is installable. Chrome shows its basic install sheet; ` +
+            "a screenshot-wide-*.png and screenshot-narrow-*.png in app/ get the richer one.");
     else
         log(`manifest: ${options.name} is installable`);
 }
@@ -2265,6 +2294,18 @@ const FALLBACK_BODY = `  const answer = await devHandler(request)
   headers.set('x-forwarded-host', here.host)
   headers.set('x-forwarded-proto', here.protocol.replace(':', ''))
 
+  // And never the visitor's own. The backend trusts this proxy, so an
+  // X-Forwarded-For the browser wrote would be read as the client address -
+  // a visitor choosing their own IP for a throttle on /login. Nothing here
+  // knows the peer's address to put in its place, so the chain is dropped
+  // unless this server sits behind a proxy of its own that wrote it, which
+  // RSC_TRUST_FORWARDED=1 says.
+  if (!(typeof process !== 'undefined' && process.env.RSC_TRUST_FORWARDED === '1')) {
+    for (const name of ['x-forwarded-for', 'forwarded', 'x-real-ip', 'x-client-ip', 'x-forwarded-port', 'x-forwarded-prefix']) {
+      headers.delete(name)
+    }
+  }
+
   const hasBody = request.method !== 'GET' && request.method !== 'HEAD'
 
   try {
@@ -2333,10 +2374,7 @@ const NITRO_PRERENDERED = `    prerendered: import.meta.env.PROD
       ? prerenderedBeside(import.meta.url, ${JSON.stringify(NITRO_STATIC_DIR)})
       : undefined,
 `;
-const NITRO_HANDLER_OPTIONS = `    props: (match, request) => ({
-      ...match.params,
-      ...Object.fromEntries(new URL(request.url).searchParams),
-    }),
+const NITRO_HANDLER_OPTIONS = `    props: queryAndParams,
     // A built server gzips what it answers, where the runtime can; the dev
     // server answers raw, which is what a person reading a response wants.
     compress: import.meta.env.PROD,
@@ -2475,7 +2513,7 @@ import { parseParams, parseSearchParams, parseBody, isSearchParamsError, isBodyE
 import { notFoundDigest, isNotFoundSignal } from ${JSON.stringify(join(packageDir, "notFound"))}
 import { noteRequestRead, urlOf } from ${JSON.stringify(join(packageDir, "request"))}
 import { redirectDigest } from ${JSON.stringify(join(packageDir, "redirectDigest"))}
-import { createRscHandler } from ${JSON.stringify(join(packageDir, "host"))}
+import { createRscHandler, queryAndParams } from ${JSON.stringify(join(packageDir, "host"))}
 import { httpHostCalls } from ${JSON.stringify(join(packageDir, "hostCalls"))}
 import { prerenderedBeside } from ${JSON.stringify(join(packageDir, "files"))}
 import { renderToReadableStream, decodeReply, decodeAction, decodeFormState, loadServerAction } from '@vitejs/plugin-rsc/rsc'
@@ -3512,11 +3550,47 @@ async function renderTree(
       }
     }
 
+    // How the app behaves added to an iPhone's home screen - Next's shape.
+    // Both capable names: Safari reads the apple- one, Chrome warns about it
+    // and reads the plain one, and Next switched between them in a minor.
+    if (md.appleWebApp != null && md.appleWebApp !== false) {
+      const web = (md.appleWebApp === true ? { capable: true } : md.appleWebApp) as Record<string, unknown>
+
+      if (web.capable) {
+        head.push(tag('mobile-web-app-capable', 'yes'))
+        head.push(tag('apple-mobile-web-app-capable', 'yes'))
+      }
+
+      if (web.title != null) head.push(tag('apple-mobile-web-app-title', web.title))
+      if (web.statusBarStyle != null) head.push(tag('apple-mobile-web-app-status-bar-style', web.statusBarStyle))
+
+      if (web.startupImage != null) {
+        const startup = Array.isArray(web.startupImage) ? web.startupImage : [web.startupImage]
+
+        for (const item of startup) {
+          if (item == null) continue
+
+          const image = typeof item === 'object' && !(item instanceof URL)
+            ? (item as Record<string, unknown>)
+            : { url: item }
+
+          head.push(
+            createElement('link', {
+              key: '__s_' + String(image.url).slice(0, 60) + '_' + String(image.media ?? ''),
+              rel: 'apple-touch-startup-image',
+              href: absolute(image.url),
+              ...(image.media ? { media: image.media } : {}),
+            }),
+          )
+        }
+      }
+    }
+
     // other is flattened in beside the named keys, because it is a place to put
     // meta tags rather than a meta tag by that name. A key at the top level
     // still renders - the type no longer invites one, but an app written
     // against the old shape must not silently lose its tags.
-    const structured = new Set(['title', 'description', 'robots', 'metadataBase', 'openGraph', 'twitter', 'icons', 'other'])
+    const structured = new Set(['title', 'description', 'robots', 'metadataBase', 'openGraph', 'twitter', 'icons', 'appleWebApp', 'other'])
     const named = Object.entries(md).filter(([k]) => !structured.has(k))
     const extra = Object.entries((md.other ?? {}) as Record<string, unknown>)
 
@@ -3606,6 +3680,11 @@ async function runHostMiddleware(component) {
     for (const route of manifest().routes) {
       if (route.hostMiddleware?.length) hostChains[route.component] = route.hostMiddleware
     }
+
+    // Api routes, keyed by module name - the key runRouteMiddleware is asked with.
+    for (const api of manifest().apis ?? []) {
+      if (api.hostMiddleware?.length) hostChains[api.name] = api.hostMiddleware
+    }
   }
 
   const names = hostChains[component] ?? []
@@ -3903,9 +3982,20 @@ export async function handleRscResume(
   )
 
   const ssr = await (import.meta as any).viteRsc.loadModule('ssr', 'index')
-  const htmlStream = await ssr.handleSsrResume(flight, postponed, nonce)
+  // Whether React could replay the recorded tree at all. A bundler that
+  // merges scopes renames components, and a name is how React matches a
+  // slot: the same page, built once and bundled again - which is what
+  // bun build --compile does - has different names at runtime than the
+  // shell recorded. Reported so the host can stop resuming this shell and
+  // render the page whole, rather than serving one whose holes are all
+  // client-rendered. Set before the stream ends, because that is when
+  // React reports it.
+  let replayFailed = false
+  const htmlStream = await ssr.handleSsrResume(flight, postponed, nonce, () => {
+    replayFailed = true
+  })
 
-  return { htmlStream }
+  return { htmlStream, replayed: () => !replayFailed }
 }
 
 // Server action (worker: rsc-action).
@@ -4460,6 +4550,8 @@ export async function handleRscPayload(
 //                     data, so only the shell is safe to cache
 // A page that sets neither is genuinely static and can be prerendered fully.
 const PPR_SHELL_TIMEOUT_MS = Number(process.env.RSC_PPR_TIMEOUT_MS || 2000)
+// How long a render goes without a Flight row before it counts as waiting.
+const PPR_QUIET_MS = 50
 
 export async function handleRscPprShell(
   component: string,
@@ -4496,6 +4588,11 @@ export async function handleRscPprShell(
   // installed, because those are different statements: a test that installed
   // one is not a build that can reach the host.
   canReachHost = false,
+  // Told once, when the render has stopped producing rows and is only
+  // waiting. The budget still runs - a slow query can still land and be
+  // stored - but the caller no longer has to hold a slot for a render that
+  // is doing nothing but watching a clock.
+  onQuiet?: () => void,
 ): Promise<{ shellHtml: string; clientChunks: unknown; timedOut: boolean; usedDynamicApis: boolean; error?: string }> {
   // Deliberately no middleware here. The probe is asking whether the content is
   // the same for everyone, which is a question about the page. Whether a
@@ -4524,6 +4621,35 @@ export async function handleRscPprShell(
   const controller = new AbortController()
   const budget = setTimeout(() => controller.abort(), budgetMs)
 
+  // Quiet is a stretch with no Flight row: what is left is awaiting something,
+  // and whether that something ever answers is what the budget decides. A
+  // guess in one direction only - a render mistaken for quiet just overlaps
+  // with the next, and is still given its whole budget.
+  let quietTimer: ReturnType<typeof setTimeout> | undefined
+  const stir = () => {
+    if (!onQuiet) return
+    clearTimeout(quietTimer)
+    quietTimer = setTimeout(() => {
+      const told = onQuiet
+      onQuiet = undefined
+      told?.()
+    }, PPR_QUIET_MS)
+  }
+  const watchForQuiet = (stream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> => {
+    if (!onQuiet) return stream
+
+    stir()
+
+    return stream.pipeThrough(
+      new TransformStream<Uint8Array, Uint8Array>({
+        transform(chunk, out) {
+          stir()
+          out.enqueue(chunk)
+        },
+      }),
+    )
+  }
+
   // Anything that failed while producing this shell.
   //
   // A rejection inside a Suspense boundary does NOT reach the caller: React
@@ -4605,7 +4731,7 @@ export async function handleRscPprShell(
       )
       // Quiet about a redirect: during the probe it is a classification, not
       // a failure, and React would otherwise print a stack for every one.
-      const flight = renderToReadableStream(tree, { onError: noteFailure })
+      const flight = watchForQuiet(renderToReadableStream(tree, { onError: noteFailure }))
       const ssr = await (import.meta as any).viteRsc.loadModule('ssr', 'index')
       // The flight stream stays open across this. A Flight stream that has
       // closed tells the decoder the connection ended, so the boundary waiting
@@ -4636,6 +4762,7 @@ export async function handleRscPprShell(
 
   await produce
   clearTimeout(budget)
+  clearTimeout(quietTimer)
 
   // timedOut used to mean the stopwatch ran out. It now means React has
   // boundaries it could not finish — the thing the caller was always asking
@@ -4804,6 +4931,7 @@ function generateEntrySsr() {
     const redirectDigestModule = join(packageDir, "redirectDigest");
     const notFoundModule = join(packageDir, "notFound");
     const earlyClicks = join(packageDir, "js/earlyClicks");
+    const installCapture = join(packageDir, "js/installCapture");
     return `// GENERATED by rscKit() — do not edit.
 import { createFromReadableStream } from '@vitejs/plugin-rsc/ssr'
 import { renderToReadableStream, resume } from 'react-dom/server.edge'
@@ -4814,6 +4942,11 @@ import { cancelledByConsumer, caughtByLoading } from ${JSON.stringify(fallbackRe
 import { parseRedirectDigest } from ${JSON.stringify(redirectDigestModule)}
 import { isNotFoundDigest } from ${JSON.stringify(notFoundModule)}
 import { EARLY_CLICKS } from ${JSON.stringify(earlyClicks)}
+${webManifestOptions ? `import { INSTALL_CAPTURE } from ${JSON.stringify(installCapture)}` : ""}
+
+// What runs ahead of the runtime: held taps, and - in an app that can be
+// installed at all - the browser's offer to install it. See installCapture.ts.
+const EARLY = EARLY_CLICKS${webManifestOptions ? " + INSTALL_CAPTURE" : ""}
 
 // Set only by the dev server. @vitejs/plugin-rsc emits its bootstrap and CSS
 // links root-relative in dev, which would send the browser to the host for
@@ -4836,7 +4969,7 @@ export async function handleSsr(
   // seconds before the runtime hydrates is held for it rather than given
   // to the browser as a document load. See earlyClicks.ts.
   const bootstrapScriptContent = bootstrap
-    ? EARLY_CLICKS + (await (import.meta as any).viteRsc.loadBootstrapScriptContent('index'))
+    ? EARLY + (await (import.meta as any).viteRsc.loadBootstrapScriptContent('index'))
     : undefined
 
   // Without an onError handler React rejects each abortable task on its own,
@@ -4878,7 +5011,7 @@ export async function handleSsrPrerender(
   const bootstrapScriptContent =
     options.bootstrap === false
       ? undefined
-      : EARLY_CLICKS + (await (import.meta as any).viteRsc.loadBootstrapScriptContent('index'))
+      : EARLY + (await (import.meta as any).viteRsc.loadBootstrapScriptContent('index'))
 
   const { prelude, postponed } = await prerender(root as any, {
     bootstrapScriptContent,
@@ -4977,6 +5110,11 @@ export async function handleSsrResume(
   rscStream: ReadableStream,
   postponed: unknown,
   nonce?: string,
+  // Told when React refuses to replay: the tree it recorded and the tree
+  // rendering now put different components in a slot, so every hole below
+  // is client-rendered instead of filled here. The caller decides what to
+  // do about it; see the host.
+  onReplayMismatch?: () => void,
 ): Promise<ReadableStream> {
   const root = await createFromReadableStream(rscStream)
 
@@ -4987,7 +5125,13 @@ export async function handleSsrResume(
     // the designed path, on every resume of a shell whose hole holds one -
     // printed as "[rsc-kit:resume] Error: useSearchParams() was read..." on
     // every request, with advice the app had already followed.
-    onError: reportRenderError('resume'),
+    onError: (error: unknown, info: unknown) => {
+      const message = String((error as { message?: string } | null)?.message ?? error)
+
+      if (message.includes('instead it rendered') || message.includes('resumable slots')) onReplayMismatch?.()
+
+      return reportRenderError('resume')(error, info)
+    },
   })
 
   return DEV_ORIGIN ? rewriteViteDevUrlStream(html, DEV_ORIGIN) : html
@@ -5030,9 +5174,21 @@ function generateEntryBrowser() {
         }))
         : null;
     const refreshModule = join(packageDir, "js/navigate");
+    const chunkPreload = join(packageDir, "js/chunkPreload");
     return `// GENERATED by rscKit() — do not edit.
 import { createViteRscApp } from ${JSON.stringify(clientBootstrap)}
 import { refresh } from ${JSON.stringify(refreshModule)}
+import { setChunkLoader } from ${JSON.stringify(chunkPreload)}
+import * as clientReferences from 'virtual:vite-rsc/client-references'
+
+// How a client component's id becomes its chunk, for loading the ones a
+// prefetched page uses before the tap - see chunkPreload.ts. The same map the
+// runtime loads them through, so a chunk loaded here is the one it finds.
+// A production build only: in development the runtime imports by path.
+if (import.meta.env.PROD) {
+  const references = (clientReferences as { default: Record<string, () => Promise<unknown>> }).default
+  setChunkLoader((id) => references[id]?.())
+}
 
 createViteRscApp(document, ${JSON.stringify(interceptManifest())}, ${JSON.stringify({
         staticPayloads: staticPayloads || null,
@@ -5246,6 +5402,25 @@ const JSX_PLUGIN_PATTERN = /react|babel|oxc/i;
  * class is ever constructed on the server.
  */
 const CLIENT_STUB = /registerClientReference\(\s*\(\) => \{ throw new Error\("Unexpectedly client reference export '"/g;
+/**
+ * The server's render of client components, with names a second bundler
+ * cannot change. See stableNames.ts: a replay matches slots by component
+ * name, and `bun build --compile` renames whatever collides when it merges
+ * module scopes. Stamped on the ssr output as written, so the names are
+ * the ones the prerender recorded - it renders from this same output - and
+ * the ones anything serving it reads, compiled or not.
+ */
+function stableComponentNames() {
+    return {
+        name: "rsc-kit:stable-component-names",
+        apply: "build",
+        applyToEnvironment: (environment) => environment.name === "ssr",
+        renderChunk(code) {
+            const stamped = stampDisplayNames(code, (source) => parseAst(source));
+            return stamped === code ? null : { code: stamped, map: null };
+        },
+    };
+}
 function extendableClientReferences() {
     return {
         name: "rsc-kit:extendable-client-references",
@@ -6031,6 +6206,32 @@ export function rscKit(options = {}) {
                                 external: serverExternals,
                                 // Same table, same reason.
                                 checks: { ineffectiveDynamicImport: false },
+                                output: {
+                                    // One copy of a dependency, however many client components
+                                    // reach for it.
+                                    //
+                                    // Every client component is its own entry here - the SSR
+                                    // side of a client reference, imported by id - and a
+                                    // dependency two of them share is copied into each one's
+                                    // chunk group. Two copies of one component are two
+                                    // different functions, and that is fine until something
+                                    // merges the module scopes: `bun build --compile` does,
+                                    // renames the second copy, and a partially prerendered
+                                    // page records its tree BY COMPONENT NAME. The shell then
+                                    // says <J>, the binary renders <J2>, React refuses the
+                                    // replay and every hole falls to the browser - a page
+                                    // that arrives looking finished with nothing wired up. A
+                                    // port found it on one page, in production, on cold
+                                    // loads only.
+                                    //
+                                    // Grouping node_modules into one chunk means a shared
+                                    // dependency exists once, so there is nothing to collide.
+                                    // The server does not pay for the bigger chunk the way a
+                                    // browser would: it reads from disk, once, at startup.
+                                    advancedChunks: {
+                                        groups: [{ name: "vendor", test: /[\\/]node_modules[\\/]/ }],
+                                    },
+                                },
                             },
                         },
                         resolve: { noExternal: bundledClientPackages },
@@ -6369,6 +6570,7 @@ export function rscKit(options = {}) {
         metadataRoutesPlugin(),
         openApiPlugin(),
         extendableClientReferences(),
+        stableComponentNames(),
         typecheckPlugin(),
         clientImportsAudit(),
         routesPlugin,