@rsc-kit/core 0.30.13 → 0.30.15

package/dist/vite.js

@@ -24,7 +24,7 @@ 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";
+import { ASSET_BASE, allAppAssets, assetFile, appAssets, headTags, shareImageUrls, typeOf, } from "./appAssets.js";
 import { reactCacheImports } from "./reactCache.js";
 import { clientEntries, clientScanPlugin, engineClientEntries, } from "./clientEntries.js";
 import { serverImportsOfClientPackages } from "./clientImports.js";
@@ -157,6 +157,7 @@ let typesDir;
 let hotFile;
 let hostCallOptions;
 let packageDir;
+let backendPaths = [];
 let hostGlobal;
 let interceptManifestFile;
 let packageAlias;
@@ -194,8 +195,7 @@ let foundAssets = {
     appleIcon: null,
     appleSplash: [],
     screenshots: [],
-    openGraph: null,
-    twitter: null,
+    shareImages: {},
 };
 /** Host functions to generate stubs for — see RscKitOptions.hostActions. */
 let hostActions;
@@ -348,6 +348,34 @@ function aliasEntries() {
     });
     return entries;
 }
+/**
+ * The prefixes a backend owns, as the matcher reads them: `/auth`, no trailing
+ * slash. Refused rather than corrected where a mistake would silently send the
+ * whole app, or its own endpoints, to the backend.
+ */
+export function normaliseBackendPaths(paths) {
+    const out = [];
+    for (const raw of paths ?? []) {
+        const given = typeof raw === "string" ? raw.trim() : "";
+        if (!given.startsWith("/")) {
+            throw new Error(`[rsc-kit] backendPaths: ${JSON.stringify(raw)} is not a path. Each starts with a slash, as in '/auth'.`);
+        }
+        // After the slash check, so "/" is the root and not "not a path".
+        const path = given.replace(/\/+$/, "");
+        if (path === "") {
+            throw new Error("[rsc-kit] backendPaths: '/' is every url, and nothing would be left for this app. Name the prefixes the backend owns.");
+        }
+        if (path === "/_rsc" || path.startsWith("/_rsc/")) {
+            throw new Error(`[rsc-kit] backendPaths: ${JSON.stringify(raw)} is this package's own endpoint, which the renderer answers.`);
+        }
+        if (/[?#*]/.test(path)) {
+            throw new Error(`[rsc-kit] backendPaths: ${JSON.stringify(raw)} is a prefix, not a pattern: no query, fragment or wildcard.`);
+        }
+        if (!out.includes(path))
+            out.push(path);
+    }
+    return out;
+}
 function resolvePaths(options) {
     projectRoot = resolve(options.projectRoot || process.env.RSC_PROJECT_ROOT || process.cwd());
     sourceDir = resolve(options.sourceDir || process.env.RSC_SOURCE_DIR || join(projectRoot, "src"));
@@ -385,6 +413,7 @@ function resolvePaths(options) {
     hotFile = options.hotFile || process.env.RSC_HOT_FILE || "";
     hostCallOptions = options.hostCall;
     packageDir = resolve(options.packageDir || process.env.RSC_PACKAGE_DIR || thisDir());
+    backendPaths = normaliseBackendPaths(options.backendPaths);
     hostGlobal = options.hostGlobal || process.env.RSC_HOST_GLOBAL || "rpc";
     interceptManifestFile = resolve(options.interceptManifestFile ||
         process.env.RSC_INTERCEPT_MANIFEST ||
@@ -1363,7 +1392,7 @@ function copyAppAssets(clientDir) {
     if (all.length === 0)
         return;
     for (const asset of all) {
-        const to = join(clientDir, asset.href.slice(1));
+        const to = join(clientDir, assetFile(asset.href.slice(1)));
         mkdirSync(dirname(to), { recursive: true });
         copyFileSync(join(sourceDir, "app", asset.file), to);
     }
@@ -2394,6 +2423,8 @@ const API_METHODS = [
 ];
 /** `orders.section.tsx` — a region of a page that can be refreshed by name. */
 const SECTION_FILE = /\.section\.(tsx|jsx|ts|js)$/;
+/** A share image file: the pages beneath its folder change what they say about themselves. */
+const SHARE_IMAGE_FILE = /^(?:opengraph|twitter)-image[-\w]*\.(?:png|svg|jpe?g|webp|gif|avif)$/i;
 /**
  * Whether a page or a section declares refreshOn. Read from the source, as
  * section names are, because the manifest is written before any bundle exists.
@@ -2769,17 +2800,40 @@ function fallbackOrigin(): string {
 const FALLBACK_MARKER = 'x-rsc-renderer-fallback'
 const PROXIED_MARKER = 'x-rsc-proxied-by-backend'
 `;
+/**
+ * The urls the app said belong to the backend, tested before any page is
+ * matched. Emitted in both variants: a test's stand-in backend is reached by
+ * the same prefixes as the real one.
+ */
+function backendPathConsts() {
+    return `const BACKEND_PATHS: string[] = ${JSON.stringify(backendPaths)}
+
+// A prefix at a segment boundary: '/auth' is '/auth' and what is under it, not '/authors'.
+function onBackendPath(pathname: string): boolean {
+  return BACKEND_PATHS.some((prefix) => pathname === prefix || pathname.startsWith(prefix + '/'))
+}
+`;
+}
 /** With no backend configured: this app's not-found page, or a test's backend. */
-const NO_FALLBACK_BODY = `  const answer = await devHandler(request)
+const NO_FALLBACK_BODY = `  // The app named this prefix as the backend's: no page is asked about it, so one
+  // that matches (a dynamic root route) cannot answer for it.
+  const toBackend = onBackendPath(new URL(request.url).pathname)
+  const answer = toBackend ? null : await devHandler(request)
 
   if (answer) return answer
 
-  if (backendForward && !pageSaidNotFound(request)) return await backendForward(request)
+  if (backendForward && (toBackend || !pageSaidNotFound(request))) return await backendForward(request)
 
   return await notFound(request)
 `;
 const FALLBACK_BODY = `  const FALLBACK_ORIGIN = fallbackOrigin()
-  const answer = await devHandler(request)
+
+  // The app named this prefix as the backend's (rscKit({ backendPaths })): no
+  // page is asked about it. A dynamic root route such as [team]/[app] matches
+  // /gitlab/connect, renders, says notFound() - and a page that said that is not
+  // forwarded, so the backend's own route was the not-found page.
+  const toBackend = onBackendPath(new URL(request.url).pathname)
+  const answer = toBackend ? null : await devHandler(request)
 
   if (answer) return answer
 
@@ -2787,7 +2841,7 @@ const FALLBACK_BODY = `  const FALLBACK_ORIGIN = fallbackOrigin()
   // its guard, or a backend's 404. That is this app's not-found.tsx, not a
   // url for the backend: forwarded, the backend answered with its own 404
   // and the app's never showed.
-  if (pageSaidNotFound(request)) return await notFound(request)
+  if (!toBackend && pageSaidNotFound(request)) return await notFound(request)
 
   // Nothing here owns this url. In development the backend usually does — a
   // Blade page, /login, a webhook, an uploaded file under /storage — so the
@@ -3093,6 +3147,7 @@ ${
 import { SegmentBoundary } from ${JSON.stringify(join(packageDir, "js/SegmentBoundary"))}
 import { LoadingBoundary } from ${JSON.stringify(join(packageDir, "js/LoadingBoundary"))}
 import { DocumentTitle } from ${JSON.stringify(join(packageDir, "js/DocumentTitle"))}
+import { depthOf, fileWins, folderOf, nearestShareImage } from ${JSON.stringify(join(packageDir, "shareImages"))}
 import { SlotBoundary } from ${JSON.stringify(join(packageDir, "js/SlotBoundary"))}
 import { RouteErrorBoundary } from ${JSON.stringify(join(packageDir, "js/RouteErrorBoundary"))}
 import __rsc_assets from 'virtual:vite-rsc/assets-manifest'
@@ -3146,6 +3201,9 @@ ${mapEntries.join("\n")}
 /** Head tags for the icons and share images found in app/. */
 const APP_HEAD: { tag: any; props: Record<string, string> }[] = ${JSON.stringify(headTags(foundAssets))}
 
+/** The share images found under app/, by the folder each is in - see shareImages.ts. */
+const SHARE_IMAGES: Record<string, { openGraph?: string; twitter?: string }> = ${JSON.stringify(shareImageUrls(foundAssets))}
+
 const WEB_MANIFEST: { href: string; themeColor?: string } | null = ${JSON.stringify(webManifestOptions
         ? {
             href: MANIFEST_PATH,
@@ -4146,13 +4204,35 @@ async function renderTree(
     }
 
     for (const [i, found] of APP_HEAD.entries()) {
-      const props = { ...found.props }
+      head.push(createElement(found.tag, { key: '__a' + i, ...found.props }))
+    }
 
-      if (props.content && /^(og:image|twitter:image)$/.test(props.property ?? props.name ?? '')) {
-        props.content = absolute(props.content)
-      }
+    // The share image files found in app/. The nearest to this page is its
+    // card - unless its metadata exports images from a segment nearer still,
+    // in which case the file is left out and the exported ones render, so a
+    // page that names its own image replaces the site's instead of following
+    // it. Scrapers read the first og:image they meet; a second after the
+    // site's would be a card that never changes.
+    const folder = folderOf(component)
+    const sources = md ? imageSources.get(md) : undefined
+    const shared = (kind: 'openGraph' | 'twitter') => {
+      const file = nearestShareImage(SHARE_IMAGES, folder, kind)
+      const source = sources?.[kind]
+
+      return fileWins(file, source?.exports ? source : null) ? file : null
+    }
+    const ogFile = shared('openGraph')
+    const twitterFile = shared('twitter')
 
-      head.push(createElement(found.tag, { key: '__a' + i, ...props }))
+    if (ogFile) head.push(createElement('meta', { key: '__og', property: 'og:image', content: absolute(ogFile.href) }))
+
+    if (twitterFile) {
+      head.push(createElement('meta', { key: '__tw', name: 'twitter:image', content: absolute(twitterFile.href) }))
+
+      // The card a twitter image implies, unless the page named its own.
+      if ((md?.twitter as { card?: unknown } | undefined)?.card == null) {
+        head.push(createElement('meta', { key: '__twc', name: 'twitter:card', content: 'summary_large_image' }))
+      }
     }
 
     if (md) {
@@ -4252,7 +4332,7 @@ async function renderTree(
         if (og.siteName != null) head.push(tag('og:site_name', og.siteName))
         if (og.type != null) head.push(tag('og:type', og.type))
         if (og.locale != null) head.push(tag('og:locale', og.locale))
-        if (og.images != null) images('og:image', og.images)
+        if (og.images != null && !ogFile) images('og:image', og.images)
       }
 
       if (md.twitter) {
@@ -4263,7 +4343,7 @@ async function renderTree(
         if (tw.description != null) head.push(tag('twitter:description', tw.description))
         if (tw.site != null) head.push(tag('twitter:site', tw.site))
         if (tw.creator != null) head.push(tag('twitter:creator', tw.creator))
-        if (tw.images != null) images('twitter:image', tw.images)
+        if (tw.images != null && !twitterFile) images('twitter:image', tw.images)
       }
 
       // icons is links, not meta. A string is one icon; an object names which
@@ -5156,6 +5236,17 @@ const METADATA_PROBE_GRACE_MS = 20
 
 const METADATA_POSTPONED = Symbol('metadata postponed')
 
+/**
+ * For each of openGraph and twitter, how deep the segment that supplied the
+ * merged object is, and whether it exports images - the other half of the
+ * comparison a share image file is held to. Beside the metadata rather than
+ * inside it, so the object a page's tags are rendered from stays only what
+ * the app wrote.
+ */
+type ImageSources = { openGraph?: { depth: number; exports: boolean }; twitter?: { depth: number; exports: boolean } }
+
+const imageSources = new WeakMap<object, ImageSources>()
+
 export async function resolveMetadata(
   component: string,
   props: Record<string, unknown> = {},
@@ -5220,18 +5311,27 @@ export async function resolveMetadata(
   // happened to declare one of its own.
   const merged: Record<string, unknown> = {}
   const other: Record<string, unknown> = {}
+  const sources: ImageSources = {}
 
-  const take = (from: Record<string, unknown>) => {
+  const take = (from: Record<string, unknown>, depth: number) => {
     for (const [k, v] of Object.entries(from)) {
       if (k === 'title') continue
       if (k === 'other') Object.assign(other, v as Record<string, unknown>)
       else merged[k] = v
+
+      // openGraph and twitter are replaced whole by a nearer segment's, so
+      // whichever segment took them last is the one whose images - or lack of
+      // them - the merged object carries. That segment's depth is what a file
+      // in app/ is weighed against; see shareImages.ts.
+      if (k === 'openGraph' || k === 'twitter') {
+        sources[k] = { depth, exports: typeof v === 'object' && v !== null && (v as { images?: unknown }).images != null }
+      }
     }
   }
 
-  for (const m of layoutMeta) take(m)
+  layoutMeta.forEach((m, i) => take(m, depthOf(folderOf(layouts[i].component))))
 
-  take(page)
+  take(page, depthOf(folderOf(component)))
 
   if (Object.keys(other).length > 0) merged.other = other
 
@@ -5256,7 +5356,11 @@ export async function resolveMetadata(
   }
   if (title != null) merged.title = title
 
-  return Object.keys(merged).length ? merged : null
+  if (Object.keys(merged).length === 0) return null
+
+  imageSources.set(merged, sources)
+
+  return merged
 }
 
 // Buffered render (worker: rsc / rscWithoutCallbacks — used at prerender time).
@@ -5707,7 +5811,7 @@ export async function handleRscPprShell(
  * server rendering live pages it had already frozen. The gate is the mode, not
  * the file.
  */
-${fallbackOrigin === false ? "" : FALLBACK_CONSTS.replace("__ORIGIN__", JSON.stringify(fallbackOrigin))}${NITRO_HOST_CALLS}
+${backendPathConsts()}${fallbackOrigin === false ? "" : FALLBACK_CONSTS.replace("__ORIGIN__", JSON.stringify(fallbackOrigin))}${NITRO_HOST_CALLS}
 let devHandler: ((request: Request) => Promise<Response | null>) | null = null
 
 export default async function handler(request: Request): Promise<Response> {
@@ -7584,7 +7688,8 @@ export function rscKit(options = {}) {
                         res.end(webManifest(webManifestOptions));
                         return;
                     }
-                    const asset = allAppAssets(foundAssets).find((a) => a.href === url);
+                    // Either spelling of a bracket: the tag says %5B, a hand-typed url says [.
+                    const asset = allAppAssets(foundAssets).find((a) => assetFile(a.href) === assetFile(url));
                     const file = asset ? join(sourceDir, "app", asset.file) : null;
                     if (!asset || !file || !existsSync(file))
                         return next();
@@ -7671,6 +7776,7 @@ export function rscKit(options = {}) {
                     // published without any — generic-host.test.ts fails if it reappears.
                     return ((base !== stem && shapes.has(stem)) ||
                         SECTION_FILE.test(base) ||
+                        SHARE_IMAGE_FILE.test(base) ||
                         (routeConfig !== null && base === routeConfig.file));
                 };
                 const restart = (file) => {