@rsc-kit/core 0.7.2 → 0.9.0

package/dist/vite.d.ts

@@ -4,6 +4,30 @@ export interface RscKitOptions {
     projectRoot?: string;
     /** Directory holding the app/ route tree. Defaults to `src`. */
     sourceDir?: string;
+    /**
+     * Animate navigations with React's `<ViewTransition>`.
+     *
+     * Off by default and a build-time constant rather than a runtime setting, so
+     * an app that does not ask for it does not carry the boundary at all.
+     *
+     * Needs react and react-dom at 19.3 or newer, where ViewTransition is
+     * stable. What it animates is the segment a navigation replaces; what a page
+     * does inside itself is the app's own business and needs no flag.
+     */
+    viewTransitions?: boolean;
+    /**
+     * Serve the app from a service worker, so it survives a reload with no
+     * network at all.
+     *
+     * Everything else this engine keeps — held pages, the prefetch cache — lives
+     * in one page's memory. Reload with no network and the browser shows its own
+     * error page: no script runs, so nothing cached in JavaScript is reachable.
+     * A worker is the only thing on the other side of that line.
+     *
+     * Off by default. It changes what a visitor sees when your deploy is broken,
+     * which is not a decision to make for someone.
+     */
+    offline?: boolean;
     /** Where the server bundles and generated entries go. Defaults to `.rsc`. */
     outDir?: string;
     /**
@@ -144,4 +168,25 @@ export interface RscKitOptions {
      */
     prerender?: boolean;
 }
+/**
+ * The service worker, written into the client output at build time.
+ *
+ * Scoped to the site root because it is served from there, so it sees every
+ * navigation. Three kinds of request, three answers:
+ *
+ * Hashed assets are immutable by construction — the name changes when the
+ * bytes do — so they are answered from the cache and only fetched once ever.
+ *
+ * Documents and payloads go to the network first and fall back to the cache,
+ * because a page whose data moved on should say so while there is a network to
+ * ask. Only the fallback is what makes a reload work with none.
+ *
+ * A document and its payload share a url and differ by header. They do not
+ * collide, because the server sends `Vary: X-RSC, ...` and the Cache API
+ * honours it when a Response is stored whole and matched with its Request.
+ *
+ * Nothing else is touched. An action is a POST and must never be answered from
+ * a cache; anything cross-origin is somebody else's to cache.
+ */
+export declare const SERVICE_WORKER: (version: string, precache: string[]) => string;
 export declare function rscKit(options?: RscKitOptions): PluginOption[];

package/dist/vite.js

@@ -13,6 +13,7 @@
 // the structural config (entries, output dirs, base). @vitejs/plugin-rsc is
 // included here so it always runs before any react() layer the app adds.
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -52,6 +53,10 @@ let routeConfig;
 let prerenderAfterBuild;
 /** True during `vite build --watch`, where re-rendering every route is noise. */
 let isWatch = false;
+/** Whether navigations are wrapped in React's ViewTransition — see options. */
+let viewTransitions = false;
+/** Whether a service worker is generated and registered — see options. */
+let offline = false;
 /** Host functions to generate stubs for — see RscKitOptions.hostActions. */
 let hostActions;
 /**
@@ -193,6 +198,8 @@ function resolvePaths(options) {
     // A host driving the build out of process cannot pass an option, and may
     // prerender itself afterwards with paths only it knows.
     prerenderAfterBuild = options.prerender ?? process.env.RSC_PRERENDER !== '0';
+    viewTransitions = options.viewTransitions === true;
+    offline = options.offline === true;
     hostActions = options.hostActions ?? fileHostActions(projectRoot);
 }
 function log(...args) {
@@ -406,10 +413,19 @@ function warnIfTypesUnreachable() {
         const include = JSON.parse(text).include;
         if (!Array.isArray(include))
             return;
-        if (include.some((entry) => typeof entry === 'string' && entry.includes('.rsc-kit')))
-            return;
-        log(`tsconfig.json does not include .rsc-kit, where the generated types are written.\n` +
-            `  Add ".rsc-kit/**/*" to "include", or typed routes and rpc() fall back to string.`);
+        const covers = (what) => include.some((entry) => typeof entry === 'string' && entry.includes(what));
+        if (!covers('.rsc-kit')) {
+            log(`tsconfig.json does not include .rsc-kit, where the generated types are written.\n` +
+                `  Add ".rsc-kit/**/*" to "include", or typed routes and rpc() fall back to string.`);
+        }
+        // Only when there is something there to check. An app with no api routes
+        // has nothing to be warned about, and a warning it cannot act on is one it
+        // learns to scroll past.
+        if (existsSync(join(projectRoot, 'server')) && !covers('server')) {
+            log(`tsconfig.json does not include server/, where your api handlers live.\n` +
+                `  Add "server/**/*" to "include", or they are not type-checked at all — ` +
+                `a handler returning the wrong shape builds and deploys without complaint.`);
+        }
     }
     catch {
         // An unparseable tsconfig is the project's own problem, not this one's.
@@ -444,10 +460,6 @@ function writeHostBindings(manifest) {
     // and a typecheck cannot see it. Written whether or not there are actions:
     // server components call it directly too.
     writeFileSync(join(typesDir, 'rsc-env.d.ts'), renderHostGlobalTypes());
-    // The engine's own ambient types, copied where the app's typechecker will
-    // see them. Deliberately a separate file from the one above: this one is
-    // the engine's and identical everywhere, that one is generated from how
-    // this host is configured.
     // The urls this build found, so a link to a page that does not exist fails
     // the typecheck instead of the browser.
     writeFileSync(join(typesDir, 'rsc-routes.d.ts'), renderRouteTypes(manifest));
@@ -456,10 +468,6 @@ function writeHostBindings(manifest) {
     // an app-authored one goes stale — the first version named only RscEngine,
     // which typechecks a server and fails a prerender script.
     writeFileSync(join(typesDir, 'rsc-engine.d.ts'), ENGINE_TYPES);
-    const engineTypes = join(packageDir, 'types.d.ts');
-    if (existsSync(engineTypes)) {
-        writeFileSync(join(typesDir, 'rsc-types.d.ts'), readFileSync(engineTypes, 'utf-8'));
-    }
     warnIfTypesUnreachable();
     const target = join(sourceDir, 'server-actions.generated.ts');
     // A host with no functions of its own leaves no file behind: kept, its
@@ -519,6 +527,200 @@ function reportAllDynamic() {
 
   ${routes.length} dynamic — prerendering is off`);
 }
+/**
+ * The service worker, written into the client output at build time.
+ *
+ * Scoped to the site root because it is served from there, so it sees every
+ * navigation. Three kinds of request, three answers:
+ *
+ * Hashed assets are immutable by construction — the name changes when the
+ * bytes do — so they are answered from the cache and only fetched once ever.
+ *
+ * Documents and payloads go to the network first and fall back to the cache,
+ * because a page whose data moved on should say so while there is a network to
+ * ask. Only the fallback is what makes a reload work with none.
+ *
+ * A document and its payload share a url and differ by header. They do not
+ * collide, because the server sends `Vary: X-RSC, ...` and the Cache API
+ * honours it when a Response is stored whole and matched with its Request.
+ *
+ * Nothing else is touched. An action is a POST and must never be answered from
+ * a cache; anything cross-origin is somebody else's to cache.
+ */
+export const SERVICE_WORKER = (version, precache) => `// GENERATED by rscKit() — do not edit.
+const VERSION = ${JSON.stringify(version)}
+const CACHE = 'rsc-kit-' + VERSION
+const PRECACHE = ${JSON.stringify(precache, null, 2)}
+
+self.addEventListener('install', (event) => {
+  // The new worker takes over rather than waiting for every tab to close.
+  // Safe here because assets are content-hashed: a page already open keeps
+  // asking for the names it was built with, and those are still cached under
+  // their own version until this activates and sweeps.
+  event.waitUntil(caches.open(CACHE).then((cache) => cache.addAll(PRECACHE)).then(() => self.skipWaiting()))
+})
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    caches
+      .keys()
+      .then((keys) => Promise.all(keys.filter((k) => k.startsWith('rsc-kit-') && k !== CACHE).map((k) => caches.delete(k))))
+      .then(() => self.clients.claim()),
+  )
+})
+
+const immutable = (url) => url.pathname.startsWith('/assets/') || /-[A-Za-z0-9_-]{8,}\\.[a-z]+$/.test(url.pathname)
+
+// Whether a response may be kept at all.
+//
+// \`no-store\` is not advice here, it is the answer. A query defaults to
+// \`private, no-store\` precisely because it may read the session, and a worker
+// that files it by url alone would serve one visitor's answer to whoever signs
+// in next — the Cache API has no notion of who asked. A live response is worse
+// again: the clone goes on streaming long after the page that opened it is
+// gone.
+//
+// Checked before every put, rather than only for the paths that happen to reach
+// a query today. A new cacheable route added later must not have to remember
+// this.
+const mayStore = (response) =>
+  response.ok && !(response.headers.get('Cache-Control') || '').includes('no-store')
+
+// What a response is filed under. A payload request carries headers the url
+// does not, so the url is where they have to go.
+const keyFor = (request) => {
+  if (!request.headers.get('X-RSC')) return request
+
+  const url = new URL(request.url)
+  url.searchParams.set('__rsc', request.headers.get('X-RSC-Segments') || '')
+
+  return new Request(url, { headers: request.headers })
+}
+
+self.addEventListener('fetch', (event) => {
+  const request = event.request
+  const url = new URL(request.url)
+
+  if (request.method !== 'GET' || url.origin !== self.location.origin) return
+
+  if (immutable(url)) {
+    event.respondWith(
+      caches.match(request).then(
+        (hit) =>
+          hit ??
+          fetch(request).then((response) => {
+            if (mayStore(response)) {
+              const copy = response.clone()
+              caches.open(CACHE).then((cache) => cache.put(request, copy))
+            }
+
+            return response
+          }),
+      ),
+    )
+
+    return
+  }
+
+  event.respondWith(
+    fetch(request)
+      .then((response) => {
+        if (mayStore(response)) {
+          const copy = response.clone()
+          caches.open(CACHE).then((cache) => cache.put(keyFor(request), copy))
+
+          // A document is not enough to boot from. The client hydrates from a
+          // payload it fetches for itself, and on a first visit that request
+          // happens before this worker controls the page — so it is never
+          // cached, and a reload with no network has the markup and nothing to
+          // hydrate it with.
+          //
+          // \`X-RSC: true\` and no segments header is exactly what a fresh boot
+          // sends, which is what makes this entry the one it finds: the server
+          // varies on those, and the Cache API matches on the same.
+          if (request.mode === 'navigate') {
+            const warm = new Request(request.url, { headers: { 'X-RSC': 'true' } })
+
+            fetch(warm)
+              .then((payload) => {
+                if (mayStore(payload)) {
+                  caches.open(CACHE).then((cache) => cache.put(keyFor(warm), payload))
+                }
+              })
+              .catch(() => {})
+          }
+
+          // And the other way round. Moving between pages fetches payloads and
+          // never documents, so a page reached only by a link had nothing to
+          // serve when someone reloaded its url — it navigated fine and then
+          // died on refresh, which is the half of offline nobody would trust.
+          //
+          // Once per url: the document is fetched only when the cache has none,
+          // so this costs one extra request the first time a page is visited
+          // rather than one on every navigation to it.
+          if (request.headers.get('X-RSC')) {
+            const document = new Request(request.url)
+
+            caches.open(CACHE).then(async (cache) => {
+              if (await cache.match(document)) return
+
+              const fresh = await fetch(document).catch(() => null)
+
+              if (fresh && mayStore(fresh)) await cache.put(document, fresh)
+            })
+          }
+        }
+
+        return response
+      })
+      .catch(async () => {
+        const hit = await caches.match(keyFor(request))
+
+        if (hit) return hit
+
+        // Nothing cached for this url and no network to ask. Falling back to
+        // the cached root was worse than failing: the document IS the page
+        // here, so the visitor got the home page's markup under the address
+        // they asked for, and it did not hydrate — a wrong page pretending to
+        // be the right one. Letting it fail says what is true, and a page
+        // already open is unaffected.
+        return Response.error()
+      }),
+  )
+})
+`;
+/**
+ * Write the worker beside the assets it caches.
+ *
+ * The version is a hash of what is being precached rather than a build id from
+ * the environment. The names are content-hashed already, so a build that
+ * changed nothing produces the same list and leaves the visitor's cache alone,
+ * and a build that changed anything produces a different one — which is the
+ * whole of cache invalidation, without asking anyone to set a variable.
+ */
+function writeServiceWorker(clientDir) {
+    if (!existsSync(clientDir))
+        return;
+    const files = [];
+    const walk = (dir, prefix) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            // Not itself, and not a map: a debugger asks for those, a visitor does
+            // not, and precaching them doubles what an install costs.
+            if (entry.name === 'sw.js' || entry.name.endsWith('.map'))
+                continue;
+            const path = join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(path, `${prefix}${entry.name}/`);
+            else
+                files.push(`${prefix}${entry.name}`);
+        }
+    };
+    walk(clientDir, '');
+    const precache = ['/', ...files.map((file) => `/${file}`)].sort();
+    const version = createHash('sha256').update(precache.join('\n')).digest('hex').slice(0, 12);
+    writeFileSync(join(clientDir, 'sw.js'), SERVICE_WORKER(version, precache));
+    log(`offline: ${precache.length} files precached as rsc-kit-${version}`);
+}
 /**
  * The rsc bundle the build just wrote, whatever it decided to call it.
  *
@@ -990,6 +1192,7 @@ import { createRscHandler } 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, loadServerAction } from '@vitejs/plugin-rsc/rsc'
+import { isQuery, queryCacheControl } from ${JSON.stringify(join(packageDir, 'query'))}
 import { Suspense, createElement, Fragment } from 'react'
 import { AsyncLocalStorage } from 'node:async_hooks'
 ${imports.join('\n')}
@@ -1290,7 +1493,14 @@ async function renderTree(
       if (bootstrap) head.push(createElement(DocumentTitle, { key: '__ts', title: String(md.title) }))
     }
     if (md.description != null) head.push(createElement('meta', { key: '__d', name: 'description', content: String(md.description) }))
-    for (const [k, v] of Object.entries(md)) {
+    // 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 named = Object.entries(md).filter(([k]) => k !== 'other')
+    const extra = Object.entries((md.other ?? {}) as Record<string, unknown>)
+
+    for (const [k, v] of [...named, ...extra]) {
       if (k === 'title' || k === 'description' || v == null) continue
       head.push(createElement('meta', { key: '__m_' + k, name: k, content: String(v) }))
     }
@@ -1677,6 +1887,44 @@ async function renderRevalidated(target: string, page: PageContext): Promise<unk
   })
 }
 
+/**
+ * Answer one read.
+ *
+ * Only functions declared with query() are reachable. The id comes off the url,
+ * and every registered server action has one — without the mark, this address
+ * would invoke mutations over GET, for anyone who can fetch it.
+ */
+export async function handleQuery(
+  id: string,
+  args: string,
+  report?: (error: unknown) => string,
+): Promise<{ stream: ReadableStream; cacheControl: string } | null> {
+  applyHost()
+
+  let fn: unknown
+
+  try {
+    fn = await loadServerAction(id)
+  } catch {
+    return null
+  }
+
+  // Null for both, deliberately. Saying "that exists but is not a query" tells
+  // whoever is probing this endpoint which ids are real actions, and the ids
+  // are stable across a build.
+  if (!isQuery(fn)) return null
+
+  const decoded = (await decodeReply(args)) as unknown[]
+  const result = await (fn as (...a: unknown[]) => unknown)(...decoded)
+
+  return {
+    stream: renderToReadableStream(result, {
+      onError: (error: unknown) => (report ? report(error) : 'Query failed.'),
+    }),
+    cacheControl: queryCacheControl(fn),
+  }
+}
+
 export async function handleAction(
   actionId: string,
   body: string | FormData | Uint8Array,
@@ -1723,6 +1971,19 @@ export async function handleAction(
 
   const args = (await decodeReply(decodable)) as unknown[]
   const action = await loadServerAction(actionId)
+
+  // A query reached the ACTION endpoint, which means it was called directly
+  // rather than through fetchQuery — so it went out as a POST and none of the
+  // reasons it was marked a read apply to it. It still works, which is the
+  // problem: nothing else would ever mention it. Only in development, and only
+  // a warning, because the call is not wrong, just not what was asked for.
+  if (isQuery(action) && import.meta.env?.DEV) {
+    console.warn(
+      '[rsc-kit] ' + actionId + ' is a query but was called directly, so it was sent as a POST. ' +
+        'Call it through fetchQuery() to send a GET.',
+    )
+  }
+
   const result = await (action as (...a: unknown[]) => unknown)(...args)
 
   // Read after the action has run: what it invalidated is only known once its
@@ -1764,12 +2025,31 @@ export async function resolveMetadata(
     : {}
 
   // Non-title metadata: layout defaults (outer→inner), page overrides.
+  //
+  // other merges per key rather than being replaced, so a page adding one
+  // custom tag keeps the ones its layout set. Assigning it like any other key
+  // would mean a root layout's theme-color disappearing from every page that
+  // happened to declare one of its own.
   const merged: Record<string, unknown> = {}
+  const other: Record<string, unknown> = {}
+
+  const take = (from: Record<string, unknown>) => {
+    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
+    }
+  }
+
   for (const l of layouts) {
     const s = metadataMap[l.component]?.static
-    if (s) for (const [k, v] of Object.entries(s)) if (k !== 'title') merged[k] = v
+
+    if (s) take(s as Record<string, unknown>)
   }
-  for (const [k, v] of Object.entries(page)) if (k !== 'title') merged[k] = v
+
+  take(page)
+
+  if (Object.keys(other).length > 0) merged.other = other
 
   // Title: the page title with the NEAREST layout title.template applied; if the
   // page has no title, the nearest layout default/string title.
@@ -2128,6 +2408,7 @@ export default async function handler(request: Request): Promise<Response> {
       handleRscPprShell,
       handleRscResume,
       handleAction,
+      handleQuery,
       resolveMetadata,
       runRouteMiddleware,
     } as never,
@@ -2302,7 +2583,25 @@ if (import.meta.hot) {
     void refresh('all')
   })
 }
-`;
+${offline
+        ? `
+// Registered after load rather than during it, so fetching and installing the
+// worker competes with nothing the first visit actually needs. The second
+// visit is the one it is for.
+//
+// Not in development: the dev server is the thing you are editing, and a
+// worker answering from a cache in front of it turns every edit into a
+// question about which copy you are looking at.
+if ('serviceWorker' in navigator && import.meta.env.PROD) {
+  window.addEventListener('load', () => {
+    void navigator.serviceWorker.register('/sw.js').catch(() => {
+      // A worker that will not register is not a reason for the page to fail.
+      // The app works; it just will not survive being reloaded offline.
+    })
+  })
+}
+`
+        : ''}`;
 }
 /**
  * Intercepted URL patterns, published by the host before the build.
@@ -2510,6 +2809,10 @@ export function rscKit(options = {}) {
                  */
                 define: {
                     'process.env.NODE_ENV': JSON.stringify(env.mode === 'development' ? 'development' : 'production'),
+                    // A constant, so the boundary and its import fall out of the bundle
+                    // entirely when this is off rather than shipping a branch nobody takes.
+                    __RSC_VIEW_TRANSITIONS__: JSON.stringify(viewTransitions),
+                    __RSC_OFFLINE__: JSON.stringify(offline),
                 },
                 /*
                  * This package's client modules are served as source, never
@@ -2730,6 +3033,8 @@ export function rscKit(options = {}) {
                 ? join(dirname(clientOut), 'server', NITRO_STATIC_DIR)
                 : join(outDir, NITRO_STATIC_DIR);
             await prerenderAfterBundles(bundle, staticDir, clientOut ?? publicAssetsDir);
+            if (offline)
+                writeServiceWorker(clientOut ?? publicAssetsDir);
         },
         configResolved(config) {
             isWatch = config.build?.watch != null;