@nanobpm/urban 0.31.1 → 0.32.0

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

@@ -9,6 +9,10 @@ export interface ApiBinding {
     base?: string;
     validateResponses?: "dev" | "always" | "never";
     eject?: boolean;
+    /** Human API docs (Swagger UI). `true`/omitted → on at `${base}-docs` (ADR 0058); `false` →
+     *  off; a string → a custom absolute route to mount the UI under. Spec-first apps get docs
+     *  for free — the UI reads the SAME OpenAPI document the runtime routes + validates from. */
+    docs?: boolean | string;
 }
 /** The `{ params, query, body }` contract a typed operation is generic over. */
 export interface OperationContract {
@@ -48,6 +52,10 @@ export type OperationHandler<Req extends OperationContract = DefaultContract, Re
 export declare function defineOperation<Req extends OperationContract = DefaultContract, Res = unknown>(_id: string, handler: OperationHandler<Req, Res>): OperationHandler<Req, Res>;
 /** Resolve an operation delegate from a loaded module: `default` (when a function) else `handler`. */
 export declare function resolveOperationHandler(mod: Record<string, unknown>): OperationHandler | undefined;
+/** The Swagger UI route for an app's `api` binding, or `undefined` when there is no api surface
+ *  or docs are disabled. Lets other surfaces (e.g. the pages shell's "API docs" badge) link to
+ *  the docs without re-deriving the path. */
+export declare function apiDocsPath(manifest: unknown): string | undefined;
 export interface ApiHandle {
     readonly name: string;
     routes: Route[];

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

@@ -12,9 +12,41 @@
 // `x-urban-eject: true` OpenAPI vendor extension. The delegate is always additively imperative: it
 // gets the raw `req` and full `AppApi` on top of the validated input.
 import { errorMessage } from "../guards.js";
-import { json, normalizeRoutePath } from "../router.js";
+import { html, json, normalizeRoutePath } from "../router.js";
 import { resolveAppPath } from "./datasource.js";
 import { collectOperations, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, resolveSchema, toRouteMatcher, undeclaredPathParams, validateValue, } from "../../../openapi/spec.js";
+/** Pinned Swagger UI dist served from a CDN, so the docs UI adds zero bundle/runtime deps to an
+ *  Urban app (matching the deps-free spirit of the rest of the surface — validators are standalone,
+ *  ADR 0058 Consequences). Pinned (not `latest`) for reproducibility. */
+const SWAGGER_UI_VERSION = "5.17.14";
+/** Escape HTML-significant characters before embedding a value (the app name) in the docs markup. */
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c] ?? c);
+}
+/** 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) {
+    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>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<link rel="stylesheet" href="${css}">
+<style>body{margin:0}</style>
+</head>
+<body>
+<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 });
+</script>
+</body>
+</html>`;
+}
 /**
  * Typed-identity helper the generated `operations.ts` wrapper re-types per operationId. Authoring:
  * `export default defineOperation("createInvoice", async ({ params, query, body }, app) => { ... })`
@@ -47,6 +79,7 @@ function readApiBinding(manifest) {
     const base = Reflect.get(raw, "base");
     const validateResponses = Reflect.get(raw, "validateResponses");
     const eject = Reflect.get(raw, "eject");
+    const docs = Reflect.get(raw, "docs");
     // Trim benign manifest whitespace so it can't produce hard-to-diagnose path/import failures.
     return {
         spec: spec.trim(),
@@ -56,8 +89,32 @@ function readApiBinding(manifest) {
             ? validateResponses
             : undefined,
         eject: eject === true,
+        // Docs default ON (spec-first apps get Swagger for free); `false` disables; a non-empty
+        // string overrides the route. Anything else (including whitespace) falls back to the default.
+        docs: docs === false ? false : typeof docs === "string" && docs.trim().length > 0 ? docs.trim() : true,
     };
 }
+/** Resolve the api `base` + docs routing from a binding, in ONE place, so `mountApi` (which
+ *  serves the docs) and `apiDocsPath` (which the pages surface links to) can never drift. */
+function resolveApiRoutes(binding) {
+    const base = normalizeRoutePath(binding.base, "/app/api");
+    const docsEnabled = binding.docs !== false;
+    // Swagger UI at a SIBLING of the base (`${base}-docs`, e.g. /app/api-docs), never a subpath
+    // of it — so the docs routes can't collide with, or be shadowed by, the operation dispatcher
+    // that owns the `${base}/` prefix (a string `docs` overrides the whole route).
+    const docsBase = normalizeRoutePath(typeof binding.docs === "string" ? binding.docs : `${base}-docs`, `${base}-docs`);
+    return { base, docsEnabled, docsBase };
+}
+/** The Swagger UI route for an app's `api` binding, or `undefined` when there is no api surface
+ *  or docs are disabled. Lets other surfaces (e.g. the pages shell's "API docs" badge) link to
+ *  the docs without re-deriving the path. */
+export function apiDocsPath(manifest) {
+    const binding = readApiBinding(manifest);
+    if (!binding)
+        return undefined;
+    const { docsEnabled, docsBase } = resolveApiRoutes(binding);
+    return docsEnabled ? docsBase : undefined;
+}
 /** Coerce a wire string to the type its parameter schema declares, so numeric/boolean bounds
  *  validate. A value that will not coerce is left as-is and fails the type check with a clear
  *  message. The delegate still receives the original string(s). */
@@ -89,9 +146,16 @@ export function mountApi(ctx, app) {
     // Normalize the manifest base the same way actions[] routes do (shared normalizeRoutePath):
     // ensure a leading "/", strip trailing slashes, and fall back when empty — otherwise a base
     // like "app/api" would never match request paths, which always start with "/".
-    const base = normalizeRoutePath(binding.base, "/app/api");
+    //
+    // The api `base` and the docs routing are derived TOGETHER by the shared helper (ADR 0058) so
+    // this module (which serves the docs) and `apiDocsPath` (which links to them from the pages
+    // shell) stay in lockstep with a single normalization of `binding.base` — no second, drifting
+    // copy of that logic here. The spec JSON is served under the docs path so the operations
+    // namespace stays purely operations.
+    const { base, docsEnabled, docsBase } = resolveApiRoutes(binding);
     const dir = binding.dir ?? "operations";
     const surfaceEject = binding.eject === true;
+    const specRoutePath = `${docsBase}/openapi.json`;
     // 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
     // than failing app boot.
@@ -351,9 +415,57 @@ export function mountApi(ctx, app) {
         source: `api:${binding.spec}`,
         handler: dispatch,
     };
+    // Docs routes (ADR 0058): the Swagger UI page + the OpenAPI JSON it reads. Both are exact GET
+    // routes on the `${base}-docs` sibling namespace, so they are wholly independent of the
+    // operation dispatcher above.
+    const serveSpec = async () => {
+        let d;
+        try {
+            d = await loadDoc();
+        }
+        catch (e) {
+            return json({ error: errorMessage(e) }, 500);
+        }
+        // Point Swagger UI "Try it out" at the mounted namespace: operations live under `base`
+        // (e.g. /app/api/invoices), not the spec's bare paths (/invoices). Overriding `servers`
+        // makes the interactive console call the real Urban routes rather than the origin root.
+        return json({ ...d, servers: [{ url: base }] });
+    };
+    const docsTitle = `${ctx.manifest.name ?? "App"} — API docs`;
+    const serveDocs = () => html(swaggerUiPage(docsTitle, specRoutePath));
+    // 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
+    // (slash-less) `docsBase` that `apiDocsPath` and every internal link already use.
+    const redirectDocsSlash = () => ({ status: 308, headers: { location: docsBase } });
+    const docsRoutes = docsEnabled
+        ? [
+            { method: "GET", path: docsBase, source: `api-docs:${binding.spec}`, handler: serveDocs },
+            {
+                method: "GET",
+                path: `${docsBase}/`,
+                source: `api-docs:${binding.spec}`,
+                handler: redirectDocsSlash,
+            },
+            {
+                method: "GET",
+                path: specRoutePath,
+                source: `api-docs:${binding.spec}`,
+                handler: serveSpec,
+            },
+        ]
+        : [];
     return {
         name: "api",
-        routes: [rootRoute, route],
-        describe: () => ({ api: { spec: binding.spec, base, dir, eject: surfaceEject } }),
+        routes: [...docsRoutes, rootRoute, route],
+        describe: () => ({
+            api: {
+                spec: binding.spec,
+                base,
+                dir,
+                eject: surfaceEject,
+                docs: docsEnabled ? { ui: docsBase, spec: specRoutePath } : false,
+            },
+        }),
     };
 }

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

@@ -18,6 +18,12 @@ export interface PagesOptions {
     rowLimit?: number;
     /** The injected default datasource name (the alias apps bind to). Default `app`. */
     sourceName?: string;
+    /**
+     * The app's Swagger UI route (from the `api` binding, resolved by `apiDocsPath`). When set,
+     * the shell renders a persistent "API docs" badge linking to it — so a spec-first app surfaces
+     * its interactive docs from its own UI for free. Omitted → no badge (app declares no `api`).
+     */
+    apiDocsPath?: string;
 }
 export interface PagesDeps {
     db: PagesDataSource;

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

@@ -17,6 +17,7 @@
 import { errorMessage, isRecord } from "../guards.js";
 import { html, json } from "../router.js";
 import { cancelInstanceReconciling } from "./cancel.js";
+import { apiDocsPath } from "./api.js";
 import { quoteIdent } from "./gateway.js";
 /** A JavaScript-body response (the renderer module served at /app/runtime.js). */
 function javascript(body, status = 200) {
@@ -66,7 +67,7 @@ export function createPagesRoutes(opts, deps) {
         return p;
     };
     const routes = [];
-    const shell = html(rendererShell(homePage));
+    const shell = html(rendererShell(homePage, opts.apiDocsPath));
     // ── the renderer shell + module ─────────────────────────────────────────
     routes.push({ method: "GET", path: "/", source: "surface:pages", handler: () => shell });
     routes.push({ method: "GET", path: "/index.html", source: "surface:pages", handler: () => shell });
@@ -335,6 +336,9 @@ export function mountPages(ctx, app) {
         homePage: typeof decl.homePage === "string" ? decl.homePage : undefined,
         rowLimit: typeof decl.rowLimit === "number" ? decl.rowLimit : undefined,
         sourceName: typeof decl.sourceName === "string" ? decl.sourceName : undefined,
+        // Link the shell's "API docs" badge to the app's Swagger UI when it declares an `api`
+        // binding (resolved by the api module, so the path never drifts from where docs mount).
+        apiDocsPath: apiDocsPath(ctx.manifest),
     };
     const sourceName = opts.sourceName ?? "app";
     const bindings = ctx.manifest.instanceTracking ?? [];
@@ -361,7 +365,13 @@ export function mountPages(ctx, app) {
 function escapeAttr(s) {
     return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
-function rendererShell(homePage) {
+function rendererShell(homePage, apiDocsPath) {
+    // A persistent "API docs" badge (spec-first apps get their Swagger UI linked from their own
+    // UI for free). `target="_blank"` + hardened `rel` so the docs open without giving the docs
+    // tab a handle back to this window (reverse-tabnabbing).
+    const apiDocsBadge = apiDocsPath
+        ? `\n  <a class="pc-apidocs" href="${escapeAttr(apiDocsPath)}" target="_blank" rel="noopener noreferrer">API docs \u2197</a>`
+        : "";
     return `<!doctype html>
 <html lang="en">
 <head>
@@ -370,7 +380,7 @@ function rendererShell(homePage) {
   <title>Urban App</title>
   <style>${RENDERER_CSS}</style>
 </head>
-<body>
+<body>${apiDocsBadge}
   <main id="page" data-home="${escapeAttr(homePage)}"><p class="pc-empty">Loading…</p></main>
   <script type="module" src="./app/runtime.js"></script>
 </body>
@@ -417,6 +427,8 @@ const RENDERER_CSS = `
 * { box-sizing: border-box; }
 body { margin:0; font:15px/1.5 system-ui,sans-serif; padding:2rem; max-width:64rem; margin-inline:auto; background:var(--nano-app); color:var(--nano-text); }
 .pc-empty { color:var(--nano-text-faint); }
+.pc-apidocs { position:fixed; top:.75rem; right:.75rem; z-index:10; font-size:.8rem; text-decoration:none; padding:.3rem .6rem; border:1px solid var(--nano-edge); border-radius:999px; background:var(--nano-panel); color:var(--nano-text-muted); }
+.pc-apidocs:hover { color:var(--nano-text); border-color:var(--nano-accent); }
 .pc-heading { font-size:1.6rem; font-weight:650; margin:0 0 .25rem; }
 .pc-sub { color:var(--nano-text-muted); margin:.25rem 0 1rem; }
 .pc-body { margin:.5rem 0; }
@@ -663,10 +675,28 @@ function renderActionForm(node) {
     }
     btn.disabled = true; msg.className = "pc-msg"; msg.textContent = "Submitting…";
     try {
-      const res = await getJSON("/app/actions/start/" + encodeURIComponent(p.action.process),
-        { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ variables }) });
-      msg.className = "pc-msg ok";
-      msg.textContent = "Started (instance " + (res.processInstanceKey ?? "?") + ")";
+      // Two action kinds: startProcess (default, back-compat) -> engine.createInstance; and
+      // publishMessage -> engine.publishMessage, which correlates a message to a message start
+      // (or intermediate catch) event. correlationKeyField names the form field that carries
+      // the correlation key; the whole form becomes the message variables.
+      if (p.action && p.action.kind === "publishMessage") {
+        const correlationKey = String(variables[p.action.correlationKeyField] ?? "").trim();
+        if (!correlationKey) {
+          msg.className = "pc-msg err";
+          msg.textContent = "Field '" + p.action.correlationKeyField + "' is required";
+          return;
+        }
+        await getJSON("/app/actions/message", { method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ name: p.action.message, correlationKey, variables }) });
+        msg.className = "pc-msg ok";
+        msg.textContent = "Message published";
+      } else {
+        const res = await getJSON("/app/actions/start/" + encodeURIComponent(p.action.process),
+          { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ variables }) });
+        msg.className = "pc-msg ok";
+        msg.textContent = "Started (instance " + (res.processInstanceKey ?? "?") + ")";
+      }
       for (const input of inputs.values()) input.value = "";
       document.dispatchEvent(new CustomEvent("pc:refresh"));
     } catch (e) {

package/dist/runtime/core/router.d.ts

@@ -12,10 +12,13 @@ export declare function json(body: unknown, status?: number): HttpResponse;
 export declare function html(body: string, status?: number): HttpResponse;
 export declare function text(body: string, status?: number): HttpResponse;
 /**
- * Normalize a manifest-supplied route path: ensure a leading "/", drop trailing
- * slashes. Incoming request paths always start with "/", so a manifest path
- * lacking one (e.g. "hooks/x") would otherwise never match. Falls back to
- * `fallback` when the value is missing or collapses to empty ("/").
+ * Normalize a manifest-supplied route path: collapse leading slashes to exactly
+ * one, drop trailing slashes. Incoming request paths always start with "/", so a
+ * manifest path lacking one (e.g. "hooks/x") would otherwise never match. Collapsing
+ * multiple leading slashes also hardens derived URLs (e.g. the Swagger `servers`
+ * entry or the pages "API docs" badge): a `//host` value stays an in-app absolute
+ * path instead of becoming a protocol-relative URL that navigates off-origin. Falls
+ * back to `fallback` when the value is missing or collapses to empty ("/").
  */
 export declare function normalizeRoutePath(value: string | undefined, fallback: string): string;
 /** Build a single HttpHandler that dispatches across the given routes. */

package/dist/runtime/core/router.js

@@ -11,14 +11,17 @@ export function text(body, status = 200) {
     return { status, headers: { "content-type": "text/plain; charset=utf-8" }, body };
 }
 /**
- * Normalize a manifest-supplied route path: ensure a leading "/", drop trailing
- * slashes. Incoming request paths always start with "/", so a manifest path
- * lacking one (e.g. "hooks/x") would otherwise never match. Falls back to
- * `fallback` when the value is missing or collapses to empty ("/").
+ * Normalize a manifest-supplied route path: collapse leading slashes to exactly
+ * one, drop trailing slashes. Incoming request paths always start with "/", so a
+ * manifest path lacking one (e.g. "hooks/x") would otherwise never match. Collapsing
+ * multiple leading slashes also hardens derived URLs (e.g. the Swagger `servers`
+ * entry or the pages "API docs" badge): a `//host` value stays an in-app absolute
+ * path instead of becoming a protocol-relative URL that navigates off-origin. Falls
+ * back to `fallback` when the value is missing or collapses to empty ("/").
  */
 export function normalizeRoutePath(value, fallback) {
     const raw = (value ?? fallback).trim();
-    const withLead = raw.startsWith("/") ? raw : `/${raw}`;
+    const withLead = `/${raw.replace(/^\/+/, "")}`;
     const noTrail = withLead.replace(/\/+$/, "");
     return noTrail || fallback;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.31.1",
+  "version": "0.32.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",
@@ -66,7 +66,7 @@
     "@nanobpm/nano-sdk": "^1.2.3",
     "@nanobpm/workflow": "^0.8.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2",
-    "create-urban-app": "^0.7.0"
+    "create-urban-app": "^0.8.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",

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

@@ -5,7 +5,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, type OperationHandler } from "./api.ts";
+import { mountApi, resolveOperationHandler, apiDocsPath, type ApiHandle, type OperationHandler } from "./api.ts";
 
 function req(method: string, path: string, opts: { query?: string; body?: string } = {}): HttpRequest {
   return {
@@ -72,9 +72,10 @@ const spec = JSON.stringify({
 });
 
 interface Built {
-  router: (r: HttpRequest) => Promise<{ status?: number; body?: string }>;
+  router: (r: HttpRequest) => Promise<{ status?: number; body?: string; headers?: Record<string, string> }>;
   imported: string[];
   logs: Array<{ level: string; msg: string }>;
+  handle: ApiHandle;
 }
 
 function build(
@@ -108,7 +109,12 @@ function build(
   const ctx: RuntimeContext = { root: "/app", manifest, engine, host };
   const handle = mountApi(ctx, appFixture());
   const router = makeRouter(handle.routes);
-  return { router: (r) => Promise.resolve(router(r)), imported, logs };
+  return { router: (r) => Promise.resolve(router(r)), imported, logs, handle };
+}
+
+/** Mount `mountApi` and return the handle directly (for asserting `describe()`). */
+function buildHandle(api: Record<string, unknown>): { handle: ApiHandle } {
+  return { handle: build(api, {}).handle };
 }
 
 test("resolveOperationHandler prefers default (function) then handler", () => {
@@ -443,3 +449,71 @@ test("an unsafe operationId never mounts (skipped) — a crafted spec can't impo
   assert.equal(res.status, 404); // no route mounted for the skipped op
   assert.equal(imported.some((p) => p.includes("evil")), false);
 });
+
+test("serves the OpenAPI spec at {base}-docs/openapi.json, rebased to the mounted namespace", async () => {
+  const { router } = build({ spec: "openapi.json" }, {});
+  const res = await router(req("GET", "/app/api-docs/openapi.json"));
+  assert.equal(res.status, 200);
+  assert.match(res.headers?.["content-type"] ?? "", /application\/json/);
+  const doc = JSON.parse(res.body ?? "{}");
+  // The doc is served intact...
+  assert.ok(doc.paths["/invoices"], "keeps the operation paths");
+  // ...but `servers` is rebased to `base` so Swagger UI "Try it out" hits the real routes
+  // (operations mount under /app/api, not the spec's bare /invoices).
+  assert.deepEqual(doc.servers, [{ url: "/app/api" }]);
+});
+
+test("serves the Swagger UI page at {base}-docs by default", async () => {
+  const { router } = build({ spec: "openapi.json" }, {});
+  const res = await router(req("GET", "/app/api-docs"));
+  assert.equal(res.status, 200);
+  assert.match(res.headers?.["content-type"] ?? "", /text\/html/);
+  const body = res.body ?? "";
+  assert.match(body, /swagger-ui/);
+  // The UI reads the spec route we serve.
+  assert.match(body, /\/app\/api-docs\/openapi\.json/);
+});
+
+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)
+  // would 404 without an explicit alias. It must permanent-redirect to the slash-less canonical.
+  const res = await router(req("GET", "/app/api-docs/"));
+  assert.equal(res.status, 308);
+  assert.equal(res.headers?.["location"], "/app/api-docs");
+});
+
+test("docs default on is reflected in describe()", () => {
+  const { handle } = buildHandle({ spec: "openapi.json" });
+  const d = handle.describe();
+  assert.deepEqual(d.api, {
+    spec: "openapi.json",
+    base: "/app/api",
+    dir: "operations",
+    eject: false,
+    docs: { ui: "/app/api-docs", spec: "/app/api-docs/openapi.json" },
+  });
+});
+
+test("docs:false disables both the UI and the spec route (no reserved paths)", async () => {
+  const { router } = build({ spec: "openapi.json", docs: false }, {});
+  // With docs off, the docs paths fall through to the operation dispatcher → no such operation.
+  assert.equal((await router(req("GET", "/app/api-docs"))).status, 404);
+  assert.equal((await router(req("GET", "/app/api-docs/openapi.json"))).status, 404);
+});
+
+test("a string docs overrides the UI route (and the spec route beneath it)", async () => {
+  const { router } = build({ spec: "openapi.json", docs: "/help" }, {});
+  assert.equal((await router(req("GET", "/help"))).status, 200);
+  assert.equal((await router(req("GET", "/help/openapi.json"))).status, 200);
+  // The default docs path is no longer served.
+  assert.equal((await router(req("GET", "/app/api-docs"))).status, 404);
+});
+
+test("apiDocsPath resolves the UI route (and honours disable / override)", () => {
+  assert.equal(apiDocsPath({ api: { spec: "openapi.json" } }), "/app/api-docs");
+  assert.equal(apiDocsPath({ api: { spec: "openapi.json", base: "/x" } }), "/x-docs");
+  assert.equal(apiDocsPath({ api: { spec: "openapi.json", docs: "/help" } }), "/help");
+  assert.equal(apiDocsPath({ api: { spec: "openapi.json", docs: false } }), undefined);
+  assert.equal(apiDocsPath({}), undefined);
+});

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

@@ -15,7 +15,7 @@
 import type { AppApi, RuntimeContext } from "../context.ts";
 import { errorMessage } from "../guards.ts";
 import type { HttpRequest, HttpResponse } from "../host.ts";
-import { json, normalizeRoutePath, type Route } from "../router.ts";
+import { html, json, normalizeRoutePath, type Route } from "../router.ts";
 import { resolveAppPath } from "./datasource.ts";
 import {
   collectOperations,
@@ -41,6 +41,48 @@ export interface ApiBinding {
   base?: string;
   validateResponses?: "dev" | "always" | "never";
   eject?: boolean;
+  /** Human API docs (Swagger UI). `true`/omitted → on at `${base}-docs` (ADR 0058); `false` →
+   *  off; a string → a custom absolute route to mount the UI under. Spec-first apps get docs
+   *  for free — the UI reads the SAME OpenAPI document the runtime routes + validates from. */
+  docs?: boolean | string;
+}
+
+/** Pinned Swagger UI dist served from a CDN, so the docs UI adds zero bundle/runtime deps to an
+ *  Urban app (matching the deps-free spirit of the rest of the surface — validators are standalone,
+ *  ADR 0058 Consequences). Pinned (not `latest`) for reproducibility. */
+const SWAGGER_UI_VERSION = "5.17.14";
+
+/** Escape HTML-significant characters before embedding a value (the app name) in the docs markup. */
+function escapeHtml(s: string): string {
+  return s.replace(
+    /[&<>"']/g,
+    (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c] ?? c,
+  );
+}
+
+/** 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 {
+  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>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<link rel="stylesheet" href="${css}">
+<style>body{margin:0}</style>
+</head>
+<body>
+<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 });
+</script>
+</body>
+</html>`;
 }
 
 /** The `{ params, query, body }` contract a typed operation is generic over. */
@@ -113,6 +155,7 @@ function readApiBinding(manifest: unknown): ApiBinding | undefined {
   const base = Reflect.get(raw, "base");
   const validateResponses = Reflect.get(raw, "validateResponses");
   const eject = Reflect.get(raw, "eject");
+  const docs = Reflect.get(raw, "docs");
   // Trim benign manifest whitespace so it can't produce hard-to-diagnose path/import failures.
   return {
     spec: spec.trim(),
@@ -123,9 +166,41 @@ function readApiBinding(manifest: unknown): ApiBinding | undefined {
         ? validateResponses
         : undefined,
     eject: eject === true,
+    // Docs default ON (spec-first apps get Swagger for free); `false` disables; a non-empty
+    // string overrides the route. Anything else (including whitespace) falls back to the default.
+    docs: docs === false ? false : typeof docs === "string" && docs.trim().length > 0 ? docs.trim() : true,
   };
 }
 
+/** Resolve the api `base` + docs routing from a binding, in ONE place, so `mountApi` (which
+ *  serves the docs) and `apiDocsPath` (which the pages surface links to) can never drift. */
+function resolveApiRoutes(binding: ApiBinding): {
+  base: string;
+  docsEnabled: boolean;
+  docsBase: string;
+} {
+  const base = normalizeRoutePath(binding.base, "/app/api");
+  const docsEnabled = binding.docs !== false;
+  // Swagger UI at a SIBLING of the base (`${base}-docs`, e.g. /app/api-docs), never a subpath
+  // of it — so the docs routes can't collide with, or be shadowed by, the operation dispatcher
+  // that owns the `${base}/` prefix (a string `docs` overrides the whole route).
+  const docsBase = normalizeRoutePath(
+    typeof binding.docs === "string" ? binding.docs : `${base}-docs`,
+    `${base}-docs`,
+  );
+  return { base, docsEnabled, docsBase };
+}
+
+/** The Swagger UI route for an app's `api` binding, or `undefined` when there is no api surface
+ *  or docs are disabled. Lets other surfaces (e.g. the pages shell's "API docs" badge) link to
+ *  the docs without re-deriving the path. */
+export function apiDocsPath(manifest: unknown): string | undefined {
+  const binding = readApiBinding(manifest);
+  if (!binding) return undefined;
+  const { docsEnabled, docsBase } = resolveApiRoutes(binding);
+  return docsEnabled ? docsBase : undefined;
+}
+
 /** Coerce a wire string to the type its parameter schema declares, so numeric/boolean bounds
  *  validate. A value that will not coerce is left as-is and fails the type check with a clear
  *  message. The delegate still receives the original string(s). */
@@ -167,9 +242,16 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
   // Normalize the manifest base the same way actions[] routes do (shared normalizeRoutePath):
   // ensure a leading "/", strip trailing slashes, and fall back when empty — otherwise a base
   // like "app/api" would never match request paths, which always start with "/".
-  const base = normalizeRoutePath(binding.base, "/app/api");
+  //
+  // The api `base` and the docs routing are derived TOGETHER by the shared helper (ADR 0058) so
+  // this module (which serves the docs) and `apiDocsPath` (which links to them from the pages
+  // shell) stay in lockstep with a single normalization of `binding.base` — no second, drifting
+  // copy of that logic here. The spec JSON is served under the docs path so the operations
+  // namespace stays purely operations.
+  const { base, docsEnabled, docsBase } = resolveApiRoutes(binding);
   const dir = binding.dir ?? "operations";
   const surfaceEject = binding.eject === true;
+  const specRoutePath = `${docsBase}/openapi.json`;
 
   // 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
@@ -445,9 +527,57 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
     handler: dispatch,
   };
 
+  // Docs routes (ADR 0058): the Swagger UI page + the OpenAPI JSON it reads. Both are exact GET
+  // routes on the `${base}-docs` sibling namespace, so they are wholly independent of the
+  // operation dispatcher above.
+  const serveSpec = async (): Promise<HttpResponse> => {
+    let d: OpenApiDoc;
+    try {
+      d = await loadDoc();
+    } catch (e) {
+      return json({ error: errorMessage(e) }, 500);
+    }
+    // Point Swagger UI "Try it out" at the mounted namespace: operations live under `base`
+    // (e.g. /app/api/invoices), not the spec's bare paths (/invoices). Overriding `servers`
+    // makes the interactive console call the real Urban routes rather than the origin root.
+    return json({ ...d, servers: [{ url: base }] });
+  };
+  const docsTitle = `${ctx.manifest.name ?? "App"} — API docs`;
+  const serveDocs = (): HttpResponse => html(swaggerUiPage(docsTitle, specRoutePath));
+  // 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
+  // (slash-less) `docsBase` that `apiDocsPath` and every internal link already use.
+  const redirectDocsSlash = (): HttpResponse => ({ status: 308, headers: { location: docsBase } });
+  const docsRoutes: Route[] = docsEnabled
+    ? [
+        { method: "GET", path: docsBase, source: `api-docs:${binding.spec}`, handler: serveDocs },
+        {
+          method: "GET",
+          path: `${docsBase}/`,
+          source: `api-docs:${binding.spec}`,
+          handler: redirectDocsSlash,
+        },
+        {
+          method: "GET",
+          path: specRoutePath,
+          source: `api-docs:${binding.spec}`,
+          handler: serveSpec,
+        },
+      ]
+    : [];
+
   return {
     name: "api",
-    routes: [rootRoute, route],
-    describe: () => ({ api: { spec: binding.spec, base, dir, eject: surfaceEject } }),
+    routes: [...docsRoutes, rootRoute, route],
+    describe: () => ({
+      api: {
+        spec: binding.spec,
+        base,
+        dir,
+        eject: surfaceEject,
+        docs: docsEnabled ? { ui: docsBase, spec: specRoutePath } : false,
+      },
+    }),
   };
 }

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

@@ -122,6 +122,34 @@ test("GET /app/runtime.js serves the renderer module", async () => {
   assert.match(res.body ?? "", /function apiUrl\(u\)/);
 });
 
+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" },
+    { db: fakeDb(), engine: fakeEngine().engine, readPage: async () => "{}" },
+  );
+  const withBadge = (await makeRouter(routes)(req("GET", "/"))).body ?? "";
+  assert.match(withBadge, /class="pc-apidocs"/);
+  assert.match(withBadge, /href="\/app\/api-docs"/);
+  // Opens in a new tab with a hardened rel (no reverse-tabnabbing handle).
+  assert.match(withBadge, /rel="noopener noreferrer"/);
+
+  // No `api` binding → no badge element (the CSS rule is always present in the shell styles).
+  const noBadge = (await dispatch("GET", "/")).body ?? "";
+  assert.doesNotMatch(noBadge, /class="pc-apidocs"/);
+});
+
+test("renderActionForm supports a publishMessage action (message-started processes)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // The form submit branches on the action kind: publishMessage posts to the message endpoint,
+  // deriving the correlation key from the named form field; startProcess keeps its old path.
+  assert.match(js, /p\.action\.kind === "publishMessage"/);
+  assert.match(js, /variables\[p\.action\.correlationKeyField\]/);
+  assert.match(js, /"\/app\/actions\/message"/);
+  // startProcess remains the default/back-compat branch.
+  assert.match(js, /"\/app\/actions\/start\/" \+ encodeURIComponent\(p\.action\.process\)/);
+});
+
 test("the renderer bridges the console theme over postMessage", async () => {
   const res = await dispatch("GET", "/app/runtime.js");
   const js = res.body ?? "";

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

@@ -20,6 +20,7 @@ import { errorMessage, isRecord } from "../guards.ts";
 import type { EngineClient } from "../host.ts";
 import { html, json, type Route } from "../router.ts";
 import { cancelInstanceReconciling, type CancelInstanceResult } from "./cancel.ts";
+import { apiDocsPath } from "./api.ts";
 import { quoteIdent } from "./gateway.ts";
 
 /** The subset of the datasource gateway the page runtime needs. */
@@ -37,6 +38,12 @@ export interface PagesOptions {
   rowLimit?: number;
   /** The injected default datasource name (the alias apps bind to). Default `app`. */
   sourceName?: string;
+  /**
+   * The app's Swagger UI route (from the `api` binding, resolved by `apiDocsPath`). When set,
+   * the shell renders a persistent "API docs" badge linking to it — so a spec-first app surfaces
+   * its interactive docs from its own UI for free. Omitted → no badge (app declares no `api`).
+   */
+  apiDocsPath?: string;
 }
 
 export interface PagesDeps {
@@ -115,7 +122,7 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
   };
 
   const routes: Route[] = [];
-  const shell = html(rendererShell(homePage));
+  const shell = html(rendererShell(homePage, opts.apiDocsPath));
 
   // ── the renderer shell + module ─────────────────────────────────────────
   routes.push({ method: "GET", path: "/", source: "surface:pages", handler: () => shell });
@@ -372,6 +379,9 @@ export function mountPages(ctx: RuntimeContext, app: AppApi): PagesHandle {
     homePage: typeof decl.homePage === "string" ? decl.homePage : undefined,
     rowLimit: typeof decl.rowLimit === "number" ? decl.rowLimit : undefined,
     sourceName: typeof decl.sourceName === "string" ? decl.sourceName : undefined,
+    // Link the shell's "API docs" badge to the app's Swagger UI when it declares an `api`
+    // binding (resolved by the api module, so the path never drifts from where docs mount).
+    apiDocsPath: apiDocsPath(ctx.manifest),
   };
   const sourceName = opts.sourceName ?? "app";
   const bindings = ctx.manifest.instanceTracking ?? [];
@@ -400,7 +410,13 @@ function escapeAttr(s: string): string {
   return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
-function rendererShell(homePage: string): string {
+function rendererShell(homePage: string, apiDocsPath?: string): string {
+  // A persistent "API docs" badge (spec-first apps get their Swagger UI linked from their own
+  // UI for free). `target="_blank"` + hardened `rel` so the docs open without giving the docs
+  // tab a handle back to this window (reverse-tabnabbing).
+  const apiDocsBadge = apiDocsPath
+    ? `\n  <a class="pc-apidocs" href="${escapeAttr(apiDocsPath)}" target="_blank" rel="noopener noreferrer">API docs \u2197</a>`
+    : "";
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -409,7 +425,7 @@ function rendererShell(homePage: string): string {
   <title>Urban App</title>
   <style>${RENDERER_CSS}</style>
 </head>
-<body>
+<body>${apiDocsBadge}
   <main id="page" data-home="${escapeAttr(homePage)}"><p class="pc-empty">Loading…</p></main>
   <script type="module" src="./app/runtime.js"></script>
 </body>
@@ -457,6 +473,8 @@ const RENDERER_CSS = `
 * { box-sizing: border-box; }
 body { margin:0; font:15px/1.5 system-ui,sans-serif; padding:2rem; max-width:64rem; margin-inline:auto; background:var(--nano-app); color:var(--nano-text); }
 .pc-empty { color:var(--nano-text-faint); }
+.pc-apidocs { position:fixed; top:.75rem; right:.75rem; z-index:10; font-size:.8rem; text-decoration:none; padding:.3rem .6rem; border:1px solid var(--nano-edge); border-radius:999px; background:var(--nano-panel); color:var(--nano-text-muted); }
+.pc-apidocs:hover { color:var(--nano-text); border-color:var(--nano-accent); }
 .pc-heading { font-size:1.6rem; font-weight:650; margin:0 0 .25rem; }
 .pc-sub { color:var(--nano-text-muted); margin:.25rem 0 1rem; }
 .pc-body { margin:.5rem 0; }
@@ -704,10 +722,28 @@ function renderActionForm(node) {
     }
     btn.disabled = true; msg.className = "pc-msg"; msg.textContent = "Submitting…";
     try {
-      const res = await getJSON("/app/actions/start/" + encodeURIComponent(p.action.process),
-        { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ variables }) });
-      msg.className = "pc-msg ok";
-      msg.textContent = "Started (instance " + (res.processInstanceKey ?? "?") + ")";
+      // Two action kinds: startProcess (default, back-compat) -> engine.createInstance; and
+      // publishMessage -> engine.publishMessage, which correlates a message to a message start
+      // (or intermediate catch) event. correlationKeyField names the form field that carries
+      // the correlation key; the whole form becomes the message variables.
+      if (p.action && p.action.kind === "publishMessage") {
+        const correlationKey = String(variables[p.action.correlationKeyField] ?? "").trim();
+        if (!correlationKey) {
+          msg.className = "pc-msg err";
+          msg.textContent = "Field '" + p.action.correlationKeyField + "' is required";
+          return;
+        }
+        await getJSON("/app/actions/message", { method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ name: p.action.message, correlationKey, variables }) });
+        msg.className = "pc-msg ok";
+        msg.textContent = "Message published";
+      } else {
+        const res = await getJSON("/app/actions/start/" + encodeURIComponent(p.action.process),
+          { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ variables }) });
+        msg.className = "pc-msg ok";
+        msg.textContent = "Started (instance " + (res.processInstanceKey ?? "?") + ")";
+      }
       for (const input of inputs.values()) input.value = "";
       document.dispatchEvent(new CustomEvent("pc:refresh"));
     } catch (e) {

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

@@ -9,6 +9,12 @@ test("normalizeRoutePath ensures a leading slash and trims trailing slashes", ()
   assert.equal(normalizeRoutePath("  /chat  ", "/chat"), "/chat");
 });
 
+test("normalizeRoutePath collapses leading slashes so a //host value stays in-app", () => {
+  assert.equal(normalizeRoutePath("//evil.com", "/app/api"), "/evil.com");
+  assert.equal(normalizeRoutePath("///app/api", "/app/api"), "/app/api");
+  assert.equal(normalizeRoutePath("  //app/api-docs  ", "/app/api"), "/app/api-docs");
+});
+
 test("normalizeRoutePath falls back when value is missing or collapses to root", () => {
   assert.equal(normalizeRoutePath(undefined, "/tasks"), "/tasks");
   assert.equal(normalizeRoutePath("/", "/tasks"), "/tasks");

package/src/runtime/core/router.ts

@@ -27,14 +27,17 @@ export function text(body: string, status = 200): HttpResponse {
 }
 
 /**
- * Normalize a manifest-supplied route path: ensure a leading "/", drop trailing
- * slashes. Incoming request paths always start with "/", so a manifest path
- * lacking one (e.g. "hooks/x") would otherwise never match. Falls back to
- * `fallback` when the value is missing or collapses to empty ("/").
+ * Normalize a manifest-supplied route path: collapse leading slashes to exactly
+ * one, drop trailing slashes. Incoming request paths always start with "/", so a
+ * manifest path lacking one (e.g. "hooks/x") would otherwise never match. Collapsing
+ * multiple leading slashes also hardens derived URLs (e.g. the Swagger `servers`
+ * entry or the pages "API docs" badge): a `//host` value stays an in-app absolute
+ * path instead of becoming a protocol-relative URL that navigates off-origin. Falls
+ * back to `fallback` when the value is missing or collapses to empty ("/").
  */
 export function normalizeRoutePath(value: string | undefined, fallback: string): string {
   const raw = (value ?? fallback).trim();
-  const withLead = raw.startsWith("/") ? raw : `/${raw}`;
+  const withLead = `/${raw.replace(/^\/+/, "")}`;
   const noTrail = withLead.replace(/\/+$/, "");
   return noTrail || fallback;
 }