@nanobpm/urban 0.41.0 → 0.42.0

package/dist/runtime/core/modules/api.d.ts

@@ -13,6 +13,33 @@ export interface ApiBinding {
      *  for free — the UI reads the SAME OpenAPI document the runtime routes + validates from. */
     docs?: boolean | 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 declare function deriveSwaggerUrls(pageHref: string, docsBase: string, apiBase: string, relSpec: string): {
+    specUrl: string;
+    server: string | null;
+};
 /** The `{ params, query, body }` contract a typed operation is generic over. `body` is optional so
  *  a generated request type for an operation without a required requestBody (its `body?` is
  *  optional/`undefined`) still satisfies the constraint — see the generated `operations.ts` /

package/dist/runtime/core/modules/api.js

@@ -28,10 +28,49 @@ const SWAGGER_UI_VERSION = "5.17.14";
 function escapeHtml(s) {
     return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c] ?? c);
 }
+/**
+ * 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, docsBase, apiBase, relSpec) {
+    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, specUrl) {
+ *  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, specUrl, docsBase, apiBase) {
     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>
@@ -47,7 +86,22 @@ function swaggerUiPage(title, specUrl) {
 <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>`;
@@ -201,12 +255,13 @@ export function mountApi(ctx, app) {
     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) => p.split("/").filter(Boolean).pop() ?? "";
     const parentPath = (p) => {
         const parts = p.split("/").filter(Boolean);
@@ -217,8 +272,7 @@ export function mountApi(ctx, app) {
     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
     // pattern). A malformed/unreadable spec surfaces as a 500 on request — with the reason — rather
@@ -605,7 +659,7 @@ export function mountApi(ctx, app) {
         return json({ ...d, servers: [{ url: serversUrl }] });
     };
     const docsTitle = `${ctx.manifest.name ?? "App"} — API docs`;
-    const serveDocs = () => html(swaggerUiPage(docsTitle, specDocUrl));
+    const serveDocs = () => 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/dist/runtime/core/modules/pages.js

@@ -474,7 +474,9 @@ body { margin:0; font:15px/1.5 system-ui,sans-serif; padding:2rem; max-width:64r
 .pc-card h2 { font-size:1rem; margin:0 0 .75rem; }
 .pc-field { display:flex; flex-direction:column; gap:.25rem; margin-bottom:.6rem; }
 .pc-field label { font-size:.8rem; color:var(--nano-text-muted); }
-.pc-field input { padding:.5rem .6rem; border:1px solid var(--nano-edge); border-radius:.4rem; font:inherit; background:var(--nano-inset); color:var(--nano-text); }
+.pc-field input:not([type=checkbox]) { padding:.5rem .6rem; border:1px solid var(--nano-edge); border-radius:.4rem; font:inherit; background:var(--nano-inset); color:var(--nano-text); }
+.pc-field-check label { display:flex; flex-direction:row; align-items:center; gap:.5rem; font-size:.9rem; color:var(--nano-text); cursor:pointer; }
+.pc-field-check input { width:auto; padding:0; accent-color:var(--nano-accent); cursor:pointer; }
 .pc-btn { padding:.5rem .9rem; border:0; border-radius:.4rem; background:var(--nano-accent); color:var(--nano-on-accent); font:inherit; cursor:pointer; }
 .pc-btn:disabled { opacity:.5; cursor:default; }
 .pc-msg { font-size:.85rem; margin-top:.5rem; min-height:1.2em; }
@@ -781,8 +783,24 @@ function renderActionForm(node) {
   const inputs = new Map();
   const fieldTypes = new Map();
   for (const f of p.fields || []) {
-    const kind = f.type === "number" ? "number" : "text";
+    const kind = f.type === "checkbox" ? "checkbox" : (f.type === "number" ? "number" : "text");
     fieldTypes.set(f.key, kind);
+    if (kind === "checkbox") {
+      // A boolean field renders a real checkbox; its default checked state comes
+      // from default/checked on the field (unset -> unchecked). We record that on
+      // the input's defaultChecked so a post-submit reset can restore it without a
+      // side map that could drift from the actual input.
+      const checked = f.default === true || f.checked === true;
+      const input = el("input", { type: "checkbox" });
+      input.defaultChecked = checked;
+      input.checked = checked;
+      inputs.set(f.key, input);
+      // Input-first, wrapped in the label so the whole row is a click target.
+      card.append(
+        el("div", { class: "pc-field pc-field-check" }, el("label", {}, input, " " + (f.label || f.key))),
+      );
+      continue;
+    }
     const attrs = { type: kind, placeholder: f.label || f.key };
     if (kind === "number") {
       attrs.inputmode = "numeric";
@@ -799,7 +817,11 @@ function renderActionForm(node) {
   btn.addEventListener("click", async () => {
     const variables = Object.create(null);
     for (const [k, input] of inputs) {
-      if (fieldTypes.get(k) === "number") {
+      if (fieldTypes.get(k) === "checkbox") {
+        // Always emit a real boolean (checked -> true / false), never a string,
+        // so a strict equality check on the action side sees the intended value.
+        variables[k] = input.checked === true;
+      } else if (fieldTypes.get(k) === "number") {
         const t = String(input.value).trim();
         // Blank → omit so the action-side default applies; a non-finite parse
         // (NaN/Infinity) is also omitted rather than smuggling a raw string
@@ -822,7 +844,12 @@ function renderActionForm(node) {
       msg.className = "pc-msg ok";
       msg.textContent = (p.action && p.action.successLabel) ||
         (res && res.processInstanceKey != null ? "Started (instance " + res.processInstanceKey + ")" : "Done");
-      for (const input of inputs.values()) input.value = "";
+      for (const [k, input] of inputs) {
+        // Text/number inputs clear; a checkbox resets to its declared default,
+        // read straight off the input's defaultChecked (no side map to drift).
+        if (fieldTypes.get(k) === "checkbox") input.checked = input.defaultChecked;
+        else input.value = "";
+      }
       document.dispatchEvent(new CustomEvent("pc:refresh"));
     } catch (e) {
       msg.className = "pc-msg err"; msg.textContent = String(e.message || e);

package/dist/runtime/index.d.ts

@@ -6,7 +6,8 @@ export { collectManifestIssues, ManifestValidationError, validateManifest, } fro
 export type { ValidationIssue } from "./core/validate.ts";
 export type { EngineClient, EngineJob, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, SqliteDb, WatchHandle, WorkerSubscription, } from "./core/host.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
-export type { Logger, LogLevel, LogFields } from "./core/logger.ts";
+export { createLogger } from "./core/logger.ts";
+export type { Logger, LogLevel, LogFields, LogSink } from "./core/logger.ts";
 export { BpmnError, isBpmnError } from "./core/host.ts";
 export { adaptConnectorHandler, mountConnectors, resolveInstalledConnectors, } from "./core/modules/connectors.ts";
 export type { ConnectorsHandle } from "./core/modules/connectors.ts";

package/dist/runtime/index.js

@@ -5,6 +5,9 @@ export { createUrbanApp } from "./core/runtime.js";
 export { expandEnv, expandEnvString, loadManifest, parseManifest, workerJobType, } from "./core/manifest.js";
 // Validation
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.js";
+// Structured logging surface (see core/logger.ts): the shape of `AppApi.log`, plus `createLogger`
+// so consumers can build a Logger for a custom sink or a no-op test double (`createLogger(() => {})`).
+export { createLogger } from "./core/logger.js";
 // BPMN error contract: a handler throws `BpmnError(code)` to raise a modelled
 // error routed to an error boundary (ADR 0050), instead of a retryable failure.
 export { BpmnError, isBpmnError } from "./core/host.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.41.0",
+	"version": "0.42.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

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

@@ -353,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

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

@@ -525,7 +525,9 @@ body { margin:0; font:15px/1.5 system-ui,sans-serif; padding:2rem; max-width:64r
 .pc-card h2 { font-size:1rem; margin:0 0 .75rem; }
 .pc-field { display:flex; flex-direction:column; gap:.25rem; margin-bottom:.6rem; }
 .pc-field label { font-size:.8rem; color:var(--nano-text-muted); }
-.pc-field input { padding:.5rem .6rem; border:1px solid var(--nano-edge); border-radius:.4rem; font:inherit; background:var(--nano-inset); color:var(--nano-text); }
+.pc-field input:not([type=checkbox]) { padding:.5rem .6rem; border:1px solid var(--nano-edge); border-radius:.4rem; font:inherit; background:var(--nano-inset); color:var(--nano-text); }
+.pc-field-check label { display:flex; flex-direction:row; align-items:center; gap:.5rem; font-size:.9rem; color:var(--nano-text); cursor:pointer; }
+.pc-field-check input { width:auto; padding:0; accent-color:var(--nano-accent); cursor:pointer; }
 .pc-btn { padding:.5rem .9rem; border:0; border-radius:.4rem; background:var(--nano-accent); color:var(--nano-on-accent); font:inherit; cursor:pointer; }
 .pc-btn:disabled { opacity:.5; cursor:default; }
 .pc-msg { font-size:.85rem; margin-top:.5rem; min-height:1.2em; }
@@ -833,8 +835,24 @@ function renderActionForm(node) {
   const inputs = new Map();
   const fieldTypes = new Map();
   for (const f of p.fields || []) {
-    const kind = f.type === "number" ? "number" : "text";
+    const kind = f.type === "checkbox" ? "checkbox" : (f.type === "number" ? "number" : "text");
     fieldTypes.set(f.key, kind);
+    if (kind === "checkbox") {
+      // A boolean field renders a real checkbox; its default checked state comes
+      // from default/checked on the field (unset -> unchecked). We record that on
+      // the input's defaultChecked so a post-submit reset can restore it without a
+      // side map that could drift from the actual input.
+      const checked = f.default === true || f.checked === true;
+      const input = el("input", { type: "checkbox" });
+      input.defaultChecked = checked;
+      input.checked = checked;
+      inputs.set(f.key, input);
+      // Input-first, wrapped in the label so the whole row is a click target.
+      card.append(
+        el("div", { class: "pc-field pc-field-check" }, el("label", {}, input, " " + (f.label || f.key))),
+      );
+      continue;
+    }
     const attrs = { type: kind, placeholder: f.label || f.key };
     if (kind === "number") {
       attrs.inputmode = "numeric";
@@ -851,7 +869,11 @@ function renderActionForm(node) {
   btn.addEventListener("click", async () => {
     const variables = Object.create(null);
     for (const [k, input] of inputs) {
-      if (fieldTypes.get(k) === "number") {
+      if (fieldTypes.get(k) === "checkbox") {
+        // Always emit a real boolean (checked -> true / false), never a string,
+        // so a strict equality check on the action side sees the intended value.
+        variables[k] = input.checked === true;
+      } else if (fieldTypes.get(k) === "number") {
         const t = String(input.value).trim();
         // Blank → omit so the action-side default applies; a non-finite parse
         // (NaN/Infinity) is also omitted rather than smuggling a raw string
@@ -874,7 +896,12 @@ function renderActionForm(node) {
       msg.className = "pc-msg ok";
       msg.textContent = (p.action && p.action.successLabel) ||
         (res && res.processInstanceKey != null ? "Started (instance " + res.processInstanceKey + ")" : "Done");
-      for (const input of inputs.values()) input.value = "";
+      for (const [k, input] of inputs) {
+        // Text/number inputs clear; a checkbox resets to its declared default,
+        // read straight off the input's defaultChecked (no side map to drift).
+        if (fieldTypes.get(k) === "checkbox") input.checked = input.defaultChecked;
+        else input.value = "";
+      }
       document.dispatchEvent(new CustomEvent("pc:refresh"));
     } catch (e) {
       msg.className = "pc-msg err"; msg.textContent = String(e.message || e);

package/src/runtime/index.ts

@@ -54,8 +54,10 @@ export type {
   WorkerSubscription,
 } from "./core/host.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
-// Structured logging surface (see core/logger.ts): the shape of `AppApi.log`.
-export type { Logger, LogLevel, LogFields } from "./core/logger.ts";
+// Structured logging surface (see core/logger.ts): the shape of `AppApi.log`, plus `createLogger`
+// so consumers can build a Logger for a custom sink or a no-op test double (`createLogger(() => {})`).
+export { createLogger } from "./core/logger.ts";
+export type { Logger, LogLevel, LogFields, LogSink } from "./core/logger.ts";
 
 // BPMN error contract: a handler throws `BpmnError(code)` to raise a modelled
 // error routed to an error boundary (ADR 0050), instead of a retryable failure.