@nanobpm/urban 0.76.0 → 0.77.1

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

@@ -1,10 +1,22 @@
-import type { HttpHandler, HttpResponse } from "./host.ts";
+import type { HttpHandler, HttpRequest, HttpResponse } from "./host.ts";
+/**
+ * A route handler that may DECLINE a matched request by returning `undefined`
+ * (or a promise of it). The router then treats the route as if it had not matched
+ * and continues to the next route (fall-through). This lets a broad prefix route —
+ * e.g. the pages surface's nested static serve at `/` — claim only the requests it
+ * can actually satisfy (a real, safe asset) and let everything else (`/healthz`, an
+ * app's own trigger routes registered *after* it) resolve to their own handlers,
+ * instead of a root catch-all silently swallowing them. A handler that returns a
+ * concrete `HttpResponse` (including a 404) still short-circuits as before, so this
+ * is backwards-compatible with every existing handler (none return `undefined`).
+ */
+export type RouteHandler = (req: HttpRequest) => Promise<HttpResponse | undefined> | HttpResponse | undefined;
 export interface Route {
     method: string;
     path: string;
     /** When true, match any path that starts with `path`. */
     prefix?: boolean;
-    handler: HttpHandler;
+    handler: RouteHandler;
     /** For diagnostics / inspect(). */
     source?: string;
 }

package/dist/runtime/core/router.js

@@ -43,8 +43,14 @@ function matches(route, req) {
 export function makeRouter(routes) {
     return async (req) => {
         for (const route of routes) {
-            if (matches(route, req))
-                return route.handler(req);
+            if (matches(route, req)) {
+                // A handler may DECLINE by returning `undefined` (see RouteHandler): treat the
+                // route as unmatched and keep looking, so a broad prefix serve can't shadow a
+                // later exact route (`/healthz`, a trigger) it didn't actually satisfy.
+                const res = await route.handler(req);
+                if (res !== undefined)
+                    return res;
+            }
         }
         return text("not found", 404);
     };

package/package.json

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

package/src/runtime/browser/runtime.browser.js

@@ -2385,32 +2385,58 @@ function renderDataGrid(node) {
 }
 
 // A navigation node — a horizontal menu bar (variant "bar", default) or a
-// vertical side rail (variant "rail"). Each item links either to another page
-// ({ label, page } -> an in-app #/<page> hash link, highlighted when it's the
-// current page) or to an external URL ({ label, href } -> a hardened new-tab
-// link; only http(s) is honoured). With items:"auto" (or omitted) the nav
-// lists every page from the /app/pages index, using each page's title. An item
-// may also carry a `badge` ({ source, table, filter, tone, refreshMs,
-// hideWhenZero }) that renders a live count pill from the /app/data gateway.
+// vertical side rail (variant "rail"). Each item links to one of three targets,
+// in precedence order:
+//   1. { label, page }  → an in-app #/<page> hash link within THIS (pages)
+//      surface, highlighted when it's the current page.
+//   2. { label, path }  → a same-origin, same-tab link to another mounted
+//      surface by relative path (e.g. "/tasks" → the taskInbox surface). The
+//      path is resolved against the app's mount root via baseRelativeUrl, so a
+//      root-absolute "/tasks" survives the Nano console's path-prefixed App-View
+//      proxy (/console/app-view/<name>/tasks) instead of escaping to the console
+//      origin. Only same-origin values are honoured here — a scheme
+//      (http(s)/javascript:/…) or protocol-relative "//host" is rejected (""),
+//      falling through to the {href} case, so `path` can never smuggle an
+//      external or executable-scheme target into a same-tab link. This is the
+//      only link form that composes multi-surface apps into a coherent,
+//      proxy-safe navigable whole (nanobpm/nano-ide#436).
+//   3. { label, href }  → a hardened external new-tab link; only http(s) is
+//      honoured.
+// With items:"auto" (or omitted) the nav lists every page from the /app/pages
+// index, using each page's title. An item may also carry a `badge` ({ source,
+// table, filter, tone, refreshMs, hideWhenZero }) that renders a live count pill
+// from the /app/data gateway.
 /** @param {any} item
  * @returns {HTMLAnchorElement|null}
  */
 function navLink(item) {
   const isPage = safePageId(item.page);
-  const isExt = !isPage && typeof item.href === "string" && /^https?:\/\//i.test(item.href);
-  if (!isPage && !isExt) return null;
+  // A same-origin relative path to another mounted surface (e.g. "/tasks"),
+  // rebased onto the app mount root so it survives the console proxy prefix.
+  const rel = isPage ? "" : sameOriginPath(item.path);
+  const isRel = !isPage && rel !== "";
+  const isExt = !isPage && !isRel && typeof item.href === "string" && /^https?:\/\//i.test(item.href);
+  if (!isPage && !isRel && !isExt) return null;
   /** @type {Record<string, any>} */
   const attrs = { class: "pc-nav-link" };
   if (isPage) {
     attrs.href = "#/" + encodeURIComponent(item.page);
     if (item.page === CURRENT) { attrs.class += " active"; attrs["aria-current"] = "page"; }
+  } else if (isRel) {
+    // Same-origin, same-tab: no target=_blank — this is in-app cross-surface
+    // navigation, not an external hand-off.
+    attrs.href = rel;
   } else {
     attrs.href = item.href; attrs.target = "_blank"; attrs.rel = "noopener noreferrer";
   }
   /** @type {Array<Node|string>} */
   const kids = [];
   if (item.icon != null) kids.push(el("span", { class: "pc-nav-icon" }, String(item.icon)));
-  const labelText = String(item.label != null ? item.label : (item.page || item.href));
+  // Default the label from the target actually used, not a fixed page>path>href
+  // fallback: when `path` is rejected and we fell through to `href`, the label
+  // must reflect the href we navigate to, never the discarded `path`.
+  const defaultLabel = isPage ? item.page : (isRel ? item.path : item.href);
+  const labelText = String(item.label != null ? item.label : defaultLabel);
   kids.push(el("span", { class: "pc-nav-label" }, labelText));
   const link = el("a", attrs, ...kids);
   // A nav item may carry a live count badge sourced from a datasource (e.g. the
@@ -2560,6 +2586,31 @@ function baseRelativeUrl(url) {
   return cleaned; // already relative
 }
 
+// Resolve a same-origin, in-app relative path (e.g. a nav item's { path: "/tasks" }
+// targeting another mounted surface) onto the app's mount root, so it survives the
+// console App-View proxy prefix — the SAME rebasing rule as baseRelativeUrl (the
+// single source of truth for "strip one leading slash to rebase onto the mount
+// root"). Unlike baseRelativeUrl (whose output is an <iframe> src that may legally
+// be an http(s) URL), a cross-surface nav link must stay SAME-ORIGIN and same-tab:
+// a scheme (http(s):, and — defence in depth — javascript:/data:/… ) or a
+// protocol-relative "//host" is NOT an in-app path, so it is rejected ("") and the
+// caller falls through to the hardened new-tab {href} handling. Whitespace is
+// stripped/trimmed FIRST (browsers strip ASCII tab/newline before parsing a URL, so
+// `/ta\tsks` must be judged on its cleaned form) so the scheme gate can't be
+// bypassed by embedded whitespace.
+/** @param {any} path */
+function sameOriginPath(path) {
+  if (typeof path !== "string") return "";
+  // Browsers normalize backslashes to `/` in URLs, so `\\evil.example/tasks` (or
+  // `/\evil.example`) is parsed as protocol-relative `//evil.example/…`. Fold `\` → `/`
+  // before the scheme/`//` gates so a backslash can't smuggle a cross-origin target past them.
+  const cleaned = path.replace(/[\t\n\r]/g, "").replace(/\\/g, "/").trim();
+  if (cleaned === "") return "";
+  if (/^[a-z][a-z0-9+.-]*:/i.test(cleaned)) return ""; // any scheme → not a same-origin in-app path
+  if (cleaned.startsWith("//")) return ""; // protocol-relative → different origin
+  return baseRelativeUrl(cleaned); // rebase root-absolute onto the mount root (shared rule)
+}
+
 // `appView` (ADR 0057 / #416): mount an embedded App View — an <iframe> hosting a
 // self-contained view document (e.g. the agent cockpit's embed.html) served
 // alongside the page. This is the runtime counterpart of the console's App-View
@@ -2798,4 +2849,4 @@ function boot() {
 // renderer functions / RENDERERS registry can be imported directly.
 if (typeof document !== "undefined" && document.getElementById("page")) boot();
 
-export { RENDERERS, renderText, renderButton, renderProse, renderNav, renderAppView, navLink, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell, buildDetailForm, evalDetailCondition, normalizeDetailOptions, chevronToggle, setChevronOpen };
+export { RENDERERS, renderText, renderButton, renderProse, renderNav, renderAppView, navLink, sameOriginPath, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell, buildDetailForm, evalDetailCondition, normalizeDetailOptions, chevronToggle, setChevronOpen };

package/src/runtime/browser/runtime.browser.test.ts

@@ -7,7 +7,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { PAGE_NODE_TYPES } from "../core/page-nodes.ts";
-import { RENDERERS, renderText, renderAppView, navLink, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell } from "./runtime.browser.js";
+import { RENDERERS, renderText, renderAppView, navLink, sameOriginPath, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell } from "./runtime.browser.js";
 
 // ── Minimal fake DOM ────────────────────────────────────────────────────────
 // Just enough of the Element/Document surface that el()/renderText touch:
@@ -348,6 +348,110 @@ test("#338: navLink badge degrades to no pill (never a broken nav) when the fetc
   assert.equal(pill.textContent, "");
 });
 
+// ── #436: same-origin cross-surface nav (a { path } item) ───────────────────
+// A pages-surface nav item can now point at another mounted surface by a relative
+// same-origin path (e.g. "/tasks" → the taskInbox surface): an in-page, same-tab
+// link, rebased onto the app mount root so it survives the console App-View proxy
+// prefix. This is distinct from { page } (an in-app #/<page> hash) and { href }
+// (an external new-tab http(s) link).
+
+test("#436: navLink({ path }) renders a same-origin, same-tab link rebased onto the mount root", (t) => {
+  t.after(installFakeDom());
+  const link = navLink({ label: "Tasks", path: "/tasks" });
+  assert.ok(link, "expected a nav link for a { path } item");
+  assert.equal(link.tagName, "A");
+  // Root-absolute "/tasks" is rebased to a document-relative "tasks" so it inherits
+  // the mount root (and thus the console proxy prefix) rather than escaping to origin.
+  assert.equal(link.getAttribute("href"), "tasks");
+  // Same-tab, same-origin: NOT an external hand-off — no new-tab / noopener chrome.
+  assert.equal(link.getAttribute("target"), null, "cross-surface nav stays in the same tab");
+  assert.equal(link.getAttribute("rel"), null, "no rel=noopener on a same-origin link");
+  const label = findByClass(link, "pc-nav-label");
+  assert.ok(label && label.textContent === "Tasks");
+});
+
+test("#436: navLink({ path }) falls back to the path as its label when none is given", (t) => {
+  t.after(installFakeDom());
+  const link = navLink({ path: "/tasks" });
+  assert.ok(link);
+  const label = findByClass(link, "pc-nav-label");
+  assert.ok(label && label.textContent === "/tasks", "label defaults to the raw path");
+});
+
+test("#436: a { page } item still wins over a { path } (in-app hash route has precedence)", (t) => {
+  t.after(installFakeDom());
+  const link = navLink({ label: "Home", page: "home", path: "/tasks" });
+  assert.ok(link);
+  assert.equal(link.getAttribute("href"), "#/home", "page hash route takes precedence over path");
+  assert.equal(link.getAttribute("target"), null);
+});
+
+test("#436: a same-origin { path } wins over an external { href } (in-app link preferred)", (t) => {
+  t.after(installFakeDom());
+  const link = navLink({ label: "Tasks", path: "/tasks", href: "https://example.test/tasks" });
+  assert.ok(link);
+  assert.equal(link.getAttribute("href"), "tasks", "the same-origin path is used, not the external href");
+  assert.equal(link.getAttribute("target"), null, "so it stays same-tab, not a new-tab external link");
+});
+
+test("#436: a scheme/protocol-relative { path } is rejected and falls through to the { href } handling", (t) => {
+  t.after(installFakeDom());
+  // A hostile/mistaken path carrying a scheme must NOT become a same-tab link — it
+  // is rejected as not-same-origin and the item falls through to the hardened
+  // new-tab external-href branch.
+  const link = navLink({ label: "Evil", path: "javascript:alert(1)", href: "https://example.test/ok" });
+  assert.ok(link);
+  assert.equal(link.getAttribute("href"), "https://example.test/ok");
+  assert.equal(link.getAttribute("target"), "_blank");
+  assert.equal(link.getAttribute("rel"), "noopener noreferrer");
+});
+
+test("#436: with no label and a rejected { path }, the default label matches the { href } actually used", (t) => {
+  t.after(installFakeDom());
+  // No explicit label: the path is rejected (unsafe scheme) and we fall through to
+  // the external href. The default label MUST reflect the href we navigate to, never
+  // the discarded path — otherwise the visible text lies about the link target.
+  const link = navLink({ path: "javascript:alert(1)", href: "https://example.test/ok" });
+  assert.ok(link);
+  assert.equal(link.getAttribute("href"), "https://example.test/ok");
+  const label = findByClass(link, "pc-nav-label");
+  assert.ok(label && label.textContent === "https://example.test/ok", "label defaults to the href actually used, not the rejected path");
+});
+
+test("#436: a { path } item with only an unsafe scheme and no href renders nothing", (t) => {
+  t.after(installFakeDom());
+  assert.equal(navLink({ label: "Evil", path: "javascript:alert(1)" }), null);
+  assert.equal(navLink({ label: "Ext", path: "//evil.example/tasks" }), null);
+});
+
+test("#436: sameOriginPath rebases in-app paths and rejects non-same-origin targets", () => {
+  // Root-absolute → rebased onto the mount root (survives the console proxy prefix).
+  assert.equal(sameOriginPath("/tasks"), "tasks");
+  assert.equal(sameOriginPath("/tasks/inbox"), "tasks/inbox");
+  // Already document-relative → left as-is.
+  assert.equal(sameOriginPath("tasks"), "tasks");
+  assert.equal(sameOriginPath("./tasks"), "./tasks");
+  // Embedded ASCII tab/newline is stripped before the scheme gate (browsers strip
+  // it before parsing), so `java\tscript:` can't sneak past as a "relative" path.
+  assert.equal(sameOriginPath("java\tscript:alert(1)"), "");
+  // Any scheme / protocol-relative host is not a same-origin in-app path.
+  assert.equal(sameOriginPath("https://example.test/tasks"), "");
+  assert.equal(sameOriginPath("http://example.test/tasks"), "");
+  assert.equal(sameOriginPath("javascript:alert(1)"), "");
+  assert.equal(sameOriginPath("data:text/html,x"), "");
+  assert.equal(sameOriginPath("//evil.example/tasks"), "");
+  // Backslashes are folded to `/` before the gates (browsers normalize them), so a
+  // `\\host` or `/\host` value can't smuggle a protocol-relative cross-origin target past.
+  assert.equal(sameOriginPath("\\\\evil.example/tasks"), "");
+  assert.equal(sameOriginPath("/\\evil.example/tasks"), "");
+  assert.equal(sameOriginPath("\\/evil.example/tasks"), "");
+  // Non-strings / blanks → "".
+  assert.equal(sameOriginPath(""), "");
+  assert.equal(sameOriginPath("   "), "");
+  assert.equal(sameOriginPath(null), "");
+  assert.equal(sameOriginPath(42), "");
+});
+
 test("#338: applyNavBadge honours hideWhenZero and mirrors the count into the accessible name", (t) => {
   const restore = installFakeDom();
   t.after(restore);

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

@@ -5,7 +5,8 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import { mountAgent } from "./agent.ts";
 import type { RuntimeContext } from "../context.ts";
-import type { EngineClient, HostContext, HttpRequest, HttpResponse } from "../host.ts";
+import type { EngineClient, HostContext, HttpResponse } from "../host.ts";
+import type { Route } from "../router.ts";
 
 const fakeEngine: EngineClient = {
   deployResources: async () => ({ deployed: 0 }),
@@ -44,14 +45,16 @@ function ctxWithFiles(files: Record<string, string>): RuntimeContext {
   return { root: ".", manifest: { schemaVersion: 1, id: "app", name: "App" }, host, engine: fakeEngine };
 }
 
-async function call(route: { handler: (req: HttpRequest) => HttpResponse | Promise<HttpResponse> }): Promise<HttpResponse> {
-  return route.handler({
+async function call(route: Route): Promise<HttpResponse> {
+  const res = await route.handler({
     method: "GET",
     path: "/",
     query: new URLSearchParams(),
     headers: new Headers(),
     text: async () => "",
   });
+  assert.ok(res, "handler should not decline");
+  return res;
 }
 
 const routeAt = (ctx: RuntimeContext, path: string) => {

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

@@ -1823,3 +1823,130 @@ test("the static asset routes do not shadow the app's own routes or /healthz", a
   const home = await router(req("GET", "/"));
   assert.match(home.body ?? "", /data-home="home"/);
 });
+
+// ── nested (multi-appView) sidecar serving (#442) ──────────────────────────
+// An app with two-or-more appViews ships each view's sidecar under its own subdir
+// (`./cockpit/embed.html`, `./board/embed.html`); #420's flat 4-name serve 404'd every
+// one. These pin the generalized nested prefix serve of `pages/<subpath>` (and that it
+// still declines — never a root catch-all — so `/healthz` / triggers keep resolving).
+
+test("GET /<subdir>/embed.html serves the nested appView sidecar", async () => {
+  const router = buildWithAssets({
+    "pages/cockpit/embed.html": "<!doctype html><title>cockpit</title>",
+    "pages/board/embed.html": "<!doctype html><title>board</title>",
+  });
+  const cockpit = await router(req("GET", "/cockpit/embed.html"));
+  assert.equal(cockpit.status, 200);
+  assert.match(cockpit.headers?.["content-type"] ?? "", /text\/html/);
+  assert.match(cockpit.body ?? "", /<title>cockpit<\/title>/);
+  const board = await router(req("GET", "/board/embed.html"));
+  assert.equal(board.status, 200);
+  assert.match(board.body ?? "", /<title>board<\/title>/);
+});
+
+test("all nested subdir sidecar assets are served with correct content types", async () => {
+  const router = buildWithAssets({
+    "pages/cockpit/embed.html": "<html>embed</html>",
+    "pages/cockpit/standalone.html": "<html>standalone</html>",
+    "pages/cockpit/mount.js": "export const mountCockpit = () => {};",
+    "pages/cockpit/cockpit.css": "body{margin:0}",
+    "pages/delivery-graphs/embed.html": "<html>dg</html>",
+  });
+  const cases: [string, RegExp][] = [
+    ["/cockpit/embed.html", /text\/html/],
+    ["/cockpit/standalone.html", /text\/html/],
+    ["/cockpit/mount.js", /text\/javascript/],
+    ["/cockpit/cockpit.css", /text\/css/],
+    // A hyphenated multi-appView page id (the merlin repro) resolves too.
+    ["/delivery-graphs/embed.html", /text\/html/],
+  ];
+  for (const [path, ct] of cases) {
+    const res = await router(req("GET", path));
+    assert.equal(res.status, 200, `${path} should 200`);
+    assert.match(res.headers?.["content-type"] ?? "", ct, `${path} content-type`);
+  }
+});
+
+test("the flat single-appView sidecar back-compat still serves (#420) alongside nested", async () => {
+  // The root `pages/embed.html` case #420 shipped must keep working: an app with exactly
+  // one appView (no subdir) is unaffected by the nested generalization.
+  const router = buildWithAssets({
+    "pages/embed.html": "<html>flat</html>",
+    "pages/cockpit/embed.html": "<html>nested</html>",
+  });
+  const flat = await router(req("GET", "/embed.html"));
+  assert.equal(flat.status, 200);
+  assert.match(flat.body ?? "", /flat/);
+  const nested = await router(req("GET", "/cockpit/embed.html"));
+  assert.equal(nested.status, 200);
+  assert.match(nested.body ?? "", /nested/);
+});
+
+test("a missing nested sidecar 404s instead of throwing", async () => {
+  const router = buildWithAssets({ "pages/cockpit/embed.html": "<html>ok</html>" });
+  const res = await router(req("GET", "/board/embed.html"));
+  assert.equal(res.status, 404);
+});
+
+test("a nested-serve path traversal attempt is rejected (never reaches the filesystem)", async () => {
+  // The `pages/` tree reuses the SAME sub-path guard as `/dist/`: any `..` / absolute /
+  // percent-escaped / backslash / doubled-slash segment must be rejected before a read.
+  let readAttempts = 0;
+  const { engine } = fakeEngine();
+  const router = makeRouter(
+    createPagesRoutes(
+      { pagesDir: "pages", homePage: "home", sourceName: "app" },
+      {
+        db: fakeDb(),
+        engine,
+        readPage: async () => JSON.stringify({ title: "Home", nodes: [] }),
+        readAsset: async (path: string) => {
+          readAttempts++;
+          return `bytes of ${path}`;
+        },
+        listPages: async () => ["home"],
+      },
+    ),
+  );
+  for (const evil of ["/cockpit/../secret.json", "/a/../../secret", "/cockpit/%2e%2e/secret", "/cockpit//etc"]) {
+    const res = await router(req("GET", evil));
+    assert.equal(res.status, 404, `${evil} must 404`);
+  }
+  assert.equal(readAttempts, 0, "no traversal path may reach the asset reader");
+});
+
+test("the nested serve declines (does not shadow) a same-path trigger route registered after it", async () => {
+  // The nested serve is a `/`-prefix route registered before the triggers surface. A miss
+  // must DECLINE (fall through) so a trigger at `/webhooks/deploy` still resolves, rather
+  // than being masked by the pages tree's 404. A root catch-all would silently swallow it.
+  const routes = createPagesRoutes(
+    { pagesDir: "pages", homePage: "home", sourceName: "app" },
+    {
+      db: fakeDb(),
+      engine: fakeEngine().engine,
+      readPage: async () => JSON.stringify({ title: "Home", nodes: [] }),
+      readAsset: async (path: string) => {
+        // Only the real nested sidecar exists; every other path is a miss.
+        if (path === "pages/cockpit/embed.html") return "<html>cockpit</html>";
+        throw new Error(`no such file: ${path}`);
+      },
+      listPages: async () => ["home"],
+    },
+  );
+  const router = makeRouter([
+    ...routes,
+    {
+      method: "GET",
+      path: "/webhooks/deploy",
+      handler: () => ({ status: 202, headers: { "content-type": "application/json" }, body: JSON.stringify({ queued: true }) }),
+    },
+  ]);
+  // The real nested sidecar is served by the pages tree.
+  const sidecar = await router(req("GET", "/cockpit/embed.html"));
+  assert.equal(sidecar.status, 200);
+  assert.match(sidecar.body ?? "", /cockpit/);
+  // The multi-segment trigger path is NOT shadowed — the nested serve declines the miss.
+  const hook = await router(req("GET", "/webhooks/deploy"));
+  assert.equal(hook.status, 202);
+  assert.deepEqual(JSON.parse(hook.body ?? "{}"), { queued: true });
+});

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

@@ -11,7 +11,8 @@
 //   GET  /              (+ /app/runtime.js)         → the schema-driven browser renderer
 //   GET  /app/pages/<id>                            → the page's page.json
 //   GET  /app/data/<source>/<table>[?where&order]   → rows (filtered/ordered, whitelisted)
-//   GET  /{embed,standalone}.html /mount.js /cockpit.css → appView sidecars (from pagesDir, #420)
+//   GET  /{embed,standalone}.html /mount.js /cockpit.css → flat appView sidecars (from pagesDir, #420)
+//   GET  /<subdir>/<asset>                          → nested appView sidecars (pages/<subdir>/…, #442)
 //   GET  /dist/<path>                               → the app dist/ bundle the sidecars reference
 //   POST /app/actions/start/<process>               → engine.createInstance
 //   POST /app/actions/cancel                        → engine.cancelInstance
@@ -107,7 +108,10 @@ function javascript(
 // document then pulls `./cockpit.css`, `./mount.js`, and (via its import-map)
 // `../dist/…`. A DEPLOYED app served none of these, so the src 404'd and the cockpit
 // iframe loaded nothing (#416's user-facing "nothing shows in the Cockpit"). These are
-// the root-served sidecar files, mapped 1:1 onto `pagesDir/<name>`. The `dist/` tree the
+// the root-served sidecar files, mapped 1:1 onto `pagesDir/<name>`. An app that ships
+// MORE than one `appView` gives each its own SUBDIR sidecar (`./cockpit/embed.html`,
+// `./board/embed.html`, …) — those are served by the nested prefix route below (#442);
+// this flat set stays as the single-appView back-compat case (#420). The `dist/` tree the
 // import-map references is served separately under the `/dist/` prefix below.
 const SIDECAR_ASSETS = ["embed.html", "standalone.html", "mount.js", "cockpit.css"] as const;
 
@@ -541,6 +545,44 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
     },
   });
 
+  // ── nested (multi-appView) sidecars (#442) ──────────────────────────────
+  // An app with more than one `appView` cannot share the four FLAT sidecar names above:
+  // each view ships its own SUBDIR sidecar — e.g. `pages/cockpit.page.json` →
+  // `./cockpit/embed.html`, `pages/board.page.json` → `./board/embed.html`. The renderer's
+  // `baseRelativeUrl(p.embed)` rebases those onto the mount root, so the browser fetches
+  // `/cockpit/embed.html`, `/board/mount.js`, … — every one of which #420's flat 4-name
+  // serve 404'd. Serve the `pagesDir` as a TREE, mapping `/<subpath>` onto
+  // `pagesDir/<subpath>` with the SAME traversal guard as the `/dist/` route (mirroring it).
+  // It is a `/`-prefix route, so to avoid a root catch-all silently swallowing `/healthz`,
+  // the app's own trigger routes, or any other route, the handler DECLINES (returns
+  // undefined → the router falls through to the next route, see `RouteHandler`) whenever it
+  // cannot serve a real nested asset:
+  //   • a bare single-segment path (`/healthz`, the flat sidecars) — owned by its own exact
+  //     route / the runtime's liveness route, never this tree;
+  //   • an unsafe subpath (`..`/absolute/percent-escaped/backslash) — traversal-rejected
+  //     before it reaches the filesystem;
+  //   • a miss (no such file) — so a same-path route registered AFTER the pages surface (a
+  //     trigger, the appended `/healthz`) still resolves instead of being masked by a 404.
+  // Registered LAST among the pages routes so every exact/prefix pages route above wins first.
+  routes.push({
+    method: "GET",
+    path: "/",
+    prefix: true,
+    source: "surface:pages",
+    handler: async (req) => {
+      const rest = req.path.slice(1); // drop the leading "/"
+      // Only a SUBDIR asset (has a `/`) belongs to this tree; a single-segment path is left
+      // to its own exact route / the appended `/healthz` liveness route.
+      if (!rest.includes("/")) return undefined;
+      const safe = safeAssetSubpath(rest);
+      if (safe === null) return undefined; // traversal/escape → decline (never touch the FS)
+      const res = await serveAsset(readAsset, `${pagesDir}/${safe}`);
+      // A miss declines rather than 404s, so a later same-path route (e.g. a trigger) can
+      // still claim it; the router's own default 404 covers a genuinely absent asset.
+      return res.status === 404 ? undefined : res;
+    },
+  });
+
   return routes;
 }