@nanobpm/urban 0.72.2 → 0.73.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.73.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.ts

@@ -686,6 +686,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); }