@nanobpm/urban 0.72.2 → 0.74.0

package/dist/runtime/core/page-nodes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Page-node types this runtime renders that are NOT (yet) in the canonical schema.
+ *
+ * When a token here lands in `@nanobpm/nano-app-schema`'s `PAGE_NODE_TYPES` and this
+ * package's dep is bumped, drop it from this list (and, once the list is empty, delete
+ * this module and re-export `PAGE_NODE_TYPES`/`PageNodeType` straight from the schema).
+ */
+export declare const LOCAL_PAGE_NODE_TYPES: readonly ["appView"];
+/** The full set of page-node types the browser renderer draws: schema ∪ local bridge. */
+export declare const PAGE_NODE_TYPES: readonly ["text", "nav", "actionForm", "dataGrid", "prose", "button", "appView"];
+/** A node type the composed-page renderer can draw — one of {@link PAGE_NODE_TYPES}. */
+export type PageNodeType = (typeof PAGE_NODE_TYPES)[number];

package/dist/runtime/core/page-nodes.js

@@ -0,0 +1,32 @@
+// The page-node type registry the browser renderer draws — the schema's canonical
+// set, extended locally with the node types this runtime ships ahead of the schema.
+//
+// The App page-node contract is owned by @nanobpm/nano-app-schema (ADR 0027): its
+// `PAGE_NODE_TYPES` is the canonical registry the Console's Page Composer binds to.
+// This runtime's browser renderer must draw exactly that set — a schema type with
+// no renderer (or a renderer with no schema type) renders an accepted node as a
+// blank <div>, the silent failure #416 fixed for `appView`.
+//
+// `appView` (ADR 0057 — an embedded App View iframe) ships in this runtime *before*
+// it lands in the published schema. Rather than silently diverge, we bridge it here
+// — the same "mirror locally until the canonical schema folds it in, then delete the
+// bridge and re-export" pattern used for `network` / `terminalStatuses` in
+// `manifest.ts` (No Drift Surfaces). This module is the single source of truth for
+// the extended set: the browser renderer's `RENDERERS satisfies Record<PageNodeType,
+// Renderer>` lock and the runtime drift test both consume `PAGE_NODE_TYPES` from
+// here, so the renderer registry and the type union cannot drift.
+import { PAGE_NODE_TYPES as SCHEMA_PAGE_NODE_TYPES } from "@nanobpm/nano-app-schema";
+/**
+ * Page-node types this runtime renders that are NOT (yet) in the canonical schema.
+ *
+ * When a token here lands in `@nanobpm/nano-app-schema`'s `PAGE_NODE_TYPES` and this
+ * package's dep is bumped, drop it from this list (and, once the list is empty, delete
+ * this module and re-export `PAGE_NODE_TYPES`/`PageNodeType` straight from the schema).
+ */
+export const LOCAL_PAGE_NODE_TYPES = [
+    // #416 / ADR 0057: an embedded App View — an <iframe> hosting a self-contained view
+    // document (e.g. the agent cockpit's embed.html) served alongside the page.
+    "appView",
+];
+/** The full set of page-node types the browser renderer draws: schema ∪ local bridge. */
+export const PAGE_NODE_TYPES = [...SCHEMA_PAGE_NODE_TYPES, ...LOCAL_PAGE_NODE_TYPES];

package/package.json

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

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

@@ -16,7 +16,7 @@
 // That lets the renderer functions and the RENDERERS registry be imported and
 // unit-tested with a fake DOM, and lets the string-generation build load it.
 
-/** @typedef {import("@nanobpm/nano-app-schema").PageNodeType} PageNodeType */
+/** @typedef {import("../core/page-nodes.ts").PageNodeType} PageNodeType */
 /**
  * A page node from a `*.page.json` document. `props` is an open, author-supplied
  * bag whose shape is owned/validated by `@nanobpm/nano-app-schema`, so it is
@@ -2532,16 +2532,108 @@ function renderNav(node) {
   return nav;
 }
 
+// A page-relative URL that resolves correctly whether the app is served at the
+// origin root (CLI on :3000) or under the Nano console's path-prefixed App-View
+// proxy (/console/app-view/<name>/). Same reasoning as the shell's `badgeHref`
+// and mount.js's reportUrl handling: a root-absolute "/x" would escape the proxy
+// prefix and hit the CONSOLE origin, so a single leading slash is stripped to
+// rebase onto the mount root; an already document-relative ("./x", "x") or an
+// absolute ("http(s)://…") / protocol-relative ("//host") URL is left untouched.
+// The result becomes an <iframe> src, so a scheme URL is only honoured when it is
+// http/https: a hostile/malformed page doc could otherwise smuggle an executable
+// `javascript:`/`data:`/`vbscript:` src, so any other scheme is rejected ("" →
+// caller omits the attribute). Input is trimmed and ASCII tab/newline stripped
+// FIRST (browsers strip those before parsing a URL, so `java\tscript:` would still
+// execute) so scheme detection cannot be bypassed by embedded whitespace.
+/** @param {string} url */
+function baseRelativeUrl(url) {
+  if (typeof url !== "string") return "";
+  const cleaned = url.replace(/[\t\n\r]/g, "").trim();
+  if (cleaned === "") return "";
+  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(cleaned);
+  if (scheme) {
+    const proto = scheme[1].toLowerCase();
+    return proto === "http" || proto === "https" ? cleaned : ""; // reject javascript:/data:/vbscript:/file:/…
+  }
+  if (cleaned.startsWith("//")) return cleaned; // protocol-relative
+  if (cleaned.startsWith("/")) return cleaned.slice(1); // root-absolute → document-relative (rebase onto mount root)
+  return cleaned; // already relative
+}
+
+// `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
+// surface: the SAME embed document renders here (in the app's own UI) and, when the
+// console embeds the app, there. Before this renderer existed an `appView` node fell
+// through to a blank <div> (RENDERERS[n.type] || (() => el("div"))), so an entire
+// embedded view — the live agent cockpit — was SILENTLY invisible with no error.
+/** @param {PageNode} node */
+function renderAppView(node) {
+  const p = node.props || {};
+  const title = p.title != null ? String(p.title) : "";
+  const fill = p.fill === true;
+  const src = baseRelativeUrl(typeof p.embed === "string" ? p.embed : "");
+
+  const frame = /** @type {HTMLIFrameElement} */ (
+    el("iframe", {
+      class: "pc-appview-frame",
+      // Base-relative so the embed resolves under both the app root and the console
+      // App-View proxy prefix (see baseRelativeUrl). Omitted (about:blank) when no
+      // usable `embed` is declared — an empty `src=""` resolves to the current
+      // document URL in browsers, risking a recursive self-embed. The node still
+      // renders its chrome rather than throwing.
+      src: src || undefined,
+      title: title || "App view",
+      loading: "lazy",
+      referrerpolicy: "same-origin",
+    })
+  );
+
+  // Forward the App-View endpoint config to the embed's own window (ADR 0057:
+  // embed.html reads `window.__NANO_APP_VIEW__`). The console injects this when IT
+  // hosts the embed; here — the same-origin app render — mount.js already defaults
+  // every endpoint to the app's own origin, so the cockpit is fully functional with
+  // nothing injected. We seed the frame's window on load only to thread through
+  // explicit per-node overrides (props.reportUrl / relayUrl / transcriptsUrl), so a
+  // page can point the embed at a non-default endpoint without editing the embed
+  // document. Best-effort and guarded: a cross-origin embed is left to its defaults.
+  /** @type {Record<string, string>} */
+  const overrides = {};
+  if (typeof p.reportUrl === "string") overrides.reportUrl = p.reportUrl;
+  if (typeof p.relayUrl === "string") overrides.relayUrl = p.relayUrl;
+  if (typeof p.transcriptsUrl === "string") overrides.transcriptsUrl = p.transcriptsUrl;
+  frame.addEventListener("load", () => {
+    try {
+      const w = /** @type {any} */ (frame.contentWindow);
+      if (w) {
+        w.__NANO_APP_VIEW__ = {
+          ...(w.__NANO_APP_VIEW__ || {}),
+          host: (typeof location !== "undefined" && location.origin) || "",
+          ...overrides,
+        };
+      }
+    } catch (_e) {
+      // Cross-origin embed: we cannot (and need not) touch its window.
+    }
+  });
+
+  const section = el("section", { class: "pc-appview" + (fill ? " pc-appview-fill" : "") });
+  if (title) section.append(el("div", { class: "pc-appview-title" }, title));
+  section.append(frame);
+  return section;
+}
+
 // The browser renderer's dispatch table: the runtime source of truth for which
 // page-node types can be drawn. `@satisfies Record<PageNodeType, Renderer>` locks
-// it, at compile time, to `@nanobpm/nano-app-schema`'s PAGE_NODE_TYPES — the same
-// registry the Console's Page Composer is bound to. Adding a schema node type
-// without a renderer here (or vice-versa) is now a type error, so the table can
-// no longer silently drift from the schema (this replaces the #290 regex guard,
-// which had to string-scrape these keys precisely because this used to be a
-// string). The drift is also covered by a real-import unit test.
+// it, at compile time, to the shared `PAGE_NODE_TYPES` registry (`../core/page-nodes.ts`
+// — the canonical @nanobpm/nano-app-schema set, extended with the node types this
+// runtime ships ahead of the schema, e.g. `appView` #416). Adding a page-node type
+// without a renderer here (or vice-versa) is now a type error, so the table can no
+// longer silently drift from the registry (this replaces the #290 regex guard, which
+// had to string-scrape these keys precisely because this used to be a string). The
+// drift is also covered by a real-import unit test.
 /** @satisfies {Record<PageNodeType, Renderer>} */
-const RENDERERS = { text: renderText, actionForm: renderActionForm, dataGrid: renderDataGrid, prose: renderProse, nav: renderNav, button: renderButton };
+const RENDERERS = { text: renderText, actionForm: renderActionForm, dataGrid: renderDataGrid, prose: renderProse, nav: renderNav, button: renderButton, appView: renderAppView };
 
 // Durable per-node UI state. localStorage is keyed by the home page id + node
 // id so two grids on the same page (or the same grid across pages) don't clash,
@@ -2706,4 +2798,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, navLink, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell, buildDetailForm, evalDetailCondition, normalizeDetailOptions, chevronToggle, setChevronOpen };
+export { RENDERERS, renderText, renderButton, renderProse, renderNav, renderAppView, navLink, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell, buildDetailForm, evalDetailCondition, normalizeDetailOptions, chevronToggle, setChevronOpen };

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

@@ -6,8 +6,8 @@
 // a real import, and adds the first true renderer-level unit coverage.
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { PAGE_NODE_TYPES } from "@nanobpm/nano-app-schema";
-import { RENDERERS, renderText, navLink, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell } from "./runtime.browser.js";
+import { PAGE_NODE_TYPES } from "../core/page-nodes.ts";
+import { RENDERERS, renderText, renderAppView, navLink, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell } from "./runtime.browser.js";
 
 // ── Minimal fake DOM ────────────────────────────────────────────────────────
 // Just enough of the Element/Document surface that el()/renderText touch:
@@ -77,6 +77,16 @@ function installFakeDom(): () => void {
   };
 }
 
+// A renderer statically returns HTMLElement but at runtime produces a FakeElement
+// (the installed fake `document.createElement`). Narrow to FakeElement so a test can
+// walk `.children` — without a banned `as` cast — by asserting the runtime shape.
+function asFake(node: unknown): FakeElement {
+  if (!(node instanceof FakeElement)) {
+    throw new Error("expected a FakeElement (is the fake DOM installed?)");
+  }
+  return node;
+}
+
 test("#291: RENDERERS is a real importable registry keyed exactly by PAGE_NODE_TYPES", () => {
   // The drift lock is enforced at compile time by `RENDERERS satisfies
   // Record<PageNodeType, Renderer>` in the source; this asserts the same at
@@ -117,6 +127,113 @@ test("#291: renderText degrades to empty text (never throws) on a missing text p
   assert.equal(node.textContent, "");
 });
 
+test("#416: appView is a rendered node type (registry + bridged PAGE_NODE_TYPES)", () => {
+  // The whole point of #416: an `appView` page node must have a real renderer, not
+  // fall through to a blank <div>. It is in the RENDERERS registry and — since it
+  // ships here ahead of the canonical schema — in the locally-bridged PAGE_NODE_TYPES.
+  assert.ok(PAGE_NODE_TYPES.includes("appView"), "appView must be in the bridged PAGE_NODE_TYPES");
+  assert.equal(typeof RENDERERS.appView, "function", "appView must have a renderer");
+});
+
+test("#416: renderAppView mounts a base-relative iframe honoring embed/title/fill", (t) => {
+  t.after(installFakeDom());
+  const section = asFake(
+    renderAppView({
+      type: "appView",
+      props: { title: "Agent networks", embed: "./embed.html", fill: true },
+    }),
+  );
+  assert.equal(section.tagName, "SECTION");
+  // fill → the tall flex container variant so the embed gets viewport height.
+  assert.equal(section.className, "pc-appview pc-appview-fill");
+
+  const frame = section.children.find(
+    (c): c is FakeElement => c instanceof FakeElement && c.tagName === "IFRAME",
+  );
+  assert.ok(frame, "an <iframe> must be mounted");
+  // The iframe src is the node's embed, left document-relative so it resolves under
+  // both the app root and the console App-View proxy prefix.
+  assert.equal(frame.getAttribute("src"), "./embed.html");
+  assert.equal(frame.getAttribute("title"), "Agent networks");
+  assert.equal(frame.className, "pc-appview-frame");
+
+  // The title also renders as a visible label above the frame.
+  const label = section.children.find(
+    (c): c is FakeElement => c instanceof FakeElement && c.className === "pc-appview-title",
+  );
+  assert.ok(label, "the title renders as a label");
+  assert.equal(label.textContent, "Agent networks");
+});
+
+test("#416: renderAppView rebases a root-absolute embed onto the mount root", (t) => {
+  t.after(installFakeDom());
+  // A root-absolute "/embed.html" would escape the console proxy prefix and hit the
+  // console origin; the renderer strips the single leading slash to rebase it.
+  const section = asFake(renderAppView({ type: "appView", props: { embed: "/embed.html" } }));
+  const frame = section.children.find(
+    (c): c is FakeElement => c instanceof FakeElement && c.tagName === "IFRAME",
+  );
+  assert.ok(frame);
+  assert.equal(frame.getAttribute("src"), "embed.html");
+});
+
+test("#416: renderAppView is non-fill by default and never throws on missing props", (t) => {
+  t.after(installFakeDom());
+  const section = asFake(renderAppView({ type: "appView", props: {} }));
+  assert.equal(section.tagName, "SECTION");
+  assert.equal(section.className, "pc-appview");
+  const frame = section.children.find(
+    (c): c is FakeElement => c instanceof FakeElement && c.tagName === "IFRAME",
+  );
+  assert.ok(frame, "an <iframe> is still mounted with no embed");
+  // No usable embed → src is OMITTED (about:blank), not src="" (which resolves to
+  // the current document URL in browsers and risks a recursive self-embed).
+  assert.equal(frame.getAttribute("src"), null);
+  // No title → no label element rendered.
+  const label = section.children.find(
+    (c): c is FakeElement => c instanceof FakeElement && c.className === "pc-appview-title",
+  );
+  assert.equal(label, undefined);
+});
+
+test("#416: renderAppView neutralizes a dangerous-scheme embed (no executable iframe src)", (t) => {
+  t.after(installFakeDom());
+  // A hostile/malformed page doc must not be able to smuggle an executable iframe
+  // src via a javascript:/data:/vbscript: embed, nor bypass the check with embedded
+  // whitespace/tabs (browsers strip those before parsing the URL).
+  for (const embed of [
+    "javascript:alert(1)",
+    "data:text/html,<script>alert(1)</script>",
+    "vbscript:msgbox(1)",
+    "  javascript:alert(1)  ",
+    "java\tscript:alert(1)",
+    "JAVASCRIPT:alert(1)",
+  ]) {
+    const section = asFake(renderAppView({ type: "appView", props: { embed } }));
+    const frame = section.children.find(
+      (c): c is FakeElement => c instanceof FakeElement && c.tagName === "IFRAME",
+    );
+    assert.ok(frame, `an <iframe> is still mounted for ${JSON.stringify(embed)}`);
+    assert.equal(
+      frame.getAttribute("src"),
+      null,
+      `dangerous embed ${JSON.stringify(embed)} must not become an iframe src`,
+    );
+  }
+});
+
+test("#416: renderAppView keeps a legit http(s) embed and trims surrounding whitespace", (t) => {
+  t.after(installFakeDom());
+  const section = asFake(
+    renderAppView({ type: "appView", props: { embed: "  https://example.test/embed.html  " } }),
+  );
+  const frame = section.children.find(
+    (c): c is FakeElement => c instanceof FakeElement && c.tagName === "IFRAME",
+  );
+  assert.ok(frame);
+  assert.equal(frame.getAttribute("src"), "https://example.test/embed.html");
+});
+
 test('#327: fmtCellValue "datetime" renders an ISO timestamp in the viewer\'s local time as "h:mmam Mon D"', () => {
   const iso = "2026-08-18T23:42:47.788Z";
   const out = fmtCellValue("datetime", iso);

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

@@ -1690,3 +1690,136 @@ test("the syntax guard is red/green: an injected syntax error fails `node --chec
   assert.equal(result.ok, false, "an injected syntax error must fail `node --check`");
   assert.match(result.stderr, /SyntaxError/);
 });
+
+// ── appView sidecar + dist static-file serving (#420) ──────────────────────
+// The renderer (#419) mounts the cockpit iframe at `./embed.html`; in a DEPLOYED app
+// urban must serve that sidecar (and the `dist/` bundle its import-map references) or
+// the iframe src 404s and the cockpit stays blank (#416's user-facing symptom). These
+// tests pin the static-serving surface #420 adds.
+
+/** Build the pages routes over an in-memory asset filesystem (app-root-relative path → body). */
+function buildWithAssets(files: Record<string, string>) {
+  const { engine } = fakeEngine();
+  const routes = createPagesRoutes(
+    { pagesDir: "pages", homePage: "home", sourceName: "app" },
+    {
+      db: fakeDb(),
+      engine,
+      readPage: async () => JSON.stringify({ title: "Home", nodes: [] }),
+      readAsset: async (path: string) => {
+        if (path in files) return files[path];
+        throw new Error(`no such file: ${path}`);
+      },
+      listPages: async () => ["home"],
+    },
+  );
+  return makeRouter(routes);
+}
+
+test("GET /embed.html serves the pages-dir sidecar as HTML", async () => {
+  const router = buildWithAssets({ "pages/embed.html": "<!doctype html><title>embed</title>" });
+  const res = await router(req("GET", "/embed.html"));
+  assert.equal(res.status, 200);
+  assert.match(res.headers?.["content-type"] ?? "", /text\/html/);
+  assert.match(res.body ?? "", /<title>embed<\/title>/);
+});
+
+test("all four appView sidecars are served from the pages dir with correct content types", async () => {
+  const router = buildWithAssets({
+    "pages/embed.html": "<html>embed</html>",
+    "pages/standalone.html": "<html>standalone</html>",
+    "pages/mount.js": "export const mountCockpit = () => {};",
+    "pages/cockpit.css": "body{margin:0}",
+  });
+  const cases: [string, RegExp][] = [
+    ["/embed.html", /text\/html/],
+    ["/standalone.html", /text\/html/],
+    ["/mount.js", /text\/javascript/],
+    ["/cockpit.css", /text\/css/],
+  ];
+  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("a missing sidecar 404s instead of throwing", async () => {
+  const router = buildWithAssets({}); // no files
+  const res = await router(req("GET", "/embed.html"));
+  assert.equal(res.status, 404);
+});
+
+test("GET /dist/<path> serves the import-map bundle the embed references", async () => {
+  const router = buildWithAssets({ "dist/cockpit/index.js": "export function bootCockpit(){}" });
+  const res = await router(req("GET", "/dist/cockpit/index.js"));
+  assert.equal(res.status, 200);
+  assert.match(res.headers?.["content-type"] ?? "", /text\/javascript/);
+  assert.match(res.body ?? "", /bootCockpit/);
+});
+
+test("a source map under /dist/ is served as JSON", async () => {
+  const router = buildWithAssets({ "dist/cockpit/index.js.map": "{\"version\":3}" });
+  const res = await router(req("GET", "/dist/cockpit/index.js.map"));
+  assert.equal(res.status, 200);
+  assert.match(res.headers?.["content-type"] ?? "", /application\/json/);
+});
+
+test("a /dist/ path traversal attempt is rejected (never reaches the filesystem)", async () => {
+  // The reader would happily read `dist/../secret` if the route let it through; the
+  // sub-path guard must reject any `..` / absolute / percent-escaped segment first.
+  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 ["/dist/../secret.json", "/dist/a/../../secret", "/dist/%2e%2e/secret", "/dist//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 static asset routes do not shadow the app's own routes or /healthz", async () => {
+  // The sidecars are served as EXACT routes (not a root catch-all), so `/`, `/app/*` and
+  // the runtime's appended `/healthz` liveness route all still resolve. A catch-all would
+  // silently swallow `/healthz` (breaking liveness probes) — this pins that it does not.
+  const routes = createPagesRoutes(
+    { pagesDir: "pages", homePage: "home", sourceName: "app" },
+    {
+      db: fakeDb(),
+      engine: fakeEngine().engine,
+      readPage: async () => JSON.stringify({ title: "Home", nodes: [] }),
+      readAsset: async () => "<html></html>",
+      listPages: async () => ["home"],
+    },
+  );
+  // No pages route matches /healthz, so the runtime's own healthz route (appended after
+  // the pages surface) would still win. Assert none of the pages routes claim it.
+  const router = makeRouter([
+    ...routes,
+    {
+      method: "GET",
+      path: "/healthz",
+      handler: () => ({ status: 200, headers: { "content-type": "application/json" }, body: JSON.stringify({ ok: true }) }),
+    },
+  ]);
+  const health = await router(req("GET", "/healthz"));
+  assert.equal(health.status, 200);
+  assert.deepEqual(JSON.parse(health.body ?? "{}"), { ok: true });
+  // The home shell still renders (not shadowed by a static route).
+  const home = await router(req("GET", "/"));
+  assert.match(home.body ?? "", /data-home="home"/);
+});

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

@@ -11,6 +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  /dist/<path>                               → the app dist/ bundle the sidecars reference
 //   POST /app/actions/start/<process>               → engine.createInstance
 //   POST /app/actions/cancel                        → engine.cancelInstance
 //   POST /app/actions/message                       → engine.publishMessage
@@ -59,6 +61,16 @@ export interface PagesDeps {
   engine: EngineClient;
   /** Read a page file; injectable for tests. */
   readPage(path: string): Promise<string>;
+  /**
+   * Read a static asset file at an app-root-relative path (the `appView` sidecar
+   * documents under `pagesDir` — `embed.html`/`standalone.html`/`mount.js`/`cockpit.css`
+   * — and the app `dist/` bundle their import-maps reference). A thin adapter over the
+   * host's `readTextFile` seam, distinct from `readPage` (which is page.json-scoped) so
+   * the intent reads clearly at the call site. Optional; falls back to `readPage` when
+   * absent (both delegate to the same host seam), so existing tests need no change.
+   * Injectable for tests. Rejects (→ 404) when the file is missing.
+   */
+  readAsset?(path: string): Promise<string>;
   /**
    * List the available page ids (the `*.page.json` basenames under `pagesDir`),
    * powering the `/app/pages` index endpoint and a `nav` node's `items: "auto"`.
@@ -88,6 +100,83 @@ function javascript(
   };
 }
 
+// The `appView` sidecar documents an app ships alongside its `*.page.json` under
+// `pagesDir` (ADR 0057 / #416 / #420). The renderer (#419) mounts an <iframe> whose
+// src is the node's base-relative `embed` (`./embed.html`), which — resolved against
+// the shell served at the app mount root — the browser fetches at `/embed.html`; that
+// 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
+// import-map references is served separately under the `/dist/` prefix below.
+const SIDECAR_ASSETS = ["embed.html", "standalone.html", "mount.js", "cockpit.css"] as const;
+
+// The app `dist/` directory (app-root sibling of the pages dir) the sidecar import-maps
+// resolve `../dist/…` onto. Because the embed is served at the mount root, `../dist`
+// resolves to `/dist` regardless of `pagesDir`, so the URL→disk mapping is fixed.
+const DIST_DIR = "dist";
+
+/** Content type for a served static web asset, by extension. The sidecars + the ESM/CSS/JSON
+ *  the import-maps reference are all UTF-8 text (the only channel `readTextFile` offers); an
+ *  unknown extension falls back to `application/octet-stream` rather than mislabelling. This is
+ *  a distinct concern from deploy's `contentTypeFor` (engine resource types: bpmn/dmn/form/…),
+ *  so the two maps do not share a source. */
+function assetContentType(path: string): string {
+  const dot = path.lastIndexOf(".");
+  const ext = dot >= 0 ? path.slice(dot + 1).toLowerCase() : "";
+  switch (ext) {
+    case "html":
+      return "text/html; charset=utf-8";
+    case "js":
+    case "mjs":
+      return "text/javascript; charset=utf-8";
+    case "css":
+      return "text/css; charset=utf-8";
+    case "json":
+    case "map": // source maps are JSON
+      return "application/json; charset=utf-8";
+    case "svg":
+      return "image/svg+xml; charset=utf-8";
+    case "txt":
+      return "text/plain; charset=utf-8";
+    default:
+      return "application/octet-stream";
+  }
+}
+
+// A URL sub-path (the `<rest>` of `/dist/<rest>`) is safe to map onto the filesystem
+// only when it is a plain, forward, relative descent: no `..`/`.` segment (path
+// traversal out of `dist/`), no empty segment (a leading/doubled slash), no absolute
+// path, and no percent-escape or backslash (the request `path` is `URL.pathname`, which
+// is NOT percent-decoded — so a `%2e%2e`/`%2f` smuggled traversal never reaches the FS;
+// we reject any `%` outright rather than decode-then-recheck). Returns the normalised
+// relative path, or null to 404. Mirrors the `[A-Za-z0-9_-]` guards the page/data routes
+// already apply, widened to the `/` `.` a nested asset path needs.
+function safeAssetSubpath(rest: string): string | null {
+  if (rest === "" || rest.includes("%") || rest.includes("\\") || rest.includes("\0")) return null;
+  if (rest.startsWith("/")) return null;
+  const segs = rest.split("/");
+  for (const s of segs) {
+    if (s === "" || s === "." || s === "..") return null;
+    if (!/^[A-Za-z0-9._-]+$/.test(s)) return null;
+  }
+  return segs.join("/");
+}
+
+/** Serve a static asset file at an app-root-relative path: 200 with its content type, or 404 when
+ *  the file is missing/unreadable. Used by both the root sidecar routes and the `/dist/` tree. */
+async function serveAsset(
+  read: (path: string) => Promise<string>,
+  filePath: string,
+): Promise<{ status: number; headers: Record<string, string>; body: string }> {
+  try {
+    const body = await read(filePath);
+    return { status: 200, headers: { "content-type": assetContentType(filePath) }, body };
+  } catch {
+    return { status: 404, headers: { "content-type": "text/plain; charset=utf-8" }, body: "not found" };
+  }
+}
+
 /** A SQL identifier guard — a table name must be a bare identifier *and* a known table
  * (checked against `schema()`), so `/app/data/:table` can never inject SQL. */
 const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -112,6 +201,10 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
   const rowLimit = Number.isFinite(rowLimitRaw) ? Math.max(0, Math.floor(rowLimitRaw)) : 200;
   const sourceName = opts.sourceName ?? "app";
   const { db, engine, readPage, listPages, cancel } = deps;
+  // Static assets (the `appView` sidecars + the `dist/` bundle) read through the host seam.
+  // Falls back to `readPage` when no dedicated reader is injected — both delegate to the same
+  // `host.readTextFile`, so there is one source of file bytes, not two.
+  const readAsset = deps.readAsset ?? readPage;
 
   // The table-name whitelist is memoised: an Urban app runs its migrations at boot
   // (before serving), so the schema is stable for the process lifetime, and the renderer
@@ -175,7 +268,41 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
     handler: () => javascript(RENDERER_JS, 200, { "cache-control": "no-cache" }),
   });
 
-  // ── GET /app/pages (index of available pages) ───────────────────────────
+  // ── appView sidecar assets (#420) ───────────────────────────────────────
+  // The `appView` renderer (#419) mounts an <iframe> at the node's base-relative `embed`
+  // (`./embed.html`), which — against the shell served at the mount root — the browser
+  // fetches at `/embed.html`; that document then pulls `./cockpit.css`, `./mount.js`, and
+  // its import-map's `../dist/…`. A DEPLOYED app served none of these, so the iframe src
+  // 404'd and the agent cockpit loaded nothing (#416 was necessary but not sufficient
+  // without this static-serving surface). Serve each sidecar at its root URL, mapped 1:1
+  // onto `pagesDir/<name>` (exact routes — never a root catch-all, which would shadow the
+  // `/healthz` liveness route the runtime appends after the pages surface).
+  for (const name of SIDECAR_ASSETS) {
+    routes.push({
+      method: "GET",
+      path: `/${name}`,
+      source: "surface:pages",
+      handler: () => serveAsset(readAsset, `${pagesDir}/${name}`),
+    });
+  }
+  // The `dist/` tree the sidecars' import-maps reference (`../dist/cockpit/index.js` →
+  // `/dist/cockpit/index.js`). A prefix route over an app-root `dist/` directory; the
+  // sub-path is strictly validated (no traversal/escape) before it reaches the FS.
+  routes.push({
+    method: "GET",
+    path: `/${DIST_DIR}/`,
+    prefix: true,
+    source: "surface:pages",
+    handler: (req) => {
+      const rest = req.path.slice(`/${DIST_DIR}/`.length);
+      const safe = safeAssetSubpath(rest);
+      if (safe === null) {
+        return { status: 404, headers: { "content-type": "text/plain; charset=utf-8" }, body: "not found" };
+      }
+      return serveAsset(readAsset, `${DIST_DIR}/${safe}`);
+    },
+  });
+
   // Powers multi-page navigation: a `nav` node with `items: "auto"` lists every
   // page here, and it lets any client enumerate the app's screens. Each entry
   // carries the page's own `title` (best-effort — an unreadable/!JSON page still
@@ -449,6 +576,7 @@ export function mountPages(ctx: RuntimeContext, app: AppApi): PagesHandle {
     engine: app.engine,
     cancel: (key) => cancelInstanceReconciling(app, bindings, key),
     readPage: (p) => ctx.host.readTextFile(p),
+    readAsset: (p) => ctx.host.readTextFile(p),
     listPages: async () => {
       const dir = opts.pagesDir ?? "pages";
       const names = await ctx.host.listDir(dir).catch(() => []);
@@ -686,6 +814,16 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-md-code { background:var(--nano-inset); border-radius:.3rem; padding:.05rem .3rem; font:.85em ui-monospace,SFMono-Regular,Menlo,monospace; }
 .pc-md-hr { border:0; border-top:1px solid var(--nano-edge); margin:1rem 0; }
 .pc-prose-body a { color:var(--nano-accent-strong); }
+/* Embedded App View (renderAppView, #416 / ADR 0057). An <iframe> hosting a
+   self-contained view document (e.g. the agent cockpit's embed.html) served
+   alongside the page. A plain node sizes to a comfortable default; a "fill" node
+   grows to a tall flex column so the embed (a live dashboard/terminal) gets the
+   viewport height it needs instead of a squat fixed box. */
+.pc-appview { margin:1rem 0; }
+.pc-appview-title { font-size:.8rem; font-weight:600; color:var(--nano-text-muted); text-transform:uppercase; letter-spacing:.03em; margin:0 0 .35rem; }
+.pc-appview-frame { display:block; width:100%; min-height:24rem; border:1px solid var(--nano-edge); border-radius:.6rem; background:var(--nano-inset); }
+.pc-appview-fill { display:flex; flex-direction:column; min-height:min(80vh,48rem); }
+.pc-appview-fill .pc-appview-frame { flex:1 1 auto; min-height:0; }
 /* A standalone button node + the modal it opens (e.g. a copy-pasteable prompt). */
 .pc-buttonrow { margin:1rem 0; }
 .pc-btn-ghost { background:transparent; color:var(--nano-text-muted); border:1px solid var(--nano-edge); }