@nanobpm/urban 0.40.2 → 0.42.0

package/src/openapi/spec.test.ts

@@ -12,6 +12,7 @@ import {
   parseSpec,
   resolveSchema,
   responseSchemaForStatus,
+  sharedRequestBodySchemas,
   toRouteMatcher,
   undeclaredPathParams,
   undeclaredSecuritySchemes,
@@ -333,6 +334,72 @@ test("validateValue enforces allOf (intersection), anyOf/oneOf (union) — match
   assert.ok(validateValue(doc, one, "x").length > 0); // matches NEITHER
 });
 
+test("validateValue: a failed oneOf discriminant names the shapes and surfaces the closest variant", () => {
+  // The Camunda-style discriminated request body: exactly one of two mutually-exclusive variants
+  // (mutual exclusion enforced by additionalProperties:false + a distinct required discriminant).
+  const byPr: OpenApiSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["pr"],
+    properties: { pr: { type: "string" }, maxRounds: { type: "integer" } },
+  };
+  const byUrl: OpenApiSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["url"],
+    properties: { url: { type: "string" }, maxRounds: { type: "integer" } },
+  };
+  const start: OpenApiSchema = { oneOf: [byPr, byUrl] };
+
+  // Neither discriminant supplied → matched 0. The summary must NAME the allowed shapes, and the
+  // closest variant's own issue must be surfaced (not just the opaque "matched 0").
+  const none = validateValue(doc, start, { maxRounds: 3 }, "body");
+  assert.ok(none.length > 0, "an empty discriminant is rejected");
+  assert.ok(
+    none.some((i) => /allowed:.*\{pr\}.*\|.*\{url\}/.test(i.message)),
+    `summary names the allowed shapes: ${JSON.stringify(none)}`,
+  );
+  assert.ok(
+    none.some((i) => i.path === "body/pr" && /required/.test(i.message)),
+    `closest variant's field issue is surfaced: ${JSON.stringify(none)}`,
+  );
+
+  // Both discriminants supplied → with additionalProperties:false, EACH variant rejects the other's
+  // field, so this is also "matches none" (the desirable strictness — a body can't smuggle both).
+  const both = validateValue(doc, start, { pr: "a/b#1", url: "http://x" }, "body");
+  assert.ok(
+    both.some((i) => /does not match any of the 2 allowed shapes/.test(i.message)),
+    `supplying both discriminants is rejected by the strict variants: ${JSON.stringify(both)}`,
+  );
+
+  // Exactly one discriminant → valid.
+  assert.equal(validateValue(doc, start, { pr: "a/b#1" }, "body").length, 0);
+
+  // `anyOf` no-match reporting mirrors `oneOf`: name the allowed shapes AND surface the closest
+  // variant's issues, so the improved diagnostics are guarded for the union branch too. Here a value
+  // matches NEITHER discriminated variant, and `{pr}` is the closest (its own field is the issue).
+  const anyStart: OpenApiSchema = { anyOf: [byPr, byUrl] };
+  const anyNone = validateValue(doc, anyStart, { maxRounds: 3 }, "body");
+  assert.ok(anyNone.length > 0, "a value matching no anyOf variant is rejected");
+  assert.ok(
+    anyNone.some((i) => /allowed:.*\{pr\}.*\|.*\{url\}/.test(i.message)),
+    `anyOf summary names the allowed shapes: ${JSON.stringify(anyNone)}`,
+  );
+  assert.ok(
+    anyNone.some((i) => i.path === "body/pr" && /required/.test(i.message)),
+    `anyOf surfaces the closest variant's field issue: ${JSON.stringify(anyNone)}`,
+  );
+
+  // The "matched more than one" branch: genuinely overlapping (non-exclusive) variants. A value that
+  // satisfies two shapes is ambiguous and must be reported as such.
+  const overlapping: OpenApiSchema = { oneOf: [{ type: "integer" }, { type: "integer", minimum: 10 }] };
+  const ambiguous = validateValue(doc, overlapping, 20, "n");
+  assert.ok(
+    ambiguous.some((i) => /must match exactly one of the 2 allowed shapes, but matched 2/.test(i.message)),
+    `ambiguous (multi-match) is reported: ${JSON.stringify(ambiguous)}`,
+  );
+});
+
 test("undeclaredPathParams flags path-template params with no declared parameter", () => {
   const drift: OpenApiDoc = {
     openapi: "3.0.0",
@@ -608,3 +675,30 @@ test("responseSchemaForStatus: a status-range ('2XX') covers concrete statuses i
   assert.equal(responseSchemaForStatus(entries, 200)?.type, "string"); // 2XX class → range schema
   assert.equal(responseSchemaForStatus(entries, 404)?.type, "object"); // outside 2XX → default
 });
+
+test("sharedRequestBodySchemas: flags a requestBody $ref reused across operations, ignores single-use", () => {
+  const jsonRef = (ref: string) => ({ requestBody: { content: { "application/json": { schema: { $ref: ref } } } } });
+  const doc: OpenApiDoc = {
+    openapi: "3.1.0",
+    components: {
+      schemas: {
+        StartVariables: { type: "object" },
+        FeatureAnswer: { type: "object" },
+      },
+    },
+    paths: {
+      // Two operations share the SAME loose body schema — the defect fingerprint.
+      "/convergence": { post: { operationId: "startConvergenceLoop", ...jsonRef("#/components/schemas/StartVariables") } },
+      "/fanout": { post: { operationId: "startPlanFanout", ...jsonRef("#/components/schemas/StartVariables") } },
+      // A distinct, single-use body — must NOT be flagged.
+      "/feature": { post: { operationId: "answerFeature", ...jsonRef("#/components/schemas/FeatureAnswer") } },
+      // An inline (non-$ref) body — no shared identity to compare, must NOT be flagged.
+      "/inline": { post: { operationId: "inlineBody", requestBody: { content: { "application/json": { schema: { type: "object" } } } } } },
+    },
+  };
+
+  const shared = sharedRequestBodySchemas(doc);
+  assert.equal(shared.length, 1, `only the reused ref is flagged: ${JSON.stringify(shared)}`);
+  assert.equal(shared[0].ref, "#/components/schemas/StartVariables");
+  assert.deepEqual(shared[0].operationIds, ["startConvergenceLoop", "startPlanFanout"]); // sorted
+});

package/src/openapi/spec.ts

@@ -338,6 +338,32 @@ export function assertUniqueOperationIds(doc: OpenApiDoc): void {
   }
 }
 
+/** Groups of operationIds that name the SAME requestBody schema `$ref` as their JSON body,
+ *  keyed by that ref (only refs shared by two or more operations are returned, sorted). A single
+ *  request-body schema reused verbatim by multiple operations is the structural fingerprint of the
+ *  "one permissive schema standing in for what should be mutually-exclusive variants" defect: two
+ *  operations that genuinely want different shapes (e.g. `startConvergenceLoop` wants pr|url,
+ *  `startPlanFanout` wants issue|url) are forced to share one loose object, so neither can be
+ *  tightened without breaking the other. gen surfaces this as a non-fatal warning so an author can
+ *  split it into per-operation named variants + `oneOf` (the Camunda REST v2 pattern). Structural
+ *  only (pure, total) — the message is built by the caller. */
+export function sharedRequestBodySchemas(doc: OpenApiDoc): { ref: string; operationIds: string[] }[] {
+  const byRef = new Map<string, string[]>();
+  for (const op of collectOperations(doc)) {
+    const ref = op.requestBodySchema?.$ref;
+    if (typeof ref !== "string" || ref.length === 0) continue;
+    const ids = byRef.get(ref) ?? [];
+    ids.push(op.operationId);
+    byRef.set(ref, ids);
+  }
+  const out: { ref: string; operationIds: string[] }[] = [];
+  for (const [ref, ids] of byRef) {
+    if (ids.length > 1) out.push({ ref, operationIds: [...ids].sort() });
+  }
+  out.sort((a, b) => a.ref.localeCompare(b.ref));
+  return out;
+}
+
 /** "method path" pointers for every operation that declares no `operationId`. Such operations are
  *  unroutable (no delegate to bind), so the runtime mount logs them at `warn` and skips them. */
 export function operationsWithoutId(doc: OpenApiDoc): string[] {
@@ -697,6 +723,36 @@ function matchesAnyType(declared: string[], value: unknown): boolean {
   return declared.some((t) => matchesType(t, value));
 }
 
+/** A short, human-readable label for one `anyOf`/`oneOf` variant, so a composition failure can name
+ *  the allowed shapes instead of an opaque "matched 0". Prefers the variant's discriminant — its
+ *  `required` fields (e.g. `{pr}` vs `{url}`) — since that is exactly what a caller must choose
+ *  between; falls back to the declared type(s), else "object". */
+function variantLabel(doc: OpenApiDoc, variant: OpenApiSchema): string {
+  const s = resolveSchema(doc, variant);
+  if (!s) return "?";
+  const req = Array.isArray(s.required) ? s.required : [];
+  if (req.length > 0) return `{${req.join(", ")}}`;
+  const types = schemaTypeList(s);
+  return types.length > 0 ? types.join("|") : "object";
+}
+
+/** The `(allowed: {pr} | {url})` suffix for a composition-failure summary message. */
+function variantSummary(doc: OpenApiDoc, variants: OpenApiSchema[]): string {
+  return ` (allowed: ${variants.map((v) => variantLabel(doc, v)).join(" | ")})`;
+}
+
+/** When a `oneOf`/`anyOf` matched no variant, surface actionable detail: the issues of the variant
+ *  the value was CLOSEST to (fewest problems). For the discriminant case this is the shape the
+ *  caller meant, so its issues read like `pr: is required` / `url: is not an allowed property`
+ *  instead of a bare "matched 0". Ties resolve to the earliest variant (declaration order). */
+function closestVariantIssues(perVariant: ValidationIssue[][]): ValidationIssue[] {
+  let best: ValidationIssue[] | undefined;
+  for (const iss of perVariant) {
+    if (best === undefined || iss.length < best.length) best = iss;
+  }
+  return best ?? [];
+}
+
 /** Validate `value` against `schema` (resolving local $refs against `doc`), returning every issue
  *  found (empty = valid). A pragmatic JSON-Schema subset; unknown keywords are ignored. */
 export function validateValue(
@@ -743,13 +799,47 @@ export function validateValue(
   if (schema.allOf) {
     for (const sub of schema.allOf) issues.push(...validateValue(doc, sub, value, path));
   }
-  if (schema.anyOf && !schema.anyOf.some((sub) => validateValue(doc, sub, value, path).length === 0)) {
-    issues.push({ path: at, message: "does not match any schema in anyOf" });
+  if (schema.anyOf) {
+    // `anyOf` needs only ONE match, so short-circuit on the first clean variant — `validateValue`
+    // runs on every request (params/query/body/response) and evaluating every variant for a large
+    // schema is needless work once we have a hit. Only when NO variant matches do we build the full
+    // per-variant issue list to name the allowed shapes and surface the closest variant's issues.
+    let anyMatched = false;
+    const perVariant: ValidationIssue[][] = [];
+    for (const sub of schema.anyOf) {
+      const subIssues = validateValue(doc, sub, value, path);
+      if (subIssues.length === 0) {
+        anyMatched = true;
+        break;
+      }
+      perVariant.push(subIssues);
+    }
+    if (!anyMatched) {
+      issues.push({
+        path: at,
+        message: `does not match any of the ${schema.anyOf.length} allowed shapes${variantSummary(doc, schema.anyOf)}`,
+      });
+      issues.push(...closestVariantIssues(perVariant));
+    }
   }
   if (schema.oneOf) {
-    const matched = schema.oneOf.filter((sub) => validateValue(doc, sub, value, path).length === 0).length;
-    if (matched !== 1) {
-      issues.push({ path: at, message: `must match exactly one schema in oneOf (matched ${matched})` });
+    const perVariant = schema.oneOf.map((sub) => validateValue(doc, sub, value, path));
+    const matched = perVariant.filter((v) => v.length === 0).length;
+    if (matched === 0) {
+      // No variant matched: name the allowed shapes AND surface the closest variant's issues, so a
+      // discriminated body (e.g. exactly one of pr|url) fails with actionable detail, not "matched 0".
+      issues.push({
+        path: at,
+        message: `does not match any of the ${schema.oneOf.length} allowed shapes${variantSummary(doc, schema.oneOf)}`,
+      });
+      issues.push(...closestVariantIssues(perVariant));
+    } else if (matched > 1) {
+      // Matched more than one: the shapes are not mutually exclusive for this value (usually a body
+      // that supplies two discriminants, or under-constrained variants). Report the ambiguity.
+      issues.push({
+        path: at,
+        message: `must match exactly one of the ${schema.oneOf.length} allowed shapes, but matched ${matched}${variantSummary(doc, schema.oneOf)}`,
+      });
     }
   }
 

package/src/runtime/core/logger.test.ts

@@ -219,3 +219,14 @@ test("child() never throws when the added bindings are hostile — degrades to t
   assert.equal(records[0].msg, "shipped");
   assert.deepEqual({ ...records[0].fields }, { orderId: "o1" });
 });
+
+test("createLogger is re-exported from the runtime public barrel", async () => {
+  // Consumers build a Logger via the package entry (`@nanobpm/urban/runtime`) — e.g. a no-op sink
+  // for test doubles of `app.log`, or a custom sink in app code — so the barrel must expose it.
+  const barrel = await import("../index.ts");
+  assert.equal(typeof barrel.createLogger, "function");
+  const { records, sink } = recorder();
+  barrel.createLogger(sink).info("via-barrel");
+  assert.equal(records.length, 1);
+  assert.equal(records[0].msg, "via-barrel");
+});

package/src/runtime/core/modules/api.test.ts

@@ -6,7 +6,7 @@ import type { AppManifest } from "../manifest.ts";
 import type { EngineClient, HostContext, HttpRequest } from "../host.ts";
 import { makeRouter } from "../router.ts";
 import { DataLayer } from "./datasource.ts";
-import { mountApi, resolveOperationHandler, apiDocsPath, NotImplemented, type ApiHandle, type OperationHandler } from "./api.ts";
+import { mountApi, resolveOperationHandler, apiDocsPath, deriveSwaggerUrls, NotImplemented, type ApiHandle, type OperationHandler } from "./api.ts";
 
 function req(
   method: string,
@@ -746,12 +746,137 @@ test("serves the Swagger UI page at {base}-docs by default", async () => {
   assert.match(res.headers?.["content-type"] ?? "", /text\/html/);
   const body = res.body ?? "";
   assert.match(body, /swagger-ui/);
-  // The UI reads the spec via a DOCUMENT-relative URL (issue #151) so it resolves through the
-  // Nano console reverse proxy, not a root-absolute path that escapes to the console origin.
-  assert.match(body, /url: "api-docs\/openapi\.json"/);
+  // The page derives ABSOLUTE spec + server URLs from window.location (issue #151 + the trailing-
+  // slash 404): the embedded derivation is passed the mount-root docs base, operations base, and a
+  // document-relative fallback. It must never hard-code a root-absolute "/app/api-docs/openapi.json"
+  // that would escape the Nano console reverse-proxy prefix.
+  assert.match(body, /window\.location\.href/);
+  assert.match(body, /"\/app\/api-docs"/); // docsBase handed to the client derivation
+  assert.match(body, /"\/app\/api"/); //     operations base handed to the client derivation
+  assert.match(body, /"api-docs\/openapi\.json"/); // document-relative fallback
   assert.doesNotMatch(body, /url: "\/app\/api-docs\/openapi\.json"/);
 });
 
+test("the rendered docs page runs its derivation end-to-end and targets the app through the proxy", async () => {
+  const { router } = build({ spec: "openapi.json" }, {});
+  const res = await router(req("GET", "/app/api-docs"));
+  const body = res.body ?? "";
+  // Extract the inline bootstrap <script> (the one that is NOT the swagger-ui-bundle src include).
+  const scripts = [...body.matchAll(/<script>([\s\S]*?)<\/script>/g)].map((m) => m[1]);
+  assert.ok(scripts.length >= 1, "expected an inline bootstrap script");
+  const boot = scripts[scripts.length - 1];
+  // 1) It must be syntactically valid JS (guards the `${derive.toString()}` template interpolation).
+  const runBoot = new Function("window", "SwaggerUIBundle", "fetch", boot);
+  // 2) Execute it in a mocked browser at the EXACT reported failing URL (proxy prefix + trailing
+  //    slash) and assert the servers override Swagger UI receives is the app's /app/api under the
+  //    proxy — never the /app/api-docs/api that produced the 404.
+  const specDoc = { openapi: "3.0.3", paths: {}, servers: [{ url: "api" }] };
+  let received: unknown;
+  const swaggerStub = (opts: { spec?: { servers?: unknown } }): unknown => {
+    received = opts.spec?.servers;
+    return {};
+  };
+  const proxySlashUrl = "http://127.0.0.1:8080/console/app-view/Nano_Workforce/app/api-docs/";
+  const win: { location: { href: string }; ui?: unknown } = { location: { href: proxySlashUrl } };
+  let fetched = "";
+  const fetchStub = (url: string): Promise<{ ok: boolean; json: () => Promise<unknown> }> => {
+    fetched = url;
+    return Promise.resolve({ ok: true, json: () => Promise.resolve(specDoc) });
+  };
+  runBoot(win, swaggerStub, fetchStub);
+  await new Promise((r) => setTimeout(r, 0)); // let the fetch().then microtasks settle
+  assert.equal(
+    fetched,
+    "http://127.0.0.1:8080/console/app-view/Nano_Workforce/app/api-docs/openapi.json",
+    "spec is fetched at an absolute, proxy-prefixed URL (immune to the trailing slash)",
+  );
+  assert.deepEqual(received, [
+    { url: "http://127.0.0.1:8080/console/app-view/Nano_Workforce/app/api" },
+    // ^ Try it out now targets the app's operations base under the proxy, not /app/api-docs/api.
+  ]);
+});
+
+test("deriveSwaggerUrls: absolute spec+server from the page URL, immune to trailing slash + proxy prefix", () => {
+  const docsBase = "/app/api-docs";
+  const apiBase = "/app/api";
+  const rel = "api-docs/openapi.json";
+  // Direct CLI (:3000), no trailing slash — the canonical case.
+  assert.deepEqual(deriveSwaggerUrls("http://127.0.0.1:3000/app/api-docs", docsBase, apiBase, rel), {
+    specUrl: "http://127.0.0.1:3000/app/api-docs/openapi.json",
+    server: "http://127.0.0.1:3000/app/api",
+  });
+  // Direct CLI WITH a trailing slash — a relative "servers: api" used to resolve to
+  // /app/api-docs/api here (the reported 404). The absolute derivation is unaffected.
+  assert.deepEqual(deriveSwaggerUrls("http://127.0.0.1:3000/app/api-docs/", docsBase, apiBase, rel), {
+    specUrl: "http://127.0.0.1:3000/app/api-docs/openapi.json",
+    server: "http://127.0.0.1:3000/app/api",
+  });
+  // Under the Nano console reverse proxy — the mount prefix is preserved in both URLs.
+  assert.deepEqual(
+    deriveSwaggerUrls(
+      "http://127.0.0.1:8080/console/app-view/Nano_Workforce/app/api-docs",
+      docsBase,
+      apiBase,
+      rel,
+    ),
+    {
+      specUrl: "http://127.0.0.1:8080/console/app-view/Nano_Workforce/app/api-docs/openapi.json",
+      server: "http://127.0.0.1:8080/console/app-view/Nano_Workforce/app/api",
+    },
+  );
+  // Proxy WITH a trailing slash — the exact failure the user reported. Now correct.
+  assert.deepEqual(
+    deriveSwaggerUrls(
+      "http://127.0.0.1:8080/console/app-view/Nano_Workforce/app/api-docs/",
+      docsBase,
+      apiBase,
+      rel,
+    ),
+    {
+      specUrl: "http://127.0.0.1:8080/console/app-view/Nano_Workforce/app/api-docs/openapi.json",
+      server: "http://127.0.0.1:8080/console/app-view/Nano_Workforce/app/api",
+    },
+  );
+  // A query string / fragment on the docs URL is ignored (pathname only).
+  assert.equal(
+    deriveSwaggerUrls("http://127.0.0.1:3000/app/api-docs?x=1#y", docsBase, apiBase, rel).server,
+    "http://127.0.0.1:3000/app/api",
+  );
+});
+
+test("deriveSwaggerUrls: a custom docs path keeps the proxy prefix too", () => {
+  // A string `docs` override lands the page at a root-level `/help`; the derivation still recovers
+  // the (proxy-prefixed) mount root by stripping that suffix and re-appending the operations base.
+  assert.deepEqual(
+    deriveSwaggerUrls(
+      "http://127.0.0.1:8080/console/app-view/App/help/",
+      "/help",
+      "/app/api",
+      "help/openapi.json",
+    ),
+    {
+      specUrl: "http://127.0.0.1:8080/console/app-view/App/help/openapi.json",
+      server: "http://127.0.0.1:8080/console/app-view/App/app/api",
+    },
+  );
+});
+
+test("deriveSwaggerUrls: falls back to the document-relative spec when the path doesn't match or href is bad", () => {
+  const docsBase = "/app/api-docs";
+  const apiBase = "/app/api";
+  const rel = "api-docs/openapi.json";
+  // Page path doesn't end in docsBase (unexpected) → keep the relative fallback, no server override.
+  assert.deepEqual(deriveSwaggerUrls("http://127.0.0.1:3000/elsewhere", docsBase, apiBase, rel), {
+    specUrl: rel,
+    server: null,
+  });
+  // Malformed href → same safe fallback (no throw).
+  assert.deepEqual(deriveSwaggerUrls("not a url", docsBase, apiBase, rel), {
+    specUrl: rel,
+    server: null,
+  });
+});
+
 test("the trailing-slash docs variant 308-redirects to the canonical path", async () => {
   const { router } = build({ spec: "openapi.json" }, {});
   // The router exact-matches non-prefix routes, so `${base}-docs/` (common from proxies/browsers)

package/src/runtime/core/modules/api.ts

@@ -70,10 +70,54 @@ function escapeHtml(s: string): string {
   );
 }
 
+/**
+ * Derive the ABSOLUTE spec + operations-server URLs the Swagger UI page should use, from the docs
+ * page's own address (`pageHref`), the mount-root-relative docs path (`docsBase`, e.g.
+ * `/app/api-docs`) and operations base (`apiBase`, e.g. `/app/api`).
+ *
+ * Why this can't be done server-side: the docs page can load at `<docsBase>` OR `<docsBase>/` (a
+ * trailing slash — reverse proxies and some webviews append one), and behind the Nano console
+ * proxy it carries a path prefix (`/console/app-view/<name>`). A document-relative spec URL or a
+ * relative `servers` entry resolves DIFFERENTLY depending on that trailing slash — which sent
+ * "Try it out" to `<mount>/app/api-docs/api/<op>` (a 404) instead of `<mount>/app/api/<op>`. The
+ * app never sees the proxy prefix, so `window.location` in the browser is the only place with the
+ * full mount path.
+ *
+ * We strip any trailing slash from the page path, then strip the known `docsBase` suffix to recover
+ * the (proxy-prefixed) mount root, and re-append `docsBase`/`apiBase` as ORIGIN-absolute URLs — so
+ * Swagger UI performs no further relative resolution and is immune to the trailing slash. When the
+ * page path doesn't end in `docsBase` (unexpected) or the href is malformed, we fall back to the
+ * document-relative `relSpec` and leave `servers` to the served spec (`server: null`).
+ *
+ * This runs in the browser: it is embedded verbatim into the docs page via `.toString()` so the
+ * shipped page and these unit tests exercise the exact same code (no drift). Keep it dependency-free
+ * and free of template literals / `${}` (it is interpolated into a template literal).
+ */
+export function deriveSwaggerUrls(
+  pageHref: string,
+  docsBase: string,
+  apiBase: string,
+  relSpec: string,
+): { specUrl: string; server: string | null } {
+  try {
+    const loc = new URL(pageHref);
+    const path = loc.pathname.replace(/\/+$/, "");
+    if (path.length >= docsBase.length && path.slice(path.length - docsBase.length) === docsBase) {
+      const mount = loc.origin + path.slice(0, path.length - docsBase.length);
+      return { specUrl: mount + docsBase + "/openapi.json", server: mount + apiBase };
+    }
+  } catch {
+    // Malformed href — fall through to the document-relative fallback below.
+  }
+  return { specUrl: relSpec, server: null };
+}
+
 /** The self-contained Swagger UI page. Static HTML: it renders even when the spec is momentarily
- *  unreadable (Swagger UI fetches `specUrl` itself and surfaces any load/parse error in-page),
- *  which keeps the docs route decoupled from spec-load failures. */
-function swaggerUiPage(title: string, specUrl: string): string {
+ *  unreadable (on a fetch/parse failure it hands `specUrl` to Swagger UI, which surfaces the error
+ *  in-page), which keeps the docs route decoupled from spec-load failures. The client derives
+ *  absolute spec + server URLs from `window.location` via `deriveSwaggerUrls` so "Try it out"
+ *  targets the app regardless of a trailing slash on the docs URL or a reverse-proxy prefix. */
+function swaggerUiPage(title: string, specUrl: string, docsBase: string, apiBase: string): string {
   const css = `https://cdn.jsdelivr.net/npm/swagger-ui-dist@${SWAGGER_UI_VERSION}/swagger-ui.css`;
   const bundle = `https://cdn.jsdelivr.net/npm/swagger-ui-dist@${SWAGGER_UI_VERSION}/swagger-ui-bundle.js`;
   return `<!doctype html>
@@ -89,7 +133,22 @@ function swaggerUiPage(title: string, specUrl: string): string {
 <div id="swagger-ui"></div>
 <script src="${bundle}" crossorigin="anonymous"></script>
 <script>
-window.ui = SwaggerUIBundle({ url: ${JSON.stringify(specUrl)}, dom_id: '#swagger-ui', deepLinking: true });
+(function () {
+  var derive = ${deriveSwaggerUrls.toString()};
+  var urls = derive(window.location.href, ${JSON.stringify(docsBase)}, ${JSON.stringify(apiBase)}, ${JSON.stringify(specUrl)});
+  function boot(opts) { window.ui = SwaggerUIBundle(opts); }
+  fetch(urls.specUrl)
+    .then(function (r) { return r.ok ? r.json() : null; })
+    .then(function (spec) {
+      if (spec && urls.server) { spec.servers = [{ url: urls.server }]; }
+      boot(spec
+        ? { spec: spec, dom_id: '#swagger-ui', deepLinking: true }
+        : { url: urls.specUrl, dom_id: '#swagger-ui', deepLinking: true });
+    })
+    .catch(function () {
+      boot({ url: urls.specUrl, dom_id: '#swagger-ui', deepLinking: true });
+    });
+})();
 </script>
 </body>
 </html>`;
@@ -312,12 +371,13 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
   const dir = binding.dir ?? "operations";
   const surfaceEject = binding.eject === true;
   const specRoutePath = `${docsBase}/openapi.json`;
-  // The Swagger UI page is served at `docsBase` (no trailing slash — the slash variant 308-
-  // redirects onto it), so its browser-relative base is the PARENT directory. Hand Swagger UI a
-  // DOCUMENT-relative spec URL and `servers` entry so both rebase onto the app's mount root:
-  // correct at the origin root (CLI :3000) AND under the Nano console reverse proxy
-  // (/console/app-view/<name>/), where a root-absolute "/app/…" escapes the prefix and hits the
-  // console origin instead of the app (issue #151).
+  // Fallback values for the RAW served spec + docs page. The interactive Swagger UI computes
+  // ABSOLUTE spec + server URLs client-side from `window.location` (see `deriveSwaggerUrls`), which
+  // is immune to a trailing slash on the docs URL and to the Nano console reverse-proxy prefix
+  // (/console/app-view/<name>/). These document-relative values remain (a) the client's fallback
+  // when the page path unexpectedly doesn't end in `docsBase`, and (b) what a non-interactive
+  // consumer reading `openapi.json` directly sees. They still rebase onto the app's mount root
+  // rather than using a root-absolute "/app/…" that would escape the proxy prefix (issue #151).
   const lastSegment = (p: string): string => p.split("/").filter(Boolean).pop() ?? "";
   const parentPath = (p: string): string => {
     const parts = p.split("/").filter(Boolean);
@@ -328,8 +388,7 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
   const specDocUrl = `${lastSegment(docsBase)}/openapi.json`;
   // `servers` can only be relativized when the operations `base` shares the docs page's parent
   // directory (the default `${base}-docs` sibling). For a fully custom `docs` path under a
-  // different parent, keep the root-absolute base (works direct; try-it-out through the proxy is
-  // the documented limitation in #151).
+  // different parent, keep the root-absolute base for the raw spec.
   const serversUrl = parentPath(base) === parentPath(docsBase) ? lastSegment(base) : base;
 
   // Resolve + parse the spec lazily on first request and cache it (mirroring the lazy module load
@@ -741,7 +800,7 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
     return json({ ...d, servers: [{ url: serversUrl }] });
   };
   const docsTitle = `${ctx.manifest.name ?? "App"} — API docs`;
-  const serveDocs = (): HttpResponse => html(swaggerUiPage(docsTitle, specDocUrl));
+  const serveDocs = (): HttpResponse => html(swaggerUiPage(docsTitle, specDocUrl, docsBase, base));
   // A permanent redirect for the trailing-slash variant (`${docsBase}/`). The router only does
   // exact matches for non-prefix routes, so without this a reverse proxy or browser that appends
   // a slash would 404 on the Swagger UI. 308 preserves the method and points at the canonical

package/src/runtime/core/modules/pages.test.ts

@@ -90,12 +90,15 @@ test("GET / serves the renderer shell with the home marker", async () => {
   assert.equal(res.status, 200);
   assert.match(res.headers?.["content-type"] ?? "", /text\/html/);
   assert.match(res.body ?? "", /data-home="home"/);
-  // The runtime module is loaded by a *relative* src so it resolves against the
-  // document's mount path — works both at the origin root and under the Nano
-  // console's /console/app-view/<name>/ reverse proxy. A root-absolute
-  // "/app/runtime.js" would 404 against the console origin and never hydrate.
-  assert.match(res.body ?? "", /src="\.\/app\/runtime\.js"/);
-  assert.doesNotMatch(res.body ?? "", /src="\/app\/runtime\.js"/);
+  // The runtime module is loaded by a *relative*, *content-fingerprinted* src so it resolves
+  // against the document's mount path — works both at the origin root and under the Nano
+  // console's /console/app-view/<name>/ reverse proxy. A root-absolute path would 404 against
+  // the console origin; a non-fingerprinted URL would let a stale browser cache replay an old
+  // module after an upgrade (silently breaking every page action).
+  assert.match(res.body ?? "", /src="\.\/app\/runtime\.[0-9a-f]{8}\.js"/);
+  assert.doesNotMatch(res.body ?? "", /src="\/app\/runtime\./);
+  // The shell itself must never be pinned by the browser (it carries the current module hash).
+  assert.match(res.headers?.["cache-control"] ?? "", /no-cache/);
 });
 
 test("the API docs badge links via a document-relative href (proxy-safe)", async () => {
@@ -145,6 +148,31 @@ test("GET /app/runtime.js serves the renderer module", async () => {
   assert.match(res.body ?? "", /function apiUrl\(u\)/);
 });
 
+test("the fingerprinted runtime URL from the shell is served immutable; the shell references it", async () => {
+  // The shell's <script src> must point at a route the router actually serves, and that route
+  // must carry long-lived immutable caching (the URL is unique per content, so it can never go
+  // stale). This is the cache-bust that stops an upgraded app from replaying an old module.
+  const shell = await dispatch("GET", "/");
+  const m = (shell.body ?? "").match(/src="\.(\/app\/runtime\.[0-9a-f]{8}\.js)"/);
+  assert.ok(m, "shell must reference a fingerprinted runtime URL");
+  const res = await dispatch("GET", m![1]);
+  assert.equal(res.status, 200);
+  assert.match(res.headers?.["content-type"] ?? "", /javascript/);
+  assert.match(res.body ?? "", /pc:refresh/);
+  assert.match(res.headers?.["cache-control"] ?? "", /immutable/);
+  assert.match(res.headers?.["cache-control"] ?? "", /max-age=31536000/);
+});
+
+test("the legacy /app/runtime.js URL still serves the module, but no-cache", async () => {
+  // Back-compat + defence in depth: an old cached shell (or any client) hitting the unhashed URL
+  // still gets the current bytes, and `no-cache` forces revalidation instead of a stale replay.
+  const res = await dispatch("GET", "/app/runtime.js");
+  assert.equal(res.status, 200);
+  assert.match(res.headers?.["content-type"] ?? "", /javascript/);
+  assert.match(res.body ?? "", /pc:refresh/);
+  assert.match(res.headers?.["cache-control"] ?? "", /no-cache/);
+});
+
 test("the shell renders an API-docs badge only when an apiDocsPath is provided", async () => {
   const routes = createPagesRoutes(
     { pagesDir: "pages", homePage: "home", sourceName: "app", apiDocsPath: "/app/api-docs" },
@@ -325,6 +353,22 @@ test("the renderer honours numeric actionForm fields", async () => {
   assert.match(js, /if \(!Number\.isFinite\(num\)\) continue;/);
 });
 
+test("the renderer honours boolean (checkbox) actionForm fields", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // Fields declared `type: "checkbox"` render a real <input type="checkbox">…
+  assert.match(js, /f\.type === "checkbox"/);
+  assert.match(js, /el\("input", \{ type: "checkbox" \}\)/);
+  // …whose default checked state comes from `default`/`checked` on the field…
+  assert.match(js, /f\.default === true \|\| f\.checked === true/);
+  // …and whose submitted value is always a real boolean (never a string), so a
+  // strict `=== true` check on the action side sees the intended value.
+  assert.match(js, /variables\[k\] = input\.checked === true;/);
+  // A post-submit reset restores a checkbox to its declared default (read off the
+  // input's defaultChecked) rather than clearing `.value` (a no-op for a checkbox).
+  assert.match(js, /input\.checked = input\.defaultChecked;/);
+});
+
 test("renderer makes collapsible nodes persist their state across sessions", async () => {
   // A node with `collapsible` gets a clickable header that hides/shows the card
   // body, and the collapsed state is written to localStorage keyed by the home