@rsc-kit/core 0.18.1 → 0.20.0

package/dist/manifest.d.ts

@@ -82,6 +82,12 @@ export interface ManifestIntercept {
 export interface ManifestApiRoute {
     /** The module name, as the engine's registry keys it. */
     name: string;
+    /**
+     * The file that answers, relative to the source directory - `app/api/x/route.ts`,
+     * or `app/sitemap.ts` for a route the build synthesised from a metadata file
+     * - so a line about the route can say where to look.
+     */
+    source?: string;
     segments: RouteSegment[];
     /** Which methods the file exports, so a 405 can name the rest. */
     methods: string[];

package/dist/manifest.js.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,+EAA+E;AAC/E,gFAAgF;AAChF,uCAAuC;AACvC,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,oBAAoB","sourcesContent":["// The shape of routes.json — what the build discovered, for a host to read.\n//\n// The build already walks app/ to generate its entries, and every host needs\n// the same facts: which url a component answers, what layouts wrap it, which\n// slots and sections belong to it. Laravel used to scan the tree a second time\n// to work that out; a JS host would have had to write a third walk. This is the\n// one answer, and these are its types.\n//\n// Urls are segments rather than a pattern string, because the pattern is the\n// host's dialect: Laravel writes {slug}, Hono writes :slug, and neither is the\n// build's business.\n\nexport interface RouteSegment {\n  /**\n   * `host`: a `[name]` directory at the top of app/. Bound from the request's\n   * host, never from a path segment - so `example.com/nope` is a 404 rather\n   * than a tenant called \"nope\". See hostRouting.\n   */\n  type: \"static\" | \"param\" | \"catchAll\" | \"host\";\n  value: string;\n}\n\nexport interface ManifestRoute {\n  component: string;\n  segments: RouteSegment[];\n  layouts: string[];\n  loadings: string[];\n  /**\n   * `error.tsx` files above this route, outermost first.\n   *\n   * The nearest one to a failure catches it, the same way the nearest\n   * `loading.tsx` is the fallback. Optional: a manifest from a build before\n   * error boundaries existed has none.\n   */\n  errors?: string[];\n  /**\n   * `middleware.ts` files above this route, outermost first.\n   *\n   * Run before anything at or below them renders, on every path. A check is\n   * not UI, and making it a layout meant the client could decline it: layouts\n   * are skipped on a partial navigation, and what gets skipped is named in a\n   * header nothing can verify.\n   */\n  middleware: string[];\n  slots: Record<string, string>;\n  sections: string[];\n  /**\n   * The host's route-config file beside this page, if it named one, and the\n   * ancestor ones that also apply — outermost first, this page's excluded.\n   *\n   * Relative to the project root: an absolute path is true only on the machine\n   * that produced it, and building in a container is ordinary.\n   */\n  config: string | null;\n  ancestorConfigs: string[];\n  /**\n   * Host middleware names for this route, outermost first.\n   *\n   * Declared in a route.ts beside or above the page. The engine does not know\n   * what they mean — they are the host's own vocabulary — it only runs them\n   * past the host before anything at or below this route renders.\n   *\n   * Empty on a route that named none, and on every route in an app that never\n   * wrote a route.ts, which is why this needs no flag.\n   *\n   * Optional because registration boots from the PREVIOUS build's manifest: a\n   * shape change takes two builds to settle, and a required field would make\n   * the first of those a hard failure rather than a route with no guards.\n   */\n  hostMiddleware?: string[];\n  /**\n   * Whether the page exports generateStaticParams.\n   *\n   * Recorded here so a host can plan a build — which routes to ask for urls,\n   * which to leave on demand — without loading the server bundle first. The\n   * function itself is reached through the bundle's getStaticParams(), because\n   * only the bundle can run it.\n   */\n  staticParams: boolean;\n}\n\nexport interface ManifestIntercept {\n  component: string;\n  slot: string;\n  segments: RouteSegment[];\n  /** (.) same level, (..) one up, (...) from the root. */\n  marker: string;\n}\n\n/**\n * A `route.ts` — an api endpoint rather than a page.\n *\n * Separate from `routes` because it is matched before them and answered\n * without rendering anything: no layouts, no payload, no client. A url cannot\n * be both, and the build refuses one that is.\n */\nexport interface ManifestApiRoute {\n  /** The module name, as the engine's registry keys it. */\n  name: string;\n  segments: RouteSegment[];\n  /** Which methods the file exports, so a 405 can name the rest. */\n  methods: string[];\n  /**\n   * `middleware.ts` files above this route, outermost first.\n   *\n   * The same chain a page in that directory runs. A route.ts sits among the\n   * pages it belongs with, so a guard on the directory covers it too —\n   * anything else would mean adding an endpoint under a guarded path silently\n   * opened a hole in it.\n   */\n  middleware: string[];\n}\n\nexport interface RouteManifest {\n  version: number;\n  build: {\n    output: string;\n    exportPath: string;\n    payloadName: string;\n    /**\n     * The site's own hosts, bare and lower-case. A request from any other\n     * host is matched with that host's segment in front of its path - see\n     * hostRouting. Absent or empty: every request is the site's own.\n     */\n    hosts?: string[];\n    /**\n     * Whether every response says what built it: `X-Powered-By: rsc-kit` and\n     * a generator meta tag in the document. The name only, never the version.\n     * `X-RSC-Kit` (how a response was served) is sent regardless.\n     */\n    identify?: boolean;\n  };\n  routes: ManifestRoute[];\n  intercepts: ManifestIntercept[];\n  /** Optional: a manifest from a build before api routes existed has none. */\n  apis?: ManifestApiRoute[];\n}\n"]}
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,+EAA+E;AAC/E,gFAAgF;AAChF,uCAAuC;AACvC,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,oBAAoB","sourcesContent":["// The shape of routes.json — what the build discovered, for a host to read.\n//\n// The build already walks app/ to generate its entries, and every host needs\n// the same facts: which url a component answers, what layouts wrap it, which\n// slots and sections belong to it. Laravel used to scan the tree a second time\n// to work that out; a JS host would have had to write a third walk. This is the\n// one answer, and these are its types.\n//\n// Urls are segments rather than a pattern string, because the pattern is the\n// host's dialect: Laravel writes {slug}, Hono writes :slug, and neither is the\n// build's business.\n\nexport interface RouteSegment {\n  /**\n   * `host`: a `[name]` directory at the top of app/. Bound from the request's\n   * host, never from a path segment - so `example.com/nope` is a 404 rather\n   * than a tenant called \"nope\". See hostRouting.\n   */\n  type: \"static\" | \"param\" | \"catchAll\" | \"host\";\n  value: string;\n}\n\nexport interface ManifestRoute {\n  component: string;\n  segments: RouteSegment[];\n  layouts: string[];\n  loadings: string[];\n  /**\n   * `error.tsx` files above this route, outermost first.\n   *\n   * The nearest one to a failure catches it, the same way the nearest\n   * `loading.tsx` is the fallback. Optional: a manifest from a build before\n   * error boundaries existed has none.\n   */\n  errors?: string[];\n  /**\n   * `middleware.ts` files above this route, outermost first.\n   *\n   * Run before anything at or below them renders, on every path. A check is\n   * not UI, and making it a layout meant the client could decline it: layouts\n   * are skipped on a partial navigation, and what gets skipped is named in a\n   * header nothing can verify.\n   */\n  middleware: string[];\n  slots: Record<string, string>;\n  sections: string[];\n  /**\n   * The host's route-config file beside this page, if it named one, and the\n   * ancestor ones that also apply — outermost first, this page's excluded.\n   *\n   * Relative to the project root: an absolute path is true only on the machine\n   * that produced it, and building in a container is ordinary.\n   */\n  config: string | null;\n  ancestorConfigs: string[];\n  /**\n   * Host middleware names for this route, outermost first.\n   *\n   * Declared in a route.ts beside or above the page. The engine does not know\n   * what they mean — they are the host's own vocabulary — it only runs them\n   * past the host before anything at or below this route renders.\n   *\n   * Empty on a route that named none, and on every route in an app that never\n   * wrote a route.ts, which is why this needs no flag.\n   *\n   * Optional because registration boots from the PREVIOUS build's manifest: a\n   * shape change takes two builds to settle, and a required field would make\n   * the first of those a hard failure rather than a route with no guards.\n   */\n  hostMiddleware?: string[];\n  /**\n   * Whether the page exports generateStaticParams.\n   *\n   * Recorded here so a host can plan a build — which routes to ask for urls,\n   * which to leave on demand — without loading the server bundle first. The\n   * function itself is reached through the bundle's getStaticParams(), because\n   * only the bundle can run it.\n   */\n  staticParams: boolean;\n}\n\nexport interface ManifestIntercept {\n  component: string;\n  slot: string;\n  segments: RouteSegment[];\n  /** (.) same level, (..) one up, (...) from the root. */\n  marker: string;\n}\n\n/**\n * A `route.ts` — an api endpoint rather than a page.\n *\n * Separate from `routes` because it is matched before them and answered\n * without rendering anything: no layouts, no payload, no client. A url cannot\n * be both, and the build refuses one that is.\n */\nexport interface ManifestApiRoute {\n  /** The module name, as the engine's registry keys it. */\n  name: string;\n  /**\n   * The file that answers, relative to the source directory - `app/api/x/route.ts`,\n   * or `app/sitemap.ts` for a route the build synthesised from a metadata file\n   * - so a line about the route can say where to look.\n   */\n  source?: string;\n  segments: RouteSegment[];\n  /** Which methods the file exports, so a 405 can name the rest. */\n  methods: string[];\n  /**\n   * `middleware.ts` files above this route, outermost first.\n   *\n   * The same chain a page in that directory runs. A route.ts sits among the\n   * pages it belongs with, so a guard on the directory covers it too —\n   * anything else would mean adding an endpoint under a guarded path silently\n   * opened a hole in it.\n   */\n  middleware: string[];\n}\n\nexport interface RouteManifest {\n  version: number;\n  build: {\n    output: string;\n    exportPath: string;\n    payloadName: string;\n    /**\n     * The site's own hosts, bare and lower-case. A request from any other\n     * host is matched with that host's segment in front of its path - see\n     * hostRouting. Absent or empty: every request is the site's own.\n     */\n    hosts?: string[];\n    /**\n     * Whether every response says what built it: `X-Powered-By: rsc-kit` and\n     * a generator meta tag in the document. The name only, never the version.\n     * `X-RSC-Kit` (how a response was served) is sent regardless.\n     */\n    identify?: boolean;\n  };\n  routes: ManifestRoute[];\n  intercepts: ManifestIntercept[];\n  /** Optional: a manifest from a build before api routes existed has none. */\n  apis?: ManifestApiRoute[];\n}\n"]}

package/dist/openapi.d.ts

@@ -0,0 +1,74 @@
+/** What the generated entry hands over for each route.ts. */
+export interface OpenApiRoute {
+    /** The route's pattern in this package's spelling: `/api/orders/[id]`. */
+    pattern: string;
+    methods: string[];
+    /** The middleware.ts files above it: a guarded route gets a security requirement. */
+    guarded: boolean;
+    /** The route module: its params, searchParams, body and openapi exports, if any. */
+    module: Record<string, unknown>;
+}
+export interface OpenApiInfo {
+    title?: string;
+    version?: string;
+    description?: string;
+}
+/**
+ * What the document says that no route can: where the API is served, and
+ * how a caller authenticates. Spread onto the document as written, so
+ * anything OpenAPI allows at the top level is allowed here.
+ */
+export interface OpenApiDocumentOptions {
+    /**
+     * Which routes the document describes. `'all'` (the default) is every
+     * route.ts that did not opt out; `'declared'` is only the ones that
+     * export `openapi`, for an app whose routes are mostly webhooks and
+     * callbacks with a handful of endpoints meant for a caller to read about.
+     */
+    include?: "all" | "declared";
+    info?: OpenApiInfo;
+    servers?: {
+        url: string;
+        description?: string;
+    }[];
+    security?: Record<string, string[]>[];
+    components?: Record<string, unknown>;
+    tags?: {
+        name: string;
+        description?: string;
+    }[];
+}
+/**
+ * What a route.ts may say about itself, beside its handler:
+ *
+ *     export const openapi = {
+ *       summary: 'Chat completions',
+ *       tags: ['Chat'],
+ *       responses: { 200: { description: 'The completion', content: { … } } },
+ *     }
+ *
+ * Merged onto every operation the file exports, or per method when keyed
+ * by one: `{ POST: { summary: … } }`. Anything OpenAPI allows on an operation.
+ * `false` leaves the route out of the document altogether; `{ DELETE: false }`
+ * leaves one method out. HEAD and OPTIONS are never documented: the engine
+ * answers them for every route.
+ */
+export type OpenApiOperationExtras = Record<string, unknown>;
+/** `/api/orders/[id]/route` → `/api/orders/{id}`, and the names it binds. */
+export declare function openApiPath(pattern: string): {
+    path: string;
+    params: string[];
+};
+/**
+ * The document.
+ *
+ * Path parameters come from the pattern, typed by the route's `params` schema
+ * where it has one and as strings otherwise; query parameters from the
+ * `searchParams` schema's properties, each optional unless the schema
+ * requires it; a request body from the `body` schema, as JSON. A guarded
+ * route names the session as its security requirement, which is what a
+ * middleware.ts above it checks.
+ */
+export declare function buildOpenApi(routes: OpenApiRoute[], options?: OpenApiDocumentOptions): Record<string, unknown>;
+/** The document, as a route answers it: JSON, cacheable, built once. */
+export declare function openApiResponse(routes: OpenApiRoute[], options?: OpenApiDocumentOptions): Response;

package/dist/openapi.js

@@ -0,0 +1,172 @@
+// An OpenAPI document from the route tree, and a page that reads it.
+//
+// Every route.ts already says what an operation needs: the methods it
+// exports, and the params, searchParams and body schemas beside them. A
+// Standard Schema describes itself as JSON Schema (Zod 4 and ArkType do;
+// Valibot needs its converter and contributes nothing here), so the document
+// is derived rather than written - the way Elysia derives its from TypeBox.
+// Nothing is annotated twice.
+//
+// The document is built from the modules the generated entry imported, and
+// stored by the build like any other api route that reads nothing per
+// request. The page that reads it is Scalar's own package, mounted as a
+// route: `export const GET = ApiReference({ url: '/openapi.json' })`.
+const METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+/** The extras a route declared for one method: the shared ones, then that method's. */
+function extrasFor(module, method) {
+    const declared = module.openapi;
+    if (declared === null || typeof declared !== "object")
+        return {};
+    const record = declared;
+    const shared = {};
+    const own = (record[method] ?? {});
+    for (const [key, value] of Object.entries(record)) {
+        if (!METHODS.has(key))
+            shared[key] = value;
+    }
+    return { ...shared, ...own };
+}
+/** A Standard Schema's JSON Schema, or null when it cannot describe itself. */
+function jsonSchemaOf(schema) {
+    if (schema === null || typeof schema !== "object")
+        return null;
+    try {
+        const produce = schema["~standard"]?.jsonSchema?.input;
+        if (typeof produce !== "function")
+            return null;
+        // A leaf JSON Schema cannot say - a Date, a custom check - documents as
+        // `{}` rather than costing the route its whole body schema.
+        const json = produce({ target: "draft-2020-12", libraryOptions: { unrepresentable: "any" } });
+        // The dialect marker belongs on the document, not on every schema in it.
+        delete json.$schema;
+        return json;
+    }
+    catch {
+        return null;
+    }
+}
+/** `/api/orders/[id]/route` → `/api/orders/{id}`, and the names it binds. */
+export function openApiPath(pattern) {
+    const params = [];
+    const path = pattern.replace(/\[(?:\.\.\.)?(\w+)\]/g, (_, name) => {
+        params.push(name);
+        return `{${name}}`;
+    });
+    return { path, params };
+}
+const HAS_BODY = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/**
+ * The document.
+ *
+ * Path parameters come from the pattern, typed by the route's `params` schema
+ * where it has one and as strings otherwise; query parameters from the
+ * `searchParams` schema's properties, each optional unless the schema
+ * requires it; a request body from the `body` schema, as JSON. A guarded
+ * route names the session as its security requirement, which is what a
+ * middleware.ts above it checks.
+ */
+export function buildOpenApi(routes, options = {}) {
+    const { info = {}, include = "all", ...rest } = options;
+    const paths = {};
+    let anyGuarded = false;
+    for (const route of routes) {
+        // `export const openapi = false`: a route that is not part of the API -
+        // the page that renders this document, a webhook for one caller. With
+        // include: 'declared', a route with no `openapi` export is the same.
+        if (route.module.openapi === false)
+            continue;
+        if (include === "declared" && route.module.openapi === undefined)
+            continue;
+        const { path, params } = openApiPath(route.pattern);
+        const paramsSchema = jsonSchemaOf(route.module.params);
+        const searchSchema = jsonSchemaOf(route.module.searchParams);
+        const bodySchema = jsonSchemaOf(route.module.body);
+        const pathParameters = params.map((name) => ({
+            name,
+            in: "path",
+            required: true,
+            schema: paramsSchema?.properties?.[name] ?? { type: "string" },
+        }));
+        const queryParameters = Object.entries(searchSchema?.properties ?? {}).map(([name, schema]) => ({
+            name,
+            in: "query",
+            required: searchSchema?.required?.includes(name) ?? false,
+            schema,
+        }));
+        const operations = {};
+        for (const method of route.methods) {
+            // HEAD and OPTIONS are answered for every route by the engine, and a
+            // file that exports one - a CORS preflight - is not documenting an
+            // operation. `openapi: { OPTIONS: false }` drops any other method.
+            if (method === "HEAD" || method === "OPTIONS")
+                continue;
+            if ((route.module.openapi?.[method]) === false)
+                continue;
+            const operation = {
+                operationId: `${method.toLowerCase()}${path
+                    .replace(/\{(\w+)\}/g, "By$1")
+                    .split("/")
+                    .filter(Boolean)
+                    .map((part) => part[0].toUpperCase() + part.slice(1))
+                    .join("")}`,
+                parameters: [...pathParameters, ...queryParameters],
+                responses: { "200": { description: "OK" } },
+            };
+            if (bodySchema && HAS_BODY.has(method)) {
+                operation.requestBody = {
+                    required: true,
+                    content: { "application/json": { schema: bodySchema } },
+                };
+                operation.responses["422"] = {
+                    description: "The input was refused; validationErrors names each field.",
+                };
+            }
+            if (route.guarded) {
+                anyGuarded = true;
+                operation.security = [{ session: [] }];
+                operation.responses["401"] = { description: "Not signed in." };
+                operation.responses["403"] = { description: "Signed in, and still not allowed." };
+            }
+            // What the route said about itself wins over what was derived, field
+            // by field; its responses merge onto the derived ones.
+            const extras = extrasFor(route.module, method);
+            const responses = { ...operation.responses, ...(extras.responses ?? {}) };
+            operations[method.toLowerCase()] = { ...operation, ...extras, responses };
+        }
+        paths[path] = { ...(paths[path] ?? {}), ...operations };
+    }
+    const document = {
+        openapi: "3.1.0",
+        info: {
+            title: info.title ?? "API",
+            version: info.version ?? "0.0.0",
+            ...(info.description ? { description: info.description } : {}),
+        },
+        ...rest,
+        paths,
+    };
+    if (anyGuarded) {
+        const components = (rest.components ?? {});
+        const schemes = (components.securitySchemes ?? {});
+        document.components = {
+            ...components,
+            securitySchemes: {
+                session: {
+                    type: "apiKey",
+                    in: "cookie",
+                    name: "session",
+                    description: "The visitor's session, checked by the middleware.ts above the route.",
+                },
+                ...schemes,
+            },
+        };
+    }
+    return document;
+}
+/** The document, as a route answers it: JSON, cacheable, built once. */
+export function openApiResponse(routes, options = {}) {
+    return Response.json(buildOpenApi(routes, options), {
+        headers: { "Cache-Control": "public, max-age=300" },
+    });
+}
+//# sourceMappingURL=openapi.js.map

package/dist/openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"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","sourcesContent":["// An OpenAPI document from the route tree, and a page that reads it.\n//\n// Every route.ts already says what an operation needs: the methods it\n// exports, and the params, searchParams and body schemas beside them. A\n// Standard Schema describes itself as JSON Schema (Zod 4 and ArkType do;\n// Valibot needs its converter and contributes nothing here), so the document\n// is derived rather than written - the way Elysia derives its from TypeBox.\n// Nothing is annotated twice.\n//\n// The document is built from the modules the generated entry imported, and\n// stored by the build like any other api route that reads nothing per\n// request. The page that reads it is Scalar's own package, mounted as a\n// route: `export const GET = ApiReference({ url: '/openapi.json' })`.\n\ntype JsonSchema = Record<string, unknown> & {\n  type?: string | string[];\n  properties?: Record<string, JsonSchema>;\n  required?: string[];\n};\n\ntype WithJsonSchema = {\n  \"~standard\"?: {\n    jsonSchema?: {\n      input?: (options: { target: string; libraryOptions?: Record<string, unknown> }) => unknown;\n    };\n  };\n};\n\n/** What the generated entry hands over for each route.ts. */\nexport interface OpenApiRoute {\n  /** The route's pattern in this package's spelling: `/api/orders/[id]`. */\n  pattern: string;\n  methods: string[];\n  /** The middleware.ts files above it: a guarded route gets a security requirement. */\n  guarded: boolean;\n  /** The route module: its params, searchParams, body and openapi exports, if any. */\n  module: Record<string, unknown>;\n}\n\nconst METHODS = new Set([\"GET\", \"POST\", \"PUT\", \"PATCH\", \"DELETE\"]);\n\n/** The extras a route declared for one method: the shared ones, then that method's. */\nfunction extrasFor(module: Record<string, unknown>, method: string): OpenApiOperationExtras {\n  const declared = module.openapi;\n\n  if (declared === null || typeof declared !== \"object\") return {};\n\n  const record = declared as Record<string, unknown>;\n  const shared: Record<string, unknown> = {};\n  const own = (record[method] ?? {}) as Record<string, unknown>;\n\n  for (const [key, value] of Object.entries(record)) {\n    if (!METHODS.has(key)) shared[key] = value;\n  }\n\n  return { ...shared, ...own };\n}\n\nexport interface OpenApiInfo {\n  title?: string;\n  version?: string;\n  description?: string;\n}\n\n/**\n * What the document says that no route can: where the API is served, and\n * how a caller authenticates. Spread onto the document as written, so\n * anything OpenAPI allows at the top level is allowed here.\n */\nexport interface OpenApiDocumentOptions {\n  /**\n   * Which routes the document describes. `'all'` (the default) is every\n   * route.ts that did not opt out; `'declared'` is only the ones that\n   * export `openapi`, for an app whose routes are mostly webhooks and\n   * callbacks with a handful of endpoints meant for a caller to read about.\n   */\n  include?: \"all\" | \"declared\";\n  info?: OpenApiInfo;\n  servers?: { url: string; description?: string }[];\n  security?: Record<string, string[]>[];\n  components?: Record<string, unknown>;\n  tags?: { name: string; description?: string }[];\n}\n\n/**\n * What a route.ts may say about itself, beside its handler:\n *\n *     export const openapi = {\n *       summary: 'Chat completions',\n *       tags: ['Chat'],\n *       responses: { 200: { description: 'The completion', content: { … } } },\n *     }\n *\n * Merged onto every operation the file exports, or per method when keyed\n * by one: `{ POST: { summary: … } }`. Anything OpenAPI allows on an operation.\n * `false` leaves the route out of the document altogether; `{ DELETE: false }`\n * leaves one method out. HEAD and OPTIONS are never documented: the engine\n * answers them for every route.\n */\nexport type OpenApiOperationExtras = Record<string, unknown>;\n\n/** A Standard Schema's JSON Schema, or null when it cannot describe itself. */\nfunction jsonSchemaOf(schema: unknown): JsonSchema | null {\n  if (schema === null || typeof schema !== \"object\") return null;\n\n  try {\n    const produce = (schema as WithJsonSchema)[\"~standard\"]?.jsonSchema?.input;\n\n    if (typeof produce !== \"function\") return null;\n\n    // A leaf JSON Schema cannot say - a Date, a custom check - documents as\n    // `{}` rather than costing the route its whole body schema.\n    const json = produce({ target: \"draft-2020-12\", libraryOptions: { unrepresentable: \"any\" } }) as JsonSchema;\n\n    // The dialect marker belongs on the document, not on every schema in it.\n    delete json.$schema;\n\n    return json;\n  } catch {\n    return null;\n  }\n}\n\n/** `/api/orders/[id]/route` → `/api/orders/{id}`, and the names it binds. */\nexport function openApiPath(pattern: string): { path: string; params: string[] } {\n  const params: string[] = [];\n  const path = pattern.replace(/\\[(?:\\.\\.\\.)?(\\w+)\\]/g, (_, name: string) => {\n    params.push(name);\n\n    return `{${name}}`;\n  });\n\n  return { path, params };\n}\n\nconst HAS_BODY = new Set([\"POST\", \"PUT\", \"PATCH\", \"DELETE\"]);\n\n/**\n * The document.\n *\n * Path parameters come from the pattern, typed by the route's `params` schema\n * where it has one and as strings otherwise; query parameters from the\n * `searchParams` schema's properties, each optional unless the schema\n * requires it; a request body from the `body` schema, as JSON. A guarded\n * route names the session as its security requirement, which is what a\n * middleware.ts above it checks.\n */\nexport function buildOpenApi(routes: OpenApiRoute[], options: OpenApiDocumentOptions = {}): Record<string, unknown> {\n  const { info = {}, include = \"all\", ...rest } = options;\n  const paths: Record<string, Record<string, unknown>> = {};\n  let anyGuarded = false;\n\n  for (const route of routes) {\n    // `export const openapi = false`: a route that is not part of the API -\n    // the page that renders this document, a webhook for one caller. With\n    // include: 'declared', a route with no `openapi` export is the same.\n    if (route.module.openapi === false) continue;\n    if (include === \"declared\" && route.module.openapi === undefined) continue;\n\n    const { path, params } = openApiPath(route.pattern);\n    const paramsSchema = jsonSchemaOf(route.module.params);\n    const searchSchema = jsonSchemaOf(route.module.searchParams);\n    const bodySchema = jsonSchemaOf(route.module.body);\n\n    const pathParameters = params.map((name) => ({\n      name,\n      in: \"path\",\n      required: true,\n      schema: paramsSchema?.properties?.[name] ?? { type: \"string\" },\n    }));\n\n    const queryParameters = Object.entries(searchSchema?.properties ?? {}).map(([name, schema]) => ({\n      name,\n      in: \"query\",\n      required: searchSchema?.required?.includes(name) ?? false,\n      schema,\n    }));\n\n    const operations: Record<string, unknown> = {};\n\n    for (const method of route.methods) {\n      // HEAD and OPTIONS are answered for every route by the engine, and a\n      // file that exports one - a CORS preflight - is not documenting an\n      // operation. `openapi: { OPTIONS: false }` drops any other method.\n      if (method === \"HEAD\" || method === \"OPTIONS\") continue;\n      if (((route.module.openapi as Record<string, unknown> | undefined)?.[method]) === false) continue;\n\n      const operation: Record<string, unknown> = {\n        operationId: `${method.toLowerCase()}${path\n          .replace(/\\{(\\w+)\\}/g, \"By$1\")\n          .split(\"/\")\n          .filter(Boolean)\n          .map((part) => part[0].toUpperCase() + part.slice(1))\n          .join(\"\")}`,\n        parameters: [...pathParameters, ...queryParameters],\n        responses: { \"200\": { description: \"OK\" } },\n      };\n\n      if (bodySchema && HAS_BODY.has(method)) {\n        operation.requestBody = {\n          required: true,\n          content: { \"application/json\": { schema: bodySchema } },\n        };\n        (operation.responses as Record<string, unknown>)[\"422\"] = {\n          description: \"The input was refused; validationErrors names each field.\",\n        };\n      }\n\n      if (route.guarded) {\n        anyGuarded = true;\n        operation.security = [{ session: [] }];\n        (operation.responses as Record<string, unknown>)[\"401\"] = { description: \"Not signed in.\" };\n        (operation.responses as Record<string, unknown>)[\"403\"] = { description: \"Signed in, and still not allowed.\" };\n      }\n\n      // What the route said about itself wins over what was derived, field\n      // by field; its responses merge onto the derived ones.\n      const extras = extrasFor(route.module, method);\n      const responses = { ...(operation.responses as object), ...((extras.responses as object) ?? {}) };\n\n      operations[method.toLowerCase()] = { ...operation, ...extras, responses };\n    }\n\n    paths[path] = { ...(paths[path] ?? {}), ...operations };\n  }\n\n  const document: Record<string, unknown> = {\n    openapi: \"3.1.0\",\n    info: {\n      title: info.title ?? \"API\",\n      version: info.version ?? \"0.0.0\",\n      ...(info.description ? { description: info.description } : {}),\n    },\n    ...rest,\n    paths,\n  };\n\n  if (anyGuarded) {\n    const components = (rest.components ?? {}) as Record<string, unknown>;\n    const schemes = (components.securitySchemes ?? {}) as Record<string, unknown>;\n\n    document.components = {\n      ...components,\n      securitySchemes: {\n        session: {\n          type: \"apiKey\",\n          in: \"cookie\",\n          name: \"session\",\n          description: \"The visitor's session, checked by the middleware.ts above the route.\",\n        },\n        ...schemes,\n      },\n    };\n  }\n\n  return document;\n}\n\n/** The document, as a route answers it: JSON, cacheable, built once. */\nexport function openApiResponse(routes: OpenApiRoute[], options: OpenApiDocumentOptions = {}): Response {\n  return Response.json(buildOpenApi(routes, options), {\n    headers: { \"Cache-Control\": \"public, max-age=300\" },\n  });\n}\n"]}

package/dist/redirect.d.ts

@@ -1,4 +1,4 @@
-import type { Href, SearchFor } from './routes.js';
+import type { Route, SearchFor } from './routes.js';
 import type { Redirection } from './redirectDigest.js';
 export { RedirectSignal, isRedirectSignal, redirectDigest, parseRedirectDigest } from './redirectDigest.js';
 export type { Redirection } from './redirectDigest.js';
@@ -10,7 +10,7 @@ export type { Redirection } from './redirectDigest.js';
  * swallowing this turns a redirect into a blank region.
  *
  * `location` is typed to the routes the build found, so a redirect to a page
- * that no longer exists stops compiling. Cast with `as Href` when the
+ * that no longer exists stops compiling. Cast with `as Route` when the
  * destination is computed — remembering where someone was going and sending
  * them back to it is the usual case.
  *
@@ -26,7 +26,7 @@ export type { Redirection } from './redirectDigest.js';
  * same check `Link` puts on its `search` prop - so a key the page never
  * reads, or a number written as text, does not compile.
  */
-export type RedirectOptions<H extends Href> = ({} extends SearchFor<H> ? {
+export type RedirectOptions<H extends Route> = ({} extends SearchFor<H> ? {
     search?: SearchFor<H>;
 } : {
     search: SearchFor<H>;
@@ -34,7 +34,7 @@ export type RedirectOptions<H extends Href> = ({} extends SearchFor<H> ? {
     /** 307 unless said otherwise; 308 for a permanent one. */
     status?: number;
 };
-export declare function redirect<H extends Href>(location: H, ...rest: {} extends SearchFor<H> ? [options?: RedirectOptions<H> | number] : [options: RedirectOptions<H>]): never;
+export declare function redirect<H extends Route>(location: H, ...rest: {} extends SearchFor<H> ? [options?: RedirectOptions<H> | number] : [options: RedirectOptions<H>]): never;
 /** The redirect asked for during the current render, if any. */
 export declare function currentRedirect(): Redirection | null;
 /**

package/dist/redirect.js.map

@@ -1 +1 @@
-{"version":3,"file":"redirect.js","sourceRoot":"","sources":["../src/redirect.ts"],"names":[],"mappings":"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","sourcesContent":["// Redirecting from inside a render.\n//\n//   import { redirect } from '@rsc-kit/core/redirect'\n//\n//   export default async function ProductPage({ slug }) {\n//     const product = await findProduct(slug)\n//     if (!product) redirect('/products')\n//     ...\n//   }\n//\n// The hard part is not throwing — it is that a redirect decided during a\n// render may be decided after the response has already begun. Headers flush\n// early on purpose (see the stream-start invariant), so by the time a\n// component deep in a Suspense boundary changes its mind, the 200 is gone.\n//\n// So there are two windows, and which one a redirect lands in is decided by\n// where it was thrown rather than by anything the caller does:\n//\n//   Before the shell resolves — nothing has been written. The host answers\n//   with a real 3xx, or for a navigation with X-RSC-Redirect, and the browser\n//   never sees the page. This is the window every guard lands in, because a\n//   guard runs above the boundaries.\n//\n//   After the shell resolves — the shell is already on the wire. It holds\n//   layouts and Suspense fallbacks, so no data from the redirecting subtree\n//   has been shown. The location travels to the client instead, which\n//   performs it as an ordinary SPA navigation.\n//\n// Neither window costs a buffered byte. The first exists because the host\n// already awaits the shell before writing anything; the second because React\n// already carries an error digest to the client.\n\nimport { assertSafeRedirect } from './safeUrl.js'\nimport { withSearch } from './routes.js'\nimport type { Href, SearchFor } from './routes.js'\nimport { resolveScope } from './revalidate.js'\nimport { RedirectSignal } from './redirectDigest.js'\nimport type { Redirection } from './redirectDigest.js'\n\nexport { RedirectSignal, isRedirectSignal, redirectDigest, parseRedirectDigest } from './redirectDigest.js'\nexport type { Redirection } from './redirectDigest.js'\n\n/** Per-render state, for the same reason revalidation has it: two can be in flight. */\ninterface Slot {\n  redirect: Redirection | null\n  /**\n   * Whether the render asked for the not-found page.\n   *\n   * Shares this scope rather than opening a second one, because it is the same\n   * question asked once per render — \"did this page decide to answer as\n   * something other than itself\" — and every render path is already wrapped in\n   * this one. notFound.ts sets it through the scope symbol without importing\n   * this module; see the note there.\n   */\n  notFound?: boolean\n}\n\ninterface Scope {\n  getStore(): Slot | undefined\n  run<T>(store: Slot, fn: () => T): T\n}\n\n/**\n * One scope, however many copies of this module exist.\n *\n * The app's components are bundled into the server bundle and the host is\n * not, so this module is loaded twice. Two scopes would mean the component\n * records in one and the host reads the other: the redirect is simply never\n * honoured, and nothing on either side reports a problem.\n */\nconst SCOPE = Symbol.for('@rsc-kit/core.redirect-scope')\n\nconst globals = globalThis as Record<symbol | string, unknown>\n\nlet ready: Promise<void> | null = null\n\nfunction scope(): Scope | null {\n  return (globals[SCOPE] as Scope | undefined) ?? null\n}\n\n/**\n * Leave this page for another one.\n *\n * Never returns: it throws, which stops the component that called it. Do not\n * wrap a call in `try`/`catch` without rethrowing what you do not recognise —\n * swallowing this turns a redirect into a blank region.\n *\n * `location` is typed to the routes the build found, so a redirect to a page\n * that no longer exists stops compiling. Cast with `as Href` when the\n * destination is computed — remembering where someone was going and sending\n * them back to it is the usual case.\n *\n * Where it is called decides how it is delivered, and the difference matters\n * for anything that must not be seen. A call above every Suspense boundary is\n * answered with a status code before a byte is written. A call inside one is\n * answered after the shell — which holds no data from inside the boundary,\n * but does hold whatever the layouts above it rendered.\n */\n/**\n * What a redirect may carry beside its destination. `search` is typed to the\n * destination page's own `searchParams` schema when it exports one - the\n * same check `Link` puts on its `search` prop - so a key the page never\n * reads, or a number written as text, does not compile.\n */\nexport type RedirectOptions<H extends Href> = ({} extends SearchFor<H>\n  ? { search?: SearchFor<H> }\n  : { search: SearchFor<H> }) & {\n  /** 307 unless said otherwise; 308 for a permanent one. */\n  status?: number\n}\n\nexport function redirect<H extends Href>(\n  location: H,\n  ...rest: {} extends SearchFor<H> ? [options?: RedirectOptions<H> | number] : [options: RedirectOptions<H>]\n): never {\n  // The second argument was a status alone once; it still is, and an object\n  // carries the query string beside it.\n  const options = typeof rest[0] === 'number' ? { status: rest[0] } : (rest[0] ?? {})\n  const status = options.status ?? 307\n  const search = (options as { search?: object }).search\n\n  return redirectTo(search ? (withSearch(location, search) as Href) : location, status)\n}\n\nfunction redirectTo(location: Href, status: number): never {\n  // Refused here, at the one place every delivery path leads back to. The\n  // destination reaches location.href on the client and an inline script in a\n  // document, and a javascript: url runs in all of them.\n  assertSafeRedirect(location)\n\n  // A redirect is a 3xx. Anything else produces a response carrying Location\n  // that no browser acts on — the page renders, the redirect silently does not\n  // happen, and nothing says why.\n  if (status < 300 || status > 399) {\n    throw new Error(\n      'Not a redirect status: ' + status + '. A redirect is 3xx; 307 preserves the method.',\n    )\n  }\n\n  const store = scope()?.getStore()\n\n  // First wins. A layout that redirects and a page that also redirects should\n  // land where the outer one said, not wherever finished last.\n  if (store && !store.redirect) {\n    store.redirect = { location, status }\n  }\n\n  throw new RedirectSignal(location, status)\n}\n\n/** The redirect asked for during the current render, if any. */\nexport function currentRedirect(): Redirection | null {\n  return scope()?.getStore()?.redirect ?? null\n}\n\n/**\n * Whether the current render called notFound().\n *\n * Read rather than caught, for the reason the redirect above is: React\n * re-raises a component's error as its own, so the thrown signal does not\n * arrive intact at the host in production.\n */\nexport function currentNotFound(): boolean {\n  return scope()?.getStore()?.notFound === true\n}\n\n/**\n * Run a render with somewhere for a redirect to be recorded, and report one.\n *\n * `taken()` is read twice by a streaming host: once when the shell resolves,\n * to answer with a status code, and again when the stream ends, for a\n * redirect that arrived too late for one.\n */\nexport async function withRedirect<T>(\n  run: (taken: () => Redirection | null) => Promise<T>,\n): Promise<T> {\n  if (!globals[SCOPE]) {\n    ready ??= resolveScope().then((resolved) => {\n      globals[SCOPE] ??= resolved as unknown as Scope\n    })\n\n    await ready\n  }\n\n  const slot: Slot = { redirect: null, notFound: false }\n\n  return await scope()!.run(slot, () => run(() => slot.redirect))\n}\n"]}
+{"version":3,"file":"redirect.js","sourceRoot":"","sources":["../src/redirect.ts"],"names":[],"mappings":"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","sourcesContent":["// Redirecting from inside a render.\n//\n//   import { redirect } from '@rsc-kit/core/redirect'\n//\n//   export default async function ProductPage({ slug }) {\n//     const product = await findProduct(slug)\n//     if (!product) redirect('/products')\n//     ...\n//   }\n//\n// The hard part is not throwing — it is that a redirect decided during a\n// render may be decided after the response has already begun. Headers flush\n// early on purpose (see the stream-start invariant), so by the time a\n// component deep in a Suspense boundary changes its mind, the 200 is gone.\n//\n// So there are two windows, and which one a redirect lands in is decided by\n// where it was thrown rather than by anything the caller does:\n//\n//   Before the shell resolves — nothing has been written. The host answers\n//   with a real 3xx, or for a navigation with X-RSC-Redirect, and the browser\n//   never sees the page. This is the window every guard lands in, because a\n//   guard runs above the boundaries.\n//\n//   After the shell resolves — the shell is already on the wire. It holds\n//   layouts and Suspense fallbacks, so no data from the redirecting subtree\n//   has been shown. The location travels to the client instead, which\n//   performs it as an ordinary SPA navigation.\n//\n// Neither window costs a buffered byte. The first exists because the host\n// already awaits the shell before writing anything; the second because React\n// already carries an error digest to the client.\n\nimport { assertSafeRedirect } from './safeUrl.js'\nimport { withSearch } from './routes.js'\nimport type { Route, SearchFor } from './routes.js'\nimport { resolveScope } from './revalidate.js'\nimport { RedirectSignal } from './redirectDigest.js'\nimport type { Redirection } from './redirectDigest.js'\n\nexport { RedirectSignal, isRedirectSignal, redirectDigest, parseRedirectDigest } from './redirectDigest.js'\nexport type { Redirection } from './redirectDigest.js'\n\n/** Per-render state, for the same reason revalidation has it: two can be in flight. */\ninterface Slot {\n  redirect: Redirection | null\n  /**\n   * Whether the render asked for the not-found page.\n   *\n   * Shares this scope rather than opening a second one, because it is the same\n   * question asked once per render — \"did this page decide to answer as\n   * something other than itself\" — and every render path is already wrapped in\n   * this one. notFound.ts sets it through the scope symbol without importing\n   * this module; see the note there.\n   */\n  notFound?: boolean\n}\n\ninterface Scope {\n  getStore(): Slot | undefined\n  run<T>(store: Slot, fn: () => T): T\n}\n\n/**\n * One scope, however many copies of this module exist.\n *\n * The app's components are bundled into the server bundle and the host is\n * not, so this module is loaded twice. Two scopes would mean the component\n * records in one and the host reads the other: the redirect is simply never\n * honoured, and nothing on either side reports a problem.\n */\nconst SCOPE = Symbol.for('@rsc-kit/core.redirect-scope')\n\nconst globals = globalThis as Record<symbol | string, unknown>\n\nlet ready: Promise<void> | null = null\n\nfunction scope(): Scope | null {\n  return (globals[SCOPE] as Scope | undefined) ?? null\n}\n\n/**\n * Leave this page for another one.\n *\n * Never returns: it throws, which stops the component that called it. Do not\n * wrap a call in `try`/`catch` without rethrowing what you do not recognise —\n * swallowing this turns a redirect into a blank region.\n *\n * `location` is typed to the routes the build found, so a redirect to a page\n * that no longer exists stops compiling. Cast with `as Route` when the\n * destination is computed — remembering where someone was going and sending\n * them back to it is the usual case.\n *\n * Where it is called decides how it is delivered, and the difference matters\n * for anything that must not be seen. A call above every Suspense boundary is\n * answered with a status code before a byte is written. A call inside one is\n * answered after the shell — which holds no data from inside the boundary,\n * but does hold whatever the layouts above it rendered.\n */\n/**\n * What a redirect may carry beside its destination. `search` is typed to the\n * destination page's own `searchParams` schema when it exports one - the\n * same check `Link` puts on its `search` prop - so a key the page never\n * reads, or a number written as text, does not compile.\n */\nexport type RedirectOptions<H extends Route> = ({} extends SearchFor<H>\n  ? { search?: SearchFor<H> }\n  : { search: SearchFor<H> }) & {\n  /** 307 unless said otherwise; 308 for a permanent one. */\n  status?: number\n}\n\nexport function redirect<H extends Route>(\n  location: H,\n  ...rest: {} extends SearchFor<H> ? [options?: RedirectOptions<H> | number] : [options: RedirectOptions<H>]\n): never {\n  // The second argument was a status alone once; it still is, and an object\n  // carries the query string beside it.\n  const options = typeof rest[0] === 'number' ? { status: rest[0] } : (rest[0] ?? {})\n  const status = options.status ?? 307\n  const search = (options as { search?: object }).search\n\n  return redirectTo(search ? (withSearch(location, search) as Route) : location, status)\n}\n\nfunction redirectTo(location: Route, status: number): never {\n  // Refused here, at the one place every delivery path leads back to. The\n  // destination reaches location.href on the client and an inline script in a\n  // document, and a javascript: url runs in all of them.\n  assertSafeRedirect(location)\n\n  // A redirect is a 3xx. Anything else produces a response carrying Location\n  // that no browser acts on — the page renders, the redirect silently does not\n  // happen, and nothing says why.\n  if (status < 300 || status > 399) {\n    throw new Error(\n      'Not a redirect status: ' + status + '. A redirect is 3xx; 307 preserves the method.',\n    )\n  }\n\n  const store = scope()?.getStore()\n\n  // First wins. A layout that redirects and a page that also redirects should\n  // land where the outer one said, not wherever finished last.\n  if (store && !store.redirect) {\n    store.redirect = { location, status }\n  }\n\n  throw new RedirectSignal(location, status)\n}\n\n/** The redirect asked for during the current render, if any. */\nexport function currentRedirect(): Redirection | null {\n  return scope()?.getStore()?.redirect ?? null\n}\n\n/**\n * Whether the current render called notFound().\n *\n * Read rather than caught, for the reason the redirect above is: React\n * re-raises a component's error as its own, so the thrown signal does not\n * arrive intact at the host in production.\n */\nexport function currentNotFound(): boolean {\n  return scope()?.getStore()?.notFound === true\n}\n\n/**\n * Run a render with somewhere for a redirect to be recorded, and report one.\n *\n * `taken()` is read twice by a streaming host: once when the shell resolves,\n * to answer with a status code, and again when the stream ends, for a\n * redirect that arrived too late for one.\n */\nexport async function withRedirect<T>(\n  run: (taken: () => Redirection | null) => Promise<T>,\n): Promise<T> {\n  if (!globals[SCOPE]) {\n    ready ??= resolveScope().then((resolved) => {\n      globals[SCOPE] ??= resolved as unknown as Scope\n    })\n\n    await ready\n  }\n\n  const slot: Slot = { redirect: null, notFound: false }\n\n  return await scope()!.run(slot, () => run(() => slot.redirect))\n}\n"]}

package/dist/request.d.ts

@@ -21,10 +21,25 @@ export interface CookieOptions {
     sameSite?: "strict" | "lax" | "none";
     partitioned?: boolean;
 }
+/** One cookie as the request carried it: the shape Next's `cookies().get()` returns. */
+export interface RequestCookie {
+    name: string;
+    value: string;
+}
+/**
+ * The cookie jar, in the shape Next's `cookies()` has.
+ *
+ * `get()` returns `{ name, value }` rather than the string, because the guide
+ * says "the same names from `@rsc-kit/core/request`" and a name that is the
+ * same with a different return shape is the worst of both: ported code
+ * reading `?.value` off a string got `undefined`, silently. `getAll()` is a
+ * list for the same reason, and because a list composes where a record does
+ * not.
+ */
 export interface Cookies {
-    get(name: string): string | undefined;
+    get(name: string): RequestCookie | undefined;
     has(name: string): boolean;
-    getAll(): Record<string, string>;
+    getAll(): RequestCookie[];
     /**
      * Write one on the response.
      *
@@ -32,8 +47,12 @@ export interface Cookies {
      * been sent. A render has already flushed its headers by the time a
      * component runs — that is what makes the first paint fast — so this throws
      * there rather than appearing to work.
+     *
+     * Either call shape Next takes: `set(name, value, options)` or
+     * `set({ name, value, ...options })`.
      */
     set(name: string, value: string, options?: CookieOptions): void;
+    set(cookie: RequestCookie & CookieOptions): void;
     /** Write one that expires immediately. Same rule about where. */
     delete(name: string, options?: CookieOptions): void;
 }
@@ -114,6 +133,19 @@ export declare function withRequest<T>(from: RequestLike, run: () => Promise<T>)
  * call that never answers: the component suspends, its Suspense fallback goes
  * into the shell, and the probe's budget decides the rest.
  */
+/**
+ * The build's probe hands a route a Request that records what is read out of
+ * it, and a read of `url` marks the route as depending on the caller — the
+ * Next way to read a query is `new URL(request.url).searchParams`, which the
+ * probe cannot otherwise see. The engine itself reads the url to resolve the
+ * awaited `searchParams`, and that read is accounted for by `searchParams`,
+ * not by `url`; this is the door it goes through. A probe answers the real
+ * Request to this key; anything else answers nothing, and the request is its
+ * own.
+ */
+export declare const UNPROBED: unique symbol;
+/** The request's url, read by the engine rather than the route. */
+export declare function urlOf(request: Request): string;
 /**
  * Record a read without suspending on it.
  *
@@ -142,6 +174,28 @@ export declare function requestWasRead(): boolean;
 export declare function requestReadBy(): string[];
 /** A read React caught at a boundary during SSR: `useSearchParams() in Query`. */
 export declare function noteFallback(text: string): void;
+/**
+ * Run something once the answer is on its way, without making it wait.
+ *
+ * Logging, an audit row, an email, a cache warm: work the visitor should not
+ * pay for, and that must still finish. Next's `after()`, and needed for the
+ * same reason on every host: on a long-lived process a detached promise
+ * happens to run to completion, but a Worker tears the isolate down when the
+ * response ends unless the work is registered with the platform's
+ * `waitUntil` - so a fire-and-forget promise there dies silently, some of
+ * the time. The host hands these to `waitUntil` where one exists and runs
+ * them detached where a process will keep them.
+ *
+ * From a component, a middleware, a server action or an api route. A
+ * rejection is reported and never reaches the response, which has already
+ * gone. Outside a request - a build - the work runs at once.
+ */
+export declare function after(work: () => unknown): void;
+/**
+ * @internal For the host: the work `after()` collected for this request, as
+ * one promise that never rejects. Taken once; a second call has nothing.
+ */
+export declare function takeAfterWork(): Promise<void> | null;
 /** The reads caught at a boundary during this render, with their components. */
 export declare function requestFallbacks(): string[];
 /**

package/dist/request.js

@@ -3,7 +3,7 @@
 //   import { headers, cookies } from '@rsc-kit/core/request'
 //
 //   export default async function middleware() {
-//     const locale = cookies().get('locale') ?? negotiate(headers().get('accept-language'))
+//     const locale = cookies().get('locale')?.value ?? negotiate(headers().get('accept-language'))
 //     if (!locale) redirect('/en')
 //   }
 //
@@ -310,10 +310,15 @@ export async function cookies() {
         writable("cookies().set()").headers.append("Set-Cookie", serializeCookie({ name, value, options }));
     };
     return {
-        get: (name) => parsed[name],
+        get: (name) => (name in parsed ? { name, value: parsed[name] } : undefined),
         has: (name) => name in parsed,
-        getAll: () => ({ ...parsed }),
-        set: write,
+        getAll: () => Object.entries(parsed).map(([name, value]) => ({ name, value })),
+        set: (nameOrCookie, value, options) => {
+            if (typeof nameOrCookie === "string")
+                return write(nameOrCookie, value ?? "", options);
+            const { name, value: v, ...rest } = nameOrCookie;
+            return write(name, v, rest);
+        },
         // Expired rather than removed: a browser drops a cookie when it is told
         // one has already passed, and there is no other way to say it.
         delete: (name, options = {}) => write(name, "", { ...options, maxAge: 0 }),
@@ -424,6 +429,7 @@ export async function withRequest(from, run) {
         awaiters: new Map(),
         inHelper: null,
         readVia: new Map(),
+        after: [],
     };
     return await scope().run(store, run);
 }
@@ -434,6 +440,21 @@ export async function withRequest(from, run) {
  * call that never answers: the component suspends, its Suspense fallback goes
  * into the shell, and the probe's budget decides the rest.
  */
+/**
+ * The build's probe hands a route a Request that records what is read out of
+ * it, and a read of `url` marks the route as depending on the caller — the
+ * Next way to read a query is `new URL(request.url).searchParams`, which the
+ * probe cannot otherwise see. The engine itself reads the url to resolve the
+ * awaited `searchParams`, and that read is accounted for by `searchParams`,
+ * not by `url`; this is the door it goes through. A probe answers the real
+ * Request to this key; anything else answers nothing, and the request is its
+ * own.
+ */
+export const UNPROBED = Symbol.for("rsc-kit.unprobed");
+/** The request's url, read by the engine rather than the route. */
+export function urlOf(request) {
+    return (request[UNPROBED] ?? request).url;
+}
 /**
  * Record a read without suspending on it.
  *
@@ -484,6 +505,49 @@ export function noteFallback(text) {
     if (!store.fallbacks.includes(text))
         store.fallbacks.push(text);
 }
+/**
+ * Run something once the answer is on its way, without making it wait.
+ *
+ * Logging, an audit row, an email, a cache warm: work the visitor should not
+ * pay for, and that must still finish. Next's `after()`, and needed for the
+ * same reason on every host: on a long-lived process a detached promise
+ * happens to run to completion, but a Worker tears the isolate down when the
+ * response ends unless the work is registered with the platform's
+ * `waitUntil` - so a fire-and-forget promise there dies silently, some of
+ * the time. The host hands these to `waitUntil` where one exists and runs
+ * them detached where a process will keep them.
+ *
+ * From a component, a middleware, a server action or an api route. A
+ * rejection is reported and never reaches the response, which has already
+ * gone. Outside a request - a build - the work runs at once.
+ */
+export function after(work) {
+    const store = scope()?.getStore();
+    if (!store || !store.request) {
+        void Promise.resolve().then(work).catch(reportAfter);
+        return;
+    }
+    store.after.push(work);
+}
+function reportAfter(error) {
+    console.error("[rsc-kit] after() work failed:", error);
+}
+/**
+ * @internal For the host: the work `after()` collected for this request, as
+ * one promise that never rejects. Taken once; a second call has nothing.
+ */
+export function takeAfterWork() {
+    const store = scope()?.getStore();
+    if (!store || store.after.length === 0)
+        return null;
+    const work = store.after.splice(0);
+    return Promise.allSettled(work.map((run) => Promise.resolve().then(run))).then((results) => {
+        for (const result of results) {
+            if (result.status === "rejected")
+                reportAfter(result.reason);
+        }
+    });
+}
 /** The reads caught at a boundary during this render, with their components. */
 export function requestFallbacks() {
     return scope()?.getStore()?.fallbacks ?? [];