@nanobpm/urban 0.32.1 → 0.33.0

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

@@ -6,10 +6,9 @@ import { type Route } from "../router.ts";
 export interface ApiBinding {
     spec: string;
     dir?: string;
-    base?: string;
     validateResponses?: "dev" | "always" | "never";
     eject?: boolean;
-    /** Human API docs (Swagger UI). `true`/omitted → on at `${base}-docs` (ADR 0058); `false` →
+    /** Human API docs (Swagger UI). `true`/omitted → on at `/app/api-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;

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

@@ -2,7 +2,7 @@
 // instead of hand-rolled imperative handlers, an author declares `api: { spec }` in the manifest and
 // writes one delegate module per `operationId`. This runtime reads the SAME OpenAPI document the
 // toolkit deriver turns into types (via the shared `openapi/spec.ts`), mounts one dispatcher over the
-// `api.base` namespace, and for each request: parses → validates params/query/body against the spec →
+// fixed `/app/api` namespace, and for each request: parses → validates params/query/body against the spec →
 // 400 with a structured error → resolves + calls the operationId delegate (validated, typed input +
 // the injected AppApi, exactly like a worker/action handler) → serializes the result.
 //
@@ -15,6 +15,10 @@ import { errorMessage } from "../guards.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";
+/** The canonical, non-configurable mount prefix for an app's OpenAPI operations. Operations always
+ *  live under `/app/api` so page actions, links, and any `callRoute` can name an operation path as a
+ *  stable framework constant (`/app/api/<op path>`) — there is no per-app `base` knob to drift. */
+const API_BASE = "/app/api";
 /** 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. */
@@ -76,7 +80,6 @@ function readApiBinding(manifest) {
     if (typeof spec !== "string" || spec.trim().length === 0)
         return undefined;
     const dir = Reflect.get(raw, "dir");
-    const base = Reflect.get(raw, "base");
     const validateResponses = Reflect.get(raw, "validateResponses");
     const eject = Reflect.get(raw, "eject");
     const docs = Reflect.get(raw, "docs");
@@ -84,7 +87,6 @@ function readApiBinding(manifest) {
     return {
         spec: spec.trim(),
         dir: typeof dir === "string" && dir.trim().length > 0 ? dir.trim() : undefined,
-        base: typeof base === "string" && base.trim().length > 0 ? base.trim() : undefined,
         validateResponses: validateResponses === "dev" || validateResponses === "always" || validateResponses === "never"
             ? validateResponses
             : undefined,
@@ -94,14 +96,15 @@ function readApiBinding(manifest) {
         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. */
+/** Resolve the api `base` + docs routing, in ONE place, so `mountApi` (which serves the docs) and
+ *  `apiDocsPath` (which the pages surface links to) can never drift. The operation base is the fixed
+ *  `/app/api` constant; only the docs route remains manifest-configurable. */
 function resolveApiRoutes(binding) {
-    const base = normalizeRoutePath(binding.base, "/app/api");
+    const base = API_BASE;
     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).
+    // Swagger UI at a SIBLING of the base (`/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 };
 }
@@ -143,19 +146,34 @@ export function mountApi(ctx, app) {
     const binding = readApiBinding(ctx.manifest);
     if (!binding)
         return { name: "api", routes: [], describe: () => ({ api: "disabled" }) };
-    // 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 "/".
-    //
-    // 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.
+    // The api `base` is the fixed `/app/api` constant; only the docs routing is derived here. Both
+    // come from 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 — 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`;
+    // 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).
+    const lastSegment = (p) => p.split("/").filter(Boolean).pop() ?? "";
+    const parentPath = (p) => {
+        const parts = p.split("/").filter(Boolean);
+        parts.pop();
+        return `/${parts.join("/")}`;
+    };
+    // `${docsBase}/openapi.json` reached relatively from the docs page = `<docs-segment>/openapi.json`.
+    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).
+    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
     // than failing app boot.
@@ -427,12 +445,13 @@ export function mountApi(ctx, app) {
             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 }] });
+        // (e.g. /app/api/invoices), not the spec's bare paths (/invoices). Overriding `servers` with a
+        // document-relative URL (issue #151) makes the interactive console call the real Urban routes
+        // both at the origin root and under the Nano console reverse proxy.
+        return json({ ...d, servers: [{ url: serversUrl }] });
     };
     const docsTitle = `${ctx.manifest.name ?? "App"} — API docs`;
-    const serveDocs = () => html(swaggerUiPage(docsTitle, specRoutePath));
+    const serveDocs = () => html(swaggerUiPage(docsTitle, specDocUrl));
     // 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

@@ -14,6 +14,13 @@
 //   POST /app/actions/start/<process>               → engine.createInstance
 //   POST /app/actions/cancel                        → engine.cancelInstance
 //   POST /app/actions/message                       → engine.publishMessage
+//
+// Page actions are ROUTE-DRIVEN: an `actionForm`/rowAction/detail-form `action` is just
+// `{ path, method?, body?, successLabel? }`. The client POSTs the resolved body (default
+// `{ variables: <form> }`) to `path`, templating `{{form.KEY}}` / `{{row.KEY}}` (and the
+// whole-object `{{form}}` / `{{row}}`) tokens. There are NO bespoke action kinds — a form
+// reaches start/cancel/message above, an OpenAPI operation under /app/api, or any app route
+// uniformly by naming its path.
 import { errorMessage, isRecord } from "../guards.js";
 import { html, json } from "../router.js";
 import { cancelInstanceReconciling } from "./cancel.js";
@@ -369,8 +376,19 @@ 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).
+    //
+    // The href must be DOCUMENT-relative, exactly like the `./app/runtime.js` script tag below:
+    // the shell is served at the app's mount root (always a trailing "/"), which is the origin
+    // root for a direct run (CLI on :3000) but a path prefix under the Nano console's reverse
+    // proxy (/console/app-view/<name>/). A root-absolute "/app/api-docs" would escape that prefix
+    // and open the CONSOLE origin (e.g. :8080/app/api-docs) instead of the app's docs. Strip the
+    // single leading slash so it rebases onto the mount root; leave a protocol-relative "//host"
+    // (which apiDocsPath never emits) untouched.
+    const badgeHref = apiDocsPath && apiDocsPath.startsWith("/") && !apiDocsPath.startsWith("//")
+        ? `./${apiDocsPath.slice(1)}`
+        : apiDocsPath;
     const apiDocsBadge = apiDocsPath
-        ? `\n  <a class="pc-apidocs" href="${escapeAttr(apiDocsPath)}" target="_blank" rel="noopener noreferrer">API docs \u2197</a>`
+        ? `\n  <a class="pc-apidocs" href="${escapeAttr(badgeHref)}" target="_blank" rel="noopener noreferrer">API docs \u2197</a>`
         : "";
     return `<!doctype html>
 <html lang="en">
@@ -575,6 +593,59 @@ async function getJSON(url, opts) {
   return body;
 }
 
+// ── route-driven actions ────────────────────────────────────────────────
+// Every page action is a single primitive: POST (or any method) the resolved
+// body to an app route path. There are NO bespoke action kinds — a form/row
+// reaches process start, message publish, cancel, an OpenAPI operation, a
+// webhook, or any app route uniformly by naming its path. Path + body may
+// interpolate the current form fields and (for grid rows/detail forms) the row
+// via {{form.KEY}} / {{row.KEY}} tokens; the whole-string tokens {{form}} and
+// {{row}} splice the object itself (type-preserving), so a body of
+// "variables": "{{form}}" sends the form object as the variable map.
+function lookupToken(path, ctx) {
+  const segs = String(path).split(".");
+  const head = segs[0];
+  let base = head === "form" ? (ctx.form || {}) : head === "row" ? (ctx.row || {}) : undefined;
+  for (let i = 1; i < segs.length; i++) base = base == null ? undefined : base[segs[i]];
+  return base;
+}
+function resolveTemplate(node, ctx) {
+  if (typeof node === "string") {
+    const whole = node.match(/^\{\{\s*([\w.]+)\s*\}\}$/);
+    if (whole) return lookupToken(whole[1], ctx);
+    return node.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, k) => {
+      const v = lookupToken(k, ctx);
+      return v == null ? "" : String(v);
+    });
+  }
+  if (Array.isArray(node)) return node.map((n) => resolveTemplate(n, ctx));
+  if (node && typeof node === "object") {
+    // Null-proto target so a template key like "__proto__" can't trigger prototype
+    // mutation (prototype-pollution class) when copied into the resolved object.
+    const out = Object.create(null);
+    for (const [k, v] of Object.entries(node)) out[k] = resolveTemplate(v, ctx);
+    return out;
+  }
+  return node;
+}
+async function runRoute(action, ctx) {
+  if (!action || typeof action.path !== "string" || action.path === "") {
+    throw new Error("This action has no route configured (action.path is missing or blank)");
+  }
+  const path = action.path.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, k) => {
+    const v = lookupToken(k, ctx);
+    return v == null ? "" : encodeURIComponent(String(v));
+  });
+  const method = String(action.method || "POST").toUpperCase();
+  let body;
+  if (action.body !== undefined) body = resolveTemplate(action.body, ctx);
+  else if (ctx.form) body = { variables: ctx.form };
+  else body = {};
+  const opts = { method, headers: { "content-type": "application/json" } };
+  if (method !== "GET" && method !== "HEAD") opts.body = JSON.stringify(body);
+  return getJSON(path, opts);
+}
+
 function el(tag, attrs = {}, ...kids) {
   const n = document.createElement(tag);
   for (const [k, v] of Object.entries(attrs)) {
@@ -675,37 +746,14 @@ function renderActionForm(node) {
     }
     btn.disabled = true; msg.className = "pc-msg"; msg.textContent = "Submitting…";
     try {
-      // 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;
-        }
-        // Send the trimmed key back as the variable too, so the value a worker
-        // reads matches the key the message was correlated on (no leading/trailing
-        // whitespace divergence between correlationKey and variables[field]).
-        variables[p.action.correlationKeyField] = correlationKey;
-        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 {
-        if (!p.action || !p.action.process) {
-          msg.className = "pc-msg err";
-          msg.textContent = "This form has no action configured";
-          return;
-        }
-        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 ?? "?") + ")";
-      }
+      // Route-driven: POST the form (as { variables } by default, or the action's
+      // own body template) to the action's route path. correlationKey / process /
+      // message are expressed by the path + body template the page author supplies,
+      // e.g. { path: "/app/actions/message", body: { name, correlationKey, variables: "{{form}}" } }.
+      const res = await runRoute(p.action, { form: variables });
+      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 = "";
       document.dispatchEvent(new CustomEvent("pc:refresh"));
     } catch (e) {
@@ -780,23 +828,9 @@ function renderDataGrid(node) {
   }
 
   async function fireAction(action, row) {
-    if (action.kind === "cancelProcess") {
-      return getJSON("/app/actions/cancel", { method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ processInstanceKey: row[action.keyField] }) });
-    }
-    if (action.kind === "publishMessage") {
-      return getJSON("/app/actions/message", { method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ name: action.message, correlationKey: row[action.correlationKeyField],
-          variables: { ...(action.variables || {}) } }) });
-    }
-    if (action.kind === "startProcess") {
-      return getJSON("/app/actions/start/" + encodeURIComponent(action.process), { method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ variables: { ...(action.variables || {}) } }) });
-    }
-    throw new Error("unknown action");
+    // Route-driven row action: POST the action's body template (default {})
+    // to its route path, with {{row.KEY}} tokens resolved from this row.
+    return runRoute(action, { row });
   }
 
   function rowActionButton(row, ra) {
@@ -831,11 +865,13 @@ function renderDataGrid(node) {
     btn.addEventListener("click", async () => {
       btn.disabled = true; msg.className = "pc-msg"; msg.textContent = "Sending…";
       try {
-        await getJSON("/app/actions/message", { method: "POST",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify({ name: f.action.message, correlationKey: row[f.action.correlationKeyField],
-            variables: { [f.inputKey]: input.value, ...(f.action.variables || {}) } }) });
-        msg.className = "pc-msg ok"; msg.textContent = "Sent";
+        // The textarea value is the form's single field (f.inputKey); route + body
+        // template come from f.action, e.g. { path: "/app/actions/message",
+        // body: { name, correlationKey: "{{row.pr_key}}", variables: "{{form}}" } }.
+        // Null-proto so an f.inputKey of "__proto__"/"constructor" can't mutate a prototype.
+        const form = Object.create(null); form[f.inputKey] = input.value;
+        await runRoute(f.action, { form, row });
+        msg.className = "pc-msg ok"; msg.textContent = (f.action && f.action.successLabel) || "Sent";
         document.dispatchEvent(new CustomEvent("pc:refresh"));
       } catch (e) {
         btn.disabled = false; msg.className = "pc-msg err"; msg.textContent = String(e.message || e);

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

@@ -95,7 +95,7 @@ export function mountSurfaces(ctx, app) {
         enabled.push(`actions(${actions.routes.length})`);
     }
     // The OpenAPI endpoint surface (ADR 0058) mounts AFTER actions (so an exact `actions[]` route
-    // still shadows an operation) and BEFORE the generic pages routes. It owns the `api.base`
+    // still shadows an operation) and BEFORE the generic pages routes. It owns the fixed `/app/api`
     // namespace via a regex dispatcher, so it only contributes routes when the app declares `api`.
     const api = mountApi(ctx, app);
     if (api.routes.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.32.1",
+  "version": "0.33.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.8.0"
+    "create-urban-app": "^0.9.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",

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

@@ -228,12 +228,13 @@ test("a malformed spec surfaces as a 500, not a boot failure", async () => {
   assert.match(JSON.parse(res.body!).error, /failed to load/);
 });
 
-test("a manifest api.base without a leading slash is normalized so routes still match", async () => {
+test("a leftover manifest api.base is ignored — operations always mount at the fixed /app/api", async () => {
   let got: Record<string, string> | undefined;
   const { router } = build(
-    { spec: "openapi.json", base: "app/api" }, // no leading slash
+    { spec: "openapi.json", base: "/somewhere/else" }, // base is no longer honoured
     { "/app/operations/getInvoice": { default: (i: { params: Record<string, string> }) => { got = i.params; return { body: { ok: true } }; } } },
   );
+  assert.equal((await router(req("GET", "/somewhere/else/invoices/42"))).status, 404);
   const res = await router(req("GET", "/app/api/invoices/42"));
   assert.equal(res.status, 200);
   assert.deepEqual(got, { id: "42" });
@@ -393,10 +394,10 @@ test("an op declaring no requestBody gets body:undefined at runtime (matches der
   assert.equal(seenBody, undefined);
 });
 
-test("readApiBinding trims whitespace on base/dir/spec so benign formatting can't break resolution", async () => {
+test("readApiBinding trims whitespace on dir/spec so benign formatting can't break resolution", async () => {
   let got: Record<string, string> | undefined;
   const { router, imported } = build(
-    { spec: "  openapi.json  ", base: "  app/api  ", dir: "  operations  " },
+    { spec: "  openapi.json  ", dir: "  operations  " },
     { "/app/operations/getInvoice": { default: (i: { params: Record<string, string> }) => { got = i.params; return { body: { ok: true } }; } } },
   );
   const res = await router(req("GET", "/app/api/invoices/42"));
@@ -458,9 +459,10 @@ test("serves the OpenAPI spec at {base}-docs/openapi.json, rebased to the mounte
   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
+  // ...but `servers` is rebased to `base` (document-relative, issue #151) so Swagger UI "Try it
+  // out" hits the real routes both at the origin root and under the Nano console reverse proxy
   // (operations mount under /app/api, not the spec's bare /invoices).
-  assert.deepEqual(doc.servers, [{ url: "/app/api" }]);
+  assert.deepEqual(doc.servers, [{ url: "api" }]);
 });
 
 test("serves the Swagger UI page at {base}-docs by default", async () => {
@@ -470,8 +472,10 @@ 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 route we serve.
-  assert.match(body, /\/app\/api-docs\/openapi\.json/);
+  // 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"/);
+  assert.doesNotMatch(body, /url: "\/app\/api-docs\/openapi\.json"/);
 });
 
 test("the trailing-slash docs variant 308-redirects to the canonical path", async () => {
@@ -512,7 +516,7 @@ test("a string docs overrides the UI route (and the spec route beneath it)", asy
 
 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", base: "/x" } }), "/app/api-docs"); // base ignored
   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

@@ -2,7 +2,7 @@
 // instead of hand-rolled imperative handlers, an author declares `api: { spec }` in the manifest and
 // writes one delegate module per `operationId`. This runtime reads the SAME OpenAPI document the
 // toolkit deriver turns into types (via the shared `openapi/spec.ts`), mounts one dispatcher over the
-// `api.base` namespace, and for each request: parses → validates params/query/body against the spec →
+// fixed `/app/api` namespace, and for each request: parses → validates params/query/body against the spec →
 // 400 with a structured error → resolves + calls the operationId delegate (validated, typed input +
 // the injected AppApi, exactly like a worker/action handler) → serializes the result.
 //
@@ -38,15 +38,19 @@ import {
 export interface ApiBinding {
   spec: string;
   dir?: string;
-  base?: string;
   validateResponses?: "dev" | "always" | "never";
   eject?: boolean;
-  /** Human API docs (Swagger UI). `true`/omitted → on at `${base}-docs` (ADR 0058); `false` →
+  /** Human API docs (Swagger UI). `true`/omitted → on at `/app/api-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 canonical, non-configurable mount prefix for an app's OpenAPI operations. Operations always
+ *  live under `/app/api` so page actions, links, and any `callRoute` can name an operation path as a
+ *  stable framework constant (`/app/api/<op path>`) — there is no per-app `base` knob to drift. */
+const API_BASE = "/app/api";
+
 /** 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. */
@@ -152,7 +156,6 @@ function readApiBinding(manifest: unknown): ApiBinding | undefined {
   const spec = Reflect.get(raw, "spec");
   if (typeof spec !== "string" || spec.trim().length === 0) return undefined;
   const dir = Reflect.get(raw, "dir");
-  const base = Reflect.get(raw, "base");
   const validateResponses = Reflect.get(raw, "validateResponses");
   const eject = Reflect.get(raw, "eject");
   const docs = Reflect.get(raw, "docs");
@@ -160,7 +163,6 @@ function readApiBinding(manifest: unknown): ApiBinding | undefined {
   return {
     spec: spec.trim(),
     dir: typeof dir === "string" && dir.trim().length > 0 ? dir.trim() : undefined,
-    base: typeof base === "string" && base.trim().length > 0 ? base.trim() : undefined,
     validateResponses:
       validateResponses === "dev" || validateResponses === "always" || validateResponses === "never"
         ? validateResponses
@@ -172,18 +174,19 @@ function readApiBinding(manifest: unknown): ApiBinding | undefined {
   };
 }
 
-/** 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. */
+/** Resolve the api `base` + docs routing, in ONE place, so `mountApi` (which serves the docs) and
+ *  `apiDocsPath` (which the pages surface links to) can never drift. The operation base is the fixed
+ *  `/app/api` constant; only the docs route remains manifest-configurable. */
 function resolveApiRoutes(binding: ApiBinding): {
   base: string;
   docsEnabled: boolean;
   docsBase: string;
 } {
-  const base = normalizeRoutePath(binding.base, "/app/api");
+  const base = API_BASE;
   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).
+  // Swagger UI at a SIBLING of the base (`/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`,
@@ -239,19 +242,34 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
   const binding = readApiBinding(ctx.manifest);
   if (!binding) return { name: "api", routes: [], describe: () => ({ api: "disabled" }) };
 
-  // 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 "/".
-  //
-  // 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.
+  // The api `base` is the fixed `/app/api` constant; only the docs routing is derived here. Both
+  // come from 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 — 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`;
+  // 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).
+  const lastSegment = (p: string): string => p.split("/").filter(Boolean).pop() ?? "";
+  const parentPath = (p: string): string => {
+    const parts = p.split("/").filter(Boolean);
+    parts.pop();
+    return `/${parts.join("/")}`;
+  };
+  // `${docsBase}/openapi.json` reached relatively from the docs page = `<docs-segment>/openapi.json`.
+  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).
+  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
@@ -538,12 +556,13 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
       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 }] });
+    // (e.g. /app/api/invoices), not the spec's bare paths (/invoices). Overriding `servers` with a
+    // document-relative URL (issue #151) makes the interactive console call the real Urban routes
+    // both at the origin root and under the Nano console reverse proxy.
+    return json({ ...d, servers: [{ url: serversUrl }] });
   };
   const docsTitle = `${ctx.manifest.name ?? "App"} — API docs`;
-  const serveDocs = (): HttpResponse => html(swaggerUiPage(docsTitle, specRoutePath));
+  const serveDocs = (): HttpResponse => html(swaggerUiPage(docsTitle, specDocUrl));
   // 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

@@ -98,6 +98,29 @@ test("GET / serves the renderer shell with the home marker", async () => {
   assert.doesNotMatch(res.body ?? "", /src="\/app\/runtime\.js"/);
 });
 
+test("the API docs badge links via a document-relative href (proxy-safe)", async () => {
+  // With an `api` binding, the shell renders a persistent "API docs" badge. Its
+  // href must be DOCUMENT-relative (./app/api-docs), mirroring the runtime.js
+  // script tag, so it resolves against the shell's mount root. A root-absolute
+  // "/app/api-docs" would escape the Nano console's /console/app-view/<name>/
+  // reverse proxy and open the console origin (e.g. :8080/app/api-docs) instead
+  // of the app's own docs — the port-mismatch bug this guards against.
+  const { engine } = fakeEngine();
+  const routes = createPagesRoutes(
+    { pagesDir: "pages", homePage: "home", sourceName: "app", apiDocsPath: "/app/api-docs" },
+    {
+      db: fakeDb(),
+      engine,
+      readPage: async () => JSON.stringify({ title: "Home", nodes: [] }),
+      listPages: async () => ["home"],
+    },
+  );
+  const res = await makeRouter(routes)(req("GET", "/"));
+  assert.match(res.body ?? "", /class="pc-apidocs"/);
+  assert.match(res.body ?? "", /href="\.\/app\/api-docs"/);
+  assert.doesNotMatch(res.body ?? "", /href="\/app\/api-docs"/);
+});
+
 test("the shell styles the app through the shared --nano-* token contract", async () => {
   const res = await dispatch("GET", "/");
   const html = res.body ?? "";
@@ -129,7 +152,7 @@ test("the shell renders an API-docs badge only when an apiDocsPath is provided",
   );
   const withBadge = (await makeRouter(routes)(req("GET", "/"))).body ?? "";
   assert.match(withBadge, /class="pc-apidocs"/);
-  assert.match(withBadge, /href="\/app\/api-docs"/);
+  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"/);
 
@@ -138,22 +161,23 @@ test("the shell renders an API-docs badge only when an apiDocsPath is provided",
   assert.doesNotMatch(noBadge, /class="pc-apidocs"/);
 });
 
-test("renderActionForm supports a publishMessage action (message-started processes)", async () => {
+test("page actions are route-driven: the runtime ships a single callRoute dispatcher, no bespoke kinds", 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"/);
-  // The trimmed correlation key is written back as the variable, so the value a
-  // worker reads matches the key the message was correlated on.
-  assert.match(js, /variables\[p\.action\.correlationKeyField\] = correlationKey/);
-  // startProcess remains the default/back-compat branch.
-  assert.match(js, /"\/app\/actions\/start\/" \+ encodeURIComponent\(p\.action\.process\)/);
-  // A missing action is reported clearly instead of throwing on p.action.process.
-  assert.match(js, /if \(!p\.action \|\| !p\.action\.process\)/);
-  assert.match(js, /no action configured/);
+  // A single primitive resolves { path, method?, body? } and POSTs it — there is no per-kind
+  // branching. The template resolver splices {{form}} / {{row}} and {{form.KEY}} / {{row.KEY}}.
+  assert.match(js, /async function runRoute\(action, ctx\)/);
+  assert.match(js, /function resolveTemplate\(node, ctx\)/);
+  assert.match(js, /function lookupToken\(path, ctx\)/);
+  // The form default body is the { variables } envelope, so plain forms hit start operations
+  // without any per-form config; row/detail forms carry an explicit body template instead.
+  assert.match(js, /body = \{ variables: ctx\.form \}/);
+  // Path tokens are URL-encoded (real keys like owner/repo#123 must not break the path).
+  assert.match(js, /encodeURIComponent\(String\(v\)\)/);
+  // The removed bespoke action kinds no longer appear anywhere in the client runtime.
+  assert.doesNotMatch(js, /p\.action\.kind/);
+  assert.doesNotMatch(js, /correlationKeyField/);
+  assert.doesNotMatch(js, /action\.kind === "(startProcess|publishMessage|cancelProcess)"/);
 });
 
 test("the renderer bridges the console theme over postMessage", async () => {

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

@@ -14,6 +14,13 @@
 //   POST /app/actions/start/<process>               → engine.createInstance
 //   POST /app/actions/cancel                        → engine.cancelInstance
 //   POST /app/actions/message                       → engine.publishMessage
+//
+// Page actions are ROUTE-DRIVEN: an `actionForm`/rowAction/detail-form `action` is just
+// `{ path, method?, body?, successLabel? }`. The client POSTs the resolved body (default
+// `{ variables: <form> }`) to `path`, templating `{{form.KEY}}` / `{{row.KEY}}` (and the
+// whole-object `{{form}}` / `{{row}}`) tokens. There are NO bespoke action kinds — a form
+// reaches start/cancel/message above, an OpenAPI operation under /app/api, or any app route
+// uniformly by naming its path.
 
 import type { AppApi, RuntimeContext } from "../context.ts";
 import { errorMessage, isRecord } from "../guards.ts";
@@ -414,8 +421,20 @@ 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).
+  //
+  // The href must be DOCUMENT-relative, exactly like the `./app/runtime.js` script tag below:
+  // the shell is served at the app's mount root (always a trailing "/"), which is the origin
+  // root for a direct run (CLI on :3000) but a path prefix under the Nano console's reverse
+  // proxy (/console/app-view/<name>/). A root-absolute "/app/api-docs" would escape that prefix
+  // and open the CONSOLE origin (e.g. :8080/app/api-docs) instead of the app's docs. Strip the
+  // single leading slash so it rebases onto the mount root; leave a protocol-relative "//host"
+  // (which apiDocsPath never emits) untouched.
+  const badgeHref =
+    apiDocsPath && apiDocsPath.startsWith("/") && !apiDocsPath.startsWith("//")
+      ? `./${apiDocsPath.slice(1)}`
+      : apiDocsPath;
   const apiDocsBadge = apiDocsPath
-    ? `\n  <a class="pc-apidocs" href="${escapeAttr(apiDocsPath)}" target="_blank" rel="noopener noreferrer">API docs \u2197</a>`
+    ? `\n  <a class="pc-apidocs" href="${escapeAttr(badgeHref!)}" target="_blank" rel="noopener noreferrer">API docs \u2197</a>`
     : "";
   return `<!doctype html>
 <html lang="en">
@@ -622,6 +641,59 @@ async function getJSON(url, opts) {
   return body;
 }
 
+// ── route-driven actions ────────────────────────────────────────────────
+// Every page action is a single primitive: POST (or any method) the resolved
+// body to an app route path. There are NO bespoke action kinds — a form/row
+// reaches process start, message publish, cancel, an OpenAPI operation, a
+// webhook, or any app route uniformly by naming its path. Path + body may
+// interpolate the current form fields and (for grid rows/detail forms) the row
+// via {{form.KEY}} / {{row.KEY}} tokens; the whole-string tokens {{form}} and
+// {{row}} splice the object itself (type-preserving), so a body of
+// "variables": "{{form}}" sends the form object as the variable map.
+function lookupToken(path, ctx) {
+  const segs = String(path).split(".");
+  const head = segs[0];
+  let base = head === "form" ? (ctx.form || {}) : head === "row" ? (ctx.row || {}) : undefined;
+  for (let i = 1; i < segs.length; i++) base = base == null ? undefined : base[segs[i]];
+  return base;
+}
+function resolveTemplate(node, ctx) {
+  if (typeof node === "string") {
+    const whole = node.match(/^\{\{\s*([\w.]+)\s*\}\}$/);
+    if (whole) return lookupToken(whole[1], ctx);
+    return node.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, k) => {
+      const v = lookupToken(k, ctx);
+      return v == null ? "" : String(v);
+    });
+  }
+  if (Array.isArray(node)) return node.map((n) => resolveTemplate(n, ctx));
+  if (node && typeof node === "object") {
+    // Null-proto target so a template key like "__proto__" can't trigger prototype
+    // mutation (prototype-pollution class) when copied into the resolved object.
+    const out = Object.create(null);
+    for (const [k, v] of Object.entries(node)) out[k] = resolveTemplate(v, ctx);
+    return out;
+  }
+  return node;
+}
+async function runRoute(action, ctx) {
+  if (!action || typeof action.path !== "string" || action.path === "") {
+    throw new Error("This action has no route configured (action.path is missing or blank)");
+  }
+  const path = action.path.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, k) => {
+    const v = lookupToken(k, ctx);
+    return v == null ? "" : encodeURIComponent(String(v));
+  });
+  const method = String(action.method || "POST").toUpperCase();
+  let body;
+  if (action.body !== undefined) body = resolveTemplate(action.body, ctx);
+  else if (ctx.form) body = { variables: ctx.form };
+  else body = {};
+  const opts = { method, headers: { "content-type": "application/json" } };
+  if (method !== "GET" && method !== "HEAD") opts.body = JSON.stringify(body);
+  return getJSON(path, opts);
+}
+
 function el(tag, attrs = {}, ...kids) {
   const n = document.createElement(tag);
   for (const [k, v] of Object.entries(attrs)) {
@@ -722,37 +794,14 @@ function renderActionForm(node) {
     }
     btn.disabled = true; msg.className = "pc-msg"; msg.textContent = "Submitting…";
     try {
-      // 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;
-        }
-        // Send the trimmed key back as the variable too, so the value a worker
-        // reads matches the key the message was correlated on (no leading/trailing
-        // whitespace divergence between correlationKey and variables[field]).
-        variables[p.action.correlationKeyField] = correlationKey;
-        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 {
-        if (!p.action || !p.action.process) {
-          msg.className = "pc-msg err";
-          msg.textContent = "This form has no action configured";
-          return;
-        }
-        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 ?? "?") + ")";
-      }
+      // Route-driven: POST the form (as { variables } by default, or the action's
+      // own body template) to the action's route path. correlationKey / process /
+      // message are expressed by the path + body template the page author supplies,
+      // e.g. { path: "/app/actions/message", body: { name, correlationKey, variables: "{{form}}" } }.
+      const res = await runRoute(p.action, { form: variables });
+      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 = "";
       document.dispatchEvent(new CustomEvent("pc:refresh"));
     } catch (e) {
@@ -827,23 +876,9 @@ function renderDataGrid(node) {
   }
 
   async function fireAction(action, row) {
-    if (action.kind === "cancelProcess") {
-      return getJSON("/app/actions/cancel", { method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ processInstanceKey: row[action.keyField] }) });
-    }
-    if (action.kind === "publishMessage") {
-      return getJSON("/app/actions/message", { method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ name: action.message, correlationKey: row[action.correlationKeyField],
-          variables: { ...(action.variables || {}) } }) });
-    }
-    if (action.kind === "startProcess") {
-      return getJSON("/app/actions/start/" + encodeURIComponent(action.process), { method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ variables: { ...(action.variables || {}) } }) });
-    }
-    throw new Error("unknown action");
+    // Route-driven row action: POST the action's body template (default {})
+    // to its route path, with {{row.KEY}} tokens resolved from this row.
+    return runRoute(action, { row });
   }
 
   function rowActionButton(row, ra) {
@@ -878,11 +913,13 @@ function renderDataGrid(node) {
     btn.addEventListener("click", async () => {
       btn.disabled = true; msg.className = "pc-msg"; msg.textContent = "Sending…";
       try {
-        await getJSON("/app/actions/message", { method: "POST",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify({ name: f.action.message, correlationKey: row[f.action.correlationKeyField],
-            variables: { [f.inputKey]: input.value, ...(f.action.variables || {}) } }) });
-        msg.className = "pc-msg ok"; msg.textContent = "Sent";
+        // The textarea value is the form's single field (f.inputKey); route + body
+        // template come from f.action, e.g. { path: "/app/actions/message",
+        // body: { name, correlationKey: "{{row.pr_key}}", variables: "{{form}}" } }.
+        // Null-proto so an f.inputKey of "__proto__"/"constructor" can't mutate a prototype.
+        const form = Object.create(null); form[f.inputKey] = input.value;
+        await runRoute(f.action, { form, row });
+        msg.className = "pc-msg ok"; msg.textContent = (f.action && f.action.successLabel) || "Sent";
         document.dispatchEvent(new CustomEvent("pc:refresh"));
       } catch (e) {
         btn.disabled = false; msg.className = "pc-msg err"; msg.textContent = String(e.message || e);

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

@@ -111,7 +111,7 @@ export function mountSurfaces(ctx: RuntimeContext, app: AppApi): SurfacesHandle
   }
 
   // The OpenAPI endpoint surface (ADR 0058) mounts AFTER actions (so an exact `actions[]` route
-  // still shadows an operation) and BEFORE the generic pages routes. It owns the `api.base`
+  // still shadows an operation) and BEFORE the generic pages routes. It owns the fixed `/app/api`
   // namespace via a regex dispatcher, so it only contributes routes when the app declares `api`.
   const api = mountApi(ctx, app);
   if (api.routes.length > 0) {