typespec-hono 0.1.0 → 0.3.0

package/dist/src/app.js

@@ -4,23 +4,29 @@ import { isRawBinaryMediaType, objectKey, } from "typespec-http-zod";
 const GENERATED_BANNER = `// GENERATED by typespec-hono from the TypeSpec service definition. DO NOT EDIT.
 // Recompile the spec that produced it; edits here are overwritten on the next run.
 `;
-/** A parameter name Hono can carry verbatim — measured against Hono, not assumed. */
+/** A parameter name Hono can carry verbatim. Measured against Hono, not assumed. */
 const PLAIN_PATH_PARAMETER = /^[A-Za-z0-9_.~-]+$/;
 /**
  * TypeSpec publishes `/widgets/{widget-id}`; Hono routes on `/widgets/:widget-id`.
  *
- * ⚠️ **This used to match `\w+`, so any parameter carrying a hyphen was left ALONE.**
- * `@path("thing-id")` produced the literal route `/things/{thing-id}` — mounted, counted by every arm
+ * **This used to match `\w+`, so any parameter carrying a hyphen was left ALONE.**
+ * `@path("thing-id")` produced the literal route `/things/{thing-id}`, mounted, counted by every arm
  * that counts routes, and reachable by nobody. It answered 404 to the only requests it was for. Hono
  * handles `:thing-id` and `:x.y` perfectly well; the narrow character class was ours.
  *
- * A name that is not plain is REFUSED rather than approximated. Hono reads a parameter up to the next
- * `/`, so an RFC 6570 modifier would survive into the name and `*` would become Hono's wildcard — a
- * route that matches the wrong requests and answers them, which is worse than one that fails.
+ * A name that is not plain is REFUSED rather than approximated, and the route stays at the literal
+ * template so it matches nothing rather than matching the wrong thing.
  *
- * ⚠️ **This runs at RENDER time, not during collection.** It used to run inside `collectRoutes`, which
+ * **This is about the NAME, not about RFC 6570 operators.** An earlier version of this comment
+ * claimed `{+path}` or `{tag*}` would survive into the name and that `*` would become Hono's
+ * wildcard. Measured, that is false: `@typespec/http` resolves the operator before this emitter sees
+ * the path, and `@typespec/openapi3` strips it from the published document too, so both artefacts say
+ * `/files{path}` and agree. What actually reaches here is a wire name from `@path("...")`, and the
+ * forms that fail are a space, `+` and `!`. `*` is rejected by `@typespec/http` before it arrives.
+ *
+ * **This runs at RENDER time, not during collection.** It used to run inside `collectRoutes`, which
  * put one framework's spelling into the shared intermediate representation and refused the whole
- * operation — validators included — over a template no router could mount. What a request body must
+ * operation (validators included) over a template no router could mount. What a request body must
  * look like does not depend on that.
  */
 export function toHonoPath(template, refuse) {
@@ -32,14 +38,21 @@ export function toHonoPath(template, refuse) {
     });
 }
 /**
- * Verbs Hono cannot dispatch to, whatever they are registered with.
+ * The verb Hono actually dispatches under.
+ *
+ * `HEAD` is rewritten to `GET` before matching -- `hono-base.js` does it unconditionally at the top
+ * of `#dispatch` -- so a route registered under `HEAD` is never reached. Registering it under `GET`
+ * is what makes it reachable, and Hono strips the response body for a real HEAD request itself,
+ * which is what RFC 9110 requires.
  *
- * ⚠️ **`HEAD` is rewritten to `GET` before matching** — `hono-base.js` does it unconditionally at the
- * top of `#dispatch` — so a route registered under it is never reached. See the `unroutable-verb`
- * diagnostic for the measurements.
+ * The original verb is still available to the handler: `c.req.method` reads `HEAD` on a HEAD
+ * request even after the rewrite, which is what lets one registration serve both.
  */
-const UNROUTABLE_VERBS = new Set(["HEAD"]);
-/** `GET` → `get`. Hono's per-verb helpers are the idiom; `app.on` is the escape hatch. */
+const REGISTRATION_VERB = { HEAD: "GET" };
+function registrationVerbOf(verb) {
+    return REGISTRATION_VERB[verb] ?? verb;
+}
+/** `GET` -> `get`. Hono's per-verb helpers are the idiom; `app.on` is the escape hatch. */
 const HONO_METHOD = {
     GET: "get",
     POST: "post",
@@ -50,7 +63,7 @@ const HONO_METHOD = {
 /**
  * A request location, as the DOCUMENT names it, mapped to the target `@hono/zod-validator` reads.
  *
- * ⚠️ **The two vocabularies are not the same, and only one of them is a contract fact.** OpenAPI says
+ * **The two vocabularies are not the same, and only one of them is a contract fact.** OpenAPI says
  * `path`, `query`, `header` and a request body; zValidator says `param`, `query`, `header` and
  * `json`. The library publishes the first because that is what the document states; translating is
  * this package's job, and it is a map rather than a coincidence.
@@ -64,41 +77,63 @@ const VALIDATOR_TARGET = {
 /**
  * The `@hono/zod-validator` target for a request body, decided by what the wire actually carries.
  *
- * ⚠️ **This was `"json"` unconditionally, and that made every non-JSON body unservable.**
- * `zValidator("json", …)` reads `c.req.json()`, so a `multipart/form-data` upload was parsed as JSON
+ * **This was `"json"` unconditionally, and that made every non-JSON body unservable.**
+ * `zValidator("json", ...)` reads `c.req.json()`, so a `multipart/form-data` upload was parsed as JSON
  * and refused. Measured: 17 such registrations in `payload/multipart` alone, and **11 of the 17
- * request bodies in the Swagger Petstore are not JSON** — 5 urlencoded, 5 XML, 1 octet-stream.
+ * request bodies in the Swagger Petstore are not JSON**, 5 urlencoded, 5 XML, 1 octet-stream.
  *
- * Hono's own target for both multipart and urlencoded is `"form"` — `c.req.parseBody()` handles the
+ * Hono's own target for both multipart and urlencoded is `"form"`, `c.req.parseBody()` handles the
  * two together, which is why one branch covers both.
  *
- * ⚠️ **Anything else stays `"json"` deliberately.** A media type this function does not recognise is
+ * **Anything else stays `"json"` deliberately.** A media type this function does not recognise is
  * not a licence to guess: `application/xml` has no Hono target and no Zod representation the document
  * justifies, so it keeps the existing behaviour rather than acquiring a new one on the way past. That
  * gap is real and is stated in the README rather than papered over here.
  */
-function bodyTargetFor(contentTypes) {
-    /**
-     * ⚠️ **EVERY, not some, and the difference is a regression I shipped for one measurement.**
-     * `addPet` in the Swagger Petstore accepts `application/json`, `application/xml` **and**
-     * `application/x-www-form-urlencoded`. Choosing `"form"` because one member is form-ish made
-     * `zValidator` call `c.req.parseBody()` on JSON bodies, and a request that answered **200** before
-     * the change answered **400** after it. Measured both ways against the same server.
-     *
-     * ⚠️ **A route offering several media types cannot be validated by one target at all**, because
-     * which parser applies is decided by the caller's `Content-Type` at REQUEST time and `zValidator`
-     * is chosen at generation time. So a mixed body keeps `"json"`: unchanged behaviour, and a stated
-     * limitation rather than a guess that breaks the common case to fix the rare one. Only a body that
-     * is form-encoded in every form it may take is unambiguous enough to switch.
-     */
-    const form = contentTypes.length > 0 &&
-        contentTypes.every((type) => type.startsWith("multipart/") || type === "application/x-www-form-urlencoded");
-    return form ? "form" : VALIDATOR_TARGET.body;
+function targetForMediaType(type) {
+    if (type === "application/x-www-form-urlencoded" || type.startsWith("multipart/"))
+        return "form";
+    // `application/json`, and the `+json` structured suffix RFC 6839 defines.
+    if (type === "application/json" || type.endsWith("+json"))
+        return VALIDATOR_TARGET.body;
+    return undefined;
+}
+/**
+ * Which `zValidator` target parses each media type the request may carry.
+ *
+ * **This used to return ONE target for the whole route, and that was silently wrong for a mixed
+ * body.** Which parser applies is decided by the caller's `Content-Type` at REQUEST time;
+ * `zValidator`'s target is fixed at generation time. So a route declaring
+ * `application/json | application/xml | application/x-www-form-urlencoded` -- which is `addPet` in
+ * the Swagger Petstore, and 11 of its 17 request bodies are not JSON -- got `zValidator("json")` and
+ * rejected every form-encoded body with a 400, raising no diagnostic at all.
+ *
+ * The answer is to decide at request time, which is the only time the answer exists. Where the
+ * document declares one parseable type this still emits a single `zValidator` exactly as before.
+ *
+ * **`application/xml` and friends are reported, not guessed at.** There is no Hono parser and no
+ * Zod representation for XML, and adding an XML dependency to a Zod emitter is not a trade this
+ * package should make. Naming them is what stops a consumer believing a route is validated when it
+ * is not -- the previous behaviour said nothing and rejected them.
+ */
+function bodyValidationFor(contentTypes) {
+    if (contentTypes.length === 0)
+        return { byType: [["", VALIDATOR_TARGET.body]], unparseable: [] };
+    const byType = [];
+    const unparseable = [];
+    for (const type of contentTypes) {
+        const target = targetForMediaType(type);
+        if (target === undefined)
+            unparseable.push(type);
+        else
+            byType.push([type, target]);
+    }
+    return { byType, unparseable };
 }
 /**
  * How an unparsed body reaches the handler, and as what.
  *
- * ⚠️ **This was always `c.req.text()` typed as `string`, and for a binary body that silently
+ * **This was always `c.req.text()` typed as `string`, and for a binary body that silently
  * corrupts.** `text()` UTF-8-decodes, so every byte outside ASCII becomes U+FFFD. Measured against a
  * Petstore `application/octet-stream` upload under `wrangler dev`:
  *
@@ -108,10 +143,10 @@ function bodyTargetFor(contentTypes) {
  * ```
  *
  * Five bytes destroyed, unrecoverably, and the request answered **200**. Success status, corrupt
- * payload, no signal — the worst shape a defect can take.
+ * payload, no signal. The worst shape a defect can take.
  *
- * ⚠️ **`rawBodyProperty` conflated two different requirements, which is why one reader looked
- * sufficient.** Its docblock justifies `text()` by a webhook's MAC covering exactly what arrived — true,
+ * **`rawBodyProperty` conflated two different requirements, which is why one reader looked
+ * sufficient.** Its docblock justifies `text()` by a webhook's MAC covering exactly what arrived, true,
  * and true only when what arrived is text. An upload is the other case, and it needs the bytes.
  * `isRawBinaryMediaType` is the library's own rule for telling them apart, already applied on the
  * response side; importing it rather than re-deriving it is what keeps the two halves from disagreeing
@@ -143,15 +178,19 @@ function inputTypeOf(entry) {
  *
  * Only the first character moves. An operation id is already the name the DOCUMENT publishes, and
  * rewriting more of it would invent a second spelling of a contract fact for the sake of house style
- * — the `_` that `resolveOperationId` inserts is part of the published name.
+ *. The `_` that `resolveOperationId` inserts is part of the published name.
  */
 function capitaliseId(operationId) {
     return `${operationId.charAt(0).toUpperCase()}${operationId.slice(1)}`;
 }
+/** The schema identifier a dispatched body validates against. */
+function identifierOf(entry) {
+    return entry.dispatched?.identifier ?? "";
+}
 /**
- * The resource a route belongs to — its first path segment — or `undefined` when it has none.
+ * The resource a route belongs to (its first path segment) or `undefined` when it has none.
  *
- * ⚠️ **A parameter is not a resource.** `/{id}/things` has no groupable head: mounting a sub-app at
+ * **A parameter is not a resource.** `/{id}/things` has no groupable head: mounting a sub-app at
  * `/:id` would make the parameter the resource name, which is not what the document says and not what
  * anybody would write.
  */
@@ -176,49 +215,41 @@ function subAppNameOf(resource) {
 /**
  * The generated Hono server.
  *
- * ⚠️ **This replaces a data table that a hand-written loop interpreted at run time.** The emitter knew,
- * per operation, which validators applied and what the call looked like — and then flattened all of it
+ * **This replaces a data table that a hand-written loop interpreted at run time.** The emitter knew,
+ * per operation, which validators applied and what the call looked like, and then flattened all of it
  * into one homogeneous array, so the consumer had to recover it dynamically and could not. Emitting
  * the call sites keeps that knowledge, and every one of them is monomorphic and checked.
  *
- * ⚠️ **Plain `Hono` and `@hono/zod-validator`, deliberately not `@hono/zod-openapi`.** The latter is
- * the same validation plus a document generated FROM the code — spec-last, and a second source of
+ * **Plain `Hono` and `@hono/zod-validator`, deliberately not `@hono/zod-openapi`.** The latter is
+ * the same validation plus a document generated FROM the code, spec-last, and a second source of
  * truth competing with the one `@typespec/openapi3` publishes from the spec. We want its validation,
  * not its documentation.
  *
- * ⚠️ **It declares no schema of its own.** Every validator this file names was declared by
+ * **It declares no schema of its own.** Every validator this file names was declared by
  * `typespec-http-zod` into `schemas.gen.ts` and is imported by name. That is what makes the two
- * packages one emitter rather than two that must agree by coincidence — and it is why a consumer who
+ * packages one emitter rather than two that must agree by coincidence, and it is why a consumer who
  * wants the validators without a server can simply not install this one.
  */
 export function renderApp(emitted, refuse, 
 /**
- * The path the DOCUMENT says this service is served under, when it says one unambiguously.
+ * Every path the DOCUMENT says this service is served under. All of them are mounted.
  *
- * ⚠️ **An OpenAPI path is relative to its server**, so `@server("/api/v1")` plus `/accounts` means
+ * **An OpenAPI path is relative to its server**, so `@server("/api/v1")` plus `/accounts` means
  * the document publishes `/api/v1/accounts`. Mounting at the root made every client generated from
  * the document, and every "try it" in a rendered document, 404.
  */
-basePath, 
+basePaths = [], 
 /**
  * What the DOCUMENT says a caller must satisfy, per operation id.
  *
- * ⚠️ **Resolved by the caller rather than read off `EmittedRoute`**, because which schemes an
+ * **Resolved by the caller rather than read off `EmittedRoute`**, because which schemes an
  * operation accepts is a fact about the HTTP program and not part of the validator IR the library
  * publishes. Keeping it out of that IR is what stops a Hono concern leaking into a package whose
  * audience is wider.
  */
 securityFor) {
     const entries = emitted.routes.flatMap((route) => {
-        /**
-         * ⚠️ **Refused AND skipped, in that order.** Emitting the route anyway would put a registration
-         * in the file that `app.routes` lists and Hono never dispatches to — which is precisely how
-         * fifteen unreachable routes passed a differential written to catch unreachable routes.
-         */
-        if (UNROUTABLE_VERBS.has(route.verb)) {
-            refuse.unroutableVerb(route);
-            return [];
-        }
+        let dispatched;
         const names = emitted.schemaNames.get(route.operationId);
         // The library declares a `Responses` const for every operation, so a missing entry is a bug in
         // this package's pairing rather than a spec the emitter chose not to serve.
@@ -229,18 +260,35 @@ securityFor) {
             const identifier = names[location];
             if (identifier === undefined)
                 continue;
-            // The body's target depends on what the document says the wire carries; the rest are fixed.
-            const target = location === "body" ? bodyTargetFor(route.requestContentTypes) : VALIDATOR_TARGET[location];
-            validators.push([target, identifier]);
+            if (location !== "body") {
+                validators.push([VALIDATOR_TARGET[location], identifier]);
+                continue;
+            }
+            /**
+             * The body is the one location whose parser the document does not fix at generation time.
+             * Where it declares a single parseable media type this is one `zValidator`, unchanged. Where
+             * it declares several, the choice belongs to the caller's `Content-Type` and is made then.
+             */
+            const body = bodyValidationFor(route.requestContentTypes);
+            if (body.unparseable.length > 0)
+                refuse.unvalidatableMediaType(route, body.unparseable);
+            if (body.byType.length === 0)
+                continue;
+            const targets = [...new Set(body.byType.map(([, target]) => target))];
+            if (targets.length === 1) {
+                validators.push([targets[0], identifier]);
+                continue;
+            }
+            dispatched = { byType: body.byType, identifier };
         }
-        return [{ route, names, validators }];
+        return [{ route, names, validators, dispatched }];
     });
     /**
-     * ⚠️ **One registration per verb+path, not per operation.**
+     * **One registration per verb+path, not per operation.**
      *
      * TypeSpec models content negotiation as several operations on one route; OpenAPI models it as one
      * path entry whose response lists every media type. This emitter used to register all of them, and
-     * Hono matches in registration order — so every operation after the first was dead code that looked
+     * Hono matches in registration order, so every operation after the first was dead code that looked
      * mounted, and the only symptom was an operation count two higher than the document's.
      */
     const grouped = new Map();
@@ -251,7 +299,7 @@ securityFor) {
     const methods = entries.map((entry) => {
         const { route, names } = entry;
         /**
-         * A negotiated member's `accept` is not in its validator — the negotiation supplies it — but it
+         * A negotiated member's `accept` is not in its validator (the negotiation supplies it) but it
          * IS in the operation's declared input, so the interface has to keep it. The literal is known
          * exactly: it is the only value that reaches this member.
          */
@@ -273,14 +321,14 @@ securityFor) {
     /**
      * **Which resources get a sub-app, and which routes stay on the root.**
      *
-     * ⚠️ **Hono's own guidance, followed rather than guessed at.** Its best-practices page says to use
-     * `app.route()` to build a larger application instead of Ruby-on-Rails-like controllers — while
+     * **Hono's own guidance, followed rather than guessed at.** Its best-practices page says to use
+     * `app.route()` to build a larger application instead of Ruby-on-Rails-like controllers, while
      * writing handlers *directly after the path definitions*, because a handler in a separate file
      * cannot infer its path parameters. Both halves are honoured here: routes are grouped by resource,
      * and every handler stays inline where `c.req.valid()` is typed.
      *
-     * ⚠️ **Measured before relying on it:** `app.route(prefix, sub)` composes paths exactly, including a
-     * parameter in the prefix, and the PARENT's `app.routes` reports the fully composed path — so a
+     * **Measured before relying on it:** `app.route(prefix, sub)` composes paths exactly, including a
+     * parameter in the prefix, and the PARENT's `app.routes` reports the fully composed path, so a
      * route mounted through a sub-app is still countable, which is what every arm that counts routes
      * depends on.
      *
@@ -299,16 +347,42 @@ securityFor) {
         if (slots.length > 1)
             subApps.set(resource, subAppNameOf(resource));
     }
-    const registrations = [...grouped.values()].map((group) => {
+    /**
+     * Registration slots, which are not the same as negotiation groups.
+     *
+     * A HEAD operation shares GET's slot, because that is the only verb Hono will dispatch it under.
+     * So one slot can hold two groups -- the GET's and the HEAD's -- and the handler tells them apart
+     * with `c.req.method`. Everything else is one group per slot, exactly as before.
+     */
+    const slots = new Map();
+    for (const group of grouped.values()) {
+        const { route } = group[0];
+        const slot = `${registrationVerbOf(route.verb)} ${route.path}`;
+        slots.set(slot, [...(slots.get(slot) ?? []), group]);
+    }
+    const registrations = [...slots.values()].map((groupsInSlot) => {
+        const headGroups = groupsInSlot.filter((g) => g[0].route.verb === "HEAD");
+        const plainGroups = groupsInSlot.filter((g) => g[0].route.verb !== "HEAD");
+        /**
+         * When a path declares both, the GET is the one whose validators the single registration
+         * carries, and the HEAD branch is served from the same request. RFC 9110 defines HEAD as
+         * identical to GET apart from the response body, so the two accepting different inputs is a
+         * contradiction in the document rather than something to reconcile here.
+         */
+        const primary = (plainGroups[0] ?? headGroups[0]);
+        const headBranch = plainGroups.length > 0 ? headGroups[0] : undefined;
+        const group = primary;
         const entry = group[0];
         const { route, validators } = entry;
-        const method = HONO_METHOD[route.verb] ?? "on";
+        /** A HEAD with no GET beside it: registered under GET, and guarded so only a HEAD reaches it. */
+        const headOnly = plainGroups.length === 0 && headGroups.length > 0;
+        const method = HONO_METHOD[registrationVerbOf(route.verb)] ?? "on";
         const path = toHonoPath(route.path, (template, name) => refuse.unsupportedPathTemplate(route, template, name));
         /**
          * A route inside a sub-app is registered RELATIVE to the prefix it is mounted at.
          *
-         * ⚠️ **The collection route is `"/"`, never the empty string.** Measured: `sub.get("/")` under
-         * `app.route("/widgets", sub)` answers `/widgets`, and `/widgets/` is a 404 — so the composed
+         * **The collection route is `"/"`, never the empty string.** Measured: `sub.get("/")` under
+         * `app.route("/widgets", sub)` answers `/widgets`, and `/widgets/` is a 404, so the composed
          * path carries no trailing slash and the document's own path is what a caller reaches.
          */
         const resource = resourceOf(path);
@@ -323,22 +397,46 @@ securityFor) {
          * may not call the operation at all which payloads are well-formed.
          */
         /**
-         * ⚠️ **Emitted whenever the document declares ANY security, not only when it declares scopes.**
-         * `@useAuth(BearerAuth)` publishes `security: [{ "BearerAuth": [] }]` — no scopes — so a
+         * **Emitted whenever the document declares ANY security, not only when it declares scopes.**
+         * `@useAuth(BearerAuth)` publishes `security: [{ "BearerAuth": [] }]` (no scopes) so a
          * scopes-only gate covered OAuth2 and nothing else. Bearer, api-key and basic carried no gate at
          * all and rested entirely on `deps.context` returning null, which answers "is somebody here"
          * rather than "did they satisfy the scheme the contract names".
          */
         const requirements = securityFor?.(route.verb, route.path) ?? [];
         const gate = requirements.length === 0 ? [] : [`\t\tdeps.authorize(${renderSecurity(requirements)}),`];
+        /**
+         * A HEAD operation with no GET beside it is registered under GET, because that is the only verb
+         * Hono dispatches. The guard keeps the registration honest: a real GET is not in the document,
+         * so it gets the 404 it would have got before this route was registered at all, and only a HEAD
+         * reaches the validators and the handler.
+         *
+         * A plain middleware rather than `except()` from `hono/combine`, deliberately. `except` wraps the
+         * final handler, which erases its response type, and Hono's RPC client derives its entire surface
+         * from that type -- measured, `hc<typeof app>` resolved the wrapped route's body to `unknown`.
+         */
+        /**
+         * Where the document declares request media types needing different parsers, the validator
+         * is chosen from the request's `Content-Type`. `byContentType` is a plain middleware, so the
+         * final handler is untouched and Hono's RPC client still derives its surface from it.
+         */
+        const dispatch = entry.dispatched === undefined
+            ? []
+            : [
+                "\t\tbyContentType([",
+                ...entry.dispatched.byType.map(([type, target]) => `\t\t\t[${JSON.stringify(type)}, ${JSON.stringify(target)}, zValidator(${JSON.stringify(target)}, ${identifierOf(entry)}, deps.invalid)],`),
+                "\t\t]),",
+            ];
         const middleware = [
+            ...(headOnly ? ["\t\theadOnly,"] : []),
             ...gate,
             ...validators.map(([target, name]) => `\t\tzValidator(${JSON.stringify(target)}, ${name}, deps.invalid),`),
+            ...dispatch,
         ];
         /**
-         * Whether the operation requires a caller — and NOTHING else about the caller.
+         * Whether the operation requires a caller, and NOTHING else about the caller.
          *
-         * ⚠️ **This used to pass `"account"` or `"resource"`, chosen by how many path parameters the
+         * **This used to pass `"account"` or `"resource"`, chosen by how many path parameters the
          * route had, and that was a rule no document states.** `@useAuth(NoAuth)` reaches OpenAPI as
          * `security: []`, so "does this need a caller" is a contract fact and is generated. "Is this
          * account-scoped or resource-scoped" is not: no OpenAPI keyword expresses it, and the
@@ -351,15 +449,15 @@ securityFor) {
         }
         else {
             /**
-             * ⚠️ **The same null check as an authenticated route, and it is what removes a CAST from
+             * **The same null check as an authenticated route, and it is what removes a CAST from
              * generated output.** This used to emit `deps.context(c, "none") as Ctx`, because one
              * signature returning `C | null` cannot express "this argument makes null impossible". A cast
              * in generated code is worse than one in hand-written code: nobody reviews it, and it
              * reappears on every compile.
              *
-             * ⚠️ **Overloading `context` was tried and is worse.** It removes the cast from here and puts
+             * **Overloading `context` was tried and is worse.** It removes the cast from here and puts
              * one in every consumer's `deps`, because an overloaded property type stops contextually
-             * typing a single implementation — measured, the wiring consumer lost inference on every
+             * typing a single implementation. Measured, the wiring consumer lost inference on every
              * hook. Trading a cast in generated code for a cast in hand-written code is the wrong
              * direction.
              *
@@ -370,10 +468,18 @@ securityFor) {
             body.push("\t\t\tif (ctx === null) return deps.noContext(c);");
         }
         const pieces = validators.map(([target]) => `...c.req.valid(${JSON.stringify(target)})`);
+        /**
+         * Only one dispatched branch runs, and `zValidator` writes under its own target. Spreading every
+         * possible target is how the handler reads whichever one it was: an unset target reads
+         * `undefined`, and spreading `undefined` into an object literal contributes nothing.
+         */
+        for (const target of new Set((entry.dispatched?.byType ?? []).map(([, name]) => name))) {
+            pieces.push(`...c.req.valid(${JSON.stringify(target)})`);
+        }
         if (route.rawBodyProperty !== undefined) {
             // The bytes ARE the contract: a signature covers exactly what arrived, so parsing and
             // re-serialising would verify a different string than the sender signed. WHICH reader
-            // preserves them depends on the media type — see `rawBodyReaderFor`.
+            // preserves them depends on the media type, see `rawBodyReaderFor`.
             const reader = rawBodyReaderFor(route.requestContentTypes);
             pieces.push(`${objectKey(route.rawBodyProperty)}: ${reader.call}`);
         }
@@ -381,12 +487,14 @@ securityFor) {
             // The member's own `accept` literal, which its input type requires and which the shared
             // validator no longer supplies. We know it exactly: it is the branch we are in.
             const own = group.length > 1 && member.route.accept !== undefined
-                ? [`${objectKey(member.route.accept.name)}: ${JSON.stringify(member.route.accept.value)}`]
+                ? [
+                    `${objectKey(member.route.accept.name)}: ${JSON.stringify(member.route.accept.value)}`,
+                ]
                 : [];
             const input = [...pieces, ...own];
             /**
-             * ⚠️ **Broken across lines rather than emitted as one.** Generated code is read far more often
-             * than it is written — in review, in a stack trace, in a diff — and a single call reached 219
+             * **Broken across lines rather than emitted as one.** Generated code is read far more often
+             * than it is written (in review, in a stack trace, in a diff) and a single call reached 219
              * characters on a real service, against the 60-to-80 of every example in Hono's own
              * documentation. Nothing about the behaviour changes; a reader's ability to see it does.
              *
@@ -394,7 +502,7 @@ securityFor) {
              * already short.
              */
             /**
-             * ⚠️ **Indented literally, because the surrounding `+1 tab` only reaches the FIRST physical
+             * **Indented literally, because the surrounding `+1 tab` only reaches the FIRST physical
              * line.** A multi-line fragment keeps whatever tabs it was written with, so the depths here
              * are absolute: the `return` sits at four, its arguments at five, and the handler's input
              * properties at six.
@@ -416,6 +524,20 @@ securityFor) {
                     "\t\t\t\t)",
                 ].join("\n");
         };
+        /**
+         * Both verbs on one path: `c.req.method` still reads `HEAD` after Hono's rewrite, so one
+         * registration serves both and each operation keeps its own handler and its own response arms.
+         * Hono strips the body on the HEAD branch itself.
+         *
+         * The HEAD branch is emitted FIRST because it is the narrower condition, and it returns, so the
+         * GET path below is reached only by a real GET.
+         */
+        if (headBranch !== undefined) {
+            const headEntry = headBranch[0];
+            body.push(`\t\t\tif (c.req.method === "HEAD") {`);
+            body.push(`\t\t\t\treturn ${invoke(headEntry).replaceAll("\n", "\n\t")};`);
+            body.push("\t\t\t}");
+        }
         if (group.length === 1) {
             body.push(`\t\t\treturn ${invoke(entry)};`);
         }
@@ -424,7 +546,7 @@ securityFor) {
              * Several operations, one route: the caller's `Accept` chooses which one answers.
              *
              * The offered list and which operation serves each type are both read from the document.
-             * `selectContentType` applies RFC 9110 §12.5.1 to them — it lives in the runtime rather than
+             * `selectContentType` applies RFC 9110 section 12.5.1 to them. It lives in the runtime rather than
              * in `deps` because both halves are derivable, and an app forced to supply it would be
              * re-implementing the standard.
              */
@@ -436,27 +558,27 @@ securityFor) {
                 body.push(`\t\t\tif (served === ${JSON.stringify(offer.contentType)}) return ${invoke(offer.member)};`);
             }
             // `selectContentType` only ever returns a member of the list it was given, so this is
-            // unreachable — and stating that is cheaper than a cast that would hide it if it were not.
+            // unreachable, and stating that is cheaper than a cast that would hide it if it were not.
             body.push(`\t\t\treturn deps.notAcceptable(c, ${offered});`);
         }
         /**
-         * ⚠️ **`app.on` takes the METHOD first, and we were not passing one.** Only five verbs have a
-         * dedicated Hono method; everything else — `HEAD`, `OPTIONS`, anything a spec invents — fell
+         * **`app.on` takes the METHOD first, and we were not passing one.** Only five verbs have a
+         * dedicated Hono method; everything else (`HEAD`, `OPTIONS`, anything a spec invents) fell
          * through to `app.on(path, handler)`, which Hono reads as `on(method, path)`. The route was
          * emitted, counted by every arm that counted rows, and mounted nowhere.
          */
         /**
-         * ⚠️ **Emitted as a CHAINED call fragment rather than a statement, and that is what makes Hono's
+         * **Emitted as a CHAINED call fragment rather than a statement, and that is what makes Hono's
          * RPC client work at all.** `hc<typeof app>` derives its entire surface from the `Schema` type
-         * parameter Hono accumulates through chaining — not from what is registered at run time. As
+         * parameter Hono accumulates through chaining, not from what is registered at run time. As
          * separate statements each call's type was discarded, `registerRoutes` returned `void`, and
          * measured in a fresh project `hc<typeof app>` resolved to **`unknown`**: not an empty client, an
          * unusable one. A hand-chained app with the same sub-app-per-resource shape supports it
-         * perfectly, so the shape was never the obstacle — only the statements were.
+         * perfectly, so the shape was never the obstacle, only the statements were.
          */
         const text = [
             `\t\t.${method}(`,
-            ...(method === "on" ? [`\t\t\t${JSON.stringify(route.verb)},`] : []),
+            ...(method === "on" ? [`\t\t\t${JSON.stringify(registrationVerbOf(route.verb))},`] : []),
             `\t\t\t${JSON.stringify(registeredPath)},`,
             ...middleware.map((line) => `\t${line}`),
             "\t\t\tasync (c) => {",
@@ -469,7 +591,7 @@ securityFor) {
     /**
      * Every identifier this file names, imported from the module that declares it.
      *
-     * ⚠️ **Derived from what the rendered text actually references, not from what was available.** An
+     * **Derived from what the rendered text actually references, not from what was available.** An
      * unused import fails the lint a generated file has to pass like any other, and a missing one is a
      * file that does not compile. Both have happened.
      */
@@ -492,21 +614,21 @@ securityFor) {
     /**
      * One `Hono` per resource, declared before the routes and mounted after them.
      *
-     * ⚠️ **Mounted AFTER, deliberately.** `app.route()` copies the sub-app's routes into the parent at
-     * the moment it is called, so mounting before the routes are registered mounts nothing — the same
+     * **Mounted AFTER, deliberately.** `app.route()` copies the sub-app's routes into the parent at
+     * the moment it is called, so mounting before the routes are registered mounts nothing, the same
      * shape of defect as Hono middleware, which only applies to routes registered after it. Declaring
      * at the top and mounting at the bottom is the arrangement that cannot be got wrong by reordering.
      */
     /**
-     * ⚠️ **One chained expression per app, because that is the only shape `hc` can read.**
+     * **One chained expression per app, because that is the only shape `hc` can read.**
      *
      * Hono accumulates its `Schema` type through the chain, so a sub-app declared and then registered
      * across separate statements throws every route's type away. Declaring it AS the chain keeps them,
      * and mounting with a chained `.route()` carries them up into the parent.
      *
-     * ⚠️ **The ordering property that used to need a comment is now structural.** Mounting before the
+     * **The ordering property that used to need a comment is now structural.** Mounting before the
      * routes were registered mounted nothing, and the fix was "declare at the top, mount at the
-     * bottom" — a rule a reordering could break. A single expression cannot be reordered wrongly: the
+     * bottom". A rule a reordering could break. A single expression cannot be reordered wrongly: the
      * sub-app is complete at the point it is mounted because it is its own initialiser.
      */
     const byTarget = new Map();
@@ -526,28 +648,31 @@ securityFor) {
      * Everything that stays on the root, then every mount, as one returned chain.
      *
      * Returned rather than discarded: `registerRoutes` used to be `void`, and measured in a fresh
-     * project that made `hc<typeof app>` resolve to **`unknown`** — Hono's RPC client, which is one of
+     * project that made `hc<typeof app>` resolve to **`unknown`**. Hono's RPC client, which is one of
      * the framework's headline features, was categorically unavailable to anything this emitter
      * produced. Handing back the chained value costs nothing and restores it.
      */
     const rootChain = [...(byTarget.get("app") ?? []), ...subAppMounts];
     // Imported only where a route actually negotiates: an unused import fails the repo's own lint.
     const negotiates = [...grouped.values()].some((group) => group.length > 1);
+    // Same rule: imported only where a HEAD operation stands alone on its path.
+    const guardsHead = registrations.some((registration) => registration.text.includes("headOnly,"));
+    const dispatchesBody = registrations.some((r) => r.text.includes("byContentType(["));
     const runtimeModule = JSON.stringify(emitted.options.runtimeModule);
     /**
-     * ⚠️ **One base sub-app, mounted with `app.route()` — Hono's own nesting, not a rewritten path on
+     * **One base sub-app, mounted with `app.route()`. Hono's own nesting, not a rewritten path on
      * every registration.** Prefixing each path individually would fight the resource grouping, and
      * would put the prefix in `hc`'s type surface as part of every route name rather than once. A
      * nested `.route()` composes exactly, and the parent's `app.routes` still reports the fully
      * composed path, which every arm that counts routes depends on.
      */
-    const usesBasePath = basePath !== undefined && basePath !== "";
+    const usesBasePath = basePaths.length > 0;
     const needsHonoValue = subApps.size > 0 || usesBasePath;
     return `${GENERATED_BANNER}
 import { zValidator } from "@hono/zod-validator";
 ${needsHonoValue ? 'import { Hono } from "hono";\nimport type { Context, Input } from "hono";' : 'import type { Context, Hono, Input } from "hono";'}
 import { z } from "zod";
-import type { AppEnv, Awaitable, Ctx, Result, RouteDeps } from ${runtimeModule};${negotiates ? `\nimport { selectContentType } from ${runtimeModule};` : ""}
+import type { AppEnv, Awaitable, Ctx, Result, RouteDeps } from ${runtimeModule};${negotiates ? `\nimport { selectContentType } from ${runtimeModule};` : ""}${guardsHead ? `\nimport { headOnly } from ${runtimeModule};` : ""}${dispatchesBody ? `\nimport { byContentType } from ${runtimeModule};` : ""}
 ${imports}
 /**
  * One method per operation, each concretely typed from the schemas it validates against.
@@ -562,21 +687,21 @@ ${methods.join("\n")}
 /**
  * One alias per operation, so a handler can live beside the module it belongs to.
  *
- * ⚠️ **Derived by indexed access, never restated.** An indexed access into Operations cannot drift
+ * **Derived by indexed access, never restated.** An indexed access into Operations cannot drift
  * from the interface; a second hand-written signature could, and a signature that silently disagrees
  * with the contract is the whole failure mode this emitter exists to remove.
  */
 ${aliases.join("\n")}
 
 /**
- * ⚠️ **There is deliberately NO exported HandlersFor alias to annotate the factory with.**
+ * **There is deliberately NO exported HandlersFor alias to annotate the factory with.**
  *
  * There was one, and it silently disabled the guard below. Annotating widens the value to
  * Operations, so T infers as Operations, Exclude<keyof T, keyof Operations> is never, and the
  * surplus-key constraint evaporates. Measured: a handler for an operation the spec no longer
  * declares produced no error at all through the annotated form, and TS2345 without it.
  *
- * Write the factory unannotated — inference then carries the real shape into registerRoutes:
+ * Write the factory unannotated, inference then carries the real shape into registerRoutes:
  *
  *     const handlersFor = (c) => backendFor(c.env);
  *     registerRoutes(app, handlersFor, deps);
@@ -585,7 +710,7 @@ ${aliases.join("\n")}
 /**
  * Refuses a handler set carrying an operation the spec no longer declares.
  *
- * ⚠️ **Removal is the change the type system misses, and it is the one that matters most.** Adding an
+ * **Removal is the change the type system misses, and it is the one that matters most.** Adding an
  * operation is a missing property; changing one is a wrong signature; both fail loudly. Removing one
  * leaves a handler that compiles forever against a route nobody mounts.
  *
@@ -602,7 +727,7 @@ export function registerRoutes<T extends Operations>(
 	deps: RouteDeps,
 ) {
 ${subAppDeclarations}${usesBasePath
-        ? `\tconst basePathRoutes = new Hono<AppEnv>()\n${rootChain.join("\n")};\n\n\treturn app.route(${JSON.stringify(basePath)}, basePathRoutes);`
+        ? `\tconst basePathRoutes = new Hono<AppEnv>()\n${rootChain.join("\n")};\n\n\treturn app${basePaths.map((prefix) => `\n\t\t.route(${JSON.stringify(prefix)}, basePathRoutes)`).join("")};`
         : `\treturn app\n${rootChain.join("\n")};`}
 }
 `;