@rsc-kit/core 0.18.1 → 0.19.0

package/dist/action.d.ts

@@ -1,6 +1,6 @@
 import { type StandardSchemaV1 } from './js/standardSchema.js';
 import { type QueryOptions } from './query.js';
-/** What an action answers with. Exactly one of the three is set. */
+/** What an action answers with. Exactly one of the four is set. */
 export interface ActionResult<Data> {
     /** What the handler returned. */
     data?: Data;
@@ -8,6 +8,12 @@ export interface ActionResult<Data> {
     validationErrors?: Record<string, string[]>;
     /** Something else went wrong, reduced to a message the browser may see. */
     serverError?: string;
+    /**
+     * Where the action sent the visitor. Set by the client, which has already
+     * started the navigation: the page is on its way there, and there is
+     * nothing for the caller to do. Never set on the server side of the call.
+     */
+    redirected?: string;
 }
 /**
  * A middleware that neither continued nor refused.
@@ -105,7 +111,15 @@ export interface ActionBuilder<Ctx extends Record<string, unknown>, Input> {
     }) => Promise<MiddlewareResult<Extra>>): ActionBuilder<Ctx & Extra, Input>;
     /** Parse and check what the caller sent. The handler's `input` follows. */
     input<S extends StandardSchemaV1>(schema: S): ActionBuilder<Ctx, Output<S>>;
-    /** The body. */
+    /**
+     * The body.
+     *
+     * What the caller gets is always the result object: `data`, or a
+     * refusal, or - when the action redirected - `redirected`, set by the
+     * client once the navigation is under way. Always an object, so a caller
+     * reading `result.validationErrors` after a redirect reads undefined and
+     * not a TypeError inside a transition, which unmounts the root.
+     */
     handler<Data>(fn: (args: HandlerArgs<Input, Ctx>) => Promise<Data> | Data): (input?: unknown) => Promise<ActionResult<Data>>;
     /**
      * The body of a READ, sharing this client's middleware and schema.

package/dist/action.js

@@ -20,7 +20,9 @@
 // page may render. This wraps one action. They are different questions: an
 // action is reachable without any page, which is why it defends itself.
 import { validateWith } from './js/standardSchema.js';
+import { decodeFormData } from './js/formEncoding.js';
 import { markQuery, QueryValidationError } from './query.js';
+import { isRedirectSignal } from './redirectDigest.js';
 /**
  * A middleware that neither continued nor refused.
  *
@@ -98,17 +100,16 @@ export function fieldErrors(errors) {
     throw new ActionValidationError(normalised);
 }
 const GENERIC = 'Something went wrong.';
-/** FormData in, a plain object out — what a schema expects to be handed. */
-function fromFormData(body) {
-    const out = {};
-    for (const key of new Set(body.keys())) {
-        const values = body.getAll(key);
-        // One value stays a value. Several stay several — a multi-select that
-        // collapsed to its last entry would be a silent data loss.
-        out[key] = values.length > 1 ? values : values[0];
-    }
-    return out;
-}
+/**
+ * FormData in, a plain object out — what a schema expects to be handed.
+ *
+ * The form's own decoder, so the object validated here is the object the
+ * browser validated. This had a flat decoder of its own: `items[0].name`
+ * stayed a key spelled exactly that, `<Form>` had already parsed it into an
+ * array, and a nested form passed in the browser and failed on the server
+ * with the fields it named gone.
+ */
+const fromFormData = (body, schema) => decodeFormData(body, schema);
 export function createActionClient(options = {}) {
     const report = options.onError ?? (() => GENERIC);
     function build(middlewares, schema) {
@@ -121,7 +122,7 @@ export function createActionClient(options = {}) {
          * that should look like from the outside.
          */
         const pipeline = async (raw, fn) => {
-            const value = raw instanceof FormData ? fromFormData(raw) : raw;
+            const value = raw instanceof FormData ? fromFormData(raw, schema) : raw;
             if (schema) {
                 const invalid = await validateWith(schema, value);
                 if (invalid)
@@ -181,6 +182,12 @@ export function createActionClient(options = {}) {
                         // Past onError deliberately — see ActionMisuse.
                         if (error instanceof ActionMisuse)
                             throw error;
+                        // A redirect is an instruction, not a failure: it has to reach
+                        // the host, which answers the action with the destination. Caught
+                        // here it became { serverError: 'Something went wrong.' } - a
+                        // login that succeeded and then showed an error.
+                        if (isRedirectSignal(error))
+                            throw error;
                         if (isActionValidationError(error)) {
                             return { validationErrors: error.errors };
                         }
@@ -196,6 +203,8 @@ export function createActionClient(options = {}) {
                     catch (error) {
                         if (error instanceof ActionMisuse)
                             throw error;
+                        if (isRedirectSignal(error))
+                            throw error;
                         // Thrown, not returned. A cache library reports failure by
                         // rejection, so a query that answered with an error-shaped object
                         // would look like a successful read of something odd.

package/dist/action.js.map

@@ -1 +1 @@
-{"version":3,"file":"action.js","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,EAAE;AACF,oEAAoE;AACpE,EAAE;AACF,uCAAuC;AACvC,+EAA+E;AAC/E,uDAAuD;AACvD,+EAA+E;AAC/E,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,EAAE;AACF,+EAA+E;AAC/E,2EAA2E;AAC3E,6EAA6E;AAC7E,+EAA+E;AAC/E,uDAAuD;AACvD,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,wEAAwE;AAExE,OAAO,EAAE,YAAY,EAAyB,MAAM,wBAAwB,CAAA;AAC5E,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAqB,MAAM,YAAY,CAAA;AAY/E;;;;;;;GAOG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,cAAc,CAAA;IAC5B,CAAC;CACF;AAED,uDAAuD;AACvD;;;;;;;;;;;GAWG;AACH,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAA;AAErE;;;;;;GAMG;AACH,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAA;AAE7D,qFAAqF;AACrF,MAAM,UAAU,aAAa,CAAC,EAAW;IACvC,OAAO,OAAO,EAAE,KAAK,UAAU,IAAK,EAAyC,CAAC,WAAW,CAAC,KAAK,IAAI,CAAA;AACrG,CAAC;AAED,SAAS,eAAe,CAAqB,EAAK;IAChD,MAAM,CAAC,cAAc,CAAC,EAAE,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IAEvD,OAAO,EAAE,CAAA;AACX,CAAC;AAED,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9B,MAAM,CAA0B;IAEhD,YAAY,MAAgC;QAC1C,KAAK,CAAC,mBAAmB,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAA;QACnC,IAAI,CAAC,MAAM,GAAG,MAAM,CACnB;QAAC,IAA2C,CAAC,eAAe,CAAC,GAAG,IAAI,CAAA;IACvE,CAAC;CACF;AAED,uEAAuE;AACvE,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAiC,CAAC,eAAe,CAAC,KAAK,IAAI,CAC7D,CAAA;AACH,CAAC;AAoCD;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,MAAyC;IACnE,MAAM,UAAU,GAA6B,EAAE,CAAA;IAE/C,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACtD,UAAU,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAA;IAClE,CAAC;IAED,MAAM,IAAI,qBAAqB,CAAC,UAAU,CAAC,CAAA;AAC7C,CAAC;AAiFD,MAAM,OAAO,GAAG,uBAAuB,CAAA;AAEvC,4EAA4E;AAC5E,SAAS,YAAY,CAAC,IAAc;IAClC,MAAM,GAAG,GAA4B,EAAE,CAAA;IAEvC,KAAK,MAAM,GAAG,IAAI,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QACvC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAE/B,sEAAsE;QACtE,2DAA2D;QAC3D,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IACnD,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,OAAO,GAAwB,EAAE;IAEjC,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAA;IAEjD,SAAS,KAAK,CACZ,WAA6C,EAC7C,MAA+B;QAE7B;;;;;;;WAOG;QACL,MAAM,QAAQ,GAAG,KAAK,EACpB,GAAY,EACZ,EAAgD,EAC9B,EAAE;YACpB,MAAM,KAAK,GAAG,GAAG,YAAY,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAA;YAE/D,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;gBAEjD,IAAI,OAAO;oBAAE,MAAM,IAAI,qBAAqB,CAAC,OAAO,CAAC,CAAA;YACvD,CAAC;YAED,MAAM,MAAM,GAAG,MAAM;gBACnB,CAAC,CAAE,CAAC,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,KAAe;gBAC9D,CAAC,CAAE,KAAe,CAAA;YAEpB,wEAAwE;YACxE,qEAAqE;YACrE,oBAAoB;YACpB,IAAI,GAAG,GAAG,EAAS,CAAA;YACnB,IAAI,KAAK,GAAG,CAAC,CAAA;YAEb,MAAM,GAAG,GAAG,KAAK,IAAsB,EAAE;gBACvC,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,EAAE,CAAC,CAAA;gBAEvC,IAAI,CAAC,UAAU,EAAE,CAAC;oBAChB,OAAO,MAAM,EAAE,CAAC;wBACd,KAAK,EAAE,MAAe;wBACtB,GAAG,EAAE,GAAY;wBACjB,kEAAkE;wBAClE,qDAAqD;wBACrD,WAAW,EAAE,WAAoB;qBAClC,CAAC,CAAA;gBACJ,CAAC;gBAED,IAAI,SAAS,GAAG,KAAK,CAAA;gBAErB,MAAM,MAAM,GAAG,MAAO,UAAwE,CAAC;oBAC7F,GAAG;oBACH,IAAI,EAAE,CAAC,KAAK,EAAE,IAAwC,EAAE,EAAE;wBACxD,SAAS,GAAG,IAAI,CAAA;wBAChB,GAAG,GAAG,EAAE,GAAG,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC,EAAS,CAAA;wBAE7C,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,EAAE,EAAE,CAAA;oBACpC,CAAC,CAAU;iBACZ,CAAC,CAAA;gBAEF,sEAAsE;gBACtE,8DAA8D;gBAC9D,uDAAuD;gBACvD,IAAI,CAAC,SAAS,EAAE,CAAC;oBACf,MAAM,IAAI,YAAY,CACpB,wFAAwF,CACzF,CAAA;gBACH,CAAC;gBAED,OAAQ,MAA8B,EAAE,KAAK,CAAA;YAC/C,CAAC,CAAA;YAED,OAAO,MAAM,GAAG,EAAE,CAAA;QACpB,CAAC,CAAA;QAED,OAAO;YACL,GAAG,CAAC,UAAU;gBACZ,OAAO,KAAK,CAAC,CAAC,GAAG,WAAW,EAAE,UAAmB,CAAC,EAAE,MAAM,CAAU,CAAA;YACtE,CAAC;YACD,KAAK,CAAC,IAAI;gBACR,OAAO,KAAK,CAAC,WAAW,EAAE,IAAI,CAAU,CAAA;YAC1C,CAAC;YACD,OAAO,CAAC,EAAE;gBACR,OAAO,eAAe,CAAC,KAAK,EAAE,GAAa,EAAE,EAAE;oBAC7C,IAAI,CAAC;wBACH,OAAO,EAAE,IAAI,EAAE,CAAC,MAAM,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAmC,EAAE,CAAA;oBAC9E,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,gDAAgD;wBAChD,IAAI,KAAK,YAAY,YAAY;4BAAE,MAAM,KAAK,CAAA;wBAE9C,IAAI,uBAAuB,CAAC,KAAK,CAAC,EAAE,CAAC;4BACnC,OAAO,EAAE,gBAAgB,EAAE,KAAK,CAAC,MAAM,EAAE,CAAA;wBAC3C,CAAC;wBAED,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;oBACvC,CAAC;gBACH,CAAC,CAAC,CAAA;YACJ,CAAC;YACD,KAAK,CAAC,EAAE,EAAE,OAAO;gBACf,MAAM,IAAI,GAAG,KAAK,EAAE,GAAa,EAAE,EAAE;oBACnC,IAAI,CAAC;wBACH,OAAO,MAAM,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;oBAChC,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,IAAI,KAAK,YAAY,YAAY;4BAAE,MAAM,KAAK,CAAA;wBAE9C,2DAA2D;wBAC3D,kEAAkE;wBAClE,sDAAsD;wBACtD,IAAI,uBAAuB,CAAC,KAAK,CAAC,EAAE,CAAC;4BACnC,MAAM,IAAI,oBAAoB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;wBAC9C,CAAC;wBAED,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;oBAChC,CAAC;gBACH,CAAC,CAAA;gBAED,OAAO,eAAe,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAwC,CAAA;YACzF,CAAC;SACF,CAAA;IACH,CAAC;IAED,OAAO,KAAK,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;AACxB,CAAC","sourcesContent":["// Server actions with a schema, middleware, and types that follow from both.\n//\n//     export const action = createActionClient({ onError: report })\n//\n//     export const createPost = action\n//       .use(async ({ next }) => next({ ctx: { user: await currentUser() } }))\n//       .input(z.object({ title: z.string().min(3) }))\n//       .handler(async ({ input, ctx }) => savePost(ctx.user.id, input.title))\n//\n// `input` is typed from the schema and `ctx` from every middleware that ran, so\n// the handler is checked against both without either being written down twice.\n//\n// The built action RETURNS its failures rather than throwing them, and that is\n// not a style choice. React serialises a rejected server action opaquely —\n// production strips the message and leaves a digest — so a thrown validation\n// error reaches the browser as \"an error occurred\" and the fields it named are\n// gone. A returned object crosses the boundary intact.\n//\n// Distinct from `middleware.ts` in a route directory, which decides whether a\n// page may render. This wraps one action. They are different questions: an\n// action is reachable without any page, which is why it defends itself.\n\nimport { validateWith, type StandardSchemaV1 } from './js/standardSchema.js'\nimport { markQuery, QueryValidationError, type QueryOptions } from './query.js'\n\n/** What an action answers with. Exactly one of the three is set. */\nexport interface ActionResult<Data> {\n  /** What the handler returned. */\n  data?: Data\n  /** Field name to messages, in the shape a form already renders. */\n  validationErrors?: Record<string, string[]>\n  /** Something else went wrong, reduced to a message the browser may see. */\n  serverError?: string\n}\n\n/**\n * A middleware that neither continued nor refused.\n *\n * Never reported through `onError`: that reduces an error to a message for the\n * browser, and this one is for whoever wrote the middleware. A check that\n * forgot to call `next()` would otherwise look exactly like a check that\n * passed.\n */\nexport class ActionMisuse extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = 'ActionMisuse'\n  }\n}\n\n/** Refuse from inside a handler, naming the fields. */\n/**\n * Marks a refusal so it survives a bundle seam.\n *\n * A property rather than `instanceof`, for the reason this project keeps\n * running into: an app's actions are bundled separately from the engine, so\n * each gets its own copy of this module and its own copy of the class.\n * `instanceof` compares identity across that seam and is simply false — and\n * the refusal is then reported as a server error, so the form shows \"Something\n * went wrong\" instead of naming the fields. Everything works; nothing logs.\n *\n * Symbol.for, so the two copies agree on the key as well as the value.\n */\nconst VALIDATION_MARK = Symbol.for('@rsc-kit/core.action-validation')\n\n/**\n * Set on every function a client builds, so the build can tell them from a\n * bare \"use server\" export. The difference is the middleware: a bare export\n * runs with nothing checking who called it, and nothing else in the app\n * would ever say so. Symbol.for, because the build reads the mark from the\n * bundled copy of this module and the app's actions were built by another.\n */\nconst CLIENT_MARK = Symbol.for('@rsc-kit/core.action-client')\n\n/** Whether a server action was built by createActionClient, and so ran its chain. */\nexport function isClientBuilt(fn: unknown): boolean {\n  return typeof fn === 'function' && (fn as unknown as Record<symbol, unknown>)[CLIENT_MARK] === true\n}\n\nfunction markClientBuilt<F extends Function>(fn: F): F {\n  Object.defineProperty(fn, CLIENT_MARK, { value: true })\n\n  return fn\n}\n\nexport class ActionValidationError extends Error {\n  public readonly errors: Record<string, string[]>\n\n  constructor(errors: Record<string, string[]>) {\n    super('Validation failed')\n    this.name = 'ActionValidationError'\n    this.errors = errors\n    ;(this as unknown as Record<symbol, boolean>)[VALIDATION_MARK] = true\n  }\n}\n\n/** Whether this is a refusal, whichever copy of the class built it. */\nexport function isActionValidationError(error: unknown): error is ActionValidationError {\n  return (\n    typeof error === 'object' &&\n    error !== null &&\n    (error as Record<symbol, unknown>)[VALIDATION_MARK] === true\n  )\n}\n\n/**\n * The field errors a handler may report, keyed by its own input's fields.\n *\n * `''` is the whole submission — for a refusal that is about no field in\n * particular, which is where the form already looks for one.\n */\nexport type FieldErrorsFor<Input> = Partial<\n  Record<(Input extends object ? keyof Input & string : string) | '', string | string[]>\n>\n\n/**\n * What a handler is given.\n *\n * `fieldErrors` is here as well as exported on its own, and the one here is\n * the one to use: it is typed to this handler's input, so a field the schema\n * does not have is a type error rather than an error the form never shows.\n * The bare export takes any string, for the rare check that runs outside a\n * handler.\n */\nexport interface HandlerArgs<Input, Ctx> {\n  input: Input\n  ctx: Ctx\n  /**\n   * Fail with errors on this input's fields. Throws; nothing after it runs.\n   *\n   * Write `return fieldErrors(...)`. It throws either way, but TypeScript does\n   * not treat a never-return as terminating when the callee is a destructured\n   * binding — only a declaration or an explicitly annotated variable — so\n   * without the return, a value checked on the line above is still possibly\n   * undefined on the line below. The return is what lets the type narrow.\n   */\n  fieldErrors: (errors: FieldErrorsFor<Input>) => never\n}\n\n/**\n * Fail with field errors the form can show.\n *\n * For what a schema cannot know — a name already taken, a balance too low.\n * Throws, so the handler stops where it is; the action turns it into a\n * returned result on the way out.\n *\n * Untyped by field, because it has no handler to take the input from. Inside\n * one, use the `fieldErrors` the handler is given instead.\n */\nexport function fieldErrors(errors: Record<string, string[] | string>): never {\n  const normalised: Record<string, string[]> = {}\n\n  for (const [field, message] of Object.entries(errors)) {\n    normalised[field] = Array.isArray(message) ? message : [message]\n  }\n\n  throw new ActionValidationError(normalised)\n}\n\n/**\n * What `next()` hands back, carrying what the step added.\n *\n * The context a middleware contributes cannot be inferred from the arguments\n * it passes to `next` — TypeScript infers from a function's return, not from a\n * call inside it. So `next` returns this, the middleware returns it, and the\n * addition is read off the middleware's own return type.\n */\nexport interface MiddlewareResult<Extra> {\n  readonly ctx: Extra\n  readonly value: unknown\n}\n\n/**\n * A step that runs before the handler.\n *\n * It calls `next` to continue, optionally adding to the context, and what it\n * adds shows up in the handler's types. Returning without calling `next` — or\n * throwing — stops the action, which is how a check refuses.\n */\nexport type ActionMiddleware<Ctx, Extra extends Record<string, unknown>> = (args: {\n  ctx: Ctx\n  next: <E extends Record<string, unknown> = Record<string, never>>(\n    opts?: { ctx?: E },\n  ) => Promise<MiddlewareResult<E>>\n}) => Promise<MiddlewareResult<Extra>>\n\ntype Output<S> = S extends StandardSchemaV1<unknown, infer O> ? O : never\n\nexport interface ActionBuilder<Ctx extends Record<string, unknown>, Input> {\n  /** Add a step, and whatever context it contributes. */\n  use<Extra extends Record<string, unknown> = Record<string, never>>(\n    middleware: (args: {\n      ctx: Ctx\n      next: <E extends Record<string, unknown> = Record<string, never>>(\n        opts?: { ctx?: E },\n      ) => Promise<MiddlewareResult<E>>\n    }) => Promise<MiddlewareResult<Extra>>,\n  ): ActionBuilder<Ctx & Extra, Input>\n  /** Parse and check what the caller sent. The handler's `input` follows. */\n  input<S extends StandardSchemaV1>(schema: S): ActionBuilder<Ctx, Output<S>>\n  /** The body. */\n  handler<Data>(\n    fn: (args: HandlerArgs<Input, Ctx>) => Promise<Data> | Data,\n  ): (input?: unknown) => Promise<ActionResult<Data>>\n  /**\n   * The body of a READ, sharing this client's middleware and schema.\n   *\n   *     export const getPosts = client.input(filter).query(async ({ input, ctx }) =>\n   *       db.posts(ctx.user.id, input))\n   *\n   * The same builder as `handler`, and deliberately so: an app configures its\n   * auth check and its error reporting once, and both a mutation and a read go\n   * through them.\n   *\n   * It fails differently, though, and that is not an oversight. An action\n   * RETURNS its failures because React serialises a rejection opaquely. A query\n   * is handed to a cache library as a fetcher, and every one of them reports\n   * failure by rejection — so this returns the data directly and throws, and\n   * the endpoint carries the message across for it.\n   */\n  query<Data>(\n    fn: (args: { input: Input; ctx: Ctx }) => Promise<Data> | Data,\n    options?: QueryOptions,\n  ): (input?: unknown) => Promise<Data>\n}\n\nexport interface ActionClientOptions {\n  /**\n   * What the browser is told when something unexpected throws.\n   *\n   * Everything reaching here is a bug or an outage, and its message may say\n   * more than a stranger should see — a query, a path, a host. Returning a\n   * fixed string is the safe default; return the message only for errors you\n   * raised deliberately.\n   */\n  onError?: (error: unknown) => string\n}\n\nconst GENERIC = 'Something went wrong.'\n\n/** FormData in, a plain object out — what a schema expects to be handed. */\nfunction fromFormData(body: FormData): Record<string, unknown> {\n  const out: Record<string, unknown> = {}\n\n  for (const key of new Set(body.keys())) {\n    const values = body.getAll(key)\n\n    // One value stays a value. Several stay several — a multi-select that\n    // collapsed to its last entry would be a silent data loss.\n    out[key] = values.length > 1 ? values : values[0]\n  }\n\n  return out\n}\n\nexport function createActionClient(\n  options: ActionClientOptions = {},\n): ActionBuilder<Record<never, never>, undefined> {\n  const report = options.onError ?? (() => GENERIC)\n\n  function build<Ctx extends Record<string, unknown>, Input>(\n    middlewares: ActionMiddleware<never, never>[],\n    schema: StandardSchemaV1 | null,\n  ): ActionBuilder<Ctx, Input> {\n      /**\n       * Validate, run the chain, call the body.\n       *\n       * Shared by both terminals, which is the point of putting a read on this\n       * builder at all: one set of middleware, one schema, one place the auth\n       * check lives. Refusals leave by throwing, and each terminal decides what\n       * that should look like from the outside.\n       */\n    const pipeline = async (\n      raw: unknown,\n      fn: (args: HandlerArgs<never, never>) => unknown,\n    ): Promise<unknown> => {\n      const value = raw instanceof FormData ? fromFormData(raw) : raw\n\n      if (schema) {\n        const invalid = await validateWith(schema, value)\n\n        if (invalid) throw new ActionValidationError(invalid)\n      }\n\n      const parsed = schema\n        ? ((await schema['~standard'].validate(value)).value as Input)\n        : (value as Input)\n\n      // Composed inside-out so the first `use` is the outermost — it sees the\n      // others run, which is what makes timing and cleanup possible rather\n      // than only checks.\n      let ctx = {} as Ctx\n      let index = 0\n\n      const run = async (): Promise<unknown> => {\n        const middleware = middlewares[index++]\n\n        if (!middleware) {\n          return await fn({\n            input: parsed as never,\n            ctx: ctx as never,\n            // The same function as the export; the type on the way in is what\n            // is different, and the type is the handler's input.\n            fieldErrors: fieldErrors as never,\n          })\n        }\n\n        let continued = false\n\n        const result = await (middleware as unknown as ActionMiddleware<Ctx, Record<string, unknown>>)({\n          ctx,\n          next: (async (opts?: { ctx?: Record<string, unknown> }) => {\n            continued = true\n            ctx = { ...ctx, ...(opts?.ctx ?? {}) } as Ctx\n\n            return { ctx, value: await run() }\n          }) as never,\n        })\n\n        // Silence is not refusal. A middleware that neither called next() nor\n        // threw has done nothing, and guessing which it meant turns a\n        // forgotten `return` into a check that quietly passes.\n        if (!continued) {\n          throw new ActionMisuse(\n            'A middleware returned without calling next(). Call it to continue, or throw to refuse.',\n          )\n        }\n\n        return (result as { value?: unknown })?.value\n      }\n\n      return await run()\n    }\n\n    return {\n      use(middleware) {\n        return build([...middlewares, middleware as never], schema) as never\n      },\n      input(next) {\n        return build(middlewares, next) as never\n      },\n      handler(fn) {\n        return markClientBuilt(async (raw?: unknown) => {\n          try {\n            return { data: (await pipeline(raw, fn)) as Awaited<ReturnType<typeof fn>> }\n          } catch (error) {\n            // Past onError deliberately — see ActionMisuse.\n            if (error instanceof ActionMisuse) throw error\n\n            if (isActionValidationError(error)) {\n              return { validationErrors: error.errors }\n            }\n\n            return { serverError: report(error) }\n          }\n        })\n      },\n      query(fn, options) {\n        const read = async (raw?: unknown) => {\n          try {\n            return await pipeline(raw, fn)\n          } catch (error) {\n            if (error instanceof ActionMisuse) throw error\n\n            // Thrown, not returned. A cache library reports failure by\n            // rejection, so a query that answered with an error-shaped object\n            // would look like a successful read of something odd.\n            if (isActionValidationError(error)) {\n              throw new QueryValidationError(error.errors)\n            }\n\n            throw new Error(report(error))\n          }\n        }\n\n        return markClientBuilt(markQuery(read, options)) as (input?: unknown) => Promise<never>\n      },\n    }\n  }\n\n  return build([], null)\n}\n"]}
+{"version":3,"file":"action.js","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"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","sourcesContent":["// Server actions with a schema, middleware, and types that follow from both.\n//\n//     export const action = createActionClient({ onError: report })\n//\n//     export const createPost = action\n//       .use(async ({ next }) => next({ ctx: { user: await currentUser() } }))\n//       .input(z.object({ title: z.string().min(3) }))\n//       .handler(async ({ input, ctx }) => savePost(ctx.user.id, input.title))\n//\n// `input` is typed from the schema and `ctx` from every middleware that ran, so\n// the handler is checked against both without either being written down twice.\n//\n// The built action RETURNS its failures rather than throwing them, and that is\n// not a style choice. React serialises a rejected server action opaquely —\n// production strips the message and leaves a digest — so a thrown validation\n// error reaches the browser as \"an error occurred\" and the fields it named are\n// gone. A returned object crosses the boundary intact.\n//\n// Distinct from `middleware.ts` in a route directory, which decides whether a\n// page may render. This wraps one action. They are different questions: an\n// action is reachable without any page, which is why it defends itself.\n\nimport { validateWith, type StandardSchemaV1 } from './js/standardSchema.js'\nimport { decodeFormData } from './js/formEncoding.js'\nimport { markQuery, QueryValidationError, type QueryOptions } from './query.js'\nimport { isRedirectSignal } from './redirectDigest.js'\n\n/** What an action answers with. Exactly one of the four is set. */\nexport interface ActionResult<Data> {\n  /** What the handler returned. */\n  data?: Data\n  /** Field name to messages, in the shape a form already renders. */\n  validationErrors?: Record<string, string[]>\n  /** Something else went wrong, reduced to a message the browser may see. */\n  serverError?: string\n  /**\n   * Where the action sent the visitor. Set by the client, which has already\n   * started the navigation: the page is on its way there, and there is\n   * nothing for the caller to do. Never set on the server side of the call.\n   */\n  redirected?: string\n}\n\n/**\n * A middleware that neither continued nor refused.\n *\n * Never reported through `onError`: that reduces an error to a message for the\n * browser, and this one is for whoever wrote the middleware. A check that\n * forgot to call `next()` would otherwise look exactly like a check that\n * passed.\n */\nexport class ActionMisuse extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = 'ActionMisuse'\n  }\n}\n\n/** Refuse from inside a handler, naming the fields. */\n/**\n * Marks a refusal so it survives a bundle seam.\n *\n * A property rather than `instanceof`, for the reason this project keeps\n * running into: an app's actions are bundled separately from the engine, so\n * each gets its own copy of this module and its own copy of the class.\n * `instanceof` compares identity across that seam and is simply false — and\n * the refusal is then reported as a server error, so the form shows \"Something\n * went wrong\" instead of naming the fields. Everything works; nothing logs.\n *\n * Symbol.for, so the two copies agree on the key as well as the value.\n */\nconst VALIDATION_MARK = Symbol.for('@rsc-kit/core.action-validation')\n\n/**\n * Set on every function a client builds, so the build can tell them from a\n * bare \"use server\" export. The difference is the middleware: a bare export\n * runs with nothing checking who called it, and nothing else in the app\n * would ever say so. Symbol.for, because the build reads the mark from the\n * bundled copy of this module and the app's actions were built by another.\n */\nconst CLIENT_MARK = Symbol.for('@rsc-kit/core.action-client')\n\n/** Whether a server action was built by createActionClient, and so ran its chain. */\nexport function isClientBuilt(fn: unknown): boolean {\n  return typeof fn === 'function' && (fn as unknown as Record<symbol, unknown>)[CLIENT_MARK] === true\n}\n\nfunction markClientBuilt<F extends Function>(fn: F): F {\n  Object.defineProperty(fn, CLIENT_MARK, { value: true })\n\n  return fn\n}\n\nexport class ActionValidationError extends Error {\n  public readonly errors: Record<string, string[]>\n\n  constructor(errors: Record<string, string[]>) {\n    super('Validation failed')\n    this.name = 'ActionValidationError'\n    this.errors = errors\n    ;(this as unknown as Record<symbol, boolean>)[VALIDATION_MARK] = true\n  }\n}\n\n/** Whether this is a refusal, whichever copy of the class built it. */\nexport function isActionValidationError(error: unknown): error is ActionValidationError {\n  return (\n    typeof error === 'object' &&\n    error !== null &&\n    (error as Record<symbol, unknown>)[VALIDATION_MARK] === true\n  )\n}\n\n/**\n * The field errors a handler may report, keyed by its own input's fields.\n *\n * `''` is the whole submission — for a refusal that is about no field in\n * particular, which is where the form already looks for one.\n */\nexport type FieldErrorsFor<Input> = Partial<\n  Record<(Input extends object ? keyof Input & string : string) | '', string | string[]>\n>\n\n/**\n * What a handler is given.\n *\n * `fieldErrors` is here as well as exported on its own, and the one here is\n * the one to use: it is typed to this handler's input, so a field the schema\n * does not have is a type error rather than an error the form never shows.\n * The bare export takes any string, for the rare check that runs outside a\n * handler.\n */\nexport interface HandlerArgs<Input, Ctx> {\n  input: Input\n  ctx: Ctx\n  /**\n   * Fail with errors on this input's fields. Throws; nothing after it runs.\n   *\n   * Write `return fieldErrors(...)`. It throws either way, but TypeScript does\n   * not treat a never-return as terminating when the callee is a destructured\n   * binding — only a declaration or an explicitly annotated variable — so\n   * without the return, a value checked on the line above is still possibly\n   * undefined on the line below. The return is what lets the type narrow.\n   */\n  fieldErrors: (errors: FieldErrorsFor<Input>) => never\n}\n\n/**\n * Fail with field errors the form can show.\n *\n * For what a schema cannot know — a name already taken, a balance too low.\n * Throws, so the handler stops where it is; the action turns it into a\n * returned result on the way out.\n *\n * Untyped by field, because it has no handler to take the input from. Inside\n * one, use the `fieldErrors` the handler is given instead.\n */\nexport function fieldErrors(errors: Record<string, string[] | string>): never {\n  const normalised: Record<string, string[]> = {}\n\n  for (const [field, message] of Object.entries(errors)) {\n    normalised[field] = Array.isArray(message) ? message : [message]\n  }\n\n  throw new ActionValidationError(normalised)\n}\n\n/**\n * What `next()` hands back, carrying what the step added.\n *\n * The context a middleware contributes cannot be inferred from the arguments\n * it passes to `next` — TypeScript infers from a function's return, not from a\n * call inside it. So `next` returns this, the middleware returns it, and the\n * addition is read off the middleware's own return type.\n */\nexport interface MiddlewareResult<Extra> {\n  readonly ctx: Extra\n  readonly value: unknown\n}\n\n/**\n * A step that runs before the handler.\n *\n * It calls `next` to continue, optionally adding to the context, and what it\n * adds shows up in the handler's types. Returning without calling `next` — or\n * throwing — stops the action, which is how a check refuses.\n */\nexport type ActionMiddleware<Ctx, Extra extends Record<string, unknown>> = (args: {\n  ctx: Ctx\n  next: <E extends Record<string, unknown> = Record<string, never>>(\n    opts?: { ctx?: E },\n  ) => Promise<MiddlewareResult<E>>\n}) => Promise<MiddlewareResult<Extra>>\n\ntype Output<S> = S extends StandardSchemaV1<unknown, infer O> ? O : never\n\nexport interface ActionBuilder<Ctx extends Record<string, unknown>, Input> {\n  /** Add a step, and whatever context it contributes. */\n  use<Extra extends Record<string, unknown> = Record<string, never>>(\n    middleware: (args: {\n      ctx: Ctx\n      next: <E extends Record<string, unknown> = Record<string, never>>(\n        opts?: { ctx?: E },\n      ) => Promise<MiddlewareResult<E>>\n    }) => Promise<MiddlewareResult<Extra>>,\n  ): ActionBuilder<Ctx & Extra, Input>\n  /** Parse and check what the caller sent. The handler's `input` follows. */\n  input<S extends StandardSchemaV1>(schema: S): ActionBuilder<Ctx, Output<S>>\n  /**\n   * The body.\n   *\n   * What the caller gets is always the result object: `data`, or a\n   * refusal, or - when the action redirected - `redirected`, set by the\n   * client once the navigation is under way. Always an object, so a caller\n   * reading `result.validationErrors` after a redirect reads undefined and\n   * not a TypeError inside a transition, which unmounts the root.\n   */\n  handler<Data>(\n    fn: (args: HandlerArgs<Input, Ctx>) => Promise<Data> | Data,\n  ): (input?: unknown) => Promise<ActionResult<Data>>\n  /**\n   * The body of a READ, sharing this client's middleware and schema.\n   *\n   *     export const getPosts = client.input(filter).query(async ({ input, ctx }) =>\n   *       db.posts(ctx.user.id, input))\n   *\n   * The same builder as `handler`, and deliberately so: an app configures its\n   * auth check and its error reporting once, and both a mutation and a read go\n   * through them.\n   *\n   * It fails differently, though, and that is not an oversight. An action\n   * RETURNS its failures because React serialises a rejection opaquely. A query\n   * is handed to a cache library as a fetcher, and every one of them reports\n   * failure by rejection — so this returns the data directly and throws, and\n   * the endpoint carries the message across for it.\n   */\n  query<Data>(\n    fn: (args: { input: Input; ctx: Ctx }) => Promise<Data> | Data,\n    options?: QueryOptions,\n  ): (input?: unknown) => Promise<Data>\n}\n\nexport interface ActionClientOptions {\n  /**\n   * What the browser is told when something unexpected throws.\n   *\n   * Everything reaching here is a bug or an outage, and its message may say\n   * more than a stranger should see — a query, a path, a host. Returning a\n   * fixed string is the safe default; return the message only for errors you\n   * raised deliberately.\n   */\n  onError?: (error: unknown) => string\n}\n\nconst GENERIC = 'Something went wrong.'\n\n/**\n * FormData in, a plain object out — what a schema expects to be handed.\n *\n * The form's own decoder, so the object validated here is the object the\n * browser validated. This had a flat decoder of its own: `items[0].name`\n * stayed a key spelled exactly that, `<Form>` had already parsed it into an\n * array, and a nested form passed in the browser and failed on the server\n * with the fields it named gone.\n */\nconst fromFormData = (body: FormData, schema: unknown): Record<string, unknown> => decodeFormData(body, schema)\n\nexport function createActionClient(\n  options: ActionClientOptions = {},\n): ActionBuilder<Record<never, never>, undefined> {\n  const report = options.onError ?? (() => GENERIC)\n\n  function build<Ctx extends Record<string, unknown>, Input>(\n    middlewares: ActionMiddleware<never, never>[],\n    schema: StandardSchemaV1 | null,\n  ): ActionBuilder<Ctx, Input> {\n      /**\n       * Validate, run the chain, call the body.\n       *\n       * Shared by both terminals, which is the point of putting a read on this\n       * builder at all: one set of middleware, one schema, one place the auth\n       * check lives. Refusals leave by throwing, and each terminal decides what\n       * that should look like from the outside.\n       */\n    const pipeline = async (\n      raw: unknown,\n      fn: (args: HandlerArgs<never, never>) => unknown,\n    ): Promise<unknown> => {\n      const value = raw instanceof FormData ? fromFormData(raw, schema) : raw\n\n      if (schema) {\n        const invalid = await validateWith(schema, value)\n\n        if (invalid) throw new ActionValidationError(invalid)\n      }\n\n      const parsed = schema\n        ? ((await schema['~standard'].validate(value)).value as Input)\n        : (value as Input)\n\n      // Composed inside-out so the first `use` is the outermost — it sees the\n      // others run, which is what makes timing and cleanup possible rather\n      // than only checks.\n      let ctx = {} as Ctx\n      let index = 0\n\n      const run = async (): Promise<unknown> => {\n        const middleware = middlewares[index++]\n\n        if (!middleware) {\n          return await fn({\n            input: parsed as never,\n            ctx: ctx as never,\n            // The same function as the export; the type on the way in is what\n            // is different, and the type is the handler's input.\n            fieldErrors: fieldErrors as never,\n          })\n        }\n\n        let continued = false\n\n        const result = await (middleware as unknown as ActionMiddleware<Ctx, Record<string, unknown>>)({\n          ctx,\n          next: (async (opts?: { ctx?: Record<string, unknown> }) => {\n            continued = true\n            ctx = { ...ctx, ...(opts?.ctx ?? {}) } as Ctx\n\n            return { ctx, value: await run() }\n          }) as never,\n        })\n\n        // Silence is not refusal. A middleware that neither called next() nor\n        // threw has done nothing, and guessing which it meant turns a\n        // forgotten `return` into a check that quietly passes.\n        if (!continued) {\n          throw new ActionMisuse(\n            'A middleware returned without calling next(). Call it to continue, or throw to refuse.',\n          )\n        }\n\n        return (result as { value?: unknown })?.value\n      }\n\n      return await run()\n    }\n\n    return {\n      use(middleware) {\n        return build([...middlewares, middleware as never], schema) as never\n      },\n      input(next) {\n        return build(middlewares, next) as never\n      },\n      handler(fn) {\n        return markClientBuilt(async (raw?: unknown) => {\n          try {\n            return { data: (await pipeline(raw, fn)) as Awaited<ReturnType<typeof fn>> }\n          } catch (error) {\n            // Past onError deliberately — see ActionMisuse.\n            if (error instanceof ActionMisuse) throw error\n\n            // A redirect is an instruction, not a failure: it has to reach\n            // the host, which answers the action with the destination. Caught\n            // here it became { serverError: 'Something went wrong.' } - a\n            // login that succeeded and then showed an error.\n            if (isRedirectSignal(error)) throw error\n\n            if (isActionValidationError(error)) {\n              return { validationErrors: error.errors }\n            }\n\n            return { serverError: report(error) }\n          }\n        })\n      },\n      query(fn, options) {\n        const read = async (raw?: unknown) => {\n          try {\n            return await pipeline(raw, fn)\n          } catch (error) {\n            if (error instanceof ActionMisuse) throw error\n            if (isRedirectSignal(error)) throw error\n\n            // Thrown, not returned. A cache library reports failure by\n            // rejection, so a query that answered with an error-shaped object\n            // would look like a successful read of something odd.\n            if (isActionValidationError(error)) {\n              throw new QueryValidationError(error.errors)\n            }\n\n            throw new Error(report(error))\n          }\n        }\n\n        return markClientBuilt(markQuery(read, options)) as (input?: unknown) => Promise<never>\n      },\n    }\n  }\n\n  return build([], null)\n}\n"]}

package/dist/apiPrerender.js

@@ -11,7 +11,7 @@
 // answer to a POST is a stored answer to something that was supposed to happen
 // once.
 import { pathKey } from './prerender.js';
-import { requestReadBy, withRequest, withResponseDraft } from './request.js';
+import { UNPROBED, requestReadBy, withRequest, withResponseDraft } from './request.js';
 import { watchNondeterminism, whileRendering } from './nondeterminism.js';
 import { allowFor } from './routing.js';
 /**
@@ -30,12 +30,17 @@ export function apiKey(url) {
 /**
  * Reading anything here means the answer depends on the caller.
  *
- * Deliberately not `url`: the url is the key the answer is stored under, so
- * reading it tells you the same thing on every request that would hit the
- * stored file. The query string is handled by refusing to serve a stored
- * answer to a request that has one, which needs no detection at all.
+ * `url` is on the list although the path is the key the answer is stored
+ * under, because nobody reads it for the path: a handler written the Next way
+ * reads `new URL(request.url).searchParams`, which the probe cannot see the
+ * way it sees the awaited `searchParams` — and a stored answer marked as
+ * varying with nothing would then be served to every query, a webhook's
+ * verification handshake included. Reading the url also puts the build
+ * machine's origin within reach of the answer. A route that wants the bare
+ * url stored awaits `searchParams` instead; the table says so.
  */
 const PER_CALLER = new Set([
+    'url',
     'headers',
     'body',
     'bodyUsed',
@@ -60,6 +65,10 @@ function probeRequest(url, touched) {
     const real = new Request(url, { method: 'GET' });
     return new Proxy(real, {
         get(target, property) {
+            // The engine's own way past the probe, for the url read that resolves
+            // the awaited searchParams - booked to searchParams, not to url.
+            if (property === UNPROBED)
+                return target;
             if (typeof property === 'string' && PER_CALLER.has(property))
                 touched.add(property);
             const value = Reflect.get(target, property, target);
@@ -178,7 +187,8 @@ export async function prerenderApiRoutes(engine, manifest, write) {
                 continue;
             }
             if (touched.size > 0) {
-                said('dynamic', 'reads the request — ' + [...touched].sort().join(', '));
+                const hint = touched.has('url') ? ' (await searchParams to read the query and keep the bare url stored)' : '';
+                said('dynamic', 'reads the request — ' + [...touched].sort().join(', ') + hint);
                 continue;
             }
             // Awaiting the query string is not a reason to give up on the route — the
@@ -186,6 +196,14 @@ export async function prerenderApiRoutes(engine, manifest, write) {
             // stored answer is good for.
             const varies = answered.readBy.includes('searchParams');
             const response = answered.response.value;
+            // A refusal is an answer to the request the build sent - none - not to
+            // the ones visitors will. A route that answers 403 with nothing read is
+            // usually checking something the probe cannot see, and a stored 403 was
+            // once every webhook handshake's answer. Left to run, and said so.
+            if (response.status >= 400) {
+                said('dynamic', `answered ${response.status} to the build — a refusal is not an answer to store`);
+                continue;
+            }
             // A cookie is an answer for one visitor, whatever the route read to
             // decide on it. Stored, the build's cookie would be handed to everyone.
             if (response.headers.has('set-cookie') || answered.drafted.has('set-cookie')) {

package/dist/apiPrerender.js.map

@@ -1 +1 @@
-{"version":3,"file":"apiPrerender.js","sourceRoot":"","sources":["../src/apiPrerender.ts"],"names":[],"mappings":"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","sourcesContent":["// Freezing an api route the way a page is frozen.\n//\n// Not as an opt-in flag, deliberately. A page is stored by default and opts\n// OUT by touching the request — connection(), cookies(), headers() all suspend\n// at build time because there is no request there, and that is what marks the\n// page dynamic. A route works the same way and for the same reason: one model\n// to learn rather than two, and the honest default in both cases is \"the build\n// tried, and here is what it found\".\n//\n// GET only. Everything else is a method a caller may not repeat, and a stored\n// answer to a POST is a stored answer to something that was supposed to happen\n// once.\n\nimport { pathKey } from './prerender.js'\nimport { requestReadBy, withRequest, withResponseDraft } from './request.js'\nimport { watchNondeterminism, whileRendering } from './nondeterminism.js'\nimport type { ManifestApiRoute, RouteManifest } from './manifest.js'\nimport { allowFor } from './routing.js'\n\n/**\n * How long a route gets to answer before it is called dynamic.\n *\n * A route that reads the request does not fail here — it never settles, because\n * the accessors suspend forever with no request to read. So the budget is what\n * turns \"waiting\" into an answer, and it only has to be long enough for a route\n * that was going to finish.\n */\nconst BUDGET_MS = 2_000\n\n/** What a stored answer holds. Enough to rebuild the Response exactly. */\nexport interface FrozenApiResponse {\n  status: number\n  headers: [string, string][]\n  body: string\n  /**\n   * Whether the answer depends on the query string.\n   *\n   * False when the handler never awaited `searchParams` and declared no schema\n   * for it, which means the same answer is right for `?utm_source=anything`.\n   * True and the stored answer is only good for the bare url.\n   */\n  varies: boolean\n}\n\n/** The file a frozen route is stored as. */\nexport function apiKey(url: string): string {\n  return `${pathKey(url)}.api.json`\n}\n\n/**\n * Reading anything here means the answer depends on the caller.\n *\n * Deliberately not `url`: the url is the key the answer is stored under, so\n * reading it tells you the same thing on every request that would hit the\n * stored file. The query string is handled by refusing to serve a stored\n * answer to a request that has one, which needs no detection at all.\n */\nconst PER_CALLER = new Set([\n  'headers',\n  'body',\n  'bodyUsed',\n  'text',\n  'json',\n  'formData',\n  'arrayBuffer',\n  'blob',\n  'bytes',\n  'signal',\n  'referrer',\n  'credentials',\n])\n\n/**\n * A Request that records what was read out of it.\n *\n * A proxy rather than a subclass because the interesting properties are\n * getters on Request.prototype, and `this` has to stay the real Request or\n * every one of them throws about an illegal invocation.\n */\nfunction probeRequest(url: string, touched: Set<string>): Request {\n  const real = new Request(url, { method: 'GET' })\n\n  return new Proxy(real, {\n    get(target, property) {\n      if (typeof property === 'string' && PER_CALLER.has(property)) touched.add(property)\n\n      const value = Reflect.get(target, property, target)\n\n      return typeof value === 'function' ? value.bind(target) : value\n    },\n  })\n}\n\n/** The url a route with no parameters answers. */\nfunction urlFor(route: ManifestApiRoute): string | null {\n  // A parameterised route has as many urls as there are values, and nothing\n  // here knows them. Pages solve this with generateStaticParams; until a route\n  // can say the same, one is answered per request.\n  if (route.segments.some((segment) => segment.type !== 'static')) return null\n\n  return '/' + route.segments.map((segment) => segment.value).join('/')\n}\n\n/**\n * What the build calls a route in its output.\n *\n * The pattern for a parameterised one, spelled the way pages already spell\n * theirs, rather than the module name — a line reading\n * \"/app/api/greet/[name]/route\" names a file on disk and the rest of the table\n * names urls.\n */\nfunction labelFor(route: ManifestApiRoute): string {\n  return (\n    '/' +\n    route.segments\n      .map((segment) => (segment.type === 'static' ? segment.value : `_${segment.value}_`))\n      .join('/')\n  )\n}\n\n/** Whether a body is text this can store and hand back unchanged. */\nfunction asText(bytes: Uint8Array): string | null {\n  try {\n    const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes)\n\n    return text\n  } catch {\n    // Binary. Storable in principle, as base64, at the cost of a third of its\n    // size on disk and a decode per request — for a route that is far more\n    // likely to be streaming a file it should be serving as a file.\n    return null\n  }\n}\n\nexport interface ApiPrerenderResult {\n  url: string\n  name: string\n  type: 'frozen' | 'dynamic'\n  reason: string | null\n  /** Stored, and worth a second look - it froze a value that will not be the same tomorrow. */\n  warning?: string\n}\n\n/**\n * Try to answer every api route once, at build time, and store what can be.\n *\n * Sequential rather than parallel: there are usually few of them, each is a\n * function call rather than a React render, and the ones that are going to be\n * dynamic spend the whole budget waiting — which is time, not work.\n */\nexport async function prerenderApiRoutes(\n  engine: { handleApiRoute?: (n: string, r: Request, p: Record<string, string>, a: string) => Promise<Response> },\n  manifest: RouteManifest,\n  write: (name: string, contents: string) => Promise<void>,\n): Promise<ApiPrerenderResult[]> {\n  if (!engine.handleApiRoute || !manifest.apis?.length) return []\n\n  const results: ApiPrerenderResult[] = []\n\n  // Date.now() and friends are watched for the length of the loop, the way\n  // the page prerender watches them; whileRendering records what each route\n  // reached for while it answered.\n  const unwatch = watchNondeterminism()\n\n  try {\n  for (const route of manifest.apis) {\n    const said = (type: 'frozen' | 'dynamic', reason: string | null) => {\n      results.push({ url: labelFor(route), name: route.name, type, reason })\n    }\n\n    if (!route.methods.includes('GET')) {\n      said('dynamic', 'no GET to store')\n      continue\n    }\n\n    // A guarded route answers differently depending on who is asking, which is\n    // the whole purpose of the guard. Storing one answer and serving it to\n    // everyone is how a guard is silently removed.\n    if (route.middleware.length > 0) {\n      said('dynamic', 'guarded by middleware')\n      continue\n    }\n\n    const url = urlFor(route)\n\n    if (!url) {\n      said('dynamic', 'one url per param value, and none are listed')\n      continue\n    }\n\n    const touched = new Set<string>()\n    const request = probeRequest('https://prerender.invalid' + url, touched)\n\n    // No request in scope, so headers(), cookies() and connection() suspend\n    // forever rather than resolving to whatever the build machine had. The\n    // budget below is what turns that into an answer.\n    // Inside a response draft, because that is where the engine puts a cookie\n    // a route sets - a literal Set-Cookie on its Response is moved there too\n    // whenever a draft is open - and a probe with no draft reads a Response\n    // the cookie may already have left. Whether it went to the draft or stayed\n    // on the Response depends on what else is running in the process; the\n    // question here is only whether there was one.\n    const answered = await withResponseDraft(({ taken }) =>\n      withRequest(null as never, async () => {\n        let readBy: string[] = []\n\n        const response = await Promise.race([\n          whileRendering(() => engine.handleApiRoute!(route.name, request, {}, allowFor(route)))\n            .then(([value, reached]) => ({ value, reached }))\n            .catch((error) => ({ error })),\n          new Promise<null>((resolve) =>\n            setTimeout(() => {\n              readBy = requestReadBy()\n              resolve(null)\n            }, BUDGET_MS),\n          ),\n        ])\n\n        return { response, readBy: readBy.length ? readBy : requestReadBy(), drafted: taken() }\n      }),\n    )\n\n    if (answered.response === null) {\n      const why = answered.readBy.length\n        ? 'dynamic — called ' + answered.readBy.join(', ')\n        : 'did not answer within the build budget'\n\n      said('dynamic', why)\n      continue\n    }\n\n    if ('error' in answered.response) {\n      // Not a build failure. A route that throws with no request may be doing\n      // exactly the right thing — refusing a caller it cannot identify — and\n      // refusing the build over it would make that route unbuildable.\n      said('dynamic', 'threw without a request')\n      continue\n    }\n\n    if (touched.size > 0) {\n      said('dynamic', 'reads the request — ' + [...touched].sort().join(', '))\n      continue\n    }\n\n    // Awaiting the query string is not a reason to give up on the route — the\n    // bare url still has one right answer. It only narrows which requests the\n    // stored answer is good for.\n    const varies = answered.readBy.includes('searchParams')\n\n    const response = answered.response.value\n\n    // A cookie is an answer for one visitor, whatever the route read to\n    // decide on it. Stored, the build's cookie would be handed to everyone.\n    if (response.headers.has('set-cookie') || answered.drafted.has('set-cookie')) {\n      said('dynamic', 'sets a cookie — an answer for one visitor, not one to store')\n      continue\n    }\n\n    const body = asText(new Uint8Array(await response.arrayBuffer()))\n\n    if (body === null) {\n      said('dynamic', 'answers with bytes rather than text')\n      continue\n    }\n\n    await write(\n      apiKey(url),\n      JSON.stringify({\n        status: response.status,\n        // Lower-cased and sorted, so two builds of the same route produce the\n        // same bytes. Headers iteration does not promise a case or an order,\n        // and a file that differs between builds for no reason defeats\n        // content-addressed caching and makes a diff unreadable. Names are\n        // case-insensitive, so nothing is lost by picking one.\n        headers: [...response.headers]\n          .map(([name, value]) => [name.toLowerCase(), value] as [string, string])\n          .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),\n        body,\n        varies,\n      } satisfies FrozenApiResponse),\n    )\n\n    said('frozen', varies ? 'stored for the bare url — it reads the query string' : null)\n\n    // The same warning a page gets: a stored answer keeps whatever Date.now()\n    // or Math.random() returned at build time, and a json body has no browser\n    // to move it to.\n    const reached = answered.response.reached\n\n    if (reached.length > 0) {\n      results[results.length - 1]!.warning =\n        `froze ${reached.join(' and ')} — a stored answer keeps whatever that returned at build time. ` +\n        'If it should differ per call, read the request (await connection()) so the route runs on demand.'\n    }\n  }\n  } finally {\n    unwatch()\n  }\n\n  return results\n}\n"]}
+{"version":3,"file":"apiPrerender.js","sourceRoot":"","sources":["../src/apiPrerender.ts"],"names":[],"mappings":"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","sourcesContent":["// Freezing an api route the way a page is frozen.\n//\n// Not as an opt-in flag, deliberately. A page is stored by default and opts\n// OUT by touching the request — connection(), cookies(), headers() all suspend\n// at build time because there is no request there, and that is what marks the\n// page dynamic. A route works the same way and for the same reason: one model\n// to learn rather than two, and the honest default in both cases is \"the build\n// tried, and here is what it found\".\n//\n// GET only. Everything else is a method a caller may not repeat, and a stored\n// answer to a POST is a stored answer to something that was supposed to happen\n// once.\n\nimport { pathKey } from './prerender.js'\nimport { UNPROBED, requestReadBy, withRequest, withResponseDraft } from './request.js'\nimport { watchNondeterminism, whileRendering } from './nondeterminism.js'\nimport type { ManifestApiRoute, RouteManifest } from './manifest.js'\nimport { allowFor } from './routing.js'\n\n/**\n * How long a route gets to answer before it is called dynamic.\n *\n * A route that reads the request does not fail here — it never settles, because\n * the accessors suspend forever with no request to read. So the budget is what\n * turns \"waiting\" into an answer, and it only has to be long enough for a route\n * that was going to finish.\n */\nconst BUDGET_MS = 2_000\n\n/** What a stored answer holds. Enough to rebuild the Response exactly. */\nexport interface FrozenApiResponse {\n  status: number\n  headers: [string, string][]\n  body: string\n  /**\n   * Whether the answer depends on the query string.\n   *\n   * False when the handler never awaited `searchParams` and declared no schema\n   * for it, which means the same answer is right for `?utm_source=anything`.\n   * True and the stored answer is only good for the bare url.\n   */\n  varies: boolean\n}\n\n/** The file a frozen route is stored as. */\nexport function apiKey(url: string): string {\n  return `${pathKey(url)}.api.json`\n}\n\n/**\n * Reading anything here means the answer depends on the caller.\n *\n * `url` is on the list although the path is the key the answer is stored\n * under, because nobody reads it for the path: a handler written the Next way\n * reads `new URL(request.url).searchParams`, which the probe cannot see the\n * way it sees the awaited `searchParams` — and a stored answer marked as\n * varying with nothing would then be served to every query, a webhook's\n * verification handshake included. Reading the url also puts the build\n * machine's origin within reach of the answer. A route that wants the bare\n * url stored awaits `searchParams` instead; the table says so.\n */\nconst PER_CALLER = new Set([\n  'url',\n  'headers',\n  'body',\n  'bodyUsed',\n  'text',\n  'json',\n  'formData',\n  'arrayBuffer',\n  'blob',\n  'bytes',\n  'signal',\n  'referrer',\n  'credentials',\n])\n\n/**\n * A Request that records what was read out of it.\n *\n * A proxy rather than a subclass because the interesting properties are\n * getters on Request.prototype, and `this` has to stay the real Request or\n * every one of them throws about an illegal invocation.\n */\nfunction probeRequest(url: string, touched: Set<string>): Request {\n  const real = new Request(url, { method: 'GET' })\n\n  return new Proxy(real, {\n    get(target, property) {\n      // The engine's own way past the probe, for the url read that resolves\n      // the awaited searchParams - booked to searchParams, not to url.\n      if (property === UNPROBED) return target\n      if (typeof property === 'string' && PER_CALLER.has(property)) touched.add(property)\n\n      const value = Reflect.get(target, property, target)\n\n      return typeof value === 'function' ? value.bind(target) : value\n    },\n  })\n}\n\n/** The url a route with no parameters answers. */\nfunction urlFor(route: ManifestApiRoute): string | null {\n  // A parameterised route has as many urls as there are values, and nothing\n  // here knows them. Pages solve this with generateStaticParams; until a route\n  // can say the same, one is answered per request.\n  if (route.segments.some((segment) => segment.type !== 'static')) return null\n\n  return '/' + route.segments.map((segment) => segment.value).join('/')\n}\n\n/**\n * What the build calls a route in its output.\n *\n * The pattern for a parameterised one, spelled the way pages already spell\n * theirs, rather than the module name — a line reading\n * \"/app/api/greet/[name]/route\" names a file on disk and the rest of the table\n * names urls.\n */\nfunction labelFor(route: ManifestApiRoute): string {\n  return (\n    '/' +\n    route.segments\n      .map((segment) => (segment.type === 'static' ? segment.value : `_${segment.value}_`))\n      .join('/')\n  )\n}\n\n/** Whether a body is text this can store and hand back unchanged. */\nfunction asText(bytes: Uint8Array): string | null {\n  try {\n    const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes)\n\n    return text\n  } catch {\n    // Binary. Storable in principle, as base64, at the cost of a third of its\n    // size on disk and a decode per request — for a route that is far more\n    // likely to be streaming a file it should be serving as a file.\n    return null\n  }\n}\n\nexport interface ApiPrerenderResult {\n  url: string\n  name: string\n  type: 'frozen' | 'dynamic'\n  reason: string | null\n  /** Stored, and worth a second look - it froze a value that will not be the same tomorrow. */\n  warning?: string\n}\n\n/**\n * Try to answer every api route once, at build time, and store what can be.\n *\n * Sequential rather than parallel: there are usually few of them, each is a\n * function call rather than a React render, and the ones that are going to be\n * dynamic spend the whole budget waiting — which is time, not work.\n */\nexport async function prerenderApiRoutes(\n  engine: { handleApiRoute?: (n: string, r: Request, p: Record<string, string>, a: string) => Promise<Response> },\n  manifest: RouteManifest,\n  write: (name: string, contents: string) => Promise<void>,\n): Promise<ApiPrerenderResult[]> {\n  if (!engine.handleApiRoute || !manifest.apis?.length) return []\n\n  const results: ApiPrerenderResult[] = []\n\n  // Date.now() and friends are watched for the length of the loop, the way\n  // the page prerender watches them; whileRendering records what each route\n  // reached for while it answered.\n  const unwatch = watchNondeterminism()\n\n  try {\n  for (const route of manifest.apis) {\n    const said = (type: 'frozen' | 'dynamic', reason: string | null) => {\n      results.push({ url: labelFor(route), name: route.name, type, reason })\n    }\n\n    if (!route.methods.includes('GET')) {\n      said('dynamic', 'no GET to store')\n      continue\n    }\n\n    // A guarded route answers differently depending on who is asking, which is\n    // the whole purpose of the guard. Storing one answer and serving it to\n    // everyone is how a guard is silently removed.\n    if (route.middleware.length > 0) {\n      said('dynamic', 'guarded by middleware')\n      continue\n    }\n\n    const url = urlFor(route)\n\n    if (!url) {\n      said('dynamic', 'one url per param value, and none are listed')\n      continue\n    }\n\n    const touched = new Set<string>()\n    const request = probeRequest('https://prerender.invalid' + url, touched)\n\n    // No request in scope, so headers(), cookies() and connection() suspend\n    // forever rather than resolving to whatever the build machine had. The\n    // budget below is what turns that into an answer.\n    // Inside a response draft, because that is where the engine puts a cookie\n    // a route sets - a literal Set-Cookie on its Response is moved there too\n    // whenever a draft is open - and a probe with no draft reads a Response\n    // the cookie may already have left. Whether it went to the draft or stayed\n    // on the Response depends on what else is running in the process; the\n    // question here is only whether there was one.\n    const answered = await withResponseDraft(({ taken }) =>\n      withRequest(null as never, async () => {\n        let readBy: string[] = []\n\n        const response = await Promise.race([\n          whileRendering(() => engine.handleApiRoute!(route.name, request, {}, allowFor(route)))\n            .then(([value, reached]) => ({ value, reached }))\n            .catch((error) => ({ error })),\n          new Promise<null>((resolve) =>\n            setTimeout(() => {\n              readBy = requestReadBy()\n              resolve(null)\n            }, BUDGET_MS),\n          ),\n        ])\n\n        return { response, readBy: readBy.length ? readBy : requestReadBy(), drafted: taken() }\n      }),\n    )\n\n    if (answered.response === null) {\n      const why = answered.readBy.length\n        ? 'dynamic — called ' + answered.readBy.join(', ')\n        : 'did not answer within the build budget'\n\n      said('dynamic', why)\n      continue\n    }\n\n    if ('error' in answered.response) {\n      // Not a build failure. A route that throws with no request may be doing\n      // exactly the right thing — refusing a caller it cannot identify — and\n      // refusing the build over it would make that route unbuildable.\n      said('dynamic', 'threw without a request')\n      continue\n    }\n\n    if (touched.size > 0) {\n      const hint = touched.has('url') ? ' (await searchParams to read the query and keep the bare url stored)' : ''\n\n      said('dynamic', 'reads the request — ' + [...touched].sort().join(', ') + hint)\n      continue\n    }\n\n    // Awaiting the query string is not a reason to give up on the route — the\n    // bare url still has one right answer. It only narrows which requests the\n    // stored answer is good for.\n    const varies = answered.readBy.includes('searchParams')\n\n    const response = answered.response.value\n\n    // A refusal is an answer to the request the build sent - none - not to\n    // the ones visitors will. A route that answers 403 with nothing read is\n    // usually checking something the probe cannot see, and a stored 403 was\n    // once every webhook handshake's answer. Left to run, and said so.\n    if (response.status >= 400) {\n      said('dynamic', `answered ${response.status} to the build — a refusal is not an answer to store`)\n      continue\n    }\n\n    // A cookie is an answer for one visitor, whatever the route read to\n    // decide on it. Stored, the build's cookie would be handed to everyone.\n    if (response.headers.has('set-cookie') || answered.drafted.has('set-cookie')) {\n      said('dynamic', 'sets a cookie — an answer for one visitor, not one to store')\n      continue\n    }\n\n    const body = asText(new Uint8Array(await response.arrayBuffer()))\n\n    if (body === null) {\n      said('dynamic', 'answers with bytes rather than text')\n      continue\n    }\n\n    await write(\n      apiKey(url),\n      JSON.stringify({\n        status: response.status,\n        // Lower-cased and sorted, so two builds of the same route produce the\n        // same bytes. Headers iteration does not promise a case or an order,\n        // and a file that differs between builds for no reason defeats\n        // content-addressed caching and makes a diff unreadable. Names are\n        // case-insensitive, so nothing is lost by picking one.\n        headers: [...response.headers]\n          .map(([name, value]) => [name.toLowerCase(), value] as [string, string])\n          .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),\n        body,\n        varies,\n      } satisfies FrozenApiResponse),\n    )\n\n    said('frozen', varies ? 'stored for the bare url — it reads the query string' : null)\n\n    // The same warning a page gets: a stored answer keeps whatever Date.now()\n    // or Math.random() returned at build time, and a json body has no browser\n    // to move it to.\n    const reached = answered.response.reached\n\n    if (reached.length > 0) {\n      results[results.length - 1]!.warning =\n        `froze ${reached.join(' and ')} — a stored answer keeps whatever that returned at build time. ` +\n        'If it should differ per call, read the request (await connection()) so the route runs on demand.'\n    }\n  }\n  } finally {\n    unwatch()\n  }\n\n  return results\n}\n"]}

package/dist/clientPackages.d.ts

@@ -0,0 +1,30 @@
+/** Where `name` is installed, walking up from `from` the way resolution does. */
+export declare function packageDir(name: string, from: string): string | null;
+/** Whether any source file under `dir` opens with "use client". */
+export declare function hasClientDirective(dir: string): boolean;
+/**
+ * Whether any source file under `dir` imports react-dom/server.
+ *
+ * For a dependency left external where server components render: its
+ * imports are never resolved by the build, so the renderer stub that names
+ * the app file for a direct import never sees this one. @react-email/render
+ * is the usual case - an action imports it, the build says nothing, and the
+ * first call throws React's refusal at a visitor.
+ */
+export declare function importsServerRenderer(dir: string): boolean;
+/**
+ * Where a package is, anywhere in the project's dependency graph.
+ *
+ * For a polyfill a dependency of a dependency needs: not hoisted to the
+ * project under a strict store, so not resolvable from the project by
+ * name, and still what has to be evaluated first. A breadth-first walk of
+ * the manifests, from each package's real path, bounded in depth. The
+ * entry file is what `main` names, or index.js.
+ */
+export declare function packageEntryInGraph(root: string, name: string, depth?: number): string | null;
+/**
+ * The direct dependencies of the project at `root` that plugin-rsc would
+ * leave external and that carry a "use client" file - and the React-using
+ * dependencies under each, which have to be bundled with it.
+ */
+export declare function clientPackages(root: string): string[];

package/dist/clientPackages.js

@@ -0,0 +1,234 @@
+// Dependencies with "use client" files that plugin-rsc would leave external.
+//
+// plugin-rsc bundles a dependency into the server graphs - and so sees its
+// directives - only when the dependency declares react as a peer. That is
+// the right signal for a library written for React. It misses the package
+// that imports react and never says so: a component wrapper generated by a
+// tool, a workspace package with react under dependencies, a published
+// package whose author forgot. Left external, its "use client" is a string
+// nobody reads, the rsc environment loads it under the react-server
+// condition, and the first useState inside it fails at render with an error
+// that names React and not the package.
+//
+// So the direct dependencies are read once at config time: any that plugin-rsc
+// would not bundle, and that carries a "use client" directive in one of its
+// files, is bundled here. Direct dependencies only - a directive two levels
+// down is the concern of the package between, which declared it.
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync, openSync, readSync, closeSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** A directive at the top of a file: comments may precede it, code may not. */
+const DIRECTIVE = /^(?:\s|\/\/[^\n]*\n|\/\*[\s\S]*?\*\/)*(?:'use client'|"use client")\s*;?/;
+const SOURCE = /\.(?:m?js|cjs|jsx)$/;
+/** The most files read per package before giving up: a bound, not a budget. */
+const FILE_CAP = 3000;
+/** Enough of a file to hold a licence header and the directive after it. */
+const HEAD_BYTES = 2048;
+/** The packages plugin-rsc handles itself, and this one. */
+const OWN = new Set(["react", "react-dom", "react-server-dom-webpack", "@vitejs/plugin-rsc"]);
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Where `name` is installed, walking up from `from` the way resolution does. */
+export function packageDir(name, from) {
+    let dir = from;
+    for (;;) {
+        const candidate = join(dir, "node_modules", name);
+        if (existsSync(join(candidate, "package.json")))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function realpathOf(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+function headOf(path) {
+    const fd = openSync(path, "r");
+    try {
+        const buffer = Buffer.alloc(HEAD_BYTES);
+        const read = readSync(fd, buffer, 0, HEAD_BYTES, 0);
+        return buffer.toString("utf8", 0, read);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Whether any source file under `dir` opens with "use client". */
+export function hasClientDirective(dir) {
+    return someSourceFile(dir, (path) => DIRECTIVE.test(headOf(path)));
+}
+/** An import of react-dom's server renderer, static or dynamic, ESM or CJS. */
+const SERVER_RENDERER_IMPORT = /["']react-dom\/server(?:\.[a-z]+)?["']/;
+/** The largest file worth reading whole for an import: a bundled dist, not a data table. */
+const WHOLE_FILE_CAP = 512 * 1024;
+/**
+ * Whether any source file under `dir` imports react-dom/server.
+ *
+ * For a dependency left external where server components render: its
+ * imports are never resolved by the build, so the renderer stub that names
+ * the app file for a direct import never sees this one. @react-email/render
+ * is the usual case - an action imports it, the build says nothing, and the
+ * first call throws React's refusal at a visitor.
+ */
+export function importsServerRenderer(dir) {
+    return someSourceFile(dir, (path) => {
+        try {
+            if (statSync(path).size > WHOLE_FILE_CAP)
+                return false;
+            return SERVER_RENDERER_IMPORT.test(readFileSync(path, "utf8"));
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Whether `test` holds for some source file under `dir`, within the cap. */
+function someSourceFile(dir, test) {
+    const pending = [dir];
+    let seen = 0;
+    while (pending.length) {
+        const current = pending.pop();
+        let entries;
+        try {
+            entries = readdirSync(current);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry === "node_modules" || entry.startsWith("."))
+                continue;
+            const path = join(current, entry);
+            let stat;
+            try {
+                stat = statSync(path);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                pending.push(path);
+                continue;
+            }
+            if (!SOURCE.test(entry))
+                continue;
+            if (++seen > FILE_CAP)
+                return false;
+            try {
+                if (test(path))
+                    return true;
+            }
+            catch {
+                // Unreadable is neither.
+            }
+        }
+    }
+    return false;
+}
+/** Whether a package says it uses React, as a peer or as a dependency. */
+function usesReact(manifest) {
+    return !!manifest && ("react" in (manifest.peerDependencies ?? {}) || "react" in (manifest.dependencies ?? {}));
+}
+/**
+ * The dependencies of a bundled package that use React, and theirs.
+ *
+ * Bundling the package that carries the directive is not enough: the
+ * runtime it calls into - @stencil/react-output-target under a generated
+ * wrapper - is its own package, with react as a peer, and plugin-rsc's
+ * crawl never reached it because it only descends through packages that
+ * declared React. Left external, that runtime loads React through Node
+ * while everything else gets it through Vite: two copies, and the hooks
+ * dispatcher is null in one of them. Every React-using dependency under
+ * a bundled package is bundled with it.
+ */
+function reactDependenciesOf(dir, into, seen) {
+    const manifest = readJson(join(dir, "package.json"));
+    for (const name of Object.keys(manifest?.dependencies ?? {})) {
+        if (OWN.has(name) || seen.has(name))
+            continue;
+        seen.add(name);
+        // From where the package really is: under Bun's store a symlink in the
+        // app's node_modules points into .bun/<pkg>@<v>/node_modules/<pkg>, and
+        // the dependency sits beside it there, not beside the symlink.
+        const depDir = packageDir(name, realpathOf(dir));
+        if (!depDir || !usesReact(readJson(join(depDir, "package.json"))))
+            continue;
+        into.add(name);
+        reactDependenciesOf(depDir, into, seen);
+    }
+}
+/**
+ * Where a package is, anywhere in the project's dependency graph.
+ *
+ * For a polyfill a dependency of a dependency needs: not hoisted to the
+ * project under a strict store, so not resolvable from the project by
+ * name, and still what has to be evaluated first. A breadth-first walk of
+ * the manifests, from each package's real path, bounded in depth. The
+ * entry file is what `main` names, or index.js.
+ */
+export function packageEntryInGraph(root, name, depth = 5) {
+    const seen = new Set();
+    let frontier = [root];
+    for (let level = 0; level <= depth && frontier.length; level++) {
+        const next = [];
+        for (const dir of frontier) {
+            const found = packageDir(name, realpathOf(dir));
+            if (found) {
+                const manifest = readJson(join(found, "package.json"));
+                const entry = join(found, manifest?.main ?? "index.js");
+                return existsSync(entry) ? entry : existsSync(entry + ".js") ? entry + ".js" : null;
+            }
+            const manifest = readJson(join(dir, "package.json"));
+            for (const dep of Object.keys(manifest?.dependencies ?? {})) {
+                if (seen.has(dep))
+                    continue;
+                seen.add(dep);
+                const depDir = packageDir(dep, realpathOf(dir));
+                if (depDir)
+                    next.push(depDir);
+            }
+        }
+        frontier = next;
+    }
+    return null;
+}
+/**
+ * The direct dependencies of the project at `root` that plugin-rsc would
+ * leave external and that carry a "use client" file - and the React-using
+ * dependencies under each, which have to be bundled with it.
+ */
+export function clientPackages(root) {
+    const own = readJson(join(root, "package.json"));
+    if (!own?.dependencies)
+        return [];
+    const found = new Set();
+    for (const name of Object.keys(own.dependencies)) {
+        if (OWN.has(name) || name.startsWith("@rsc-kit/"))
+            continue;
+        const dir = packageDir(name, root);
+        if (!dir)
+            continue;
+        const manifest = readJson(join(dir, "package.json"));
+        // plugin-rsc's own rule: react as a peer, and the package is bundled already.
+        if (manifest?.peerDependencies && "react" in manifest.peerDependencies)
+            continue;
+        if (!hasClientDirective(dir))
+            continue;
+        found.add(name);
+        reactDependenciesOf(dir, found, new Set([name]));
+    }
+    return [...found].sort();
+}
+//# sourceMappingURL=clientPackages.js.map